fulgur 0.0.1 → 0.5.0

data/src/engine.rs

@@ -0,0 +1,297 @@
+//! `Fulgur::Engine` と `Fulgur::EngineBuilder` の Ruby バインディング。
+//!
+//! - `Engine.new(**kwargs)`: kwargs-only constructor。
+//! - `Engine.builder`: `EngineBuilder` を返す。
+//! - `EngineBuilder#page_size`, `#margin`, `#assets`, `#landscape`, `#title`,
+//!   `#author`, `#lang`, `#bookmarks`: setter は `self` を返してチェーンを成立させる。
+//! - `EngineBuilder#build`: `Engine` を返す。2 回目の呼び出しは RuntimeError。
+//!
+//! `Engine#render_html` は `Fulgur::Pdf` を返し、`#render_html_to_file` は
+//! PDF をそのままファイルに書き出す。どちらもレンダリング中は GVL を解放する。
+
+use crate::asset_bundle::RbAssetBundle;
+use crate::error::map_fulgur_error;
+use crate::margin::RbMargin;
+use crate::page_size::extract as extract_page_size;
+use crate::pdf::RbPdf;
+use fulgur::{Engine, EngineBuilder};
+use magnus::{
+    Error, Module, RModule, Ruby, Value, function, method,
+    prelude::*,
+    scan_args::{get_kwargs, scan_args},
+};
+use std::cell::RefCell;
+
+#[magnus::wrap(class = "Fulgur::EngineBuilder", free_immediately, size)]
+pub struct RbEngineBuilder {
+    inner: RefCell<Option<EngineBuilder>>,
+}
+
+impl RbEngineBuilder {
+    fn new() -> Self {
+        Self {
+            inner: RefCell::new(Some(Engine::builder())),
+        }
+    }
+
+    fn take(&self) -> Result<EngineBuilder, Error> {
+        self.inner.borrow_mut().take().ok_or_else(|| {
+            Error::new(
+                magnus::exception::runtime_error(),
+                "EngineBuilder has already been built",
+            )
+        })
+    }
+
+    fn map(&self, f: impl FnOnce(EngineBuilder) -> EngineBuilder) -> Result<(), Error> {
+        let b = self.take()?;
+        *self.inner.borrow_mut() = Some(f(b));
+        Ok(())
+    }
+}
+
+// -- setter (chain API) --
+//
+// `magnus::typed_data::Obj<T>` は TypedData wrapper を保持する Ruby オブジェクト参照で、
+// `Deref<Target = T>` を実装している。setter は同じ self (Obj) を返して Ruby 側で
+// `.page_size(:a4).margin(...)` の chain を成立させる。
+
+fn builder_page_size(
+    b: magnus::typed_data::Obj<RbEngineBuilder>,
+    value: Value,
+) -> Result<magnus::typed_data::Obj<RbEngineBuilder>, Error> {
+    let ps = extract_page_size(value)?;
+    b.map(|inner| inner.page_size(ps))?;
+    Ok(b)
+}
+
+fn builder_margin(
+    b: magnus::typed_data::Obj<RbEngineBuilder>,
+    m: &RbMargin,
+) -> Result<magnus::typed_data::Obj<RbEngineBuilder>, Error> {
+    // `Margin` は `Copy`。クロージャに move するためローカルへコピーする。
+    let margin = m.inner;
+    b.map(|inner| inner.margin(margin))?;
+    Ok(b)
+}
+
+fn builder_assets(
+    b: magnus::typed_data::Obj<RbEngineBuilder>,
+    bundle: &RbAssetBundle,
+) -> Result<magnus::typed_data::Obj<RbEngineBuilder>, Error> {
+    let taken = bundle.take_inner();
+    b.map(|inner| inner.assets(taken))?;
+    Ok(b)
+}
+
+fn builder_landscape(
+    b: magnus::typed_data::Obj<RbEngineBuilder>,
+    v: bool,
+) -> Result<magnus::typed_data::Obj<RbEngineBuilder>, Error> {
+    b.map(|inner| inner.landscape(v))?;
+    Ok(b)
+}
+
+fn builder_title(
+    b: magnus::typed_data::Obj<RbEngineBuilder>,
+    s: String,
+) -> Result<magnus::typed_data::Obj<RbEngineBuilder>, Error> {
+    b.map(|inner| inner.title(s))?;
+    Ok(b)
+}
+
+fn builder_author(
+    b: magnus::typed_data::Obj<RbEngineBuilder>,
+    s: String,
+) -> Result<magnus::typed_data::Obj<RbEngineBuilder>, Error> {
+    b.map(|inner| inner.author(s))?;
+    Ok(b)
+}
+
+fn builder_lang(
+    b: magnus::typed_data::Obj<RbEngineBuilder>,
+    s: String,
+) -> Result<magnus::typed_data::Obj<RbEngineBuilder>, Error> {
+    b.map(|inner| inner.lang(s))?;
+    Ok(b)
+}
+
+fn builder_bookmarks(
+    b: magnus::typed_data::Obj<RbEngineBuilder>,
+    v: bool,
+) -> Result<magnus::typed_data::Obj<RbEngineBuilder>, Error> {
+    b.map(|inner| inner.bookmarks(v))?;
+    Ok(b)
+}
+
+fn builder_build(b: magnus::typed_data::Obj<RbEngineBuilder>) -> Result<RbEngine, Error> {
+    let built = b.take()?;
+    Ok(RbEngine {
+        inner: built.build(),
+    })
+}
+
+#[magnus::wrap(class = "Fulgur::Engine", free_immediately, size)]
+pub struct RbEngine {
+    pub(crate) inner: Engine,
+}
+
+impl RbEngine {
+    /// HTML 文字列を PDF バイト列に変換し、`Fulgur::Pdf` でラップして返す。
+    ///
+    /// レンダリング本体は GVL を解放して実行するため、他の Ruby スレッド
+    /// (Thread.new 等) が並行して進める。GVL 解放中のクロージャ内では
+    /// Ruby VM に触れてはならないので、エラー変換 (`map_fulgur_error`) は
+    /// GVL 再取得後に行う。
+    fn render_html(&self, html: String) -> Result<RbPdf, Error> {
+        // `Engine: Send + Sync` は `src/lib.rs` の `assert_impl_all!` で
+        // コンパイル時に検証済み。raw pointer に一段落としてクロージャへ
+        // 渡し、GVL 解放スレッド側で `&Engine` に戻す。
+        struct Args {
+            engine: *const Engine,
+            html: String,
+        }
+        // SAFETY: `Engine: Sync` なので複数スレッドから &Engine 経由で
+        // read-only 参照するのは安全。raw pointer 自体は !Send のため
+        // 明示的に unsafe impl で Send を付与する。self (RbEngine) は
+        // `without_gvl` の間 block される呼び出し側スタックに生きている
+        // ので、dangling にはならない。
+        unsafe impl Send for Args {}
+
+        let args = Args {
+            engine: &self.inner as *const Engine,
+            html,
+        };
+        let result: Result<Vec<u8>, fulgur::Error> = crate::gvl::without_gvl(args, |a| {
+            // SAFETY: `a.engine` は呼び出し元の `&self.inner` から作った
+            // pointer。`without_gvl` は呼び出し元を block しているため、
+            // この closure が走っている間 `self` は生存している。
+            let engine: &Engine = unsafe { &*a.engine };
+            engine.render_html(&a.html)
+        });
+
+        let ruby = Ruby::get().expect("ruby vm");
+        match result {
+            Ok(bytes) => Ok(RbPdf::new(bytes)),
+            Err(e) => Err(map_fulgur_error(&ruby, e)),
+        }
+    }
+
+    /// HTML を PDF に変換してファイルに書き出す。`render_html` と同じく GVL を
+    /// 解放して実行する。`path` は `String` または `to_path` 応答オブジェクト (`Pathname` 等)。
+    fn render_html_to_file(&self, html: String, path: Value) -> Result<(), Error> {
+        struct Args {
+            engine: *const Engine,
+            html: String,
+            path: std::path::PathBuf,
+        }
+        // SAFETY: `render_html` と同じ不変条件。`Engine: Send + Sync` は
+        // compile-time に assert されている。`without_gvl` は呼び出し元を
+        // block するため、closure 実行中に `self` (= *engine) は生きている。
+        unsafe impl Send for Args {}
+
+        let path_str = crate::pdf::coerce_to_path(path)?;
+        let args = Args {
+            engine: &self.inner as *const Engine,
+            html,
+            path: std::path::PathBuf::from(path_str),
+        };
+        let result: Result<(), fulgur::Error> = crate::gvl::without_gvl(args, |a| {
+            // SAFETY: `a.engine` は呼び出し元の `&self.inner` から作った
+            // pointer。`without_gvl` の block 中は self が生存している。
+            let engine: &Engine = unsafe { &*a.engine };
+            engine.render_html_to_file(&a.html, &a.path)
+        });
+
+        let ruby = Ruby::get().expect("ruby vm");
+        result.map_err(|e| map_fulgur_error(&ruby, e))
+    }
+}
+
+/// kwargs-only constructor。positional args は受け付けない。
+fn engine_new(args: &[Value]) -> Result<RbEngine, Error> {
+    let scanned = scan_args::<(), (), (), (), _, ()>(args)?;
+    let kw = get_kwargs::<
+        _,
+        (),
+        (
+            Option<Value>,
+            Option<&RbMargin>,
+            Option<bool>,
+            Option<String>,
+            Option<String>,
+            Option<String>,
+            Option<bool>,
+            Option<&RbAssetBundle>,
+        ),
+        (),
+    >(
+        scanned.keywords,
+        &[],
+        &[
+            "page_size",
+            "margin",
+            "landscape",
+            "title",
+            "author",
+            "lang",
+            "bookmarks",
+            "assets",
+        ],
+    )?;
+    let (page_size, margin, landscape, title, author, lang, bookmarks, assets) = kw.optional;
+
+    let mut b = Engine::builder();
+    if let Some(v) = page_size {
+        b = b.page_size(extract_page_size(v)?);
+    }
+    if let Some(m) = margin {
+        b = b.margin(m.inner);
+    }
+    if let Some(v) = landscape {
+        b = b.landscape(v);
+    }
+    if let Some(s) = title {
+        b = b.title(s);
+    }
+    if let Some(s) = author {
+        b = b.author(s);
+    }
+    if let Some(s) = lang {
+        b = b.lang(s);
+    }
+    if let Some(v) = bookmarks {
+        b = b.bookmarks(v);
+    }
+    if let Some(bundle) = assets {
+        b = b.assets(bundle.take_inner());
+    }
+    Ok(RbEngine { inner: b.build() })
+}
+
+fn engine_builder() -> RbEngineBuilder {
+    RbEngineBuilder::new()
+}
+
+pub fn define(_ruby: &Ruby, fulgur: &RModule) -> Result<(), Error> {
+    let engine = fulgur.define_class("Engine", magnus::class::object())?;
+    engine.define_singleton_method("new", function!(engine_new, -1))?;
+    engine.define_singleton_method("builder", function!(engine_builder, 0))?;
+    engine.define_method("render_html", method!(RbEngine::render_html, 1))?;
+    engine.define_method(
+        "render_html_to_file",
+        method!(RbEngine::render_html_to_file, 2),
+    )?;
+
+    let builder = fulgur.define_class("EngineBuilder", magnus::class::object())?;
+    builder.define_method("page_size", method!(builder_page_size, 1))?;
+    builder.define_method("margin", method!(builder_margin, 1))?;
+    builder.define_method("assets", method!(builder_assets, 1))?;
+    builder.define_method("landscape", method!(builder_landscape, 1))?;
+    builder.define_method("title", method!(builder_title, 1))?;
+    builder.define_method("author", method!(builder_author, 1))?;
+    builder.define_method("lang", method!(builder_lang, 1))?;
+    builder.define_method("bookmarks", method!(builder_bookmarks, 1))?;
+    builder.define_method("build", method!(builder_build, 0))?;
+    Ok(())
+}

data/src/error.rs

@@ -0,0 +1,57 @@
+//! Fulgur::Error → Ruby 例外 への写像。
+//!
+//! Ruby 側の `Fulgur::Error` / `Fulgur::RenderError` / `Fulgur::AssetError` クラスは
+//! `lib/fulgur.rb` で既に定義済み。このモジュールでは lookup のみ行い、
+//! `fulgur::Error` の variant に応じて適切な Ruby 例外に変換する。
+
+use fulgur::Error as FulgurError;
+use magnus::{Error, ExceptionClass, Module, RModule, Ruby, exception};
+
+/// Ruby 側の `Fulgur::<name>` 例外クラスを lookup する。
+fn class(ruby: &Ruby, name: &str) -> Result<ExceptionClass, Error> {
+    let fulgur = ruby.class_object().const_get::<_, RModule>("Fulgur")?;
+    fulgur.const_get::<_, ExceptionClass>(name)
+}
+
+/// `fulgur::Error` を Ruby の `magnus::Error` に変換する。
+///
+/// - `Io(NotFound)` → `Errno::ENOENT`
+/// - `Io(_)` / `WoffDecode` / `HtmlParse` / `Layout` / `PdfGeneration` / `Template` → `Fulgur::RenderError`
+/// - `Asset` / `UnsupportedFontFormat` → `Fulgur::AssetError`
+///
+/// lookup に失敗した場合は `RuntimeError` にフォールバックする。
+pub fn map_fulgur_error(ruby: &Ruby, err: FulgurError) -> Error {
+    match err {
+        FulgurError::Io(io_err) => match io_err.kind() {
+            std::io::ErrorKind::NotFound => {
+                let errno = ruby
+                    .class_object()
+                    .const_get::<_, RModule>("Errno")
+                    .and_then(|m| m.const_get::<_, ExceptionClass>("ENOENT"))
+                    .unwrap_or_else(|_| exception::runtime_error());
+                Error::new(errno, io_err.to_string())
+            }
+            _ => render_error(ruby, io_err.to_string()),
+        },
+        FulgurError::Asset(msg) | FulgurError::UnsupportedFontFormat(msg) => asset_error(ruby, msg),
+        FulgurError::WoffDecode(msg)
+        | FulgurError::HtmlParse(msg)
+        | FulgurError::Layout(msg)
+        | FulgurError::PdfGeneration(msg)
+        | FulgurError::Template(msg) => render_error(ruby, msg),
+    }
+}
+
+fn render_error(ruby: &Ruby, msg: String) -> Error {
+    match class(ruby, "RenderError") {
+        Ok(c) => Error::new(c, msg),
+        Err(_) => Error::new(exception::runtime_error(), msg),
+    }
+}
+
+fn asset_error(ruby: &Ruby, msg: String) -> Error {
+    match class(ruby, "AssetError") {
+        Ok(c) => Error::new(c, msg),
+        Err(_) => Error::new(exception::runtime_error(), msg),
+    }
+}

data/src/gvl.rs

@@ -0,0 +1,79 @@
+//! GVL (Giant VM Lock) 解放ヘルパ。
+//!
+//! magnus 0.7 は GVL 解放 API を持たないため、rb-sys の
+//! `rb_thread_call_without_gvl` を直接呼ぶ。解放中のスレッドで
+//! Ruby VM に触れると UB になるため、closure は Rust-only データで動く
+//! ようにする (`&Engine`, `String` など)。
+//!
+//! # 設計メモ
+//!
+//! - `body` は `fn` pointer (キャプチャ無し)。キャプチャが必要なら
+//!   `Data` に必要な値を詰めて渡す。現在の `render_html` 呼び出しでは
+//!   `Args { engine: *const Engine, html: String }` 相当を渡す。
+//! - ubf (unblock function) は `None`。Ruby プロセスが signal を受けても
+//!   GVL 再取得まで保留される。v0.5.0 では interruptable rendering を
+//!   実装しないので OK。
+//! - `body` 内で panic が発生した場合、`extern "C"` 境界を unwind すると
+//!   UB になる (rustc docs 参照)。shim 内で `catch_unwind` で捕捉し、
+//!   GVL 再取得後に `resume_unwind` で伝播させる。
+
+use std::ffi::c_void;
+use std::panic::{AssertUnwindSafe, catch_unwind, resume_unwind};
+
+/// `body` を GVL 解放状態で実行する。
+///
+/// # Safety (呼び出し側契約)
+///
+/// `body` 内で Ruby VM API を呼んではならない。`Value`, `RString`, `Ruby::get()`
+/// のような Ruby 依存の型・関数はすべて禁止。純粋な Rust データ (`String`,
+/// `&Engine` など) のみ操作すること。
+///
+/// `body` 内で panic が発生した場合は `catch_unwind` で捕捉され、GVL 再取得後に
+/// `resume_unwind` で呼び出し側スレッドに伝播する。unwind が `extern "C"` 境界を
+/// 越えないため UB にはならない。
+pub fn without_gvl<Data, Ret>(data: Data, body: fn(Data) -> Ret) -> Ret {
+    struct Payload<D, R> {
+        data: Option<D>,
+        body: fn(D) -> R,
+        result: Option<std::thread::Result<R>>,
+    }
+
+    unsafe extern "C" fn shim<D, R>(arg: *mut c_void) -> *mut c_void {
+        // SAFETY: arg は `Payload<D, R>` への mutable pointer (caller が作る)。
+        // GVL 解放中、他の Ruby スレッドはこの領域を触れない (payload は
+        // caller のスタックにあり、caller は block する)。
+        let p = unsafe { &mut *(arg as *mut Payload<D, R>) };
+        let data = p.data.take().expect("payload data taken twice");
+        let body = p.body;
+        // panic を catch_unwind で捕捉し、extern "C" 境界を越える unwind (UB) を防ぐ。
+        // AssertUnwindSafe は `body: fn(Data) -> Ret` が UnwindSafe でないケース
+        // (e.g., `&Engine` を含む Data) でも、panic 後は payload を触らないため安全。
+        p.result = Some(catch_unwind(AssertUnwindSafe(move || body(data))));
+        std::ptr::null_mut()
+    }
+
+    let mut payload: Payload<Data, Ret> = Payload {
+        data: Some(data),
+        body,
+        result: None,
+    };
+    // SAFETY: shim は payload を mutable 参照するが、rb_thread_call_without_gvl
+    // は caller を block し、shim が終わるまで payload は生存する。ubf=None
+    // なので shim は必ず完走し、payload.result が Some になる。
+    unsafe {
+        rb_sys::rb_thread_call_without_gvl(
+            Some(shim::<Data, Ret>),
+            &mut payload as *mut _ as *mut c_void,
+            None,
+            std::ptr::null_mut(),
+        );
+    }
+    match payload
+        .result
+        .expect("rb_thread_call_without_gvl did not invoke shim")
+    {
+        Ok(v) => v,
+        // GVL 再取得済みの状態で panic を呼び出し側に伝播する。
+        Err(payload) => resume_unwind(payload),
+    }
+}

data/src/lib.rs

@@ -0,0 +1,40 @@
+//! Ruby bindings for fulgur (HTML/CSS → PDF).
+//!
+//! すべての magnus 依存コードは `ruby-api` feature で gate している。
+//! feature off の場合このクレートは空になり、`cargo build --workspace` が通る。
+//! 実バイナリは `rake compile` が `features = ["ruby-api"]` を注入してビルドする。
+
+#![cfg(feature = "ruby-api")]
+
+use magnus::{Error, define_module};
+
+mod asset_bundle;
+mod engine;
+mod error;
+mod gvl;
+mod margin;
+mod page_size;
+mod pdf;
+
+/// `engine.rs` の GVL 解放 (`unsafe impl Send for Args`) は `fulgur::Engine: Send + Sync` の
+/// コンパイル時保証に依存している。`[cfg(test)]` ゲートを付けずに通常ビルドで走らせることで、
+/// `fulgur` crate 側の変更で `Engine` が `!Send` になった瞬間に `rake compile` が落ちる。
+mod assertions {
+    use static_assertions::assert_impl_all;
+    assert_impl_all!(fulgur::Engine: Send, Sync);
+    // `fulgur::AssetBundle` (root re-export) は 0.4.5 には存在せず HEAD のみ。
+    // release-ruby は crates.io の ext 依存 (0.4.5 時点では 0.4.5) を使うため、
+    // full path `fulgur::asset::AssetBundle` を参照して前方互換を保つ。
+    assert_impl_all!(fulgur::asset::AssetBundle: Send, Sync);
+}
+
+#[magnus::init]
+fn init(ruby: &magnus::Ruby) -> Result<(), Error> {
+    let fulgur = define_module("Fulgur")?;
+    page_size::define(ruby, &fulgur)?;
+    margin::define(ruby, &fulgur)?;
+    asset_bundle::define(ruby, &fulgur)?;
+    pdf::define(ruby, &fulgur)?;
+    engine::define(ruby, &fulgur)?;
+    Ok(())
+}

data/src/margin.rs

@@ -0,0 +1,76 @@
+//! `Fulgur::Margin` Ruby class wrapping `fulgur::Margin`.
+//!
+//! primitive constructor `__build__(top, right, bottom, left)` を Rust 側で定義し、
+//! Ruby 側 (`lib/fulgur/margin.rb`) が positional / kwargs を解釈して `__build__` を呼び出す。
+//! factory method として `.uniform(pt)` と `.symmetric(vertical, horizontal)` も公開する。
+
+use fulgur::Margin;
+use magnus::{Error, Module, RModule, Ruby, function, method, prelude::*};
+
+#[magnus::wrap(class = "Fulgur::Margin", free_immediately, size)]
+#[derive(Clone, Copy)]
+pub struct RbMargin {
+    pub(crate) inner: Margin,
+}
+
+impl RbMargin {
+    pub(crate) fn new(inner: Margin) -> Self {
+        Self { inner }
+    }
+
+    fn top(&self) -> f32 {
+        self.inner.top
+    }
+
+    fn right(&self) -> f32 {
+        self.inner.right
+    }
+
+    fn bottom(&self) -> f32 {
+        self.inner.bottom
+    }
+
+    fn left(&self) -> f32 {
+        self.inner.left
+    }
+
+    fn inspect(&self) -> String {
+        format!(
+            "#<Fulgur::Margin top={:.2} right={:.2} bottom={:.2} left={:.2}>",
+            self.inner.top, self.inner.right, self.inner.bottom, self.inner.left
+        )
+    }
+
+    fn uniform(pt: f32) -> Self {
+        Self::new(Margin::uniform(pt))
+    }
+
+    fn symmetric(vertical: f32, horizontal: f32) -> Self {
+        Self::new(Margin::symmetric(vertical, horizontal))
+    }
+
+    /// Ruby 側 `Fulgur::Margin.new` から呼ばれる primitive constructor。
+    /// Ruby 側が positional / kwargs を解釈して `__build__(t, r, b, l)` を呼び出す。
+    fn from_trbl(top: f32, right: f32, bottom: f32, left: f32) -> Self {
+        Self::new(Margin {
+            top,
+            right,
+            bottom,
+            left,
+        })
+    }
+}
+
+pub fn define(_ruby: &Ruby, fulgur: &RModule) -> Result<(), Error> {
+    let class = fulgur.define_class("Margin", magnus::class::object())?;
+    class.define_singleton_method("__build__", function!(RbMargin::from_trbl, 4))?;
+    class.define_singleton_method("uniform", function!(RbMargin::uniform, 1))?;
+    class.define_singleton_method("symmetric", function!(RbMargin::symmetric, 2))?;
+    class.define_method("top", method!(RbMargin::top, 0))?;
+    class.define_method("right", method!(RbMargin::right, 0))?;
+    class.define_method("bottom", method!(RbMargin::bottom, 0))?;
+    class.define_method("left", method!(RbMargin::left, 0))?;
+    class.define_method("inspect", method!(RbMargin::inspect, 0))?;
+    class.define_method("to_s", method!(RbMargin::inspect, 0))?;
+    Ok(())
+}

data/src/page_size.rs

@@ -0,0 +1,93 @@
+//! `Fulgur::PageSize` Ruby class wrapping `fulgur::PageSize`.
+//!
+//! 定数 `A4` / `LETTER` / `A3`、`.custom(width_mm, height_mm)` クラスメソッド、
+//! インスタンスメソッド `width` / `height` / `landscape` / `inspect` / `to_s` を公開する。
+//!
+//! 併せて、Task 6 以降の engine バインディングから使われる `extract()` ヘルパーを提供し、
+//! `Symbol` / `String` / `Fulgur::PageSize` のいずれでも `fulgur::PageSize` に変換できるようにする。
+
+use fulgur::PageSize;
+use magnus::{
+    Error, Module, RModule, Ruby, Symbol, TryConvert, Value, function, method, prelude::*,
+};
+
+#[magnus::wrap(class = "Fulgur::PageSize", free_immediately, size)]
+#[derive(Clone, Copy)]
+pub struct RbPageSize {
+    pub(crate) inner: PageSize,
+}
+
+impl RbPageSize {
+    pub(crate) fn new(inner: PageSize) -> Self {
+        Self { inner }
+    }
+
+    fn width(&self) -> f32 {
+        self.inner.width
+    }
+
+    fn height(&self) -> f32 {
+        self.inner.height
+    }
+
+    fn landscape(&self) -> Self {
+        Self::new(self.inner.landscape())
+    }
+
+    fn inspect(&self) -> String {
+        format!(
+            "#<Fulgur::PageSize width={:.2} height={:.2}>",
+            self.inner.width, self.inner.height
+        )
+    }
+
+    fn custom(width_mm: f32, height_mm: f32) -> Self {
+        Self::new(PageSize::custom(width_mm, height_mm))
+    }
+}
+
+/// `Symbol` / `String` / `Fulgur::PageSize` を `fulgur::PageSize` に変換する。
+/// Task 6 以降の engine バインディングから呼び出される。
+#[allow(dead_code)]
+pub fn extract(value: Value) -> Result<PageSize, Error> {
+    if let Ok(ps) = <&RbPageSize>::try_convert(value) {
+        return Ok(ps.inner);
+    }
+    if let Ok(sym) = <Symbol>::try_convert(value) {
+        return parse_name(&sym.name()?);
+    }
+    if let Ok(s) = <String>::try_convert(value) {
+        return parse_name(&s);
+    }
+    Err(Error::new(
+        magnus::exception::arg_error(),
+        "page_size must be Symbol, String, or Fulgur::PageSize",
+    ))
+}
+
+fn parse_name(name: &str) -> Result<PageSize, Error> {
+    match name.to_ascii_uppercase().as_str() {
+        "A4" => Ok(PageSize::A4),
+        "LETTER" => Ok(PageSize::LETTER),
+        "A3" => Ok(PageSize::A3),
+        other => Err(Error::new(
+            magnus::exception::arg_error(),
+            format!("unknown page size: {other}"),
+        )),
+    }
+}
+
+pub fn define(_ruby: &Ruby, fulgur: &RModule) -> Result<(), Error> {
+    let class = fulgur.define_class("PageSize", magnus::class::object())?;
+    class.define_singleton_method("custom", function!(RbPageSize::custom, 2))?;
+    class.define_method("width", method!(RbPageSize::width, 0))?;
+    class.define_method("height", method!(RbPageSize::height, 0))?;
+    class.define_method("landscape", method!(RbPageSize::landscape, 0))?;
+    class.define_method("inspect", method!(RbPageSize::inspect, 0))?;
+    class.define_method("to_s", method!(RbPageSize::inspect, 0))?;
+
+    class.const_set("A4", RbPageSize::new(PageSize::A4))?;
+    class.const_set("LETTER", RbPageSize::new(PageSize::LETTER))?;
+    class.const_set("A3", RbPageSize::new(PageSize::A3))?;
+    Ok(())
+}