acro_that 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40016774a590828e59c4c9ea4331a8d170ccd536d7522cbdb193fefda3f28333
-  data.tar.gz: bade6f113359d96d1f7c1a85efd7033732350c0b19bf40dd412e104da359aa5a
+  metadata.gz: '09e4943697402d884588b9cb40c2d8b3fb010809e9b9f5781711b600eeeabc74'
+  data.tar.gz: a5c950e1c0fad9555314c5bc08d85a493626a0e174072990fff17a86ef32f61c
 SHA512:
-  metadata.gz: 60e6c6afd93cfd8911c0b0a0d4b6b080cb2c8af85a104cf3fd09f8fc7f9ac642999a8d5694c374ad64b71d4aa769f6d8b390cc82829317abd64598aa42e7280f
-  data.tar.gz: 31762cf9f6f285edd78976692e9c5bab7a67cf6298a03c8d4208b02927639be29e0d1f4ca1f14c3f1c170b9f617404e0931dc8bbedd17de79fcee5c80035dd29
+  metadata.gz: dafc26f93d0101eea028176451f1450bf5c536ee3657cf2c55bb151cdd282b85c0428e876bae4495c9bb9a36f4255128cc5fba938a7fb7833b0888ada5697ea8
+  data.tar.gz: 6ee3232b237cdeb6f61c7d73b43599b187a575d25e08a522020df52edc9224e2400e5372c08923ecf29c2e6332ee77e51cb828beb0b74974bd8079533ccc752e

data/CHANGELOG.md

@@ -5,7 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.3] - 2025-01-XX
+## [0.1.5] - 2025-11-01
+
+### Fixed
+- Fixed signature field image data parsing when adding signature fields. Image data (base64 or data URI) is now properly detected and parsed when creating signature fields, matching the behavior of `update_field`.
+
+### Added
+- Added support for `metadata` option in `add_field` to pass PDF widget properties. This allows setting properties like field flags (`Ff`) for multiline text fields, alignment (`Q`), and other PDF widget options directly when creating fields.
+
+## [0.1.4] - 2025-11-01
 
 ### Fixed
 - Fixed bug where fields added to multi-page PDFs were all placed on the same page. Fields now correctly appear on their specified pages when using the `page` option in `add_field`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    acro_that (0.1.2)
+    acro_that (0.1.5)
       chunky_png (~> 1.4)
 
 GEM

data/issues/README.md

@@ -13,21 +13,26 @@ This folder contains documentation of code cleanup and refactoring opportunities
 2. **/Annots Array Manipulation** - Complex logic duplicated in 3 locations
 
 ### Medium Priority Issues
-3. **Page-Finding Logic** - Similar logic in 4+ methods
-4. **Box Parsing Logic** - Repeated code blocks for 5 box types
+3. **Box Parsing Logic** - Repeated code blocks for 5 box types
+4. **Checkbox Appearance Creation** - Significant duplication in new code
+5. **PDF Metadata Formatting** - Could benefit from being shared utilities
 
 ### Low Priority Issues
-5. Duplicated `next_fresh_object_number` implementation
-6. Object reference extraction pattern duplication
-7. Unused method: `get_widget_rect_dimensions`
-8. Base64 decoding logic duplication
+6. Duplicated `next_fresh_object_number` implementation (may be intentional)
+7. Object reference extraction pattern duplication
+8. Unused method: `get_widget_rect_dimensions`
+9. Base64 decoding logic duplication
+
+### Completed ✅
+- **Page-Finding Logic** - Successfully refactored into `DictScan.is_page?` and unified page-finding methods
 
 ## Quick Stats
 
-- **8 refactoring opportunities** identified
+- **10 refactoring opportunities** identified (1 completed, 9 remaining)
 - **6+ locations** with widget matching duplication
 - **3 locations** with /Annots array manipulation duplication
 - **1 unused method** found
+- **2 new issues** identified in recent code additions
 
 ## Next Steps
 

data/issues/refactoring-opportunities.md

@@ -2,30 +2,21 @@
 
 This document identifies code duplication and unused methods that could be refactored to improve maintainability.
 
-## 1. Duplicated Page-Finding Logic
+## 1. Duplicated Page-Finding Logic ✅ **COMPLETED**
 
-### Issue
-Multiple methods have similar logic for finding page objects in a PDF document.
-
-### Locations
-- `Document#list_pages` (lines 75-104)
-- `Document#collect_pages_from_tree` (lines 691-712)
-- `Document#find_page_number_for_ref` (lines 714-728)
-- `AddField#find_page_ref` (lines 155-211)
-
-### Pattern
-The pattern `body.include?("/Type /Page") || body =~ %r{/Type\s*/Page(?!s)\b}` appears in multiple places with slight variations.
+### Status
+**RESOLVED** - This refactoring has been completed:
+- ✅ `DictScan.is_page?(body)` exists (line 320 in dict_scan.rb)
+- ✅ `Document#find_all_pages` exists (line 693 in document.rb)
+- ✅ `Document#find_page_by_number(page_num)` exists (line 725 in document.rb)
+- ✅ `Base#find_page_by_number` delegates to Document
+- ✅ `AddField#find_page_ref` now uses `find_page_by_number` (line 288)
 
-### Suggested Refactor
-Create a shared module or utility methods in `DictScan`:
-- `DictScan.is_page?(body)` - Check if a body represents a page object
-- `Document#find_all_pages` - Unified method to find all page objects
-- `Document#find_page_by_number(page_num)` - Find a specific page by number
+### Original Issue
+Multiple methods had similar logic for finding page objects in a PDF document.
 
-### Benefits
-- Single source of truth for page detection logic
-- Easier to maintain and update page-finding behavior
-- Consistent page ordering across methods
+### Resolution
+All page-finding logic has been unified into `DictScan.is_page?` and `Document#find_all_pages` / `find_page_by_number`.
 
 ---
 
@@ -97,45 +88,18 @@ Extend `DictScan` with methods:
 
 ---
 
-## 4. Duplicated Box Parsing Logic
+## 4. Duplicated Box Parsing Logic ✅ **COMPLETED**
 
-### Issue
-`Document#list_pages` has repeated code blocks for parsing different box types (MediaBox, CropBox, ArtBox, BleedBox, TrimBox).
+### Status
+**RESOLVED** - This refactoring has been completed:
+- ✅ `DictScan.parse_box(body, box_type)` exists (line 340 in dict_scan.rb)
+- ✅ `Document#list_pages` now uses `parse_box` for all box types (lines 89-99 in document.rb)
 
-### Locations
-- `Document#list_pages` (lines 120-165)
+### Original Issue
+`Document#list_pages` had repeated code blocks for parsing different box types (MediaBox, CropBox, ArtBox, BleedBox, TrimBox).
 
-### Pattern
-Each box type uses identical logic:
-```ruby
-if body =~ %r{/MediaBox\s*\[(.*?)\]}
-  box_values = ::Regexp.last_match(1).scan(/[-+]?\d*\.?\d+/).map(&:to_f)
-  if box_values.length == 4
-    llx, lly, urx, ury = box_values
-    media_box = { llx: llx, lly: lly, urx: urx, ury: ury }
-  end
-end
-```
-
-### Suggested Refactor
-Create a helper method:
-```ruby
-def parse_box(body, box_type)
-  pattern = %r{/#{box_type}\s*\[(.*?)\]}
-  return nil unless body =~ pattern
-  
-  box_values = ::Regexp.last_match(1).scan(/[-+]?\d*\.?\d+/).map(&:to_f)
-  return nil unless box_values.length == 4
-  
-  llx, lly, urx, ury = box_values
-  { llx: llx, lly: lly, urx: urx, ury: ury }
-end
-```
-
-### Benefits
-- Reduces code duplication from ~45 lines to ~10 lines per box type
-- Easier to add new box types
-- Consistent parsing logic
+### Resolution
+Extracted the common box parsing logic into `DictScan.parse_box` helper method. All box type parsing in `Document#list_pages` now uses this shared method, reducing code duplication from ~45 lines to ~10 lines while maintaining existing functionality.
 
 ---
 
@@ -145,32 +109,23 @@ end
 The `next_fresh_object_number` method is implemented identically in two places.
 
 ### Locations
-- `Document#next_fresh_object_number` (lines 730-739)
+- `Document#next_fresh_object_number` (lines 745-754)
 - `Base#next_fresh_object_number` (lines 28-37)
 
 ### Pattern
-Both methods have identical implementation:
-```ruby
-def next_fresh_object_number
-  max_obj_num = 0
-  resolver.each_object do |ref, _|
-    max_obj_num = [max_obj_num, ref[0]].max
-  end
-  patches.each do |p|
-    max_obj_num = [max_obj_num, p[:ref][0]].max
-  end
-  max_obj_num + 1
-end
-```
+Both methods have identical implementation. However, `Document` doesn't include `Base`, so both need to exist independently.
 
 ### Suggested Refactor
-- Remove `Document#next_fresh_object_number` - it's only called within `Document` but could use `Base`'s implementation
-- Or: Document already has access to resolver and patches, so remove duplication by making Document use Base's method
+- Consider whether `Document` should use `Base`'s implementation via delegation
+- Or: Keep both implementations if Document needs independent access
 
 ### Benefits
 - Single implementation
 - Consistent object numbering logic
 
+### Note
+This may be intentional since `Document` doesn't include `Base` - both classes need this functionality independently.
+
 ---
 
 ## 6. Unused Methods
@@ -250,15 +205,50 @@ end
 1. **Widget Matching Logic (#2)** - Most duplicated, used in many critical operations
 2. **/Annots Array Manipulation (#3)** - Complex logic that's error-prone when duplicated
 
-### Medium Priority
-3. **Page-Finding Logic (#1)** - Used in multiple places, but less frequently
-4. **Box Parsing Logic (#4)** - Simple duplication, easy to refactor
 
 ### Low Priority
-5. **next_fresh_object_number (#5)** - Simple duplication
-6. **Object Reference Extraction (#8)** - Could improve consistency
-7. **Unused Methods (#6)** - Cleanup task
-8. **Base64 Decoding (#7)** - Minor duplication
+6. **next_fresh_object_number (#5)** - Simple duplication (may be intentional)
+7. **Object Reference Extraction (#8)** - Could improve consistency
+8. **Unused Methods (#6)** - Cleanup task (`get_widget_rect_dimensions`)
+9. **Base64 Decoding (#7)** - Minor duplication
+
+### Completed ✅
+- **Page-Finding Logic (#1)** - Successfully refactored into `DictScan.is_page?` and unified page-finding methods
+- **Checkbox Appearance Creation (#9)** - Extracted common Form XObject building logic into `build_form_xobject` helper method
+- **Box Parsing Logic (#4)** - Extracted common box parsing logic into `DictScan.parse_box` helper method
+- **PDF Metadata Formatting (#10)** - Moved `format_pdf_key` and `format_pdf_value` to `DictScan` module as shared utilities
+
+---
+
+## 9. Duplicated Checkbox Appearance Creation Logic ✅ **COMPLETED**
+
+### Status
+**RESOLVED** - This refactoring has been completed:
+- ✅ `AddField#build_form_xobject` exists (line 472 in add_field.rb)
+- ✅ `AddField#create_checkbox_yes_appearance` now uses `build_form_xobject` (line 458)
+- ✅ `AddField#create_checkbox_off_appearance` now uses `build_form_xobject` (line 469)
+
+### Original Issue
+The `create_checkbox_yes_appearance` and `create_checkbox_off_appearance` methods had duplicated Form XObject dictionary building logic.
+
+### Resolution
+Extracted the common Form XObject dictionary building logic into `build_form_xobject` helper method. Both checkbox appearance methods now use this shared method, reducing duplication while maintaining existing functionality.
+
+---
+
+## 10. PDF Metadata Formatting Methods Could Be Shared ✅ **COMPLETED**
+
+### Status
+**RESOLVED** - This refactoring has been completed:
+- ✅ `DictScan.format_pdf_key(key)` exists (line 134 in dict_scan.rb)
+- ✅ `DictScan.format_pdf_value(value)` exists (line 140 in dict_scan.rb)
+- ✅ `AddField` now uses `DictScan.format_pdf_key` and `DictScan.format_pdf_value` (lines 145-146, 195-196)
+
+### Original Issue
+The `format_pdf_key` and `format_pdf_value` methods in `AddField` were useful utility functions that could be shared across the codebase.
+
+### Resolution
+Moved `format_pdf_key` and `format_pdf_value` from `AddField` to the `DictScan` module as module functions. This makes them reusable throughout the codebase and provides a single source of truth for PDF formatting rules. `AddField` now uses these shared utilities, maintaining existing functionality while improving code reusability.
 
 ---
 

data/lib/acro_that/actions/add_field.rb

@@ -12,6 +12,7 @@ module AcroThat
         @document = document
         @name = name
         @options = options
+        @metadata = options[:metadata] || {}
       end
 
       def call
@@ -28,6 +29,10 @@ module AcroThat
                         "/Tx"
                       when :button, "button", "/Btn", "/btn"
                         "/Btn"
+                      when :radio, "radio"
+                        "/Btn"
+                      when :checkbox, "checkbox"
+                        "/Btn"
                       when :choice, "choice", "/Ch", "/ch"
                         "/Ch"
                       when :signature, "signature", "/Sig", "/sig"
@@ -37,6 +42,12 @@ module AcroThat
                       end
         @field_value = @options[:value] || ""
 
+        # Auto-set radio button flags if type is :radio and flags not explicitly set
+        # Radio button flags: Radio (bit 15 = 32768) + NoToggleToOff (bit 14 = 16384) = 49152
+        if [:radio, "radio"].include?(type_input) && !(@metadata[:Ff] || @metadata["Ff"])
+          @metadata[:Ff] = 49_152
+        end
+
         # Create a proper field dictionary + a widget annotation that references it via /Parent
         @field_obj_num = next_fresh_object_number
         widget_obj_num = @field_obj_num + 1
@@ -60,6 +71,34 @@ module AcroThat
         # Add widget to the target page's /Annots
         add_widget_to_page(widget_obj_num, page_num)
 
+        # If this is a signature field with image data, add the signature appearance
+        if @field_type == "/Sig" && @field_value && !@field_value.empty?
+          image_data = @field_value
+          # Check if value looks like base64 image data or data URI (same logic as update_field)
+          if image_data.is_a?(String) && (image_data.start_with?("data:image/") || (image_data.length > 50 && image_data.match?(%r{^[A-Za-z0-9+/]*={0,2}$})))
+            field_ref = [@field_obj_num, 0]
+            # Try adding signature appearance - use width and height from options
+            action = Actions::AddSignatureAppearance.new(@document, field_ref, image_data, width: width, height: height)
+            # NOTE: We don't fail if appearance addition fails - field was still created successfully
+            action.call
+          end
+        end
+
+        # If this is a checkbox (button field that's not a radio button), add appearance dictionaries
+        # Button fields can be checkboxes or radio buttons:
+        # - Radio buttons have Radio flag (bit 15 = 32768) set
+        # - Checkboxes don't have Radio flag set
+        is_checkbox = false
+        if @field_type == "/Btn"
+          field_flags = (@metadata[:Ff] || @metadata["Ff"] || 0).to_i
+          is_radio = field_flags.anybits?(32_768) || [:radio, "radio"].include?(type_input)
+          is_checkbox = !is_radio
+        end
+
+        if is_checkbox
+          add_checkbox_appearance(widget_obj_num, x, y, width, height)
+        end
+
         true
       end
 
@@ -69,9 +108,45 @@ module AcroThat
         dict = "<<\n"
         dict += "  /FT #{type}\n"
         dict += "  /T #{DictScan.encode_pdf_string(@name)}\n"
-        dict += "  /Ff 0\n"
+
+        # Apply /Ff from metadata, or use default 0
+        # Note: Radio button flags should already be set in metadata during type normalization
+        field_flags = @metadata[:Ff] || @metadata["Ff"] || 0
+        dict += "  /Ff #{field_flags}\n"
+
         dict += "  /DA (/Helv 0 Tf 0 g)\n"
-        dict += "  /V #{DictScan.encode_pdf_string(value)}\n" if value && !value.empty?
+
+        # For signature fields with image data, don't set /V (appearance stream will be added separately)
+        # For checkboxes/radio buttons, set /V to normalized value (Yes/Off) - macOS Preview needs this
+        # For other fields, set /V normally
+        should_set_value = if type == "/Sig" && value && !value.empty?
+                             # Check if value looks like image data
+                             !(value.is_a?(String) && (value.start_with?("data:image/") || (value.length > 50 && value.match?(%r{^[A-Za-z0-9+/]*={0,2}$}))))
+                           else
+                             true
+                           end
+
+        # For button fields (checkboxes/radio), normalize value to "Yes" or "Off"
+        normalized_field_value = if type == "/Btn" && value
+                                   # Accept "Yes", "/Yes" (PDF name format), true (boolean), or "true" (string)
+                                   value_str = value.to_s
+                                   is_checked = ["Yes", "/Yes", "true"].include?(value_str) || value == true
+                                   is_checked ? "Yes" : "Off"
+                                 else
+                                   value
+                                 end
+
+        dict += "  /V #{DictScan.encode_pdf_string(normalized_field_value)}\n" if should_set_value && normalized_field_value && !normalized_field_value.to_s.empty?
+
+        # Apply other metadata entries (excluding Ff which we handled above)
+        @metadata.each do |key, val|
+          next if [:Ff, "Ff"].include?(key) # Already handled above
+
+          pdf_key = DictScan.format_pdf_key(key)
+          pdf_value = DictScan.format_pdf_value(val)
+          dict += "  #{pdf_key} #{pdf_value}\n"
+        end
+
         dict += ">>"
         dict
       end
@@ -87,7 +162,44 @@ module AcroThat
         widget += "  /Rect #{rect_array}\n"
         widget += "  /F 4\n"
         widget += "  /DA (/Helv 0 Tf 0 g)\n"
-        widget += "  /V #{DictScan.encode_pdf_string(value)}\n" if value && !value.empty?
+
+        # For checkboxes, /V is set to "Yes" or "Off" and /AS is set accordingly
+        # For signature fields with image data, don't set /V (appearance stream will be added separately)
+        # For other fields or non-image signature values, set /V normally
+        should_set_value = if type == "/Sig" && value && !value.empty?
+                             # Check if value looks like image data
+                             !(value.is_a?(String) && (value.start_with?("data:image/") || (value.length > 50 && value.match?(%r{^[A-Za-z0-9+/]*={0,2}$}))))
+                           elsif type == "/Btn"
+                             # For button fields (checkboxes), set /V to "Yes" or "Off"
+                             # This will be handled by checkbox appearance code, but we set it here for consistency
+                             true
+                           else
+                             true
+                           end
+
+        # For checkboxes, set /V to "Yes" or empty/Off
+        if type == "/Btn" && should_set_value
+          # Checkbox value should be "Yes" if checked, otherwise empty or "Off"
+          # Accept "Yes", "/Yes" (PDF name format), true (boolean), or "true" (string)
+          value_str = value.to_s
+          is_checked = ["Yes", "/Yes", "true"].include?(value_str) || value == true
+          checkbox_value = is_checked ? "Yes" : "Off"
+          widget += "  /V #{DictScan.encode_pdf_string(checkbox_value)}\n"
+        elsif should_set_value && value && !value.empty?
+          widget += "  /V #{DictScan.encode_pdf_string(value)}\n"
+        end
+
+        # Apply metadata entries that are valid for widgets
+        # Common widget properties: /Q (alignment), /Ff (field flags), /BS (border style), etc.
+        @metadata.each do |key, val|
+          pdf_key = DictScan.format_pdf_key(key)
+          pdf_value = DictScan.format_pdf_value(val)
+          # Only add if not already present (we've added /F above, /V above if value exists)
+          next if ["/F", "/V"].include?(pdf_key)
+
+          widget += "  #{pdf_key} #{pdf_value}\n"
+        end
+
         widget += ">>"
         widget
       end
@@ -122,6 +234,41 @@ module AcroThat
           patched = DictScan.upsert_key_value(patched, "/NeedAppearances", "true")
         end
 
+        # Step 2.5: Remove /XFA if present (prevents XFA detection warnings in viewers like Master PDF)
+        # We're creating AcroForms, not XFA forms, so remove /XFA if it exists
+        if patched.include?("/XFA")
+          xfa_pattern = %r{/XFA(?=[\s(<\[/])}
+          if patched.match(xfa_pattern)
+            # Try to get the value token to determine what we're removing
+            xfa_value = DictScan.value_token_after("/XFA", patched)
+            if xfa_value
+              # Remove /XFA by replacing it with an empty string
+              # We'll use a simple approach: find the key and remove it with its value
+              xfa_match = patched.match(xfa_pattern)
+              if xfa_match
+                # Find the start and end of /XFA and its value
+                key_start = xfa_match.begin(0)
+                # Skip /XFA key
+                value_start = xfa_match.end(0)
+                value_start += 1 while value_start < patched.length && patched[value_start] =~ /\s/
+                # Use value_token_after to get the complete value token
+                # We already have xfa_value, so calculate its end
+                value_end = value_start + xfa_value.length
+                # Skip trailing whitespace
+                value_end += 1 while value_end < patched.length && patched[value_end] =~ /\s/
+                # Remove /XFA and its value
+                before = patched[0...key_start]
+                # Remove any whitespace before /XFA too (but not the opening <<)
+                before = before.rstrip
+                after = patched[value_end..]
+                patched = "#{before} #{after.lstrip}".strip
+                # Clean up any double spaces
+                patched = patched.gsub(/\s+/, " ")
+              end
+            end
+          end
+        end
+
         # Step 3: Ensure /DR /Font has /Helv mapping
         unless patched.include?("/DR") && patched.include?("/Helv")
           font_obj_num = next_fresh_object_number
@@ -220,6 +367,122 @@ module AcroThat
         apply_patch(target_page_ref, new_body, page_body) if new_body && new_body != page_body
         true
       end
+
+      def add_checkbox_appearance(widget_obj_num, _x, _y, width, height)
+        # Create appearance form XObjects for Yes and Off states
+        yes_obj_num = next_fresh_object_number
+        off_obj_num = yes_obj_num + 1
+
+        # Create Yes appearance (checked box with checkmark)
+        yes_body = create_checkbox_yes_appearance(width, height)
+        @document.instance_variable_get(:@patches) << { ref: [yes_obj_num, 0], body: yes_body }
+
+        # Create Off appearance (empty box)
+        off_body = create_checkbox_off_appearance(width, height)
+        @document.instance_variable_get(:@patches) << { ref: [off_obj_num, 0], body: off_body }
+
+        # Get current widget body and add /AP dictionary
+        widget_ref = [widget_obj_num, 0]
+        original_widget_body = get_object_body_with_patch(widget_ref)
+        widget_body = original_widget_body.dup
+
+        # Create /AP dictionary with Yes and Off appearances
+        ap_dict = "<<\n  /N <<\n    /Yes #{yes_obj_num} 0 R\n    /Off #{off_obj_num} 0 R\n  >>\n>>"
+
+        # Add /AP to widget
+        if widget_body.include?("/AP")
+          # Replace existing /AP
+          ap_key_pattern = %r{/AP(?=[\s(<\[/])}
+          if widget_body.match(ap_key_pattern)
+            widget_body = DictScan.replace_key_value(widget_body, "/AP", ap_dict)
+          end
+        else
+          # Insert /AP before closing >>
+          widget_body = DictScan.upsert_key_value(widget_body, "/AP", ap_dict)
+        end
+
+        # Set /AS based on the value - use the EXACT same normalization logic as widget creation
+        # This ensures consistency between /V and /AS
+        # Normalize value: "Yes" if truthy (Yes, "/Yes", true, etc.), otherwise "Off"
+        value_str = @field_value.to_s
+        is_checked = value_str == "Yes" || value_str == "/Yes" || value_str == "true" || @field_value == true
+        normalized_value = is_checked ? "Yes" : "Off"
+
+        # Set /AS to match normalized value (same as what was set for /V in widget creation)
+        as_value = if normalized_value == "Yes"
+                     "/Yes"
+                   else
+                     "/Off"
+                   end
+
+        widget_body = if widget_body.include?("/AS")
+                        DictScan.replace_key_value(widget_body, "/AS", as_value)
+                      else
+                        DictScan.upsert_key_value(widget_body, "/AS", as_value)
+                      end
+
+        apply_patch(widget_ref, widget_body, original_widget_body)
+      end
+
+      def create_checkbox_yes_appearance(width, height)
+        # Create a form XObject that draws a checked checkbox
+        # Box outline + checkmark
+        # Scale to match width and height
+        # Simple appearance: draw a box and a checkmark
+        # For simplicity, use PDF drawing operators
+        # Box: rectangle from (0,0) to (width, height)
+        # Checkmark: simple path drawing
+
+        # PDF content stream for checked checkbox
+        # Draw just the checkmark (no box border)
+        border_width = [width * 0.08, height * 0.08].min
+
+        # Calculate checkmark path
+        check_x1 = width * 0.25
+        check_y1 = height * 0.45
+        check_x2 = width * 0.45
+        check_y2 = height * 0.25
+        check_x3 = width * 0.75
+        check_y3 = height * 0.75
+
+        content_stream = "q\n"
+        content_stream += "0 0 0 rg\n" # Black color (darker)
+        content_stream += "#{border_width} w\n" # Line width
+        # Draw checkmark only (no box border)
+        content_stream += "#{check_x1} #{check_y1} m\n"
+        content_stream += "#{check_x2} #{check_y2} l\n"
+        content_stream += "#{check_x3} #{check_y3} l\n"
+        content_stream += "S\n" # Stroke
+        content_stream += "Q\n"
+
+        build_form_xobject(content_stream, width, height)
+      end
+
+      def create_checkbox_off_appearance(width, height)
+        # Create a form XObject for unchecked checkbox
+        # Empty appearance (no border, no checkmark) - viewer will draw default checkbox
+
+        content_stream = "q\n"
+        # Empty appearance for unchecked state
+        content_stream += "Q\n"
+
+        build_form_xobject(content_stream, width, height)
+      end
+
+      def build_form_xobject(content_stream, width, height)
+        # Build a Form XObject dictionary with the given content stream
+        dict = "<<\n"
+        dict += "  /Type /XObject\n"
+        dict += "  /Subtype /Form\n"
+        dict += "  /BBox [0 0 #{width} #{height}]\n"
+        dict += "  /Length #{content_stream.bytesize}\n"
+        dict += ">>\n"
+        dict += "stream\n"
+        dict += content_stream
+        dict += "\nendstream"
+
+        dict
+      end
     end
   end
 end

data/lib/acro_that/actions/update_field.rb

@@ -129,6 +129,36 @@ module AcroThat
         # Also update any widget annotations that reference this field via /Parent
         update_widget_annotations_for_field(field_ref, @new_value)
 
+        # If this is a checkbox without appearance streams, create them
+        if fld.button_field?
+          # Check if it's a checkbox (not a radio button) by checking field flags
+          field_body = get_object_body_with_patch(field_ref)
+          is_radio = false
+          if field_body
+            field_flags_match = field_body.match(%r{/Ff\s+(\d+)})
+            if field_flags_match
+              field_flags = field_flags_match[1].to_i
+              # Radio button flag is bit 15 = 32768
+              is_radio = field_flags.anybits?(32_768)
+            end
+          end
+
+          # Only create checkbox appearances (not radio buttons)
+          unless is_radio
+            widget_ref = find_checkbox_widget(fld.ref)
+            if widget_ref
+              widget_body = get_object_body_with_patch(widget_ref)
+              # Create appearances if /AP doesn't exist
+              unless widget_body&.include?("/AP")
+                rect = extract_widget_rect(widget_body)
+                if rect && rect[:width].positive? && rect[:height].positive?
+                  add_checkbox_appearance(widget_ref, rect[:width], rect[:height])
+                end
+              end
+            end
+          end
+        end
+
         # Best-effort: set NeedAppearances to true so viewers regenerate appearances
         ensure_need_appearances
 
@@ -144,8 +174,22 @@ module AcroThat
         # Ensure we have a valid dictionary
         return dict_body unless dict_body&.include?("<<")
 
-        # Encode the new value
-        v_token = DictScan.encode_pdf_string(new_value)
+        # For checkboxes (/Btn fields), normalize value to "Yes" or "Off"
+        ft_pattern = %r{/FT\s+/Btn}
+        is_button_field = ft_pattern.match(dict_body)
+
+        normalized_value = if is_button_field
+                             # For checkboxes/radio buttons, normalize to "Yes" or "Off"
+                             # Accept "Yes", "/Yes" (PDF name format), true (boolean), or "true" (string)
+                             value_str = new_value.to_s
+                             is_checked = ["Yes", "/Yes", "true"].include?(value_str) || new_value == true
+                             is_checked ? "Yes" : "Off"
+                           else
+                             new_value
+                           end
+
+        # Encode the normalized value
+        v_token = DictScan.encode_pdf_string(normalized_value)
 
         # Find /V using pattern matching to ensure we get the complete key
         v_key_pattern = %r{/V(?=[\s(<\[/])}
@@ -166,24 +210,34 @@ module AcroThat
 
         # Update /AS for checkboxes/radio buttons if needed
         # Check for /FT /Btn more carefully
-        ft_pattern = %r{/FT\s+/Btn}
-        if ft_pattern.match(patched) && (as_needed = DictScan.appearance_choice_for(new_value, patched))
-          as_pattern = %r{/AS(?=[\s(<\[/])}
-          has_as = patched.match(as_pattern)
-
-          patched = if has_as
-                      DictScan.replace_key_value(patched, "/AS", as_needed)
-                    else
-                      DictScan.upsert_key_value(patched, "/AS", as_needed)
-                    end
-
-          # Verify /AS replacement worked
-          unless patched && patched.include?("<<") && patched.include?(">>")
-            warn "Warning: Dictionary corrupted after /AS replacement"
-            # Revert to before /AS change
-            return DictScan.replace_key_value(dict_body, "/V", v_token) if has_v
-
-            return dict_body
+        if ft_pattern.match(patched)
+          # For button fields, set /AS based on normalized value
+          as_value = if normalized_value == "Yes"
+                       "/Yes"
+                     else
+                       "/Off"
+                     end
+
+          # Only set /AS if /AP exists (appearance dictionary is present)
+          # If /AP doesn't exist, we can't set /AS properly
+          if patched.include?("/AP")
+            as_pattern = %r{/AS(?=[\s(<\[/])}
+            has_as = patched.match(as_pattern)
+
+            patched = if has_as
+                        DictScan.replace_key_value(patched, "/AS", as_value)
+                      else
+                        DictScan.upsert_key_value(patched, "/AS", as_value)
+                      end
+
+            # Verify /AS replacement worked
+            unless patched && patched.include?("<<") && patched.include?(">>")
+              warn "Warning: Dictionary corrupted after /AS replacement"
+              # Revert to before /AS change
+              return DictScan.replace_key_value(dict_body, "/V", v_token) if has_v
+
+              return dict_body
+            end
           end
         end
 
@@ -296,6 +350,184 @@ module AcroThat
 
         DictScan.is_multiline_field?(field_body)
       end
+
+      def find_checkbox_widget(field_ref)
+        # Check patches first
+        patches = @document.instance_variable_get(:@patches)
+        patches.each do |patch|
+          next unless patch[:body]
+          next unless DictScan.is_widget?(patch[:body])
+
+          # Check if widget has /Parent pointing to field_ref
+          if patch[:body] =~ %r{/Parent\s+(\d+)\s+(\d+)\s+R}
+            parent_ref = [Integer(::Regexp.last_match(1)), Integer(::Regexp.last_match(2))]
+            return patch[:ref] if parent_ref == field_ref
+          end
+
+          # Also check if widget IS the field (flat structure)
+          if patch[:body].include?("/FT") && DictScan.value_token_after("/FT",
+                                                                        patch[:body]) == "/Btn" && (patch[:ref] == field_ref)
+            return patch[:ref]
+          end
+        end
+
+        # Then check resolver (for existing widgets)
+        resolver.each_object do |ref, body|
+          next unless body && DictScan.is_widget?(body)
+
+          # Check if widget has /Parent pointing to field_ref
+          if body =~ %r{/Parent\s+(\d+)\s+(\d+)\s+R}
+            parent_ref = [Integer(::Regexp.last_match(1)), Integer(::Regexp.last_match(2))]
+            return ref if parent_ref == field_ref
+          end
+
+          # Also check if widget IS the field (flat structure)
+          if body.include?("/FT") && DictScan.value_token_after("/FT", body) == "/Btn" && (ref == field_ref)
+            return ref
+          end
+        end
+
+        # Fallback: if field_ref itself is a widget
+        body = get_object_body_with_patch(field_ref)
+        return field_ref if body && DictScan.is_widget?(body) && body.include?("/FT") && DictScan.value_token_after(
+          "/FT", body
+        ) == "/Btn"
+
+        nil
+      end
+
+      def extract_widget_rect(widget_body)
+        return nil unless widget_body
+
+        rect_tok = DictScan.value_token_after("/Rect", widget_body)
+        return nil unless rect_tok&.start_with?("[")
+
+        rect_values = rect_tok.scan(/[-+]?\d*\.?\d+/).map(&:to_f)
+        return nil unless rect_values.length == 4
+
+        x1, y1, x2, y2 = rect_values
+        width = (x2 - x1).abs
+        height = (y2 - y1).abs
+
+        return nil if width <= 0 || height <= 0
+
+        { x: x1, y: y1, width: width, height: height }
+      end
+
+      def add_checkbox_appearance(widget_ref, width, height)
+        # Create appearance form XObjects for Yes and Off states
+        yes_obj_num = next_fresh_object_number
+        off_obj_num = yes_obj_num + 1
+
+        # Create Yes appearance (checked box with checkmark)
+        yes_body = create_checkbox_yes_appearance(width, height)
+        @document.instance_variable_get(:@patches) << { ref: [yes_obj_num, 0], body: yes_body }
+
+        # Create Off appearance (empty box)
+        off_body = create_checkbox_off_appearance(width, height)
+        @document.instance_variable_get(:@patches) << { ref: [off_obj_num, 0], body: off_body }
+
+        # Get current widget body and add /AP dictionary
+        original_widget_body = get_object_body_with_patch(widget_ref)
+        widget_body = original_widget_body.dup
+
+        # Create /AP dictionary with Yes and Off appearances
+        ap_dict = "<<\n  /N <<\n    /Yes #{yes_obj_num} 0 R\n    /Off #{off_obj_num} 0 R\n  >>\n>>"
+
+        # Add /AP to widget
+        if widget_body.include?("/AP")
+          # Replace existing /AP
+          ap_key_pattern = %r{/AP(?=[\s(<\[/])}
+          if widget_body.match(ap_key_pattern)
+            widget_body = DictScan.replace_key_value(widget_body, "/AP", ap_dict)
+          end
+        else
+          # Insert /AP before closing >>
+          widget_body = DictScan.upsert_key_value(widget_body, "/AP", ap_dict)
+        end
+
+        # Set /AS based on the value - use the EXACT same normalization logic as widget creation
+        # This ensures consistency between /V and /AS
+        # Normalize value: "Yes" if truthy (Yes, "/Yes", true, etc.), otherwise "Off"
+        value_str = @new_value.to_s
+        is_checked = value_str == "Yes" || value_str == "/Yes" || value_str == "true" || @new_value == true
+        normalized_value = is_checked ? "Yes" : "Off"
+
+        # Set /AS to match normalized value (same as what was set for /V in widget creation)
+        as_value = if normalized_value == "Yes"
+                     "/Yes"
+                   else
+                     "/Off"
+                   end
+
+        widget_body = if widget_body.include?("/AS")
+                        DictScan.replace_key_value(widget_body, "/AS", as_value)
+                      else
+                        DictScan.upsert_key_value(widget_body, "/AS", as_value)
+                      end
+
+        apply_patch(widget_ref, widget_body, original_widget_body)
+      end
+
+      def create_checkbox_yes_appearance(width, height)
+        # Create a form XObject that draws a checked checkbox
+        # Box outline + checkmark
+        # Scale to match width and height
+        # Simple appearance: draw a box and a checkmark
+        # For simplicity, use PDF drawing operators
+        # Box: rectangle from (0,0) to (width, height)
+        # Checkmark: simple path drawing
+
+        # PDF content stream for checked checkbox
+        # Draw just the checkmark (no box border)
+        border_width = [width * 0.08, height * 0.08].min
+
+        # Calculate checkmark path
+        check_x1 = width * 0.25
+        check_y1 = height * 0.45
+        check_x2 = width * 0.45
+        check_y2 = height * 0.25
+        check_x3 = width * 0.75
+        check_y3 = height * 0.75
+
+        content_stream = "q\n"
+        content_stream += "0 0 0 rg\n" # Black color (darker)
+        content_stream += "#{border_width} w\n" # Line width
+        # Draw checkmark only (no box border)
+        content_stream += "#{check_x1} #{check_y1} m\n"
+        content_stream += "#{check_x2} #{check_y2} l\n"
+        content_stream += "#{check_x3} #{check_y3} l\n"
+        content_stream += "S\n" # Stroke
+        content_stream += "Q\n"
+
+        build_form_xobject(content_stream, width, height)
+      end
+
+      def create_checkbox_off_appearance(width, height)
+        # Create a form XObject for unchecked checkbox
+        # Empty appearance (no border, no checkmark) - viewer will draw default checkbox
+
+        content_stream = "q\n"
+        # Empty appearance for unchecked state
+        content_stream += "Q\n"
+
+        build_form_xobject(content_stream, width, height)
+      end
+
+      def build_form_xobject(content_stream, width, height)
+        # Build a Form XObject dictionary with the given content stream
+        dict = "<<\n"
+        dict += "  /Type /XObject\n"
+        dict += "  /Subtype /Form\n"
+        dict += "  /BBox [0 0 #{width} #{height}]\n"
+        dict += "  /Length #{content_stream.bytesize}\n"
+        dict += ">>\n"
+        dict += "stream\n"
+        dict += content_stream
+        dict += "\nendstream"
+
+        dict
+      end
     end
   end
 end

data/lib/acro_that/dict_scan.rb

@@ -130,6 +130,42 @@ module AcroThat
       end
     end
 
+    # Format a metadata key as a PDF dictionary key (ensure it starts with /)
+    def format_pdf_key(key)
+      key_str = key.to_s
+      key_str.start_with?("/") ? key_str : "/#{key_str}"
+    end
+
+    # Format a metadata value appropriately for PDF
+    def format_pdf_value(value)
+      case value
+      when Integer, Float
+        value.to_s
+      when String
+        # If it looks like a PDF string (starts with parenthesis or angle bracket), use as-is
+        if value.start_with?("(") || value.start_with?("<") || value.start_with?("/")
+          value
+        else
+          # Otherwise encode as a PDF string
+          encode_pdf_string(value)
+        end
+      when Array
+        # Array format: [item1 item2 item3]
+        items = value.map { |v| format_pdf_value(v) }.join(" ")
+        "[#{items}]"
+      when Hash
+        # Dictionary format: << /Key1 value1 /Key2 value2 >>
+        dict = value.map do |k, v|
+          pdf_key = format_pdf_key(k)
+          pdf_val = format_pdf_value(v)
+          "  #{pdf_key} #{pdf_val}"
+        end.join("\n")
+        "<<\n#{dict}\n>>"
+      else
+        value.to_s
+      end
+    end
+
     def value_token_after(key, dict_src)
       # Find key followed by delimiter (whitespace, (, <, [, /)
       # Use regex to ensure key is a complete token
@@ -335,6 +371,19 @@ module AcroThat
       ff_value.anybits?(0x1000)
     end
 
+    # Parse a box array (MediaBox, CropBox, ArtBox, BleedBox, TrimBox, etc.)
+    # Returns a hash with keys :llx, :lly, :urx, :ury, or nil if not found/invalid
+    def parse_box(body, box_type)
+      pattern = %r{/#{box_type}\s*\[(.*?)\]}
+      return nil unless body =~ pattern
+
+      box_values = ::Regexp.last_match(1).scan(/[-+]?\d*\.?\d+/).map(&:to_f)
+      return nil unless box_values.length == 4
+
+      llx, lly, urx, ury = box_values
+      { llx: llx, lly: lly, urx: urx, ury: ury }
+    end
+
     # Remove /AP (appearance stream) entry from a dictionary
     def remove_appearance_stream(dict_body)
       return dict_body unless dict_body&.include?("/AP")

data/lib/acro_that/document.rb

@@ -84,58 +84,19 @@ module AcroThat
         # Extract MediaBox, CropBox, or ArtBox for dimensions
         width = nil
         height = nil
-        media_box = nil
-        crop_box = nil
-        art_box = nil
-        bleed_box = nil
-        trim_box = nil
-
-        # Try MediaBox first (most common)
-        if body =~ %r{/MediaBox\s*\[(.*?)\]}
-          box_values = ::Regexp.last_match(1).scan(/[-+]?\d*\.?\d+/).map(&:to_f)
-          if box_values.length == 4
-            llx, lly, urx, ury = box_values
-            width = urx - llx
-            height = ury - lly
-            media_box = { llx: llx, lly: lly, urx: urx, ury: ury }
-          end
-        end
-
-        # Try CropBox
-        if body =~ %r{/CropBox\s*\[(.*?)\]}
-          box_values = ::Regexp.last_match(1).scan(/[-+]?\d*\.?\d+/).map(&:to_f)
-          if box_values.length == 4
-            llx, lly, urx, ury = box_values
-            crop_box = { llx: llx, lly: lly, urx: urx, ury: ury }
-          end
-        end
-
-        # Try ArtBox
-        if body =~ %r{/ArtBox\s*\[(.*?)\]}
-          box_values = ::Regexp.last_match(1).scan(/[-+]?\d*\.?\d+/).map(&:to_f)
-          if box_values.length == 4
-            llx, lly, urx, ury = box_values
-            art_box = { llx: llx, lly: lly, urx: urx, ury: ury }
-          end
-        end
 
-        # Try BleedBox
-        if body =~ %r{/BleedBox\s*\[(.*?)\]}
-          box_values = ::Regexp.last_match(1).scan(/[-+]?\d*\.?\d+/).map(&:to_f)
-          if box_values.length == 4
-            llx, lly, urx, ury = box_values
-            bleed_box = { llx: llx, lly: lly, urx: urx, ury: ury }
-          end
+        # Try MediaBox first (most common) - also extract width/height
+        media_box = DictScan.parse_box(body, "MediaBox")
+        if media_box
+          width = media_box[:urx] - media_box[:llx]
+          height = media_box[:ury] - media_box[:lly]
         end
 
-        # Try TrimBox
-        if body =~ %r{/TrimBox\s*\[(.*?)\]}
-          box_values = ::Regexp.last_match(1).scan(/[-+]?\d*\.?\d+/).map(&:to_f)
-          if box_values.length == 4
-            llx, lly, urx, ury = box_values
-            trim_box = { llx: llx, lly: lly, urx: urx, ury: ury }
-          end
-        end
+        # Parse other box types
+        crop_box = DictScan.parse_box(body, "CropBox")
+        art_box = DictScan.parse_box(body, "ArtBox")
+        bleed_box = DictScan.parse_box(body, "BleedBox")
+        trim_box = DictScan.parse_box(body, "TrimBox")
 
         # Extract rotation
         rotate = nil
@@ -203,7 +164,7 @@ module AcroThat
         next unless body
 
         is_widget = DictScan.is_widget?(body)
-        
+
         # Collect widget information if this is a widget
         if is_widget
           # Extract position from widget
@@ -266,6 +227,11 @@ module AcroThat
         ft_tok = body.include?("/FT") ? DictScan.value_token_after("/FT", body) : nil
         type = ft_tok
 
+        # Normalize button field values: "Yes" -> "/Yes" to match PDF name conventions
+        if type == "/Btn" && value == "Yes"
+          value = "/Yes"
+        end
+
         position = {}
         if is_widget
           rect_tok = DictScan.value_token_after("/Rect", body)

data/lib/acro_that/field.rb

@@ -9,6 +9,8 @@ module AcroThat
     TYPES = {
       text: "/Tx",
       button: "/Btn",
+      checkbox: "/Btn",
+      radio: "/Btn",
       choice: "/Ch",
       signature: "/Sig"
     }.freeze

data/lib/acro_that/page.rb

@@ -88,4 +88,3 @@ module AcroThat
     end
   end
 end
-

data/lib/acro_that/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AcroThat
-  VERSION = "0.1.4"
+  VERSION = "0.1.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acro_that
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Michael Wynkoop