pdfrb 0.2.1 → 0.6.0

data/PROPOSAL.stringio-require.md

@@ -0,0 +1,53 @@
+# PROPOSAL: Missing `require "stringio"` in Fonts
+
+## Summary
+
+`Pdfrb::Document::Fonts` references `StringIO` without requiring it.
+When pdfrb is loaded without another gem that happens to require
+`stringio` first, `Fonts#register_font` raises `NameError`.
+
+## Bug description
+
+In `fonts.rb`, line 204:
+
+```ruby
+def register_font(resource, name, name_or_io, **opts)
+  font_dict = if name_or_io.is_a?(IO) || name_or_io.is_a?(StringIO)
+    #                                  ^^^^^^^^ NameError if stringio not loaded
+```
+
+Line 207 also uses `StringIO`:
+
+```ruby
+io = StringIO.new(File.binread(name_or_io))
+```
+
+There is no `require "stringio"` at the top of `fonts.rb`.
+
+## Reproduction
+
+```ruby
+# In a clean Ruby process where stringio hasn't been loaded:
+require "pdfrb"
+doc = Pdfrb::Document.new
+doc.fonts.add("/path/to/font.ttf")
+# NameError: uninitialized constant Pdfrb::Document::Fonts::StringIO
+```
+
+In practice, other gems often load `stringio` first, masking this bug.
+But it surfaces in minimal environments.
+
+## Proposed fix
+
+Add to the top of `lib/pdfrb/document/fonts.rb`:
+
+```ruby
+require "stringio"
+```
+
+Or add it to `lib/pdfrb.rb` (the main entry point).
+
+## Priority
+
+Low — easy one-line fix, but rare in practice (other gems usually
+load stringio first).

data/PROPOSAL.struct-tree-root.md

@@ -0,0 +1,102 @@
+# PROPOSAL: StructTreeRoot for tagged PDF (PDF/UA)
+
+## Summary
+
+Add `Document#structure` facade for building PDF structure trees
+(`/StructTreeRoot`), enabling tagged PDF output for accessibility
+(PDF/UA, WCAG 2.1, Section 508 compliance).
+
+## Motivation
+
+pdfrb 0.3.0 already has Canvas tagged-content support (`tagged`,
+`artifact`, `marked_content`), but lacks the `/StructTreeRoot` assembly
+that ties tagged content sequences into a navigable structure tree.
+Without StructTreeRoot, screen readers cannot navigate the document.
+
+The `idml` gem needs tagged PDF output for:
+- Government documents (Section 508 compliance)
+- Academic publishing (WCAG 2.1 AA)
+- Accessible PDF/A (PDF/A-1a, PDF/A-2a)
+
+## Proposed API
+
+```ruby
+# Build structure tree
+doc.structure.add_element(:H1, text: "Chapter 1", page: 0, mcid: 0)
+doc.structure.add_element(:P, text: "Body text...", page: 0, mcid: 1)
+doc.structure.add_element(:Figure, alt: "Diagram", page: 1, mcid: 2)
+doc.structure.add_element(:TR, children: [
+  doc.structure.element(:TH, text: "Name"),
+  doc.structure.element(:TH, text: "Value"),
+])
+
+# Mark content in the Canvas
+page.canvas.tagged(:H1, mcid: 0) { canvas.text("Chapter 1", ...) }
+page.canvas.tagged(:P, mcid: 1) { canvas.text("Body text...", ...) }
+
+# Build and attach to Catalog
+doc.structure.build!
+```
+
+## PDF structure
+
+```
+/StructTreeRoot
+  /Type /StructTreeRoot
+  /K [ struct_elem_0 struct_elem_1 ... ]
+  /ParentTree << /Nums [ 0 [elem_ref] 1 [elem_ref] ... ] >>
+  /ParentTreeNextKey N
+
+/StructElem (each)
+  /Type /StructElem
+  /S /H1               (structure type: H1, P, Figure, TR, TH, TD, ...)
+  /P struct_tree_root  (parent)
+  /K mcid_or_ref       (content reference)
+  /Pg page_ref         (page containing the content)
+  /Alt (alt text)      (for figures)
+```
+
+## Implementation outline
+
+```ruby
+class Pdfrb::Document
+  class Structure
+    attr_reader :document, :elements
+
+    def initialize(document)
+      @document = document
+      @elements = []
+      @next_mcid = 0
+    end
+
+    def add_element(type, text: nil, alt: nil, page:, mcid:, **opts)
+      elem = StructElement.new(type, text:, alt:, page:, mcid:, **opts)
+      @elements << elem
+      elem
+    end
+
+    def next_mcid
+      id = @next_mcid
+      @next_mcid += 1
+      id
+    end
+
+    # Build /StructTreeRoot and attach to Catalog.
+    def build!
+      return if @elements.empty?
+
+      root_id = allocate_struct_tree_root
+      @elements.each { |e| e.build_object(document, root_id) }
+      build_parent_tree(root_id)
+      document.catalog[:StructTreeRoot] = Pdfrb::Model::Reference.new(root_id)
+      document.catalog[:MarkInfo] = { Type: :MarkInfo, Marked: true }
+    end
+  end
+end
+```
+
+## Priority
+
+Medium — the Canvas already supports marked content (`BMC`/`EMC`), so
+this is the missing piece for full tagged PDF. Not blocking for basic
+rendering but essential for accessibility compliance.

data/PROPOSAL.text-measurement.md

@@ -0,0 +1,93 @@
+# PROPOSAL: Canvas text measurement API
+
+## Summary
+
+Add `Document#fonts#measure_text(text, font:, size:)` returning the
+rendered width in points. Enables callers to do line breaking, text
+centering, and frame-fitting without a separate font metrics library.
+
+## Motivation
+
+The `idml` gem has its own text layout engine (`Idml::TextEngine`) with
+a `FontMetrics` class that reads TTF tables via Fontisan. This is
+necessary because pdfrb doesn't expose text measurement. If pdfrb
+provided this, the idml gem could:
+
+1. Remove the entire `Idml::TextEngine::FontMetrics` class (~200 lines).
+2. Remove the `Fontisan` dependency.
+3. Use pdfrb's own font data (which it already loads for `encode_text`).
+
+## Proposed API
+
+```ruby
+# Measure the rendered width of a text string at a given font and size.
+# @param text [String] the text to measure.
+# @param font [Symbol] font resource name from Fonts#add.
+# @param size [Float] font size in points.
+# @return [Float] width in points.
+def measure_text(text, font:, size:)
+  afm = afm_for_font(font)
+  return 0.0 unless afm
+
+  scale = size / 1000.0
+  text.each_char.sum { |char| (afm.widths[char] || 0) * scale }
+end
+
+# Get font metrics for a registered font.
+# @param font [Symbol] font resource name.
+# @return [Hash] { ascent:, descent:, cap_height:, x_height:, units_per_em: }
+def metrics_for(font)
+  afm = afm_for_font(font)
+  return {} unless afm
+
+  {
+    ascent: afm.ascent,
+    descent: afm.descent,
+    cap_height: afm.cap_height,
+    x_height: afm.x_height,
+    units_per_em: 1000,
+  }
+end
+```
+
+## Implementation notes
+
+pdfrb already loads AFM (Adobe Font Metrics) data for the 14 standard
+Type1 fonts (`AFM_DIR`). For embedded TrueType fonts, the glyph widths
+are in the font's `hmtx` table, which pdfrb parses during font loading.
+
+The `measure_text` method would:
+1. For standard fonts: use AFM width data (already loaded).
+2. For embedded TrueType: use the glyph widths from `hmtx`.
+3. For unknown fonts: return 0.0 or raise.
+
+## Usage example
+
+```ruby
+font = doc.fonts.add("Helvetica")
+width = doc.fonts.measure_text("Hello, World!", font: font, size: 12)
+# => ~63.0 (points)
+
+# Line breaking
+frame_width = 200
+words = text.split
+line = +""
+lines = []
+words.each do |word|
+  test = "#{line} #{word}".strip
+  if doc.fonts.measure_text(test, font: font, size: 12) <= frame_width
+    line = test
+  else
+    lines << line
+    line = word
+  end
+end
+lines << line if line.any?
+```
+
+## Priority
+
+Medium — the idml gem has a workaround (its own FontMetrics), but
+centralizing measurement in pdfrb reduces duplication and eliminates
+the Fontisan dependency for idml consumers who don't need standalone
+font parsing.

data/PROPOSAL.ttf-table-parsing-fix.md

@@ -0,0 +1,112 @@
+# PROPOSAL: Fix TTF table parsing — table() returns raw bytes instead of parsed objects
+
+## Summary
+
+`Pdfrb::Font::TrueType::File#table("cmap")` returns a raw `String` of
+table bytes instead of a parsed table object. This breaks
+`Fonts#glyph_width`, `Fonts#glyph_widths`, `Fonts#measure_text`, and
+`Fonts#extract_ttf_widths` for all TrueType/OpenType fonts.
+
+## Bug description
+
+In `extract_ttf_widths` (fonts.rb:380-400):
+
+```ruby
+ttf = Pdfrb::Font::TrueType::File.new(data)
+cmap = ttf.table("cmap")     # Returns: String (raw bytes)
+hmtx = ttf.table("hmtx")     # Returns: String (raw bytes)
+
+gid = cmap.glyph_id_for(cp)  # ERROR: undefined method 'glyph_id_for' for String
+```
+
+`ttf.table("cmap")` returns the raw binary data of the cmap table as
+a String, not a parsed `CmapTable` object with a `glyph_id_for` method.
+
+## Reproduction
+
+```ruby
+require "pdfrb"
+doc = Pdfrb::Document.new
+font = doc.fonts.add("/System/Library/Fonts/Supplemental/Arial.ttf")
+doc.fonts.glyph_width(font, 65)
+# => 0  (should be ~667 for 'A' in Arial)
+# Warning: pdfrb: could not extract TTF widths: undefined method
+#          'glyph_id_for' for an instance of String
+```
+
+Standard 14 fonts (Helvetica, Times, Courier) work because they use
+AFM data, not TTF parsing.
+
+## Impact
+
+- `glyph_width` / `glyph_widths` return 0 for all TTF/OTF fonts.
+- `measure_text` returns 0 for TTF/OTF text.
+- `metrics_for` returns empty hash for TTF/OTF fonts.
+- Font width arrays in FontDescriptor are empty or wrong.
+- Font embedding (FontFile2) may have incorrect /Widths array.
+
+This blocks the `idml` gem from:
+- Using pdfrb's measurement API (TODO 63)
+- Replacing Fontisan (the idml gem keeps fontisan as a fallback)
+- Producing correct PDFs with embedded TrueType fonts
+
+## Proposed fix
+
+`TrueType::File#table(name)` should return a parsed table object:
+
+```ruby
+class Pdfrb::Font::TrueType::File
+  def table(name)
+    entry = @tables[name]
+    return nil unless entry
+
+    data = @data[entry.offset, entry.length]
+    parse_table(name, data)
+  end
+
+  def parse_table(name, data)
+    case name
+    when "cmap" then CmapTable.new(data)
+    when "hmtx" then HmtxTable.new(data, @num_hmetrics)
+    when "head" then HeadTable.new(data)
+    when "hhea" then HheaTable.new(data)
+    when "name" then NameTable.new(data)
+    else data  # fallback: return raw bytes
+    end
+  end
+end
+
+class CmapTable
+  def initialize(data)
+    @data = data
+    @subtables = parse_subtables(data)
+  end
+
+  def glyph_id_for(codepoint)
+    @subtables.each do |sub|
+      gid = sub.lookup(codepoint)
+      return gid if gid && gid > 0
+    end
+    nil
+  end
+end
+
+class HmtxTable
+  def initialize(data, num_metrics)
+    @widths = []
+    num_metrics.times do |i|
+      @widths[i] = data[i * 4, 2].unpack1("n")
+    end
+  end
+
+  def width_for(glyph_id)
+    @widths[glyph_id] || @widths.last || 0
+  end
+end
+```
+
+## Priority
+
+**Critical** — this is the #1 bug blocking pdfrb adoption for the idml
+gem. Without TTF parsing, glyph widths are wrong, text measurement
+fails, and font embedding produces incorrect PDFs.

data/RELEASE.md

@@ -0,0 +1,48 @@
+# Releasing pdfrb
+
+Releases are driven by git tags. The release workflow is at
+`.github/workflows/release.yml` and runs on tag push (or manual dispatch
+for an existing tag).
+
+## Publish flow
+
+1. Ensure `lib/pdfrb/version.rb` has the target version.
+2. Merge the version-bump change via a PR (never commit directly to main).
+3. When the PR lands, tag the merged commit:
+
+   ```sh
+   git tag v$(ruby -Ilib -e 'require "pdfrb/version"; print Pdfrb::VERSION')
+   git push origin v<VERSION>
+   ```
+
+4. The `Release` workflow fires automatically:
+   - Verifies tag ↔ `lib/pdfrb/version.rb` match.
+   - Builds the gem (`bundle exec rake build`).
+   - Publishes to RubyGems via OIDC trusted publishing (no stored API key).
+   - Creates a GitHub release with auto-generated notes.
+
+## Trusted publishing (OIDC)
+
+The workflow uses `rubygems/configure-rubygems-credentials` with OIDC.
+To enable, on RubyGems:
+
+1. Open the `pdfrb` gem settings.
+2. Add the GitHub workflow as a trusted publisher:
+   - Repository: `claricle/pdfrb`
+   - Workflow filename: `release.yml`
+   - Environment: (leave blank)
+
+Until that is configured, the `Publish to RubyGems` step will fail.
+
+## Manual dispatch
+
+The workflow accepts a `tag` input. Run it from the Actions UI on a
+previously-pushed tag if the auto-trigger missed (e.g., the workflow
+file was added after the tag was pushed).
+
+## Pre-release checklist
+
+- `bundle exec rake` is green.
+- `lib/pdfrb/version.rb` matches the intended tag.
+- `CHANGELOG.md` has an entry for the new version.
+- No uncommitted changes on `main`.

data/lib/pdfrb/action/base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Action
+    # Base action builder. Subclasses define +action_type+ (the /S value)
+    # and +to_pdf+ (type-specific serialization).
+    class Base
+      class << self
+        # @return [Symbol] the /S value (e.g. :GoTo, :URI).
+        def action_type
+          raise NotImplementedError
+        end
+
+        def register_as(name = action_type)
+          Action.register(name, self)
+          self
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/action/types.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Action
+    # Concrete action types (ISO 32000-2 §12.6). Each class defines
+    # its /S value and type-specific fields, then registers itself.
+
+    # GoTo — jump to a destination in the current document. §12.6.4.2
+    class GoTo < Base
+      class << self
+        def action_type; :GoTo; end
+
+        def to_pdf(dest:)
+          { S: :GoTo, D: dest }
+        end
+      end
+      register_as
+    end
+
+    # URI — open a Uniform Resource Identifier. §12.6.4.7
+    class URI < Base
+      class << self
+        def action_type; :URI; end
+
+        def to_pdf(uri:, is_map: false)
+          { S: :URI, URI: uri, IsMap: is_map }.compact
+        end
+      end
+      register_as
+    end
+
+    # Launch — launch an external application. §12.6.4.5
+    class Launch < Base
+      class << self
+        def action_type; :Launch; end
+
+        def to_pdf(file_spec:, new_window: nil)
+          payload = { S: :Launch, F: file_spec }
+          payload[:NewWindow] = new_window unless new_window.nil?
+          payload
+        end
+      end
+      register_as
+    end
+
+    # Named — execute a named action predefined by the viewer. §12.6.4.11
+    class Named < Base
+      class << self
+        def action_type; :Named; end
+
+        def to_pdf(name:)
+          { S: :Named, N: name }
+        end
+      end
+      register_as
+    end
+
+    # GoToR — go to a destination in a remote document. §12.6.4.3
+    class GoToR < Base
+      class << self
+        def action_type; :GoToR; end
+
+        def to_pdf(file_spec:, dest:, new_window: nil)
+          payload = { S: :GoToR, F: file_spec, D: dest }
+          payload[:NewWindow] = new_window unless new_window.nil?
+          payload
+        end
+      end
+      register_as
+    end
+
+    # SubmitForm — submit form data to a URL. §12.7.6.2
+    class SubmitForm < Base
+      class << self
+        def action_type; :SubmitForm; end
+
+        def to_pdf(url:, flags: 0)
+          { S: :SubmitForm, F: url, Flags: flags }
+        end
+      end
+      register_as
+    end
+
+    # ResetForm — reset form fields to defaults. §12.7.6.3
+    class ResetForm < Base
+      class << self
+        def action_type; :ResetForm; end
+
+        def to_pdf(fields: nil, flags: 0)
+          payload = { S: :ResetForm, Flags: flags }
+          payload[:Fields] = fields if fields
+          payload
+        end
+      end
+      register_as
+    end
+
+    # JavaScript — execute JavaScript. §12.6.4.16
+    # NOTE: PDF/A prohibits this; included for completeness.
+    class JavaScript < Base
+      class << self
+        def action_type; :JavaScript; end
+
+        def to_pdf(script:)
+          { S: :JavaScript, JS: script }
+        end
+      end
+      register_as
+    end
+
+    # Hide — show or hide an annotation. §12.6.4.9
+    class Hide < Base
+      class << self
+        def action_type; :Hide; end
+
+        def to_pdf(target:, hide: true)
+          { S: :Hide, T: target, H: hide }
+        end
+      end
+      register_as
+    end
+
+    # ImportData — import FDF/XFDF form data. §12.7.6.4
+    class ImportData < Base
+      class << self
+        def action_type; :ImportData; end
+
+        def to_pdf(file_spec:)
+          { S: :ImportData, F: file_spec }
+        end
+      end
+      register_as
+    end
+
+    # SetOCGState — toggle optional-content groups. §12.6.4.13
+    class SetOCGState < Base
+      class << self
+        def action_type; :SetOCGState; end
+
+        def to_pdf(state:, preserve_rb: false)
+          payload = { S: :SetOCGState, State: state }
+          payload[:PreserveRB] = preserve_rb unless preserve_rb == false
+          payload
+        end
+      end
+      register_as
+    end
+
+    # Trans — page transition for slide-show mode. §12.4.3
+    class Trans < Base
+      class << self
+        def action_type; :Trans; end
+
+        def to_pdf(style:, duration: nil, direction: nil)
+          trans = { S: style }
+          trans[:D] = duration if duration
+          trans[:Di] = direction if direction
+          { S: :Trans, Trans: trans }
+        end
+      end
+      register_as
+    end
+
+    # GoToE — go to a destination in an embedded file. §12.6.4.4 (PDF 1.6+)
+    class GoToE < Base
+      class << self
+        def action_type; :GoToE; end
+
+        def to_pdf(file_spec:, dest:, new_window: nil)
+          payload = { S: :GoToE, F: file_spec, D: dest }
+          payload[:NewWindow] = new_window unless new_window.nil?
+          payload
+        end
+      end
+      register_as
+    end
+  end
+end

data/lib/pdfrb/action.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Actions (ISO 32000-2 §12.6). An action specifies an interactive
+  # behavior: jump to a destination, open a URI, launch an app, etc.
+  #
+  # Each action type is a value object that serializes to a PDF action
+  # dictionary with /S (action type) and type-specific keys.
+  module Action
+    autoload :Base, "pdfrb/action/base"
+    # Each action builder class lives in types.rb but is referenced
+    # directly by callers. Autoload from that file.
+    autoload :GoTo, "pdfrb/action/types"
+    autoload :URI, "pdfrb/action/types"
+    autoload :Launch, "pdfrb/action/types"
+    autoload :Named, "pdfrb/action/types"
+    autoload :GoToR, "pdfrb/action/types"
+    autoload :SubmitForm, "pdfrb/action/types"
+    autoload :ResetForm, "pdfrb/action/types"
+    autoload :JavaScript, "pdfrb/action/types"
+    autoload :Hide, "pdfrb/action/types"
+    autoload :ImportData, "pdfrb/action/types"
+    autoload :SetOCGState, "pdfrb/action/types"
+    autoload :Trans, "pdfrb/action/types"
+    autoload :GoToE, "pdfrb/action/types"
+
+    class << self
+      def registry
+        @registry ||= {}
+      end
+
+      def register(name, klass)
+        registry[name.to_sym] = klass
+      end
+
+      def [](name)
+        key = name.to_sym
+        result = registry[key]
+        return result if result
+
+        # Lazy-load on miss: trigger autoload of GoTo which loads
+        # the entire types.rb file and registers all subtypes.
+        GoTo unless @loaded
+        @loaded = true
+        registry[key]
+      end
+
+      def types
+        GoTo unless @loaded
+        @loaded = true
+        registry.keys
+      end
+    end
+  end
+end