pdfrb 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 263ee1cee601c0c5b86775ad6bbeb97777f4e7e01c95f63074281d00fbec3d54
-  data.tar.gz: 5d157430c7657ae19b8954975721863a68db7dbd1a5e3439b8a830da3bc7db4a
+  metadata.gz: 04b26536220e55c3be57627ba747561baeee1d58f37e57a2f68f5f121ec1381c
+  data.tar.gz: 7a3f7a5a10b43e253e34bb5551042db89e3d94694a568beee186c2995fefe867
 SHA512:
-  metadata.gz: 8a6e80f5ad5a3dba5e4dfe087ca33554c0a8fce926e6ad9934f307485bc1728996f336d87ef1b53295dbb79d80d66d41f820c81208a8bcd488b382a6c103c2da
-  data.tar.gz: '08f52568ba799d4d02c347982407dec464eee0d861d85dafd7c8da8541738e84ccdce83c1ac7866f357f549ccd1f16f2712967f5f22fedaae54977b083ef59af'
+  metadata.gz: 70ec6abd4b94413e5cfcf1c18b4437332fc84c38262bc58347c3b55b354416cbf4f1ecfe24995dfeea12776306e8c07b1acdddd0d96b64e572bc82d60ed629df
+  data.tar.gz: 35daa8aa6439430f7d6dbc043777bc969f0844a14dd503650076fe5ffc9edd03859f22f64a3b3d290cc84eb10774589dca52c7138fc4b102bfab660692fb4461

data/CHANGELOG.md

@@ -2,8 +2,32 @@
 
 All notable changes to the pdfrb gem will be documented in this file.
 
+## [0.3.0] — 2026-08-02
+
+### Added — Semantic PDF diff
+
+* **Pdfrb::Compare** — semantic PDF comparison engine. Compares two
+  PDFs at the structural level: page count, per-page text similarity
+  (Levenshtein), font inventory diffs, image count delta, outline
+  (bookmark) diffs, metadata (/Info) diffs, and structural (Catalog +
+  Trailer key) diffs.
+* **Pdfrb::Compare::Report** — immutable report with `equivalent?`,
+  `similarity` (0..1), `summary` string, and `to_h` serialisation.
+* **CLI: `pdfrb diff LEFT RIGHT`** — compare two PDFs from the
+  command line. Exits 0 if equivalent, 1 if different.
+* **Programmatic API**: `Pdfrb::Compare.compare(left, right)` and
+  `Pdfrb::Compare.equivalent?(left, right)`. Accepts bytes, IO, or
+  Document objects.
+
+### Metrics
+
+* 550 specs (was 537), 0 failures, 4 pending.
+* 0 rubocop offenses.
+* 182 → 185 lib files; 49 → 50 spec files.
+
 ## [0.2.1] — 2026-08-02
 
+
 ### Added
 
 * **Form XObjects** (`Document::FormXObject`) — create reusable form

data/lib/pdfrb/cli.rb

@@ -67,7 +67,28 @@ module Pdfrb
       puts "Wrote #{output}"
     end
 
-    desc "encrypt INPUT OUTPUT --password PASSWORD", "Encrypt a PDF (stub — needs Phase 11 integration)"
+    desc "diff LEFT RIGHT", "Compare two PDFs semantically"
+    def diff(left, right)
+      report = Pdfrb::Compare.compare(
+        File.binread(left),
+        File.binread(right)
+      )
+      puts report.summary
+      unless report.equivalent?
+        puts
+        report.per_page_text_diffs.first(5).each do |d|
+          puts "  Page #{d[:page] + 1}: #{(d[:similarity] * 100).round(1)}% similar"
+        end
+        unless report.font_diff[:added].empty? && report.font_diff[:removed].empty?
+          puts "  Fonts added: #{report.font_diff[:added].join(', ')}" unless report.font_diff[:added].empty?
+          puts "  Fonts removed: #{report.font_diff[:removed].join(', ')}" unless report.font_diff[:removed].empty?
+        end
+        puts "  Page count delta: #{report.page_count_delta}" unless report.page_count_delta.zero?
+        exit 1
+      end
+    end
+
+    desc "encrypt INPUT OUTPUT --password PASSWORD", "Encrypt a PDF"
     method_option :password, type: :string, required: true
     def encrypt(input, output)
       warn "encrypt: not yet fully implemented (Phase 11 integration pending)"

data/lib/pdfrb/document/form_xobject.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Form XObject facade. Creates reusable form templates that can
+    # be drawn on multiple pages via the /Do operator. A Form XObject
+    # is a stream with /Type (omitted), /Subtype /Form, /BBox, and
+    # optional /Matrix + /Resources.
+    class FormXObject
+      attr_reader :document, :stream, :name
+
+      def initialize(document, name: nil, bbox: nil, matrix: nil)
+        @document = document
+        @bbox = bbox || [0, 0, 612, 792]
+        @matrix = matrix
+
+        dict = { Subtype: :Form, BBox: @bbox }
+        dict[:Matrix] = @matrix if @matrix
+        @stream = document.add(dict, type: Pdfrb::Model::Cos::Stream)
+        @name = (name || "Form#{@stream.oid}").to_sym
+        @canvas = nil
+      end
+
+      # Returns a Canvas for drawing into this Form XObject.
+      # The Canvas writes to the Form XObject's content stream.
+      def canvas
+        return @canvas if @canvas
+
+        contents_stream = @document.add({}, type: Pdfrb::Model::Cos::Stream)
+        @stream.value[:Resources] = {}
+        @canvas = Pdfrb::Content::Canvas.new(contents_stream, document: @document)
+        @stream.stream = +"".b # placeholder; filled by ensure_stream_payload
+        @contents_stream = contents_stream
+        @canvas
+      end
+
+      # Finalize: copy the canvas content into the Form XObject stream
+      # and register it in the document's resource names. Called
+      # automatically before write.
+      def finalize!
+        return unless @contents_stream
+
+        @stream.stream = @contents_stream.stream
+        @stream.value[:Resources] = @contents_stream.value[:Resources] || {}
+      end
+
+      # Register this Form XObject in a page's /Resources /XObject dict
+      # so it can be referenced via the /Do operator.
+      def register_on_page(page)
+        resources = page.value[:Resources]
+        resources = {} unless resources.is_a?(::Hash)
+        xobjects = resources[:XObject] || {}
+        xobjects[@name] = Pdfrb::Model::Reference.new(@stream.oid, @stream.gen)
+        resources[:XObject] = xobjects
+        page.value[:Resources] = resources
+      end
+
+      # Draw this Form XObject on a canvas at the given position.
+      def draw_on(target_canvas, at:, scale: 1.0)
+        target_canvas.emit_op(Pdfrb::Content::Operator::SaveGraphicsState)
+        target_canvas.translate(at[0], at[1])
+        target_canvas.scale(scale) if (scale - 1.0).abs > 1e-9
+        target_canvas.append(" /#{@name} Do\n")
+        target_canvas.emit_op(Pdfrb::Content::Operator::RestoreGraphicsState)
+      end
+    end
+  end
+end

data/lib/pdfrb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pdfrb
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/pdfrb.rb

@@ -93,5 +93,7 @@ module Pdfrb
 
   # CLI (only loaded when invoked via the +pdfrb+ executable; avoids
   # pulling in thor for library-only users).
+  autoload :Compare, "pdfrb/compare"
+
   autoload :CLI, "pdfrb/cli"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pdfrb
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -737,6 +737,7 @@ files:
 - lib/pdfrb/document/destinations.rb
 - lib/pdfrb/document/files.rb
 - lib/pdfrb/document/fonts.rb
+- lib/pdfrb/document/form_xobject.rb
 - lib/pdfrb/document/images.rb
 - lib/pdfrb/document/metadata.rb
 - lib/pdfrb/document/outline.rb