@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/syntax/xref.js

@@ -0,0 +1,341 @@
+// Copyright (c) 2026 AwaCloud SAS
+// Author: Matthieu Bouilloux
+// SPDX-License-Identifier: AGPL-3.0-only
+// Dual-licensed; see the NOTICE file for licensing and any additional terms.
+
+/**
+ * @fileoverview Classical PDF cross-reference table parser per ISO
+ * 32000-2:2020 §7.5.4, plus the two cross-reference-stream helpers the
+ * incremental writer needs (§7.5.8): `readXrefStreamDict` reads the
+ * dictionary of a `/Type /XRef` stream section WITHOUT decoding its data,
+ * and `buildXrefStream` emits an uncompressed `/Type /XRef` stream section
+ * for an incremental update over a stream base.
+ *
+ * @module pdf/syntax/xref
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfTokenizer } from './tokenizer.js';
+import { pdfParser } from './parser.js';
+
+export const pdfXref = {
+    name: 'pdfXref',
+    dependencies: ['pdfErrors', 'pdfTokenizer', 'pdfParser'],
+    deps: [pdfErrors, pdfTokenizer, pdfParser],
+    factory(errors, tokenizerMod, parserMod) {
+        const { ParseError, RenderError } = errors;
+        const tokenize = tokenizerMod.tokenize;
+        const lastIndexOfBytes = tokenizerMod.lastIndexOfBytes;
+        const parseObject = parserMod.parseObject;
+        const LF = 0x0A, CR = 0x0D, SP = 0x20;
+
+        function locateStartXref(bytes) {
+            const tail = Math.max(0, bytes.length - 8192);
+            const idx = lastIndexOfBytes(bytes,
+                new Uint8Array([0x73, 0x74, 0x61, 0x72, 0x74, 0x78, 0x72, 0x65, 0x66]),
+                bytes.length);
+            if (idx < tail) return -1;
+            return idx;
+        }
+
+        function readStartXref(bytes, at) {
+            const tok = tokenize(bytes, { start: at });
+            const kw = tok.next();
+            if (!kw || kw.kind !== 'kw' || kw.value !== 'startxref') {
+                throw new ParseError('pdf/xref/no-startxref',
+                    'startxref keyword not found',
+                    { context: { offset: at } });
+            }
+            const num = tok.next();
+            if (!num || num.kind !== 'int' || num.value < 0) {
+                throw new ParseError('pdf/xref/bad-startxref',
+                    'startxref must be followed by a non-negative integer',
+                    { context: { offset: at } });
+            }
+            return num.value;
+        }
+
+        function parseIntBytes(bytes, off, len) {
+            let n = 0;
+            for (let i = 0; i < len; i++) {
+                const b = bytes[off + i];
+                if (b < 0x30 || b > 0x39) {
+                    throw new ParseError('pdf/xref/bad-digit',
+                        'expected ASCII digit in xref entry',
+                        { context: { offset: off + i, byte: b } });
+                }
+                n = n * 10 + (b - 0x30);
+            }
+            return n;
+        }
+
+        function parseXrefTable(bytes, at) {
+            const tok = tokenize(bytes, { start: at });
+            const kw = tok.next();
+            if (!kw || kw.kind !== 'kw' || kw.value !== 'xref') {
+                throw new ParseError('pdf/xref/no-xref-keyword',
+                    'expected xref keyword',
+                    { context: { offset: at } });
+            }
+            const entries = {};
+            for (;;) {
+                const first = tok.peek();
+                if (!first || first.kind !== 'int') {
+                    if (first) tok.seek(first.offset);
+                    break;
+                }
+                tok.next();
+                const cnt = tok.next();
+                if (!cnt || cnt.kind !== 'int' || cnt.value < 0) {
+                    throw new ParseError('pdf/xref/bad-subsection-header',
+                        'xref subsection header must be `<first> <count>`',
+                        { context: { offset: first.offset } });
+                }
+                let p = tok.pos();
+                if (p < bytes.length && bytes[p] === CR) p++;
+                if (p < bytes.length && bytes[p] === LF) p++;
+                for (let k = 0; k < cnt.value; k++) {
+                    if (p + 20 > bytes.length) {
+                        throw new ParseError('pdf/xref/truncated-entry',
+                            'truncated xref entry',
+                            { context: { offset: p, expected: 20 } });
+                    }
+                    const off = parseIntBytes(bytes, p, 10);
+                    if (bytes[p + 10] !== SP) {
+                        throw new ParseError('pdf/xref/bad-entry-format',
+                            'xref entry missing space at col 10',
+                            { context: { offset: p } });
+                    }
+                    const gen = parseIntBytes(bytes, p + 11, 5);
+                    if (bytes[p + 16] !== SP) {
+                        throw new ParseError('pdf/xref/bad-entry-format',
+                            'xref entry missing space at col 16',
+                            { context: { offset: p } });
+                    }
+                    const tag = bytes[p + 17];
+                    if (tag !== 0x6E && tag !== 0x66) {
+                        throw new ParseError('pdf/xref/bad-entry-flag',
+                            'xref entry flag must be n or f',
+                            { context: { offset: p, byte: tag } });
+                    }
+                    entries[first.value + k] = {
+                        offset: off,
+                        gen,
+                        free: tag === 0x66
+                    };
+                    p += 20;
+                }
+                tok.seek(p);
+            }
+            return { entries, end: tok.pos() };
+        }
+
+        function parseTrailerDict(bytes, at) {
+            const tok = tokenize(bytes, { start: at });
+            const kw = tok.next();
+            if (!kw || kw.kind !== 'kw' || kw.value !== 'trailer') {
+                throw new ParseError('pdf/xref/no-trailer',
+                    'expected trailer keyword',
+                    { context: { offset: at } });
+            }
+            const dict = parseObject(tok);
+            if (dict.type !== 'dict') {
+                throw new ParseError('pdf/xref/trailer-not-dict',
+                    'trailer must be a dictionary',
+                    { context: { offset: at } });
+            }
+            return { dict, end: tok.pos() };
+        }
+
+        /**
+         * Read the dictionary of the cross-reference stream section at `at`
+         * (`N G obj << /Type /XRef … >> stream`, §7.5.8). The stream data is
+         * NOT decoded — the dict alone carries the section's trailer keys
+         * (`/Root`, `/Info`, `/ID`, `/Size`, `/Prev`) — so no filter module
+         * is needed and an indirect `/Length` is not an obstacle here.
+         *
+         * @param {Uint8Array} bytes
+         * @param {number} at  Offset designated by `startxref` or a `/Prev`.
+         * @returns {{num: number, gen: number, dict: object}}
+         * @throws ParseError `pdf/xref/not-xref-stream` — no indirect object
+         *   at `at`, or one that is not a `/Type /XRef` stream.
+         */
+        function readXrefStreamDict(bytes, at) {
+            const notStream = (why) => new ParseError('pdf/xref/not-xref-stream',
+                `no cross-reference stream at offset ${at}: ${why}`,
+                { context: { offset: at } });
+            if (!Number.isInteger(at) || at < 0 || at >= bytes.length) {
+                throw notStream('offset outside the file');
+            }
+            let num, gen, kw, dict, after;
+            try {
+                const tok = tokenize(bytes, { start: at });
+                num = tok.next();
+                gen = tok.next();
+                kw = tok.next();
+                if (!num || num.kind !== 'int' || !gen || gen.kind !== 'int'
+                    || !kw || kw.kind !== 'kw' || kw.value !== 'obj') {
+                    throw notStream('no indirect object header');
+                }
+                dict = parseObject(tok);
+                after = tok.peek();
+            } catch (e) {
+                if (e && e.code === 'pdf/xref/not-xref-stream') throw e;
+                throw notStream('the object does not parse');
+            }
+            const type = dict && dict.type === 'dict' && dict.entries.Type;
+            if (!type || type.type !== 'name' || type.value !== 'XRef'
+                || !after || after.kind !== 'kw' || after.value !== 'stream') {
+                throw notStream('the object is not a /Type /XRef stream');
+            }
+            return { num: num.value, gen: gen.value, dict };
+        }
+
+        /** Smallest number of bytes (>= 1) that holds `n` big-endian. */
+        function byteWidth(n) {
+            let w = 1;
+            while (n > 0xFF) { n = Math.floor(n / 256); w++; }
+            return w;
+        }
+
+        function hexLit(bytes) {
+            const H = '0123456789ABCDEF';
+            let s = '<';
+            for (let i = 0; i < bytes.length; i++) {
+                s += H[bytes[i] >> 4] + H[bytes[i] & 0xF];
+            }
+            return s + '>';
+        }
+
+        function isRef(r) {
+            return !!r && Number.isInteger(r.num) && r.num >= 1;
+        }
+
+        /**
+         * Emit one uncompressed cross-reference stream section for an
+         * incremental update (§7.5.8, §7.5.6), as the complete indirect
+         * object `num 0 obj << /Type /XRef … >> stream … endstream endobj`.
+         * The caller appends `startxref` / `%%EOF`.
+         *
+         * Rows: object 0's free-list head, one type-1 row per `entries`
+         * item, and the stream's own type-1 row at `offset`. `/Index` lists
+         * one pair per contiguous run of object numbers; `/W` is the
+         * narrowest `[1 w2 w3]` that fits; `/Size` is `num + 1` or
+         * `opts.size`, whichever is larger. No `/Filter`: the data is
+         * written uncompressed, so no filter module is involved.
+         *
+         * `opts.encrypt` (an indirect reference) is written as
+         * `/Encrypt n g R` right after `/ID`: an update over an encrypted
+         * document repeats the document's `/Encrypt` (ISO 32000-2 §7.5.6).
+         * Without it the output is unchanged.
+         *
+         * @param {{num: number, offset: number,
+         *          entries: Array<{num: number, offset: number, gen?: number}>,
+         *          size?: number, prev: number,
+         *          root: {num: number, gen?: number},
+         *          info?: {num: number, gen?: number}|null,
+         *          id?: Array<Uint8Array>|null,
+         *          encrypt?: {num: number, gen?: number}|null}} opts
+         * @returns {Uint8Array}
+         * @throws RenderError `pdf/xref/bad-stream-section` on an unusable
+         *   `num`, `offset`, `prev`, `root`, `encrypt` (anything but an
+         *   indirect reference — a direct `/Encrypt` dictionary is not
+         *   written here) or entry.
+         */
+        function buildXrefStream(opts) {
+            const bad = (why) => new RenderError('pdf/xref/bad-stream-section',
+                `cannot build the cross-reference stream: ${why}`);
+            if (!opts || !Number.isInteger(opts.num) || opts.num < 1) {
+                throw bad('num must be an integer >= 1');
+            }
+            if (!Number.isInteger(opts.offset) || opts.offset < 0) {
+                throw bad('offset must be an integer >= 0');
+            }
+            if (!Number.isInteger(opts.prev) || opts.prev < 0) {
+                throw bad('prev must be an integer >= 0');
+            }
+            if (!isRef(opts.root)) throw bad('root must be { num >= 1, gen }');
+            if (opts.encrypt != null && !isRef(opts.encrypt)) {
+                throw bad('encrypt must be an indirect reference { num >= 1, gen }');
+            }
+            const rows = new Map();
+            rows.set(0, [0, 0, 65535]);
+            for (const e of opts.entries || []) {
+                if (!e || !Number.isInteger(e.num) || e.num < 1
+                    || !Number.isInteger(e.offset) || e.offset < 0) {
+                    throw bad('each entry needs num >= 1 and offset >= 0');
+                }
+                rows.set(e.num, [1, e.offset, e.gen | 0]);
+            }
+            rows.set(opts.num, [1, opts.offset, 0]);
+
+            const nums = Array.from(rows.keys()).sort((a, b) => a - b);
+            let max2 = 0, max3 = 0;
+            for (const r of rows.values()) {
+                if (r[1] > max2) max2 = r[1];
+                if (r[2] > max3) max3 = r[2];
+            }
+            const w = [1, byteWidth(max2), byteWidth(max3)];
+            const rec = w[0] + w[1] + w[2];
+            const data = new Uint8Array(nums.length * rec);
+            let o = 0;
+            for (const n of nums) {
+                const r = rows.get(n);
+                let at = o;
+                for (let f = 0; f < 3; f++) {
+                    let v = r[f];
+                    for (let k = w[f] - 1; k >= 0; k--) {
+                        data[at + k] = v & 0xFF;
+                        v = Math.floor(v / 256);
+                    }
+                    at += w[f];
+                }
+                o += rec;
+            }
+
+            const index = [];
+            for (let i = 0; i < nums.length;) {
+                let j = i;
+                while (j + 1 < nums.length && nums[j + 1] === nums[j] + 1) j++;
+                index.push(`${nums[i]} ${j - i + 1}`);
+                i = j + 1;
+            }
+
+            const size = Math.max(opts.num + 1,
+                Number.isInteger(opts.size) ? opts.size : 0);
+            let d = `<< /Type /XRef /Size ${size} /W [${w.join(' ')}]`
+                + ` /Index [${index.join(' ')}]`
+                + ` /Root ${opts.root.num} ${opts.root.gen | 0} R`;
+            if (isRef(opts.info)) d += ` /Info ${opts.info.num} ${opts.info.gen | 0} R`;
+            if (opts.id && opts.id[0] instanceof Uint8Array
+                && opts.id[1] instanceof Uint8Array) {
+                d += ` /ID [${hexLit(opts.id[0])}${hexLit(opts.id[1])}]`;
+            }
+            if (isRef(opts.encrypt)) {
+                d += ` /Encrypt ${opts.encrypt.num} ${opts.encrypt.gen | 0} R`;
+            }
+            d += ` /Prev ${opts.prev} /Length ${data.length} >>`;
+
+            const te = new TextEncoder();
+            const head = te.encode(`${opts.num} 0 obj\n${d}\nstream\n`);
+            const tail = te.encode('\nendstream\nendobj\n');
+            const out = new Uint8Array(head.length + data.length + tail.length);
+            out.set(head, 0);
+            out.set(data, head.length);
+            out.set(tail, head.length + data.length);
+            return out;
+        }
+
+        return {
+            locateStartXref,
+            readStartXref,
+            parseXrefTable,
+            parseTrailerDict,
+            readXrefStreamDict,
+            buildXrefStream
+        };
+    }
+};

package/src/tagged/classMap.js

@@ -0,0 +1,81 @@
+// Copyright (c) 2026 AwaCloud SAS
+// Author: Matthieu Bouilloux
+// SPDX-License-Identifier: AGPL-3.0-only
+// Dual-licensed; see the NOTICE file for licensing and any additional terms.
+
+/**
+ * @fileoverview ClassMap typing per ISO 32000-2:2020 §14.7.5.4.
+ *
+ * The structure-tree `/ClassMap` maps class names (used in StructElem
+ * `/C` entries) to attribute objects or arrays of attribute objects.
+ * An attribute object is a dict that begins with `/O` naming the owner
+ * (e.g. `/Layout`, `/Table`, `/List`).
+ *
+ * The values are stored verbatim; only top-level shape is validated.
+ *
+ * @module pdf/tagged/classMap
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfClassMap = {
+    name: 'pdfClassMap',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        function typeClassMap(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/tagged/class-map/not-dict',
+                    'ClassMap must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const classes = {};
+            for (const [k, v] of Object.entries(dict.entries)) {
+                if (!v) {
+                    throw new ParseError('pdf/tagged/class-map/bad-value',
+                        'ClassMap entry has no value',
+                        { context: { key: k } });
+                }
+                if (v.type === 'dict') {
+                    classes[k] = [v];
+                } else if (v.type === 'array') {
+                    for (const item of v.items) {
+                        if (!item || item.type !== 'dict') {
+                            throw new ParseError('pdf/tagged/class-map/bad-item',
+                                'ClassMap array entries must be attribute dicts',
+                                { context: { key: k, kind: item && item.type } });
+                        }
+                    }
+                    classes[k] = v.items.slice();
+                } else {
+                    throw new ParseError('pdf/tagged/class-map/bad-value',
+                        'ClassMap values must be a dict or array of dicts',
+                        { context: { key: k, kind: v.type } });
+                }
+            }
+            return { classes, raw: dict };
+        }
+
+        function getClassAttributes(typed, name, owner) {
+            if (!typed || !typed.classes) return [];
+            const list = typed.classes[name];
+            if (!list) return [];
+            if (!owner) return list.slice();
+            const out = [];
+            for (const d of list) {
+                const o = d.entries && d.entries.O;
+                if (o && o.type === 'name' && o.value === owner) out.push(d);
+            }
+            return out;
+        }
+
+        return { typeClassMap, getClassAttributes };
+    }
+};

package/src/tagged/markedContent.js

@@ -0,0 +1,123 @@
+// Copyright (c) 2026 AwaCloud SAS
+// Author: Matthieu Bouilloux
+// SPDX-License-Identifier: AGPL-3.0-only
+// Dual-licensed; see the NOTICE file for licensing and any additional terms.
+
+/**
+ * @fileoverview Marked-content scanner per ISO 32000-2:2020 §14.6.
+ *
+ * Walks an operator list produced by `pdfContentStream.parseContentStream`
+ * and extracts marked-content sequences delimited by `BMC` / `BDC` /
+ * `EMC`. Each entry records its tag, properties (the inline dict or the
+ * /Properties name resolved by the caller from the page resources), the
+ * `MCID` (if any) and the inclusive op-index range.
+ *
+ * Also exposes `resolveMcidToStruct(pageRef, mcid, parentTree, resolveRef)`
+ * which combines a page's `/StructParents` key with the document
+ * `/ParentTree` to find the owning StructElem ref of a given MCID.
+ *
+ * @module pdf/tagged/markedContent
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+import { pdfParentTree } from './parentTree.js';
+
+export const pdfMarkedContent = {
+    name: 'pdfMarkedContent',
+    dependencies: ['pdfErrors', 'pdfParser', 'pdfParentTree'],
+    deps: [pdfErrors, pdfParser, pdfParentTree],
+    factory(errors, parser, parentTree) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+        const { lookupParent } = parentTree;
+
+        function extractMcids(opsList) {
+            if (!Array.isArray(opsList)) {
+                throw new ParseError('pdf/tagged/marked-content/bad-ops',
+                    'extractMcids expects an array of ops',
+                    { context: { typeof: typeof opsList } });
+            }
+            const out = [];
+            const stack = [];
+            for (let i = 0; i < opsList.length; i++) {
+                const op = opsList[i];
+                if (!op || typeof op.op !== 'string') continue;
+                if (op.op === 'BMC') {
+                    stack.push(openEntry(op, i, null));
+                } else if (op.op === 'BDC') {
+                    stack.push(openEntry(op, i, op.args[1] || null));
+                } else if (op.op === 'EMC') {
+                    if (stack.length === 0) {
+                        throw new ParseError('pdf/tagged/marked-content/unmatched-emc',
+                            'EMC without matching BMC/BDC',
+                            { context: { index: i } });
+                    }
+                    const e = stack.pop();
+                    e.end = i;
+                    out.push(e);
+                }
+            }
+            if (stack.length > 0) {
+                throw new ParseError('pdf/tagged/marked-content/unterminated',
+                    'BMC/BDC without matching EMC',
+                    { context: { open: stack.length } });
+            }
+            out.sort((a, b) => a.start - b.start);
+            return out;
+        }
+
+        function openEntry(op, index, properties) {
+            const tag = op.args[0];
+            if (!tag || tag.type !== 'name') {
+                throw new ParseError('pdf/tagged/marked-content/bad-tag',
+                    'marked-content tag must be a name',
+                    { context: { index, kind: tag && tag.type } });
+            }
+            return {
+                tag: tag.value,
+                start: index,
+                end: -1,
+                mcid: readMcid(properties),
+                properties
+            };
+        }
+
+        function readMcid(properties) {
+            if (!properties || properties.type !== 'dict') return null;
+            const m = properties.entries.MCID;
+            if (!m) return null;
+            if (m.type !== 'int' && m.type !== 'real') return null;
+            return m.value | 0;
+        }
+
+        function resolveMcidToStruct(pageDict, mcid, pTree, resolveRef) {
+            if (!isType(pageDict, 'dict')) {
+                throw new ParseError('pdf/tagged/marked-content/bad-page',
+                    'page must be a dict',
+                    { context: { kind: pageDict && pageDict.type } });
+            }
+            const sp = pageDict.entries.StructParents;
+            if (!sp || (sp.type !== 'int' && sp.type !== 'real')) {
+                return null;
+            }
+            const found = lookupParent(pTree, sp.value | 0, resolveRef);
+            if (!found) return null;
+            let arr = found;
+            if (arr.type === 'ref') arr = resolveRef(arr);
+            if (!arr || arr.type !== 'array') {
+                throw new ParseError('pdf/tagged/marked-content/bad-entry',
+                    'page /ParentTree entry must be an array indexed by MCID',
+                    { context: { kind: arr && arr.type } });
+            }
+            const item = arr.items[mcid | 0];
+            if (!item) return null;
+            return item;
+        }
+
+        return { extractMcids, resolveMcidToStruct };
+    }
+};

package/src/tagged/parentTree.js

@@ -0,0 +1,126 @@
+// Copyright (c) 2026 AwaCloud SAS
+// Author: Matthieu Bouilloux
+// SPDX-License-Identifier: AGPL-3.0-only
+// Dual-licensed; see the NOTICE file for licensing and any additional terms.
+
+/**
+ * @fileoverview Number-tree walker for `/ParentTree` per ISO 32000-2:2020
+ * §7.9.7 and §14.7.4.
+ *
+ * The structure tree's `/ParentTree` is a number tree mapping integer
+ * keys (the `/StructParents` or `/StructParent` values found on pages
+ * and annotations / content-stream objects) to:
+ *
+ *   - a StructElem reference (annotations / form XObjects, where a
+ *     single MCID/object owns the parent), or
+ *   - an array of StructElem references indexed by MCID (pages, where
+ *     each MCID on the page has its own parent).
+ *
+ * A number-tree node is a dict with either `/Nums` (leaf) or `/Kids`
+ * (intermediate). Intermediate nodes carry `/Limits` (2-int array)
+ * giving the inclusive key range of the subtree.
+ *
+ * @module pdf/tagged/parentTree
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfParentTree = {
+    name: 'pdfParentTree',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        function lookupParent(tree, key, resolveRef, opts) {
+            const maxDepth = (opts && opts.maxDepth) || 32;
+            let node = tree;
+            if (node && node.type === 'ref') node = resolveRef(node);
+            return walk(node, 0);
+
+            function walk(n, depth) {
+                if (depth > maxDepth) {
+                    throw new ParseError('pdf/tagged/parent-tree/max-depth',
+                        'number tree depth limit exceeded',
+                        { context: { depth, maxDepth } });
+                }
+                if (!isType(n, 'dict')) {
+                    throw new ParseError('pdf/tagged/parent-tree/not-dict',
+                        'number tree node is not a dict',
+                        { context: { kind: n && n.type } });
+                }
+                const nums = n.entries.Nums;
+                const kids = n.entries.Kids;
+
+                if (nums && nums.type === 'array') {
+                    return findInNums(nums.items, key);
+                }
+                if (kids && kids.type === 'array') {
+                    for (const k of kids.items) {
+                        if (k.type !== 'ref') {
+                            throw new ParseError('pdf/tagged/parent-tree/non-ref-kid',
+                                'number-tree /Kids entries must be indirect refs',
+                                { context: { kind: k.type } });
+                        }
+                        const child = resolveRef(k);
+                        if (!isType(child, 'dict')) {
+                            throw new ParseError('pdf/tagged/parent-tree/bad-child',
+                                'number-tree kid did not resolve to dict',
+                                { context: { ref: k } });
+                        }
+                        if (inLimits(child.entries.Limits, key)) {
+                            return walk(child, depth + 1);
+                        }
+                    }
+                    return null;
+                }
+                throw new ParseError('pdf/tagged/parent-tree/empty-node',
+                    'number tree node has neither /Nums nor /Kids',
+                    { context: {} });
+            }
+        }
+
+        function findInNums(items, key) {
+            if (items.length % 2 !== 0) {
+                throw new ParseError('pdf/tagged/parent-tree/bad-nums',
+                    '/Nums must have an even number of entries',
+                    { context: { len: items.length } });
+            }
+            for (let i = 0; i < items.length; i += 2) {
+                const k = items[i];
+                if (!k || (k.type !== 'int' && k.type !== 'real')) {
+                    throw new ParseError('pdf/tagged/parent-tree/bad-key',
+                        '/Nums key must be a number',
+                        { context: { kind: k && k.type } });
+                }
+                if ((k.value | 0) === key) return items[i + 1];
+            }
+            return null;
+        }
+
+        function inLimits(limits, key) {
+            if (!limits) return true;
+            if (limits.type !== 'array' || limits.items.length !== 2) {
+                throw new ParseError('pdf/tagged/parent-tree/bad-limits',
+                    '/Limits must be a 2-element array of integers',
+                    { context: { kind: limits.type } });
+            }
+            const lo = limits.items[0];
+            const hi = limits.items[1];
+            if (!lo || !hi || (lo.type !== 'int' && lo.type !== 'real')
+                           || (hi.type !== 'int' && hi.type !== 'real')) {
+                throw new ParseError('pdf/tagged/parent-tree/bad-limits',
+                    '/Limits entries must be numbers',
+                    { context: {} });
+            }
+            return key >= (lo.value | 0) && key <= (hi.value | 0);
+        }
+
+        return { lookupParent };
+    }
+};