pdfrb 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04b26536220e55c3be57627ba747561baeee1d58f37e57a2f68f5f121ec1381c
-  data.tar.gz: 7a3f7a5a10b43e253e34bb5551042db89e3d94694a568beee186c2995fefe867
+  metadata.gz: 6f24b6c90eb4e01436139908a7aaa0472ed8a22704e40e934f651c0265763d62
+  data.tar.gz: da4e7fc8a4f9c4cecbbf22ca2ab2288ca8f07c4bc974dc6eac8b2166fb784d94
 SHA512:
-  metadata.gz: 70ec6abd4b94413e5cfcf1c18b4437332fc84c38262bc58347c3b55b354416cbf4f1ecfe24995dfeea12776306e8c07b1acdddd0d96b64e572bc82d60ed629df
-  data.tar.gz: 35daa8aa6439430f7d6dbc043777bc969f0844a14dd503650076fe5ffc9edd03859f22f64a3b3d290cc84eb10774589dca52c7138fc4b102bfab660692fb4461
+  metadata.gz: 550b8e52600d4ebe1cffbce341d0725d750a41ba8585c1b85c827f9c7a4b6fda7e24d6dd6f3c2ed6f5f83e442729e792f3fef05a9d34459118a9720d039bf3bb
+  data.tar.gz: c950a24d0cf3af6734edbe2819d0390c07442fa941e026be4744fb6db0e02beadc4e3d2ac220fbb5d4f52eee67bc3e9d19e03602dabaaefdf65929ecbe1a61d3

data/.rubocop.yml

@@ -12,7 +12,7 @@ plugins:
   - rubocop-rake
 
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.2
   NewCops: enable
   Exclude:
     - "data/**/*"

data/Gemfile

@@ -12,4 +12,5 @@ gem "rubocop-performance", "~> 1.23"
 gem "rubocop-rake", "~> 0.7"
 gem "rubocop-rspec", "~> 3.5"
 
+gem "lutaml-model", "~> 0.8"
 gem "simplecov", require: false, group: :test

data/PROPOSAL.canvas-clip.md

@@ -0,0 +1,92 @@
+# PROPOSAL: Canvas clip operators
+
+## Summary
+
+Add `Canvas#clip` and `Canvas#clip_path` methods for PDF clipping path
+operators (`W`, `W*`, `n`), enabling content to be clipped to arbitrary
+paths.
+
+## Motivation
+
+The IDML→PDF rendering pipeline (the `idml` gem) needs to clip placed
+images to their parent Rectangle's bounds. Currently, pdfrb 0.3.0 has
+no clip operator on Canvas. The `idml` gem implements a workaround via
+`PdfrbExt::Clip` (custom `Operator::Base` subclass), but this belongs
+in pdfrb itself.
+
+Other use cases:
+- Clipping text frames to their bounds
+- Masking layers
+- Cropping form XObjects
+- Print marks (crop/bleed/trim)
+
+## Proposed API
+
+```ruby
+# Set clipping path using nonzero winding rule.
+# Must be called after defining a path (rectangle, move_to/line_to, etc.)
+# and before drawing content that should be clipped.
+# The clip persists until the graphics state is restored (Q).
+def clip
+  emit_op(Operator::ClipNonZero)
+  emit_op(Operator::EndPath)
+  self
+end
+
+# Set clipping path using even-odd rule.
+def clip_even_odd
+  emit_op(Operator::ClipEvenOdd)
+  emit_op(Operator::EndPath)
+  self
+end
+```
+
+## Operator classes to add
+
+```ruby
+module Pdfrb::Content::Operator
+  # PDF `W` — modify clipping path (nonzero winding)
+  class ClipNonZero < NoArg
+    def self.name; "W"; end
+    register
+  end
+
+  # PDF `W*` — modify clipping path (even-odd)
+  class ClipEvenOdd < NoArg
+    def self.name; "W*"; end
+    register
+  end
+
+  # PDF `n` — end path without filling or stroking
+  class EndPath < NoArg
+    def self.name; "n"; end
+    register
+  end
+end
+```
+
+## Usage example
+
+```ruby
+canvas.save_graphics_state do
+  canvas.rectangle(100, 100, 200, 200)
+  canvas.clip  # clip to the rectangle
+  canvas.draw_image(:Im1, at: [50, 50], width: 300, height: 300)
+end
+```
+
+## Implementation notes
+
+- `W` and `W*` are technically not no-arg operators in the strict PDF
+  sense — they are modifiers applied to the current path. But since they
+  take no operands, `NoArg` is the correct base class.
+- `n` is already listed as `EndPath` in the operator module but may not
+  be registered. If it is, `Canvas#end_path` already exists and can be
+  reused.
+- The `clip` method should call `end_path` after `W`/`W*` to consume
+  the path, matching the common `W n` idiom.
+
+## Priority
+
+Medium — commonly needed for any PDF rendering pipeline that places
+images or text within geometric frames.

data/PROPOSAL.canvas-draw-image-matrix.md

@@ -0,0 +1,87 @@
+# PROPOSAL: Canvas draw_image with transform matrix
+
+## Summary
+
+Add `Canvas#draw_image_matrix(name, a:, b:, c:, d:, e:, f:)` for drawing
+image XObjects with an arbitrary affine transform matrix, complementing
+the existing `Canvas#draw_image(name, at:, width:, height:)` which only
+supports position + uniform scale.
+
+## Motivation
+
+The `idml` gem places images using IDML's `ItemTransform` — a full 2D
+affine matrix `a b c d e f` that includes non-uniform scaling, rotation,
+and translation. The current `draw_image` only accepts `at: [x, y]` and
+`width:, height:`, which can't express rotation or skew.
+
+Currently the `idml` gem works around this by emitting raw operators:
+
+```ruby
+canvas.concat(scale_x, 0, 0, scale_y, x, y)
+canvas.emit_op(PdfrbExt::InvokeXObject, name)
+```
+
+This works but bypasses pdfrb's Canvas abstraction. A proper API method
+would be cleaner and more discoverable.
+
+## Proposed API
+
+```ruby
+# Draw an image XObject with a full affine transform matrix.
+# The matrix maps the image's unit square (0,0)-(1,1) to the
+# destination rectangle on the page.
+#
+# @param name [Symbol] image resource name from Document#images#add.
+# @param a, b, c, d, e, f [Numeric] affine matrix components.
+#
+# Example: scale 200×150 and place at (72, 300):
+#   canvas.draw_image_matrix(:Im1, a: 200, b: 0, c: 0, d: 150, e: 72, f: 300)
+#
+# Example: rotate 45° and scale:
+#   rad = 45 * Math::PI / 180
+#   cos = Math.cos(rad)
+#   sin = Math.sin(rad)
+#   canvas.draw_image_matrix(:Im1, a: cos*200, b: sin*200, c: -sin*150, d: cos*150, e: 100, f: 400)
+def draw_image_matrix(name, a:, b:, c:, d:, e:, f:)
+  save_graphics_state do
+    concat(a, b, c, d, e, f)
+    emit_op(Operator::InvokeXObject, name)
+  end
+  self
+end
+```
+
+## Alternative: extend draw_image
+
+```ruby
+def draw_image(name, at: nil, width: nil, height: nil, matrix: nil)
+  if matrix
+    a, b, c, d, e, f = matrix
+    save_graphics_state { concat(a, b, c, d, e, f); emit_op(Operator::InvokeXObject, name) }
+  else
+    # existing at:/width:/height: behavior
+  end
+end
+```
+
+## Register InvokeXObject operator
+
+This proposal also requires registering the `Do` (Invoke XObject)
+operator in pdfrb's operator catalogue:
+
+```ruby
+module Pdfrb::Content::Operator
+  class InvokeXObject < Base
+    class << self
+      def name; "Do"; end
+      def serialize(serializer, name); "/#{name} Do\n"; end
+    end
+    register
+  end
+end
+```
+
+## Priority
+
+Medium — the `idml` gem has a workaround via PdfrbExt, but pdfrb should
+have the `Do` operator and a matrix-aware image drawing method built-in.

data/PROPOSAL.canvas-rich-text.md

@@ -0,0 +1,103 @@
+# PROPOSAL: Canvas rich text — multi-run text in one BT/ET block
+
+## Summary
+
+Add `Canvas#text_rich(runs, at:)` for drawing text with per-run font,
+size, color, and positioning. Eliminates the need for N separate
+`text` calls when a paragraph contains mixed styling (e.g., bold word
+within regular text, different font sizes, color changes).
+
+## Motivation
+
+The `idml` gem's `TextFrameRenderer` renders styled text from IDML
+documents where a single paragraph can contain multiple
+`CharacterStyleRange` runs — each with its own font, size, and color.
+Currently, each run requires a separate `canvas.text` call (separate
+BT/ET block), which:
+
+1. Produces a larger content stream (more BT/ET pairs).
+2. Loses cursor continuity — the caller must compute the x-offset
+   after each run manually.
+3. Can't use `TJ` (array show) for kerning between runs.
+
+## Proposed API
+
+```ruby
+# Draw multiple text runs in a single BT/ET block with cursor
+# tracking. Each run advances the text cursor by its width.
+#
+# @param runs [Array<Hash>] each hash has:
+#   :text [String] the text to show.
+#   :font [Symbol] font resource name.
+#   :size [Float] font size in points.
+#   :color [Array, nil] optional fill color (e.g., [:rgb, 1, 0, 0]).
+#   :char_spacing [Float, nil] optional character spacing.
+# @param at [Array(Numeric, Numeric)] [x, y] of the first run's baseline.
+#
+# Example:
+#   canvas.text_rich([
+#     { text: "Hello ", font: :F1, size: 12 },
+#     { text: "World", font: :F1, size: 12, color: [:rgb, 1, 0, 0] },
+#     { text: "!", font: :F1, size: 14 },
+#   ], at: [72, 720])
+def text_rich(runs, at:)
+  emit_op Operator::BeginText
+  cursor_x, cursor_y = at
+
+  runs.each do |run|
+    emit_op Operator::Font, run[:font], run[:size]
+    emit_op Operator::SetTextMatrix, 1, 0, 0, 1, cursor_x, cursor_y
+    if run[:color]
+      fill_color(run[:color])
+    end
+    encoded = document.fonts.encode_text(run[:text], run[:font])
+    width = document.fonts.measure_text(run[:text],
+                                        font: run[:font],
+                                        size: run[:size])
+    emit_op Operator::ShowText, escape_pdf_string(encoded)
+    cursor_x += width
+  end
+
+  emit_op Operator::EndText
+  self
+end
+```
+
+## Alternative: TJ (array show) optimization
+
+For runs with the same font and size, use `TJ` to show text with
+positioning adjustments in a single operator:
+
+```
+[(Hel) -50 (lo W) 20 (orld!)] TJ
+```
+
+This enables kerning between runs and reduces operator count. But it
+requires all runs to use the same font/size, which limits its use.
+
+## Implementation notes
+
+- `text_rich` uses `SetFont` (Tf) per run to switch fonts within the
+  same BT/ET block. This is valid PDF — Tf can be called multiple times.
+- Color changes use `SetFillColor` (rg/k) between runs.
+- `SetTextMatrix` (Tm) positions each run at the absolute cursor.
+- The cursor advances by `measure_text(run[:text], ...)` after each run.
+
+## Usage example
+
+```ruby
+# Render a paragraph with mixed styling
+canvas.text_rich([
+  { text: "This is ", font: :F1, size: 12 },
+  { text: "bold", font: :F2, size: 12 },       # F2 = bold variant
+  { text: " text in ", font: :F1, size: 12 },
+  { text: "red", font: :F1, size: 12, color: [:rgb, 1, 0, 0] },
+  { text: ".", font: :F1, size: 12 },
+], at: [72, 720])
+```
+
+## Priority
+
+Medium — the `idml` gem works around this with N `text` calls, but
+`text_rich` would produce cleaner, smaller content streams and enable
+proper kerning between styled runs.

data/PROPOSAL.canvas-text-lines.md

@@ -0,0 +1,77 @@
+# PROPOSAL: Canvas multi-line text helper
+
+## Summary
+
+Add `Canvas#text_lines(lines, font:, size:, leading:, at:)` for drawing
+multiple lines of text with consistent leading. Simplifies multi-line
+text rendering that currently requires N separate `text` calls.
+
+## Motivation
+
+The `idml` gem's `TextFrameRenderer` breaks text into lines via a line
+breaker, then calls `canvas.text` once per line at a manually computed
+y position:
+
+```ruby
+lines.each do |line|
+  canvas.text(line.text, at: [x, baseline_y], font: font, size: size)
+  baseline_y -= size * 1.2
+end
+```
+
+This is verbose and error-prone (leading calculation, y overflow). A
+multi-line helper centralizes the logic.
+
+## Proposed API
+
+```ruby
+# Draw multiple lines of text with consistent leading.
+# @param lines [Array<String>] text strings, one per line.
+# @param font [Symbol] font resource name.
+# @param size [Float] font size in points.
+# @param leading [Float] line spacing in points (default: size * 1.2).
+# @param at [Array(Numeric, Numeric)] [x, y] of the first line's baseline.
+# @param char_spacing [Float, nil] optional character spacing.
+# @param word_spacing [Float, nil] optional word spacing.
+def text_lines(lines, font:, size:, at:, leading: nil,
+               char_spacing: nil, word_spacing: nil)
+  lead = leading || size * 1.2
+  x, y = at
+  lines.each do |line|
+    text(line, at: [x, y], font: font, size: size,
+         char_spacing: char_spacing, word_spacing: word_spacing)
+    y -= lead
+  end
+  self
+end
+```
+
+## Usage example
+
+```ruby
+# Simple multi-line text
+canvas.text_lines(
+  ["Line 1", "Line 2", "Line 3"],
+  font: :F1, size: 12, at: [72, 720]
+)
+
+# Custom leading
+canvas.text_lines(
+  wrapped_text_array,
+  font: :F1, size: 10, at: [72, 700], leading: 14
+)
+```
+
+## Implementation notes
+
+- Each line is a separate `text` call (no TJ array optimization).
+  This is intentional: different lines may have different widths
+  (justified vs left-aligned).
+- The caller controls wrapping (via their own line breaker). This
+  method only handles vertical positioning.
+- `leading` follows PDF convention: distance between baselines.
+
+## Priority
+
+Low — the current approach (N `text` calls) works. But the helper
+reduces boilerplate in every text-heavy rendering pipeline.

data/PROPOSAL.canvas-transparency.md

@@ -0,0 +1,106 @@
+# PROPOSAL: Canvas transparency and blend modes
+
+## Summary
+
+Add `Canvas#opacity=`, `Canvas#blend_mode=`, and
+`Canvas#with_transparency(opacity:, blend_mode:, &block)` for
+rendering semi-transparent page items with blending modes
+(Multiply, Screen, Overlay, etc.).
+
+## Motivation
+
+The `idml` gem's element models include transparency attributes
+(`BlendingSetting`, `OpacityGradientStop`, `FillTransparencySetting`)
+that carry Opacity, BlendMode, and IsolatedKnockout settings. Without
+transparency support in pdfrb's Canvas, these attributes are silently
+ignored — semi-transparent shapes render at full opacity.
+
+IDML documents commonly use:
+- Semi-transparent overlays (Opacity = 50%)
+- Multiply blend mode for shadow effects
+- Screen blend mode for highlights
+- Isolated blending groups
+
+## Proposed API
+
+```ruby
+class Pdfrb::Content::Canvas
+  # Set fill/stroke opacity (0.0–1.0).
+  # Uses ExtGState with /ca (fill alpha) and /CA (stroke alpha).
+  # @param alpha [Float] opacity value (0.0 = transparent, 1.0 = opaque).
+  def opacity=(alpha)
+    gs = document.ext_g_states.add(ca: alpha, CA: alpha)
+    emit_op Operator::ApplyExtGState, gs
+  end
+
+  # Set blend mode for subsequent drawing operations.
+  # @param mode [Symbol] one of: :Normal, :Multiply, :Screen,
+  #   :Overlay, :Darken, :Lighten, :ColorDodge, :ColorBurn,
+  #   :HardLight, :SoftLight, :Difference, :Exclusion,
+  #   :Hue, :Saturation, :Color, :Luminosity.
+  def blend_mode=(mode)
+    gs = document.ext_g_states.add(BM: mode.to_s)
+    emit_op Operator::ApplyExtGState, gs
+  end
+
+  # Execute a block with transparency settings, then restore.
+  def with_transparency(opacity: 1.0, blend_mode: nil)
+    save_graphics_state
+    self.opacity = opacity if opacity < 1.0
+    self.blend_mode = blend_mode if blend_mode
+    yield self
+    restore_graphics_state
+  end
+end
+```
+
+## PDF structure
+
+Transparency requires an `/ExtGState` (Extended Graphics State)
+dictionary with alpha and blend mode entries:
+
+```
+/ExtGState <<
+  /Type /ExtGState
+  /ca 0.5      % fill alpha
+  /CA 0.5      % stroke alpha
+  /BM /Multiply
+  /SMask <<    % soft mask (optional)
+    /Type /Mask /S /Alpha /G <form xobject>
+  >>
+>>
+```
+
+The Canvas applies it via `gs` operator:
+```
+/GS1 gs
+```
+
+## Document-level support
+
+```ruby
+class Pdfrb::Document
+  class ExtGStates
+    def add(ca: nil, CA: nil, BM: nil, SMask: nil)
+      # Create ExtGState dict, register in /Resources/ExtGState
+      # Return resource name (e.g., :GS1)
+    end
+  end
+end
+```
+
+## Usage example
+
+```ruby
+# Semi-transparent red rectangle with multiply blend
+canvas.with_transparency(opacity: 0.5, blend_mode: :Multiply) do
+  canvas.fill_color([:rgb, 1, 0, 0])
+  canvas.rectangle(100, 100, 200, 200)
+  canvas.fill
+end
+```
+
+## Priority
+
+Low — transparency is an advanced feature. Most IDML documents don't
+use it. But for documents that do, it's a visible rendering gap.

data/PROPOSAL.external-font-metrics.md

@@ -0,0 +1,129 @@
+# PROPOSAL: Accept externally-provided font metrics in Fonts#add
+
+## Summary
+
+Allow `Fonts#add` to accept pre-parsed font metrics (glyph widths,
+ascent/descent, encoding) from the caller, instead of requiring pdfrb
+to parse TTF/OTF binary tables internally. This lets consumers use
+well-tested font parsers (like Fontisan) and pass the results to pdfrb.
+
+## Motivation
+
+pdfrb's internal TTF table parser (`TrueType::File#table`) is broken
+— it returns raw `String` bytes instead of parsed table objects, causing
+`glyph_id_for` to fail for all TrueType/OpenType fonts. This breaks
+`glyph_width`, `measure_text`, `metrics_for`, and font width arrays.
+
+Fontisan (used by the `idml` gem) correctly parses all TTF tables
+(cmap, hmtx, head, hhea, name) and provides per-glyph widths, metrics,
+and encoding. It is battle-tested across hundreds of font files.
+
+Instead of pdfrb reimplementing TTF parsing (and getting it wrong),
+pdfrb should accept externally-provided metrics. This follows the
+Unix philosophy: do one thing well. pdfrb assembles PDFs; Fontisan
+parses fonts.
+
+## Proposed API
+
+```ruby
+# Register a font with externally-provided metrics.
+# @param name_or_io [String, IO] font file path or IO (for FontFile2
+#   embedding — pdfrb reads the raw bytes, does NOT parse tables).
+# @param widths [Hash{Integer => Integer}, nil] codepoint → advance
+#   width in font units. Required for correct text width measurement.
+# @param metrics [Hash, nil] font-level metrics:
+#   { units_per_em:, ascent:, descent:, cap_height:, x_height: }
+# @param encoding [Hash{Integer => Integer}, nil] codepoint → glyph ID
+#   mapping (from cmap table). Used for encode_text.
+# @param subset [Boolean] if true, subset during write using
+#   used_codepoints.
+# @return [Symbol] font resource name.
+def add(name_or_io, widths: nil, metrics: nil, encoding: nil,
+        subset: nil, **opts)
+```
+
+When `widths:` is provided, pdfrb uses it instead of calling the broken
+`extract_ttf_widths`. When `metrics:` is provided, `metrics_for` returns
+it instead of an empty hash. When `encoding:` is provided, `encode_text`
+uses it instead of the broken cmap parser.
+
+## Usage with Fontisan
+
+```ruby
+require "fontisan"
+require "pdfrb"
+
+# Parse font with Fontisan (correct, tested)
+font_path = "/path/to/Arial.ttf"
+fontisan = Fontisan::FontLoader.load(font_path)
+
+# Extract metrics via Fontisan
+metrics = {
+  units_per_em: fontisan.head.units_per_em,
+  ascent: fontisan.hhea.ascent,
+  descent: fontisan.hhea.descent,
+}
+widths = fontisan.hmtx.advance_widths  # {glyph_id => width}
+encoding = fontisan.cmap.code_map       # {codepoint => glyph_id}
+
+# Register with pdfrb using externally-provided data
+doc = Pdfrb::Document.new
+font = doc.fonts.add(font_path,
+                     widths: widths,
+                     metrics: metrics,
+                     encoding: encoding)
+
+# Now glyph_width, measure_text, metrics_for all work correctly
+doc.fonts.glyph_width(font, 65)  # => 667 (for 'A')
+doc.fonts.measure_text("Hello", font: font, size: 12)  # => ~28.0
+```
+
+## Usage from the idml gem
+
+The `idml` gem already has `FontMetrics` (Fontisan-based) that provides
+`glyph_width(codepoint)`, `units_per_em`, `ascent`, `descent`. It would
+build the `widths:` and `metrics:` hashes from FontMetrics and pass them
+to pdfrb:
+
+```ruby
+# In Idml::Render::Pipeline
+metrics = Idml::TextEngine::FontMetrics.open(font_path)
+widths = {}
+(32..255).each { |cp| widths[cp] = metrics.glyph_width(cp) }
+
+font_name = writer.register_font_with_metrics(
+  font_path,
+  widths: widths,
+  metrics: { units_per_em: metrics.units_per_em,
+             ascent: metrics.ascent,
+             descent: metrics.descent },
+)
+```
+
+## Implementation notes
+
+1. Store `widths`, `metrics`, `encoding` alongside the font registration.
+2. In `glyph_width(font, codepoint)`: if external widths provided,
+   return `widths[codepoint] || 0`. Otherwise fall back to AFM (standard
+   14) or the internal TTF parser.
+3. In `metrics_for(font)`: if external metrics provided, return them.
+   Otherwise fall back to AFM or internal parser.
+4. In `encode_text(text, font)`: if external encoding provided, use it
+   for codepoint → glyph ID mapping. Otherwise fall back to existing
+   encoding.
+5. FontFile2 embedding reads the raw file bytes (pdfrb already does
+   this correctly — the bug is only in table *parsing*, not file reading).
+
+## What pdfrb should NOT do
+
+- Parse TTF/OTF tables internally — this is Fontisan's job.
+- Depend on Fontisan — pdfrb should remain dependency-free for font
+  parsing. The caller decides which parser to use.
+- Reimplement cmap/hmtx/head/hhea/name parsing — these are complex
+  binary formats with many edge cases that Fontisan handles correctly.
+
+## Priority
+
+**Critical** — this unblocks TODOs 52 and 63 in the idml gem. Without
+external metrics support, the idml gem cannot use pdfrb's measurement
+API and must keep its entire text engine separate from pdfrb.