@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/extra/embedded-files-portfolio.js

@@ -0,0 +1,234 @@
+// 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 PDF Portfolio (/Collection) typing.
+ *
+ * Augments the L1 collection typing with deeper inspection of the
+ * sub-dictionaries: /Schema field definitions, /Sort criteria,
+ * /Navigator extension, the initial /D entry, the /View mode
+ * ('D'|'T'|'H'|'C'), and the /CI (Collection Item) custom icon dict.
+ *
+ * @module pdf/extra/embedded-files-portfolio
+ */
+
+import { pdfErrors } from '../errors.js';
+
+export const pdfEmbeddedFilesPortfolio = {
+    name: 'pdfEmbeddedFilesPortfolio',
+    dependencies: ['pdfErrors'],
+    deps: [pdfErrors],
+
+    factory(errors) {
+        const { ParseError } = errors;
+        const VIEW_MODES = new Set(['D', 'T', 'H', 'C']);
+        const SCHEMA_SUBTYPES = new Set([
+            'S', 'D', 'N', 'F', 'Desc', 'ModDate', 'CreationDate', 'Size'
+        ]);
+        const KNOWN_COLLECTION = new Set([
+            'Type', 'Schema', 'D', 'View', 'Sort', 'Navigator',
+            'Folders', 'Colors', 'Split'
+        ]);
+
+        function isDict(v) { return v && v.type === 'dict'; }
+        function isName(v) { return v && v.type === 'name'; }
+        function isStr(v) { return v && v.type === 'string'; }
+        function isArr(v) { return v && v.type === 'array'; }
+        function isBool(v) { return v && v.type === 'bool'; }
+        function isInt(v) { return v && v.type === 'int'; }
+
+        function typeSchemaField(name, fieldDict) {
+            if (!isDict(fieldDict)) {
+                throw new ParseError('pdf/portfolio/bad-schema-field',
+                    '/Schema field must be a dictionary',
+                    { context: { field: name, type: fieldDict && fieldDict.type } });
+            }
+            const e = fieldDict.entries;
+            const out = { name, raw: fieldDict, _extras: {} };
+            if (e.Subtype) {
+                if (!isName(e.Subtype) || !SCHEMA_SUBTYPES.has(e.Subtype.value)) {
+                    throw new ParseError('pdf/portfolio/bad-schema-subtype',
+                        '/Subtype on /Schema field must be one of S,D,N,F,Desc,ModDate,CreationDate,Size',
+                        { context: { field: name, actual: e.Subtype.value } });
+                }
+                out.subtype = e.Subtype.value;
+            }
+            if (e.N) {
+                if (!isStr(e.N)) {
+                    throw new ParseError('pdf/portfolio/bad-schema-n',
+                        '/N must be a string', { context: { field: name } });
+                }
+                out.displayName = e.N.value;
+            }
+            if (e.O != null) {
+                if (!isInt(e.O)) {
+                    throw new ParseError('pdf/portfolio/bad-schema-o',
+                        '/O must be an integer', { context: { field: name } });
+                }
+                out.order = e.O.value;
+            }
+            if (e.V != null) {
+                if (!isBool(e.V)) {
+                    throw new ParseError('pdf/portfolio/bad-schema-v',
+                        '/V must be boolean', { context: { field: name } });
+                }
+                out.visible = e.V.value;
+            }
+            if (e.E != null) {
+                if (!isBool(e.E)) {
+                    throw new ParseError('pdf/portfolio/bad-schema-e',
+                        '/E must be boolean', { context: { field: name } });
+                }
+                out.editable = e.E.value;
+            }
+            const KNOWN = new Set(['Subtype', 'N', 'O', 'V', 'E']);
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function typeSchema(schemaDict) {
+            if (!isDict(schemaDict)) {
+                throw new ParseError('pdf/portfolio/bad-schema',
+                    '/Schema must be a dictionary',
+                    { context: { type: schemaDict && schemaDict.type } });
+            }
+            const fields = {};
+            for (const [k, v] of Object.entries(schemaDict.entries)) {
+                fields[k] = typeSchemaField(k, v);
+            }
+            return { fields, raw: schemaDict };
+        }
+
+        function typeSort(sortDict) {
+            if (!isDict(sortDict)) {
+                throw new ParseError('pdf/portfolio/bad-sort',
+                    '/Sort must be a dictionary');
+            }
+            const e = sortDict.entries;
+            const out = { raw: sortDict, _extras: {} };
+            if (e.S) {
+                if (isName(e.S)) out.keys = [e.S.value];
+                else if (isArr(e.S)) {
+                    const ks = [];
+                    for (const it of e.S.items) {
+                        if (!isName(it)) {
+                            throw new ParseError('pdf/portfolio/bad-sort-s-item',
+                                '/Sort /S array items must be names');
+                        }
+                        ks.push(it.value);
+                    }
+                    out.keys = ks;
+                } else {
+                    throw new ParseError('pdf/portfolio/bad-sort-s',
+                        '/Sort /S must be a name or array of names');
+                }
+            }
+            if (e.A != null) {
+                if (isBool(e.A)) out.ascending = [e.A.value];
+                else if (isArr(e.A)) {
+                    const as = [];
+                    for (const it of e.A.items) {
+                        if (!isBool(it)) {
+                            throw new ParseError('pdf/portfolio/bad-sort-a-item',
+                                '/Sort /A array items must be booleans');
+                        }
+                        as.push(it.value);
+                    }
+                    out.ascending = as;
+                } else {
+                    throw new ParseError('pdf/portfolio/bad-sort-a',
+                        '/Sort /A must be a bool or array of bools');
+                }
+            }
+            for (const k of Object.keys(e)) {
+                if (k !== 'S' && k !== 'A') out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function typeNavigator(nav) {
+            if (nav && nav.type === 'ref') return { ref: { num: nav.num, gen: nav.gen }, raw: nav };
+            if (!isDict(nav)) {
+                throw new ParseError('pdf/portfolio/bad-navigator',
+                    '/Navigator must be a dict or ref');
+            }
+            return { raw: nav, entries: nav.entries };
+        }
+
+        function typeCustomIcon(ci) {
+            if (!isDict(ci) && !(ci && ci.type === 'stream')) {
+                throw new ParseError('pdf/portfolio/bad-ci',
+                    '/CI custom icon must be dict or stream',
+                    { context: { type: ci && ci.type } });
+            }
+            return { raw: ci };
+        }
+
+        function typePortfolio(collectionDict) {
+            if (!isDict(collectionDict)) {
+                throw new ParseError('pdf/portfolio/not-dict',
+                    'Collection must be a dictionary',
+                    { context: { type: collectionDict && collectionDict.type } });
+            }
+            const e = collectionDict.entries;
+            if (e.Type && (!isName(e.Type) || e.Type.value !== 'Collection')) {
+                throw new ParseError('pdf/portfolio/bad-type',
+                    '/Type must be /Collection',
+                    { context: { actual: e.Type && e.Type.value } });
+            }
+            const out = { raw: collectionDict, _extras: {} };
+            if (e.Schema)    out.schema    = typeSchema(e.Schema);
+            if (e.D) {
+                if (!isStr(e.D)) {
+                    throw new ParseError('pdf/portfolio/bad-d',
+                        '/D must be a string');
+                }
+                out.initialDoc = e.D.value;
+            }
+            if (e.View) {
+                if (!isName(e.View) || !VIEW_MODES.has(e.View.value)) {
+                    throw new ParseError('pdf/portfolio/bad-view',
+                        '/View must be one of D, T, H, C',
+                        { context: { actual: e.View && e.View.value } });
+                }
+                out.view = e.View.value;
+            }
+            if (e.Sort)      out.sort      = typeSort(e.Sort);
+            if (e.Navigator) out.navigator = typeNavigator(e.Navigator);
+            for (const k of Object.keys(e)) {
+                if (!KNOWN_COLLECTION.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function typeCollectionItem(ciDict) {
+            if (!isDict(ciDict)) {
+                throw new ParseError('pdf/portfolio/ci-not-dict',
+                    '/CI item must be a dict');
+            }
+            const out = { raw: ciDict, fields: {}, _extras: {} };
+            for (const [k, v] of Object.entries(ciDict.entries)) {
+                if (k === 'Type') continue;
+                if (k === 'CI') out.customIcon = typeCustomIcon(v);
+                else out.fields[k] = v;
+            }
+            return out;
+        }
+
+        return {
+            typePortfolio,
+            typeSchema,
+            typeSchemaField,
+            typeSort,
+            typeNavigator,
+            typeCustomIcon,
+            typeCollectionItem,
+            VIEW_MODES,
+            SCHEMA_SUBTYPES
+        };
+    }
+};

package/src/extra/font-cid-typed.js

@@ -0,0 +1,185 @@
+// 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 CIDFont per ISO 32000-2:2020 §9.7.4
+ * (CIDFontType0/CIDFontType2), `/CIDSystemInfo` §9.7.3, `/CIDToGIDMap`
+ * §9.7.4.3, glyph-metrics arrays `/W /W2 /DW /DW2` §9.7.4.3, and the
+ * predefined CMap catalog §9.7.5.2.
+ *
+ * @module pdf/extra/font-cid-typed
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParserObj } from '../syntax/parser-obj.js';
+
+export const pdfFontCidTyped = {
+    name: 'pdfFontCidTyped',
+    dependencies: ['pdfErrors', 'pdfParserObj'],
+    deps: [pdfErrors, pdfParserObj],
+    factory(errors, parserObj) {
+        const { ParseError } = errors;
+        const { isType } = parserObj;
+
+        const SUBTYPES = new Set(['CIDFontType0', 'CIDFontType2']);
+
+        const PREDEFINED_CMAPS = Object.freeze({
+            'Adobe-GB1': Object.freeze([
+                'GB-EUC-H', 'GB-EUC-V', 'GBpc-EUC-H', 'GBpc-EUC-V',
+                'GBK-EUC-H', 'GBK-EUC-V', 'GBKp-EUC-H', 'GBKp-EUC-V',
+                'GBK2K-H', 'GBK2K-V', 'UniGB-UCS2-H', 'UniGB-UCS2-V',
+                'UniGB-UTF16-H', 'UniGB-UTF16-V'
+            ]),
+            'Adobe-CNS1': Object.freeze([
+                'B5pc-H', 'B5pc-V', 'HKscs-B5-H', 'HKscs-B5-V',
+                'ETen-B5-H', 'ETen-B5-V', 'ETenms-B5-H', 'ETenms-B5-V',
+                'CNS-EUC-H', 'CNS-EUC-V', 'UniCNS-UCS2-H', 'UniCNS-UCS2-V',
+                'UniCNS-UTF16-H', 'UniCNS-UTF16-V'
+            ]),
+            'Adobe-Japan1': Object.freeze([
+                '83pv-RKSJ-H', '90ms-RKSJ-H', '90ms-RKSJ-V', '90msp-RKSJ-H',
+                '90msp-RKSJ-V', '90pv-RKSJ-H', 'Add-RKSJ-H', 'Add-RKSJ-V',
+                'EUC-H', 'EUC-V', 'Ext-RKSJ-H', 'Ext-RKSJ-V', 'H', 'V',
+                'UniJIS-UCS2-H', 'UniJIS-UCS2-V', 'UniJIS-UCS2-HW-H',
+                'UniJIS-UCS2-HW-V', 'UniJIS-UTF16-H', 'UniJIS-UTF16-V'
+            ]),
+            'Adobe-Korea1': Object.freeze([
+                'KSC-EUC-H', 'KSC-EUC-V', 'KSCms-UHC-H', 'KSCms-UHC-V',
+                'KSCms-UHC-HW-H', 'KSCms-UHC-HW-V', 'KSCpc-EUC-H',
+                'UniKS-UCS2-H', 'UniKS-UCS2-V', 'UniKS-UTF16-H', 'UniKS-UTF16-V'
+            ]),
+            'Identity': Object.freeze(['Identity-H', 'Identity-V'])
+        });
+
+        const KNOWN = new Set([
+            'Type', 'Subtype', 'BaseFont', 'CIDSystemInfo', 'FontDescriptor',
+            'DW', 'W', 'DW2', 'W2', 'CIDToGIDMap'
+        ]);
+
+        function typeCIDFont(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/cid-font/not-dict',
+                    'CIDFont must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'Font')) {
+                throw new ParseError('pdf/extra/cid-font/bad-type',
+                    '/Type entry must be /Font',
+                    { context: { actual: e.Type.value } });
+            }
+            if (!isType(e.Subtype, 'name') || !SUBTYPES.has(e.Subtype.value)) {
+                throw new ParseError('pdf/extra/cid-font/bad-subtype',
+                    '/Subtype must be CIDFontType0 or CIDFontType2',
+                    { context: { actual: e.Subtype && e.Subtype.value } });
+            }
+            if (!isType(e.CIDSystemInfo, 'dict') && !(e.CIDSystemInfo && e.CIDSystemInfo.type === 'ref')) {
+                throw new ParseError('pdf/extra/cid-font/missing-csi',
+                    '/CIDSystemInfo is required (dict or ref)',
+                    { context: { type: e.CIDSystemInfo && e.CIDSystemInfo.type } });
+            }
+            const out = {
+                subtype:         e.Subtype.value,
+                baseFont:        isType(e.BaseFont, 'name') ? e.BaseFont.value : null,
+                cidSystemInfo:   isType(e.CIDSystemInfo, 'dict') ? typeCIDSystemInfo(e.CIDSystemInfo) : e.CIDSystemInfo,
+                fontDescriptor:  e.FontDescriptor || null,
+                dw:              numVal(e.DW, 1000),
+                w:               isType(e.W, 'array')  ? decodeWidthsW(e.W)  : null,
+                dw2:             isType(e.DW2, 'array') ? toNumArray(e.DW2)  : [880, -1000],
+                w2:              isType(e.W2, 'array') ? e.W2.items.map(it => it) : null,
+                cidToGIDMap:     e.CIDToGIDMap || null,
+                raw:             dict,
+                _extras:         {}
+            };
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function typeCIDSystemInfo(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/cid-system-info/not-dict',
+                    'CIDSystemInfo must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (!isType(e.Registry, 'string') || !isType(e.Ordering, 'string')) {
+                throw new ParseError('pdf/extra/cid-system-info/incomplete',
+                    '/Registry and /Ordering are required strings');
+            }
+            return {
+                registry:    e.Registry.value,
+                ordering:    e.Ordering.value,
+                supplement:  numVal(e.Supplement, 0)
+            };
+        }
+
+        function decodeWidthsW(arr) {
+            if (!isType(arr, 'array')) {
+                throw new ParseError('pdf/extra/cid-font/bad-w',
+                    '/W must be an array',
+                    { context: { type: arr && arr.type } });
+            }
+            const items = arr.items;
+            const out = [];
+            let i = 0;
+            while (i < items.length) {
+                const c = items[i];
+                if (!c || (c.type !== 'int' && c.type !== 'real')) {
+                    throw new ParseError('pdf/extra/cid-font/bad-w-c',
+                        '/W expects numeric CID');
+                }
+                const first = c.value | 0;
+                const nxt = items[i + 1];
+                if (nxt && nxt.type === 'array') {
+                    const widths = [];
+                    for (const it of nxt.items) {
+                        if (!it || (it.type !== 'int' && it.type !== 'real')) {
+                            throw new ParseError('pdf/extra/cid-font/bad-w-item',
+                                '/W array sub-items must be numeric');
+                        }
+                        widths.push(it.value);
+                    }
+                    out.push({ first, last: first + widths.length - 1, widths });
+                    i += 2;
+                } else {
+                    const last = nxt;
+                    const w = items[i + 2];
+                    if (!last || (last.type !== 'int' && last.type !== 'real') ||
+                        !w    || (w.type !== 'int' && w.type !== 'real')) {
+                        throw new ParseError('pdf/extra/cid-font/bad-w-range',
+                            '/W range form requires c_first c_last w');
+                    }
+                    out.push({ first, last: last.value | 0, width: w.value });
+                    i += 3;
+                }
+            }
+            return out;
+        }
+
+        function numVal(v, dflt) {
+            if (!v) return dflt;
+            if (v.type !== 'int' && v.type !== 'real') return dflt;
+            return v.value;
+        }
+
+        function toNumArray(v) {
+            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);
+            }
+            return out;
+        }
+
+        return { typeCIDFont, typeCIDSystemInfo, decodeWidthsW, PREDEFINED_CMAPS };
+    }
+};
+

package/src/extra/font-color-tagging.js

@@ -0,0 +1,144 @@
+// 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: color-font detection per ISO 32000-2:2020
+ * §9.8.2 (FontDescriptor `/Flags`) plus the OpenType color tables
+ * COLR/sbix/SVG via /FontFile3 streams with `/Subtype /OpenType`.
+ *
+ * Color-font detection is heuristic — the PDF FontDescriptor does NOT
+ * carry a single "is-color-font" flag. We expose:
+ *  - `decodeFontDescriptorFlags(int)`     → typed flag record
+ *  - `detectColorFontTables(stream)`      → which color-OT tables are
+ *    present in an embedded OpenType font program by sfnt-table scan
+ *  - `typeFontFile3OpenType(stream)`      → typed wrapper around a
+ *    `/FontFile3` stream whose `/Subtype` is `/OpenType`
+ *
+ * @module pdf/extra/font-color-tagging
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParserObj } from '../syntax/parser-obj.js';
+
+export const pdfFontColorTagging = {
+    name: 'pdfFontColorTagging',
+    dependencies: ['pdfErrors', 'pdfParserObj'],
+    deps: [pdfErrors, pdfParserObj],
+    factory(errors, parserObj) {
+        const { ParseError } = errors;
+        const { isType } = parserObj;
+
+        const FONT_DESCRIPTOR_FLAGS = Object.freeze({
+            FixedPitch:   1 << 0,
+            Serif:        1 << 1,
+            Symbolic:     1 << 2,
+            Script:       1 << 3,
+            Nonsymbolic:  1 << 5,
+            Italic:       1 << 6,
+            AllCap:       1 << 16,
+            SmallCap:     1 << 17,
+            ForceBold:    1 << 18
+        });
+
+        const COLOR_OT_TABLES = Object.freeze(['COLR', 'CPAL', 'sbix', 'SVG ', 'CBDT', 'CBLC']);
+
+        function decodeFontDescriptorFlags(flags) {
+            if (typeof flags !== 'number' || !Number.isFinite(flags)) {
+                throw new ParseError('pdf/extra/font-flags/bad-input',
+                    'flags must be a finite number',
+                    { context: { flags } });
+            }
+            const f = flags | 0;
+            const out = { raw: f };
+            for (const [k, mask] of Object.entries(FONT_DESCRIPTOR_FLAGS)) {
+                out[k.charAt(0).toLowerCase() + k.slice(1)] = (f & mask) !== 0;
+            }
+            return out;
+        }
+
+        function detectColorFontTables(bytes) {
+            if (!(bytes instanceof Uint8Array)) {
+                throw new ParseError('pdf/extra/color-font/bad-input',
+                    'expected Uint8Array', { context: { kind: typeof bytes } });
+            }
+            if (bytes.length < 12) {
+                throw new ParseError('pdf/extra/color-font/truncated',
+                    'sfnt header too short', { context: { length: bytes.length } });
+            }
+            const numTables = (bytes[4] << 8) | bytes[5];
+            const need = 12 + numTables * 16;
+            if (bytes.length < need) {
+                throw new ParseError('pdf/extra/color-font/truncated',
+                    'sfnt table directory truncated',
+                    { context: { numTables, length: bytes.length } });
+            }
+            const tables = [];
+            for (let i = 0; i < numTables; i++) {
+                const off = 12 + i * 16;
+                const tag = String.fromCharCode(bytes[off], bytes[off + 1], bytes[off + 2], bytes[off + 3]);
+                tables.push(tag);
+            }
+            return {
+                hasCOLR: tables.includes('COLR'),
+                hasSbix: tables.includes('sbix'),
+                hasSVG:  tables.includes('SVG '),
+                hasCBDT: tables.includes('CBDT'),
+                tables
+            };
+        }
+
+        function typeFontFile3OpenType(stream) {
+            if (!isType(stream, 'stream')) {
+                throw new ParseError('pdf/extra/fontfile3/not-stream',
+                    '/FontFile3 must be a stream',
+                    { context: { type: stream && stream.type } });
+            }
+            const dict = stream.dict;
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/fontfile3/no-dict',
+                    '/FontFile3 stream missing dict');
+            }
+            const e = dict.entries;
+            if (!isType(e.Subtype, 'name') || e.Subtype.value !== 'OpenType') {
+                throw new ParseError('pdf/extra/fontfile3/bad-subtype',
+                    '/FontFile3 /Subtype must be /OpenType',
+                    { context: { actual: e.Subtype && e.Subtype.value } });
+            }
+            let color = null;
+            if (stream.raw instanceof Uint8Array && stream.raw.length >= 12) {
+                try { color = detectColorFontTables(stream.raw); }
+                catch (_e) { color = null; }
+            }
+            return {
+                subtype:  'OpenType',
+                length:   stream.raw instanceof Uint8Array ? stream.raw.length : null,
+                metadata: e.Metadata || null,
+                color,
+                raw:      stream,
+                _extras:  collectExtras(e, new Set(['Subtype', 'Length', 'Filter', 'DecodeParms', 'Metadata']))
+            };
+        }
+
+        function collectExtras(entries, known) {
+            const out = {};
+            for (const k of Object.keys(entries)) {
+                if (!known.has(k)) out[k] = entries[k];
+            }
+            return out;
+        }
+
+        return {
+            decodeFontDescriptorFlags,
+            detectColorFontTables,
+            typeFontFile3OpenType,
+            FONT_DESCRIPTOR_FLAGS,
+            COLOR_OT_TABLES
+        };
+    }
+};
+