fulgur 0.5.0-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a59f68ed163b7a1d7dddfdc0481bcbcf7844affea4fa3f32c191e5cbf3e3cb9b
+  data.tar.gz: 3abf8a424ad6a25473bdfe87c2ae5d77147bef8c8bc549d3b5d6368b692b6e75
+SHA512:
+  metadata.gz: 40b12fb4eb1c2d2a74b1e9f03f4a7c5c0e972ecc50d1b150f2135ba7d2b365d9e5e9ed61373d23c870fc2f3c518c00d1a724f8d27c272a2447dd7ddaeddbda12
+  data.tar.gz: c2fccbabda140f27c3b8c8d94d87f260b40dcce8b47355212af35c3402460db091b37642321ac62cc0bd15127cbe194718b4285edc15a5e0f62e0259e6c5de89

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/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitsuru Takigahira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,234 @@
+# fulgur
+
+Ruby bindings for [fulgur](https://github.com/mitsuru/fulgur) — an offline,
+deterministic HTML/CSS to PDF conversion library written in Rust.
+
+## Status
+
+**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.
+
+> **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.
+
+## 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; }")
+
+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
+
+```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)
+- [fulgur on crates.io](https://crates.io/crates/fulgur)
+
+## License
+
+Licensed under either of Apache License, Version 2.0 or MIT license at
+your option.

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "fulgur/version"
+
+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"

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: fulgur
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: aarch64-linux
+authors:
+- Mitsuru Hayasaka
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-18 00:00:00.000000000 Z
+dependencies: []
+description: Ruby bindings for fulgur, a deterministic HTML/CSS to PDF rendering engine.
+email:
+- hayasaka.mitsuru@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE-MIT
+- README.md
+- lib/fulgur.rb
+- lib/fulgur/3.1/fulgur.so
+- lib/fulgur/3.2/fulgur.so
+- lib/fulgur/3.3/fulgur.so
+- lib/fulgur/3.4/fulgur.so
+- lib/fulgur/asset_bundle.rb
+- lib/fulgur/margin.rb
+- lib/fulgur/version.rb
+homepage: https://github.com/mitsuru/fulgur
+licenses:
+- Apache-2.0
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/mitsuru/fulgur
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.5.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Offline HTML/CSS → PDF conversion
+test_files: []