feat(perry-ext): #516 — PDF creation API (createPdf/pdfAddText/pdfNewPage/pdfSave)

[proggeramlug]

Summary

Closes #516. Adds the producer half of the PDF feature — a new perry-ext-pdf crate exposing five FFI entry points that let Perry programs build and save PDF documents at runtime. The consumer half (PdfView widget) already shipped in perry-ui-{ios,visionos,macos} plus stubs on the other platform crates, so this PR completes #516.

Surface (@perryts/pdf)

export declare function createPdf(opts: {
  path: string;
  pageWidth?: number;
  pageHeight?: number;
}): number;
export declare function pdfAddText(pdf: number, text: string, x: number, y: number, fontSize?: number): void;
export declare function pdfAddLine(pdf: number, x1: number, y1: number, x2: number, y2: number): void;
export declare function pdfNewPage(pdf: number): void;
export declare function pdfSave(pdf: number): void;

Page units = PDF points (1/72"). Origin = bottom-left (PDF standard). Default page = US Letter (612 × 792 pt).

Implementation notes

• Engine: the pure-Rust printpdf 0.9 crate with default-features = false — drops the heavy html / azul-layout feature set; we only need text + lines for v1.
• Fonts: text is rendered in Helvetica via printpdf's BuiltinFont (one of the 14 PDF built-in fonts) so we don't have to embed or subset a TTF.
• Handles: 1-based i64 counter, kept alive in a OnceLock<Mutex<HashMap<i64, OpenDoc>>>. pdfSave removes the entry; subsequent ops warn-once and return.
• Options object: createPdf({ path, pageWidth?, pageHeight? }) is round-tripped through perry_ffi::json_stringify, parsed by a tiny hand-rolled JSON reader inside the crate. Same trick perry-ext-fastify uses; keeps serde_json / serde_derive out of this small crate.

Wiring

Cookie-cutter mirror of #1028 (perry-ext-google-auth):

• New crate: crates/perry-ext-pdf/{Cargo.toml,src/lib.rs}.
• Workspace Cargo.toml: new member + dep entry.
• crates/perry/well_known_bindings.toml: @perryts/pdf → libperry_ext_pdf.a.
• crates/perry-api-manifest/src/entries.rs: module added to NATIVE_MODULES; 5 manifest entries.
• crates/perry-codegen/src/lower_call.rs: 5 NativeModSig rows. createPdf ret = NR_PTR, mutators ret = NR_VOID.
• crates/perry-codegen/src/runtime_decls.rs: 5 extern declarations.
• types/perry/pdf/{index.d.ts,package.json}.
• Smoke test: test-files/test_pdf_create_smoke.ts (creates a 2-page PDF, asserts magic header + EOF marker via hex-encoded buffer).

Drive-by fix (not strictly #516)

Main commit 9a9a233 (fix: address #945 scalar method allocation regression) left three unresolved HEAD/incoming merge-conflict markers in crates/perry-codegen/src/{lower_call,type_analysis}.rs (Promise.* / Array.fromAsync dispatch). The full workspace build was failing on main before this PR's content was even relevant. Resolved by keeping the richer HEAD-side comments and switching the calls to the post-#1030 canonical is_global_constructor_expr helper. The legacy is_global_builtin_named is left in place with #[allow(dead_code)] since removing it is outside #516's scope.

Scope boundaries (deliberate v1 cuts)

• No image embedding (jpeg / png / svg) — needs printpdf's images feature + a 2nd FFI shape.
• No custom font loading or font subsetting.
• No encryption, forms, annotations beyond text + straight lines.
• The PdfView widget path is not touched — that's the consumer side and already shipped.
• No version bump / no CHANGELOG.md entry (per CLAUDE.md, that's the maintainer's job at merge time).

Validation

• cargo build --release -p perry-runtime -p perry-stdlib -p perry -p perry-ext-pdf succeeds.
• cargo test -p perry-ext-pdf — 3/3 unit tests pass.
• cargo test -p perry-codegen --test manifest_consistency — 4/4 pass (dispatch ↔ manifest drift guards including the new @perryts/pdf rows).
• cargo test -p perry --bins well_known — 6/6 pass (every_entry_references_a_workspace_crate confirms the new entry resolves to a real workspace crate).
• Smoke test runs end-to-end on macOS:

  $ /tmp/test_pdf_smoke_bin
  OK: PDF written to /tmp/perry_pdf_smoke.pdf ( 1726 bytes)
  $ file /tmp/perry_pdf_smoke.pdf
  /tmp/perry_pdf_smoke.pdf: PDF document, version 1.3, 2 pages
  

Test plan

• CI: cargo-test, lint, parity, compile-smoke, api-docs-drift, security-audit all green.
• Manual: cargo run --release -- test-files/test_pdf_create_smoke.ts -o /tmp/smoke && /tmp/smoke && file /tmp/perry_pdf_smoke.pdf → reports PDF document, version 1.3, 2 pages.
• Open the resulting /tmp/perry_pdf_smoke.pdf in any PDF viewer — page 1 shows "Hello from Perry!" with the underline rule, page 2 shows "Page 2".