@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/extra/transparency-typed.js

@@ -0,0 +1,135 @@
+// 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 Transparency Group attributes (§11.6.6),
+ * Soft Mask (§11.6.5.2 — Luminosity/Alpha) with `/TR` transfer, and the
+ * frozen catalog of standard blend modes (§11.3.5) — ISO 32000-2:2020.
+ *
+ * @module pdf/extra/transparency-typed
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfTransparencyTyped = {
+    name: 'pdfTransparencyTyped',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        /** 16 standard blend modes (§11.3.5 Table 136). */
+        const BLEND_MODES = Object.freeze([
+            'Normal', 'Compatible', 'Multiply', 'Screen', 'Overlay',
+            'Darken', 'Lighten', 'ColorDodge', 'ColorBurn', 'HardLight',
+            'SoftLight', 'Difference', 'Exclusion',
+            'Hue', 'Saturation', 'Color', 'Luminosity'
+        ]);
+
+        const NUM = (v) => v && (v.type === 'int' || v.type === 'real');
+
+        function typeTransparencyGroup(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/transparency-group/not-dict',
+                    'Transparency Group must be a dict',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'Group')) {
+                throw new ParseError('pdf/extra/transparency-group/bad-type',
+                    '/Type entry must be /Group',
+                    { context: { actual: e.Type.value } });
+            }
+            if (!isType(e.S, 'name') || e.S.value !== 'Transparency') {
+                throw new ParseError('pdf/extra/transparency-group/bad-s',
+                    '/S must be /Transparency',
+                    { context: { actual: e.S && e.S.value } });
+            }
+            const known = new Set(['Type', 'S', 'CS', 'I', 'K']);
+            const out = {
+                s:        'Transparency',
+                cs:       e.CS || null,
+                isolated: isType(e.I, 'bool') ? e.I.value : false,
+                knockout: isType(e.K, 'bool') ? e.K.value : false,
+                raw:      dict,
+                _extras:  {}
+            };
+            for (const k of Object.keys(e)) if (!known.has(k)) out._extras[k] = e[k];
+            return out;
+        }
+
+        function typeSoftMask(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/soft-mask/not-dict',
+                    'Soft Mask must be a dict',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'Mask')) {
+                throw new ParseError('pdf/extra/soft-mask/bad-type',
+                    '/Type entry must be /Mask',
+                    { context: { actual: e.Type.value } });
+            }
+            if (!isType(e.S, 'name') || (e.S.value !== 'Alpha' && e.S.value !== 'Luminosity')) {
+                throw new ParseError('pdf/extra/soft-mask/bad-s',
+                    '/S must be /Alpha or /Luminosity',
+                    { context: { actual: e.S && e.S.value } });
+            }
+            if (!e.G) {
+                throw new ParseError('pdf/extra/soft-mask/missing-g',
+                    'Soft Mask requires /G (transparency group XObject)');
+            }
+            const known = new Set(['Type', 'S', 'G', 'BC', 'TR']);
+            const out = {
+                kind:        e.S.value,
+                g:           e.G,
+                backdrop:    isType(e.BC, 'array') ? toNumArr(e.BC) : null,
+                transfer:    e.TR || null,
+                raw:         dict,
+                _extras:     {}
+            };
+            for (const k of Object.keys(e)) if (!known.has(k)) out._extras[k] = e[k];
+            return out;
+        }
+
+        function resolveBlendMode(value) {
+            if (!value) return null;
+            if (isType(value, 'name')) {
+                return BLEND_MODES.includes(value.value) ? value.value : null;
+            }
+            if (isType(value, 'array')) {
+                for (const it of value.items) {
+                    if (isType(it, 'name') && BLEND_MODES.includes(it.value)) return it.value;
+                }
+                return null;
+            }
+            throw new ParseError('pdf/extra/blend-mode/bad-type',
+                '/BM must be name or array of names',
+                { context: { type: value.type } });
+        }
+
+        function toNumArr(v) {
+            const out = [];
+            for (const it of v.items) {
+                if (!NUM(it)) return null;
+                out.push(it.value);
+            }
+            return out;
+        }
+
+        return {
+            typeTransparencyGroup,
+            typeSoftMask,
+            resolveBlendMode,
+            BLEND_MODES
+        };
+    }
+};
+

package/src/extra/well-tagged-pdf.js

@@ -0,0 +1,138 @@
+// 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: WTPDF 1.0 (Well-Tagged PDF) linter.
+ *
+ * @module pdf/extra/well-tagged-pdf
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfWellTagged = {
+    name: 'pdfWellTagged',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, _p) {
+        const { ParseError } = errors;
+
+        /** Frozen catalog of rule identifiers used in lint output. */
+        const WTPDF_RULES = Object.freeze({
+            'wtpdf/artifact':       'decorative content must be tagged Artifact',
+            'wtpdf/span/empty':     'Span used as pseudo-paragraph wrapper',
+            'wtpdf/table/empty':    'Table must contain at least one TR',
+            'wtpdf/table/row':      'TR must contain TH or TD children',
+            'wtpdf/list/empty':     'L must contain at least one LI',
+            'wtpdf/list/item':      'LI should contain Lbl + LBody',
+            'wtpdf/heading/jump':   'heading level jump (e.g. H1 -> H3) is discouraged'
+        });
+
+        function lintWellTagged(tree) {
+            if (!tree || typeof tree !== 'object') {
+                throw new ParseError('pdf/extra/wtpdf/bad-tree',
+                    'lintWellTagged requires a structure tree object',
+                    { context: { type: typeof tree } });
+            }
+            const errs = [];
+            const warnings = [];
+            let lastHeading = 0;
+            function walk(node) {
+                if (!node || typeof node !== 'object' || !node.s) return;
+                switch (node.s) {
+                    case 'Table':   checkTable(node, errs); break;
+                    case 'L':       checkList(node, errs, warnings); break;
+                    case 'Span':    if (!node.role) {
+                                        warnings.push({ rule: 'wtpdf/span/empty',
+                                            message: WTPDF_RULES['wtpdf/span/empty'] });
+                                    } break;
+                    case 'Artifact': /* allowed */ break;
+                    default: break;
+                }
+                const m = /^H([1-6])$/.exec(node.s);
+                if (m) {
+                    const lvl = Number(m[1]);
+                    if (lastHeading && lvl > lastHeading + 1) {
+                        warnings.push({ rule: 'wtpdf/heading/jump',
+                            message: WTPDF_RULES['wtpdf/heading/jump'],
+                            from: lastHeading, to: lvl });
+                    }
+                    lastHeading = lvl;
+                }
+                if (Array.isArray(node.k)) {
+                    for (const c of node.k) {
+                        if (c && typeof c === 'object') walk(c);
+                    }
+                }
+            }
+            walk(tree);
+            return { pass: errs.length === 0, errors: errs, warnings };
+        }
+
+        function checkTable(node, errs) {
+            const rows = (node.k || []).filter(c => c && c.s === 'TR');
+            if (rows.length === 0) {
+                errs.push({ rule: 'wtpdf/table/empty',
+                    message: WTPDF_RULES['wtpdf/table/empty'] });
+                return;
+            }
+            for (const tr of rows) {
+                const cells = (tr.k || []).filter(c => c && (c.s === 'TH' || c.s === 'TD'));
+                if (cells.length === 0) {
+                    errs.push({ rule: 'wtpdf/table/row',
+                        message: WTPDF_RULES['wtpdf/table/row'] });
+                }
+            }
+        }
+
+        function checkList(node, errs, warnings) {
+            const items = (node.k || []).filter(c => c && c.s === 'LI');
+            if (items.length === 0) {
+                errs.push({ rule: 'wtpdf/list/empty',
+                    message: WTPDF_RULES['wtpdf/list/empty'] });
+                return;
+            }
+            for (const li of items) {
+                const has = { Lbl: false, LBody: false };
+                for (const c of li.k || []) {
+                    if (c && c.s === 'Lbl')   has.Lbl   = true;
+                    if (c && c.s === 'LBody') has.LBody = true;
+                }
+                if (!has.Lbl || !has.LBody) {
+                    warnings.push({ rule: 'wtpdf/list/item',
+                        message: WTPDF_RULES['wtpdf/list/item'] });
+                }
+            }
+        }
+
+        function checkArtifactPlacement(regions) {
+            if (!Array.isArray(regions)) {
+                throw new ParseError('pdf/extra/wtpdf/regions/bad-input',
+                    'checkArtifactPlacement requires an array',
+                    { context: { type: typeof regions } });
+            }
+            const errs = [];
+            for (const r of regions) {
+                if (!r || typeof r !== 'object') continue;
+                if (r.tagged === false && r.role !== 'Artifact') {
+                    errs.push({ rule: 'wtpdf/artifact',
+                        message: WTPDF_RULES['wtpdf/artifact'],
+                        mcid: r.mcid });
+                }
+            }
+            return { pass: errs.length === 0, errors: errs, warnings: [] };
+        }
+
+        return {
+            lintWellTagged,
+            checkArtifactPlacement,
+            WTPDF_RULES
+        };
+    }
+};
+

package/src/extra/xmp-extended.js

@@ -0,0 +1,190 @@
+// 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: minimal XMP packet extractor.
+ *
+ * Tokenises an XMP RDF/XML packet for a fixed set of well-known
+ * namespaces and pulls out tag→value pairs. This is intentionally NOT
+ * an RDF parser; it walks the element stream and harvests qualified
+ * tag names whose prefix maps to one of the known namespaces.
+ *
+ * Supported namespaces (by URI):
+ *   dc      → http://purl.org/dc/elements/1.1/
+ *   xmp     → http://ns.adobe.com/xap/1.0/
+ *   xmpMM   → http://ns.adobe.com/xap/1.0/mm/
+ *   pdf     → http://ns.adobe.com/pdf/1.3/
+ *   pdfaid  → http://www.aiim.org/pdfa/ns/id/
+ *   pdfuaid → http://www.aiim.org/pdfua/ns/id/
+ *
+ * @module pdf/extra/xmp-extended
+ */
+
+import { pdfErrors } from '../errors.js';
+
+export const pdfXmpExtended = {
+    name: 'pdfXmpExtended',
+    dependencies: ['pdfErrors'],
+    deps: [pdfErrors],
+
+    factory(errors) {
+        const { ParseError } = errors;
+        const KNOWN_NAMESPACES = {
+            'http://purl.org/dc/elements/1.1/':  'dc',
+            'http://ns.adobe.com/xap/1.0/':      'xmp',
+            'http://ns.adobe.com/xap/1.0/mm/':   'xmpMM',
+            'http://ns.adobe.com/pdf/1.3/':      'pdf',
+            'http://www.aiim.org/pdfa/ns/id/':   'pdfaid',
+            'http://www.aiim.org/pdfua/ns/id/':  'pdfuaid'
+        };
+
+        function toText(bytes) {
+            if (typeof bytes === 'string') return bytes;
+            if (bytes instanceof Uint8Array) return new TextDecoder('utf-8').decode(bytes);
+            throw new ParseError('pdf/xmp2/bad-input',
+                'XMP input must be string or Uint8Array',
+                { context: { type: typeof bytes } });
+        }
+
+        // Parse xmlns:* attributes from a start-tag inner string.
+        function parseNamespaces(attrText) {
+            const map = {};
+            const rx = /xmlns:([\w-]+)\s*=\s*"([^"]*)"/g;
+            let m;
+            while ((m = rx.exec(attrText))) {
+                map[m[1]] = m[2];
+            }
+            return map;
+        }
+
+        // Parse attr=value pairs.
+        function parseAttrs(attrText) {
+            const out = {};
+            const rx = /([\w:-]+)\s*=\s*"([^"]*)"/g;
+            let m;
+            while ((m = rx.exec(attrText))) {
+                if (!m[1].startsWith('xmlns')) out[m[1]] = m[2];
+            }
+            return out;
+        }
+
+        function decodeEntities(s) {
+            return s.replace(/&lt;/g, '<')
+                    .replace(/&gt;/g, '>')
+                    .replace(/&quot;/g, '"')
+                    .replace(/&apos;/g, "'")
+                    .replace(/&amp;/g, '&');
+        }
+
+        // Tokenises tag/value pairs. Returns array of
+        //   { prefix, ns, localName, value, attrs }.
+        function extract(input) {
+            const text = toText(input);
+            const len = text.length;
+            // Top-level ns map from rdf:RDF attributes.
+            const tagRx = /<\/?([\w:-]+)([^>]*?)\/?>/g;
+            const stack = [{ ns: {} }];
+            const pairs = [];
+
+            let i = 0;
+            while (i < len) {
+                tagRx.lastIndex = i;
+                const m = tagRx.exec(text);
+                if (!m) break;
+                const start = m.index;
+                const whole = m[0];
+                const qname = m[1];
+                const attrText = m[2] || '';
+                const isClose = whole.startsWith('</');
+                const isSelf = whole.endsWith('/>');
+
+                if (isClose) {
+                    stack.pop();
+                    i = start + whole.length;
+                    continue;
+                }
+
+                // Open element. Inherit ns from parent, merge new ns
+                // declarations.
+                const parentNs = stack[stack.length - 1].ns;
+                const newNs = Object.assign({}, parentNs, parseNamespaces(attrText));
+                const attrs = parseAttrs(attrText);
+
+                let prefix = null, local = qname;
+                const colon = qname.indexOf(':');
+                if (colon >= 0) {
+                    prefix = qname.slice(0, colon);
+                    local = qname.slice(colon + 1);
+                }
+                const nsUri = prefix ? newNs[prefix] : null;
+                const knownPrefix = nsUri ? KNOWN_NAMESPACES[nsUri] : null;
+
+                let value = null;
+                if (!isSelf) {
+                    // Find matching close tag (simple — no nesting of
+                    // same-name tags supported beyond stack).
+                    const closeTag = `</${qname}>`;
+                    const closeAt = text.indexOf(closeTag, start + whole.length);
+                    if (closeAt < 0) {
+                        throw new ParseError('pdf/xmp2/unclosed-tag',
+                            `unclosed <${qname}>`,
+                            { context: { offset: start } });
+                    }
+                    const inner = text.slice(start + whole.length, closeAt);
+                    // If inner has no child element, treat as leaf value.
+                    if (!/<[\w]/.test(inner)) {
+                        value = decodeEntities(inner.trim());
+                    }
+                    stack.push({ ns: newNs, qname });
+                    if (value !== null) {
+                        // Skip past close tag and pop, since we consumed.
+                        stack.pop();
+                        i = closeAt + closeTag.length;
+                    } else {
+                        i = start + whole.length;
+                    }
+                } else {
+                    i = start + whole.length;
+                }
+
+                if (knownPrefix && (value !== null || Object.keys(attrs).length > 0)) {
+                    pairs.push({
+                        prefix: knownPrefix,
+                        ns: nsUri,
+                        localName: local,
+                        value,
+                        attrs
+                    });
+                }
+            }
+            return pairs;
+        }
+
+        // Group pairs into a { ns: { local: value | [values] } } map.
+        function group(pairs) {
+            const out = {};
+            for (const p of pairs) {
+                if (!out[p.prefix]) out[p.prefix] = {};
+                const bag = out[p.prefix];
+                if (bag[p.localName] === undefined) bag[p.localName] = p.value;
+                else if (Array.isArray(bag[p.localName])) bag[p.localName].push(p.value);
+                else bag[p.localName] = [bag[p.localName], p.value];
+            }
+            return out;
+        }
+
+        function parsePacket(input) {
+            const pairs = extract(input);
+            return { pairs, grouped: group(pairs) };
+        }
+
+        return {
+            parsePacket,
+            extract,
+            group,
+            KNOWN_NAMESPACES
+        };
+    }
+};