@jasy/pdf 1.0.0-alpha.4 → 1.0.0-alpha.6

package/README.md

@@ -117,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.
 
 ---
 
@@ -132,6 +132,9 @@ 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.
 - **PDF/A-3, matched not approximated.** The conformance graph is hand-built and **passes veraPDF**, the

package/dist/api/content.d.ts

@@ -2,6 +2,7 @@ import { ImageElement, CustomImage } from "../elements/image-element.js";
 import { PDFElement } from "../elements/pdf-element.js";
 import { ColorInput } from "./color.js";
 import { Insets } from "./insets.js";
+import { SizeInput } from "./dimension.js";
 /** A horizontal rule (locked §4). */
 export interface DividerOptions {
     /** Line color (default a light gray). */
@@ -22,12 +23,17 @@ export type ImageSource = string | Uint8Array | CustomImage;
 /** How the image fills its box (locked §4). Mirrors CSS `object-fit`. */
 export type ImageFit = "none" | "contain" | "cover" | "fill";
 export interface ImageOptions {
-    width?: number;
-    height?: number;
-    /** Fit within the box (default `none`). */
+    /** Size on each axis: points (fixed) or a percentage string like `"50%"` (a fraction of the offered
+     *  space). Pin exactly ONE axis and the other follows the image's aspect ratio (CSS `height: auto`). */
+    width?: SizeInput;
+    height?: SizeInput;
+    /** Fit within the box (default `none`; `fill` when exactly one axis is pinned so it scales to fit). */
     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

@@ -3,6 +3,7 @@ import { PaddingElement } from "../elements/layout/padding-element.js";
 import { ImageElement, CustomLocalImage, CustomBytesImage, BoxFit, } from "../elements/image-element.js";
 import { toColor } from "./color.js";
 import { toEdges } from "./insets.js";
+import { toDimension } from "./dimension.js";
 const DEFAULT_DIVIDER_COLOR = "lightgray";
 const DEFAULT_DIVIDER_MARGIN = { y: 6 };
 /**
@@ -35,15 +36,24 @@ const FIT = {
  * `CustomImage` for non-filesystem sources. Maps to an `ImageElement`.
  */
 export function Image(src, opts = {}) {
+    const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
+    const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
+    // Exactly one axis pinned -> the other is derived from the aspect ratio, so scale the image to the
+    // resulting box (fit: fill). Both or neither pinned keeps the default fit (none).
+    const autoScale = (opts.width !== undefined) !== (opts.height !== undefined);
+    const fit = opts.fit ? FIT[opts.fit] : autoScale ? BoxFit.fill : undefined;
     return new ImageElement({
         image: typeof src === "string"
             ? new CustomLocalImage(src)
             : src instanceof Uint8Array
                 ? new CustomBytesImage(src)
                 : src,
-        width: opts.width,
-        height: opts.height,
-        fit: opts.fit ? FIT[opts.fit] : undefined,
+        width: w?.points,
+        height: h?.points,
+        widthFactor: w?.factor,
+        heightFactor: h?.factor,
+        fit,
         radius: opts.radius,
+        alt: opts.alt,
     });
 }

package/dist/api/descriptor.js

@@ -1,7 +1,8 @@
 import { Text, Paragraph, span } from "./text.js";
-import { Column, Row, Box, Padding, Spacer, Expanded, Positioned } from "./layout.js";
+import { Column, Row, Box, Padding, Spacer, Expanded, Positioned, Link, Anchor, Bookmark, Rotated, RotatedBox, } from "./layout.js";
 import { Divider, Image } from "./content.js";
 import { Page, Document, DefaultTextStyle } from "./structure.js";
+import { PageNumber, PageCount } from "./page-builder.js";
 import { Table } from "./table.js";
 // Element children (Column/Row/Box/Page/…) → built recursively. Text/Paragraph children are
 // strings or `span` descriptors and become content instead.
@@ -50,6 +51,14 @@ function slotElement(node) {
     const els = (node.children ?? []).map((c) => (typeof c === "string" ? Text(c) : build(c)));
     return els.length === 1 ? els[0] : Column(els);
 }
+// The single child a wrapper takes (`Link`, `Anchor`, `Bookmark`, `Rotated`, ...). Several children are
+// stacked in a Column, so `<JasyLink><Text/><Text/></JasyLink>` behaves like the factory would.
+function wrappedChild(children) {
+    const els = children.map((c) => (typeof c === "string" ? Text(c) : build(c)));
+    if (els.length === 0)
+        throw new Error("A wrapper element needs exactly one child");
+    return els.length === 1 ? els[0] : Column(els);
+}
 const REGISTRY = {
     document: (props, children) => {
         const doc = Document(props, elementChildren(children));
@@ -89,6 +98,18 @@ const REGISTRY = {
     },
     positioned: (props, children) => Positioned(props, elementChildren(children)[0]),
     "default-text-style": (props, children) => DefaultTextStyle(props, elementChildren(children)),
+    // Navigation. `Link` takes exactly one of `href` (a URL) or `to` (an `Anchor` name) - the factory
+    // enforces that, so a template typo surfaces as an error instead of a dead link.
+    link: (props, children) => Link(props, wrappedChild(children)),
+    anchor: (props, children) => Anchor(props, wrappedChild(children)),
+    bookmark: (props, children) => Bookmark(props, wrappedChild(children)),
+    // Transforms.
+    rotated: (props, children) => Rotated(props, wrappedChild(children)),
+    "rotated-box": (props, children) => RotatedBox(props, wrappedChild(children)),
+    // Page numbers. `PageBuilder` itself is deliberately NOT exposed: it takes a closure, which a template
+    // cannot express. These two cover what the closure exists for.
+    "page-number": (props) => PageNumber(props),
+    "page-count": (props) => PageCount(props),
 };
 /**
  * Registers a custom element type, so a binding (or a user-defined component) can introduce

package/dist/api/dimension.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Size input for a Box's `width` / `height` (relative sizing). Either a number of PDF points (a
+ * fixed size) or a percentage string like `"50%"` - a fraction of the space the parent offers on
+ * that axis. Every form normalizes to a `Dimension` via `toDimension`, so the engine only ever sees
+ * points and factors, never a string. A percentage resolves against the parent's offered extent, so
+ * it only has meaning inside a bounded region (a fraction of an unbounded axis is a no-op).
+ */
+export type SizeInput = number | `${number}%`;
+/** A resolved `SizeInput`: exactly one of an absolute point size or a 0..1 fraction of the parent. */
+export interface Dimension {
+    /** Absolute size in PDF points. */
+    points?: number;
+    /** Fraction of the parent's offered extent on this axis; a `"50%"` input is `0.5`. */
+    factor?: number;
+}
+/**
+ * Normalizes a `SizeInput` to a `Dimension` (a point size or a fraction). Rejects negatives at this
+ * boundary so `resolveExtent` and the layout never see a negative size.
+ */
+export declare function toDimension(value: SizeInput): Dimension;

package/dist/api/dimension.js

@@ -0,0 +1,16 @@
+const PERCENT = /^(\d+(?:\.\d+)?)%$/; // no leading "-": a size cannot be negative
+/**
+ * Normalizes a `SizeInput` to a `Dimension` (a point size or a fraction). Rejects negatives at this
+ * boundary so `resolveExtent` and the layout never see a negative size.
+ */
+export function toDimension(value) {
+    if (typeof value === "number") {
+        if (value < 0)
+            throw new Error(`Invalid size ${value}: a size cannot be negative.`);
+        return { points: value };
+    }
+    const m = PERCENT.exec(value.trim());
+    if (m)
+        return { factor: parseFloat(m[1]) / 100 };
+    throw new Error(`Invalid size "${value}": use a number of points or a percentage like "50%".`);
+}

package/dist/api/index.d.ts

@@ -1,8 +1,10 @@
 export * from "./color.js";
 export * from "./insets.js";
+export * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.js";
 export * from "./content.js";
+export * from "./page-builder.js";
 export * from "./structure.js";
 export * from "./table.js";
 export * from "./descriptor.js";

package/dist/api/index.js

@@ -3,9 +3,11 @@
 // core classes stay untouched and remain exported for power users.
 export * from "./color.js";
 export * from "./insets.js";
+export * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.js";
 export * from "./content.js";
+export * from "./page-builder.js";
 export * from "./structure.js";
 export * from "./table.js";
 export * from "./descriptor.js";

package/dist/api/layout.d.ts

@@ -4,10 +4,16 @@ import { RectangleElement } from "../elements/rectangle-element.js";
 import { ExpandedElement } from "../elements/layout/expanded-element.js";
 import { PaddingElement } from "../elements/layout/padding-element.js";
 import { PositionedElement, PositionedInsets } from "../elements/layout/positioned-element.js";
+import { LinkElement } from "../elements/layout/link-element.js";
+import { BookmarkElement } from "../elements/layout/bookmark-element.js";
+import { AnchorElement } from "../elements/layout/anchor-element.js";
+import { RotatedElement } from "../elements/layout/rotated-element.js";
+import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
 import { PDFElement } from "../elements/pdf-element.js";
 import { MainAlign, CrossAlign } from "../utils/flex-layout.js";
 import { ColorInput } from "./color.js";
 import { Insets } from "./insets.js";
+import { SizeInput } from "./dimension.js";
 /** Options shared by the `Column` and `Row` stacks (locked §4). */
 export interface StackOptions {
     /** Space inserted between children, in points. */
@@ -17,6 +23,11 @@ export interface StackOptions {
     justify?: MainAlign;
     /** Position across the axis (CSS `align-items`): start (default) · center · end · stretch. */
     align?: CrossAlign;
+    /** Size on each axis: points (fixed) or a percentage string like `"50%"` (a fraction of the offered
+     *  space). Omit to fill the offered width / shrink-wrap to the children. A percentage needs a bounded
+     *  axis (`height: "50%"` only resolves where the parent bounds the height). */
+    width?: SizeInput;
+    height?: SizeInput;
 }
 /** A vertical stack. `Column(children)` or `Column(opts, children)`. */
 export declare function Column(children: PDFElement[]): ContainerElement;
@@ -41,9 +52,11 @@ export interface BoxOptions {
     bg?: ColorInput;
     /** Inner padding between the border and the children. */
     padding?: Insets;
-    /** Fixed size; omit to fill the offered width and shrink-wrap the height. */
-    width?: number;
-    height?: number;
+    /** Size on each axis: a number of points (fixed) or a percentage string like `"50%"` (a fraction
+     *  of the space the parent offers on that axis). Omit `width` to fill the offered width, omit
+     *  `height` to shrink-wrap the content. A percentage only resolves in a bounded region. */
+    width?: SizeInput;
+    height?: SizeInput;
     /** Corner radius in points. */
     radius?: number;
     /** Make this box a positioning frame: `Positioned` children placed inside it resolve their
@@ -70,6 +83,55 @@ export declare function Padding(padding: Insets, child: PDFElement): PaddingElem
  * end-aligned with a pixel offset. An edge wins over an anchor on the same axis.
  */
 export declare function Positioned(opts: PositionedInsets, child: PDFElement): PositionedElement;
+/**
+ * Makes any `child` a clickable hyperlink - the child's whole box is the clickable region (an image, a
+ * box, a row). Pass `href` for an external URL, or `to` for an internal jump to an `Anchor({ name })`
+ * elsewhere in the document (e.g. a clickable table-of-contents row). Exactly one of the two. The link
+ * draws nothing itself, so style the child - e.g. `Link({ href }, Text("jasy.dev", { color: "#1450aa" }))`
+ * or `Link({ to: "chapter-2" }, Text("Chapter 2 ....... 5"))`. For a link on part of a line, put `href`/
+ * `to` on a `span` instead (`Text([span("Visit "), span("jasy.dev", { href })])`), linking just that run.
+ */
+export declare function Link(opts: {
+    href?: string;
+    to?: string;
+}, child: PDFElement): LinkElement;
+/**
+ * Marks `child` as a named jump target that an internal `Link({ to: name })` can point at (a table of
+ * contents linking to sections, cross-references). Layout-transparent: `child` renders exactly as it
+ * would on its own, on whatever page it lands on. `name` must match the link's `to`.
+ * `Anchor({ name: "chapter-2" }, Text("Chapter 2", { size: 24 }))`.
+ */
+export declare function Anchor(opts: {
+    name: string;
+}, child: PDFElement): AnchorElement;
+/**
+ * Adds a bookmark to the document outline (the viewer's sidebar) that jumps to `child`. `title` is the
+ * label; `level` (1-based, default 1) nests it - a `level: 2` bookmark hangs under the nearest preceding
+ * `level: 1`, so you get a collapsible tree (chapters -> sections). It is layout-transparent: `child`
+ * renders exactly as it would on its own. `Bookmark({ title: "Chapter 2", level: 1 }, Text("Chapter 2"))`.
+ */
+export declare function Bookmark(opts: {
+    title: string;
+    level?: number;
+}, child: PDFElement): BookmarkElement;
+/**
+ * Rotates `child` at PAINT time by `angle` degrees (clockwise), around its center - like CSS
+ * `transform: rotate()` / Flutter `Transform.rotate`. The child keeps its normal, unrotated layout box,
+ * so siblings do NOT reflow around the spun shape and the drawing may overflow its slot. Pair it with a
+ * `relative` Box + `Positioned` for a diagonal watermark or a "PAID" stamp laid over a document.
+ */
+export declare function Rotated(opts: {
+    angle: number;
+}, child: PDFElement): RotatedElement;
+/**
+ * Rotates `child` by whole quarter-turns and, unlike `Rotated`, is LAYOUT-AWARE: a 90 / 270 turn swaps
+ * the box's width and height so siblings reflow around it (a tall label becomes a narrow, tall strip
+ * that reserves exactly that footprint). `turns` = clockwise 90-degree steps (1 = 90, 2 = 180, 3 = 270).
+ * Use it for a vertical label beside a table; use `Rotated` for a free-angle stamp / watermark.
+ */
+export declare function RotatedBox(opts: {
+    turns: number;
+}, child: PDFElement): RotatedBoxElement;
 /**
  * A flexible empty gap that pushes its siblings apart - `Row([a, Spacer(), b])` sends `a`
  * and `b` to the edges. `flex` weights it against other flex children (default 1).

package/dist/api/layout.js

@@ -4,9 +4,21 @@ import { RectangleElement } from "../elements/rectangle-element.js";
 import { ExpandedElement } from "../elements/layout/expanded-element.js";
 import { PaddingElement } from "../elements/layout/padding-element.js";
 import { PositionedElement } from "../elements/layout/positioned-element.js";
+import { LinkElement } from "../elements/layout/link-element.js";
+import { BookmarkElement } from "../elements/layout/bookmark-element.js";
+import { AnchorElement } from "../elements/layout/anchor-element.js";
+import { RotatedElement } from "../elements/layout/rotated-element.js";
+import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
 import { toColor } from "./color.js";
 import { toEdges } from "./insets.js";
+import { toDimension } from "./dimension.js";
 import { splitArgs } from "./args.js";
+/** Splits `StackOptions` width/height into the fixed points + fraction the stack elements expect. */
+function stackSize(opts) {
+    const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
+    const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
+    return { width: w?.points, height: h?.points, widthFactor: w?.factor, heightFactor: h?.factor };
+}
 // The public default for `cross` is `start` (locked §5) - i.e. don't stretch a child unless
 // asked. The engine default is `stretch`; the factory sets the friendlier public one.
 const DEFAULT_CROSS = "start";
@@ -19,6 +31,7 @@ export function Column(a, b) {
         gap: opts.gap,
         main: opts.justify, // undefined → engine default `start` (matches §5)
         cross: opts.align ?? DEFAULT_CROSS,
+        ...stackSize(opts),
     });
 }
 export function Row(a, b) {
@@ -28,6 +41,7 @@ export function Row(a, b) {
         gap: opts.gap,
         main: opts.justify,
         cross: opts.align ?? DEFAULT_CROSS,
+        ...stackSize(opts),
     });
 }
 export function Box(a, b) {
@@ -49,6 +63,9 @@ export function Box(a, b) {
         return c !== undefined ? toColor(c) : undefined;
     };
     const hasBorder = opts.border !== undefined || opts.borderWidth !== undefined || hasPerSide;
+    // A point size fills `width`/`height`; a percentage fills `widthFactor`/`heightFactor`.
+    const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
+    const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
     return new RectangleElement({
         x: 0,
         y: 0,
@@ -56,8 +73,10 @@ export function Box(a, b) {
         color: opts.border !== undefined ? toColor(opts.border) : undefined,
         backgroundColor: opts.bg !== undefined ? toColor(opts.bg) : undefined,
         borderWidth: hasBorder ? (opts.borderWidth ?? 1) : 0,
-        width: opts.width,
-        height: opts.height,
+        width: w?.points,
+        height: h?.points,
+        widthFactor: w?.factor,
+        heightFactor: h?.factor,
         radius: opts.radius,
         sideBorders: hasPerSide
             ? {
@@ -85,6 +104,56 @@ export function Padding(padding, child) {
 export function Positioned(opts, child) {
     return new PositionedElement({ child, ...opts });
 }
+/**
+ * Makes any `child` a clickable hyperlink - the child's whole box is the clickable region (an image, a
+ * box, a row). Pass `href` for an external URL, or `to` for an internal jump to an `Anchor({ name })`
+ * elsewhere in the document (e.g. a clickable table-of-contents row). Exactly one of the two. The link
+ * draws nothing itself, so style the child - e.g. `Link({ href }, Text("jasy.dev", { color: "#1450aa" }))`
+ * or `Link({ to: "chapter-2" }, Text("Chapter 2 ....... 5"))`. For a link on part of a line, put `href`/
+ * `to` on a `span` instead (`Text([span("Visit "), span("jasy.dev", { href })])`), linking just that run.
+ */
+export function Link(opts, child) {
+    if ((opts.href === undefined) === (opts.to === undefined)) {
+        throw new Error("Link needs exactly one of `href` (external URL) or `to` (internal Anchor name).");
+    }
+    return new LinkElement({ href: opts.href, dest: opts.to, child });
+}
+/**
+ * Marks `child` as a named jump target that an internal `Link({ to: name })` can point at (a table of
+ * contents linking to sections, cross-references). Layout-transparent: `child` renders exactly as it
+ * would on its own, on whatever page it lands on. `name` must match the link's `to`.
+ * `Anchor({ name: "chapter-2" }, Text("Chapter 2", { size: 24 }))`.
+ */
+export function Anchor(opts, child) {
+    return new AnchorElement({ name: opts.name, child });
+}
+/**
+ * Adds a bookmark to the document outline (the viewer's sidebar) that jumps to `child`. `title` is the
+ * label; `level` (1-based, default 1) nests it - a `level: 2` bookmark hangs under the nearest preceding
+ * `level: 1`, so you get a collapsible tree (chapters -> sections). It is layout-transparent: `child`
+ * renders exactly as it would on its own. `Bookmark({ title: "Chapter 2", level: 1 }, Text("Chapter 2"))`.
+ */
+export function Bookmark(opts, child) {
+    return new BookmarkElement({ title: opts.title, level: opts.level, child });
+}
+/**
+ * Rotates `child` at PAINT time by `angle` degrees (clockwise), around its center - like CSS
+ * `transform: rotate()` / Flutter `Transform.rotate`. The child keeps its normal, unrotated layout box,
+ * so siblings do NOT reflow around the spun shape and the drawing may overflow its slot. Pair it with a
+ * `relative` Box + `Positioned` for a diagonal watermark or a "PAID" stamp laid over a document.
+ */
+export function Rotated(opts, child) {
+    return new RotatedElement({ angle: opts.angle, child });
+}
+/**
+ * Rotates `child` by whole quarter-turns and, unlike `Rotated`, is LAYOUT-AWARE: a 90 / 270 turn swaps
+ * the box's width and height so siblings reflow around it (a tall label becomes a narrow, tall strip
+ * that reserves exactly that footprint). `turns` = clockwise 90-degree steps (1 = 90, 2 = 180, 3 = 270).
+ * Use it for a vertical label beside a table; use `Rotated` for a free-angle stamp / watermark.
+ */
+export function RotatedBox(opts, child) {
+    return new RotatedBoxElement({ turns: opts.turns, child });
+}
 /**
  * A flexible empty gap that pushes its siblings apart - `Row([a, Spacer(), b])` sends `a`
  * and `b` to the edges. `flex` weights it against other flex children (default 1).

package/dist/api/page-builder.d.ts

@@ -0,0 +1,32 @@
+import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
+import { PageInfo, PDFElement } from "../elements/pdf-element.js";
+import { TextOptions } from "./text.js";
+export type { PageInfo };
+/**
+ * Builds content from the page it ends up on - this is how you show `pageNumber` / `pageCount`. Place it
+ * anywhere: in a `Page`'s `header`/`footer`, in the body, in a table cell, several times on one page.
+ * Because you write the closure, formatting and conditions are yours:
+ *
+ * ```ts
+ * PageBuilder(({ pageNumber, pageCount }) => Text(`Seite ${pageNumber} von ${pageCount}`))
+ * PageBuilder(({ pageNumber }) => (pageNumber === 1 ? Logo() : Text("Fortsetzung")))
+ * PageBuilder(({ pageNumber, pageCount }) => Text(`${pageNumber - 1} / ${pageCount - 1}`)) // cover page
+ * ```
+ *
+ * `pageNumber` is 1-based and counts PHYSICAL pages (an overflowing `Page` contributes several);
+ * `pageCount` is the document total; `pageSize` is the media box in points.
+ *
+ * The numbers themselves are always exact. Two sizing caveats, both from the same chicken-and-egg (the
+ * content decides the count that the content displays): in the flowing BODY the box is reserved before the
+ * total is known, so a much wider final string can paint slightly past it; and a conditional header may
+ * SHRINK on later pages but must not GROW, because the body band was measured against the first build.
+ */
+export declare function PageBuilder(build: (info: PageInfo) => PDFElement): PageBuilderElement;
+/** `Text` options plus an `offset` added to the number (e.g. `-1` to not count a cover page). */
+export interface PageNumberOptions extends TextOptions {
+    offset?: number;
+}
+/** The current page number as text. Sugar for `PageBuilder` - same thing, one word. */
+export declare function PageNumber({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
+/** The document's total page count as text. Sugar for `PageBuilder`. */
+export declare function PageCount({ offset, ...style }?: PageNumberOptions): PageBuilderElement;

package/dist/api/page-builder.js

@@ -0,0 +1,32 @@
+import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
+import { Text } from "./text.js";
+/**
+ * Builds content from the page it ends up on - this is how you show `pageNumber` / `pageCount`. Place it
+ * anywhere: in a `Page`'s `header`/`footer`, in the body, in a table cell, several times on one page.
+ * Because you write the closure, formatting and conditions are yours:
+ *
+ * ```ts
+ * PageBuilder(({ pageNumber, pageCount }) => Text(`Seite ${pageNumber} von ${pageCount}`))
+ * PageBuilder(({ pageNumber }) => (pageNumber === 1 ? Logo() : Text("Fortsetzung")))
+ * PageBuilder(({ pageNumber, pageCount }) => Text(`${pageNumber - 1} / ${pageCount - 1}`)) // cover page
+ * ```
+ *
+ * `pageNumber` is 1-based and counts PHYSICAL pages (an overflowing `Page` contributes several);
+ * `pageCount` is the document total; `pageSize` is the media box in points.
+ *
+ * The numbers themselves are always exact. Two sizing caveats, both from the same chicken-and-egg (the
+ * content decides the count that the content displays): in the flowing BODY the box is reserved before the
+ * total is known, so a much wider final string can paint slightly past it; and a conditional header may
+ * SHRINK on later pages but must not GROW, because the body band was measured against the first build.
+ */
+export function PageBuilder(build) {
+    return new PageBuilderElement({ build });
+}
+/** The current page number as text. Sugar for `PageBuilder` - same thing, one word. */
+export function PageNumber({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ pageNumber }) => Text(String(pageNumber + offset), style));
+}
+/** The document's total page count as text. Sugar for `PageBuilder`. */
+export function PageCount({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ pageCount }) => Text(String(pageCount + offset), style));
+}

package/dist/api/structure.d.ts

@@ -39,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). */
@@ -125,6 +138,12 @@ export interface RenderOptions {
     /** 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

@@ -8,6 +8,7 @@ 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";
@@ -56,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);
@@ -81,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);
@@ -153,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)
@@ -163,6 +176,18 @@ export async function renderPdf(doc, options) {
                 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