Skip to content

A migration guide from Prawn code to the native API - #124

Merged
czj merged 9 commits into
mainfrom
claude/confident-pasteur-jz0fj6
Nov 21, 2026
Merged

czj merged 9 commits into
mainfrom
claude/confident-pasteur-jz0fj6

Conversation

@czj

@czj czj commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

The site and the README presented Gamba as a faster Prawn, and nothing showed someone with fifty Prawn documents what to move, in which order, and what each step brings. Without that path, applications stay on the compatibility layer.

A new migration page takes the bench invoice through three stages, each useful alone, and sets Prawn idioms beside the native code that replaces them. The home page, README and gemspec now lead with the native API, keeping Prawn compatibility as the second argument. Part of #88.

  • Three stages, one invoice: the same code on Gamba, then its table as one gamba block (byte for byte the same PDF), then written natively and tagged for PDF/UA, with time and weight at each stage read from benchmarks.json.
  • Middle stage measured: bench/mixed/invoice.rb becomes a "Gamba, one native block" column of rake bench. Until the next release run, the page says that number is not measured yet.
  • Idioms side by side: bounding_box columns, fonts and colours set then reset with move_down, tables counted by position, repeat with number_pages, and room measured before a heading.
  • Samples run in CI: test/migration_page_test.rb runs all 14 samples of the page. It also checks that each stage shows the code the bench measures, that the stages draw the same invoice, and that each Prawn idiom draws the same text as its native code.
  • Left for later in The guide shows no path from Prawn code to the native API #88: a native reference generated from the code, and running the guide's existing samples, which name files such as Inter.ttf that the repository does not ship.
Proof
  • bundle exec rake test: 1422 runs, 0 failures, 8 skips (veraPDF and Mustang are not installed here). RuboCop is clean, and rake docs:highlight:check passes.
  • The stage 2 invoice compared with the Prawn-API invoice on Gamba: cmp finds them identical, and so do their 100 dpi rasters.
  • Bench runs here (no YJIT, 50 iterations; not committed): documents 15.9 ms, mixed 14.8 ms, native 21.4 ms. Weights are 28,990 / 28,990 / 28,993 bytes.
  • Playwright at 1280 px and 390 px: the numbers table fills, there is no horizontal scroll, and the console shows no errors.

Generated by Claude Code

A stack or a grid with a background or a border moved whole to the next
page, and raised when it was higher than a page. It now breaks pages like
a plain stack: its decoration is drawn on each page around what that page
holds of it, beneath the content, with its padding kept clear at the top
and bottom of every page. keep_together: true still moves it whole.

Assisted-by: Claude [Claude Code]
Random stacks, rows and grids nested three levels deep, with gaps,
paddings, decorations and page break rules, holding texts and tables, are
placed and read back with mutool trace: nothing drawn leaves the margins,
no two lines overlap, a stack kept together stays on one page whenever it
fits an empty one, and rendering twice gives the same bytes. CI runs 1000
trees on a fresh seed.

Assisted-by: Claude [Claude Code]
The layout fuzzer, on fresh seeds, found three ways to draw past the
bottom margin. The gap below the last line of a decorated stack's part
took its frame past the page; the bottom padding of a plain stack inside
one did too; and a table row higher than a page ran past it, as Prawn's
table draws it. A decorated stack's part now ends where its padding
starts, a plain stack's bottom padding ends with the page, and a table
whose row cannot fit a page raises CannotFit naming its height.

Fuzz ids are zero-padded, so that a word broken across lines in a narrow
column cannot pass for another box's id.

Assisted-by: Claude [Claude Code]
Each native box takes a role saying what it is to a reader, for tagged
PDF to read: a text is a paragraph, a heading from h1 to h6, a list item
or an artifact; a container groups, or is a list, a list item or a figure;
images and codes are figures with their alternative text in alt; tables
are tables. Unknown roles, and alt on anything but a figure, raise.

Headings already make the PDF's outline, nested by level, each pointing
at the top of its first line on the page where it lands. Those of a
header or a footer make none.

Assisted-by: Claude [Claude Code]
…eur-jz0fj6

# Conflicts:
#	test/support/layout_trees.rb
…eur-jz0fj6

# Conflicts:
#	docs/guide.html
#	lib/gamba/native/layout.rb
#	test/native_boxes_test.rb
#	test/native_document_test.rb
#	test/native_layout_test.rb
A migration page takes the bench invoice from Prawn code to Gamba's own
API: the same code on Gamba, its table as one native block (byte for byte
the same PDF), then written natively and tagged. Five Prawn idioms sit
beside the native code that replaces them. A test runs every sample of
the page, checks the stages show the bench's code and draw the same
invoice, and that each pair draws the same text.

The bench measures the middle stage from bench/mixed, and the home page,
README and gemspec lead with the native API, Prawn compatibility second.

Assisted-by: Claude [Claude Code]
…eur-jz0fj6

# Conflicts:
#	bench/compare.rb
#	docs/benchmarks.html
@czj
czj merged commit 3340d49 into main Nov 21, 2026
14 checks passed
@czj
czj deleted the claude/confident-pasteur-jz0fj6 branch November 21, 2026 12:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants