@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/font/type3.js

@@ -0,0 +1,75 @@
+// 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 Type 3 user-defined font typing per ISO 32000-2:2020 §9.6.4.
+ *
+ * Unlike Type1/TrueType/CIDFont (which delegate to `@awacloud/fonts`),
+ * Type 3 fonts are **PDF-specific** — each glyph is defined by a
+ * content stream in the `/CharProcs` dict, not a portable font format.
+ *
+ * @module pdf/font/type3
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfType3 = {
+    name: 'pdfType3',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parserMod) {
+        const { ParseError } = errors;
+        const isType = (parserMod && parserMod.isType)
+            || ((v, kind) => !!(v && v.type === kind));
+
+        function toArray(v, n) {
+            if (!v || v.type !== 'array' || v.items.length !== n) return null;
+            const r = new Array(n);
+            for (let i = 0; i < n; i++) {
+                const it = v.items[i];
+                if (!it || (it.type !== 'int' && it.type !== 'real')) return null;
+                r[i] = it.value;
+            }
+            return r;
+        }
+
+        function typeType3(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/type3/not-dict',
+                    'Type 3 font must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (!e.Subtype || e.Subtype.type !== 'name' || e.Subtype.value !== 'Type3') {
+                throw new ParseError('pdf/type3/wrong-subtype',
+                    '/Subtype must be /Type3',
+                    { context: { actual: e.Subtype && e.Subtype.value } });
+            }
+            return {
+                subtype: 'Type3',
+                bbox:    toArray(e.FontBBox, 4),
+                matrix:  toArray(e.FontMatrix, 6) || [0.001, 0, 0, 0.001, 0, 0],
+                charProcs: e.CharProcs && e.CharProcs.type === 'dict'
+                    ? { ...e.CharProcs.entries } : {},
+                encoding:  e.Encoding || null,
+                firstChar: e.FirstChar && e.FirstChar.type === 'int' ? e.FirstChar.value : null,
+                lastChar:  e.LastChar  && e.LastChar.type  === 'int' ? e.LastChar.value  : null,
+                widths:    e.Widths && e.Widths.type === 'array'
+                    ? e.Widths.items.filter(it => it.type === 'int' || it.type === 'real')
+                                    .map(it => it.value)
+                    : null,
+                fontDescriptor: e.FontDescriptor || null,
+                resources:      e.Resources || null,
+                raw: dict
+            };
+        }
+
+        return { typeType3 };
+    }
+};

package/src/form/acroform.js

@@ -0,0 +1,94 @@
+// 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 AcroForm dict typing per ISO 32000-2:2020 §12.7.3.
+ *
+ * @module pdf/form/acroform
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfAcroForm = {
+    name: 'pdfAcroForm',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parserMod) {
+        const { ParseError } = errors;
+        const isType = (parserMod && parserMod.isType)
+            || ((v, kind) => !!(v && v.type === kind));
+
+        const KNOWN = new Set([
+            'Fields', 'NeedAppearances', 'SigFlags', 'CO', 'DR', 'DA', 'Q', 'XFA'
+        ]);
+
+        function toBool(v, dflt) {
+            if (!v) return dflt;
+            if (v.type !== 'bool') return dflt;
+            return !!v.value;
+        }
+
+        function toInt(v, dflt) {
+            if (!v) return dflt;
+            if (v.type !== 'int' && v.type !== 'real') return dflt;
+            return v.value | 0;
+        }
+
+        function toRefArray(v, errCode) {
+            if (!v) return [];
+            if (v.type !== 'array') {
+                throw new ParseError(errCode,
+                    'expected an array of indirect references',
+                    { context: { kind: v.type } });
+            }
+            const out = [];
+            for (const it of v.items) {
+                if (!it || it.type !== 'ref') {
+                    throw new ParseError(errCode,
+                        'array entry must be an indirect reference',
+                        { context: { kind: it && it.type } });
+                }
+                out.push({ num: it.num, gen: it.gen });
+            }
+            return out;
+        }
+
+        function typeAcroForm(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/form/acroform/not-dict',
+                    'AcroForm must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+
+            const fields = toRefArray(e.Fields, 'pdf/form/acroform/bad-fields');
+
+            const out = {
+                fields,
+                needAppearances: toBool(e.NeedAppearances, false),
+                sigFlags: toInt(e.SigFlags, 0),
+                co: e.CO ? toRefArray(e.CO, 'pdf/form/acroform/bad-co') : [],
+                dr: isType(e.DR, 'dict') ? e.DR : null,
+                da: isType(e.DA, 'string') ? e.DA.value : null,
+                q:  toInt(e.Q, 0),
+                raw: dict,
+                _extras: {}
+            };
+
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            if (e.XFA) out._extras.XFA = e.XFA;
+
+            return out;
+        }
+
+        return { typeAcroForm };
+    }
+};

package/src/form/appearance.js

@@ -0,0 +1,90 @@
+// 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 Appearance-stream dict typing per ISO 32000-2:2020 §12.5.5.
+ *
+ * @module pdf/form/appearance
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfAppearance = {
+    name: 'pdfAppearance',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parserMod) {
+        const { ParseError } = errors;
+        const isType = (parserMod && parserMod.isType)
+            || ((v, kind) => !!(v && v.type === kind));
+
+        const SLOTS = ['N', 'R', 'D'];
+
+        function normalise(v, slot) {
+            if (!v) {
+                return { default: null, states: {} };
+            }
+            if (v.type === 'ref' || v.type === 'stream') {
+                return { default: v, states: {} };
+            }
+            if (v.type === 'dict') {
+                const states = {};
+                for (const k of Object.keys(v.entries)) {
+                    const sub = v.entries[k];
+                    if (!sub || (sub.type !== 'ref' && sub.type !== 'stream')) {
+                        throw new ParseError('pdf/form/ap/bad-state',
+                            'appearance-state entry must be a stream or indirect ref',
+                            { context: { slot, state: k, kind: sub && sub.type } });
+                    }
+                    states[k] = sub;
+                }
+                return { default: null, states };
+            }
+            throw new ParseError('pdf/form/ap/bad-slot',
+                '/AP slot must be a stream, indirect ref, or sub-dict',
+                { context: { slot, kind: v.type } });
+        }
+
+        function typeAppearanceStreams(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/form/ap/not-dict',
+                    '/AP must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+
+            const out = {
+                N: normalise(e.N, 'N'),
+                R: e.R ? normalise(e.R, 'R') : null,
+                D: e.D ? normalise(e.D, 'D') : null,
+                raw: dict,
+                _extras: {}
+            };
+
+            if (!e.N) {
+                throw new ParseError('pdf/form/ap/missing-n',
+                    '/AP is missing required /N entry',
+                    { context: {} });
+            }
+
+            for (const k of Object.keys(e)) {
+                if (k !== 'N' && k !== 'R' && k !== 'D') out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function listPopulatedSlots(ap) {
+            const out = [];
+            for (const s of SLOTS) if (ap[s]) out.push(s);
+            return out;
+        }
+
+        return { typeAppearanceStreams, listPopulatedSlots };
+    }
+};

package/src/form/button.js

@@ -0,0 +1,105 @@
+// 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 Button field typing per ISO 32000-2:2020 §12.7.5.2.
+ *
+ * @module pdf/form/button
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfButtonField = {
+    name: 'pdfButtonField',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parserMod) {
+        const { ParseError } = errors;
+        const isType = (parserMod && parserMod.isType)
+            || ((v, kind) => !!(v && v.type === kind));
+
+        const FLAG_NO_TOGGLE_OFF    = 1 << 14;
+        const FLAG_RADIO            = 1 << 15;
+        const FLAG_PUSHBUTTON       = 1 << 16;
+        const FLAG_RADIOS_IN_UNISON = 1 << 25;
+
+        const KNOWN = new Set([
+            'Type', 'FT', 'Parent', 'Kids', 'T', 'TU', 'TM', 'Ff', 'V', 'DV',
+            'AA', 'DA', 'Q', 'Opt', 'AP', 'AS'
+        ]);
+
+        function intOr(v, dflt) {
+            if (!v) return dflt;
+            if (v.type !== 'int' && v.type !== 'real') return dflt;
+            return v.value | 0;
+        }
+
+        function toOpt(v) {
+            if (!v) return [];
+            if (v.type !== 'array') {
+                throw new ParseError('pdf/form/btn/bad-opt',
+                    '/Opt must be an array when present',
+                    { context: { kind: v.type } });
+            }
+            const out = [];
+            for (const it of v.items) {
+                if (isType(it, 'string'))     out.push(it.value);
+                else if (isType(it, 'name'))  out.push(it.value);
+                else {
+                    throw new ParseError('pdf/form/btn/bad-opt-entry',
+                        '/Opt entries must be strings or names',
+                        { context: { kind: it && it.type } });
+                }
+            }
+            return out;
+        }
+
+        function typeButtonField(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/form/btn/not-dict',
+                    'button field must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.FT && (e.FT.type !== 'name' || e.FT.value !== 'Btn')) {
+                throw new ParseError('pdf/form/btn/bad-ft',
+                    '/FT must be /Btn for a button field',
+                    { context: { actual: e.FT.value } });
+            }
+
+            const flags = intOr(e.Ff, 0);
+            const isPush  = (flags & FLAG_PUSHBUTTON) !== 0;
+            const isRadio = (flags & FLAG_RADIO)      !== 0;
+            let kind;
+            if (isPush)       kind = 'pushbutton';
+            else if (isRadio) kind = 'radio';
+            else              kind = 'checkbox';
+
+            const out = {
+                ft: 'Btn',
+                flags,
+                kind,
+                noToggleToOff:  (flags & FLAG_NO_TOGGLE_OFF)    !== 0,
+                radiosInUnison: (flags & FLAG_RADIOS_IN_UNISON) !== 0,
+                v:   isType(e.V,  'name')   ? e.V.value  : null,
+                dv:  isType(e.DV, 'name')   ? e.DV.value : null,
+                opt: toOpt(e.Opt),
+                t:   isType(e.T,  'string') ? e.T.value  : null,
+                raw: dict,
+                _extras: {}
+            };
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        return { typeButtonField };
+    }
+};

package/src/form/choice.js

@@ -0,0 +1,152 @@
+// 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 Choice field typing per ISO 32000-2:2020 §12.7.5.4.
+ *
+ * @module pdf/form/choice
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfChoiceField = {
+    name: 'pdfChoiceField',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parserMod) {
+        const { ParseError } = errors;
+        const isType = (parserMod && parserMod.isType)
+            || ((v, kind) => !!(v && v.type === kind));
+
+        const F_COMBO              = 1 << 17;
+        const F_EDIT               = 1 << 18;
+        const F_SORT               = 1 << 19;
+        const F_MULTI_SELECT       = 1 << 21;
+        const F_DO_NOT_SPELLCHECK  = 1 << 22;
+        const F_COMMIT_ON_SEL_CHG  = 1 << 26;
+
+        const KNOWN = new Set([
+            'Type', 'FT', 'Parent', 'Kids', 'T', 'TU', 'TM', 'Ff', 'V', 'DV',
+            'AA', 'DA', 'Q', 'Opt', 'TI', 'I', 'AP'
+        ]);
+
+        function intOr(v, dflt) {
+            if (!v) return dflt;
+            if (v.type !== 'int' && v.type !== 'real') return dflt;
+            return v.value | 0;
+        }
+
+        function isStringy(v) { return !!(v && (v.type === 'string' || v.type === 'name')); }
+
+        function toOpt(v) {
+            if (!v) return [];
+            if (v.type !== 'array') {
+                throw new ParseError('pdf/form/ch/bad-opt',
+                    '/Opt must be an array when present',
+                    { context: { kind: v.type } });
+            }
+            const out = [];
+            for (const it of v.items) {
+                if (isType(it, 'string')) {
+                    out.push({ export: it.value, display: it.value });
+                } else if (isType(it, 'name')) {
+                    out.push({ export: it.value, display: it.value });
+                } else if (isType(it, 'array')) {
+                    if (it.items.length !== 2) {
+                        throw new ParseError('pdf/form/ch/bad-opt-entry',
+                            '/Opt sub-array must have exactly two elements',
+                            { context: { len: it.items.length } });
+                    }
+                    const a = it.items[0], b = it.items[1];
+                    if (!isStringy(a) || !isStringy(b)) {
+                        throw new ParseError('pdf/form/ch/bad-opt-entry',
+                            '/Opt sub-array elements must be strings',
+                            { context: { kinds: [a && a.type, b && b.type] } });
+                    }
+                    out.push({ export: a.value, display: b.value });
+                } else {
+                    throw new ParseError('pdf/form/ch/bad-opt-entry',
+                        '/Opt entries must be strings or [export, display] arrays',
+                        { context: { kind: it && it.type } });
+                }
+            }
+            return out;
+        }
+
+        function toV(v) {
+            if (!v) return null;
+            if (isStringy(v)) return [v.value];
+            if (v.type === 'array') {
+                const out = [];
+                for (const it of v.items) {
+                    if (!isStringy(it)) {
+                        throw new ParseError('pdf/form/ch/bad-v',
+                            '/V array entries must be strings',
+                            { context: { kind: it && it.type } });
+                    }
+                    out.push(it.value);
+                }
+                return out;
+            }
+            return null;
+        }
+
+        function toIndices(v) {
+            if (!v || v.type !== 'array') return [];
+            const out = [];
+            for (const it of v.items) {
+                if (it && (it.type === 'int' || it.type === 'real')) out.push(it.value | 0);
+            }
+            return out;
+        }
+
+        function typeChoiceField(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/form/ch/not-dict',
+                    'choice field must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.FT && (e.FT.type !== 'name' || e.FT.value !== 'Ch')) {
+                throw new ParseError('pdf/form/ch/bad-ft',
+                    '/FT must be /Ch for a choice field',
+                    { context: { actual: e.FT.value } });
+            }
+
+            const flags = intOr(e.Ff, 0);
+            const combo = (flags & F_COMBO) !== 0;
+            const out = {
+                ft: 'Ch',
+                flags,
+                kind: combo ? 'combo' : 'list',
+                editable:         combo && ((flags & F_EDIT)             !== 0),
+                sort:             (flags & F_SORT)               !== 0,
+                multiSelect:      !combo && ((flags & F_MULTI_SELECT)    !== 0),
+                doNotSpellCheck:  (flags & F_DO_NOT_SPELLCHECK)  !== 0,
+                commitOnSelChange:(flags & F_COMMIT_ON_SEL_CHG)  !== 0,
+                opt: toOpt(e.Opt),
+                v:   toV(e.V),
+                dv:  toV(e.DV),
+                i:   toIndices(e.I),
+                ti:  intOr(e.TI, 0),
+                da:  isType(e.DA, 'string') ? e.DA.value : null,
+                q:   intOr(e.Q, 0),
+                t:   isType(e.T, 'string')  ? e.T.value  : null,
+                raw: dict,
+                _extras: {}
+            };
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        return { typeChoiceField };
+    }
+};

package/src/form/fieldTree.js

@@ -0,0 +1,120 @@
+// 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 Form-field tree walker per ISO 32000-2:2020 §12.7.4.
+ *
+ * @module pdf/form/fieldTree
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfFieldTree = {
+    name: 'pdfFieldTree',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parserMod) {
+        const { ParseError } = errors;
+        const isType = (parserMod && parserMod.isType)
+            || ((v, kind) => !!(v && v.type === kind));
+
+        const INHERITABLE = new Set(['FT', 'Ff', 'V', 'DV', 'DA', 'Q', 'MaxLen']);
+
+        function isFieldKidsArray(kids, resolveRef) {
+            if (!kids || kids.type !== 'array' || kids.items.length === 0) return false;
+            const first = kids.items[0];
+            if (!first || first.type !== 'ref') return false;
+            let resolved;
+            try { resolved = resolveRef(first); } catch (_e) { return false; }
+            if (!isType(resolved, 'dict')) return false;
+            return !!resolved.entries.T;
+        }
+
+        function walkFieldTree(rootRefs, resolveRef, opts) {
+            const maxDepth  = (opts && opts.maxDepth)  || 32;
+            const maxFields = (opts && opts.maxFields) || 100000;
+            if (!Array.isArray(rootRefs)) {
+                throw new ParseError('pdf/form/tree/bad-roots',
+                    'rootRefs must be an array',
+                    { context: { 'type': typeof rootRefs } });
+            }
+            const out = [];
+            const visited = new Set();
+            for (const r of rootRefs) walk(r, [], 0);
+            return out;
+
+            function walk(ref, ancestors, depth) {
+                if (depth > maxDepth) {
+                    throw new ParseError('pdf/form/tree/max-depth',
+                        'field tree depth limit exceeded',
+                        { context: { depth, maxDepth } });
+                }
+                if (!ref || typeof ref.num !== 'number') {
+                    throw new ParseError('pdf/form/tree/bad-ref',
+                        'field reference is malformed',
+                        { context: { ref } });
+                }
+                const key = ref.num + ':' + ref.gen;
+                if (visited.has(key)) {
+                    throw new ParseError('pdf/form/tree/cycle',
+                        'cycle detected in field 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/form/tree/not-dict',
+                        'field tree node is not a dict',
+                        { context: { ref } });
+                }
+
+                const kids = node.entries.Kids;
+                const isTerminal = !isFieldKidsArray(kids, resolveRef);
+
+                out.push({
+                    ref: { num: ref.num, gen: ref.gen },
+                    node,
+                    ancestors: ancestors.slice(),
+                    terminal: isTerminal
+                });
+                if (out.length > maxFields) {
+                    throw new ParseError('pdf/form/tree/too-many',
+                        'field count limit exceeded',
+                        { context: { maxFields } });
+                }
+
+                if (isTerminal) return;
+                const nextAncestors = ancestors.concat([node]);
+                for (const k of kids.items) {
+                    if (k.type !== 'ref') {
+                        throw new ParseError('pdf/form/tree/non-ref-kid',
+                            'field /Kids entries must be indirect refs',
+                            { context: { kind: k.type } });
+                    }
+                    walk({ num: k.num, gen: k.gen }, nextAncestors, depth + 1);
+                }
+            }
+        }
+
+        function getInherited(node, ancestors, key) {
+            if (!INHERITABLE.has(key)) return undefined;
+            if (node && node.entries && node.entries[key] !== undefined) {
+                return node.entries[key];
+            }
+            for (let i = ancestors.length - 1; i >= 0; i--) {
+                const a = ancestors[i];
+                if (a && a.entries && a.entries[key] !== undefined) return a.entries[key];
+            }
+            return undefined;
+        }
+
+        return { walkFieldTree, getInherited };
+    }
+};