@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/document/pages.js

@@ -0,0 +1,103 @@
+// 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 Page-tree walker per ISO 32000-2:2020 §7.7.3.
+ *
+ * The page tree is a balanced tree of `/Type /Pages` nodes whose leaves
+ * are `/Type /Page` dicts. Internal nodes carry `/Kids` (an array of
+ * refs) and `/Count` (number of leaves in the subtree). The catalog
+ * holds a reference to the root.
+ *
+ * This module walks an already-resolved tree (the caller passes a
+ * `resolveRef(ref) → obj` function) and produces an ordered list of
+ * page refs.
+ *
+ * @module pdf/document/pages
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfPages = {
+    name: 'pdfPages',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parserMod) {
+        const { ParseError } = errors;
+        const isType = (parserMod && parserMod.isType)
+            || ((v, kind) => !!(v && v.type === kind));
+
+        function walkPageTree(rootRef, resolveRef, opts) {
+            const maxDepth = (opts && opts.maxDepth) || 64;
+            const maxPages = (opts && opts.maxPages) || 200000;
+            const out = [];
+            const visited = new Set();
+            walk(rootRef, 0);
+            return out;
+
+            function walk(ref, depth) {
+                if (depth > maxDepth) {
+                    throw new ParseError('pdf/pages/max-depth',
+                        'page tree depth limit exceeded',
+                        { context: { depth, maxDepth } });
+                }
+                const key = ref.num + ':' + ref.gen;
+                if (visited.has(key)) {
+                    throw new ParseError('pdf/pages/cycle',
+                        'cycle detected in page tree',
+                        { context: { ref } });
+                }
+                visited.add(key);
+
+                const node = resolveRef({ type: 'ref', num: ref.num, gen: ref.gen });
+                if (!isType(node, 'dict')) {
+                    throw new ParseError('pdf/pages/not-dict',
+                        'page tree node is not a dict',
+                        { context: { ref } });
+                }
+                const t = node.entries.Type;
+                const isPage = (t && t.type === 'name' && t.value === 'Page')
+                    || (!node.entries.Kids && !t);
+                if (isPage) {
+                    out.push({ num: ref.num, gen: ref.gen });
+                    if (out.length > maxPages) {
+                        throw new ParseError('pdf/pages/too-many',
+                            'page count limit exceeded',
+                            { context: { maxPages } });
+                    }
+                    return;
+                }
+
+                const kids = node.entries.Kids;
+                if (!kids || kids.type !== 'array') {
+                    throw new ParseError('pdf/pages/missing-kids',
+                        'intermediate page tree node missing /Kids array',
+                        { context: { ref, hasKids: !!kids } });
+                }
+                for (const k of kids.items) {
+                    if (k.type !== 'ref') {
+                        throw new ParseError('pdf/pages/non-ref-kid',
+                            'page tree /Kids entries must be indirect refs',
+                            { context: { kind: k.type } });
+                    }
+                    walk({ num: k.num, gen: k.gen }, depth + 1);
+                }
+            }
+        }
+
+        function readPageCount(node) {
+            if (!isType(node, 'dict')) return null;
+            const c = node.entries.Count;
+            if (!c || (c.type !== 'int' && c.type !== 'real')) return null;
+            return c.value | 0;
+        }
+
+        return { walkPageTree, readPageCount };
+    }
+};

package/src/document/resources.js

@@ -0,0 +1,146 @@
+// 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 Resource dictionary resolution per ISO 32000-2:2020
+ * §7.8.3.
+ *
+ * A Page (or Form XObject) carries a `/Resources` dict with six
+ * named sub-dicts that map local names (used in content streams) to
+ * indirect references:
+ *
+ * | Sub-dict      | Maps to                          |
+ * |---------------|----------------------------------|
+ * | `/Font`       | Font dicts                       |
+ * | `/XObject`    | Image / Form XObjects            |
+ * | `/ColorSpace` | ColorSpace arrays / refs         |
+ * | `/ExtGState`  | ExtGState dicts                  |
+ * | `/Pattern`    | Pattern dicts                    |
+ * | `/Shading`    | Shading dicts                    |
+ *
+ * A `/ProcSet` array exists for legacy PDFs and is read but never
+ * required at L2 (the spec deprecates it in PDF 2.0).
+ *
+ * Resources are **inheritable**: a Page that lacks `/Resources` of its
+ * own inherits from its `/Parent` chain in the page tree (§7.7.3.4).
+ *
+ * @module pdf/document/resources
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfResources = {
+    name: 'pdfResources',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parserObjMod) {
+        const { ParseError } = errors;
+        const isType = (parserObjMod && parserObjMod.isType)
+            || ((v, kind) => !!(v && v.type === kind));
+
+        const CATEGORIES = ['Font', 'XObject', 'ColorSpace', 'ExtGState', 'Pattern', 'Shading'];
+
+        /**
+         * Type a `/Resources` dictionary into its six category maps.
+         *
+         * A category value (`/Font`, `/ExtGState`, …) may itself be an
+         * indirect reference (ISO 32000-2 §7.3.10 — any object may be
+         * indirect); when `resolveRef` is supplied such a reference is
+         * resolved through it (the document's own resolver, which reaches
+         * objects inside object streams). Without a resolver a referenced
+         * category is rejected as before (`pdf/resources/bad-subdict`).
+         *
+         * @param {object|null} dict Typed `/Resources` dict, or `null`.
+         * @param {(ref: object) => object} [resolveRef] Indirect-ref resolver.
+         * @returns {object} The typed `Resources` shape.
+         */
+        function typeResources(dict, resolveRef) {
+            const out = {
+                Font: {}, XObject: {}, ColorSpace: {},
+                ExtGState: {}, Pattern: {}, Shading: {},
+                ProcSet: null,
+                raw: dict || null
+            };
+            if (!dict) return out;
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/resources/not-dict',
+                    '/Resources must be a dictionary',
+                    { context: { type: dict.type } });
+            }
+            for (const cat of CATEGORIES) {
+                let sub = dict.entries[cat];
+                if (!sub) continue;
+                if (sub.type === 'ref' && typeof resolveRef === 'function') {
+                    sub = resolveRef(sub);
+                    if (!sub || sub.type === 'null') continue;
+                }
+                if (sub.type !== 'dict') {
+                    throw new ParseError('pdf/resources/bad-subdict',
+                        `/${cat} entry must be a dictionary`,
+                        { context: { category: cat, type: sub.type } });
+                }
+                out[cat] = { ...sub.entries };
+            }
+            if (dict.entries.ProcSet && dict.entries.ProcSet.type === 'array') {
+                out.ProcSet = dict.entries.ProcSet.items
+                    .filter(it => it.type === 'name')
+                    .map(it => it.value);
+            }
+            return out;
+        }
+
+        function resolvePageResources(pageDict, resolveRef) {
+            let node = pageDict;
+            const visited = new Set();
+            for (let safety = 0; safety < 64; safety++) {
+                if (!isType(node, 'dict')) break;
+                if (node.entries.Resources) {
+                    const r = node.entries.Resources;
+                    if (r.type === 'ref') return typeResources(resolveRef(r), resolveRef);
+                    if (r.type === 'dict') return typeResources(r, resolveRef);
+                    throw new ParseError('pdf/resources/bad-shape',
+                        '/Resources must be a dict or indirect ref',
+                        { context: { type: r.type } });
+                }
+                const parent = node.entries.Parent;
+                if (!parent || parent.type !== 'ref') break;
+                const key = parent.num + ':' + parent.gen;
+                if (visited.has(key)) {
+                    throw new ParseError('pdf/resources/cycle',
+                        'cycle in page-tree parent chain',
+                        { context: { ref: parent } });
+                }
+                visited.add(key);
+                node = resolveRef(parent);
+            }
+            return typeResources(null);
+        }
+
+        function lookupResource(resources, category, name, resolveRef) {
+            const cat = resources[category];
+            if (!cat) {
+                throw new ParseError('pdf/resources/unknown-category',
+                    `unknown resource category "${category}"`,
+                    { context: { category } });
+            }
+            const entry = cat[name];
+            if (!entry) {
+                throw new ParseError('pdf/resources/missing-name',
+                    `resource /${category} /${name} not found`,
+                    { context: { category, name, available: Object.keys(cat) } });
+            }
+            if (entry.type === 'ref' && typeof resolveRef === 'function') {
+                return resolveRef(entry);
+            }
+            return entry;
+        }
+
+        return { typeResources, resolvePageResources, lookupResource };
+    }
+};

package/src/document/writer.js

@@ -0,0 +1,211 @@
+// 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 Document writer — turn a model into PDF bytes (`%PDF-2.0` unless `opts.version` says otherwise).
+ *
+ * Strategy:
+ *
+ * 1. Emit the header (`%PDF-<version>\n`) and the binary comment line (bytes `0x25 0xE2 0xE3 0xCF 0xD3 0x0A`).
+ * 2. For each indirect object, serialize via `serializeIndirect` and
+ *    record its byte offset.
+ * 3. Emit a classical xref table (`xref` keyword + subsection
+ *    `0 N` + 20-byte entries — object 0 is the head of the free list
+ *    with `0000000000 65535 f `).
+ * 4. Emit the trailer dict + `startxref` pointer + `%%EOF`.
+ *
+ * @module pdf/document/writer
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfSerializer } from '../syntax/serializer.js';
+
+export const pdfWriter = {
+    name: 'pdfWriter',
+    dependencies: ['pdfErrors', 'pdfSerializer'],
+    deps: [pdfErrors, pdfSerializer],
+    factory(errors, serializerMod) {
+        const { RenderError } = errors;
+        const serializeIndirect = serializerMod.serializeIndirect;
+
+        const te = new TextEncoder();
+
+        function pad10(n) { return String(n).padStart(10, '0'); }
+
+        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 concat(arrays) {
+            let n = 0;
+            for (const a of arrays) n += a.length;
+            const out = new Uint8Array(n);
+            let o = 0;
+            for (const a of arrays) { out.set(a, o); o += a.length; }
+            return out;
+        }
+
+        function validateIndirects(list) {
+            let prev = -1;
+            for (const it of list) {
+                if (!it || !Number.isFinite(it.num) || it.num < 1) {
+                    throw new RenderError('pdf/writer/bad-indirect',
+                        'each indirect requires num >= 1',
+                        { context: { item: it } });
+                }
+                if (it.num === prev) {
+                    throw new RenderError('pdf/writer/duplicate-num',
+                        'duplicate object number',
+                        { context: { num: it.num } });
+                }
+                prev = it.num;
+            }
+        }
+
+        function buildXref(maxNum, offsets) {
+            let s = `xref\n0 ${maxNum + 1}\n`;
+            s += '0000000000 65535 f \n';
+            for (let n = 1; n <= maxNum; n++) {
+                if (offsets.has(n)) {
+                    s += pad10(offsets.get(n)) + ' 00000 n \n';
+                } else {
+                    s += '0000000000 00000 f \n';
+                }
+            }
+            return te.encode(s);
+        }
+
+        function buildTrailer(opts) {
+            const parts = [`trailer\n<< /Size ${opts.size}`];
+            parts.push(` /Root ${opts.root.num} ${opts.root.gen | 0} R`);
+            if (opts.info) parts.push(` /Info ${opts.info.num} ${opts.info.gen | 0} R`);
+            if (opts.id) {
+                parts.push(' /ID [');
+                parts.push(hexLit(opts.id[0]));
+                parts.push(hexLit(opts.id[1]));
+                parts.push(']');
+            }
+            parts.push(' >>\n');
+            parts.push(`startxref\n${opts.xrefOffset}\n%%EOF\n`);
+            return te.encode(parts.join(''));
+        }
+
+        function writeDocument(opts) {
+            if (!opts || !Array.isArray(opts.indirects)) {
+                throw new RenderError('pdf/writer/bad-input',
+                    'writeDocument expects { indirects: [...] }');
+            }
+            if (!opts.root || !Number.isFinite(opts.root.num)) {
+                throw new RenderError('pdf/writer/no-root',
+                    'writeDocument requires opts.root');
+            }
+            const version = opts.version || '2.0';
+            if (!/^\d\.\d$/.test(version)) {
+                throw new RenderError('pdf/writer/bad-version',
+                    'version must look like "x.y"',
+                    { context: { version } });
+            }
+            const indirects = opts.indirects.slice().sort((a, b) => a.num - b.num);
+            validateIndirects(indirects);
+
+            const parts = [];
+            let cursor  = 0;
+            const offsets = new Map();
+
+            function push(u8) {
+                parts.push(u8);
+                cursor += u8.length;
+            }
+
+            push(te.encode(`%PDF-${version}\n`));
+            push(new Uint8Array([0x25, 0xE2, 0xE3, 0xCF, 0xD3, 0x0A]));
+
+            const maxNum = indirects.length > 0 ? indirects[indirects.length - 1].num : 0;
+            for (const { num, gen, value } of indirects) {
+                offsets.set(num, cursor);
+                push(serializeIndirect(num, gen, value));
+            }
+
+            const xrefOffset = cursor;
+            push(buildXref(maxNum, offsets));
+
+            const size = maxNum + 1;
+            push(buildTrailer({
+                size,
+                root: opts.root,
+                info: opts.info,
+                id:   opts.id,
+                xrefOffset
+            }));
+
+            return concat(parts);
+        }
+
+        /**
+         * Snapshot a `pdf.read()` model into an ordered `{ num, gen, value }`
+         * list ready for `writeDocument`. Forces full resolution first; an
+         * in-use xref entry that cannot be resolved is NOT written (its
+         * indirect never reaches the cache), and the loss is reported rather
+         * than silent.
+         *
+         * Lenient by default: the list is still returned, with the skipped
+         * entries on its non-enumerable `skippedObjects` property
+         * (`Array<{ num, gen, code }>`, empty when nothing was skipped;
+         * `code` is the caught error's code when it is a typed pdf error,
+         * else `'unknown'`). With `opts.strict === true` the call throws a
+         * `RenderError` coded `pdf/writer/unresolvable-objects` instead,
+         * carrying the same list in `context.objects`.
+         *
+         * @param {object} model A model produced by `pdf.read()`.
+         * @param {{ strict?: boolean }} [opts]
+         * @returns {Array<{num:number, gen:number, value:object}>}
+         */
+        function assembleIndirects(model, opts) {
+            if (!model || !model._raw || typeof model._raw.resolve !== 'function') {
+                throw new RenderError('pdf/writer/bad-model',
+                    'assembleIndirects requires a model produced by pdf.read()');
+            }
+            const skipped = [];
+            for (const k of Object.keys(model.xref.entries)) {
+                const e = model.xref.entries[k];
+                if (e.free) continue;
+                try {
+                    model._raw.resolve({ type: 'ref', num: Number(k), gen: e.gen });
+                } catch (err) {
+                    skipped.push({
+                        num: Number(k),
+                        gen: e.gen,
+                        code: errors.isPdfError(err) ? err.code : 'unknown'
+                    });
+                }
+            }
+            if (skipped.length > 0 && opts && opts.strict === true) {
+                throw new RenderError('pdf/writer/unresolvable-objects',
+                    `${skipped.length} object${skipped.length === 1 ? '' : 's'} could not be resolved and would be dropped`,
+                    { context: { objects: skipped } });
+            }
+            const out = [];
+            for (const [key, rec] of model._raw.indirects.entries()) {
+                const [n, g] = key.split(':').map(Number);
+                out.push({ num: n, gen: g, value: rec.value });
+            }
+            out.sort((a, b) => a.num - b.num);
+            Object.defineProperty(out, 'skippedObjects', {
+                value: skipped, enumerable: false, writable: true, configurable: true
+            });
+            return out;
+        }
+
+        return { writeDocument, assembleIndirects };
+    }
+};