@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/form/signature.js

@@ -0,0 +1,100 @@
+// 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 Signature field typing per ISO 32000-2:2020 §12.7.5.5.
+ *
+ * @module pdf/form/signature
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfSignatureField = {
+    name: 'pdfSignatureField',
+    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([
+            'Type', 'FT', 'Parent', 'Kids', 'T', 'TU', 'TM', 'Ff', 'V', 'DV',
+            'AA', 'DA', 'Q', 'Lock', 'SV', 'AP'
+        ]);
+
+        function intOr(v, dflt) {
+            if (!v) return dflt;
+            if (v.type !== 'int' && v.type !== 'real') return dflt;
+            return v.value | 0;
+        }
+
+        function typeSignatureField(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/form/sig/not-dict',
+                    'signature field must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.FT && (e.FT.type !== 'name' || e.FT.value !== 'Sig')) {
+                throw new ParseError('pdf/form/sig/bad-ft',
+                    '/FT must be /Sig for a signature field',
+                    { context: { actual: e.FT.value } });
+            }
+
+            let v = null;
+            if (e.V) {
+                if (e.V.type === 'ref' || e.V.type === 'dict') v = e.V;
+                else {
+                    throw new ParseError('pdf/form/sig/bad-v',
+                        '/V must be a dict or indirect reference',
+                        { context: { kind: e.V.type } });
+                }
+            }
+
+            let lock = null;
+            if (e.Lock) {
+                if (e.Lock.type === 'ref' || e.Lock.type === 'dict') lock = e.Lock;
+                else {
+                    throw new ParseError('pdf/form/sig/bad-lock',
+                        '/Lock must be a dict or indirect reference',
+                        { context: { kind: e.Lock.type } });
+                }
+            }
+
+            let sv = null;
+            if (e.SV) {
+                if (e.SV.type === 'ref' || e.SV.type === 'dict') sv = e.SV;
+                else {
+                    throw new ParseError('pdf/form/sig/bad-sv',
+                        '/SV must be a dict or indirect reference',
+                        { context: { kind: e.SV.type } });
+                }
+            }
+
+            const out = {
+                ft: 'Sig',
+                flags:  intOr(e.Ff, 0),
+                v,
+                lock,
+                sv,
+                t:      isType(e.T, 'string') ? e.T.value : null,
+                signed: v !== null,
+                raw:    dict,
+                _extras: {}
+            };
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        return { typeSignatureField };
+    }
+};

package/src/form/text.js

@@ -0,0 +1,101 @@
+// 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 Text field typing per ISO 32000-2:2020 §12.7.5.3.
+ *
+ * @module pdf/form/text
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfTextField = {
+    name: 'pdfTextField',
+    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_MULTILINE         = 1 << 12;
+        const F_PASSWORD          = 1 << 13;
+        const F_FILE_SELECT       = 1 << 20;
+        const F_DO_NOT_SPELLCHECK = 1 << 22;
+        const F_DO_NOT_SCROLL     = 1 << 23;
+        const F_COMB              = 1 << 24;
+        const F_RICH_TEXT         = 1 << 25;
+
+        const KNOWN = new Set([
+            'Type', 'FT', 'Parent', 'Kids', 'T', 'TU', 'TM', 'Ff', 'V', 'DV',
+            'AA', 'DA', 'Q', 'MaxLen', 'AP', 'RV'
+        ]);
+
+        function intOr(v, dflt) {
+            if (!v) return dflt;
+            if (v.type !== 'int' && v.type !== 'real') return dflt;
+            return v.value | 0;
+        }
+
+        function toTextValue(v) {
+            if (!v) return null;
+            if (v.type === 'string') return v.value;
+            if (v.type === 'stream' && v.raw)  return v.raw;
+            return null;
+        }
+
+        function typeTextField(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/form/tx/not-dict',
+                    'text field must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.FT && (e.FT.type !== 'name' || e.FT.value !== 'Tx')) {
+                throw new ParseError('pdf/form/tx/bad-ft',
+                    '/FT must be /Tx for a text field',
+                    { context: { actual: e.FT.value } });
+            }
+
+            const flags = intOr(e.Ff, 0);
+            const out = {
+                ft: 'Tx',
+                flags,
+                multiline:        (flags & F_MULTILINE)         !== 0,
+                password:         (flags & F_PASSWORD)          !== 0,
+                fileSelect:       (flags & F_FILE_SELECT)       !== 0,
+                doNotSpellCheck:  (flags & F_DO_NOT_SPELLCHECK) !== 0,
+                doNotScroll:      (flags & F_DO_NOT_SCROLL)     !== 0,
+                comb:             (flags & F_COMB)              !== 0,
+                richText:         (flags & F_RICH_TEXT)         !== 0,
+                v:      toTextValue(e.V),
+                dv:     toTextValue(e.DV),
+                maxLen: e.MaxLen ? intOr(e.MaxLen, null) : null,
+                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: {}
+            };
+
+            if (out.comb && out.maxLen == null) {
+                throw new ParseError('pdf/form/tx/comb-without-maxlen',
+                    'Comb flag set but /MaxLen is missing',
+                    { context: { flags } });
+            }
+
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        return { typeTextField };
+    }
+};

package/src/linearization/linearization.js

@@ -0,0 +1,107 @@
+// 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 Linearization Parameter Dictionary typing per ISO
+ * 32000-2:2020 Annex F.2.
+ *
+ * If the first indirect object in a PDF is a dictionary whose first
+ * entry is `/Linearized`, the file is "fast web view" optimized. The
+ * dictionary contains:
+ *   /Linearized  — version number (required, usually 1.0)
+ *   /L           — file length (required)
+ *   /H           — hint stream offset/length array (required)
+ *   /O           — object number of the first page (required)
+ *   /E           — end of first page (required)
+ *   /N           — number of pages (required)
+ *   /T           — offset of first entry in main xref table (required)
+ *   /P           — page number of the first page (optional, default 0)
+ *
+ * Read-only: `pdf.write` does not linearize (no writer module references this module), and
+ * `extra/linearization-write` only builds the `/Linearized` dictionary and a
+ * zero-length hint-stream placeholder.
+ *
+ * @module pdf/linearization/linearization
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfLinearization = {
+    name: 'pdfLinearization',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const KNOWN = new Set(['Linearized', 'L', 'H', 'O', 'E', 'N', 'T', 'P']);
+
+        function int(v, key) {
+            if (!v || (v.type !== 'int' && v.type !== 'real')) {
+                throw new ParseError('pdf/linearization/missing-' + key.toLowerCase(),
+                    '/' + key + ' must be a number',
+                    { context: { type: v && v.type } });
+            }
+            return v.value | 0;
+        }
+        function num(v, key) {
+            if (!v || (v.type !== 'int' && v.type !== 'real')) {
+                throw new ParseError('pdf/linearization/missing-' + key.toLowerCase(),
+                    '/' + key + ' must be a number',
+                    { context: { type: v && v.type } });
+            }
+            return +v.value;
+        }
+
+        function typeLinearizationDict(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/linearization/not-dict',
+                    'Linearization params must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (!e.Linearized) {
+                throw new ParseError('pdf/linearization/not-linearized',
+                    'dictionary has no /Linearized entry');
+            }
+            const out = { raw: dict, _extras: {} };
+            out.version = num(e.Linearized, 'Linearized');
+            out.length  = int(e.L, 'L');
+            out.firstPageObject = int(e.O, 'O');
+            out.endOfFirstPage  = int(e.E, 'E');
+            out.numberOfPages   = int(e.N, 'N');
+            out.mainXrefOffset  = int(e.T, 'T');
+
+            if (!e.H || e.H.type !== 'array') {
+                throw new ParseError('pdf/linearization/missing-h',
+                    '/H must be an array',
+                    { context: { type: e.H && e.H.type } });
+            }
+            out.hintOffsets = e.H.items
+                .filter((x) => x.type === 'int' || x.type === 'real')
+                .map((x) => x.value);
+            if (out.hintOffsets.length < 2) {
+                throw new ParseError('pdf/linearization/bad-h',
+                    '/H must hold at least two numbers',
+                    { context: { length: out.hintOffsets.length } });
+            }
+
+            if (e.P !== undefined) {
+                out.firstPageNumber = int(e.P, 'P');
+            }
+
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        return { typeLinearizationDict };
+    }
+};