If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/prawnpdf/prawn shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 3w ago
• 22+ active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 63% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live prawnpdf/prawn repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/prawnpdf/prawn.

What it runs against: a local clone of prawnpdf/prawn — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in prawnpdf/prawn | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 51 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of prawnpdf/prawn. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/prawnpdf/prawn.git
#   cd prawn
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of prawnpdf/prawn and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "prawnpdf/prawn(\\.git)?\\b" \\
  && ok "origin remote is prawnpdf/prawn" \\
  || miss "origin remote is not prawnpdf/prawn (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/prawn.rb" \\
  && ok "lib/prawn.rb" \\
  || miss "missing critical file: lib/prawn.rb"
test -f "lib/prawn/document.rb" \\
  && ok "lib/prawn/document.rb" \\
  || miss "missing critical file: lib/prawn/document.rb"
test -f "lib/prawn/graphics.rb" \\
  && ok "lib/prawn/graphics.rb" \\
  || miss "missing critical file: lib/prawn/graphics.rb"
test -f "lib/prawn/font.rb" \\
  && ok "lib/prawn/font.rb" \\
  || miss "missing critical file: lib/prawn/font.rb"
test -f "lib/prawn/document/bounding_box.rb" \\
  && ok "lib/prawn/document/bounding_box.rb" \\
  || miss "missing critical file: lib/prawn/document/bounding_box.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 51 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~21d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/prawnpdf/prawn"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Prawn is a pure Ruby PDF generation library that creates PDF documents programmatically without external dependencies. It provides vector drawing (lines, polygons, curves), text rendering with TrueType/AFM font support, image embedding (PNG/JPG), and security features like encryption—enabling developers to generate complex PDFs directly from Ruby code. Monolithic structure: core PDF generation logic in lib/, font management in data/fonts/, benchmarks in bench/, test fixtures in data/images/. Font support split between AFM (Adobe Font Metrics, legacy), TTF (TrueType), and OTF (OpenType). No src/lib separation—pure Ruby implementation without compiled extensions.

Ruby developers and Rails applications that need to generate dynamic PDFs (invoices, reports, certificates, documents) without relying on external PDF engines like wkhtmltopdf. Users who need fine-grained control over layout, fonts, and document structure prefer Prawn over HTML-to-PDF converters.

Prawn is production-ready and actively maintained. The repository shows a full CI/CD pipeline (.github/workflows/ci.yml), comprehensive test coverage (implied by .rspec configuration), 6 released versions tracked in checksums/, and regular maintenance evidenced by the maintained badge in README. Latest release is 2.5.0, indicating ongoing development.

Low risk overall, but dependency on custom font handling (data/fonts/ contains 20+ font files requiring maintenance). The monolithic single-repo approach means all features are tightly coupled. Maintainer bus factor exists (check contributor list), though the codebase is stable and well-tested. No breaking changes visible in recent CHANGELOG entries, but UTF-8/i18n complexity could introduce subtle bugs.

Repository is actively maintained with CI running on every commit. The presence of 6 recent version checksums (through 2.5.0) and the maintained badge indicate ongoing releases. Contributing guidelines (CONTRIBUTING.md) are current, suggesting the project welcomes PRs. No major architectural refactoring evident; improvements appear incremental and backward-compatible.

git clone https://github.com/prawnpdf/prawn.git
cd prawn
bundle install
bundle exec rake spec

The Gemfile drives dependency management (standard Ruby/Bundler setup). Tests use RSpec (.rspec config file present). No external services required for local development.

Daily commands:

bundle exec rake spec          # Run full test suite
bundle exec rake bench         # Run performance benchmarks
rake --tasks                   # List all available tasks

No development server needed—Prawn is a library, not an application. Benchmarks in bench/ (afm_text_bench.rb, ttf_text_bench.rb, table_bench.rb) can be run to measure performance.

• lib/prawn.rb — Main entry point and gem loader that initializes all Prawn functionality; every contributor must understand the public API surface exposed here.
• lib/prawn/document.rb — Core Document class that orchestrates PDF generation; the primary abstraction every PDF operation flows through.
• lib/prawn/graphics.rb — Graphics rendering module that handles vector drawing, colors, and PDF operators; critical for understanding how shapes and styles are applied.
• lib/prawn/font.rb — Font abstraction layer that manages font loading, metrics, and encoding; essential for text rendering features.
• lib/prawn/document/bounding_box.rb — Bounding box implementation providing layout constraints and coordinate system management; fundamental for all positioning logic.
• lib/prawn/fonts.rb — Font factory and registry managing AFM, TTF, TTC, OTF, and DFONT format support; required to add new font type support.

• Document (Ruby classes, PDF object hierarchy) — Coordinates PDF page creation, state management (current page, position, font, color), and rendering pipeline.
  • Failure mode: Invalid PDF if page tree or content streams are

Add a new graphics drawing method (e.g., custom shape)

1. Add the method to lib/prawn/graphics.rb or create a new graphics submodule (lib/prawn/graphics.rb)
2. Implement the PDF operator logic using current_path and stroke/fill helpers (lib/prawn/graphics.rb)
3. Test with spec/prawn/graphics/test_name.rb using the document object's public methods (spec/prawn/graphics/)
4. Document in CHANGELOG.md and add example to manual if user-facing (CHANGELOG.md)

Add support for a new font format

1. Create a new parser class in lib/prawn/fonts/new_format.rb inheriting from a relevant font base (lib/prawn/fonts/new_format.rb)
2. Implement required methods: glyph_width, character_count, encode_text, and build_to_unicode_cmap (lib/prawn/fonts/new_format.rb)
3. Register the format in lib/prawn/fonts.rb by adding a case branch in the font loading logic (lib/prawn/fonts.rb)
4. Add test fixtures to data/fonts/ and create comprehensive tests in spec/prawn/fonts/ (spec/prawn/fonts/)

Implement a new text layout feature (e.g., custom text flow)

1. Create a new layout class in lib/prawn/document/ or extend bounding_box.rb (lib/prawn/document/bounding_box.rb)
2. Implement text measurement using Font#compute_width_of and positioning via Document#move_to (lib/prawn/font.rb)
3. Expose as a public Document method that coordinates layout, wrapping, and rendering (lib/prawn/document.rb)
4. Write tests validating text wrapping, overflow, and final document dimensions (spec/prawn/document/)

Add image embedding with a new codec or format

1. Create codec logic in lib/prawn/images/ (if it doesn't exist) for format parsing and color space detection (lib/prawn/images/)
2. Register codec in Document's image handling pipeline (lib/prawn/document.rb)
3. Add test images to data/images/ and unit tests to spec/prawn/ (spec/prawn/)
4. Document new format support and update README.md feature list (README.md)

• Pure Ruby implementation — Eliminates C dependencies, maximizes portability across Ruby implementations and platforms; trade-off is raw rendering speed vs. C extensions.
• PDF 1.4+ operator model — Direct PDF primitive emission gives fine-grained control over output and enables advanced features (blend modes, patterns, encryption) without high-level abstraction overhead.
• Modular font architecture (AFM, TTF, TTC, OTF, DFONT) — Supports diverse font sources—builtin Adobe fonts for simplicity, TrueType/OpenType for rich typography, DFont for macOS compatibility.
• Bounding box coordinate transformation — Simplifies layout logic by allowing nested coordinate systems; each box translates to local origin, reducing calculation errors in complex layouts.

• Pure Ruby vs. C extensions

  • Why: Maximize compatibility and ease of installation; no compilation step required.
  • Consequence: Performance is slower than compiled libraries; suitable for batch PDF generation, not real-time high-throughput scenarios.

• Direct PDF operator emission vs. high-level abstraction

  • Why: Enables advanced PDF features and fine control; simpler mental model for developers familiar with PDF spec.
  • Consequence: Lower-level API is more verbose for simple tasks; requires understanding PDF operators for custom drawing.

• Embedding fonts vs. subsetting

  • Why: Ensures text is always searchable and preserves all glyphs; simpler implementation.
  • Consequence: Larger PDF file sizes, especially with complex fonts; memory overhead during generation.

• Synchronous, single-threaded rendering

  • Why: Simpler state management and PDF object ordering; no race conditions on page tree or content streams.
  • Consequence: Cannot parallelize multi-page PDFs; generation is sequential and blocking.

• Real-time streaming PDF generation (PDFs must be fully assembled before writing)
• PDF form editing or incremental updates (read-only, generation-only model)
• Direct SVG-to-PDF conversion (geometric primitives only)
• WCAG accessibility tagging (no tagged PDF support for screen readers)
• Database-backed asset management (assumes assets provided by caller)

Font licensing: AFM fonts (Helvetica, Times, Courier) are system fonts; TTF fonts (DejaVuSans, Dustismo) have specific licenses (check data/fonts/MustRead.html). PDF spec complexity: low-level PDF object generation requires understanding PDF spec primitives—mistakes break PDF readers. Text wrapping i18n: right-to-left text and fallback fonts add complexity; test thoroughly with non-ASCII strings. Image encoding: PNG type 6 and 16-bit color require specific test fixtures (see bench/png_type_6.rb); wrong encoding breaks rendering. No external services required for basic usage, but embedding custom fonts requires license compliance checks.

• Adobe Font Metrics (AFM) — Prawn bundles AFM files (data/fonts/*.afm) for standard PDF fonts (Helvetica, Times, Courier). Understanding AFM vs TTF lets you optimize font loading and embedding strategies.
• TrueType Font (TTF) Subsetting & Embedding — Prawn embeds TTF fonts into PDFs to ensure consistent rendering across systems. The library must parse TTF tables and subset glyphs used in the document to minimize file size.
• PDF Object Tree & Content Streams — Prawn generates low-level PDF objects (dictionaries, arrays, streams) that form the PDF spec structure. Understanding the object model is essential for debugging rendering issues or adding custom PDF features.
• Text Layout & Line Breaking Algorithms — Prawn implements text wrapping, justification, and flow (especially for i18n and RTL text). The layout engine handles Unicode normalization, fallback fonts, and paragraph breaking—critical for correct document output.
• PNG Image Encoding & 16-bit Color Depth — Prawn embeds PNG/JPG images with support for alpha channels and 16-bit color (see bench/png_type_6.rb). Misunderstanding color depth or alpha handling breaks image rendering.
• PDF Encryption & Password Protection — Prawn offers security features (mentioned in README) including AES encryption. Understanding PDF encryption algorithms is necessary for correct implementation and security audits.
• Right-to-Left (RTL) Text & Bidirectional Unicode — Prawn supports RTL rendering for Arabic, Hebrew, etc. (mentioned in README under i18n). This requires understanding Unicode bidirectional algorithm and fallback font cascading.

• ruby-vips/ruby-vips — Image processing library often used with Prawn to pre-process images before embedding (scaling, format conversion, optimization)
• jnunemaker/grit — Historical dependency for some Prawn users generating PDFs from Git data; represents typical Prawn use case in Ruby ecosystem
• rails/rails — Prawn is commonly integrated into Rails apps via view templates (e.g., action_view renderers) to generate PDF responses
• Homebrew/homebrew-core — Prawn depends on system fonts; Homebrew often used to install required font packages for production deployments
• wkhtmltopdf/wkhtmltopdf — Direct alternative for HTML-to-PDF (which Prawn explicitly does NOT do), mentioned in README as incompatible philosophy

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for PNG image handling with different bit depths

The repo contains multiple PNG test images with varying bit depths (16bit.png, indexed_color.png, indexed_transparency.png) and corresponding .alpha and .color files in data/images/, but there's no clear indication of test files validating these edge cases. Prawn's image handling is critical for PDF generation reliability. Adding dedicated unit tests for different PNG formats (16-bit, indexed color, interlaced, transparency) would improve robustness and catch regressions.

• [ ] Create spec/images/png_handling_spec.rb for PNG-specific test cases
• [ ] Add tests for 16-bit PNG rendering using data/images/16bit.png
• [ ] Add tests for indexed color PNGs using data/images/indexed_color.png and indexed_transparency.png
• [ ] Add tests for interlaced PNG handling using data/images/dice_interlaced.png
• [ ] Verify alpha channel handling for all PNG variants
• [ ] Run tests against bench/png_type_6.rb and bench/png_type_6_objects.rb scenarios

Create integration tests for embedded font rendering with various character sets

The repo includes multiple font files (TTF, OTF, DFONT, AFM) and a Chinese font (gkai00mp.ttf), but there's no visible integration test suite validating that all these fonts render correctly with different character sets and encodings. This is particularly important for the TrueType font embedding feature. Adding comprehensive font rendering tests would catch encoding/embedding issues early.

• [ ] Create spec/fonts/font_rendering_integration_spec.rb
• [ ] Add tests for TTF fonts (DejaVuSans.ttf, Dustismo_Roman.ttf) rendering ASCII and Unicode
• [ ] Add tests for OTF font rendering (Bodoni-Book.otf)
• [ ] Add tests for CJK font rendering using data/fonts/gkai00mp.ttf with Chinese characters
• [ ] Add tests for embedded vs. built-in font consistency
• [ ] Test font subsetting and performance using bench/ttf_text_bench.rb as reference

Add CI workflow tests for gem build and checksum verification

The repo contains checksum files for multiple released versions (prawn-2.2.0 through prawn-2.5.0) in the checksums/ directory, but .github/workflows/ci.yml may not include explicit gem building and checksum validation steps. Adding a CI workflow that verifies gem builds produce consistent, verifiable artifacts would improve release reliability and security.

• [ ] Review .github/workflows/ci.yml for gem build steps
• [ ] Add CI job to build gem and compute SHA512 checksum
• [ ] Compare computed checksum against checksums/ directory entries for released versions
• [ ] Add test to verify Gemfile.lock and gemspec consistency
• [ ] Document checksum verification process in CONTRIBUTING.md
• [ ] Add CI step to validate no uncommitted changes to checksums/ after build

• Add comprehensive documentation for custom font embedding. data/fonts/ has 20+ fonts but no in-depth guide for users to embed their own. Write a 'Custom Fonts' section in README.md with code examples for TTF, OTF, and AFM formats.: Low—documentation only, no code changes needed
• Expand table benchmarks. bench/table_bench.rb exists but only tests basic cases. Add benchmarks for large tables (1000+ rows), merged cells, and complex styling to catch performance regressions early.: Medium—add new benchmark scenarios, run and document results
• Create regression tests for image embedding edge cases. bench/png_type_6.rb hints at PNG type 6 complexity. Add spec/ tests for 16-bit color images, alpha channels, and various PNG/JPG profiles to prevent future embedding bugs.: Medium—requires creating test fixtures and comprehensive specs

Prawn maintains a reasonable security posture as a PDF generation library. The main security concern is the embedded test certificate in the repository, which requires verification. The codebase lacks explicit security documentation (SECURITY.md), which is important for responsible vulnerability disclosure in open-source projects. The included font files and test assets appear legitimate but should be documented. No evidence of hardcoded secrets, SQL injection risks, or XSS vulnerabilities was found in the file structure. The project uses standard CI/CD workflows (GitHub Actions) which is a positive security practice. Overall, this is a low-risk library focused on PDF generation without complex external dependencies visible in the provided structure.

• Medium · Embedded Test Certificate in Repository — certs/pointlessone.pem. The file 'certs/pointlessone.pem' contains a certificate that is committed to the repository. While this appears to be a test certificate based on the name, storing certificates in version control can pose security risks if not properly managed, especially if credentials or keys become associated with them. Fix: Verify this is a public test certificate with no sensitive data. If it contains any private keys, remove it immediately. Consider storing certificates in a secure configuration management system or environment variables for testing purposes.
• Low · Missing CONTRIBUTING.md Security Guidelines — Repository root. While CONTRIBUTING.md exists, there is no evidence of security-focused contribution guidelines or security policy documentation (e.g., SECURITY.md). This is important for open-source projects to coordinate responsible disclosure of vulnerabilities. Fix: Create a SECURITY.md file documenting how users should report security vulnerabilities privately rather than through public issue trackers.
• Low · Dual License GPLv2/GPLv3 Without Clear Primary License — COPYING, GPLv2, GPLv3, LICENSE files. The repository includes both GPLv2 and GPLv3 licenses with a separate COPYING file. This dual-licensing approach may create confusion about license compatibility and obligations, though not a direct security vulnerability. Fix: Clarify the primary license in README.md and consider consolidating license documentation. Ensure all dependencies are compatible with the chosen license(s).
• Low · Font Files from Untrusted Sources — data/fonts/. The repository includes multiple font files (TTF, OTF, DFONT) embedded in the data directory. Font parsing can be a vector for security issues if processing untrusted fonts, though these appear to be standard fonts. Fix: Document the source and verification status of all embedded font files. Consider using system fonts when possible or document font validation procedures in security guidelines.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.