Changelog

All notable changes to @barrierbreak/a11ydocs-pdf are documented here. This project follows Semantic Versioning.

[1.7.0] - 2026-06-16

Changed

• renderTemplate now wraps all content under a single Document structure root by default. A template produces a complete document, but without an explicit structureRoot its tagged content (headings, paragraphs, figures, tables) was emitted as a flat list of top-level structure elements directly under StructTreeRoot — PDF/UA-1 expects a single top-level Document element. renderTemplate now defaults the structure root to Document when the document was created without one. Pass structureRoot: false to createDocument to opt out and keep bare roots; an explicit structureRoot is still respected. The low-level addPage/manual-structure API is unaffected (no implicit wrapper).

[1.6.2] - 2026-06-16

Fixed

• Template running header drawn last in the content stream. 1.6.1 hoisted a running header's structure roots to the front of the tag tree, but the body was still drawn first in the page content, so the header logo Figure received the highest marked-content id (MCID). Reading order and content order disagreed — content-order tools and PDF/UA validators saw the logo last. The header's content operators are now hoisted to the front of the page content stream alongside its structure roots, so the header is drawn first (lowest MCID) and reading order matches content order. Footers/page numbers are unaffected (they correctly remain last). Safe because text operators are self-contained (BT/ET with an absolute Tm) and image operators are wrapped in their own q/Q.
• richParagraph threw on non-string run text. A run whose text was null or undefined (e.g. localStorage.getItem(...) returning null on a miss) crashed normalizeRichRuns with Cannot read properties of null (reading 'length'). Such runs are now dropped like empty runs, so bad input degrades to nothing instead of aborting the whole render.

[1.6.1] - 2026-06-15

Fixed

• Tagged links never referenced from the structure tree. A link annotation was only tied to a Link structure element when the caller passed tag: "Link" explicitly. Inline links — flow.richParagraph runs, page-level richText runs, table-cell links, and paragraph text-annotation links — and the public page.link() omitted it, so the annotation was emitted with no OBJR back-reference (an untagged annotation, a PDF/UA-1 failure). An unspecified link tag now defaults to Link; pass tag: "Artifact" to opt out for decorative links.
• Inline link text was stranded outside its Link element. flow.richParagraph placed the visible link glyphs under the surrounding P and left the Link element holding only the annotation. The link's text is now grouped inside the Link structure element together with its OBJR.
• Marked content read after child elements. A structure element's /K array always listed child elements before the node's own marked content, so a paragraph like "Page URL: " + link was announced as the link first, then the leading text. /K now interleaves a node's own marked content with its child elements in content (reading) order; pure containers still keep their children's insertion order, so the hoisted running header is unaffected.
• Per-cell header cells emitted no /Scope. A table cell promoted to TH purely via cell.header (outside any headerRows/headerColumns band — e.g. a row-label column) was written without a /Scope, which auditors flag as a missing row header. Such cells now default to /Scope /Row (still overridable via cell.scope).
• Template running header read last in the tag tree. Headers/footers render after the body, so a header logo Figure landed at the end of the page's structure order instead of the start. Header structure roots are now hoisted to the front of the reading order; footers remain last (their correct final-appearance position).

[1.6.0] - 2026-06-10

Added

• WOFF2 decoding — new @barrierbreak/a11ydocs-pdf/woff2 subpath export. decodeWoff2(bytes) converts a .woff2 file (the format browsers and font CDNs serve) into standard TTF/OTF bytes ready for embedTrueTypeFont()/registerFontFamily(). Implements a zero-dependency Brotli (RFC 7932) decompressor — full prefix codes, context modeling, block switching, and the 122 KB static dictionary with all 121 word transforms — plus WOFF2 glyf/loca triplet reconstruction and hmtx transform reversal. Ships as a separate subpath so the embedded dictionary never loads with the core library. isWoff2(bytes) and brotliDecompress(bytes) are also exported.
• loadGoogleFont() now works in browsers: when Google serves a woff2 file, the decoder is loaded on demand and the result is returned as TTF bytes. Node continues to receive a plain .ttf/.otf with no decoder loaded.
• Table cell styling: per-cell font, color, align, and background overrides on TableCellDefinition (joining bold/italic). Cell fonts resolve registered families and built-in variants.
• Table decoration options: borderColor/borderWidth draw the cell grid, headerBackground fills header cells, and zebra (boolean or color) stripes alternate body rows. All decoration is emitted as tagged-PDF artifacts.
• Rich text in table cells: cells accept inline runs instead of text — mixed fonts, sizes, colors, bold/italic, underline/strike, and links wrap together inside the cell, with row heights tracking the tallest line.

Fixed

• fallbackFonts entries naming a registered font family never matched (the family name was passed through as if it were a built-in font, so fallback glyph coverage silently failed). Family names in fallbackFonts now resolve to the matching face, honoring the call's bold/italic flags and case-insensitive matching.

[1.5.5] - 2026-06-10

Added

• Table cells accept bold and italic flags ({ text: "Results", header: true, bold: true }). The flags resolve against the table font: a registered family picks the matching face, a built-in base family picks its standard-14 variant. Works in page.table(), flow.table(), structure-container tables, and template table blocks; row heights account for the styled face.

Fixed

• Registered font families did not resolve in flow.table(), flow.list(), and their height estimators — a template with page: { font: "Roboto" } and a table or list block threw Unknown font "Roboto" even though the family was registered. All table/list entry points now resolve families like the text APIs do.

[1.5.4] - 2026-06-10

Changed

• Font family names are now matched case-insensitively (like CSS font-family). Registering a font as "Roboto" and referencing it as "roboto" or "ROBOTO" in text/template APIs now works correctly. This applies to registerFontFamily(), renderTemplate({ fonts }), and all text APIs.

Fixed

• loadExtensionFontBytes() now strips "./" prefixes from paths before resolving via chrome.runtime.getURL(), which would otherwise produce URLs that fail to fetch.
• loadExtensionFontBytes() now accepts absolute extension URLs (chrome-extension://..., moz-extension://..., https://...), passing them through without calling getURL.
• loadExtensionFontBytes() wraps fetch failures with a detailed diagnostic message mentioning web_accessible_resources, file path, and case-sensitivity — saving debugging time when a content script can't reach a bundled font.

[1.5.3] - 2026-06-10

Added

• renderTemplate() now accepts a fonts option — a Record<string, FontFamilyInput> of family-name → faces that are registered before the template renders. Faces accept raw bytes, embedded handles, or built-in names.
• loadExtensionFontFaces(paths) — loads bundled extension font files and returns FontFamilyInput without registering, so it composes directly with renderTemplate({ fonts }).

[1.5.2] - 2026-06-10

Added

• loadExtensionFont(doc, family, paths) and loadExtensionFontBytes(path) — load font files bundled with a Chrome extension via chrome.runtime.getURL() and register them as a font family in one call. Fonts are fetched in parallel and passed to registerFontFamily(). Exported as @barrierbreak/a11ydocs-pdf/chrome-extension-fonts.

[1.5.1] - 2026-06-10

Fixed

• PdfFlow.richParagraph() and PdfPage.richText() produced text ops without a tag, so the tagged PDF structure tree showed the P element with empty marked-content identifiers. The block-level tag now flows through to each run's options so the structure tree carries the correct MCIDs.

[1.5.0] - 2026-06-06

Added

• renderDocumentJson(document) and renderDocumentJsonSync(document) — render a PDF from a single, fully serializable PdfDocumentJson value. Fonts are declared by source (base64 / file path / url / Google Fonts) and referenced by name; images carry a src instead of raw bytes; headers/footers are static block arrays with / / / tokens; document options (encryption, conformance, language, tagged, metadata) live on the root. renderDocumentJson is async; renderDocumentJsonSync handles fully inline (base64) documents.
• Absolute positioning in PdfDocumentJson: add a position ({ x, y, width?, height?, page?, origin? }) to a block to draw it at exact PDF-point coordinates instead of flowing. Positionable types: paragraph, the image formats, rect, textField, checkBox, signatureField.
• PdfDocument.getPage(index, origin?) and PdfDocument.pageCount — return a PdfPage builder for an already-created page so finished pages can be drawn on with the absolute-coordinate APIs.
• PdfErrorCode.INVALID_DOCUMENT_JSON for a malformed PdfDocumentJson.

Fixed

• ParsedPdfDocument.extractText() returned empty text for pages whose content stream was FlateDecode-compressed (common once a page carried a table, list, or header/footer). The extractor decoded the already-inflated lazy-stream bytes a second time and discarded the page; text and ToUnicode decoding now tolerate the pre-decoded bytes.

[1.3.0] - 2026-06-02

Added

• Shape helpers on PdfPage: rect(), line(), circle(), ellipse() with a simplified ShapeStyle (inferred fill/stroke paint mode).
• Text measurement: PdfDocument.measureText(), measureTextBlock(), and measureRichText() return width/height/line-count without drawing.
• PdfPage.image() auto-detects the raster format (PNG, JPEG, GIF, BMP, TIFF, WebP, JPEG 2000) from the data.
• addPage({ origin: "top-left" }) flips the y-axis so coordinates grow downward from the top edge — applied across the page drawing, annotation, and form-field methods.
• underline and strike options on text and inline runs, drawn as decorative lines.
• Named colors: text/shape color options accept names like "red", plus a color() helper that resolves named and #hex colors.
• Shape and image helpers on PdfStructureContainer (rect, line, circle, ellipse, image, path) and ellipse/line on PdfFlow.
• registerFontFamily() accepts raw font bytes per face (embedded automatically) in addition to handles and built-in names (FontFamilyInput).
• Document-wide shape defaults via createDocument({ shapeDefaults }), merged beneath per-call styles by the page shape helpers.
• Layout-feedback methods PdfPage.placeText() and placeTextBlock() that draw and return { width, height, (lineCount,) endY } for manual stacking.
• "Choosing an API" guide page mapping common goals to the right API.

Changed

• The font option now reports a clear "did you mean" error (INVALID_FONT) for an unknown string font instead of silently falling back, suggesting the closest standard-14 name. Unknown page-size names throw INVALID_PAGE_SIZE with the same suggestion treatment.
• PdfStructureContainer builder methods (text, textBlock, list, table, image, link) now return this for chaining, consistent with PdfPage and PdfFlow.

[1.2.1] - 2026-06-02

Fixed

• The font text option now accepts a font-family name registered with registerFontFamily() (and any string-typed value), instead of rejecting it at compile time. PdfFont widened to FontName | PdfEmbeddedFont | (string & {}), preserving built-in name autocomplete.

[1.2.0] - 2026-06-02

Added

• Inline rich text: PdfPage.richText() and PdfFlow.richParagraph() lay out an array of InlineTextRun segments that flow on the same line and wrap together, each with its own font, weight, size, color, and optional link.
• richParagraph template block (TemplateRichParagraphBlock) for inline rich text in renderTemplate().
• Inline rich text supports align: "justify", line-level direction ("ltr" | "rtl" | "auto"), and writingMode: "vertical" (single-column stacking); flow and template rich paragraphs wrap and split across columns and pages.
• Vertical alignment: verticalAlign ("top" | "middle" | "bottom") on table cells (TableOptions default and per-TableCellDefinition).
• Vertical alignment within a fixed-height box via height + verticalAlign on TextBlockOptions and RichTextOptions.
• New exported types: InlineTextRun, RichTextOptions, FlowRichTextOptions, TemplateRichParagraphBlock, VerticalAlign.

[1.1.0] - 2026-06-02

Added

• bold and italic text options that resolve to the matching font face for the standard-14 base families (Helvetica, Times, Courier)
• PdfDocument.registerFontFamily() to group font faces (built-in or embedded) under a name, selectable with the bold/italic flags
• Document-wide text defaults via createDocument({ defaults }) (font, bold, italic, fontSize, color, kerning, direction)
• Unit helpers mm(), cm(), inch(), and pt() for authoring layouts in physical units
• PdfDocument.save(path) convenience alias for writeToFile()

Changed

• PdfPage builder methods (text, images, annotations, form fields, graphics state, transforms) now return this for fluent chaining
• bold/italic, registered font families, and document defaults resolve uniformly across page.text()/textBlock(), the PdfFlow cursor API, renderTemplate() blocks, and structure containers

[1.0.0] - 2026-05-11

Added

• Zero-dependency PDF 1.4+ generation engine in TypeScript
• PDF 1.5 object streams and 2.0 encryption support
• Text rendering with 14 standard fonts plus embedded TrueType (Unicode, kerning, ligatures, RTL/Arabic)
• Image support: JPEG, PNG (transparency/alpha)
• Tagged PDF for accessibility: PDF/UA-1, structure trees, MCID-based marked content
• Flow-based coordinate-free layout engine
• Template-based report/document rendering with headers, footers, page numbers, and auto-outline
• Forms (AcroForm): text, checkbox, radio, choice, push button, signature
• Annotations: URI links, highlights, notes, free-text
• Encryption: rc4-40, rc4-128, AES-128, AES-256
• PDF parsing and incremental editing: metadata, pages, forms, overlays
• Page transfer utilities: extract, split, merge, append
• Streaming output via ByteSink abstraction
• XMP metadata support
• Linearized (Fast Web View) output for single-page documents
• PDF version auto-detection and conformance validation