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

package/README.md

@@ -137,9 +137,9 @@ verify all of it:
 
 | Package | What it is |
 | --- | --- |
-| **[@jasy/zugferd](https://www.npmjs.com/package/@jasy/zugferd)** | ZUGFeRD / XRechnung: your data → PDF/A-3 + EN-16931 XML, with local validation. **The prize.** |
-| **[@jasy/cli](https://www.npmjs.com/package/@jasy/cli)** | the `jasy` terminal: read · validate · export, headless **and** interactive |
-| **[@jasy/pdf](https://www.npmjs.com/package/@jasy/pdf)** | the declarative, Flutter-style PDF layout engine that powers them |
+| **[@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 |
 
 ---
 

package/dist/api/args.d.ts

@@ -1,4 +1,4 @@
-import { PDFElement } from "../elements/pdf-element";
+import { PDFElement } from "../elements/pdf-element.js";
 /**
  * Lets a container factory be called either `F(children)` or `F(opts, children)` - the
  * same ergonomic shape across Document/Page/Column/Row/Box. When the first argument is the

package/dist/api/args.js

@@ -1,13 +1,10 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.splitArgs = splitArgs;
 /**
  * Lets a container factory be called either `F(children)` or `F(opts, children)` - the
  * same ergonomic shape across Document/Page/Column/Row/Box. When the first argument is the
  * child array, options default to empty.
  */
-function splitArgs(a, b) {
+export function splitArgs(a, b) {
     if (Array.isArray(a))
         return { opts: {}, children: a };
-    return { opts: a, children: b !== null && b !== void 0 ? b : [] };
+    return { opts: a, children: b ?? [] };
 }

package/dist/api/color.d.ts

@@ -1,11 +1,11 @@
-import { Color } from "../common/color";
+import { Color } from "../common/color.js";
 /**
- * Every way to name a colour. The FORM picks the convention, so there is never a guess
+ * Every way to name a color. The FORM picks the convention, so there is never a guess
  * (locked design §2):
  *
  * | form                      | example                  | meaning                        |
  * |---------------------------|--------------------------|--------------------------------|
- * | named (full CSS set)      | `"steelblue"`, `"transparent"` | the ~148 CSS colour names |
+ * | named (full CSS set)      | `"steelblue"`, `"transparent"` | the ~148 CSS color names |
  * | hex 6 / 3                 | `"#1450aa"` / `"#14a"`   | CSS RGB                        |
  * | hex 8 / 4                 | `"#1450aacc"` / `"#14ac"`| CSS RGBA (alpha LAST)          |
  * | number                    | `0xff1450aa`             | Flutter ARGB (alpha FIRST)     |
@@ -19,6 +19,6 @@ export declare function rgb(r: number, g: number, b: number): Color;
 export declare function rgba(r: number, g: number, b: number, a: number): Color;
 /**
  * Normalizes any `ColorInput` to an engine `Color`. The single funnel every factory uses,
- * so a colour means the same thing no matter how it was written.
+ * so a color means the same thing no matter how it was written.
  */
 export declare function toColor(input: ColorInput): Color;

package/dist/api/color.js

@@ -1,24 +1,18 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.rgb = rgb;
-exports.rgba = rgba;
-exports.toColor = toColor;
-const color_1 = require("../common/color");
+import { Color } from "../common/color.js";
 /** Channels 0–255, fully opaque. */
-function rgb(r, g, b) {
-    return new color_1.Color(r, g, b, 1);
+export function rgb(r, g, b) {
+    return new Color(r, g, b, 1);
 }
 /** Channels 0–255, alpha 0–1. */
-function rgba(r, g, b, a) {
-    return new color_1.Color(r, g, b, a);
+export function rgba(r, g, b, a) {
+    return new Color(r, g, b, a);
 }
 /**
  * Normalizes any `ColorInput` to an engine `Color`. The single funnel every factory uses,
- * so a colour means the same thing no matter how it was written.
+ * so a color means the same thing no matter how it was written.
  */
-function toColor(input) {
-    var _a;
-    if (input instanceof color_1.Color)
+export function toColor(input) {
+    if (input instanceof Color)
         return input;
     if (typeof input === "number")
         return fromArgbNumber(input);
@@ -27,7 +21,7 @@ function toColor(input) {
         return fromHex(s);
     const named = CSS_COLORS[s];
     if (named)
-        return new color_1.Color(named[0], named[1], named[2], (_a = named[3]) !== null && _a !== void 0 ? _a : 1);
+        return new Color(named[0], named[1], named[2], named[3] ?? 1);
     throw new Error(`Unknown color: "${input}"`);
 }
 /** Flutter ARGB: 0xAARRGGBB, alpha FIRST. A 6-digit number has alpha 0x00 = transparent. */
@@ -36,7 +30,7 @@ function fromArgbNumber(n) {
     const r = (n >>> 16) & 0xff;
     const g = (n >>> 8) & 0xff;
     const b = n & 0xff;
-    return new color_1.Color(r, g, b, a / 255);
+    return new Color(r, g, b, a / 255);
 }
 /** CSS hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA. Alpha is LAST. */
 function fromHex(s) {
@@ -58,7 +52,7 @@ function fromHex(s) {
     const a = full.length === 8 ? parseInt(full.slice(6, 8), 16) / 255 : 1;
     if ([r, g, b].some(Number.isNaN))
         throw new Error(`Invalid hex color: "${s}"`);
-    return new color_1.Color(r, g, b, a);
+    return new Color(r, g, b, a);
 }
 // The full CSS named-color set (~148, incl. the synonyms grey/gray and `transparent`).
 // [r, g, b] or [r, g, b, alpha]. Lower-cased keys; `toColor` lower-cases the input.

package/dist/api/content.d.ts

@@ -1,10 +1,10 @@
-import { ImageElement, CustomImage } from "../elements/image-element";
-import { PDFElement } from "../elements/pdf-element";
-import { ColorInput } from "./color";
-import { Insets } from "./insets";
+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";
 /** A horizontal rule (locked §4). */
 export interface DividerOptions {
-    /** Line colour (default a light grey). */
+    /** Line color (default a light gray). */
     color?: ColorInput;
     /** Line thickness in points (default 1). */
     thickness?: number;
@@ -14,11 +14,11 @@ export interface DividerOptions {
 /**
  * A horizontal rule that spans the parent's width. Maps to a `LineElement` (hiding its
  * `xEnd`/`yEnd` mechanics) wrapped in a `PaddingElement` - the line has no height of its
- * own, so the padding gives it vertical room and centres the rule. Use inside a Column.
+ * own, so the padding gives it vertical room and centers the rule. Use inside a Column.
  */
 export declare function Divider(opts?: DividerOptions): PDFElement;
-/** An image source: a local file path, or a `CustomImage` (e.g. a browser-supplied image). */
-export type ImageSource = string | CustomImage;
+/** An image source: a local file path (Node), raw bytes (e.g. a browser fetch/upload), or a `CustomImage`. */
+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 {

package/dist/api/content.js

@@ -1,47 +1,46 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Divider = Divider;
-exports.Image = Image;
-const line_element_1 = require("../elements/line-element");
-const padding_element_1 = require("../elements/layout/padding-element");
-const image_element_1 = require("../elements/image-element");
-const color_1 = require("./color");
-const insets_1 = require("./insets");
+import { LineElement } from "../elements/line-element.js";
+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";
 const DEFAULT_DIVIDER_COLOR = "lightgray";
 const DEFAULT_DIVIDER_MARGIN = { y: 6 };
 /**
  * A horizontal rule that spans the parent's width. Maps to a `LineElement` (hiding its
  * `xEnd`/`yEnd` mechanics) wrapped in a `PaddingElement` - the line has no height of its
- * own, so the padding gives it vertical room and centres the rule. Use inside a Column.
+ * own, so the padding gives it vertical room and centers the rule. Use inside a Column.
  */
-function Divider(opts = {}) {
-    var _a, _b, _c;
-    const line = new line_element_1.LineElement({
+export function Divider(opts = {}) {
+    const line = new LineElement({
         x: 0,
         y: 0,
         xEnd: 0, // resolved to the parent's width at layout time
         yEnd: 0, // horizontal: no vertical span
-        color: (0, color_1.toColor)((_a = opts.color) !== null && _a !== void 0 ? _a : DEFAULT_DIVIDER_COLOR),
-        strokeWidth: (_b = opts.thickness) !== null && _b !== void 0 ? _b : 1,
+        color: toColor(opts.color ?? DEFAULT_DIVIDER_COLOR),
+        strokeWidth: opts.thickness ?? 1,
     });
-    return new padding_element_1.PaddingElement({
-        margin: (0, insets_1.toEdges)((_c = opts.margin) !== null && _c !== void 0 ? _c : DEFAULT_DIVIDER_MARGIN),
+    return new PaddingElement({
+        margin: toEdges(opts.margin ?? DEFAULT_DIVIDER_MARGIN),
         child: line,
     });
 }
 const FIT = {
-    none: image_element_1.BoxFit.none,
-    contain: image_element_1.BoxFit.contain,
-    cover: image_element_1.BoxFit.cover,
-    fill: image_element_1.BoxFit.fill,
+    none: BoxFit.none,
+    contain: BoxFit.contain,
+    cover: BoxFit.cover,
+    fill: BoxFit.fill,
 };
 /**
  * An image. `src` is a local file path (wrapped in a `CustomLocalImage`) or a ready
  * `CustomImage` for non-filesystem sources. Maps to an `ImageElement`.
  */
-function Image(src, opts = {}) {
-    return new image_element_1.ImageElement({
-        image: typeof src === "string" ? new image_element_1.CustomLocalImage(src) : src,
+export function Image(src, opts = {}) {
+    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,

package/dist/api/descriptor.d.ts

@@ -1,5 +1,5 @@
-import { PDFElement } from "../elements/pdf-element";
-import { PDFDocumentElement } from "../elements/pdf-document-element";
+import { PDFElement } from "../elements/pdf-element.js";
+import { PDFDocumentElement } from "../elements/pdf-document-element.js";
 /**
  * The framework-agnostic contract (the firewall). A binding (Vue/React, or any tree-builder)
  * produces a tree of these plain descriptors; `build` turns each node into an engine element

package/dist/api/descriptor.js

@@ -1,29 +1,24 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerElement = registerElement;
-exports.build = build;
-exports.buildDocument = buildDocument;
-const text_1 = require("./text");
-const layout_1 = require("./layout");
-const content_1 = require("./content");
-const structure_1 = require("./structure");
+import { Text, Paragraph, span } from "./text.js";
+import { Column, Row, Box, Padding, Spacer, Expanded, Positioned } from "./layout.js";
+import { Divider, Image } from "./content.js";
+import { Page, Document, DefaultTextStyle } from "./structure.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.
 function elementChildren(children) {
     return children.map(build);
 }
 function textOf(node) {
-    var _a;
     if (typeof node === "string")
         return node;
-    const first = (_a = node.children) === null || _a === void 0 ? void 0 : _a[0];
+    const first = node.children?.[0];
     return typeof first === "string" ? first : "";
 }
 function toSegment(c) {
     if (typeof c === "string")
-        return (0, text_1.span)(c);
+        return span(c);
     if (c.type === "span")
-        return (0, text_1.span)(textOf(c), c.props);
+        return span(textOf(c), c.props);
     throw new Error(`A Text child must be a string or a span, got "${c.type}"`);
 }
 function textContent(children) {
@@ -31,40 +26,89 @@ function textContent(children) {
         return children[0];
     return children.map(toSegment);
 }
+// A `<TableCell>`'s content → a `Cell`: a lone string stays a string (the table wraps it in Text);
+// otherwise its children are built (a single element, or a Column of several).
+function buildCell(cell) {
+    if (typeof cell === "string")
+        return cell;
+    const kids = cell.children ?? [];
+    if (kids.length === 1 && typeof kids[0] === "string")
+        return kids[0];
+    if (kids.length === 0)
+        return "";
+    const els = kids.map(build);
+    return els.length === 1 ? els[0] : Column(els);
+}
+// A `<TableRow>`'s `<TableCell>` children → one row of `Cell`s.
+function rowCells(row) {
+    return (row.children ?? [])
+        .filter((c) => typeof c !== "string" && c.type === "table-cell")
+        .map(buildCell);
+}
+// A `#header` / `#footer` slot's content → one element (a Column if it holds several; strings → Text).
+function slotElement(node) {
+    const els = (node.children ?? []).map((c) => (typeof c === "string" ? Text(c) : build(c)));
+    return els.length === 1 ? els[0] : Column(els);
+}
 const REGISTRY = {
-    document: (props, children) => (0, structure_1.Document)(props, elementChildren(children)),
-    page: (props, children) => (0, structure_1.Page)(props, elementChildren(children)),
-    column: (props, children) => (0, layout_1.Column)(props, elementChildren(children)),
-    row: (props, children) => (0, layout_1.Row)(props, elementChildren(children)),
-    box: (props, children) => (0, layout_1.Box)(props, elementChildren(children)),
-    padding: (props, children) => { var _a; return (0, layout_1.Padding)((_a = props.insets) !== null && _a !== void 0 ? _a : 0, elementChildren(children)[0]); },
-    expanded: (props, children) => (0, layout_1.Expanded)(props, elementChildren(children)[0]),
-    spacer: (props) => (0, layout_1.Spacer)(props === null || props === void 0 ? void 0 : props.flex),
-    divider: (props) => (0, content_1.Divider)(props),
-    image: (props) => (0, content_1.Image)(props.src, props),
-    text: (props, children) => (0, text_1.Text)(textContent(children), props),
-    paragraph: (props, children) => (0, text_1.Paragraph)(textContent(children), props),
+    document: (props, children) => {
+        const doc = Document(props, elementChildren(children));
+        // A binding can register fonts declaratively: `fonts: { Name: bytes | path | family }`.
+        if (props.fonts) {
+            for (const [name, src] of Object.entries(props.fonts))
+                doc.addFont(name, src);
+        }
+        return doc;
+    },
+    page: (props, children) => {
+        // `#header` / `#footer` arrive as `page-header` / `page-footer` marker children (read raw); the rest
+        // is the body. Both repeat on every physical page the body paginates onto.
+        const slot = (type) => {
+            const m = children.find((c) => typeof c !== "string" && c.type === type);
+            return m ? slotElement(m) : undefined;
+        };
+        const body = children.filter((c) => typeof c === "string" || (c.type !== "page-header" && c.type !== "page-footer"));
+        return Page({ ...props, header: slot("page-header"), footer: slot("page-footer") }, elementChildren(body));
+    },
+    column: (props, children) => Column(props, elementChildren(children)),
+    row: (props, children) => Row(props, elementChildren(children)),
+    box: (props, children) => Box(props, elementChildren(children)),
+    padding: (props, children) => Padding(props.insets ?? 0, elementChildren(children)[0]),
+    expanded: (props, children) => Expanded(props, elementChildren(children)[0]),
+    spacer: (props) => Spacer(props?.flex),
+    divider: (props) => Divider(props),
+    image: (props) => Image(props.src, props),
+    text: (props, children) => Text(textContent(children), props),
+    paragraph: (props, children) => Paragraph(textContent(children), props),
+    // `<Table>` reads its `<TableRow>`/`<TableCell>` structure raw; one row may be marked `header`.
+    table: (props, children) => {
+        const rows = children.filter((c) => typeof c !== "string" && c.type === "table-row");
+        const header = rows.find((r) => r.props?.header);
+        const body = rows.filter((r) => !r.props?.header);
+        return Table({ ...props, header: header ? rowCells(header) : undefined }, body.map(rowCells));
+    },
+    positioned: (props, children) => Positioned(props, elementChildren(children)[0]),
+    "default-text-style": (props, children) => DefaultTextStyle(props, elementChildren(children)),
 };
 /**
  * Registers a custom element type, so a binding (or a user-defined component) can introduce
  * its own tag that resolves to an engine element through this same seam. Overwrites an
  * existing type of the same name.
  */
-function registerElement(type, factory) {
+export function registerElement(type, factory) {
     REGISTRY[type] = factory;
 }
 /** Turns one descriptor node (or bare string → `Text`) into an engine element. */
-function build(node) {
-    var _a, _b;
+export function build(node) {
     if (typeof node === "string")
-        return (0, text_1.Text)(node);
+        return Text(node);
     const factory = REGISTRY[node.type];
     if (!factory)
         throw new Error(`Unknown element type: "${node.type}"`);
-    return factory((_a = node.props) !== null && _a !== void 0 ? _a : {}, (_b = node.children) !== null && _b !== void 0 ? _b : []);
+    return factory(node.props ?? {}, node.children ?? []);
 }
 /** Builds a descriptor tree whose root is a `document` into the renderable root element. */
-function buildDocument(root) {
+export function buildDocument(root) {
     if (root.type !== "document")
         throw new Error(`Expected a "document" root, got "${root.type}"`);
     return build(root);

package/dist/api/index.d.ts

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

package/dist/api/index.js

@@ -1,27 +1,11 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
 // The intuitive API layer: declarative factory functions + input normalizers that compile
 // down to the core engine elements. A thin, curated surface ON TOP of the engine - the
 // core classes stay untouched and remain exported for power users.
-__exportStar(require("./color"), exports);
-__exportStar(require("./insets"), exports);
-__exportStar(require("./text"), exports);
-__exportStar(require("./layout"), exports);
-__exportStar(require("./content"), exports);
-__exportStar(require("./structure"), exports);
-__exportStar(require("./table"), exports);
-__exportStar(require("./descriptor"), exports);
+export * from "./color.js";
+export * from "./insets.js";
+export * from "./text.js";
+export * from "./layout.js";
+export * from "./content.js";
+export * from "./structure.js";
+export * from "./table.js";
+export * from "./descriptor.js";

package/dist/api/insets.js

@@ -1,9 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.toEdges = toEdges;
 /** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`. */
-function toEdges(i) {
-    var _a, _b, _c, _d, _e, _f;
+export function toEdges(i) {
     if (typeof i === "number")
         return [i, i, i, i];
     if (Array.isArray(i))
@@ -13,9 +9,9 @@ function toEdges(i) {
     // axis interpretation (an empty object is all-zero either way).
     const o = i;
     if (o.x !== undefined || o.y !== undefined) {
-        const x = (_a = o.x) !== null && _a !== void 0 ? _a : 0;
-        const y = (_b = o.y) !== null && _b !== void 0 ? _b : 0;
+        const x = o.x ?? 0;
+        const y = o.y ?? 0;
         return [y, x, y, x];
     }
-    return [(_c = o.top) !== null && _c !== void 0 ? _c : 0, (_d = o.right) !== null && _d !== void 0 ? _d : 0, (_e = o.bottom) !== null && _e !== void 0 ? _e : 0, (_f = o.left) !== null && _f !== void 0 ? _f : 0];
+    return [o.top ?? 0, o.right ?? 0, o.bottom ?? 0, o.left ?? 0];
 }

package/dist/api/layout.d.ts

@@ -1,12 +1,13 @@
-import { ContainerElement } from "../elements/container-element";
-import { RowElement } from "../elements/row-element";
-import { RectangleElement } from "../elements/rectangle-element";
-import { ExpandedElement } from "../elements/layout/expanded-element";
-import { PaddingElement } from "../elements/layout/padding-element";
-import { PDFElement } from "../elements/pdf-element";
-import { MainAlign, CrossAlign } from "../utils/flex-layout";
-import { ColorInput } from "./color";
-import { Insets } from "./insets";
+import { ContainerElement } from "../elements/container-element.js";
+import { RowElement } from "../elements/row-element.js";
+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 { PDFElement } from "../elements/pdf-element.js";
+import { MainAlign, CrossAlign } from "../utils/flex-layout.js";
+import { ColorInput } from "./color.js";
+import { Insets } from "./insets.js";
 /** Options shared by the `Column` and `Row` stacks (locked §4). */
 export interface StackOptions {
     /** Space inserted between children, in points. */
@@ -25,9 +26,9 @@ export declare function Row(children: PDFElement[]): RowElement;
 export declare function Row(opts: StackOptions, children: PDFElement[]): RowElement;
 /** A bordered / filled box that wraps its children (locked §4). */
 export interface BoxOptions {
-    /** Border (stroke) colour. A box has a border only when `border` or `borderWidth` is set. */
+    /** Border (stroke) color. A box has a border only when `border` or `borderWidth` is set. */
     border?: ColorInput;
-    /** Per-side border colours - override/add to `border`. Any of these makes the box draw
+    /** Per-side border colors - override/add to `border`. Any of these makes the box draw
      *  individual side lines (sharp corners) instead of a uniform frame - this is how you get
      *  grid lines (e.g. a cell with only `borderBottom` + `borderRight`). */
     borderTop?: ColorInput;
@@ -36,7 +37,7 @@ export interface BoxOptions {
     borderLeft?: ColorInput;
     /** Border thickness in points (default 1 when a border is present). */
     borderWidth?: number;
-    /** Background fill colour. */
+    /** Background fill color. */
     bg?: ColorInput;
     /** Inner padding between the border and the children. */
     padding?: Insets;
@@ -45,6 +46,12 @@ export interface BoxOptions {
     height?: number;
     /** Corner radius in points. */
     radius?: number;
+    /** Make this box a positioning frame: `Positioned` children placed inside it resolve their
+     *  offsets against this box (CSS `position: relative`). */
+    relative?: boolean;
+    /** `"hidden"` crops children to the box (rounded corners included); `"visible"` (default) lets a
+     *  `Positioned` child spill over the edge. */
+    overflow?: "hidden" | "visible";
 }
 /**
  * A box: maps to a `RectangleElement` (fill + border + radius) whose children are stacked
@@ -55,6 +62,14 @@ export declare function Box(children: PDFElement[]): RectangleElement;
 export declare function Box(opts: BoxOptions, children: PDFElement[]): RectangleElement;
 /** Insets a single child by `padding` (a number / `{x,y}` / `{top,…}` / 4-tuple). */
 export declare function Padding(padding: Insets, child: PDFElement): PaddingElement;
+/**
+ * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box. Two ways, pick per
+ * axis: pin to EDGES - `Positioned({ top, left, right, bottom }, child)`, where a negative value
+ * pokes into / out of the corner (a badge, a tab, a ribbon) and pinning both sides stretches; or
+ * ANCHOR + nudge - `Positioned({ h: "center", v: "end", x: -10, y: -8 }, child)`, i.e. centered /
+ * 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;
 /**
  * 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).