vivlio-starter-pdf 1.0.1 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65b529f996ccbfdab12d4a410404206e4580126c6e75dcbc1b45fb88c6044241
-  data.tar.gz: 6b8b71dbf5f5f622cca5dc4328016a71b0c29b3fa72dacb83914daae5abd4ac8
+  metadata.gz: 0335b9ec25ee9a373f9d4c261c1a4a610e87fb2ac538b2207b3dd8f741bc82c1
+  data.tar.gz: 9645fdbcb4575cae982bf48ef0c60f061b6f26afbbe101bd4530f95262c6da32
 SHA512:
-  metadata.gz: 01cd3cebf924395a018536bfff12940f6990c1051c2a782c48ff56bfb397c3c363d26c33c2b6e6abfdead321e884e0a9ec2da4189f4cbc656271d25c95c3d309
-  data.tar.gz: 4dc1e2d408d87ebd5738fc697338de5c55d7f8f62d6f38224774e263c392fb4a70e67ebb2f9354c3d76a747229f204c151173c1852f7a481d0d4149713f3e550
+  metadata.gz: 01f2c370439f11cf3012f32b092415a8aeebab059386f09462292952e7026b8b616db82e00aae11489465d562c0f90f89ea548f6df98d89523e05c7b0f1e8a00
+  data.tar.gz: 215ff34974f8bc3f2fd81f929bd39413ff79ad454db5993ee36c350dd48af12b091372b9b1ca42c6b048e29d5633e88b29bfb5dca3aebcaa8726d4d594773f4e

data/.ruby-version

@@ -0,0 +1 @@
+4.0.6

data/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+### Planned
+- パフォーマンス最適化（大規模 PDF 対応）
+- 追加 OCR エンジン対応
+- クラウド OCR サービス連携
+- PDF 暗号化対応
+
+## [1.1.2] - 2026-08-07
+
+### Changed
+- **必要な Ruby を 4.0 以上から 3.4 以上へ緩めた** (`vivlio-starter-pdf.gemspec`): Ruby 4.0 固有の機能は使っていない。Prism のバージョン指定パースで全 13 ファイルを解析したところ 4.0.0 / 3.4.0 / 3.3.0 いずれも構文エラー 0 件で、実際の下限を決めていたのは `it`（暗黙ブロック引数・38 箇所）**単独**だった。`it` は 3.3 でも構文エラーにならず実行時 `NameError` になる——静的解析では見つからないので、Ruby 3.4.10 で実走して全テスト通過を確認している。コード変更はゼロ（gemspec 1 行のみ）。本体 `vivlio-starter` の緩和に合わせたもので、本体だけ緩めてもプラグインが `>= 4.0` のままでは 3.4 環境に入らない。
+
+### Fixed
+- **壊れたアウトライン項目 1 件が、しおりを全滅させていたのを直した** (`outline_writer.rb`): 見出しのタイトルに不正な UTF-8 バイトが混ざると `String#strip` が `Encoding::CompatibilityError` を投げ、`add_outline!` の rescue まで飛んで **PDF からしおりが丸ごと消えていた**。範囲外ページ・空タイトル・深すぎる階層はいずれも `on_skip` で 1 件ずつ飛ばす設計なのに、ここだけ全体を巻き添えにしていた。
+  - `add_outline!` は `false` を返すだけで PDF 自体は出来上がるため、**成果物を開くまで誰も気付けない**種類の失敗だった。
+  - 該当項目だけを飛ばし、理由（`title is not valid UTF-8, skipping outline entry: …`）を `on_skip` で報告する。原稿のどの見出しを直せばよいか分かる形にした。
+  - `EncodingError` と `ArgumentError` の両方を捕まえる。壊れたバイト列に Ruby がどちらを投げるかはメソッド次第で（`strip` は `Encoding::CompatibilityError`、`match?` は `ArgumentError`）、その差でしおりの有無が決まってはならない。
+- **アウトライン項目に `nil` 以外の想定外の型が混ざると全体が止まっていたのを直した** (`outline_writer.rb`): `fetch` が `respond_to?(:[])` だけで添字アクセスしていたため、配列に `String` や `Integer` が紛れると `TypeError: no implicit conversion of Symbol into Integer`（`Integer#[]` はビット参照）で落ちていた。Hash 風オブジェクトは従来どおり受けつつ、添字アクセスの失敗は既定値へ倒す。
+
+### Added
+- **堅牢性テストを整備した** (`test/robustness/`): 本体 `vivlio-starter` の `test/vivlio_starter/robustness/` と同じ位置づけで 14 件を追加。守る約束は 2 つ——**公開 API は例外を外へ出さない**（ビルドパイプラインの途中から呼ばれるため、失敗は戻り値で伝える）、**失敗しても入力を壊さない**（読み込んだのと同じパスへ書き戻すため、途中失敗で元 PDF が切り詰められると最も気付きにくい事故になる）。上記 2 件の修正はこのテストを書く過程で見つかったもの。
+  - `broken_pdf_test.rb` — PDF でないファイル・0 バイト・存在しないパス・暗号化 PDF・書き込み不可ファイル。戻り値と、**入力のバイト列が不変であること**を固定
+  - `outline_entry_test.rb` — 壊れた項目を 1 件ずつ飛ばして残りを書くこと、飛ばした理由を報告すること、全滅時に空のしおりツリーを残さないこと
+
+## [1.1.1] - 2026-06-23
+
+### Fixed
+- 隠しノンブルのフォントを埋め込み可能な TTF に変更（FT-02）。HexaPDF 組込の標準 14 フォント `Helvetica` は PDF に埋め込まれず、印刷所入稿で「非埋め込みフォント」事故になっていた。書籍プロジェクト直下に同梱の `stylesheets/fonts/hackgen35/HackGen35ConsoleNF-Regular.ttf` があれば `font.map` へ登録して使用し、数字グリフのみをサブセット埋め込みする（極小）。同梱フォントが無い場合は従来どおり `Helvetica` にフォールバックしてビルドは継続する。`EnhancedProviderTest` を追加。
+
+## [1.1.0] - 2026-06-10
+
+### Changed
+- 本体側に合わせ、lib/vivlio_starter/cli/pdf/配下にファイル構成を調整した。
+
 ## [1.0.1] - 2026-03-21
 
 ### Added
@@ -59,13 +92,3 @@ vivlio-starter-pdf 1.0.0 としてリリース！HexaPDF を活用した高度
 - 日本語テキストの空白圧縮処理
 - 括弧の正規化と誤読修正
 - 出版向けの文字処理最適化
-
----
-
-## [Unreleased]
-
-### Planned
-- パフォーマンス最適化（大規模 PDF 対応）
-- 追加 OCR エンジン対応
-- クラウド OCR サービス連携
-- PDF 暗号化対応

data/README.md

@@ -1,7 +1,7 @@
 # vivlio-starter-pdf
 
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
-[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%204.0-red.svg)](https://www.ruby-lang.org/)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.4-red.svg)](https://www.ruby-lang.org/)
 
 **vivlio-starter** の AGPL 拡張プラグイン。HexaPDF を活用した高度な PDF 解析・後処理機能を提供します。
 
@@ -46,24 +46,34 @@ brew install tesseract tesseract-lang poppler vips
 vs pdf:read document.pdf
 ```
 
+標準（MIT）実装に戻して動作を比べたいときは、環境変数で無効化できます。
+
+```zsh
+VIVLIO_PDF_PLUGIN=disable vs build
+```
+
 ### Ruby API
 
 ```ruby
-require "vivlio/starter/pdf"
+require "vivlio_starter/pdf"
 
 # PDF → Markdown 変換
-result = Vivlio::Starter::PDF::Reader.new("input.pdf",
+result = VivlioStarter::Pdf::Reader.new("input.pdf",
   ocr: { mode: "auto", languages: ["jpn"], dpi: 300 }
 ).execute
 
 # アウトライン付与
-provider = Vivlio::Starter::Pdf::EnhancedProvider.new
+provider = VivlioStarter::Pdf::EnhancedProvider.new
 provider.add_outline!(pdf_path, items, max_level: 3)
 
 # 隠しノンブル
 provider.stamp_nombre!(pdf_path, bleed_pt: 8.5)
 ```
 
+`stamp_nombre!` / `add_outline!` は成功で `true`、失敗で `false` を返し、`page_count` は失敗で `nil` を返します。**例外は外へ出しません**（本体のビルドパイプラインの途中から呼ばれるため）。失敗しても入力 PDF は書き換えません。
+
+`add_outline!` の `items` は `{ level:, text:, page: }` の配列です。壊れた項目（不正な UTF-8 のタイトル・範囲外ページ・空タイトル）は 1 件ずつ飛ばして残りを書き込み、飛ばした理由をログに出します。
+
 ## 設定
 
 `config/book.yml` の `pdf_read` セクションで挙動を制御できます。

data/RELEASE_NOTE.md

@@ -1,133 +1,55 @@
-# vivlio-starter-pdf 1.0.0 Release Note
+# vivlio-starter-pdf リリースノート
 
-## 🎉 最初のメジャーリリース
+書籍制作ツール **vivlio-starter** の AGPL 拡張プラグインです。HexaPDF を使い、隠しノンブル・PDF アウトライン・PDF → Markdown 変換（OCR 連携）を担当します。使い方は [README](README.md)、網羅的な変更履歴は [CHANGELOG](CHANGELOG.md) をご覧ください。
 
-vivlio-starter-pdf 1.0.0 をリリースできることを大変嬉しく思います。これは **vivlio-starter** の AGPL 拡張プラグインで、HexaPDF を活用した高度な PDF 解析・後処理機能を提供します。
+新しい版から順に並べています。
 
-## 🚀 主要機能
-
-### PDF → Markdown 変換
-- HexaPDF でテキスト・画像を高精度に抽出
-- 精密な座標解析による行・段落の再構成
-- Markdown 形式での構造化出力
-
-### OCR 連携と日本語対応 🆕
-- スキャン PDF を自動検出
-- Tesseract による日本語 OCR 実行
-- OCR テキストの空白圧縮と括弧正規化
-- prh 辞書による誤読修正
-
-### 画像抽出と位置合わせ
-- PDF 内の XObject を解析し、WebP 形式で書き出し
-- テキスト行と画像の精密な座標マッピング
-- イラスト領域の自動検出と除外
-
-### 出版向け機能
-- **隠しノンブル**: 入稿用 PDF の塗り足し領域にページ番号をオーバーレイ
-- **PDF アウトライン**: HTML 見出しを解析し、PDF のブックマークツリーを構築
-
-## 📦 インストール
-
-```ruby
-# Gemfile
-gem 'vivlio-starter-pdf', '~> 1.0.0'
-```
-
-```bash
-bundle install
-```
-
-### 外部ツール（OCR 利用時）
-
-```bash
-brew install tesseract tesseract-lang poppler vips
-```
-
-## 💡 使用例
-
-### vivlio-starter との連携（プラグイン専用）
-
-```bash
-# Enhanced Mode で自動的に HexaPDF/OCR パイプラインを使用
-vs pdf:read document.pdf
-```
-
-### Ruby API
-
-```ruby
-require "vivlio/starter/pdf"
-
-# PDF → Markdown 変換
-result = Vivlio::Starter::PDF::Reader.new("input.pdf",
-  ocr: { mode: "auto", languages: ["jpn"], dpi: 300 }
-).execute
+---
 
-# アウトライン付与
-provider = Vivlio::Starter::Pdf::EnhancedProvider.new
-provider.add_outline!(pdf_path, items, max_level: 3)
+## 1.1.2 — 2026-08-07
 
-# 隠しノンブル
-provider.stamp_nombre!(pdf_path, bleed_pt: 8.5)
-```
+**細かな不具合修正が中心のリリースです。** ただし 1 件は成果物に直接影響するため、しおり付き PDF を作る方は更新をおすすめします。
 
-## 🔧 設定
+- **壊れた見出しが 1 つあると、しおりが丸ごと消えていた問題を直しました。** 見出しに不正な UTF-8 バイトが混ざると例外が最上位まで飛び、**PDF からしおりが全滅**していました。範囲外ページや空タイトルは 1 件ずつ飛ばす設計だったのに、ここだけ全体を巻き添えにしていたことになります。しかも PDF 自体は出来上がるため、**開いてみるまで誰も気付けません**。今は該当項目だけを飛ばし、どの見出しが原因かをログで知らせます
+- **想定外の型が項目に混ざると、アウトライン付与が止まっていた問題を直しました**（`TypeError`）
+- **必要な Ruby を 4.0 以上から 3.4 以上へ緩めました**（コード変更はゼロ、gemspec 1 行のみ）。本体の緩和に合わせたものです。本体だけ緩めても、プラグインが 4.0 以上のままでは 3.4 環境に入りません
 
-`config/book.yml` の `pdf_read` セクションで挙動を制御：
+あわせて、これらを二度と起こさないための**堅牢性テスト 14 件**を `test/robustness/` に追加しました。守る約束は 2 つです。
 
-```yaml
-pdf_read:
-  text_area:
-    top_margin: 18
-    bottom_margin: 20
-    inner_margin: 15
-    outer_margin: 12
-  page_separator: false
-  ocr:
-    mode: auto
-    languages:
-      - japanese
-    dpi: 300
-    psm: 3
-    inline_image_text: include
-```
+1. **公開 API は例外を外へ出さない。** 本体のビルドパイプラインの途中から呼ばれるため、1 つの PDF 操作が例外で飛ぶとビルド全体が落ちます。失敗は戻り値で伝えます
+2. **失敗しても入力を壊さない。** 読み込んだのと同じパスへ書き戻すので、途中で失敗して元 PDF が切り詰められると「ビルドは続いたのに成果物が壊れている」という最も気付きにくい事故になります
 
-## ✅ テスト品質
+上の 2 件は、このテストを書く過程で見つかりました。
 
-- **網羅的なテストスイート**
-- **実環境での動作検証**
-- **外部ツール連携のテスト**
+## 1.1.1 — 2026-06-23
 
-## 🔄 0.1.0 からの変更点
+- **隠しノンブルを埋め込み可能なフォントで描画するようにしました（FT-02）。** HexaPDF 組込の標準 14 フォント `Helvetica` は PDF に埋め込まれず、印刷所入稿で「非埋め込みフォント」の差し戻しになっていました
+- 書籍プロジェクト直下に同梱の `stylesheets/fonts/hackgen35/HackGen35ConsoleNF-Regular.ttf` があれば、数字グリフのみをサブセット埋め込みします（増分は極小）。無ければ従来どおり `Helvetica` にフォールバックしてビルドを続けます
 
-### 新機能
-- 完全な OCR 連携と日本語対応
-- 画像位置合わせの精密化
-- PDF アウトライン生成機能
-- 隠しノンブル機能
+## 1.1.0 — 2026-06-10
 
-### 改善
-- gemspec の RubyGems 公開設定
-- ドキュメントの整備
-- 外部ツールの自動案内
+- **名前空間を `VivlioStarter::Pdf` へ統一し、`lib/vivlio_starter/` 配下へ再編しました。** 1.0.0 以降で**唯一の非互換変更**です
 
-## 🎯 実績
+本体（`vs`）経由で使っている場合、影響はありません。**Ruby API を直接呼んでいる場合のみ**書き換えが必要です。
 
-- **vivlio-starter** Enhanced Mode で実稼働
-- **日本語出版** 向けの最適化完了
-- **HexaPDF** との高度な連携実現
-- **AGPL-3.0** ライセンス準拠
+| | 1.0.x | 1.1.0 以降 |
+|:---|:---|:---|
+| require | `require "vivlio/starter/pdf"` | `require "vivlio_starter/pdf"` |
+| 名前空間 | `Vivlio::Starter::PDF` と `Vivlio::Starter::Pdf` が混在 | `VivlioStarter::Pdf` に統一 |
 
-## 📋 互換性
+1.0.x では `PDF` と `Pdf` の 2 つの綴りが同居しており、どちらを書けばよいか実物を見ないと分からない状態でした。
 
-- **Ruby**: 4.0+
-- **依存**: hexapdf (~> 1.0), ruby-vips (~> 2.2)
-- **外部ツール**: Tesseract, poppler, libvips（OCR 使用時）
-- **セマンティックバージョニング**: 1.x.x 系は後方互換性を保証
+## 1.0.1 — 2026-03-21
 
-## 🙏 感謝
+- **CLI を追加しました**（`vivlio-starter-pdf --version` / `--help`）。インストール直後に動作確認できます
 
-vivlio-starter-pdf の開発にあたり、HexaPDF の強力な PDF 処理能力と、日本語出版の現場でのニーズが大きな助けとなりました。特に OCR 連携と日本語テキスト処理についての知見は、本プラグインをより実用的なものにする上で不可欠でした。
+## 1.0.0 — 2026-03-21
 
----
+最初のメジャーリリースです。
 
-**vivlio-starter-pdf 1.0.0**: 高度な PDF 処理のための強力な拡張プラグイン
+- **隠しノンブル** — 入稿用 PDF の塗り足し領域に、断裁されて消えるページ番号を刷り込みます
+- **PDF アウトライン** — 見出しから PDF のブックマークツリーを構築します
+- **PDF → Markdown 変換** — HexaPDF でテキスト・画像を座標付きで抽出します
+- **OCR 連携** — スキャン PDF を自動検出し、Tesseract で日本語 OCR を実行。空白圧縮・括弧正規化・prh 辞書による誤読修正まで行います
+- **画像抽出** — PDF 内の XObject を解析し、WebP 形式で書き出します
+- プラグイン専用設計。インストールされていれば本体が自動検出し、Standard Mode から Enhanced Mode へ切り替わります

data/Rakefile

@@ -3,10 +3,72 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+# gemspec が Ruby 3.4 以上を謳う以上、それが本当かは実際に走らせないと分からない。
+# `it`（暗黙ブロック引数）は 3.3 以下でも構文エラーにならず「it というメソッドの
+# 呼び出し」として通り、実行時に NameError になる——静的解析では捕まらない。
+SUPPORTED_RUBY_VERSIONS = %w[3.4.10 4.0.6].freeze
+
+# 別の Ruby を子プロセスで起動する以上、親の bundler 環境は必ず捨てる。
+# `bundle exec rake test` から呼ばれると、親（現在の Ruby）の bundler を
+# 子（別の Ruby）が読みに行き、テストが始まる前に LoadError で落ちる。
+# nil を渡すと、その環境変数は子から取り除かれる。
+UNBUNDLED_ENV = {
+  "RUBYOPT" => nil, "RUBYLIB" => nil, "GEM_HOME" => nil, "GEM_PATH" => nil,
+  "BUNDLE_GEMFILE" => nil, "BUNDLE_BIN_PATH" => nil, "BUNDLER_VERSION" => nil,
+  "BUNDLER_SETUP" => nil
+}.freeze
+
+namespace :test do
+  # テストの実体。現在の Ruby で 1 回だけ走る（test:versions が各版でこれを呼ぶ）
+  Rake::TestTask.new(:current) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/**/*_test.rb"]
+  end
+
+  desc "対応する全 Ruby 版（#{SUPPORTED_RUBY_VERSIONS.join(' / ')}）でテストする"
+  task :versions do
+    missing = SUPPORTED_RUBY_VERSIONS - `rbenv versions --bare`.split("\n")
+    unless missing.empty?
+      abort <<~MESSAGE
+        次の Ruby が rbenv に入っていません: #{missing.join(', ')}
+          #{missing.map { "rbenv install #{it}" }.join("\n  ")}
+      MESSAGE
+    end
+
+    # 版ごとに bundle が要る。未導入なら黙って入れる（その版の初回だけ時間がかかる）
+    failed = SUPPORTED_RUBY_VERSIONS.reject do |version|
+      puts "\n=== Ruby #{version} ==="
+      env = UNBUNDLED_ENV.merge("RBENV_VERSION" => version)
+
+      unless system(env, "rbenv exec bundle check", out: File::NULL, err: File::NULL)
+        next false unless system(env, "rbenv exec bundle install --quiet")
+      end
+
+      system(env, "rbenv exec bundle exec rake test:current")
+    end
+
+    abort "\n失敗した Ruby: #{failed.join(', ')}" unless failed.empty?
+    puts "\n全 Ruby 版で通過: #{SUPPORTED_RUBY_VERSIONS.join(' / ')}"
+  end
 end
 
+# 手元では常に対応全版を回す（1 版あたり 10 秒弱で終わるため、分けるほどの負担にならない）。
+# CI（GitHub Actions）は版をマトリクスで分担するので、各ジョブは 1 回でよい。
+task test: (ENV["CI"] ? "test:current" : "test:versions")
 task default: :test
+
+# gem のアンインストール → ビルド → インストールを一括実行
+task :reinstall do
+  gemspec = Dir['*.gemspec'].first
+  raise 'gemspec が見つかりません' unless gemspec
+
+  require_relative 'lib/vivlio_starter/cli/pdf/version'
+  version = VivlioStarter::Pdf::VERSION
+  gem_name = 'vivlio-starter-pdf'
+  gem_file = "#{gem_name}-#{version}.gem"
+
+  sh "gem uninstall #{gem_name} --version #{version} --executables --ignore-dependencies 2>/dev/null || true"
+  sh "gem build #{gemspec}"
+  sh "gem install #{gem_file}"
+end

data/exe/vivlio-starter-pdf

@@ -1,52 +1,50 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'vivlio/starter/pdf'
+require 'vivlio_starter/pdf'
 
 # vivlio-starter-pdf CLI
 # Provides basic version information for debugging and user confirmation
 
-module Vivlio
-  module Starter
-    module PDF
-      class CLI
-        def self.run(args = [])
-          case args[0]
-          when '--version', '-v'
-            puts "vivlio-starter-pdf #{VERSION}"
-          when '--help', '-h', nil
-            puts <<~HELP
-              vivlio-starter-pdf #{VERSION} - Advanced PDF processor for vivlio-starter
-              
-              Usage:
-                vivlio-starter-pdf [options]
-              
-              Options:
-                --version, -v  Print version and exit
-                --help, -h     Print this help and exit
-              
-              Description:
-                vivlio-starter-pdf is an AGPL-licensed plugin for vivlio-starter
-                that provides advanced PDF processing capabilities including:
-                - PDF to Markdown conversion using HexaPDF
-                - Japanese OCR support with Tesseract
-                - Image extraction and precise positioning
-                - PDF outline generation and hidden pagination
-              
-              This is a plugin and should be used through vivlio-starter:
-                vs pdf:read document.pdf
-              
-              For more information, visit: https://github.com/Atelier-Mirai/vivlio-starter-pdf
-            HELP
-          else
-            puts "Error: Unknown option '#{args[0]}'"
-            puts "Use 'vivlio-starter-pdf --help' for usage information."
-            exit 1
-          end
+module VivlioStarter
+  module Pdf
+    class CLI
+      def self.run(args = [])
+        case args[0]
+        when '--version', '-v'
+          puts "vivlio-starter-pdf #{VERSION}"
+        when '--help', '-h', nil
+          puts <<~HELP
+            vivlio-starter-pdf #{VERSION} - Advanced PDF processor for vivlio-starter
+
+            Usage:
+              vivlio-starter-pdf [options]
+
+            Options:
+              --version, -v  Print version and exit
+              --help, -h     Print this help and exit
+
+            Description:
+              vivlio-starter-pdf is an AGPL-licensed plugin for vivlio-starter
+              that provides advanced PDF processing capabilities including:
+              - PDF to Markdown conversion using HexaPDF
+              - Japanese OCR support with Tesseract
+              - Image extraction and precise positioning
+              - PDF outline generation and hidden pagination
+
+            This is a plugin and should be used through vivlio-starter:
+              vs pdf:read document.pdf
+
+            For more information, visit: https://github.com/Atelier-Mirai/vivlio-starter-pdf
+          HELP
+        else
+          puts "Error: Unknown option '#{args[0]}'"
+          puts "Use 'vivlio-starter-pdf --help' for usage information."
+          exit 1
         end
       end
     end
   end
 end
 
-Vivlio::Starter::PDF::CLI.run(ARGV)
+VivlioStarter::Pdf::CLI.run(ARGV)

data/lib/vivlio_starter/cli/pdf/enhanced_provider.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "hexapdf"
+require_relative "utilities"
+require_relative "log_helper"
+require_relative "outline_writer"
+
+module VivlioStarter
+  module Pdf
+    # vivlio-starter 本体から呼び出される HexaPDF ベースのプロバイダ
+    #
+    # 隠しノンブル書き込み・PDF アウトライン付与など、
+    # Enhanced Mode 固有の PDF 操作を提供する。
+    class EnhancedProvider
+      # 隠しノンブルに使う埋め込み可能フォント（書籍プロジェクト同梱の TTF）。
+      # HexaPDF 組込の "Helvetica" は標準 14 フォントで PDF に埋め込まれず、印刷所入稿で
+      # 「非埋め込みフォント」事故になる（FT-02）。プロジェクト直下に同梱の
+      # HackGen35ConsoleNF があれば登録してサブセット埋め込みする（数字のみで極小）。
+      NOMBRE_FONT_RELATIVE = File.join("stylesheets", "fonts", "hackgen35", "HackGen35ConsoleNF-Regular.ttf")
+      # document.config の font.map へ登録する内部フォント名
+      NOMBRE_FONT_NAME = "VivlioNombre"
+      # 同梱フォントが見つからない場合のフォールバック（非埋め込み標準フォント）
+      FALLBACK_FONT_NAME = "Helvetica"
+      # 隠しノンブルのフォントサイズ（pt）
+      FONT_SIZE_PT = 6
+
+      # PDF のページ数を取得する
+      def page_count(pdf_path)
+        Utilities.page_count(pdf_path)
+      end
+
+      # 空白ページ PDF が存在しなければ生成する
+      def ensure_blank_page_pdf(path, width_pt, height_pt)
+        Utilities.ensure_blank_page_pdf(path, width_pt, height_pt)
+      end
+
+      # PDF の各ページに隠しノンブル（ページ番号）を書き込む
+      # 奇数ページは左端、偶数ページは右端に 90° 回転して配置する
+      # @param pdf_path [String] 対象 PDF のパス
+      # @param bleed_pt [Float] 塗り足し幅（pt）
+      # @return [Boolean] 成功なら true
+      def stamp_nombre!(pdf_path, bleed_pt:)
+        return false unless File.exist?(pdf_path)
+
+        document = HexaPDF::Document.open(pdf_path)
+        total = document.pages.count
+        return false if total.zero?
+
+        LogHelper.log_action("[NombreStamper] 隠しノンブルを書き込みます（#{total} ページ）[Enhanced Mode]…")
+
+        font = register_nombre_font(document)
+
+        document.pages.each_with_index do |page, idx|
+          stamp_page(page, idx + 1, bleed_pt: bleed_pt.to_f, font:)
+        end
+
+        document.write(pdf_path, optimize: true)
+        LogHelper.log_success("[NombreStamper] 隠しノンブル書き込み完了（#{total} ページ）")
+        true
+      rescue StandardError => e
+        LogHelper.log_error("[NombreStamper] 隠しノンブル書き込みに失敗: #{e.message}")
+        false
+      end
+
+      # PDF にアウトライン（しおり）を付与する
+      # OutlineWriter を使い、階層構造を HexaPDF のアウトラインツリーに変換する
+      # @param pdf_path [String] 対象 PDF のパス
+      # @param items [Array<Hash>] アウトライン項目（:level, :text, :page）
+      # @param max_level [Integer] アウトラインの最大階層深度
+      # @return [Boolean] 成功なら true
+      def add_outline!(pdf_path, items, max_level:)
+        return false unless File.exist?(pdf_path)
+
+        document = HexaPDF::Document.open(pdf_path)
+        writer = OutlineWriter.new(document, max_level:, on_skip: method(:log_outline_skip))
+        inserted = writer.write(items)
+        if inserted.zero?
+          LogHelper.log_warn("[OutlineWriter] 有効なアウトライン項目が存在しないためスキップしました")
+          return false
+        end
+
+        document.write(pdf_path, optimize: true)
+        LogHelper.log_success("[OutlineWriter] PDF にアウトラインを #{inserted} 件追加しました")
+        true
+      rescue StandardError => e
+        LogHelper.log_error("[OutlineWriter] PDF アウトライン付与に失敗: #{e.message}")
+        false
+      end
+
+      private
+
+      # 隠しノンブル用フォントを document へ登録し、canvas に渡すフォント名を返す。
+      # 同梱 TTF（NOMBRE_FONT_RELATIVE）があればサブセット埋め込みされる名前を、
+      # 見つからなければ非埋め込みの Helvetica（FALLBACK_FONT_NAME）を返す。
+      # @param document [HexaPDF::Document]
+      # @return [String] canvas.font に渡すフォント名
+      def register_nombre_font(document)
+        return FALLBACK_FONT_NAME unless File.exist?(NOMBRE_FONT_RELATIVE)
+
+        (document.config["font.map"] ||= {})[NOMBRE_FONT_NAME] = { none: NOMBRE_FONT_RELATIVE }
+        NOMBRE_FONT_NAME
+      end
+
+      # 1 ページに隠しノンブルを描画する
+      # 奇数ページは左端 90°、偶数ページは右端 -90° に回転配置する
+      def stamp_page(page, page_number, bleed_pt:, font:)
+        canvas = page.canvas(type: :overlay)
+        box = page.box(:media)
+
+        canvas.font(font, size: FONT_SIZE_PT)
+        canvas.fill_color(0)
+
+        x_offset = bleed_pt / 2.0
+        y_center = box.height / 2.0
+
+        if page_number.odd?
+          draw_rotated_text(canvas, page_number.to_s, x: x_offset, y: y_center, angle: 90)
+        else
+          draw_rotated_text(canvas, page_number.to_s, x: box.width - x_offset, y: y_center, angle: -90)
+        end
+      end
+
+      # キャンバス上の指定座標にテキストを回転描画する
+      def draw_rotated_text(canvas, text, x:, y:, angle:)
+        canvas
+          .save_graphics_state
+          .translate(x, y)
+          .rotate(angle)
+          .text(text, at: [0, 0])
+          .restore_graphics_state
+      end
+
+      # OutlineWriter のスキップ通知をログに出力するコールバック
+      def log_outline_skip(message)
+        LogHelper.log_warn("[OutlineWriter] #{message}")
+      end
+    end
+  end
+end

data/lib/vivlio_starter/cli/pdf/log_helper.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module VivlioStarter
+  module Pdf
+    # Logging helper that integrates with vivlio-starter CLI when available
+    module LogHelper
+      module_function
+
+      def log_action(message)
+        dispatch(:log_action, message) { puts(message) }
+      end
+
+      def log_info(message)
+        dispatch(:log_info, message) { puts(message) }
+      end
+
+      def log_success(message)
+        dispatch(:log_success, message) { puts(message) }
+      end
+
+      def log_warn(message)
+        dispatch(:log_warn, message) { warn(message) }
+      end
+
+      def log_error(message)
+        dispatch(:log_error, message) { warn(message) }
+      end
+
+      def dispatch(method, message)
+        if defined?(VivlioStarter::CLI::Common)
+          VivlioStarter::CLI::Common.public_send(method, message)
+        else
+          yield if block_given?
+        end
+      end
+    end
+  end
+end