@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/tagged/roleMap.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 RoleMap typing per ISO 32000-2:2020 §14.7.5 + namespace
+ * handling per §14.7.6 (PDF 2.0).
+ *
+ * `/RoleMap` maps custom structure-type names to standard ones. A chain
+ * lookup may be required if a custom role maps to another custom role.
+ * Cycles are detected and rejected.
+ *
+ * The PDF 2.0 namespace model adds `/Namespaces` and per-element `/NS`.
+ * A namespace dict may carry its own `/RoleMapNS` that takes precedence
+ * for elements within that namespace.
+ *
+ * @module pdf/tagged/roleMap
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfRoleMap = {
+    name: 'pdfRoleMap',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const STANDARD_TYPES = new Set([
+            // Grouping
+            'Document', 'DocumentFragment', 'Part', 'Art', 'Sect', 'Div',
+            'BlockQuote', 'Caption', 'TOC', 'TOCI', 'Index', 'NonStruct',
+            'Private', 'Aside', 'Title', 'FENote',
+            // Paragraph-like
+            'P', 'H', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'H7',
+            // Lists
+            'L', 'LI', 'Lbl', 'LBody',
+            // Tables
+            'Table', 'TR', 'TH', 'TD', 'THead', 'TBody', 'TFoot',
+            // Inline
+            'Span', 'Quote', 'Note', 'Reference', 'BibEntry', 'Code',
+            'Link', 'Annot', 'Em', 'Strong',
+            // Ruby / Warichu
+            'Ruby', 'RB', 'RT', 'RP', 'Warichu', 'WT', 'WP',
+            // Illustration
+            'Figure', 'Formula', 'Form', 'Artifact'
+        ]);
+
+        function typeRoleMap(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/tagged/role-map/not-dict',
+                    'RoleMap must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const map = {};
+            for (const [k, v] of Object.entries(dict.entries)) {
+                if (!v || v.type !== 'name') {
+                    throw new ParseError('pdf/tagged/role-map/bad-value',
+                        'RoleMap values must be name objects',
+                        { context: { key: k, kind: v && v.type } });
+                }
+                map[k] = v.value;
+            }
+            return { map, raw: dict };
+        }
+
+        function resolveStandardType(name, map, namespaceMap) {
+            const chain = [];
+            const seen = new Set();
+            let cur = name;
+            while (cur) {
+                if (seen.has(cur)) {
+                    throw new ParseError('pdf/tagged/role-map/cycle',
+                        'cycle detected resolving role-map alias',
+                        { context: { chain: chain.slice() } });
+                }
+                seen.add(cur);
+                chain.push(cur);
+                if (STANDARD_TYPES.has(cur)) return { standard: cur, chain };
+                const nsHit = namespaceMap && namespaceMap[cur];
+                const next = nsHit || (map && map[cur]);
+                if (!next || next === cur) {
+                    return { standard: null, chain };
+                }
+                cur = next;
+            }
+            return { standard: null, chain };
+        }
+
+        function isStandardType(name) {
+            return STANDARD_TYPES.has(name);
+        }
+
+        return {
+            typeRoleMap,
+            resolveStandardType,
+            isStandardType,
+            STANDARD_TYPES
+        };
+    }
+};

package/src/tagged/structElement.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 Structure Element typing per ISO 32000-2:2020 §14.7.3.
+ *
+ * A `/Type /StructElem` dict represents a node in the logical structure
+ * tree. Heterogeneous `/K` is normalized to
+ * `[{ kind: 'elem'|'mcid'|'mcr'|'objr', ... }]`.
+ *
+ * @module pdf/tagged/structElement
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfStructElement = {
+    name: 'pdfStructElement',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const KNOWN = new Set([
+            'Type', 'S', 'P', 'ID', 'Pg', 'K', 'A', 'C', 'R', 'T', 'Lang',
+            'Alt', 'E', 'ActualText', 'AF', 'NS', 'PhoneticAlphabet', 'Phoneme'
+        ]);
+
+        function typeStructElement(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/tagged/struct-elem/not-dict',
+                    'StructElem must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'StructElem')) {
+                throw new ParseError('pdf/tagged/struct-elem/bad-type',
+                    '/Type entry must be /StructElem',
+                    { context: { actual: e.Type.value } });
+            }
+            if (!e.S || e.S.type !== 'name') {
+                throw new ParseError('pdf/tagged/struct-elem/missing-s',
+                    'StructElem missing required /S (structure type) name',
+                    { context: { type: e.S && e.S.type } });
+            }
+
+            const out = {
+                s:    e.S.value,
+                raw:  dict,
+                _extras: {}
+            };
+
+            if (e.P  && e.P.type === 'ref')    out.p  = e.P;
+            if (e.Pg && e.Pg.type === 'ref')   out.pg = e.Pg;
+            if (e.ID && e.ID.type === 'string') out.id = e.ID.value;
+            if (e.A)                            out.a  = e.A;
+            if (e.C && (e.C.type === 'name' || e.C.type === 'array')) out.c = e.C;
+            if (e.R && (e.R.type === 'int' || e.R.type === 'real'))   out.r = e.R.value | 0;
+            if (e.T          && e.T.type === 'string')         out.t          = e.T.value;
+            if (e.Lang       && e.Lang.type === 'string')      out.lang       = e.Lang.value;
+            if (e.Alt        && e.Alt.type === 'string')       out.alt        = e.Alt.value;
+            if (e.E          && e.E.type === 'string')         out.e          = e.E.value;
+            if (e.ActualText && e.ActualText.type === 'string') out.actualText = e.ActualText.value;
+            if (e.AF) out.af = e.AF;
+            if (e.NS && e.NS.type === 'ref') out.ns = e.NS;
+            if (e.PhoneticAlphabet && e.PhoneticAlphabet.type === 'name') {
+                out.phoneticAlphabet = e.PhoneticAlphabet.value;
+            }
+            if (e.Phoneme && e.Phoneme.type === 'string') out.phoneme = e.Phoneme.value;
+
+            if (e.K !== undefined) out.k = readKids(e.K);
+
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+
+            return out;
+        }
+
+        function readKids(k) {
+            if (!k) return [];
+            if (k.type === 'array') {
+                const out = [];
+                for (const item of k.items) out.push(classifyKid(item));
+                return out;
+            }
+            return [classifyKid(k)];
+        }
+
+        function classifyKid(item) {
+            if (!item || !item.type) {
+                throw new ParseError('pdf/tagged/struct-elem/bad-kid',
+                    'StructElem /K entry is malformed',
+                    { context: { item } });
+            }
+            if (item.type === 'int') return { kind: 'mcid', mcid: item.value | 0 };
+            if (item.type === 'ref') return { kind: 'elem', ref: item };
+            if (item.type === 'dict') {
+                const t = item.entries.Type;
+                const tn = t && t.type === 'name' ? t.value : null;
+                if (tn === 'MCR') {
+                    return {
+                        kind: 'mcr',
+                        pg:   item.entries.Pg,
+                        stm:  item.entries.Stm,
+                        stmOwn: item.entries.StmOwn,
+                        mcid: (item.entries.MCID && item.entries.MCID.type === 'int')
+                            ? item.entries.MCID.value | 0 : null,
+                        raw:  item
+                    };
+                }
+                if (tn === 'OBJR') {
+                    return {
+                        kind: 'objr',
+                        pg:   item.entries.Pg,
+                        obj:  item.entries.Obj,
+                        raw:  item
+                    };
+                }
+                if (item.entries.MCID && item.entries.MCID.type === 'int') {
+                    return { kind: 'mcr', mcid: item.entries.MCID.value | 0, raw: item };
+                }
+            }
+            throw new ParseError('pdf/tagged/struct-elem/bad-kid',
+                'StructElem /K entry must be ref, int, MCR-dict, or OBJR-dict',
+                { context: { kind: item.type } });
+        }
+
+        return { typeStructElement };
+    }
+};

package/src/tagged/structTree.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 Structure Tree Root typing per ISO 32000-2:2020 §14.7.2.
+ *
+ * The `/Type /StructTreeRoot` dict is referenced by the Catalog's
+ * `/StructTreeRoot` entry and anchors the logical structure tree used by
+ * Tagged PDF (§14.8) and PDF/UA-2 (ISO 14289-2). Unknown entries land in
+ * `_extras`.
+ *
+ * @module pdf/tagged/structTree
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfStructTree = {
+    name: 'pdfStructTree',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const KNOWN = new Set([
+            'Type', 'K', 'IDTree', 'ParentTree', 'ParentTreeNextKey',
+            'RoleMap', 'ClassMap', 'Namespaces', 'AF', 'PronunciationLexicon'
+        ]);
+
+        function typeStructTreeRoot(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/tagged/struct-tree/not-dict',
+                    'StructTreeRoot must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'StructTreeRoot')) {
+                throw new ParseError('pdf/tagged/struct-tree/bad-type',
+                    '/Type entry must be /StructTreeRoot',
+                    { context: { actual: e.Type.value } });
+            }
+
+            const out = { raw: dict, _extras: {} };
+
+            if (e.K !== undefined) out.kids = readKids(e.K);
+            if (e.IDTree)             out.idTree            = e.IDTree;
+            if (e.ParentTree)         out.parentTree        = e.ParentTree;
+            if (e.ParentTreeNextKey && (e.ParentTreeNextKey.type === 'int'
+                                     || e.ParentTreeNextKey.type === 'real')) {
+                out.parentTreeNextKey = e.ParentTreeNextKey.value | 0;
+            }
+            if (e.RoleMap   && e.RoleMap.type   === 'dict')  out.roleMap   = e.RoleMap;
+            if (e.ClassMap  && e.ClassMap.type  === 'dict')  out.classMap  = e.ClassMap;
+            if (e.Namespaces && e.Namespaces.type === 'array') out.namespaces = e.Namespaces;
+            if (e.AF) out.af = e.AF;
+            if (e.PronunciationLexicon) out.pronunciationLexicon = e.PronunciationLexicon;
+
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+
+            return out;
+        }
+
+        function readKids(k) {
+            if (!k) return [];
+            if (k.type === 'array') {
+                const out = [];
+                for (const item of k.items) {
+                    if (item.type !== 'ref' && item.type !== 'dict') {
+                        throw new ParseError('pdf/tagged/struct-tree/bad-kid',
+                            'StructTreeRoot /K array entries must be refs or dicts',
+                            { context: { kind: item.type } });
+                    }
+                    out.push(item);
+                }
+                return out;
+            }
+            if (k.type === 'ref' || k.type === 'dict') return [k];
+            throw new ParseError('pdf/tagged/struct-tree/bad-kid',
+                'StructTreeRoot /K must be a ref, dict, or array',
+                { context: { kind: k.type } });
+        }
+
+        return { typeStructTreeRoot };
+    }
+};