pdfrb 0.2.1 → 0.6.0

data/PROPOSAL.font-embedding-fontfile2.md

@@ -0,0 +1,88 @@
+# PROPOSAL: Font embedding verification and FontFile2 output
+
+## Summary
+
+Ensure `Fonts#add` produces a `/FontFile2` (or `/FontFile3`) stream
+in the output PDF when a TrueType/OpenType font file is passed. Add
+a `Fonts#embedded?` query and log warnings when embedding fails.
+
+## Motivation
+
+The `idml` gem registers document fonts via `document.fonts.add(path)`.
+The returned resource name works for `canvas.text`, but the output PDF
+does not contain `/FontFile2`. This means:
+- Text renders correctly only on systems with the font installed.
+- The PDF is not self-contained.
+- PDF/A compliance (which requires all fonts embedded) is impossible.
+
+Testing with `/System/Library/Fonts/Supplemental/Arial.ttf`:
+```ruby
+doc = Pdfrb::Document.new
+doc.fonts.add("/System/Library/Fonts/Supplemental/Arial.ttf")
+# Output PDF has /BaseFont but no /FontFile2
+```
+
+## Root cause analysis
+
+Looking at `Fonts#add`, the code path for TrueType fonts calls
+`register_font(resource, name, name_or_io, **opts)`. This method
+may not be creating the FontDescriptor + FontFile2 objects for
+all font types. The standard 14 Type1 fonts don't need embedding,
+but TrueType (.ttf) and OpenType (.otf) files should be embedded
+as FontFile2 / FontFile3 respectively.
+
+## Proposed changes
+
+### 1. Ensure FontFile2 for TrueType
+
+When `name_or_io` is a `.ttf` file path or IO:
+1. Read the font data.
+2. Create a stream object with the raw TTF bytes.
+3. Create a FontDescriptor with `/FontFile2` pointing to the stream.
+4. Set the Font dictionary's `/FontDescriptor` to the FontDescriptor.
+
+### 2. Add `Fonts#embedded?(resource)` query
+
+```ruby
+def embedded?(resource)
+  entry = @font_entries[resource]
+  return false unless entry
+
+  entry[:font_descriptor]&.value&.key?(:FontFile2) ||
+    entry[:font_descriptor]&.value&.key?(:FontFile3)
+end
+```
+
+### 3. Log warning on embedding failure
+
+When embedding is requested but fails (corrupt font, unsupported
+format), log a warning:
+
+```ruby
+Pdfrb.logger.warn("Failed to embed font #{name}: #{e.message}")
+```
+
+### 4. Font subsetting (stretch goal)
+
+Embed only the glyphs actually used:
+1. Collect used codepoints from `encode_text` calls.
+2. Subset the TTF using a glyph table parser.
+3. Embed the subsetted font as FontFile2.
+
+This reduces a 500KB font to ~5-20KB in the PDF.
+
+## Usage example
+
+```ruby
+font = doc.fonts.add("/path/to/MinionPro-Regular.otf")
+doc.fonts.embedded?(font)  # => true (after this proposal)
+
+page = doc.pages.add
+page.canvas.text("Hello", at: [72, 720], font: font, size: 12)
+# PDF now contains /FontFile2 with the font data
+```
+
+## Priority
+
+High — without font embedding, the PDF is not portable. This is the
+#1 gap for the idml gem's rendering pipeline.

data/PROPOSAL.font-resolver-ttc.md

@@ -0,0 +1,105 @@
+# PROPOSAL: FontResolver .ttc (TrueType Collection) support
+
+## Summary
+
+`Pdfrb::FontResolver` doesn't search for `.ttc` (TrueType Collection)
+files. On macOS, many common fonts (Helvetica, Times New Roman, Courier,
+Arial Unicode) are stored exclusively as `.ttc`. Without `.ttc` support,
+the resolver returns `nil` for these fonts.
+
+## Bug description
+
+In `build_cache` (font_resolver.rb):
+
+```ruby
+Dir.glob("**/*.{ttf,otf}", base: dir).each do |rel_path|
+```
+
+The glob only matches `.ttf` and `.otf` files — `.ttc` is excluded.
+
+## Reproduction
+
+```ruby
+resolver = Pdfrb::FontResolver.new
+resolver.find(family: "Helvetica", style: "Regular")
+# => nil  (should find /System/Library/Fonts/Helvetica.ttc)
+```
+
+On macOS:
+- Helvetica is at `/System/Library/Fonts/Helvetica.ttc`
+- Times New Roman is at `/System/Library/Fonts/Times New Roman.ttf` (works)
+- Arial Unicode MS is at `/System/Library/Fonts/Supplemental/Arial Unicode.ttf` (works)
+- Many system fonts are `.ttc` only
+
+## Impact
+
+The `idml` gem cannot use `Pdfrb::FontResolver` on macOS because many
+fonts are `.ttc` only. It keeps the `Fontisan`-based resolver as a
+fallback.
+
+## Proposed fix
+
+### 1. Add `.ttc` to glob
+
+```ruby
+Dir.glob("**/*.{ttf,otf,ttc}", base: dir).each do |rel_path|
+```
+
+### 2. Parse .ttc files
+
+A `.ttc` file contains multiple fonts. The TTC header lists the offset
+of each font's data within the file:
+
+```
+TTC Header:
+  Tag: "ttcf"
+  MajorVersion, MinorVersion
+  numFonts: N
+  offsetTable[N]: offsets to each font's data
+
+Each font at its offset has a standard TTF/OTF structure.
+```
+
+For each `.ttc` file, parse the TTC header and iterate each font:
+
+```ruby
+def parse_font_info(path)
+  data = File.binread(path)
+  if data[0, 4] == "ttcf"
+    parse_ttc(path, data)
+  else
+    parse_ttf(path, data)  # existing single-font parsing
+  end
+end
+
+def parse_ttc(path, data)
+  results = []
+  num_fonts = data[8, 4].unpack1("N")
+  num_fonts.times do |i|
+    offset = data[12 + i * 4, 4].unpack1("N")
+    info = parse_ttf_at_offset(path, data, offset)
+    results << info if info
+  end
+  results
+end
+```
+
+### 3. Register fonts from .ttc with Fonts#add
+
+When registering a font from a `.ttc` file, the caller should specify
+which font within the collection:
+
+```ruby
+# Option A: FontResolver returns the .ttc path + index
+resolver.find(family: "Helvetica", style: "Regular")
+# => { path: "/System/Library/Fonts/Helvetica.ttc", index: 0 }
+
+# Option B: Fonts#add accepts a collection index
+doc.fonts.add("/path/to/Helvetica.ttc", collection_index: 0)
+```
+
+## Priority
+
+High — macOS is a primary development platform for the idml gem.
+Without `.ttc` support, pdfrb's FontResolver is unusable on macOS for
+common fonts.

data/PROPOSAL.font-resolver.md

@@ -0,0 +1,96 @@
+# PROPOSAL: Font file resolver
+
+## Summary
+
+Add `Pdfrb::FontResolver` that searches system font directories for
+font files by family name + style. Eliminates the need for external
+font-finding libraries (like `fontisan` in the `idml` gem).
+
+## Motivation
+
+The `idml` gem uses `Fontisan` to:
+1. Search `/System/Library/Fonts`, `/Library/Fonts`, `~/Library/Fonts`,
+   `/usr/share/fonts`, `~/.local/share/fonts` for `.ttf`/`.otf` files.
+2. Parse each file's `name` table to get PostScript name, family name,
+   style name.
+3. Match by family + style (e.g., "Minion Pro" + "Regular" →
+   "MinionPro-Regular").
+4. Return the file path.
+
+This is ~100 lines of `fontisan`-dependent code. If pdfrb provided font
+resolution, the `idml` gem could drop the `fontisan` dependency entirely.
+
+## Proposed API
+
+```ruby
+module Pdfrb
+  class FontResolver
+    DEFAULT_SEARCH_PATHS = [
+      "/System/Library/Fonts",
+      "/Library/Fonts",
+      File.expand_path("~/Library/Fonts"),
+      "/usr/share/fonts",
+      File.expand_path("~/.local/share/fonts"),
+    ].freeze
+
+    # @param search_paths [Array<String>] directories to search.
+    def initialize(search_paths: DEFAULT_SEARCH_PATHS)
+    end
+
+    # Find a font file by family name and optional style.
+    # @param family [String] e.g., "Arial", "Minion Pro"
+    # @param style [String] e.g., "Regular", "Bold", "Italic"
+    # @return [String, nil] file path, or nil if not found.
+    def find(family:, style: "Regular")
+    end
+
+    # Find by PostScript name (exact match).
+    # @param ps_name [String] e.g., "ArialMT", "MinionPro-Regular"
+    # @return [String, nil] file path.
+    def find_by_ps_name(ps_name)
+    end
+
+    # List all available font files in search paths.
+    # @return [Array<Hash>] [{ path:, family:, style:, ps_name: }, ...]
+    def available_fonts
+    end
+  end
+end
+```
+
+## Implementation notes
+
+pdfrb already parses font `name` tables during `Fonts#add`. The resolver
+would:
+
+1. Glob `**/*.{ttf,otf,ttc}` in each search path.
+2. For each file, parse the `name` table to get family/style/PS name.
+3. Cache results (font directory scanning is expensive).
+4. Match by family + style with fuzzy matching (e.g., "Bold Italic"
+   matches "BoldItalic").
+
+For `.ttc` (TrueType Collection) files, each file contains multiple
+fonts. The resolver should iterate all fonts within the collection.
+
+Platform-specific paths:
+- macOS: `/System/Library/Fonts`, `/Library/Fonts`, `~/Library/Fonts`
+- Linux: `/usr/share/fonts`, `/usr/local/share/fonts`, `~/.local/share/fonts`, `~/.fonts`
+- Windows: `C:\Windows\Fonts`
+
+## Usage example
+
+```ruby
+resolver = Pdfrb::FontResolver.new
+path = resolver.find(family: "Minion Pro", style: "Regular")
+# => "/Library/Fonts/MinionPro-Regular.otf"
+
+font = doc.fonts.add(path)
+page = doc.pages.add
+page.canvas.text("Hello", at: [72, 720], font: font, size: 12)
+```
+
+## Priority
+
+Medium — eliminates the `fontisan` dependency for pdfrb consumers.
+The `idml` gem's entire `FontResolver` + `FontMetrics` classes
+(~300 lines) could be replaced by pdfrb's resolver + measurement.

data/PROPOSAL.font-subsetting.md

@@ -0,0 +1,98 @@
+# PROPOSAL: Font subsetting via used_codepoints
+
+## Summary
+
+Automatically subset embedded TrueType/OpenType fonts to include only
+the glyphs actually used in the document. pdfrb 0.18.0 already tracks
+`Fonts#used_codepoints` — extend this to drive the font subsetting
+during serialization.
+
+## Motivation
+
+The `idml` gem embeds document fonts via `Fonts#add`. Without subsetting,
+a 500KB Minion Pro font is embedded in full, even if only 50 glyphs are
+used. Subsetting reduces this to ~5-15KB — a 30-100× reduction.
+
+This is critical for:
+- Web PDFs (smaller download)
+- Email attachments (size limits)
+- PDF/A compliance (font embedding is mandatory, but subsetting is best practice)
+- Batch processing (many small PDFs)
+
+## Current state in pdfrb 0.18.0
+
+- `Fonts#used_codepoints` — tracks which Unicode codepoints have been
+  encoded via `encode_text`. ✓
+- `Fonts#embedded?` — checks if a font has FontFile2. ✓
+- `Fonts#add` — registers fonts but may not subset by default.
+
+## Proposed changes
+
+### 1. Automatic subsetting on write
+
+When `Document#write` serializes the PDF, for each embedded TrueType
+font:
+
+1. Get `used_codepoints` for the font resource.
+2. Parse the TTF/OTF file's `glyf` (TrueType) or `CFF` (OpenType) table.
+3. Build the glyph closure: used glyphs + their component glyphs
+   (for composite glyphs) + `.notdef`.
+4. Rebuild the font tables with only the needed glyphs.
+5. Write the subsetted font as the FontFile2 stream.
+
+### 2. Opt-in flag
+
+```ruby
+font = doc.fonts.add("/path/to/font.ttf", subset: true)
+# ... render text ...
+doc.write("output.pdf")  # FontFile2 contains only used glyphs
+```
+
+Default: `subset: true` (most callers want subsetting).
+
+### 3. Subset prefix
+
+Subsetting conventions use a 6-character uppercase prefix + `+` before
+the font name (e.g., `ABCDEF+MinionPro-Regular`). This signals to PDF
+processors that the font is a subset.
+
+```ruby
+# In the /BaseFont entry:
+/BaseFont /ABCDEF+MinionPro-Regular
+```
+
+### 4. Fallback for invalid fonts
+
+If subsetting fails (corrupt font, unsupported table structure), fall
+back to full embedding and log a warning.
+
+## Implementation notes
+
+TrueType subsetting algorithm:
+1. Collect used codepoint → glyph ID mappings from `cmap`.
+2. Expand glyph closure: for each glyph, check if it's a composite
+   (`.ttf` glyf table with `GF_COMPONENT` flag). Add component glyphs.
+3. Rebuild `glyf`, `loca`, `maxp`, `hmtx`, `hhea`, `cmap`, `name`
+   tables with only the needed glyphs.
+4. Recompute checksums.
+
+OpenType/CFF subsetting is more complex (CharStrings, Private DICT,
+FDArray). Consider using a library like `ttf-rb` or porting the
+algorithm from `fontTools.subset` (Python).
+
+## Usage example
+
+```ruby
+doc = Pdfrb::Document.new
+font = doc.fonts.add("/path/to/MinionPro-Regular.otf")
+page = doc.pages.add
+page.canvas.text("Hello, World!", at: [72, 720], font: font, size: 12)
+doc.write("output.pdf")
+# Only H, e, l, o, comma, space, W, r, d, ! glyphs are embedded
+```
+
+## Priority
+
+High — font subsetting is the #1 remaining gap for production-quality
+PDF output. Without it, every idml-generated PDF is 300-500KB larger
+than necessary.

data/PROPOSAL.gradient-shadings.md

@@ -0,0 +1,110 @@
+# PROPOSAL: Gradient shading patterns
+
+## Summary
+
+Add `Document#shadings` facade and `Canvas#fill_shading(name)` /
+`Canvas#stroke_shading(name)` for PDF Type 2 (axial) and Type 3 (radial)
+gradient shading patterns. Replaces the discrete-rectangle approximation
+used by the `idml` gem.
+
+## Motivation
+
+The `idml` gem renders IDML gradient fills as 32 discrete colored
+rectangles (a "staircase" approximation). This produces visible banding
+and a larger file size than a proper PDF shading pattern.
+
+PDF natively supports smooth gradients via shading dictionaries:
+- **Type 2 (Axial)**: linear gradient between two points.
+- **Type 3 (Radial)**: circular gradient between two circles.
+- **Type 4–7 (Free-form, Coons, Tensor-product)**: complex meshes.
+
+A proper shading pattern produces a mathematically smooth gradient with
+zero banding.
+
+## Proposed API
+
+```ruby
+module Pdfrb
+  class Document
+    class Shadings
+      # Add an axial (linear) gradient.
+      # @param from [Array(Numeric, Numeric)] start point [x, y].
+      # @param to [Array(Numeric, Numeric)] end point [x, y].
+      # @param stops [Array<Array>] gradient stops:
+      #   [[offset, [color_family, *values]], ...]
+      #   e.g., [[0.0, [:rgb, 1, 0, 0]], [1.0, [:rgb, 0, 0, 1]]]
+      # @return [Symbol] shading resource name (e.g., :Sh1).
+      def add_axial(from:, to:, stops:)
+      end
+
+      # Add a radial gradient.
+      # @param from [Array(Numeric, Numeric, Numeric)] [cx, cy, radius].
+      # @param to [Array(Numeric, Numeric, Numeric)] [cx, cy, radius].
+      # @param stops [Array<Array>] same format as axial.
+      # @return [Symbol] shading resource name.
+      def add_radial(from:, to:, stops:)
+      end
+
+      def [](name); end
+      def each(&block); end
+    end
+  end
+end
+```
+
+```ruby
+class Pdfrb::Content::Canvas
+  # Fill the current path using a shading pattern.
+  # @param name [Symbol] shading resource name from Shadings#add_axial.
+  def fill_shading(name)
+    emit_op(Operator::ShadingFill, name)
+  end
+end
+```
+
+## PDF structure
+
+```
+/Shading << /Sh1 << /Type /Shading /ShadingType 2
+  /ColorSpace /DeviceRGB
+  /Coords [x0 y0 x1 y1]
+  /Function << /FunctionType 4 /Domain [0 1]
+    /Range [0 1 0 1 0 1]
+    /Length N >> stream { ... PostScript calculator ... } endstream
+>> >>
+```
+
+For simple 2-stop gradients, a Type 2 ExponentialInterpolation
+function is simpler:
+
+```
+/Function << /FunctionType 2 /Domain [0 1]
+  /C0 [1 0 0] /C1 [0 0 1] /N 1 >>
+```
+
+## Usage example
+
+```ruby
+shading = doc.shadings.add_axial(
+  from: [0, 0], to: [200, 0],
+  stops: [[0.0, [:rgb, 1, 0, 0]], [1.0, [:rgb, 0, 0, 1]]]
+)
+page.canvas.rectangle(0, 0, 200, 100)
+page.canvas.fill_shading(shading)
+```
+
+## Implementation notes
+
+- Shadings need to be in `/Resources/Shading` on each page (or in the
+  catalog for document-wide).
+- Multi-stop gradients require a StitchingFunction (Type 3) that
+  chains multiple Type 2 interpolation functions.
+- For color spaces, support DeviceRGB, DeviceCMYK, and DeviceGray.
+- The `sh` operator (shading fill) ignores the current path — it fills
+  the entire shading clip area. To clip to a shape, use the path as a
+  clip before `sh`.
+
+## Priority
+
+Medium — gradients are a visual quality issue, not a correctness issue.
+The discrete approximation works but produces visible banding.

data/PROPOSAL.page-mediabox-setter.md

@@ -0,0 +1,66 @@
+# PROPOSAL: Page MediaBox setter
+
+## Summary
+
+Add `Page#media_box=` setter method so pages can have custom dimensions
+without accessing the COS dictionary directly.
+
+## Motivation
+
+The `idml` gem renders IDML documents with arbitrary page sizes (A4,
+business card, poster, etc.). pdfrb defaults to US Letter (612×792).
+Currently, setting a custom MediaBox requires:
+
+```ruby
+page = document.pages.add
+page[:"MediaBox"] = [0, 0, width, height]  # COS dict access
+```
+
+This is fragile — it bypasses pdfrb's model layer and couples the caller
+to COS internals. A proper setter provides a clean, model-driven API.
+
+## Proposed API
+
+```ruby
+class Pdfrb::Model::Type::Page
+  # Set the page's MediaBox.
+  # @param box [Array<Numeric>] [llx, lly, urx, ury] in PDF points.
+  def media_box=(box)
+    self[:"MediaBox"] = box
+  end
+end
+```
+
+Alternatively, support it at creation time:
+
+```ruby
+# In Pages#add
+def add(width: 612, height: 792, **opts)
+  page = super(**opts)
+  page.media_box = [0, 0, width, height] unless width == 612 && height == 792
+  page
+end
+```
+
+## Usage example
+
+```ruby
+# A4 portrait
+page = document.pages.add
+page.media_box = [0, 0, 595, 842]
+
+# Custom size via creation
+page = document.pages.add(width: 595, height: 842)
+```
+
+## Implementation notes
+
+- The reader method `media_box` already exists.
+- The setter is a one-liner delegating to `self[:"MediaBox"]=`.
+- The COS dict `[]=` is public (inherited from Cos::Dictionary).
+- No validation needed at this level — callers pass valid rectangles.
+
+## Priority
+
+Low — workaround exists via `page[:"MediaBox"] = [...]`. But a proper
+setter improves API cleanliness and discoverability.

data/PROPOSAL.per-glyph-width.md

@@ -0,0 +1,91 @@
+# PROPOSAL: Per-glyph width measurement
+
+## Summary
+
+Add `Fonts#glyph_width(font, codepoint)` and `Fonts#glyph_widths(font,
+codepoints)` for measuring individual glyph advance widths. Enables
+text layout engines to do per-character shaping without parsing font
+binary tables externally.
+
+## Motivation
+
+The `idml` gem has its own text layout engine (`Idml::TextEngine`) that
+shapes text character-by-character via a `FontMetrics#glyph_width(cp)`
+method. This requires parsing the TTF `hmtx` table via the `fontisan`
+gem (~200 lines of binary parsing code).
+
+pdfrb 0.18.0 has `Fonts#measure_text(text, font:, size:)` which measures
+a full string. But for line breaking, the layout engine needs per-glyph
+widths to know where word boundaries fall and how to distribute space
+across justified lines.
+
+## Proposed API
+
+```ruby
+# Measure the advance width of a single glyph at size 1000 (font units).
+# @param font [Symbol] font resource name.
+# @param codepoint [Integer] Unicode codepoint.
+# @return [Integer] advance width in font units (not scaled by size).
+def glyph_width(font, codepoint)
+  # Look up glyph ID from cmap, then width from hmtx.
+end
+
+# Measure advance widths for multiple codepoints in one call.
+# @param font [Symbol] font resource name.
+# @param codepoints [Array<Integer>] Unicode codepoints.
+# @return [Array<Integer>] widths in font units, one per codepoint.
+def glyph_widths(font, codepoints)
+  codepoints.map { |cp| glyph_width(font, cp) }
+end
+```
+
+## Why not just measure_text per character?
+
+`measure_text(char, font:, size:)` works but:
+1. It returns a scaled `Float` (width in points at the given size).
+   The layout engine needs unscaled `Integer` widths (font units) to
+   avoid floating-point accumulation errors across many glyphs.
+2. It's slower — each call goes through the full encoding + metrics
+   pipeline. A batch `glyph_widths` call is more efficient.
+3. It doesn't distinguish between "glyph not found" (width 0) and
+   "glyph has width 0" (like space in some fonts).
+
+## Implementation notes
+
+pdfrb already parses the `cmap` and `hmtx` tables during font loading
+(for `encode_text` and `measure_text`). The glyph width data is in
+memory — `glyph_width` just needs to expose it.
+
+For the 14 standard Type1 fonts, AFM data already has per-glyph widths.
+For embedded TrueType/OpenType, the `hmtx` table has advance widths
+indexed by glyph ID.
+
+```ruby
+def glyph_width(font, codepoint)
+  font_data = font_data_for(font)
+  return 0 unless font_data
+
+  glyph_id = font_data.cmap_lookup(codepoint)
+  font_data.advance_width(glyph_id)
+end
+```
+
+## Usage example
+
+```ruby
+font = doc.fonts.add("/path/to/Arial.ttf")
+
+# Per-glyph widths for line breaking
+widths = doc.fonts.glyph_widths(font, "Hello World".each_codepoint.to_a)
+# => [722, 556, 556, 556, 277, 0, 667, 556, 722, 556, 500]
+
+# Text layout engine uses these for word-wrap
+total = widths.sum  # => 5661 font units
+width_at_12pt = total * 12.0 / 1000  # => 67.9 points
+```
+
+## Priority
+
+Medium — `measure_text` is a workaround, but per-glyph widths eliminate
+the need for `fontisan` in the `idml` gem and enable faster, more
+accurate text layout.