pdfrb 0.1.0

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+--markup markdown
+--files CHANGELOG.md,LICENSE
+--output-dir doc/yard

data/CHANGELOG.md

@@ -0,0 +1,226 @@
+# Changelog
+
+All notable changes to the pdfrb gem will be documented in this file.
+
+## [Unreleased]
+
+### Added — 2026-08-01 (layout engine session)
+
+**Full layout engine + XSL-FO pipeline (TODO.layout 01–17).**
+
+* `Pdfrb::Layout::FontMetrics` (AfmMetrics + TrueTypeMetrics) +
+  `GlyphMeasurer` — real glyph widths for the 14 standard Type1 fonts
+  (via Adobe AFM, now vendored) and any TTF/OTF (via head/hhea/hmtx/
+  cmap/OS-2 table parsers). Replaces the 0.5×font_size estimate; matches
+  Adobe metrics to 0.01pt.
+* `Pdfrb::Layout::TextLayout` — Greedy and Knuth-Plass line breaking
+  with real glyph metrics, alignment (left/right/center/justify),
+  hyphenation hooks, and break-opportunity finder that handles
+  multi-run paragraphs (bold spans, hyperlinks).
+* `Pdfrb::Layout::PageFlow` + `Flowable` + `Frame` — flowing-text
+  engine with split-on-page-break for paragraphs/tables, keep-together,
+  page-break-before/after, and a two-pass static-content render for
+  `fo:page-number` and `fo:page-number-citation`.
+* `Pdfrb::Layout::Table` + `TableLayout::Fixed` + `TableLayout::Auto`
+  + `TableFlowable` + `TableRenderer` — fixed-width and CSS 2.1
+  auto-width column layout, row/col spans, header row repeat across
+  page breaks.
+* `Pdfrb::Layout::PageTemplate` + `Region` + `PageSequenceMaster` +
+  `StaticContent` — page geometry with 5 regions (body/before/after/
+  start/end) and odd/even/first/last/blank page-template selection.
+* `Pdfrb::Layout::Leader` + `FieldRun`s (PageNumberField,
+  PageNumberCitationField, PageCountField) — TOC leaders and
+  page-number fields, resolved via the two-pass layout.
+* `Pdfrb::Layout::SVG::*` — SVG → PDF renderer supporting path data,
+  rect/circle/ellipse/line/polyline/polygon, text, image (with
+  data: URI), nested groups with transforms, and presentational
+  styling. New SVG element = one Element subclass.
+* `Pdfrb::Layout::FO::*` — XSL-FO parser (REXML-based) + PropertyResolver
+  (inheritance + shorthand expansion) + MasterBuilder + FlowBuilder +
+  Compiler. End-to-end: `Pdfrb.render_fo(xml, io:)` produces a PDF.
+* `Pdfrb.parse_fo(xml)` and `Pdfrb.render_fo(xml, path_or_io:)` top-level
+  entry points.
+
+### Fixed — 2026-08-01 (layout engine session)
+
+* `Pdfrb::Font::AFMParser` — handle `StartCharMetrics 315` (with count),
+  not just bare `StartCharMetrics`.
+* `Pdfrb::Font::GlyphList` — accept both canonical hex format and
+  literal-Unicode repackagings of glyphlist.txt.
+* `Pdfrb::Filter::FlateDecode` — `out << unfiltered.pack("C*")` so PNG
+  predictor output is concatenated correctly (was appending Array to
+  String).
+* `Pdfrb::Model::Cos::Stream#decoded_stream` — use type-checked
+  `as_filter_list` / `as_parms_list` helpers instead of `Array(...)`,
+  which silently converts a Hash `DecodeParms` to `[[:k, :v], ...]`
+  and bypasses the predictor.
+* `Pdfrb::Source::ObjectReader#load_from_objstm` — unpack the
+  `[oid, value]` pair from ObjectStreamReader and re-wrap via
+  `document.wrap` so type-dispatch (Catalog, Pages, etc.) works for
+  compressed objects.
+* `Pdfrb::Document::Pages#count` — dereference Reference-typed `/Count`
+  before treating as Integer; fall back to walking the Kids tree.
+* `Pdfrb::Document::Pages#walk` — robust against Reference-typed
+  `/Kids` arrays (common in FOP output).
+
+### Added — 2026-07-30 (session 2)
+
+**Phase 2 — COS layer (TODOs 08–14).**
+
+* `Pdfrb::Model::Object` — base wrapper with `value`, `oid`, `gen`,
+  `document`; `indirect?`, `must_be_indirect?`, `deref`, `pdf_type`.
+* `Pdfrb::Model::Reference` — frozen value object by `(oid, gen)`,
+  hashable, comparable, serialises as `"5 0 R"`.
+* `Pdfrb::Model::PdfArray < Object` — Enumerable wrapper around an
+  Array of PDF values, with full mutation API and oid/gen/document
+  support for indirect arrays.
+* `Pdfrb::Model::Rectangle` — immutable `[llx lly urx ury]` value
+  with `width`, `height`, `left`/`right`/`top`/`bottom`.
+* `Pdfrb::Model::Matrix` — immutable `[a b c d e f]` affine with the
+  PDF-correct column-vector composition (`M1 * M2` applies M2 then
+  M1) and translate/scale/rotate/skew factories.
+* `Pdfrb::Model::Date` — PDF date `D:YYYYMMDDHHmmSSOHH'mm'` <-> `Time`.
+* `Pdfrb::Model::Cos::NameEncoding` — Symbol <-> `/...` wire format
+  with `#xx` escape encode/decode.
+* `Pdfrb::Model::Cos::StringEncoding` — text/binary string helpers:
+  UTF-16BE BOM detection, full PDFDocEncoding table (Appendix D.2),
+  PDFDocEncoding <-> UTF-8 conversion.
+* `Pdfrb::Model::Cos::Fields::Field` — typed field metadata with
+  `resolved_types`, `valid_value?`, Arlington slot.
+* `Pdfrb::Model::Cos::Fields` converters: Dictionary, Array, String,
+  PDFByteString, Date, Rectangle, Integer — selected by `usable_for?`
+  and applied in order via `Fields.apply`.
+* `Pdfrb::Model::Cos::Dictionary` — base class with `define_field`,
+  `field`, `each_field`, type registry (`register_type`/`lookup_type`),
+  `[]`/`[]=` with full pipeline (default -> dereference -> unbox ->
+  convert), `each`/`each_raw`, `validate`.
+* `Pdfrb::Model::Cos::Stream < Dictionary` — raw-bytes holder with
+  `decoded_stream` / `encoded_stream=` that drives `Pdfrb::Filter`.
+* `Pdfrb::Document` — top-level facade with `wrap`, `add`,
+  `object`/`dereference`, `register_listener`/`dispatch_message`.
+
+**Phase 5 partial — Filters (TODOs 34–36).**
+
+* `Pdfrb::Filter` module + registry; `Filter.apply(bytes, filters:,
+  parms:, direction:, document:)` chains decoders/encoders.
+* `Pdfrb::Filter::Base` — included interface; subclasses call
+  `register_as "Name"`.
+* `Pdfrb::Filter::FlateDecode` — zlib + PNG predictor unfiltering
+  (None/Sub/Up/Average/Paeth).
+* `Pdfrb::Filter::ASCIIHexDecode` — hex <-> bytes with EOD marker `>`.
+
+**Phase 6 — Arlington layer (TODOs 45–53).**
+
+* Vendored `data/pdfrb/arlington/latest/*.tsv` — 613 TSV files from
+  `~/src/pdfa/arlington-pdf-model/tsv/latest/`. Single source of
+  truth for PDF object model.
+* `Pdfrb::Arlington::Loader` — lazy TSV reader with `(name, version)`
+  memoisation. `object_definition("Catalog")` returns a parsed
+  `ObjectDefinition`.
+* `Pdfrb::Arlington::ObjectDefinition` / `FieldDefinition` — typed
+  records for one TSV / one row. FieldDefinition exposes bare types,
+  required/predicate-split required, links, possible-value lists.
+* `Pdfrb::Arlington::Type` — the 17 type symbols + validity check.
+* `Pdfrb::Arlington::PdfVersion` — Comparable value object with full
+  `.from_tsv_cell` parsing (plain, `fn:Extension(name, ver)`, `fn:Eval`).
+* `Pdfrb::Arlington::Predicate::Lexer/Parser/AST/Evaluator/Context`
+  — full `fn:` mini-DSL: tokeniser, recursive-descent parser
+  (logical ops require parens per spec), evaluator with `@key`,
+  `parent::`, `trailer::` path resolution, and BinOp/UnaryOp/LogicalOp
+  evaluation.
+* `Pdfrb::Arlington::Predicate::Functions` registry + 6 built-in
+  groups (OCP: one file per category):
+  - `version.rb` — SinceVersion, BeforeVersion, Deprecated,
+    IsPDFVersion, Extension.
+  - `presence.rb` — IsRequired, IsPresent, NotPresent.
+  - `logical.rb` — Eval, Not, And, Or.
+  - `arithmetic.rb` — ArrayLength, StringLength, RequiredValue,
+    BitSet, BitsClear, BitsSet, KeyNameIsColorant, NoCycle.
+  - `reference.rb` — MustBeDirect, MustBeIndirect.
+  - `file.rb` — FileSize.
+* `Dictionary.arlington_object "Name"` — pulls field metadata from
+  the matching TSV at class-load time and feeds it through
+  `define_field`. Type mapping from the 17 Arlington symbols to Ruby
+  classes (booleans -> [TrueClass, FalseClass], name -> Symbol,
+  rectangle -> Rectangle, etc.).
+
+**Phase 15 partial — fixture corpus sourcing (TODOs 148, 158).**
+
+* `claricle/pdf-core-examples` forked from
+  `pdf-association/pdf-core-examples` (private). The `ci` team is on
+  both `claricle/pdfrb` and `claricle/pdf-core-examples`, so
+  `claricle-ci` (already on `ci`) can pull examples in CI using
+  `CLARICLE_CI_PAT_TOKEN`.
+* TODO 148 updated: corpus is fetched (not committed) via
+  `rake fixtures:pull`; `spec/fixtures/pdf-core-examples/` is
+  gitignored.
+* TODO 158 added: GitHub Actions workflow that pulls the corpus
+  before rspec.
+
+### Stats
+
+* 163 specs, 0 failures, 0 rubocop offenses.
+* 39 source files under `lib/`, 12 spec files under `spec/`.
+* 613 vendored TSVs under `data/pdfrb/arlington/latest/`.
+* 158 TODO files in `TODO.general-rels/` (added 158 for CI).
+
+### Code quality
+
+* Pure Ruby `autoload` everywhere; no `require_relative` in lib/.
+* No `respond_to?` for type checks, no `instance_variable_set/get`,
+  no `send` to private methods.
+* `# frozen_string_literal: true` on every `.rb`.
+* Real instances in specs, never `double()`.
+
+---
+
+### Added — 2026-07-30
+
+**0.1.0 — initial scaffold.**
+
+The pdfrb gem is created as a pure-Ruby PDF library modelled on the
+sibling `postscript` gem and HexaPDF, with the PDF object model driven
+directly by the vendored Arlington PDF Model TSVs.
+
+* Project skeleton: gemspec, Gemfile, Rakefile (default = spec +
+  rubocop), `.rspec`, `.rubocop.yml` (Cimas base + rspec/performance/
+  rake plugins), `.gitignore`, `.gitattributes` (TSV EOL=LF).
+* `Pdfrb::PdfConstants` — PDF lexical constants (header magic, EOL,
+  whitespace, delimiters, version enumeration, keywords) per
+  ISO 32000-2:2020 s7.2.
+* `Pdfrb::Error` hierarchy — typed errors for every failure mode:
+  `ParseError` (with `source_position`), `LexError`, `SyntaxError`,
+  `MalformedPdfError` (with `recovered?`), `SerializeError`,
+  `FilterError` (with `filter_name`), `EncryptionError`,
+  `UnsupportedVersionError`, `ObjectReferenceError` (with oid/gen),
+  `ValidationError` (with field/predicate names).
+* `Pdfrb::Configuration` — per-Document frozen settings hash with
+  deep-merge. Defaults for malformed-PDF recovery, auto-decrypt,
+  invalid-string handling.
+* `Pdfrb::DataDir` — resolves paths under the gem's bundled
+  `data/pdfrb/` (Arlington TSVs, AFM, ICC, etc.).
+* Top-level `lib/pdfrb.rb` autoload tree for all planned namespaces
+  (Source, Model, Arlington, Filter, Content, Encryption,
+  DigitalSignature, Font, FontLoader, ImageLoader, Layout, Task,
+  Serializer, Writer, Importer, Revision(s), XrefSection, Document,
+  Composer, CLI). Lazy: file not loaded until constant accessed.
+* `Rakefile` `arlington:refresh` task to re-vendor TSVs from
+  `~/src/pdfa/arlington-pdf-model/tsv/latest/`.
+* `CLAUDE.md` onboarding doc.
+* `TODO.general-rels/` work-breakdown structure (157 entries across
+  16 phases).
+
+### Architecture
+
+Mirrors `postscript`'s layered split (Source / Model / Serializer)
+extended for PDF's needs. The differentiator vs HexaPDF is that
+field metadata is loaded at runtime from the vendored Arlington TSVs
+(single source of truth) rather than hand-coded via `define_field`.
+
+### Code quality
+
+* Pure Ruby `autoload` everywhere; no `require_relative` in lib/.
+* No `respond_to?` for type checks, no `instance_variable_set/get`,
+  no `send` to private methods.
+* `# frozen_string_literal: true` on every `.rb`.
+* Real instances in specs, never `double()`.

data/CLAUDE.md

@@ -0,0 +1,110 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`pdfrb` is a pure-Ruby PDF library: a byte-level reader, an Arlington-model-driven typed domain model, and a serializer. The PDF object model is sourced **directly** from the vendored Arlington PDF Model TSVs (the machine-readable definition of ISO 32000-2:2020), so field metadata, version predicates, and validators stay aligned with the spec by *data*, not by hand-coded mimicry.
+
+Two-direction contract:
+- *"PDF file <=> Model"* — parse PDF bytes into a typed Model and serialize a Model back to PDF bytes. Round-trip is the correctness backbone.
+- *"API Builder Input => Model"* — `Document`, `Canvas` build a typed Model from user intent; the serializer then writes it. (Layout concerns live in the sibling `arroolio` gem.)
+
+Mirrors the layered design of the sibling `postscript` gem (PS/EPS). Architectural blueprint cross-referenced against HexaPDF.
+
+## Commands
+
+```sh
+bundle install                      # first-time setup
+bundle exec rake                    # default task: spec + rubocop
+bundle exec rspec                   # all specs
+bundle exec rspec spec/pdfrb/error_spec.rb:42   # one spec by line number
+bundle exec rubocop                 # lint
+bundle exec rubocop -A              # lint + safe autocorrect
+bundle exec rake arlington:refresh  # re-vendor TSVs from ~/src/pdfa/arlington-pdf-model/tsv/
+```
+
+Run `bin/console` (create it if missing) for an interactive prompt preloaded with `Pdfrb`.
+
+## Architecture (big picture)
+
+| Layer | Owns | File |
+|---|---|---|
+| `Pdfrb::Source` | PDF bytes → tokens → COS object graph (read direction) | `lib/pdfrb/source.rb` |
+| `Pdfrb::Model` | Typed PDF domain model: COS scalars + `Type::*` semantics | `lib/pdfrb/model.rb` |
+| `Pdfrb::Arlington` | Loads vendored TSVs; evaluates `fn:` predicates. **Drives `Model` field definitions.** | `lib/pdfrb/arlington.rb` |
+| `Pdfrb::Filter` | Stream filter pipeline (FlateDecode, LZWDecode, ...) | `lib/pdfrb/filter.rb` |
+| `Pdfrb::Content` | Content-stream operators + Canvas drawing API | `lib/pdfrb/content.rb` |
+| `Pdfrb::Serializer` | Model → PDF bytes (COS values) | `lib/pdfrb/serializer.rb` |
+| `Pdfrb::Writer` | Document → file (xref + trailer assembly) | `lib/pdfrb/writer.rb` |
+| `Pdfrb::Document` | Top-level facade | `lib/pdfrb/document.rb` |
+
+### Layering rule (MECE)
+
+Reader and Writer both depend on `Model` only. `Model` depends on `Arlington` for field metadata. `Content` extends `Model` with canvas + operators. Never shortcut across layers — the Serializer must never read bytes; the Parser must never write them.
+
+### Autoload rule
+
+Internal code uses **only** `autoload`, declared in the **immediate parent namespace's file**. Never `require_relative`, never `require "pdfrb/..."` for code in this gem (only `require` stdlib + gem deps). Create a namespace's file before adding children under it.
+
+```ruby
+# lib/pdfrb.rb
+module Pdfrb
+  autoload :Source, "pdfrb/source"     # lib/pdfrb/source.rb exists and holds Source's children autoloads
+  autoload :Model, "pdfrb/model"       # lib/pdfrb/model.rb exists and holds Model's children autoloads
+  ...
+end
+```
+
+### Arlington integration
+
+Each `Pdfrb::Model::Type::*` class declares `arlington_object "Catalog"` (or the matching TSV name). Calling it materializes `Field` objects from the vendored TSV in `data/pdfrb/arlington/latest/` and wires them into the dictionary's field set. Validation invokes predicate evaluators (`fn:IsRequired(...)`, `fn:SinceVersion(...)`, etc.).
+
+**Never hand-edit field metadata on a `Model::Type::*` class.** The TSVs are the single source of truth. If a field is wrong, fix the TSV upstream and re-run `rake arlington:refresh`.
+
+## Conventions (project-specific)
+
+- `# frozen_string_literal: true` on **every** `.rb`.
+- Immutable value objects. `freeze` in constructors where data crosses a layer boundary (mirrors `postscript`).
+- Errors: every failure mode subclasses `Pdfrb::Error` and carries typed metadata (`source_position`, `filter_name`, `oid`/`gen`, `field_name`, etc.). See `lib/pdfrb/error.rb`.
+- Specs: real instances, never `double()`. Use `Struct.new` for plain-data stand-ins. Property specs (`spec/pdfrb/round_trip_spec.rb`) are the correctness backbone.
+- Forbidden Ruby patterns (per global memory):
+  - `send` to private methods
+  - `instance_variable_set` / `instance_variable_get`
+  - `respond_to?` for type checks — use `is_a?`
+  - hand-rolled `to_h`/`from_h`/`to_json`/etc. on model classes — declare fields, let the framework serialize
+- Semantic types live under `Pdfrb::Model::Type::*` and are named after the matching Arlington TSV (e.g. `Catalog` ↔ `Catalog.tsv`).
+- Content operators follow the registry pattern: one subclass per operator, `register_as` at the bottom of the file (mirrors `postscript`'s `Model::Operators`).
+- Filters follow the same registry pattern: one subclass per filter, registered in `Pdfrb::Filter::REGISTRY`.
+- Tests live under `spec/pdfrb/` mirroring the `lib/pdfrb/` structure. One spec file per source file.
+
+## Where to look first
+
+Before touching anything, read these five files in order:
+
+1. `lib/pdfrb.rb` — autoload tree, the public surface.
+2. `lib/pdfrb/error.rb` — failure taxonomy.
+3. `lib/pdfrb/source.rb` — reading layer entry point.
+4. `lib/pdfrb/model.rb` — domain model entry point.
+5. `lib/pdfrb/arlington.rb` — model-driven-ness engine.
+
+Then read the matching TODO entry in `TODO.general-rels/` for the feature you're working on.
+
+## Reference repositories
+
+These repos live outside the project tree but are the authoritative references. Paths assume the user's standard layout (`~/src/`).
+
+| Path | Role |
+|---|---|
+| `~/src/claricle/postscript/` | Sibling gem to mimic — autoload pattern, layered Source/Model/Serializer, error hierarchy, rspec/rubocop setup. |
+| `~/src/pdfa/arlington-pdf-model/` | Canonical PDF object model: ~600 TSV files (one per PDF object type) + `fn:` predicate grammar. **This is the data we port.** Refresh via `rake arlington:refresh`. |
+| `~/src/external/hexapdf/` | Reference Ruby implementation. Architectural blueprint for Tokenizer/Parser/Dictionary/Type::*/Writer/Content/Canvas, security handlers, layout. We differ by sourcing field metadata from Arlington rather than hand-coding it. |
+| `~/src/pdfa/spec-pdf-core/` | AsciiDoc source of ISO 32000-2 itself — text-of-truth for human reference, not a test corpus. |
+| `~/src/pdfa/appnote-pdf20-002-af/` | PDF 2.0 Application Note 002 — Associated Files (`AF` key semantics, when `AF` is required, `EmbeddedFile` relationship). |
+| `~/src/pdfa/appnote-pdf20-003-metadata/` | PDF 2.0 Application Note 003 — locations for object metadata streams (`Metadata` key placement; DPM stream exclusion). |
+| `~/src/pdfa/technote-pdfua1-001/` | PDF/UA-1 Technical Note 001 — `ActualText` on `Figure` structure elements. |
+| `~/src/pdfa/technote-pdfua1-002/` | PDF/UA-1 Technical Note 002 — `Reference` structure elements containing links. |
+
+## Work in progress
+
+The gem is at 0.1.0 — foundation only (autoload tree, error hierarchy, constants, configuration). All remaining implementation work is tracked as individual TODO files in `TODO.general-rels/`. The master index is `TODO.general-rels/README.md`. Pick up work in dependency order; each TODO file's front-matter declares `depends_on`.

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "pry", "~> 0.14"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.13"
+gem "rubocop", "~> 1.75"
+gem "rubocop-performance", "~> 1.23"
+gem "rubocop-rake", "~> 0.7"
+gem "rubocop-rspec", "~> 3.5"

data/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Ribose Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,88 @@
+= Pdfrb
+
+Pure-Ruby PDF library: a byte-level reader, an Arlington-model-driven
+typed domain model, and a serializer. The PDF object model is sourced
+_directly_ from the vendored Arlington PDF Model TSVs (the
+machine-readable definition of ISO 32000-2:2020), so field metadata,
+version predicates, and validators stay aligned with the spec by
+_data_, not by hand-coded mimicry.
+
+Two-direction contract:
+
+* *"PDF file <=> Model"* — parse PDF bytes into a typed Model and
+  serialize a Model back to PDF bytes. Round-trip is the correctness
+  backbone.
+* *"API Builder Input => Model"* — `Document` and `Canvas` build a
+  typed Model from user intent, which the serializer then writes.
+
+Pdfrb is deliberately scoped to the PDF byte format. Layout concerns
+(page templates, flows, line breaking, tables, etc.) live in the
+sibling `arroolio` gem.
+
+Mirrors the layered design of the sibling
+https://github.com/claricle/postscript[postscript] gem (PS/EPS parser
++ serializer). Architecture blueprint cross-referenced against
+https://github.com/gettalong/hexapdf[HexaPDF].
+
+== Installation
+
+[source,sh]
+----
+gem install pdfrb
+----
+
+== Usage (sketch — APIs land across the TODO sequence)
+
+[source,ruby]
+----
+require "pdfrb"
+
+# Read
+doc = Pdfrb.open("input.pdf")
+puts doc.catalog.pages.count
+
+# Create
+doc = Pdfrb::Document.new
+page = doc.pages.add
+page.canvas.text("Hello, PDF", at: [72, 720])
+doc.write("hello.pdf")
+----
+
+== Architecture
+
+[cols="1,4", options="header"]
+|===
+| Layer | Owns
+| `Pdfrb::Source` | PDF bytes -> tokens -> COS object graph (read direction).
+| `Pdfrb::Model` | Typed PDF domain model: COS scalars + `Type::*` semantics.
+| `Pdfrb::Arlington` | Loads vendored TSVs; evaluates `fn:` predicates. Drives `Model` field definitions.
+| `Pdfrb::Filter` | Stream filter pipeline (FlateDecode, LZWDecode, ...).
+| `Pdfrb::Content` | Content-stream operators + Canvas drawing API.
+| `Pdfrb::Serializer` | Model -> PDF bytes (COS).
+| `Pdfrb::Writer` | Document -> file (xref + trailer assembly).
+| `Pdfrb::Document` | Top-level facade.
+|===
+
+Adding a new PDF type = adding one `Model::Type::*` subclass that
+declares `arlington_object "Name"`. Adding a new content operator =
+one subclass + `register_as`. Adding a new filter = one subclass +
+register. No switch edits (Open/Closed).
+
+== Reference materials
+
+[cols="1,4", options="header"]
+|===
+| Path | Role
+| `~/src/claricle/postscript/` | Sibling gem to mimic for conventions.
+| `~/src/pdfa/arlington-pdf-model/` | Canonical PDF object model (TSV data).
+| `~/src/external/hexapdf/` | Reference Ruby implementation.
+| `~/src/pdfa/spec-pdf-core/` | AsciiDoc source of ISO 32000-2.
+| `~/src/pdfa/appnote-pdf20-002-af/` | App Note 002: Associated Files.
+| `~/src/pdfa/appnote-pdf20-003-metadata/` | App Note 003: Metadata stream locations.
+| `~/src/pdfa/technote-pdfua1-001/` | PDF/UA Tech Note 001: ActualText on Figure.
+| `~/src/pdfa/technote-pdfua1-002/` | PDF/UA Tech Note 002: Reference elements with links.
+|===
+
+== License
+
+BSD-2-Clause. See `LICENSE`.

data/Rakefile

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+namespace :arlington do
+  desc "Re-vendor the Arlington TSVs from ~/src/pdfa/arlington-pdf-model/tsv/latest"
+  task :refresh do
+    require "fileutils"
+
+    source = File.expand_path("~/src/pdfa/arlington-pdf-model/tsv")
+    dest_root = File.expand_path("data/pdfrb/arlington", __dir__)
+
+    unless File.directory?(source)
+      warn "Arlington source not found at #{source}"
+      exit 1
+    end
+
+    FileUtils.rm_rf(dest_root)
+    FileUtils.cp_r(source, dest_root)
+    puts "Refreshed Arlington TSVs -> #{dest_root}"
+  end
+end
+
+namespace :fixtures do
+  desc "Pull fixture corpus from claricle/pdf-core-examples"
+  task :pull do
+    token = ENV["CLARICLE_CI_PAT_TOKEN"] || ENV["GH_TOKEN"]
+    if token.nil? || token.empty?
+      warn "No CLARICLE_CI_PAT_TOKEN set — skipping fixture pull"
+      next
+    end
+    dir = File.expand_path("spec/fixtures/pdf-core-examples", __dir__)
+    FileUtils.rm_rf(dir) if Dir.exist?(dir)
+    system("git clone --depth 1 " \
+           "https://x-access-token:#{token}@github.com/claricle/pdf-core-examples " \
+           "#{dir}") || warn("Failed to clone fixture corpus")
+  end
+end

data/benchmarks/bench.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Benchmark script. Run with: bundle exec ruby benchmarks/bench.rb
+# Compares pdfrb parse/serialize performance against HexaPDF (if installed).
+
+require "bundler/setup"
+require "pdfrb"
+require "benchmark"
+require "stringio"
+
+def generate_test_pdf(pages: 10)
+  doc = Pdfrb::Document.new
+  font = doc.fonts.add("Helvetica")
+  pages.times do |i|
+    page = doc.pages.add
+    page.canvas.text("Page #{i + 1} — the quick brown fox", at: [72, 720], font: font, size: 12)
+  end
+  out = StringIO.new
+  doc.write(io: out)
+  out.string
+end
+
+pdf_bytes = generate_test_pdf(pages: 10)
+puts "Test PDF: #{pdf_bytes.bytesize} bytes, 10 pages"
+puts
+
+n = 100
+Benchmark.bm(25) do |x|
+  x.report("parse (x#{n})") do
+    n.times { Pdfrb::Document.new(io: StringIO.new(pdf_bytes)) }
+  end
+  x.report("serialize (x#{n})") do
+    n.times do
+      doc = Pdfrb::Document.new
+      font = doc.fonts.add("Helvetica")
+      doc.pages.add.canvas.text("bench", at: [72, 720], font: font, size: 12)
+      out = StringIO.new
+      doc.write(io: out)
+    end
+  end
+  x.report("round-trip (x#{n})") do
+    n.times do
+      doc = Pdfrb::Document.new(io: StringIO.new(pdf_bytes))
+      out = StringIO.new
+      doc.write(io: out)
+    end
+  end
+end