pdfrb 0.3.0 → 0.7.1

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,61 @@
+# Releasing pdfrb
+
+Releases are driven by the Metanorma CI reusable workflow at
+`.github/workflows/release.yml`. It supports two triggers:
+
+1. **`workflow_dispatch`** with a `next_version` input — manual run
+   from the Actions UI. Accepted values: `x.y.z`, `major`, `minor`,
+   `patch`, or `pre|rc|etc` to bump to a prerelease.
+2. **`repository_dispatch`** with event type `do-release` — for
+   automation triggers from other repos.
+
+Both call
+[`metanorma/ci/.github/workflows/rubygems-release.yml@main`](https://github.com/metanorma/ci/blob/main/.github/workflows/rubygems-release.yml),
+which handles version bumping, tag creation, gem build, RubyGems
+publish, and GitHub release creation.
+
+## Required secrets
+
+* `CLARICLE_CI_RUBYGEMS_API_KEY` — RubyGems API key with `push`
+  permission on the `pdfrb` gem. Set in repo Settings → Secrets and
+  Variables → Actions.
+* `GITHUB_TOKEN` — automatic; used for creating the GitHub release.
+
+## Triggering a release
+
+### From the Actions UI
+
+1. Go to Actions → `release` workflow.
+2. Click "Run workflow".
+3. Enter the next version (e.g., `0.7.0`, `patch`, `minor`, `major`).
+4. Click "Run workflow".
+
+### From the API / CI
+
+```sh
+gh workflow run release.yml \
+  -f next_version=0.7.0
+```
+
+Or via `repository_dispatch` from another repo:
+
+```sh
+gh api /repos/claricle/pdfrb/dispatches \
+  -f event_type=do-release \
+  -f 'client_payload[next_version]=0.7.0'
+```
+
+## CI (test) workflow
+
+`.github/workflows/rake.yml` runs the standard Metanorma CI
+generic-rake workflow on every push to `main`/`master`, every tag
+push, every pull request, and via manual `workflow_dispatch`. It
+fires the test matrix across supported Ruby versions.
+
+## Pre-release checklist
+
+* `bundle exec rake` is green locally.
+* `lib/pdfrb/version.rb` matches the intended release (the release
+  workflow handles this automatically when given `next_version`).
+* `CHANGELOG.md` has an entry for the new version.
+* No uncommitted changes on `main`.