Restore upstream parity and close remaining port gaps

[romulocrj]

Summary

• address the actionable PR review feedback and restore missing dart_pdf behavior across the PDF object model, fonts and text, images, SVG, widgets, charts, and pagination
• restore image compression and bound high-volume binary paths with Uint8Array-based storage, including regression coverage for memory-sensitive image processing
• resolve or explicitly classify the remaining PORT GAP markers, including direct shadings, CID/TTF word spacing, custom pie legends, and CBLC/CBDT bitmap-font fallback
• reject CFF/PostScript outlines with a clear CFF fonts are not supported exception, matching the fact that upstream has no correct CFF subsetting support
• update the porting status, roadmap, architecture notes, attribution, README rationale, and the as-is/no-warranty/no-support notice

Validation

• npm run verify — 447/447 tests passed
• npm run examples — 8/8 upstream examples generated
• test/v8/run.sh — 30/30 bare-V8 checks passed

[Copilot]

Pull request overview

This PR restores upstream parity across several PDF-generation subsystems (text/font handling, SVG rendering, images, gradients/shadings, and pagination) while also tightening memory usage on binary-heavy paths (streams, PNG inflate/unfilter, and image channel storage).

Changes:

• Adds SVG parity features: text (<text>/<tspan>), embedded raster <image> data URLs, and luminosity masks via soft-mask form XObjects.
• Restores font/text parity: Arabic shaping + bidi reordering for RTL spans, composite-font word spacing via TJ adjustments, and CBLC/CBDT bitmap-glyph fallback painted as images.
• Improves memory behavior: byte-buffer-backed canvases/streams, Uint8Array accumulation for PNG IDAT, split RGB/alpha storage in PdfImage, and a constrained-heap regression test.

Reviewed changes

Copilot reviewed 83 out of 115 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/check-source.mjs	Adds a lint check to enforce Uint8Array for binary-ish fields (vs number[]).
test/widgets_phase_5_7.test.mjs	Adds validation/regression tests for pagination thresholds, stroke widths, borders, polylines, and GridPaper inputs.
test/ttf_parser.test.mjs	Adds CBLC/CBDT bitmap-glyph parsing test ensuring view-based (no-copy) bitmap data.
test/ttf_font.test.mjs	Adds composite-font word spacing behavior test and bitmap fallback rendering test; updates CFF rejection test.
test/svg_widget.test.mjs	Adds end-to-end SVG mask serialization assertions.
test/svg_painter.test.mjs	Adds SVG text/image/mask painter coverage and adjusts expected save/restore scoping.
test/svg_gradient.test.mjs	Adds repeat/reflect spread tests, stop-opacity mask composition tests, and bounds-based expansion tests.
test/support/bitmap-font.mjs	Adds a host-free bitmap-font fixture builder for CBLC/CBDT format 17 PNG glyphs.
test/object_model.test.mjs	Adds tests for PdfStream.take, repeatable PdfDictStream output, and shading resources reaching page output.
test/memory-image-child.mjs	Adds child-process probe for large PNG decode/materialization under constrained heap.
test/memory_regressions.test.mjs	Adds regression test that runs the constrained-heap child process.
test/js_pdf.test.mjs	Adds regression that MultiPage does not duplicate content bytes before post-processing.
test/jpeg_phase_4_2.test.mjs	Extends JPEG tests for progressive/extended markers, EXIF orientation, DPI decode/resample, and segment-safe marker replacement.
test/graphics.test.mjs	Adds direct-shading (sh) dedupe/selection test.
test/decoration_phase_3_5.test.mjs	Adds DecorationImage coverage and updates exposed constructor set.
test/chart_phase_5_1.test.mjs	Adds coverage for caller-supplied pie legend widgets.
test/bidi.test.mjs	Adds Arabic shaping + bidi regression tests.
src/widgets/text.ts	Implements RTL bidi+Arabic shaping in RichText and bitmap-glyph fallback as inline images.
src/widgets/text_style.ts	Updates docs to reflect per-glyph fallback resolution now implemented by RichText.
src/widgets/svg.ts	Adds customFontLookup hook and resolves generic families for SVG text rendering.
src/widgets/shape.ts	Validates stroke widths and fixes open polyline painting for 2-point polygons.
src/widgets/page.ts	Switches page content to takeOutputBytes() and plumbs shadings into serialized page resources.
src/widgets/multi_page.ts	Validates NewPage.freeSpace; avoids copying content bytes in first pass and serializes bytes + shadings in final pass.
src/widgets/image_provider.ts	Adds JPEG parsing/orientation + DPI decode/resample path; uses PdfImage.resize; improves immutability/copy semantics.
src/widgets/grid_paper.ts	Validates scale/opacity/offsets (finite + ranges) before storing normalized values.
src/widgets/forms.ts	Plumbs shadings into form appearance resources.
src/widgets/decoration.ts	Adds DecorationGraphic/DecorationImage and BoxDecoration image painting with fit/alignment/clipping.
src/widgets/chart/pie_chart.ts	Adds legendWidget option and prioritizes it over generated legend text.
src/widgets/annotations.ts	Validates geometric annotation border widths to avoid invalid PDF serialization.
src/svg/xml.ts	Updates scope documentation around unsupported XML features and external loading.
src/svg/transform.ts	Reclassifies preserveAspectRatio note as upstream parity (not a port gap).
src/svg/text.ts	Adds SVG text operation implementation with font resolution, metrics, and painting.
src/svg/path.ts	Fixes graphics state scoping around fill/stroke to consistently restore context.
src/svg/parser.ts	Reclassifies percentage sizeValue behavior as upstream compatibility behavior.
src/svg/painter.ts	Adds font lookup/caching, SVG text/image support, and wraps masked operations.
src/svg/operation.ts	Updates docstring to reflect mask support via luminosity soft masks.
src/svg/mask_path.ts	Implements SVG mask resolution and painting as deferred luminosity soft masks.
src/svg/image.ts	Implements SVG embedded raster images via base64 data URLs.
src/svg/gradient.ts	Adds stop-opacity masks, bounded repeat/reflect expansion, and direct shading function spreading.
src/svg/brush.ts	Updates docstring to reflect mask support.
src/pdf/soft_mask.ts	Introduces soft-mask reference type deferred until document serialization.
src/pdf/obj/ttf_font.ts	Rejects CFF fonts with explicit error; adds bitmap glyph access; zeroes Arabic diacritic advances post-shaping.
src/pdf/obj/page.ts	Reclassifies /Rotate omission as deliberate divergence with swapped physical dimensions.
src/pdf/obj/page_list.ts	Reclassifies flat page tree as upstream parity.
src/pdf/obj/image.ts	Stores decoded pixels as RGB+alpha channels (lazy RGBA view), supports resizing, and avoids extra copying for encoded JPEG.
src/pdf/obj/graphic_stream.ts	Adds /Shading resource collection and registration.
src/pdf/obj/function.ts	Adds bounded repeat/reflect spread stitching for gradient functions.
src/pdf/obj/font_descriptor.ts	Reclassifies certain descriptor constants as upstream parity.
src/pdf/obj/annotation.ts	Adds shadings to form appearance resource contract.
src/pdf/image/png.ts	Avoids number[] IDAT accumulation; reuses buffers during unfiltering and avoids extra copies on inflate.
src/pdf/image/jpeg.ts	Adds EXIF orientation parsing and exposes orientation in JpegInfo.
src/pdf/graphics.ts	Switches canvas content to byte-backed stream; adds soft masks and direct shadings; fixes composite-font word spacing via TJ.
src/pdf/graphic_state.ts	Updates docs to reflect soft mask states installed via PdfCanvas.
src/pdf/format/xref.ts	Reclassifies xref-table choice as serialization choice.
src/pdf/format/string.ts	Emits UTF-16BE for strings outside WinAnsi, matching reader expectations.
src/pdf/format/stream.ts	Uses geometric growth; adds take() and view() APIs to release/avoid copies.
src/pdf/format/dict_stream.ts	Ensures compression output is repeatable without mutating the original dictionary.
src/pdf/format/deflate.ts	Refactors deflate so zlib wrapper writes without building intermediate arrays.
src/pdf/format/base.ts	Updates docs around PdfSettings/compression/encryption scope.
src/pdf/font/type1_fonts.ts	Reclassifies omission of widths/descriptor entries as serialization choice.
src/pdf/font/ttf_writer.ts	Reclassifies CFF limitation as format limit.
src/pdf/font/ttf_parser.ts	Adds bitmap strike parsing (CBLC/CBDT) and Arabic isolated-form cmap aliasing.
src/pdf/font/font.ts	Adds isComposite and getBitmap hooks for composite and bitmap-glyph behavior.
src/pdf/font/bidi_utils.ts	Adds logical->visual bidi conversion integrating Arabic shaping + UAX #9 reorder.
src/pdf/font/arabic.ts	Adds Arabic shaping (contextual forms + lam-alef ligature) and diacritic detection.
src/pdf/document.ts	Allows page content as bytes, adds soft-mask resolution, and plumbs shadings/SMask resources through serialization.
src/index.ts	Exposes new decoration primitives and shading/function exports; updates type exports.
src/barcode/qrcode.ts	Replaces number[] bit buffer with bounded Uint8Array bit writer.
src/barcode/pdf417.ts	Avoids array copies by operating on Uint8Array slices/subarrays.
README.md	Updates rationale, versioned artifact names, removes now-implemented limitations, and adds warranty/support notice.
package.json	Bumps version to 0.1.6.
ORIGINAL-ISSUES.md	Documents and explains fix for 2-point open polygon behavior.
NOTICE	Adds third-party attribution for JPEG decoder and bidi implementation sources.
examples/svg-gradients-phase-2.8.mjs	Expands gradient example to include reflected spread + stop-opacity use case.
examples/jpeg-phase-4.2.mjs	Exports and hardens marker replacement to be segment-aware and safe.
examples/generation-results.json	Updates example generation timestamp and byte counts.
examples/decoration-phase-3.5.mjs	Adds DecorationImage example output.
docs/ROADMAP.md	Updates status narrative to reflect parity audit closure and added memory safeguards.
docs/ARCHITECTURE.md	Updates architecture docs for Unicode strings, typed streams, decoration images, and bidi shaping parity.
dist/types/widgets/svg.d.ts	Updates declarations for SvgImage customFontLookup.
dist/types/widgets/multi_page.d.ts	Updates declarations for new summaries pass.
dist/types/widgets/image_provider.d.ts	Updates MemoryImage declaration to match deferred JPEG metadata handling.
dist/types/widgets/decoration.d.ts	Adds DecorationGraphic/DecorationImage typings and BoxDecoration image slot.
dist/types/widgets/chart/pie_chart.d.ts	Adds legendWidget typings for pie datasets.
dist/types/svg/text.d.ts	Adds declarations for new SVG text operation.
dist/types/svg/painter.d.ts	Updates painter ctor/resolveFont typing and adds font caching fields.
dist/types/svg/mask_path.d.ts	Adds declarations for SVG masked operation.
dist/types/svg/image.d.ts	Adds declarations for SVG embedded raster image operation.
dist/types/svg/gradient.d.ts	Updates declarations for variable opacity masks and spread behavior.
dist/types/pdf/soft_mask.d.ts	Adds soft mask typings.
dist/types/pdf/obj/ttf_font.d.ts	Adds bitmap-glyph method and composite flag typing.
dist/types/pdf/obj/image.d.ts	Updates PdfImage typing for channel storage, resizing, and lazy RGBA view.
dist/types/pdf/obj/graphic_stream.d.ts	Adds shadings resource typing.
dist/types/pdf/obj/function.d.ts	Adds spread function typing.
dist/types/pdf/obj/font_descriptor.d.ts	Updates docstring classification in typings.
dist/types/pdf/obj/annotation.d.ts	Adds shadings to appearance resources typing.
dist/types/pdf/image/jpeg.d.ts	Adds EXIF orientation typing.
dist/types/pdf/image/jpeg_decoder.d.ts	Adds JPEG decoder typings.
dist/types/pdf/graphics.d.ts	Updates canvas API typings for bytes, soft masks, shadings, and drawString.
dist/types/pdf/format/string.d.ts	Adds pdfUnicodeString typing.
dist/types/pdf/format/stream.d.ts	Adds take()/view() typings.
dist/types/pdf/font/unicode_bidi.d.ts	Adds bidi reorder typings.
dist/types/pdf/font/type1_fonts.d.ts	Updates docstring classification in typings.
dist/types/pdf/font/ttf_parser.d.ts	Adds bitmap table + bitmap glyph typing.
dist/types/pdf/font/font.d.ts	Adds isComposite and bitmap glyph typing.
dist/types/pdf/font/bidi_utils.d.ts	Adds logical-to-visual typing.
dist/types/pdf/font/arabic.d.ts	Adds Arabic shaping typings.
dist/types/pdf/document.d.ts	Updates SerializedPage.content to bytes and plumbs shadings typing.
dist/types/index.d.ts	Exposes new APIs/types (DecorationImage, shading/function exports, bitmap font types).
AI_USAGE.md	Updates docs to reflect added SVG/bidi support and decoration image capability.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.