@pdf-testkit/core 0.1.0

package/dist/diff/diff.d.ts

@@ -0,0 +1,9 @@
+import type { DiffOptions, DiffResult } from '../events.js';
+import type { StructuralSnapshot } from '../types.js';
+/**
+ * Compare two structural snapshots and emit typed semantic events. Never emits a
+ * raw JSON blob or a similarity score — only named events, which is the entire
+ * differentiation of the tool.
+ */
+export declare function diffSnapshots(baseline: StructuralSnapshot, next: StructuralSnapshot, opts?: DiffOptions): DiffResult;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/diff/diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAA8C,MAAM,cAAc,CAAC;AAExG,OAAO,KAAK,EAA4B,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAKhF;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,kBAAkB,EAC5B,IAAI,EAAE,kBAAkB,EACxB,IAAI,GAAE,WAAgB,GACrB,UAAU,CAwHZ"}

package/dist/diff/diff.js

@@ -0,0 +1,139 @@
+import { DEFAULT_POSITION_THRESHOLD_PTS, DEFAULT_SEVERITY } from '../events.js';
+import { centerDistance } from '../geometry.js';
+import { textPreview } from '../text/normalize.js';
+import { matchNodes } from './match.js';
+/**
+ * Compare two structural snapshots and emit typed semantic events. Never emits a
+ * raw JSON blob or a similarity score — only named events, which is the entire
+ * differentiation of the tool.
+ */
+export function diffSnapshots(baseline, next, opts = {}) {
+    // Identical structure -> no work. This is also what keeps re-serializing the
+    // same document from ever producing a spurious diff.
+    if (baseline.contentHash === next.contentHash) {
+        return { changed: false, events: [], baselineHash: baseline.contentHash, newHash: next.contentHash };
+    }
+    const threshold = opts.positionThresholdPts ?? DEFAULT_POSITION_THRESHOLD_PTS;
+    const ignore = new Set(opts.ignoreRoles ?? []);
+    const minConfidence = opts.minConfidence ?? 0;
+    const severityOf = (type) => opts.severityOverrides?.[type] ?? DEFAULT_SEVERITY[type];
+    const baseNodes = baseline.nodes.filter((n) => !ignore.has(n.role));
+    const nextNodes = next.nodes.filter((n) => !ignore.has(n.role));
+    const events = [];
+    if (baseline.pageCount !== next.pageCount) {
+        events.push({
+            type: 'page-count-changed',
+            severity: severityOf('page-count-changed'),
+            confidence: 1,
+            from: baseline.pageCount,
+            to: next.pageCount,
+            message: `page count changed ${baseline.pageCount} → ${next.pageCount}`,
+        });
+    }
+    const { pairs, added, removed } = matchNodes(baseNodes, nextNodes);
+    for (const { base, next: after } of pairs) {
+        const conf = Math.min(base.confidence, after.confidence);
+        if (after.role === 'table') {
+            const movedPage = base.pageIndex !== after.pageIndex;
+            const movedOnPage = centerDistance(base.bbox, after.bbox) > threshold;
+            if (movedPage || movedOnPage) {
+                events.push({
+                    type: 'table-moved',
+                    severity: severityOf('table-moved'),
+                    confidence: conf,
+                    nodeId: after.id,
+                    fromPage: base.pageIndex,
+                    toPage: after.pageIndex,
+                    fromBBox: base.bbox,
+                    toBBox: after.bbox,
+                    message: movedPage
+                        ? `table moved from page ${base.pageIndex + 1} to page ${after.pageIndex + 1}`
+                        : `table moved ${Math.round(centerDistance(base.bbox, after.bbox))}pt on page ${after.pageIndex + 1}`,
+                });
+            }
+        }
+        else if (base.pageIndex !== after.pageIndex) {
+            events.push({
+                type: 'element-moved-to-different-page',
+                severity: severityOf('element-moved-to-different-page'),
+                confidence: conf,
+                nodeId: after.id,
+                role: after.role,
+                textPreview: textPreview(after.text),
+                fromPage: base.pageIndex,
+                toPage: after.pageIndex,
+                message: `${describe(after)} moved from page ${base.pageIndex + 1} to page ${after.pageIndex + 1}`,
+            });
+        }
+        if (base.role === 'heading' && after.role === 'heading' && base.headingLevel !== after.headingLevel) {
+            events.push({
+                type: 'heading-hierarchy-changed',
+                severity: severityOf('heading-hierarchy-changed'),
+                confidence: conf,
+                nodeId: after.id,
+                textPreview: textPreview(after.text),
+                fromLevel: base.headingLevel,
+                toLevel: after.headingLevel,
+                message: `heading "${textPreview(after.text)}" hierarchy changed ${fmtLevel(base.headingLevel)} → ${fmtLevel(after.headingLevel)}`,
+            });
+        }
+        // Overflow is a regression only when it is newly present in this run.
+        if (after.overflow && !base.overflow) {
+            events.push(overflowEvent(after, severityOf('text-overflowed-container'), conf));
+        }
+    }
+    for (const node of added) {
+        events.push({
+            type: 'element-added',
+            severity: severityOf('element-added'),
+            confidence: node.confidence,
+            nodeId: node.id,
+            role: node.role,
+            textPreview: textPreview(node.text),
+            pageIndex: node.pageIndex,
+            message: `${describe(node)} added on page ${node.pageIndex + 1}`,
+        });
+        if (node.overflow) {
+            events.push(overflowEvent(node, severityOf('text-overflowed-container'), node.confidence));
+        }
+    }
+    for (const node of removed) {
+        events.push({
+            type: 'element-removed',
+            severity: severityOf('element-removed'),
+            confidence: node.confidence,
+            role: node.role,
+            textPreview: textPreview(node.text),
+            pageIndex: node.pageIndex,
+            message: `${describe(node)} removed from page ${node.pageIndex + 1}`,
+        });
+    }
+    const filtered = events.filter((e) => e.confidence >= minConfidence);
+    return {
+        changed: filtered.length > 0,
+        events: filtered,
+        baselineHash: baseline.contentHash,
+        newHash: next.contentHash,
+    };
+}
+function overflowEvent(node, severity, confidence) {
+    const o = node.overflow;
+    return {
+        type: 'text-overflowed-container',
+        severity,
+        confidence,
+        nodeId: node.id,
+        textPreview: textPreview(node.text),
+        overflow: o,
+        pageIndex: node.pageIndex,
+        message: `${describe(node)} overflowed its ${o.container} box by ${o.overflowPts}pt (${o.axis})`,
+    };
+}
+function describe(node) {
+    const preview = textPreview(node.text);
+    return preview ? `${node.role} "${preview}"` : node.role;
+}
+function fmtLevel(level) {
+    return level == null ? '—' : `H${level}`;
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../src/diff/diff.ts"],"names":[],"mappings":"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"}

package/dist/diff/match.d.ts

@@ -0,0 +1,21 @@
+import type { StructuralNode } from '../types.js';
+export interface NodePair {
+    base: StructuralNode;
+    next: StructuralNode;
+}
+export interface MatchResult {
+    pairs: NodePair[];
+    added: StructuralNode[];
+    removed: StructuralNode[];
+}
+/**
+ * Pair baseline nodes with new-run nodes so the diff engine can tell a *moved*
+ * element from a *removed + added* pair. Staged and greedy; each matched node
+ * leaves the pool.
+ *
+ * The stages are ordered from most to least certain so that identical content
+ * (stage 1) and minor edits (stage 2) never fall through to remove+add — the
+ * phantom-churn failure mode that makes a diff tool noisy.
+ */
+export declare function matchNodes(baseNodes: StructuralNode[], nextNodes: StructuralNode[]): MatchResult;
+//# sourceMappingURL=match.d.ts.map

package/dist/diff/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/diff/match.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAQD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,cAAc,EAAE,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,WAAW,CAmFhG"}

package/dist/diff/match.js

@@ -0,0 +1,133 @@
+import { centerDistance } from '../geometry.js';
+import { textSimilarity } from '../text/normalize.js';
+const FUZZY_THRESHOLD = 0.85;
+/** Boxes closer than this (center-to-center, points) are the same slot. Below a
+ * line height, so a deleted paragraph (which shifts others by a full line) never
+ * false-matches, while an in-place text edit always does. */
+const POSITION_MATCH_TOL = 4;
+/**
+ * Pair baseline nodes with new-run nodes so the diff engine can tell a *moved*
+ * element from a *removed + added* pair. Staged and greedy; each matched node
+ * leaves the pool.
+ *
+ * The stages are ordered from most to least certain so that identical content
+ * (stage 1) and minor edits (stage 2) never fall through to remove+add — the
+ * phantom-churn failure mode that makes a diff tool noisy.
+ */
+export function matchNodes(baseNodes, nextNodes) {
+    const baseLeft = new Set(baseNodes);
+    const nextLeft = new Set(nextNodes);
+    const pairs = [];
+    // Stage 1 — exact stable key (role + normText + headingLevel). Within a key,
+    // pair by (pageIndex, order) rank so identical repeated content stays aligned.
+    const nextByKey = groupBy([...nextLeft], exactKey);
+    for (const base of [...baseLeft].sort(byReadingOrder)) {
+        const bucket = nextByKey.get(exactKey(base));
+        if (!bucket || bucket.length === 0)
+            continue;
+        const next = bucket.shift();
+        pairs.push({ base, next });
+        baseLeft.delete(base);
+        nextLeft.delete(next);
+    }
+    // Stage 2 — fuzzy text for text/heading nodes (a changed number, a typo fix).
+    for (const base of [...baseLeft]) {
+        if (!isTexty(base) || base.normText == null)
+            continue;
+        let best = null;
+        let bestScore = FUZZY_THRESHOLD;
+        for (const cand of nextLeft) {
+            if (cand.role !== base.role || cand.normText == null)
+                continue;
+            const score = textSimilarity(base.normText, cand.normText);
+            if (score >= bestScore) {
+                bestScore = score;
+                best = cand;
+            }
+        }
+        if (best) {
+            pairs.push({ base, next: best });
+            baseLeft.delete(base);
+            nextLeft.delete(best);
+        }
+    }
+    // Stage 2.5 — positional fallback for text/heading nodes: same role, same
+    // page, and near-identical box is the same element with edited content. This
+    // is what stops a small text/punctuation edit from becoming remove+add churn
+    // (the fuzzy stage can't catch every rewrite).
+    for (const base of [...baseLeft]) {
+        if (!isTexty(base))
+            continue;
+        let best = null;
+        let bestD = POSITION_MATCH_TOL;
+        for (const cand of nextLeft) {
+            if (cand.role !== base.role || cand.pageIndex !== base.pageIndex)
+                continue;
+            const d = centerDistance(base.bbox, cand.bbox);
+            if (d <= bestD) {
+                bestD = d;
+                best = cand;
+            }
+        }
+        if (best) {
+            pairs.push({ base, next: best });
+            baseLeft.delete(base);
+            nextLeft.delete(best);
+        }
+    }
+    // Stage 3 — structural pairing for tables (and other non-text containers) by
+    // role + table signature, nearest in page order.
+    for (const base of [...baseLeft]) {
+        if (isTexty(base))
+            continue;
+        let best = null;
+        let bestCost = Infinity;
+        for (const cand of nextLeft) {
+            if (cand.role !== base.role)
+                continue;
+            if (!sameTableShape(base, cand))
+                continue;
+            const cost = Math.abs(cand.pageIndex - base.pageIndex) * 1000 + Math.abs(cand.order - base.order);
+            if (cost < bestCost) {
+                bestCost = cost;
+                best = cand;
+            }
+        }
+        if (best) {
+            pairs.push({ base, next: best });
+            baseLeft.delete(base);
+            nextLeft.delete(best);
+        }
+    }
+    return { pairs, added: [...nextLeft], removed: [...baseLeft] };
+}
+function exactKey(n) {
+    return `${n.role}|${n.normText ?? ''}|${n.headingLevel ?? ''}`;
+}
+function isTexty(n) {
+    return n.role === 'text' || n.role === 'heading';
+}
+function sameTableShape(a, b) {
+    if (!a.table || !b.table)
+        return true; // non-tables: shape is irrelevant
+    return a.table.rows === b.table.rows && a.table.cols === b.table.cols;
+}
+function byReadingOrder(a, b) {
+    return a.pageIndex - b.pageIndex || a.order - b.order;
+}
+function groupBy(items, key) {
+    const map = new Map();
+    for (const item of items) {
+        const k = key(item);
+        const bucket = map.get(k);
+        if (bucket)
+            bucket.push(item);
+        else
+            map.set(k, [item]);
+    }
+    // Keep each bucket in reading order for stable stage-1 pairing.
+    for (const bucket of map.values())
+        bucket.sort(byReadingOrder);
+    return map;
+}
+//# sourceMappingURL=match.js.map

package/dist/diff/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../../src/diff/match.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,79 @@
+import type { BBox, NodeRole } from './types.js';
+export type SemanticEventType = 'page-count-changed' | 'element-moved-to-different-page' | 'table-moved' | 'heading-hierarchy-changed' | 'text-overflowed-container' | 'element-added' | 'element-removed';
+export type Severity = 'info' | 'warn' | 'error';
+export interface BaseEvent {
+    type: SemanticEventType;
+    severity: Severity;
+    /** Human-readable, used in matcher/CLI failure output. */
+    message: string;
+    /** Min confidence of the involved nodes (0..1). */
+    confidence: number;
+}
+export interface PageCountChangedEvent extends BaseEvent {
+    type: 'page-count-changed';
+    from: number;
+    to: number;
+}
+export interface ElementMovedToPageEvent extends BaseEvent {
+    type: 'element-moved-to-different-page';
+    nodeId: string;
+    role: NodeRole;
+    textPreview: string;
+    fromPage: number;
+    toPage: number;
+}
+export interface TableMovedEvent extends BaseEvent {
+    type: 'table-moved';
+    nodeId: string;
+    fromPage: number;
+    toPage: number;
+    fromBBox: BBox;
+    toBBox: BBox;
+}
+export interface HeadingHierarchyChangedEvent extends BaseEvent {
+    type: 'heading-hierarchy-changed';
+    nodeId: string;
+    textPreview: string;
+    fromLevel: number | null;
+    toLevel: number | null;
+}
+export interface TextOverflowedEvent extends BaseEvent {
+    type: 'text-overflowed-container';
+    nodeId: string;
+    textPreview: string;
+    overflow: import('./types.js').OverflowInfo;
+    pageIndex: number;
+}
+export interface ElementAddedEvent extends BaseEvent {
+    type: 'element-added';
+    nodeId: string;
+    role: NodeRole;
+    textPreview: string;
+    pageIndex: number;
+}
+export interface ElementRemovedEvent extends BaseEvent {
+    type: 'element-removed';
+    role: NodeRole;
+    textPreview: string;
+    pageIndex: number;
+}
+export type SemanticEvent = PageCountChangedEvent | ElementMovedToPageEvent | TableMovedEvent | HeadingHierarchyChangedEvent | TextOverflowedEvent | ElementAddedEvent | ElementRemovedEvent;
+export interface DiffResult {
+    changed: boolean;
+    events: SemanticEvent[];
+    baselineHash: string;
+    newHash: string;
+}
+export interface DiffOptions {
+    /** Override the default severity for any event type. */
+    severityOverrides?: Partial<Record<SemanticEventType, Severity>>;
+    /** On-page movement beyond this many points counts as a table move. Default 24. */
+    positionThresholdPts?: number;
+    /** Roles to ignore entirely when diffing (e.g. ['image']). */
+    ignoreRoles?: NodeRole[];
+    /** Drop events whose confidence is below this (0..1). Default 0. */
+    minConfidence?: number;
+}
+export declare const DEFAULT_SEVERITY: Record<SemanticEventType, Severity>;
+export declare const DEFAULT_POSITION_THRESHOLD_PTS = 24;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/events.js

@@ -0,0 +1,11 @@
+export const DEFAULT_SEVERITY = {
+    'page-count-changed': 'error',
+    'heading-hierarchy-changed': 'error',
+    'text-overflowed-container': 'error',
+    'element-moved-to-different-page': 'warn',
+    'table-moved': 'warn',
+    'element-added': 'warn',
+    'element-removed': 'warn',
+};
+export const DEFAULT_POSITION_THRESHOLD_PTS = 24;
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAwGA,MAAM,CAAC,MAAM,gBAAgB,GAAwC;IACnE,oBAAoB,EAAE,OAAO;IAC7B,2BAA2B,EAAE,OAAO;IACpC,2BAA2B,EAAE,OAAO;IACpC,iCAAiC,EAAE,MAAM;IACzC,aAAa,EAAE,MAAM;IACrB,eAAe,EAAE,MAAM;IACvB,iBAAiB,EAAE,MAAM;CAC1B,CAAC;AAEF,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,CAAC"}

package/dist/extract/finalize.d.ts

@@ -0,0 +1,16 @@
+import type { Producer, StructuralSnapshot } from '../types.js';
+import type { RawNode, RawPage } from './raw.js';
+/**
+ * Shared post-processing that turns raw extractor output into a canonical
+ * `StructuralSnapshot`: assigns reading order, stable ids, normalized text,
+ * rounds all coordinates, links parents, and computes the content hash. Both
+ * `fromFormeLayout` and `fromPdf` converge here so downstream code is identical
+ * regardless of producer.
+ */
+export declare function finalize(producer: Producer, rawPages: RawPage[], rawNodes: RawNode[], opts?: {
+    source?: {
+        name?: string;
+    };
+    createdAt?: string;
+}): StructuralSnapshot;
+//# sourceMappingURL=finalize.d.ts.map

package/dist/extract/finalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize.d.ts","sourceRoot":"","sources":["../../src/extract/finalize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAgC,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAI9F,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEjD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,OAAO,EAAE,EACnB,QAAQ,EAAE,OAAO,EAAE,EACnB,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD,kBAAkB,CA0EpB"}

package/dist/extract/finalize.js

@@ -0,0 +1,88 @@
+import { median, round1, roundBBox } from '../geometry.js';
+import { normalizeText } from '../text/normalize.js';
+import { computeContentHash } from '../snapshot/serialize.js';
+/**
+ * Shared post-processing that turns raw extractor output into a canonical
+ * `StructuralSnapshot`: assigns reading order, stable ids, normalized text,
+ * rounds all coordinates, links parents, and computes the content hash. Both
+ * `fromFormeLayout` and `fromPdf` converge here so downstream code is identical
+ * regardless of producer.
+ */
+export function finalize(producer, rawPages, rawNodes, opts) {
+    const pages = [...rawPages].sort((a, b) => a.index - b.index);
+    // Reading order + a per-page ordinal counter keyed by role, computed on nodes
+    // sorted by y-band then x. y-band tolerance derives from the page's median
+    // line height so items on the same visual line share a band.
+    const finalIdByTemp = new Map();
+    const ordered = [];
+    const orderByTemp = new Map();
+    const nodeIdsByPage = new Map();
+    for (const page of pages) {
+        const pageNodes = rawNodes.filter((n) => n.pageIndex === page.index);
+        const rowTol = readingRowTolerance(pageNodes);
+        const band = (y) => Math.round(y / rowTol);
+        pageNodes.sort((a, b) => band(a.bbox.y) - band(b.bbox.y) || a.bbox.x - b.bbox.x);
+        const ordinalByRole = new Map();
+        const ids = [];
+        pageNodes.forEach((node, i) => {
+            const ordinal = ordinalByRole.get(node.role) ?? 0;
+            ordinalByRole.set(node.role, ordinal + 1);
+            const id = `${page.index}:${node.role}:${ordinal}`;
+            finalIdByTemp.set(node.tempId, id);
+            orderByTemp.set(node.tempId, i);
+            ids.push(id);
+            ordered.push(node);
+        });
+        nodeIdsByPage.set(page.index, ids);
+    }
+    const nodes = ordered.map((raw) => {
+        const id = finalIdByTemp.get(raw.tempId);
+        const parentId = raw.parentTempId != null ? finalIdByTemp.get(raw.parentTempId) ?? null : null;
+        const node = {
+            id,
+            role: raw.role,
+            pageIndex: raw.pageIndex,
+            bbox: roundBBox(raw.bbox),
+            order: orderByTemp.get(raw.tempId) ?? 0,
+            parentId,
+            text: raw.text,
+            normText: normalizeText(raw.text),
+            font: raw.font
+                ? { ...raw.font, size: raw.font.size == null ? null : round1(raw.font.size) }
+                : null,
+            headingLevel: raw.headingLevel,
+            overflow: raw.overflow,
+            confidence: raw.confidence,
+        };
+        if (raw.table)
+            node.table = raw.table;
+        return node;
+    });
+    const pageSnapshots = pages.map((p) => ({
+        index: p.index,
+        width: round1(p.width),
+        height: round1(p.height),
+        contentBox: roundBBox(p.contentBox),
+        nodeIds: nodeIdsByPage.get(p.index) ?? [],
+    }));
+    const withoutHash = {
+        version: 1,
+        producer,
+        createdAt: opts?.createdAt ?? new Date().toISOString(),
+        ...(opts?.source ? { source: opts.source } : {}),
+        pageCount: pageSnapshots.length,
+        pages: pageSnapshots,
+        nodes,
+    };
+    return { ...withoutHash, contentHash: computeContentHash(withoutHash) };
+}
+function readingRowTolerance(nodes) {
+    const heights = nodes
+        .filter((n) => n.role === 'text' || n.role === 'heading' || n.role === 'cell')
+        .map((n) => n.font?.size ?? n.bbox.height)
+        .filter((h) => h > 0);
+    if (heights.length === 0)
+        return 6;
+    return Math.max(2, 0.5 * median(heights));
+}
+//# sourceMappingURL=finalize.js.map

package/dist/extract/finalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize.js","sourceRoot":"","sources":["../../src/extract/finalize.ts"],"names":[],"mappings":"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"}

package/dist/extract/fromFormeLayout.d.ts

@@ -0,0 +1,82 @@
+import type { NodeRole, StructuralSnapshot } from '../types.js';
+/**
+ * Minimal structural mirror of `@formepdf/core`'s `LayoutInfo`. Declared locally
+ * so `@pdf-testkit/core` never has to depend on `@formepdf/core` — any object of
+ * this shape (e.g. the result of `renderPdfWithLayout(...).layout`) works.
+ *
+ * Real FormePDF output (verified by dogfooding, not just the published types):
+ *  - headings are `H1`..`H6` (level encoded in the tag), not a generic `Heading`
+ *  - block text nodes have `textContent: undefined`; the actual text lives on
+ *    nested `TextLine` children
+ *  - there is no `Table` wrapper node — `TableRow`s are direct children of the
+ *    page (or a container), so a table is synthesized from contiguous rows
+ * This extractor also accepts the simpler documented shape (`Heading`, `Table`
+ * with `textContent` set directly), so both are supported.
+ */
+export interface FormeLayoutInfo {
+    pages: FormePageInfo[];
+}
+export interface FormePageInfo {
+    width: number;
+    height: number;
+    contentX: number;
+    contentY: number;
+    contentWidth: number;
+    contentHeight: number;
+    elements: FormeElementInfo[];
+}
+export interface FormeElementInfo {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** e.g. "H1".."H6", "Text", "TextLine", "Table", "TableRow", "TableCell", "View", "Image". */
+    nodeType: string;
+    style?: {
+        fontSize?: number;
+        fontWeight?: number;
+        fontFamily?: string;
+        fontStyle?: string;
+    };
+    children?: FormeElementInfo[];
+    textContent?: string;
+}
+/**
+ * Explicit disposition for every value of `@formepdf/core`'s `ElementNodeType`
+ * union. Every union member has a deliberate role here — none rely on the
+ * fallthrough. Audited against @formepdf/core 0.12.1; re-review whenever that
+ * dependency version bumps (the coverage test in formeNodeTypeCoverage.test.ts
+ * enforces that this table + FORME_INTENTIONALLY_UNMAPPED cover the whole union).
+ *
+ * Judgment calls (confirmed): charts + all graphics → opaque `image` regions;
+ * form controls → structural `container`; `Lbl` (list marker) → `text`.
+ */
+export declare const FORME_ROLE_BY_NODE_TYPE: Record<string, NodeRole>;
+/**
+ * Union members intentionally given no semantic role (out of scope for v0.1),
+ * with a one-line reason each. Currently empty — every ElementNodeType maps to a
+ * deliberate role above. Kept as the explicit opt-out mechanism and referenced
+ * by the coverage test so a future "don't test this" decision is visible, never
+ * a silent default.
+ */
+export declare const FORME_INTENTIONALLY_UNMAPPED: ReadonlySet<string>;
+/**
+ * Authoritative, heuristic-free extraction from FormePDF layout metadata. Roles,
+ * heading levels, and the content box are explicit, so every node is emitted at
+ * confidence 1.0. This is the reliable path the whole product is validated on
+ * before the fragile pdfjs path is touched.
+ */
+export declare function fromFormeLayout(layout: FormeLayoutInfo, opts?: {
+    source?: {
+        name?: string;
+    };
+    createdAt?: string;
+    assertShape?: boolean;
+}): StructuralSnapshot;
+/** Thrown when FormePDF's layout shape no longer matches what this extractor
+ * understands — a broken contract on the authoritative fast path, which must
+ * fail loudly rather than silently produce a wrong diff. */
+export declare class FormeShapeError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=fromFormeLayout.d.ts.map

package/dist/extract/fromFormeLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fromFormeLayout.d.ts","sourceRoot":"","sources":["../../src/extract/fromFormeLayout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,QAAQ,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAMhF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE;QACN,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CA4C5D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,MAAM,CAE3D,CAAC;AA4BH;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/E,kBAAkB,CA8GpB;AAED;;4DAE4D;AAC5D,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B"}