@jasy/pdf 1.0.0-alpha.3 → 1.0.0-alpha.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Heuberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -37,7 +37,7 @@ account, no upload, nothing leaves your machine.
 ## You bring the line items. jasy does the rest.
 
 You never compute a total, a VAT breakdown or a rounding again. You hand jasy the line items - it
-**derives** the document totals and the EN-16931 VAT breakdown, spec-correct. That is *why* the
+**derives** the document totals and the EN-16931 VAT breakdown, spec-correct. That is _why_ the
 invoices validate: the amounts are correct **by construction**, so the single biggest class of
 EN-16931 failures (the BR-CO total checks) simply cannot happen.
 
@@ -48,13 +48,23 @@ const { bytes, xml } = await renderZugferd({
   number: "RE-2026-001",
   issueDate: "2026-06-17",
   currency: "EUR",
-  seller: { name: "Northwind Studio GmbH", vatId: "DE123456789",
-            address: { city: "Berlin", postCode: "10115", country: "DE" } },
-  buyer:  { name: "Globex Corporation Ltd",
-            address: { city: "Munich", postCode: "80331", country: "DE" } },
+  seller: {
+    name: "Northwind Studio GmbH",
+    vatId: "DE123456789",
+    address: { city: "Berlin", postCode: "10115", country: "DE" },
+  },
+  buyer: {
+    name: "Globex Corporation Ltd",
+    address: { city: "Munich", postCode: "80331", country: "DE" },
+  },
   lines: [
-    { name: "Brand identity design", quantity: 2, unit: "HUR", netUnitPrice: 100,
-      vat: { category: "S", ratePercent: 19 } },
+    {
+      name: "Brand identity design",
+      quantity: 2,
+      unit: "HUR",
+      netUnitPrice: 100,
+      vat: { category: "S", ratePercent: 19 },
+    },
   ],
 });
 // bytes -> a valid ZUGFeRD PDF/A-3   ·   xml -> the embedded EN-16931 XML
@@ -107,8 +117,8 @@ const pdf = await renderToBytes(
 ```
 
 Real text layout (Adobe AFM metrics, kerning, word-wrap), flexbox-style `gap` / `justify` / `align`,
-boxes with radius and alpha, images, custom TrueType fonts, and **real pagination** - content that
-overflows flows onto the next page, headers and footers repeat.
+boxes with radius and alpha, images, custom TrueType fonts, **AES-256 password encryption**, and **real
+pagination** - content that overflows flows onto the next page, headers and footers repeat.
 
 ---
 
@@ -122,8 +132,11 @@ verify all of it:
   740 KB font ships as a ~76 KB subset, and the text stays copy- and searchable.
 - **Compression.** Content streams and images are FlateDecode-compressed; the spreadsheets `jasy export`
   writes are real `.xlsx` ZIPs we deflate with our own writer and CRC32, zero dependencies.
+- **AES-256 encryption, pure JS.** Lock a PDF with `renderToBytes(doc, { encrypt: { userPassword } })` - the
+  newest standard handler (AES-256, R6 / ISO 32000-2) via the platform WebCrypto: no native crypto, no deps,
+  the same code in Node **and** the browser. Owner password + permissions optional.
 - **Real font metrics.** Text is laid out with the Adobe AFM metrics of the standard-14 fonts - kerning
-  and word-wrap are *computed*, not guessed.
+  and word-wrap are _computed_, not guessed.
 - **PDF/A-3, matched not approximated.** The conformance graph is hand-built and **passes veraPDF**, the
   official ISO 19005 validator.
 - **Byte-exact round-trips.** Generate and parse are inverses: `generate → parse → regenerate` reproduces
@@ -135,11 +148,11 @@ verify all of it:
 
 ## Packages
 
-| Package | What it is |
-| --- | --- |
+| Package                                             | What it is                                                                                     |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
 | **[@jasy/zugferd](https://npmx.dev/@jasy/zugferd)** | ZUGFeRD / XRechnung: your data → PDF/A-3 + EN-16931 XML, with local validation. **The prize.** |
-| **[@jasy/cli](https://npmx.dev/@jasy/cli)** | the `jasy` terminal: read · validate · export, headless **and** interactive |
-| **[@jasy/pdf](https://npmx.dev/@jasy/pdf)** | the declarative, Flutter-style PDF layout engine that powers them |
+| **[@jasy/cli](https://npmx.dev/@jasy/cli)**         | the `jasy` terminal: read · validate · export, headless **and** interactive                    |
+| **[@jasy/pdf](https://npmx.dev/@jasy/pdf)**         | the declarative, Flutter-style PDF layout engine that powers them                              |
 
 ---
 
@@ -158,7 +171,7 @@ verify all of it:
 
 jasy targets the documents that matter here: invoices, reports, quotes, datasheets. It is **not** a
 LaTeX / WeasyPrint replacement - no microtypography, hyphenation or bidi, and arbitrary multi-page flow
-of *any* content is still maturing. For e-invoices (a table, totals, a footer) it is complete - they
+of _any_ content is still maturing. For e-invoices (a table, totals, a footer) it is complete - they
 even paginate. We would rather under-promise and over-deliver in the demo above.
 
 > **Status:** young and pre-1.0. The API can still shift between minor versions. Everything shown here

package/dist/api/content.d.ts

@@ -28,6 +28,9 @@ export interface ImageOptions {
     fit?: ImageFit;
     /** Corner radius in points (rounds the image box). */
     radius?: number;
+    /** Alternate text for accessibility (tagged PDF): describes the image for screen readers. With `alt`
+     *  the image is a `Figure`; without it (and when rendered `accessible`) it counts as decoration. */
+    alt?: string;
 }
 /**
  * An image. `src` is a local file path (wrapped in a `CustomLocalImage`) or a ready

package/dist/api/content.js

@@ -45,5 +45,6 @@ export function Image(src, opts = {}) {
         height: opts.height,
         fit: opts.fit ? FIT[opts.fit] : undefined,
         radius: opts.radius,
+        alt: opts.alt,
     });
 }

package/dist/api/structure.d.ts

@@ -4,6 +4,8 @@ import { PDFElement } from "../elements/pdf-element.js";
 import { DefaultTextStyleElement } from "../elements/layout/default-text-style-element.js";
 import type { OverflowPolicy } from "../layout/fragmentation.js";
 import { PageSize } from "../constants/page-sizes.js";
+import { type EncryptOptions } from "../crypto/security-handler.js";
+export type { EncryptOptions, Permissions } from "../crypto/security-handler.js";
 import { StackOptions } from "./layout.js";
 import { Insets } from "./insets.js";
 import { TextDefaults } from "./text.js";
@@ -37,12 +39,25 @@ export declare function Page(children: PDFElement[]): PageElement;
 export declare function Page(opts: PageOptions, children: PDFElement[]): PageElement;
 /** Document options: PDF metadata plus the inheritable text defaults (font, size, color, lineHeight,
  *  align, bold/italic) every `Text` inherits unless it sets its own - Flutter's `DefaultTextStyle`. */
+/** Where color emoji come from when a code point isn't in the current text font, so `Text("Hi 😅")`
+ *  works in one string. Either a **font** (native vector, offline - recommended; register it in
+ *  `fonts`) as a string name or `{ font }`, or an **image/CDN source** `{ url, format }` (react-pdf
+ *  style: fetches `${url}${hexCodePoint}.${format}`, e.g. a Twemoji CDN). The font source is better
+ *  (vector, no network); the image source exists for parity + as an escape hatch. */
+export type EmojiSource = string | {
+    font: string;
+} | {
+    url: string;
+    format?: "png";
+};
 export interface DocumentOptions extends TextDefaults {
     /** PDF metadata. */
     meta?: {
         title?: string;
         author?: string;
     };
+    /** Color-emoji fallback: emoji code points not in the text font render from this source. */
+    emoji?: EmojiSource;
 }
 /** A single font file for `addFont`: a `.ttf` path (read on Node) or its raw bytes (e.g. a browser
  *  upload). */
@@ -120,6 +135,15 @@ export interface RenderOptions {
     /** What to do when content is taller than a page and cannot break: `"error"` throws (default),
      *  `"warn"` logs and clips, `"ignore"` clips silently. It is always clipped either way. */
     onOverflow?: OverflowPolicy;
+    /** Encrypt the PDF with a password (AES-256, the newest standard). NOT compatible with PDF/A
+     *  (ZUGFeRD invoices) - encrypting one throws, since PDF/A forbids encryption. */
+    encrypt?: EncryptOptions;
+    /** Emit an accessible, tagged PDF (structure tree for screen readers). */
+    accessible?: boolean;
+    /** Document language for accessibility, e.g. `"en-US"` / `"de-DE"` (default `"en-US"`). */
+    lang?: string;
+    /** Document title (used by accessible readers; also good metadata). */
+    title?: string;
 }
 /** Renders a `Document(...)` tree to the raw PDF string. */
 export declare function renderPdf(doc: PDFDocumentElement, options?: RenderOptions): Promise<string>;

package/dist/api/structure.js

@@ -7,6 +7,8 @@ import { Orientation } from "../renderer/pdf-config.js";
 import { PDFDocument } from "../renderer/pdf-document-class.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
 import { getArrayBuffer } from "../utils/utf8-to-windows1252-encoder.js";
+import { createSecurityHandler } from "../crypto/security-handler.js";
+import { uaXmp } from "../utils/ua-xmp.js";
 import { Column } from "./layout.js";
 import { toEdges } from "./insets.js";
 import { toTextStyleOverride } from "./text.js";
@@ -55,6 +57,8 @@ const docMeta = new WeakMap();
 // Fonts registered via doc.addFont(...), kept beside the element (like meta) and registered on the
 // object manager at render time. Path sources are read to bytes in addFont, so the map holds bytes.
 const docFonts = new WeakMap();
+// The document's color-emoji fallback source, kept beside the element and applied at render time.
+const docEmoji = new WeakMap();
 /** Reads any path sources to bytes, leaving bytes / families as-is. */
 function resolveFontSource(source) {
     const read = (s) => (typeof s === "string" ? readFileBytes(s) : s);
@@ -80,6 +84,8 @@ export function Document(a, b) {
     });
     if (opts.meta)
         docMeta.set(doc, opts.meta);
+    if (opts.emoji)
+        docEmoji.set(doc, opts.emoji);
     // Managed font registry: addFont registers, getFonts/hasFont query, render reads it (below).
     const registry = new Map();
     docFonts.set(doc, registry);
@@ -117,6 +123,11 @@ export async function renderPdf(doc, options) {
         ...options?.fonts,
     };
     const attachments = options?.attachments ?? [];
+    // The security handler's key derivation is async (WebCrypto), so build it here, before the sync
+    // PDFDocument constructor wires it into the object manager.
+    const securityHandler = options?.encrypt
+        ? await createSecurityHandler(options.encrypt)
+        : undefined;
     // A throwaway PDFDocument whose build() yields this tree, reusing the engine's standard
     // font registration + config handling (the constructor does both). Custom fonts are
     // registered here, before layout/render, so both the metrics and the backend see them.
@@ -147,6 +158,14 @@ export async function renderPdf(doc, options) {
                     description: a.description,
                 });
             }
+            // Color-emoji fallback (Document({ emoji })): a font (native vector) or a CDN/image source.
+            const emoji = docEmoji.get(doc);
+            if (typeof emoji === "string")
+                om.setEmojiFont(emoji);
+            else if (emoji && "font" in emoji)
+                om.setEmojiFont(emoji.font);
+            else if (emoji && "url" in emoji)
+                om.setEmojiImageSource(emoji.url, emoji.format ?? "png");
             if (options?.xmp)
                 om.setXmpMetadata(options.xmp);
             if (options?.outputIntent)
@@ -155,6 +174,20 @@ export async function renderPdf(doc, options) {
                 om.setPdfVersion(options.pdfVersion);
             if (options?.documentId)
                 om.enableDocumentId();
+            if (securityHandler)
+                om.setSecurityHandler(securityHandler);
+            if (options?.accessible) {
+                om.struct.enabled = true;
+                if (options.lang)
+                    om.struct.lang = options.lang;
+                // Fall back to the document's own title (Document({ meta })) when no explicit title is given.
+                const title = options.title ?? meta?.title;
+                if (title)
+                    om.struct.title = title;
+                // Declare PDF/UA-1 in the XMP metadata, unless the caller supplied their own packet.
+                if (!options.xmp)
+                    om.setXmpMetadata(uaXmp({ title }));
+            }
         }
         build() {
             return doc;

package/dist/api/table.js

@@ -1,6 +1,7 @@
 import { BoxConstraints } from "../layout/box-constraints.js";
 import { RepeatingHeaderElement } from "../elements/layout/repeating-header-element.js";
 import { DeferredElement } from "../elements/layout/deferred-element.js";
+import { StructGroup } from "../elements/layout/struct-group.js";
 import { Column, Row, Box, Expanded, Padding } from "./layout.js";
 import { Text } from "./text.js";
 function asElement(c) {
@@ -52,8 +53,11 @@ function composeTable(opts, rows, columns) {
             ...(firstCol ? { borderLeft: cb } : {}),
         };
     // `ruled` rows get just a bottom line (the header underline / the table foot), without the full grid.
-    const wrap = (cell, col, firstRow, firstCol, ruled) => {
-        const inner = cellPadding !== undefined ? Padding(cellPadding, asElement(cell)) : asElement(cell);
+    const wrap = (cell, col, firstRow, firstCol, ruled, isHeader) => {
+        const content = cellPadding !== undefined ? Padding(cellPadding, asElement(cell)) : asElement(cell);
+        // Tag the cell (TH for a header cell, else TD). StructGroup is layout-transparent - visually nothing
+        // changes; it only nests the cell's content under a table-cell element in the accessible structure tree.
+        const inner = new StructGroup({ role: isHeader ? "TH" : "TD", child: content });
         // The border lives on the wrapper, which stretches to the row height (crisp lines).
         const border = {
             ...borderFor(firstRow, firstCol),
@@ -68,14 +72,18 @@ function composeTable(opts, rows, columns) {
         throw new Error(`Unsupported column width "${col}" - use a number of points or "<n>fr"`);
     };
     // align:stretch → equal-height cells, so a wrapping cell keeps the row's bottom rule straight.
-    const buildRow = (cells, firstRow, ruled = false) => Row({ gap: colGap, align: "stretch" }, cells.map((cell, i) => wrap(cell, columns[i] ?? "1fr", firstRow, i === 0, ruled)));
+    const buildRow = (cells, firstRow, ruled = false, isHeader = false) => new StructGroup({
+        role: "TR",
+        child: Row({ gap: colGap, align: "stretch" }, cells.map((cell, i) => wrap(cell, columns[i] ?? "1fr", firstRow, i === 0, ruled, isHeader))),
+    });
     // The first row (which gets the top border) is the header if present, else body row 0.
     // `rule` underlines the header and the last body row (the table foot).
     const last = rows.length - 1;
     const body = Column({ gap: rowGap }, rows.map((cells, idx) => buildRow(cells, !opts.header && idx === 0, rule !== undefined && idx === last)));
-    return opts.header
-        ? new RepeatingHeaderElement(buildRow(opts.header, true, rule !== undefined), body, rowGap)
+    const table = opts.header
+        ? new RepeatingHeaderElement(buildRow(opts.header, true, rule !== undefined, true), body, rowGap)
         : body;
+    return new StructGroup({ role: "Table", child: table });
 }
 /**
  * A `Column` of `Row`s. Fixed-point columns sit in a fixed-width `Box`, `"Nfr"` fractions

package/dist/api/text.d.ts

@@ -1,4 +1,4 @@
-import { TextElement, TextSegment } from "../elements/text-element.js";
+import { TextElement, TextRole, TextSegment } from "../elements/text-element.js";
 import { TextOverflow } from "../text/line-breaker.js";
 import { ResolvedTextStyle } from "../text/text-style.js";
 import { ColorInput } from "./color.js";
@@ -23,6 +23,9 @@ export interface TextOptions extends TextStyle {
     /** Line-height multiplier (default `1`). `1.4` gives roomier body copy; each line is
      *  `size * lineHeight` tall. */
     lineHeight?: number;
+    /** Accessibility role for the tagged structure tree (only when rendered with `accessible`): a heading
+     *  level `"h1"`..`"h6"` or `"p"` (default). Purely semantic - it does not change the visual style. */
+    role?: TextRole;
 }
 /**
  * An inline run for mixed-style `Text` (`Text([span("a", {bold:true}), span("b")])`). Each

package/dist/api/text.js

@@ -52,6 +52,7 @@ export function Text(content, opts = {}) {
         maxLines: opts.maxLines,
         overflow: opts.overflow,
         lineHeight: opts.lineHeight,
+        role: opts.role,
     });
 }
 /** `Text` with body-paragraph defaults (same options; a separate name reads as intent). */