fulgur 0.0.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2790fa4c3713ccd81cc9b8892acecf0e805faeea46b331495919e1c703d0a00f
-  data.tar.gz: 644d46841ef4a505247c8801b1ee3e164a5bcc17f4adfda997c3e809fb78d638
+  metadata.gz: e921af1392812aec76a28ea1bbf77598131c39c3fd344159375dd3d9642a2185
+  data.tar.gz: 75810a1529a8d327b17950cf60372bf0d0a54f5c1dbf1406297d560e41ad018c
 SHA512:
-  metadata.gz: 94ad56b86a3d79499cf60fa6550f37b14f53476422b24a7bf4c5f7854c81fd9015e7defc1f9ba9fee5a993ecdbec0abfbe2a7d78ce9a455e2ef03fd5532836f5
-  data.tar.gz: ac3682a7518b0d9798526a1b9314bf1034dd316ad8f69c2f7935aff5e5617694333abaa3cfc5184a6c40a558ad535bd3b301b01ecbbf1045d530db52386df206
+  metadata.gz: 857299514d3931f5404e1701ae5524984ebbcc4b51e3afc164c558828d6254b6f1e3c59ab34fcf68530d0a63fc47042e85d1408a1f31a178bafd4d2a8c13ecf6
+  data.tar.gz: 6d946aad252616dc511afbd17ad895540c5923418be7435ac1648f3aba1a559920a78704a837345f515af97f62bfc254bb4da42b09f52667ba370efa728d2afa

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to the `fulgur` gem will be documented here.
+
+## [Unreleased]
+
+## [0.0.1] - 2026-04-17
+
+Initial Ruby binding for fulgur.
+
+### Added
+
+- `Fulgur::Engine` (kwargs constructor + builder chain)
+- `Fulgur::EngineBuilder` for reusable engine construction
+- `Fulgur::AssetBundle` with long (`add_*`) and short (`css`, `font_file`, etc.) aliases
+- `Fulgur::PageSize` with `A4` / `LETTER` / `A3` constants and `.custom(w_mm, h_mm)`; accepts `Symbol`, `String`, or class constants as input
+- `Fulgur::Margin` with CSS-style positional args, keyword args, and `.uniform` / `.symmetric` factories
+- `Fulgur::Pdf` result object: `#to_s` (ASCII-8BIT), `#to_base64`, `#to_data_uri`, `#write_to_path`, `#write_to_io` (64 KiB chunked, binmode-guaranteed), `#bytesize`
+- `Engine#render_html` and `Engine#render_html_to_file` release the GVL during the Rust render call
+- Error hierarchy: `Fulgur::Error` / `Fulgur::RenderError` / `Fulgur::AssetError`, plus standard `ArgumentError` / `Errno::ENOENT`
+- Ruby 3.3+ support
+
+### Known Limitations
+
+- Precompiled gems / RubyGems publish automation are tracked separately (fulgur-qyf) and not yet in place; gems must be built from source for now
+- Streaming renderer: Krilla emits bytes at the end of rendering, so `#write_to_io` chunks a completed buffer rather than streaming during layout
+- No Ractor safety analysis yet

data/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "fulgur-ruby"
+version = "0.5.0"
+# rb_sys cross-gem-action は `directory: crates/fulgur-ruby` のみをコンテナに
+# マウントするため、この Cargo.toml は workspace root 不在でも cargo metadata
+# を解決できる必要がある。したがって workspace 継承 (`.workspace = true`) は
+# 使わず、値は root Cargo.toml [workspace.package] と同期させて inline する。
+edition = "2024"
+rust-version = "1.85.0"
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/mitsuru/fulgur"
+homepage = "https://github.com/mitsuru/fulgur"
+description = "Ruby bindings for fulgur — offline HTML/CSS to PDF conversion"
+publish = false
+
+[lib]
+name = "fulgur"
+crate-type = ["cdylib", "rlib"]
+
+[features]
+ruby-api = ["dep:magnus", "dep:rb-sys"]
+
+[dependencies]
+fulgur = { path = "../fulgur" }
+base64 = "0.22"
+magnus = { version = "0.7", optional = true }
+rb-sys = { version = "0.9", optional = true }
+# Send/Sync 保証 (Engine) のコンパイル時 assertion で使用。
+# ext/fulgur/Cargo.toml にも同じ依存を追加していること。
+static_assertions = "1.1"

data/README.md

@@ -1,28 +1,228 @@
 # fulgur
 
-Ruby bindings for [fulgur](https://github.com/mitsuru/fulgur) — an offline, deterministic HTML/CSS to PDF conversion library written in Rust.
+Ruby bindings for [fulgur](https://github.com/mitsuru/fulgur) — an offline,
+deterministic HTML/CSS to PDF conversion library written in Rust.
 
 ## Status
 
-**This gem is a name reservation.** The implementation is under active development.
+**MVP (gem v0.0.1, unreleased).** The core `Engine` / `EngineBuilder` /
+`AssetBundle` / `PageSize` / `Margin` / `Pdf` API is available. Precompiled
+gems, batch rendering, sandboxing, and template-engine wiring are planned
+for later releases.
 
-## Planned API
+> **Versioning note:** the `fulgur` gem is versioned independently from the
+> underlying `fulgur` Rust crate and the `pyfulgur` PyPI package. This gem
+> starts at `0.0.1` as an MVP and will bump on its own cadence. "v0.5.0"
+> elsewhere in project documents refers to the parent epic that bundles
+> the Rust / Python / Ruby shipping milestones, not this gem's version.
 
-> **Not available in v0.0.1.** The current release is a placeholder for name reservation.
+## Install
+
+> **Note:** v0.0.1 is an early MVP. Pre-built gems are not yet published to
+> RubyGems; build from source for now.
+
+Requires a Rust toolchain (1.85+) and Ruby 3.3+.
+
+```bash
+# From a checkout of the fulgur repository
+cd crates/fulgur-ruby
+bundle install
+bundle exec rake compile
+```
+
+Once pre-built gems ship, installation will be:
+
+```bash
+gem install fulgur
+```
+
+For Bundler:
+
+```ruby
+gem "fulgur"
+```
+
+## Quick start
 
 ```ruby
 require "fulgur"
 
 bundle = Fulgur::AssetBundle.new
 bundle.add_css("body { font-family: sans-serif; }")
-bundle.add_font_file("fonts/NotoSans-Regular.ttf")
 
-engine = Fulgur::Engine.builder.page_size("A4").assets(bundle).build
-pdf_bytes = engine.render_html("<h1>Hello, world!</h1>")
+engine = Fulgur::Engine.new(page_size: :a4, assets: bundle)
+pdf = engine.render_html("<h1>Hello, world!</h1>")
+
+pdf.write_to_path("output.pdf")
+```
+
+Builder style:
+
+```ruby
+engine = Fulgur::Engine.builder
+  .page_size(Fulgur::PageSize::A4)
+  .landscape(false)
+  .title("My doc")
+  .assets(bundle)
+  .build
+
+engine.render_html_to_file("<h1>Hi</h1>", "out.pdf")
+```
+
+## API surface
+
+### `Fulgur::Engine`
+
+Keyword-argument constructor:
+
+```ruby
+engine = Fulgur::Engine.new(
+  page_size: :a4,                # Symbol, String, or Fulgur::PageSize
+  margin: Fulgur::Margin.uniform(72),
+  landscape: false,
+  title: "My Document",
+  author: "Me",
+  lang: "en",
+  bookmarks: true,
+  assets: bundle,                # Fulgur::AssetBundle
+)
+```
+
+Or use the builder:
+
+```ruby
+engine = Fulgur::Engine.builder
+  .page_size(:letter)
+  .margin(Fulgur::Margin.new(72, 36, 48, 24))
+  .assets(bundle)
+  .build
+```
+
+### Rendering
 
-File.binwrite("output.pdf", pdf_bytes)
+```ruby
+pdf = engine.render_html(html_string)        # => Fulgur::Pdf
+engine.render_html_to_file(html, "out.pdf")  # shortcut
+```
+
+`render_html` and `render_html_to_file` release the GVL, allowing other
+Ruby threads to run concurrently during rendering.
+
+### `Fulgur::Pdf` (render result)
+
+```ruby
+pdf.bytesize                   # => Integer
+pdf.to_s                       # => String (ASCII-8BIT binary)
+pdf.to_base64                  # => String (Base64)
+pdf.to_data_uri                # => "data:application/pdf;base64,..."
+pdf.write_to_path("out.pdf")   # write raw bytes to file path
+pdf.write_to_io(io)            # chunked write to any IO (calls binmode when supported)
 ```
 
+The result object keeps bytes on the Rust side. Methods like `to_base64`
+encode directly from the Rust buffer, avoiding an intermediate Ruby binary
+String. For server-side batch workloads rendering many PDFs, this halves
+peak memory compared with `Base64.strict_encode64(bytes)` on the Ruby
+side.
+
+### `Fulgur::AssetBundle`
+
+Offline-first: all assets must be explicitly registered.
+
+```ruby
+bundle = Fulgur::AssetBundle.new
+bundle.add_css("body { font-family: 'Noto Sans' }")
+bundle.add_css_file("style.css")
+bundle.add_font_file("NotoSans-Regular.ttf")
+bundle.add_image("logo", File.binread("logo.png"))
+bundle.add_image_file("icon", "icon.png")
+```
+
+Short aliases are also available:
+
+```ruby
+bundle.css "..."
+bundle.css_file "style.css"
+bundle.font_file "NotoSans.ttf"
+bundle.image "logo", bytes
+bundle.image_file "icon", "icon.png"
+```
+
+### `Fulgur::PageSize`
+
+```ruby
+Fulgur::PageSize::A4
+Fulgur::PageSize::LETTER
+Fulgur::PageSize::A3
+Fulgur::PageSize.custom(100, 200)  # width/height in mm
+```
+
+Engine kwargs and builder also accept `:a4`, `"A4"`, etc. as shorthand.
+
+### `Fulgur::Margin`
+
+```ruby
+Fulgur::Margin.new(72)                         # uniform
+Fulgur::Margin.new(72, 36)                     # [vertical, horizontal]
+Fulgur::Margin.new(72, 36, 48, 24)             # [top, right, bottom, left]
+Fulgur::Margin.new(top: 72, right: 36, bottom: 48, left: 24)
+Fulgur::Margin.uniform(72)
+Fulgur::Margin.symmetric(72, 36)
+```
+
+All values are in points (pt).
+
+## LLM integration
+
+`Fulgur::Pdf#to_base64` and `#to_data_uri` are optimized for passing PDFs
+to LLMs as base64-encoded payloads (e.g., Anthropic Claude, OpenAI GPT-4):
+
+```ruby
+pdf = engine.render_html(html)
+
+anthropic.messages.create(
+  model: "claude-opus-4-7",
+  messages: [{
+    role: "user",
+    content: [
+      {
+        type: "document",
+        source: {
+          type: "base64",
+          media_type: "application/pdf",
+          data: pdf.to_base64,
+        },
+      },
+      { type: "text", text: "Summarize this document." },
+    ],
+  }],
+)
+```
+
+## Errors
+
+```text
+Fulgur::Error        # base class (StandardError)
+Fulgur::RenderError  # rendering failure (HTML parse, layout, PDF generation, WOFF decode)
+Fulgur::AssetError   # asset registration failure (unsupported font format, invalid asset)
+
+ArgumentError        # invalid arguments (unknown page_size, malformed margin)
+Errno::ENOENT        # missing font/image/CSS file
+```
+
+## Development
+
+```bash
+cd crates/fulgur-ruby
+bundle install
+bundle exec rake compile   # builds the Rust extension
+bundle exec rspec          # runs tests
+bundle exec rake           # compile + test
+```
+
+The native extension lives under `ext/fulgur/`, the Ruby-side wrappers
+under `lib/`, and Rust sources under `src/`.
+
 ## Links
 
 - [fulgur on GitHub](https://github.com/mitsuru/fulgur)
@@ -30,4 +230,5 @@ File.binwrite("output.pdf", pdf_bytes)
 
 ## License
 
-Licensed under either of Apache License, Version 2.0 or MIT license at your option.
+Licensed under either of Apache License, Version 2.0 or MIT license at
+your option.

data/ext/fulgur/Cargo.toml

@@ -0,0 +1,30 @@
+[workspace]
+
+[package]
+name = "fulgur"
+version = "0.5.0"
+# crates/fulgur-ruby/Cargo.toml と同じ src を共有 (path = "../../src/lib.rs")。
+# workspace と同じ edition 2024 に揃える。
+edition = "2024"
+
+[lib]
+name = "fulgur"
+crate-type = ["cdylib"]
+path = "../../src/lib.rs"
+
+[features]
+default = ["ruby-api"]
+ruby-api = ["dep:magnus", "dep:rb-sys"]
+
+[dependencies]
+# cross-gem-action は `directory: crates/fulgur-ruby` しか container にマウントしない
+# ため、`path = "../../../fulgur"` では cargo がパスを解決できない。crates.io 公開版
+# を参照する (release 時は release.yml → release: published → release-ruby.yml の順で
+# 発火するため、この時点で fulgur のバージョンは crates.io に存在する)。
+# release-prepare.yml が sed でこの行のバージョンを同期する。
+fulgur = "0.5.0"
+base64 = "0.22"
+magnus = { version = "0.7", optional = true }
+rb-sys = { version = "0.9", optional = true }
+# 親 crate の src/lib.rs `mod assertions` が使用。
+static_assertions = "1.1"

data/ext/fulgur/extconf.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("fulgur/fulgur") do |r|
+  r.features = ["ruby-api"]
+end

data/lib/fulgur/asset_bundle.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Fulgur
+  class AssetBundle
+    alias_method :css, :add_css
+    alias_method :css_file, :add_css_file
+    alias_method :font_file, :add_font_file
+    alias_method :image, :add_image
+    alias_method :image_file, :add_image_file
+  end
+end

data/lib/fulgur/margin.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Fulgur
+  class Margin
+    class << self
+      alias_method :__native_new__, :new
+
+      def new(*args, **kwargs)
+        unless kwargs.empty?
+          raise ArgumentError, "positional and kwargs are mutually exclusive" unless args.empty?
+
+          required = %i[top right bottom left]
+          missing = required - kwargs.keys
+          raise ArgumentError, "missing keys: #{missing.join(", ")}" unless missing.empty?
+
+          t, r, b, l = kwargs.values_at(*required).map(&:to_f)
+          return __build__(t, r, b, l)
+        end
+
+        case args.length
+        when 1
+          v = args[0].to_f
+          __build__(v, v, v, v)
+        when 2
+          vv, hh = args.map(&:to_f)
+          __build__(vv, hh, vv, hh)
+        when 4
+          t, r, b, l = args.map(&:to_f)
+          __build__(t, r, b, l)
+        else
+          raise ArgumentError, "wrong number of arguments (#{args.length} for 1, 2, 4, or kwargs)"
+        end
+      end
+    end
+  end
+end

data/lib/fulgur/version.rb

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

data/lib/fulgur.rb

@@ -1,15 +1,19 @@
 # frozen_string_literal: true
 
-# Fulgur — Ruby bindings for fulgur (HTML/CSS to PDF).
-#
-# This is a placeholder gem. The implementation is under active development.
-# See https://github.com/mitsuru/fulgur for details.
-module Fulgur
-  VERSION = "0.0.1"
+require_relative "fulgur/version"
 
-  def self.placeholder
-    raise NotImplementedError,
-      "fulgur gem is not yet implemented. " \
-      "See https://github.com/mitsuru/fulgur for progress."
-  end
+begin
+  minor = RUBY_VERSION[/\A\d+\.\d+/]
+  require_relative "fulgur/#{minor}/fulgur"
+rescue LoadError
+  require_relative "fulgur/fulgur"
 end
+
+module Fulgur
+  class Error < StandardError; end
+  class RenderError < Error; end
+  class AssetError < Error; end
+end
+
+require_relative "fulgur/margin"
+require_relative "fulgur/asset_bundle"

data/src/asset_bundle.rs

@@ -0,0 +1,78 @@
+//! `Fulgur::AssetBundle` Ruby class wrapping `fulgur::AssetBundle`.
+//!
+//! Ruby は GVL 下で single-threaded なので `RefCell` による内部可変で十分。
+//! Engine builder に渡すときは `take_inner()` で中身を奪い、空の
+//! `AssetBundle::new()` に差し替える。
+
+use crate::error::map_fulgur_error;
+// `fulgur::AssetBundle` root re-export は 0.4.5 には存在しないため full path で参照。
+use fulgur::asset::AssetBundle;
+use magnus::{Error, Module, RModule, RString, Ruby, function, method, prelude::*};
+use std::cell::RefCell;
+use std::path::PathBuf;
+
+#[magnus::wrap(class = "Fulgur::AssetBundle", free_immediately, size)]
+pub struct RbAssetBundle {
+    pub(crate) inner: RefCell<AssetBundle>,
+}
+
+impl RbAssetBundle {
+    pub(crate) fn new() -> Self {
+        Self {
+            inner: RefCell::new(AssetBundle::new()),
+        }
+    }
+
+    /// Engine builder に渡すために中身を取り出す。
+    /// 奪った後は empty AssetBundle に差し替える。
+    #[allow(dead_code)] // Task 6 で engine builder から呼ばれる
+    pub(crate) fn take_inner(&self) -> AssetBundle {
+        std::mem::replace(&mut *self.inner.borrow_mut(), AssetBundle::new())
+    }
+
+    fn add_css(&self, css: String) {
+        self.inner.borrow_mut().add_css(css);
+    }
+
+    fn add_css_file(&self, path: String) -> Result<(), Error> {
+        let ruby = Ruby::get().expect("ruby vm");
+        self.inner
+            .borrow_mut()
+            .add_css_file(PathBuf::from(path))
+            .map_err(|e| map_fulgur_error(&ruby, e))
+    }
+
+    fn add_font_file(&self, path: String) -> Result<(), Error> {
+        let ruby = Ruby::get().expect("ruby vm");
+        self.inner
+            .borrow_mut()
+            .add_font_file(PathBuf::from(path))
+            .map_err(|e| map_fulgur_error(&ruby, e))
+    }
+
+    fn add_image(&self, name: String, data: RString) {
+        // SAFETY: `as_slice` returns a reference tied to the Ruby VM lifetime;
+        // we immediately copy into an owned `Vec<u8>` so the borrow ends here.
+        let bytes = unsafe { data.as_slice() }.to_vec();
+        self.inner.borrow_mut().add_image(name, bytes);
+    }
+
+    fn add_image_file(&self, name: String, path: String) -> Result<(), Error> {
+        let ruby = Ruby::get().expect("ruby vm");
+        self.inner
+            .borrow_mut()
+            .add_image_file(name, PathBuf::from(path))
+            .map_err(|e| map_fulgur_error(&ruby, e))
+    }
+}
+
+pub fn define(_ruby: &Ruby, fulgur: &RModule) -> Result<(), Error> {
+    let class = fulgur.define_class("AssetBundle", magnus::class::object())?;
+    class.define_singleton_method("new", function!(RbAssetBundle::new, 0))?;
+    class.define_method("add_css", method!(RbAssetBundle::add_css, 1))?;
+    class.define_method("add_css_file", method!(RbAssetBundle::add_css_file, 1))?;
+    class.define_method("add_font_file", method!(RbAssetBundle::add_font_file, 1))?;
+    class.define_method("add_image", method!(RbAssetBundle::add_image, 2))?;
+    class.define_method("add_image_file", method!(RbAssetBundle::add_image_file, 2))?;
+    Ok(())
+}