@ryanyahya/opendoc 0.4.0

package/node_modules/@formepdf/core/dist/extract.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Extract embedded JSON data from a Forme-generated PDF.
+ *
+ * Scans the PDF bytes for a `forme-data.json` EmbeddedFile attachment,
+ * decompresses the stream, and parses the JSON. Returns `null` if the
+ * PDF doesn't contain embedded data (e.g. non-Forme PDF).
+ */
+export declare function extractData(pdfBytes: Uint8Array): unknown | null;

package/node_modules/@formepdf/core/dist/extract.js

@@ -0,0 +1,56 @@
+import { inflateSync } from 'node:zlib';
+/**
+ * Extract embedded JSON data from a Forme-generated PDF.
+ *
+ * Scans the PDF bytes for a `forme-data.json` EmbeddedFile attachment,
+ * decompresses the stream, and parses the JSON. Returns `null` if the
+ * PDF doesn't contain embedded data (e.g. non-Forme PDF).
+ */
+export function extractData(pdfBytes) {
+    const text = new TextDecoder('latin1').decode(pdfBytes);
+    // Find the FileSpec referencing forme-data.json
+    const fsMatch = text.match(/\/F\s*\(forme-data\.json\)/);
+    if (!fsMatch)
+        return null;
+    // Extract the EmbeddedFile stream object number from /EF << /F N 0 R >>
+    // Search around the FileSpec location for the /EF reference
+    const fsStart = fsMatch.index;
+    const fsRegion = text.slice(Math.max(0, fsStart - 200), fsStart + 200);
+    const efMatch = fsRegion.match(/\/EF\s*<<\s*\/F\s+(\d+)\s+0\s+R\s*>>/);
+    if (!efMatch)
+        return null;
+    const streamObjId = efMatch[1];
+    // Find the stream object: "N 0 obj ... stream\n...\nendstream"
+    const objPattern = new RegExp(streamObjId + '\\s+0\\s+obj\\b');
+    const objMatch = text.match(objPattern);
+    if (!objMatch)
+        return null;
+    const objStart = objMatch.index;
+    // Find stream start (after "stream\r\n" or "stream\n")
+    const streamKeyword = text.indexOf('stream', objStart);
+    if (streamKeyword === -1)
+        return null;
+    let streamDataStart = streamKeyword + 6; // "stream".length
+    // Skip \r\n or \n after "stream"
+    if (pdfBytes[streamDataStart] === 0x0d)
+        streamDataStart++; // \r
+    if (pdfBytes[streamDataStart] === 0x0a)
+        streamDataStart++; // \n
+    // Find endstream
+    const endstreamPos = text.indexOf('\nendstream', streamDataStart);
+    if (endstreamPos === -1)
+        return null;
+    const compressedBytes = pdfBytes.slice(streamDataStart, endstreamPos);
+    // Check if FlateDecode is used
+    const objRegion = text.slice(objStart, streamKeyword);
+    const isCompressed = objRegion.includes('/FlateDecode');
+    let jsonBytes;
+    if (isCompressed) {
+        jsonBytes = inflateSync(Buffer.from(compressedBytes));
+    }
+    else {
+        jsonBytes = compressedBytes;
+    }
+    const jsonString = new TextDecoder('utf-8').decode(jsonBytes);
+    return JSON.parse(jsonString);
+}

package/node_modules/@formepdf/core/dist/index.d.ts

@@ -0,0 +1,311 @@
+import type { ReactElement } from 'react';
+import { type AttachmentOptions, type FacturXOptions } from './attachments.js';
+export interface Color {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export interface EdgeValues<T> {
+    top: T;
+    right: T;
+    bottom: T;
+    left: T;
+}
+export interface CornerValues {
+    top_left: number;
+    top_right: number;
+    bottom_right: number;
+    bottom_left: number;
+}
+export type ElementFlexDirection = 'Row' | 'Column' | 'RowReverse' | 'ColumnReverse';
+export type ElementJustifyContent = 'FlexStart' | 'FlexEnd' | 'Center' | 'SpaceBetween' | 'SpaceAround' | 'SpaceEvenly';
+export type ElementAlignItems = 'FlexStart' | 'FlexEnd' | 'Center' | 'Stretch' | 'Baseline';
+export type ElementAlignContent = 'FlexStart' | 'FlexEnd' | 'Center' | 'SpaceBetween' | 'SpaceAround' | 'SpaceEvenly' | 'Stretch';
+export type ElementFlexWrap = 'NoWrap' | 'Wrap' | 'WrapReverse';
+export type ElementFontStyle = 'Normal' | 'Italic' | 'Oblique';
+export type ElementTextAlign = 'Left' | 'Right' | 'Center' | 'Justify';
+export type ElementTextDecoration = 'None' | 'Underline' | 'LineThrough';
+export type ElementTextTransform = 'None' | 'Uppercase' | 'Lowercase' | 'Capitalize';
+export type ElementOverflow = 'Visible' | 'Hidden';
+export type ElementPosition = 'Relative' | 'Absolute';
+/**
+ * Semantic role of a layout node. Note the specific transforms below
+ * (also documented on `ElementInfo`) — this union describes what the
+ * runtime actually emits, not what the JSX author wrote:
+ *
+ * - Six discrete heading tags (`H1`–`H6`) — NO generic `'Heading'`
+ * - `Table` wrapper containing `TableRow` / `TableCell` — one wrapper per
+ *   page fragment when the table breaks across pages (clone semantics,
+ *   like `View`). Before engine 0.14 layout unwrapped tables to sibling
+ *   rows; the wrapper was added so table-level border/background paint
+ *   and structural consumers get a real table node.
+ * - `List` + `ListItem` + `Lbl` — from `<OrderedList>` / `<UnorderedList>`
+ * - `FixedHeader` / `FixedFooter` — NO single `Fixed` (split by position)
+ * - `Bookmark` — zero-height marker from `bookmark` on a container, emitted
+ *   on every container path (fits or overflowing) and the sole carrier of
+ *   the outline entry
+ * - `TextLine` — leaf lines under `Text` blocks (holds `textContent`)
+ * - Inline `<Strong>`/`<Em>`/`<Code>`/`<Link>` do not appear here;
+ *   they contribute style runs within `TextLine`
+ *
+ * ### When adding a new value here
+ *
+ * Also add a `<Component>` that produces the new nodeType to
+ * `RICH_FIXTURE` in `packages/core/tests/layout-shape.test.ts`.
+ * A coverage tripwire in that file fails otherwise ("declared but
+ * never rendered"), on the exact drift risk this whole file exists
+ * to prevent.
+ */
+export type ElementNodeType = 'View' | 'Text' | 'TextLine' | 'H1' | 'H2' | 'H3' | 'H4' | 'H5' | 'H6' | 'Table' | 'TableRow' | 'TableCell' | 'List' | 'ListItem' | 'Lbl' | 'FixedHeader' | 'FixedFooter' | 'Bookmark' | 'Image' | 'Svg' | 'QrCode' | 'Barcode' | 'Canvas' | 'Watermark' | 'BarChart' | 'LineChart' | 'PieChart' | 'AreaChart' | 'DotPlot' | 'TextField' | 'Checkbox' | 'Dropdown' | 'RadioButton';
+/**
+ * Drawing kind for the node. Governs the PDF operator the serializer
+ * emits; NOT the same as `nodeType`, which describes semantic role.
+ */
+export type ElementKind = 'None' | 'Rect' | 'Text' | 'Image' | 'Svg' | 'QrCode' | 'Barcode' | 'Chart' | 'FormField' | 'Watermark';
+export interface ElementStyleInfo {
+    flexDirection: ElementFlexDirection;
+    justifyContent: ElementJustifyContent;
+    alignItems: ElementAlignItems;
+    alignContent: ElementAlignContent;
+    flexWrap: ElementFlexWrap;
+    flexGrow: number;
+    flexShrink: number;
+    gap: number;
+    columnGap: number;
+    rowGap: number;
+    position: ElementPosition;
+    /** Offset from parent, in points. Only meaningful when `position === 'Absolute'`. */
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+    margin: EdgeValues<number>;
+    padding: EdgeValues<number>;
+    borderWidth: EdgeValues<number>;
+    borderColor: EdgeValues<Color>;
+    borderRadius: CornerValues;
+    /**
+     * Explicit `style.width` from the source. May be a number (points) or
+     * a stringified value (e.g. percentage) — the layout engine formats
+     * some dimension variants as strings in the JSON output. Prefer the
+     * top-level `ElementInfo.width` for the resolved rendered width.
+     */
+    width?: number | string;
+    /** Explicit `style.height`. See `width` for shape notes. */
+    height?: number | string;
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: number;
+    fontStyle: ElementFontStyle;
+    lineHeight: number;
+    letterSpacing: number;
+    textAlign: ElementTextAlign;
+    textDecoration: ElementTextDecoration;
+    textTransform: ElementTextTransform;
+    color: Color;
+    backgroundColor: Color | null;
+    opacity: number;
+    overflow: ElementOverflow;
+    breakBefore: boolean;
+    breakable: boolean;
+    minOrphanLines: number;
+    minWidowLines: number;
+}
+/**
+ * A single node in the layout tree returned by
+ * `renderDocumentWithLayout()`. The tree does NOT mirror the JSX
+ * source — several transforms happen during layout:
+ *
+ * - `<Table>` is unwrapped. Its `<Row>` children appear as sibling
+ *   `TableRow` nodes at the containing page/View level. There is no
+ *   `Table` wrapper node.
+ * - `<OrderedList>` and `<UnorderedList>` both produce a `List` node
+ *   containing `ListItem` children. Each `ListItem` has a `Lbl` child
+ *   (the marker "1." / "•") followed by the item's own content children.
+ * - `<Fixed position="header">` produces a `FixedHeader` nodeType and
+ *   `<Fixed position="footer">` produces `FixedFooter`. There is no
+ *   single `Fixed` nodeType.
+ * - Headings render as six discrete `H1` … `H6` nodeTypes. There is
+ *   no generic `Heading` nodeType with a `level` field.
+ * - `<Text>` block content is split into `TextLine` leaf children.
+ *   The actual text lives on `TextLine.textContent`; on non-`TextLine`
+ *   nodes (including the parent `Text` block), `textContent` is `null`.
+ * - Inline elements (`<Strong>`, `<Em>`, `<Code>`, `<Link>`) do NOT
+ *   appear as their own nodes — they contribute style runs within
+ *   `TextLine` leaves.
+ * - `<PageBreak>` produces no node. It triggers a page break at
+ *   layout time and is otherwise invisible.
+ * - `bookmark` on a container (`<View>`, `<Page>`, and bare `<ListItem>` /
+ *   `<TableRow>` / `<TableCell>`) produces a zero-height `Bookmark` marker
+ *   node (no rect, draws nothing) so the entry reaches the PDF outline.
+ *   The marker is emitted whether or not the container overflows a page,
+ *   and it is the ONLY element carrying that `bookmark` — one marker, one
+ *   outline entry.
+ *   Caveat: `bookmark` on a NON-container (`<Text>`, `<Image>`, `<Svg>`,
+ *   charts, form fields) still rides on that node's own element, and rows
+ *   or cells laid out inside a `<Table>` carry it on the row/cell element.
+ *   So `Bookmark` nodes are not an exhaustive index of the document's
+ *   bookmarks — scan the `bookmark` field for that.
+ *
+ * The runtime-conformance test in this package asserts every one of
+ * these transforms explicitly. If it breaks, update this JSDoc first.
+ */
+export interface ElementInfo {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    kind: ElementKind;
+    nodeType: ElementNodeType;
+    style: ElementStyleInfo;
+    children: ElementInfo[];
+    /**
+     * Rendered text for this line. Present ONLY on `TextLine` nodeType
+     * leaves — every non-`TextLine` node (including the parent `Text`
+     * block) emits `null` here at runtime. If you need the text of a
+     * `Text` block, concatenate its `TextLine` children's `textContent`.
+     */
+    textContent?: string | null;
+    /**
+     * Source file / line / column of the JSX that produced this node.
+     * Populated only when the render pipeline seeds
+     * `globalThis.__formeSourceMap` — currently only the CLI dev server
+     * does that. Production `renderDocument` / `renderDocumentWithLayout`
+     * calls never populate this field.
+     */
+    sourceLocation?: {
+        file: string;
+        line: number;
+        column: number;
+    };
+}
+export interface PageInfo {
+    width: number;
+    height: number;
+    contentX: number;
+    contentY: number;
+    contentWidth: number;
+    contentHeight: number;
+    elements: ElementInfo[];
+}
+export interface LayoutInfo {
+    pages: PageInfo[];
+}
+export interface RenderWithLayoutResult {
+    pdf: Uint8Array;
+    layout: LayoutInfo;
+    /**
+     * Non-fatal warnings raised during rendering (e.g. `pdfUa: true` was
+     * requested but no embeddable font was registered, so a standard font
+     * was left unembedded). Empty when nothing went wrong.
+     */
+    warnings: string[];
+}
+export declare function renderPdf(json: string): Promise<Uint8Array>;
+export declare function renderPdfWithLayout(json: string): Promise<RenderWithLayoutResult>;
+export interface CertificationConfig {
+    certificatePem: string;
+    privateKeyPem: string;
+    reason?: string;
+    location?: string;
+    contact?: string;
+    visible?: boolean;
+    page?: number;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+/** @deprecated Use CertificationConfig */
+export type SignatureConfig = CertificationConfig;
+export interface RenderDocumentOptions {
+    /** Data to embed as a hidden JSON attachment in the PDF. */
+    embedData?: unknown;
+    /** When true, form field values are rendered as static text. No interactive fields in output. */
+    flattenForms?: boolean;
+    /**
+     * Files to embed as PDF attachments (associated files). Under a
+     * PDF/A-3 level each becomes a conformant associated file; PDF/A-2
+     * refuses attachments (it only allows other PDF/A files).
+     */
+    attachments?: AttachmentOptions[];
+    /**
+     * Factur-X / ZUGFeRD e-invoice container: embeds the caller-supplied
+     * invoice XML with the spec filename, MIME type, `/AFRelationship`,
+     * and XMP identification. Requires `pdfa: "3b"` (or 3a/3u) on the
+     * `<Document>`. Forme does not generate or validate the XML itself.
+     */
+    facturX?: FacturXOptions;
+}
+export declare function renderDocument(element: ReactElement, options?: RenderDocumentOptions): Promise<Uint8Array>;
+export declare function renderDocumentWithLayout(element: ReactElement, options?: RenderDocumentOptions): Promise<RenderWithLayoutResult>;
+/**
+ * Render a pre-serialized document object (from `serialize()`) to PDF,
+ * resolving font sources (file paths, byte arrays) and HTTP image URLs
+ * first.
+ *
+ * Use this when you have a serialized doc (e.g. from a non-react
+ * adapter that calls its own `serialize()`) and need font/image
+ * resolution without going through the React element-based
+ * `renderDocument()`. The browser and worker entries export the same
+ * pair.
+ */
+export declare function renderSerializedDoc(doc: Record<string, unknown>, options?: RenderDocumentOptions): Promise<Uint8Array>;
+/**
+ * Like `renderSerializedDoc` but also returns layout info for overlays.
+ */
+export declare function renderSerializedDocWithLayout(doc: Record<string, unknown>, options?: RenderDocumentOptions): Promise<RenderWithLayoutResult>;
+export declare function renderTemplate(templateJson: string, dataJson: string): Promise<Uint8Array>;
+export declare function renderTemplateWithLayout(templateJson: string, dataJson: string): Promise<RenderWithLayoutResult>;
+export declare function certifyPdf(pdfBytes: Uint8Array, config: CertificationConfig): Promise<Uint8Array>;
+/** @deprecated Use certifyPdf */
+export declare const signPdf: typeof certifyPdf;
+export interface RedactionRegion {
+    /** 0-indexed page number. */
+    page: number;
+    /** X coordinate in points from the left edge. */
+    x: number;
+    /** Y coordinate in points from the top edge (web/screen coordinates). */
+    y: number;
+    /** Width of the redaction rectangle in points. */
+    width: number;
+    /** Height of the redaction rectangle in points. */
+    height: number;
+    /** Fill color as hex string (e.g. "#000000"). Defaults to black. */
+    color?: string;
+}
+export declare function redactPdf(pdfBytes: Uint8Array, regions: RedactionRegion[]): Promise<Uint8Array>;
+export interface RedactionPattern {
+    /** The text or regex pattern to search for. */
+    pattern: string;
+    /** 'Literal' for exact text match (case-insensitive), 'Regex' for regex. */
+    pattern_type: 'Literal' | 'Regex';
+    /** Optional 0-indexed page to restrict search to. */
+    page?: number;
+    /** Fill color as hex string (e.g. "#000000"). Defaults to black. */
+    color?: string;
+}
+/**
+ * Find text regions matching patterns in a PDF.
+ *
+ * Searches PDF content streams for literal or regex patterns and returns
+ * redaction regions (in web top-origin coordinates) for each match.
+ */
+export declare function findTextRegions(pdfBytes: Uint8Array, patterns: RedactionPattern[]): Promise<RedactionRegion[]>;
+/**
+ * Redact text matching patterns from a PDF.
+ *
+ * Convenience wrapper: finds all text matching the patterns, then
+ * applies coordinate-based redaction to each match.
+ */
+export declare function redactText(pdfBytes: Uint8Array, patterns: RedactionPattern[]): Promise<Uint8Array>;
+/**
+ * Merge multiple PDF documents into a single PDF.
+ *
+ * @param pdfs - Array of PDF byte arrays to merge in order.
+ * @returns The merged PDF as a Uint8Array.
+ */
+export declare function mergePdfs(pdfs: Uint8Array[]): Promise<Uint8Array>;
+export { extractData } from './extract.js';
+export type { AttachmentOptions, FacturXOptions, AfRelationship, FacturXProfile } from './attachments.js';

package/node_modules/@formepdf/core/dist/index.js

@@ -0,0 +1,167 @@
+// Node entry uses the wasm-pack `--target nodejs` build, which is a
+// self-initializing CJS module: it `require('fs').readFileSync`s its
+// own .wasm at import time, so callers don't need to await any init.
+import { render_pdf as wasmRenderPdf } from '../pkg-node/forme.js';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { applyAttachmentOptions } from './attachments.js';
+// ── Font resolution ──────────────────────────────────────────────
+function uint8ArrayToBase64(bytes) {
+    return Buffer.from(bytes).toString('base64');
+}
+async function resolveFonts(doc) {
+    const fonts = doc.fonts;
+    if (!fonts?.length)
+        return;
+    for (const font of fonts) {
+        if (font.src instanceof Uint8Array) {
+            font.src = uint8ArrayToBase64(font.src);
+        }
+        else if (typeof font.src === 'string' && !font.src.startsWith('data:')) {
+            const bytes = await readFile(resolve(font.src));
+            font.src = uint8ArrayToBase64(new Uint8Array(bytes));
+        }
+        // data URIs pass through as-is (engine extracts base64 portion)
+    }
+}
+// ── Image resolution ─────────────────────────────────────────────
+async function resolveImages(doc) {
+    const children = doc.children;
+    if (!children?.length)
+        return;
+    for (const child of children) {
+        await resolveImagesInNode(child);
+    }
+}
+async function resolveImagesInNode(node) {
+    const kind = node.kind;
+    if (kind?.type === 'Image' && typeof kind.src === 'string') {
+        const src = kind.src;
+        if (src.startsWith('http://') || src.startsWith('https://')) {
+            const res = await fetch(src);
+            if (!res.ok)
+                throw new Error(`Failed to fetch image: ${src} (${res.status})`);
+            const contentType = res.headers.get('content-type') || 'image/png';
+            const buf = new Uint8Array(await res.arrayBuffer());
+            kind.src = `data:${contentType};base64,${uint8ArrayToBase64(buf)}`;
+        }
+    }
+    const children = node.children;
+    if (children?.length) {
+        for (const child of children) {
+            await resolveImagesInNode(child);
+        }
+    }
+}
+// ── Render functions ───────────────────────────────────────────────
+export async function renderPdf(json) {
+    return wasmRenderPdf(json);
+}
+export async function renderPdfWithLayout(json) {
+    const { render_pdf_with_layout } = await import('../pkg-node/forme.js');
+    const result = render_pdf_with_layout(json);
+    return { ...result, warnings: result.warnings ?? [] };
+}
+export async function renderDocument(element, options) {
+    const { serialize } = await import('@formepdf/react');
+    const doc = serialize(element);
+    return renderSerializedDoc(doc, options);
+}
+export async function renderDocumentWithLayout(element, options) {
+    const { serialize } = await import('@formepdf/react');
+    const doc = serialize(element);
+    return renderSerializedDocWithLayout(doc, options);
+}
+// ── Serialized document rendering ────────────────────────────────────
+/**
+ * Render a pre-serialized document object (from `serialize()`) to PDF,
+ * resolving font sources (file paths, byte arrays) and HTTP image URLs
+ * first.
+ *
+ * Use this when you have a serialized doc (e.g. from a non-react
+ * adapter that calls its own `serialize()`) and need font/image
+ * resolution without going through the React element-based
+ * `renderDocument()`. The browser and worker entries export the same
+ * pair.
+ */
+export async function renderSerializedDoc(doc, options) {
+    if (options?.embedData !== undefined) {
+        doc.embeddedData = JSON.stringify(options.embedData);
+    }
+    if (options?.flattenForms) {
+        doc.flattenForms = true;
+    }
+    applyAttachmentOptions(doc, options);
+    await Promise.all([resolveFonts(doc), resolveImages(doc)]);
+    return renderPdf(JSON.stringify(doc));
+}
+/**
+ * Like `renderSerializedDoc` but also returns layout info for overlays.
+ */
+export async function renderSerializedDocWithLayout(doc, options) {
+    if (options?.embedData !== undefined) {
+        doc.embeddedData = JSON.stringify(options.embedData);
+    }
+    if (options?.flattenForms) {
+        doc.flattenForms = true;
+    }
+    applyAttachmentOptions(doc, options);
+    await Promise.all([resolveFonts(doc), resolveImages(doc)]);
+    return renderPdfWithLayout(JSON.stringify(doc));
+}
+// ── Template rendering ──────────────────────────────────────────────
+export async function renderTemplate(templateJson, dataJson) {
+    const { render_template_pdf } = await import('../pkg-node/forme.js');
+    return render_template_pdf(templateJson, dataJson);
+}
+export async function renderTemplateWithLayout(templateJson, dataJson) {
+    const { render_template_pdf_with_layout } = await import('../pkg-node/forme.js');
+    const result = render_template_pdf_with_layout(templateJson, dataJson);
+    return { ...result, warnings: result.warnings ?? [] };
+}
+// ── PDF certification ────────────────────────────────────────────────
+export async function certifyPdf(pdfBytes, config) {
+    const { certify_pdf } = await import('../pkg-node/forme.js');
+    return certify_pdf(pdfBytes, JSON.stringify(config));
+}
+/** @deprecated Use certifyPdf */
+export const signPdf = certifyPdf;
+export async function redactPdf(pdfBytes, regions) {
+    const { redact_pdf } = await import('../pkg-node/forme.js');
+    return redact_pdf(pdfBytes, JSON.stringify(regions));
+}
+/**
+ * Find text regions matching patterns in a PDF.
+ *
+ * Searches PDF content streams for literal or regex patterns and returns
+ * redaction regions (in web top-origin coordinates) for each match.
+ */
+export async function findTextRegions(pdfBytes, patterns) {
+    const { find_text_regions } = await import('../pkg-node/forme.js');
+    const json = find_text_regions(pdfBytes, JSON.stringify(patterns));
+    return JSON.parse(json);
+}
+/**
+ * Redact text matching patterns from a PDF.
+ *
+ * Convenience wrapper: finds all text matching the patterns, then
+ * applies coordinate-based redaction to each match.
+ */
+export async function redactText(pdfBytes, patterns) {
+    const { redact_text } = await import('../pkg-node/forme.js');
+    return redact_text(pdfBytes, JSON.stringify(patterns));
+}
+// ── PDF merging ──────────────────────────────────────────────────────
+/**
+ * Merge multiple PDF documents into a single PDF.
+ *
+ * @param pdfs - Array of PDF byte arrays to merge in order.
+ * @returns The merged PDF as a Uint8Array.
+ */
+export async function mergePdfs(pdfs) {
+    const { merge_pdfs } = await import('../pkg-node/forme.js');
+    const base64Pdfs = pdfs.map((pdf) => Buffer.from(pdf).toString('base64'));
+    return merge_pdfs(JSON.stringify(base64Pdfs));
+}
+// ── Data extraction ──────────────────────────────────────────────────
+export { extractData } from './extract.js';

package/node_modules/@formepdf/core/dist/layout.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Stable accessor helpers for the layout tree returned by
+ * `renderDocumentWithLayout()`.
+ *
+ * These helpers exist for one specific reason: the raw `ElementInfo` /
+ * `LayoutInfo` shape is documented but the documentation is not a
+ * contract, and it has drifted from runtime twice now. Consumers that
+ * hard-code invariants like "the text lives on `TextLine` children,
+ * not the parent `Text`" break silently every time an internal refactor
+ * shifts them.
+ *
+ * The helpers in this module encapsulate those invariants once, in a
+ * narrow, deliberately-maintained surface. Each helper corresponds to
+ * one of the layout-time transforms documented on `ElementInfo`. When
+ * an invariant changes in the engine, this file is where you update it
+ * — the runtime-conformance test (`tests/layout-shape.test.ts`) catches
+ * engine drift; helper tests (`tests/layout-helpers.test.ts`) catch
+ * drift in the helpers themselves.
+ *
+ * **Prefer these helpers to raw tree walking unless you specifically
+ * need raw shape access** (e.g. custom snapshot comparison, structural
+ * analysis the helpers don't cover).
+ */
+import type { LayoutInfo, PageInfo, ElementInfo, ElementNodeType } from './index.js';
+/**
+ * Any of the layout-tree root shapes a helper might reasonably accept.
+ * All helpers that traverse the tree accept this union so consumers
+ * don't have to unwrap `layout.pages[0].elements` themselves.
+ */
+export type LayoutRoot = LayoutInfo | PageInfo | PageInfo[] | ElementInfo | ElementInfo[];
+/**
+ * Depth-first walk of every node in `root`, calling `cb` for each.
+ *
+ * `path` is a human-readable string identifying where in the tree the
+ * node lives (e.g. `"[0].children[2]"` for the third child of the first
+ * root element). Useful for building error messages; ignore if you
+ * don't need it.
+ *
+ * Callbacks that return `false` skip descent into that node's children.
+ * Any other return (including `void`) descends normally.
+ */
+export declare function walkElements(root: LayoutRoot, cb: (node: ElementInfo, path: string) => void | boolean): void;
+/**
+ * Every node in `root` for which `predicate` returns truthy. Order is
+ * depth-first, source-order.
+ */
+export declare function findElements(root: LayoutRoot, predicate: (node: ElementInfo, path: string) => boolean): ElementInfo[];
+/**
+ * First node in `root` for which `predicate` returns truthy, or `null`
+ * if none. Order is depth-first, source-order. Stops as soon as a match
+ * is found (does not descend into the match's children).
+ */
+export declare function findFirstElement(root: LayoutRoot, predicate: (node: ElementInfo, path: string) => boolean): ElementInfo | null;
+/**
+ * Every `TextLine` leaf descendant of `node`, in source order. If
+ * `node` is itself a `TextLine`, returns `[node]`.
+ *
+ * This is the load-bearing helper: it encapsulates the invariant that
+ * text lives on `TextLine` children, never on the parent `Text` block.
+ */
+export declare function getTextLines(node: ElementInfo): ElementInfo[];
+/**
+ * Concatenated text of every `TextLine` descendant of `node`, joined
+ * with `"\n"`. If `node` is itself a `TextLine`, returns its own text.
+ *
+ * Lines are joined with newlines rather than spaces because the layout
+ * engine may have wrapped a single JSX string across multiple lines,
+ * and preserving that structure is more useful than silently smushing
+ * or space-joining. If you want a flat string, `.replace(/\n/g, ' ')`
+ * the result.
+ *
+ * Returns `""` if no `TextLine` descendants exist.
+ */
+export declare function getNodeText(node: ElementInfo): string;
+/**
+ * If `node` is a heading (`H1`–`H6`), returns the numeric level (1–6).
+ * Returns `null` otherwise.
+ *
+ * Encapsulates the invariant that headings render as six discriminated
+ * nodeTypes (`H1`, `H2`, …) rather than a generic `Heading` node with a
+ * separate `level` field.
+ */
+export declare function getHeadingLevel(node: ElementInfo): 1 | 2 | 3 | 4 | 5 | 6 | null;
+/**
+ * Every `TableRow` under `parent`, looking through `Table` wrapper nodes.
+ *
+ * Since engine 0.14, `<Table>` emits a `Table` container element per page
+ * fragment with the rows nested inside it. Pass the containing `page`
+ * (or the parent `View` that held the `<Table>` in JSX) as `parent` —
+ * or a `Table` element directly. Loose sibling rows (the pre-0.14 shape)
+ * are still returned for compatibility with stored layouts.
+ *
+ * Returns rows in source order.
+ */
+export declare function getTableRows(parent: PageInfo | ElementInfo): ElementInfo[];
+/**
+ * The `FixedHeader` and `FixedFooter` nodes on `page`. Encapsulates the
+ * invariant that `<Fixed position="header">` and `<Fixed position="footer">`
+ * produce two distinct nodeTypes rather than a shared `Fixed` node with
+ * a `position` field.
+ *
+ * Both arrays may be empty. Multiple entries in either array indicate
+ * repeating fixed regions (e.g. when the same `<Fixed>` repeats across
+ * page breaks — the layout may emit one node per occurrence).
+ */
+export declare function getFixedRegions(page: PageInfo): {
+    header: ElementInfo[];
+    footer: ElementInfo[];
+};
+/**
+ * Every `ListItem` child of a `List` node. Returns `[]` if `list` is
+ * not a `List` (silently — no throw, so this composes cleanly with
+ * `.flatMap`).
+ */
+export declare function getListItems(list: ElementInfo): ElementInfo[];
+/**
+ * Rendered text of the marker (`Lbl`) child of a `ListItem` — e.g.
+ * `"1."` for the first item of an `<OrderedList>`, `"•"` for an
+ * `<UnorderedList>` item. Returns `null` if `item` is not a `ListItem`
+ * or has no `Lbl` child.
+ *
+ * Encapsulates the invariant that list markers are separate `Lbl`
+ * children of each `ListItem` rather than a field on `ListItem` itself.
+ */
+export declare function getListItemMarker(item: ElementInfo): string | null;
+/**
+ * Type-guard for narrowing to a specific `ElementNodeType`. Useful for
+ * `.filter(isNodeType('TableRow'))` chains.
+ */
+export declare function isNodeType<T extends ElementNodeType>(nodeType: T): (node: ElementInfo) => node is ElementInfo & {
+    nodeType: T;
+};