@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/extra/color-spaces-extended.js

@@ -0,0 +1,196 @@
+// 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 Opt-in: typed PDF color spaces per ISO 32000-2:2020 §8.6.
+ *
+ * Covers: CalGray (§8.6.5.2), CalRGB (§8.6.5.3), Lab (§8.6.5.4),
+ * ICCBased (§8.6.5.5, with Metadata), Indexed (§8.6.6.3),
+ * Separation (§8.6.6.4), DeviceN (§8.6.6.5) with /Attributes,
+ * NChannel (DeviceN subtype, /Process), Pattern (§8.7).
+ *
+ * Color spaces in PDF are typically arrays where the first element is
+ * the family name. We type the array form and the named device families.
+ *
+ * @module pdf/extra/color-spaces-extended
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParserObj } from '../syntax/parser-obj.js';
+
+export const pdfColorSpacesExtended = {
+    name: 'pdfColorSpacesExtended',
+    dependencies: ['pdfErrors', 'pdfParserObj'],
+    deps: [pdfErrors, pdfParserObj],
+    factory(errors, parserObj) {
+        const { ParseError } = errors;
+        const { isType } = parserObj;
+
+        const COLOR_SPACE_FAMILIES = new Set([
+            'CalGray', 'CalRGB', 'Lab', 'ICCBased', 'Indexed',
+            'Separation', 'DeviceN', 'NChannel', 'Pattern',
+            'DeviceGray', 'DeviceRGB', 'DeviceCMYK'
+        ]);
+
+        function typeColorSpace(value) {
+            if (isType(value, 'name')) {
+                if (!COLOR_SPACE_FAMILIES.has(value.value)) {
+                    return { family: 'NamedResource', name: value.value, raw: value };
+                }
+                return { family: value.value, raw: value };
+            }
+            if (!isType(value, 'array') || value.items.length < 1) {
+                throw new ParseError('pdf/extra/colorspace/bad-shape',
+                    'color space must be name or non-empty array',
+                    { context: { type: value && value.type } });
+            }
+            const head = value.items[0];
+            if (!isType(head, 'name')) {
+                throw new ParseError('pdf/extra/colorspace/bad-family',
+                    'color space array must start with a name');
+            }
+            const family = head.value;
+            if (!COLOR_SPACE_FAMILIES.has(family)) {
+                throw new ParseError('pdf/extra/colorspace/unknown',
+                    'unknown color-space family',
+                    { context: { family } });
+            }
+            switch (family) {
+                case 'CalGray':    return { family, ...readCalGray(value), raw: value };
+                case 'CalRGB':     return { family, ...readCalRGB(value), raw: value };
+                case 'Lab':        return { family, ...readLab(value), raw: value };
+                case 'ICCBased':   return { family, ...readICCBased(value), raw: value };
+                case 'Indexed':    return { family, ...readIndexed(value), raw: value };
+                case 'Separation': return { family, ...readSeparation(value), raw: value };
+                case 'DeviceN':    return { family, ...readDeviceN(value), raw: value };
+                case 'NChannel':   return { family, ...readDeviceN(value), nChannel: true, raw: value };
+                case 'Pattern':    return { family, ...readPattern(value), raw: value };
+                default:           return { family, raw: value };
+            }
+        }
+
+        function readCalDict(d) {
+            if (!isType(d, 'dict')) {
+                throw new ParseError('pdf/extra/colorspace/cal-no-dict',
+                    'Cal* parameters dict missing');
+            }
+            return {
+                whitePoint: numArr(d.entries.WhitePoint, 3),
+                blackPoint: numArr(d.entries.BlackPoint, 3),
+                gamma:      d.entries.Gamma   || null,
+                matrix:     numArr(d.entries.Matrix, 9)
+            };
+        }
+
+        function readCalGray(arr) {
+            if (arr.items.length < 2) {
+                throw new ParseError('pdf/extra/colorspace/cal-truncated', 'CalGray needs dict');
+            }
+            return { params: readCalDict(arr.items[1]) };
+        }
+
+        function readCalRGB(arr) {
+            if (arr.items.length < 2) {
+                throw new ParseError('pdf/extra/colorspace/cal-truncated', 'CalRGB needs dict');
+            }
+            return { params: readCalDict(arr.items[1]) };
+        }
+
+        function readLab(arr) {
+            if (arr.items.length < 2 || !isType(arr.items[1], 'dict')) {
+                throw new ParseError('pdf/extra/colorspace/lab-truncated', 'Lab needs dict');
+            }
+            const d = arr.items[1].entries;
+            return {
+                whitePoint: numArr(d.WhitePoint, 3),
+                blackPoint: numArr(d.BlackPoint, 3),
+                range:      numArr(d.Range, 4)
+            };
+        }
+
+        function readICCBased(arr) {
+            if (arr.items.length < 2 || !isType(arr.items[1], 'stream')) {
+                throw new ParseError('pdf/extra/colorspace/icc-no-stream',
+                    'ICCBased needs a stream');
+            }
+            const s = arr.items[1];
+            const e = s.dict.entries;
+            return {
+                n:        (e.N && (e.N.type === 'int' || e.N.type === 'real')) ? (e.N.value | 0) : null,
+                alt:      e.Alternate || null,
+                range:    numArr(e.Range, null),
+                metadata: e.Metadata  || null,
+                profile:  s
+            };
+        }
+
+        function readIndexed(arr) {
+            if (arr.items.length < 4) {
+                throw new ParseError('pdf/extra/colorspace/indexed-truncated',
+                    'Indexed needs [base hival lookup]');
+            }
+            const hival = arr.items[2];
+            if (!hival || (hival.type !== 'int' && hival.type !== 'real')) {
+                throw new ParseError('pdf/extra/colorspace/indexed-bad-hival',
+                    'Indexed hival must be numeric');
+            }
+            return {
+                base:    arr.items[1],
+                hival:   hival.value | 0,
+                lookup:  arr.items[3]
+            };
+        }
+
+        function readSeparation(arr) {
+            if (arr.items.length < 4) {
+                throw new ParseError('pdf/extra/colorspace/sep-truncated',
+                    'Separation needs [name alternate tintTransform]');
+            }
+            return {
+                colorant:      isType(arr.items[1], 'name') ? arr.items[1].value : null,
+                alternate:     arr.items[2],
+                tintTransform: arr.items[3]
+            };
+        }
+
+        function readDeviceN(arr) {
+            if (arr.items.length < 4) {
+                throw new ParseError('pdf/extra/colorspace/devn-truncated',
+                    'DeviceN needs [names alternate tintTransform attributes?]');
+            }
+            let names = null;
+            if (isType(arr.items[1], 'array')) {
+                names = arr.items[1].items.map(it => isType(it, 'name') ? it.value : null);
+            }
+            return {
+                names,
+                alternate:     arr.items[2],
+                tintTransform: arr.items[3],
+                attributes:    arr.items[4] || null
+            };
+        }
+
+        function readPattern(arr) {
+            return { base: arr.items[1] || null };
+        }
+
+        function numArr(v, expectedLen) {
+            if (!isType(v, 'array')) return null;
+            const out = [];
+            for (const it of v.items) {
+                if (!it || (it.type !== 'int' && it.type !== 'real')) return null;
+                out.push(it.value);
+            }
+            if (expectedLen != null && out.length !== expectedLen) return null;
+            return out;
+        }
+
+        return { typeColorSpace, COLOR_SPACE_FAMILIES };
+    }
+};
+

package/src/extra/content-ops-extended.js

@@ -0,0 +1,153 @@
+// 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 Opt-in: extended graphics-state operators and full
+ * ExtGState typing.
+ *
+ * Per ISO 32000-2:2020 §8.4.5 (graphics-state operators) and §8.4.5
+ * Table 57 (ExtGState parameter dictionary).
+ *
+ * Rare gstate-extra ops covered: `d0`, `d1` (Type 3 font char-width
+ * shape operators, §9.6.4) ; `gs` is L0 already, but this module also
+ * exposes the catalog of every ExtGState key.
+ *
+ * @module pdf/extra/content-ops-extended
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParserObj } from '../syntax/parser-obj.js';
+
+export const pdfContentOpsExtended = {
+    name: 'pdfContentOpsExtended',
+    dependencies: ['pdfErrors', 'pdfParserObj'],
+    deps: [pdfErrors, pdfParserObj],
+    factory(errors, parserObj) {
+        const { ParseError } = errors;
+        const { isType } = parserObj;
+
+        const EXT_GSTATE_KEYS = Object.freeze({
+            Type:    { kind: 'name',  doc: 'must be /ExtGState' },
+            LW:      { kind: 'num',   doc: 'line width' },
+            LC:      { kind: 'int',   doc: 'line cap style 0|1|2' },
+            LJ:      { kind: 'int',   doc: 'line join style 0|1|2' },
+            ML:      { kind: 'num',   doc: 'miter limit' },
+            D:       { kind: 'array', doc: '[ dashArray dashPhase ]' },
+            RI:      { kind: 'name',  doc: 'rendering intent' },
+            OP:      { kind: 'bool',  doc: 'stroke overprint' },
+            op:      { kind: 'bool',  doc: 'non-stroke overprint' },
+            OPM:     { kind: 'int',   doc: 'overprint mode 0|1' },
+            Font:    { kind: 'array', doc: '[ font size ]' },
+            BG:      { kind: 'stream-or-func', doc: 'black-generation function' },
+            BG2:     { kind: 'stream-or-name',  doc: 'BG or /Default' },
+            UCR:     { kind: 'stream-or-func', doc: 'undercolor-removal function' },
+            UCR2:    { kind: 'stream-or-name',  doc: 'UCR or /Default' },
+            TR:      { kind: 'stream-or-func-or-array', doc: 'transfer function' },
+            TR2:    { kind: 'stream-or-func-or-array-or-name', doc: 'transfer function or /Default' },
+            HT:      { kind: 'dict-or-stream-or-name', doc: 'halftone' },
+            FL:      { kind: 'num',   doc: 'flatness tolerance' },
+            SM:      { kind: 'num',   doc: 'smoothness tolerance' },
+            SA:      { kind: 'bool',  doc: 'stroke adjustment' },
+            BM:      { kind: 'name-or-array', doc: 'blend mode' },
+            SMask:   { kind: 'dict-or-name',  doc: 'soft mask' },
+            CA:      { kind: 'num',   doc: 'stroke alpha [0,1]' },
+            ca:      { kind: 'num',   doc: 'non-stroke alpha [0,1]' },
+            AIS:     { kind: 'bool',  doc: 'alpha is shape' },
+            TK:      { kind: 'bool',  doc: 'text knockout' },
+            UseBlackPtComp: { kind: 'name', doc: 'ON|OFF|Default' },
+            HTO:     { kind: 'array', doc: 'halftone origin [tx ty]' }
+        });
+
+        const NUM = (v) => v && (v.type === 'int' || v.type === 'real');
+
+        function typeExtGState(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/ext-gstate/not-dict',
+                    'ExtGState must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'ExtGState')) {
+                throw new ParseError('pdf/extra/ext-gstate/bad-type',
+                    '/Type entry must be /ExtGState',
+                    { context: { actual: e.Type.value } });
+            }
+            const out = {
+                type:            e.Type ? e.Type.value : null,
+                lw:              NUM(e.LW)  ? e.LW.value  : null,
+                lc:              NUM(e.LC)  ? (e.LC.value | 0) : null,
+                lj:              NUM(e.LJ)  ? (e.LJ.value | 0) : null,
+                ml:              NUM(e.ML)  ? e.ML.value  : null,
+                d:               isType(e.D, 'array') ? e.D : null,
+                ri:              isType(e.RI, 'name') ? e.RI.value : null,
+                op:              isType(e.OP, 'bool') ? e.OP.value : null,
+                opNs:            isType(e.op, 'bool') ? e.op.value : null,
+                opm:             NUM(e.OPM) ? (e.OPM.value | 0) : null,
+                font:            isType(e.Font, 'array') ? e.Font : null,
+                bg:              e.BG || null,
+                bg2:             e.BG2 || null,
+                ucr:             e.UCR || null,
+                ucr2:            e.UCR2 || null,
+                tr:              e.TR || null,
+                tr2:             e.TR2 || null,
+                ht:              e.HT || null,
+                fl:              NUM(e.FL) ? e.FL.value : null,
+                sm:              NUM(e.SM) ? e.SM.value : null,
+                sa:              isType(e.SA, 'bool') ? e.SA.value : null,
+                bm:              e.BM || null,
+                sMask:           e.SMask || null,
+                ca:              NUM(e.CA) ? e.CA.value : null,
+                caNs:            NUM(e.ca) ? e.ca.value : null,
+                ais:             isType(e.AIS, 'bool') ? e.AIS.value : null,
+                tk:              isType(e.TK, 'bool')  ? e.TK.value  : null,
+                useBlackPtComp:  isType(e.UseBlackPtComp, 'name') ? e.UseBlackPtComp.value : null,
+                hto:             isType(e.HTO, 'array') ? e.HTO : null,
+                raw:             dict,
+                _extras:         {}
+            };
+            for (const k of Object.keys(e)) {
+                if (!(k in EXT_GSTATE_KEYS)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function decodeType3CharOp(op, operands) {
+            if (op !== 'd0' && op !== 'd1') {
+                throw new ParseError('pdf/extra/content-ops/unknown',
+                    'expected d0 or d1 operator',
+                    { context: { op } });
+            }
+            if (op === 'd0') {
+                if (!operands || operands.length !== 2) {
+                    throw new ParseError('pdf/extra/content-ops/bad-d0',
+                        'd0 requires 2 operands wx wy',
+                        { context: { count: operands && operands.length } });
+                }
+                return { kind: 'd0', wx: +operands[0], wy: +operands[1] };
+            }
+            if (!operands || operands.length !== 6) {
+                throw new ParseError('pdf/extra/content-ops/bad-d1',
+                    'd1 requires 6 operands wx wy llx lly urx ury',
+                    { context: { count: operands && operands.length } });
+            }
+            return {
+                kind: 'd1',
+                wx:   +operands[0],
+                wy:   +operands[1],
+                bbox: [ +operands[2], +operands[3], +operands[4], +operands[5] ]
+            };
+        }
+
+        return {
+            typeExtGState,
+            decodeType3CharOp,
+            EXT_GSTATE_KEYS
+        };
+    }
+};
+

package/src/extra/document-parts.js

@@ -0,0 +1,149 @@
+// 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 Opt-in: Document Parts (ISO/TS 32004) typing.
+ *
+ * TS 32004 introduces a hierarchical "Document Parts" tree rooted in the
+ * Catalog under `/DPartRoot`. Each node is a `/Type /DPart` dict with:
+ *   /Parent        — parent DPart (omitted on root)
+ *   /DParts        — array of child DPart refs or page refs
+ *   /Start         — first page index in this subtree (computed)
+ *   /End           — last page index in this subtree
+ *   /DPM           — Document Part Metadata dict
+ *   /NodeNameTree  — name-tree mapping local names → DPart refs
+ *
+ * @module pdf/extra/document-parts
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfDocumentParts = {
+    name: 'pdfDocumentParts',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const DPART_KNOWN = new Set([
+            'Type', 'Parent', 'DParts', 'Start', 'End', 'DPM', 'NodeNameTree'
+        ]);
+        const ROOT_KNOWN = new Set([
+            'Type', 'DPartRootNode', 'RecordLevel', 'NodeNameList'
+        ]);
+
+        function typeDPartRoot(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/dparts/root/not-dict',
+                    '/DPartRoot must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'DPartRoot')) {
+                throw new ParseError('pdf/extra/dparts/root/bad-type',
+                    '/Type must be /DPartRoot when present',
+                    { context: { actual: e.Type.value } });
+            }
+            if (!e.DPartRootNode) {
+                throw new ParseError('pdf/extra/dparts/root/missing-node',
+                    '/DPartRoot requires a /DPartRootNode entry');
+            }
+            const out = {
+                rootNode:    e.DPartRootNode,
+                recordLevel: isType(e.RecordLevel, 'int') ? e.RecordLevel.value : null,
+                nodeNameList: toNameList(e.NodeNameList),
+                raw: dict,
+                _extras: {}
+            };
+            for (const k of Object.keys(e)) {
+                if (!ROOT_KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function typeDPart(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/dparts/node/not-dict',
+                    '/DPart must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'DPart')) {
+                throw new ParseError('pdf/extra/dparts/node/bad-type',
+                    '/Type must be /DPart when present',
+                    { context: { actual: e.Type.value } });
+            }
+            const out = {
+                parent:       e.Parent || null,
+                dParts:       toRefArray(e.DParts),
+                start:        isType(e.Start, 'int') ? e.Start.value : null,
+                end:          isType(e.End,   'int') ? e.End.value   : null,
+                dpm:          isType(e.DPM, 'dict') ? typeDPM(e.DPM) : null,
+                nodeNameTree: e.NodeNameTree || null,
+                raw:          dict,
+                _extras:      {}
+            };
+            if (e.DPM && !isType(e.DPM, 'dict')) {
+                throw new ParseError('pdf/extra/dparts/node/bad-dpm',
+                    '/DPM must be a dictionary',
+                    { context: { type: e.DPM.type } });
+            }
+            for (const k of Object.keys(e)) {
+                if (!DPART_KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function typeDPM(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/dparts/dpm/not-dict',
+                    '/DPM must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            const out = { entries: {}, raw: dict };
+            for (const k of Object.keys(e)) out.entries[k] = e[k];
+            return out;
+        }
+
+        function walkDParts(root, visit) {
+            if (!root) return;
+            if (typeof visit !== 'function') {
+                throw new ParseError('pdf/extra/dparts/walk/bad-visit',
+                    'walkDParts requires a visit callback');
+            }
+            visit(root);
+            if (!root.dParts) return;
+            for (const child of root.dParts) {
+                if (isType(child, 'dict')) walkDParts(typeDPart(child), visit);
+            }
+        }
+
+        function toRefArray(v) {
+            if (!v) return null;
+            if (v.type !== 'array') return null;
+            return v.items.slice();
+        }
+
+        function toNameList(v) {
+            if (!v) return null;
+            if (v.type !== 'array') return null;
+            const out = [];
+            for (const it of v.items) {
+                if (isType(it, 'name')) out.push(it.value);
+                else out.push(it);
+            }
+            return out;
+        }
+
+        return { typeDPartRoot, typeDPart, typeDPM, walkDParts };
+    }
+};
+