@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/errors.js

@@ -0,0 +1,78 @@
+// 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 Typed error hierarchy for `@awacloud/pdf` — exposed as the
+ * `pdfErrors` module factory.
+ *
+ * Five classes inheriting from `PdfError` :
+ *
+ * - `ParseError`      — malformed input encountered while reading
+ *                       (bad header, truncated xref, unbalanced dict,
+ *                       unknown filter, …).
+ * - `RenderError`     — invalid model encountered while writing
+ *                       (e.g. circular indirect reference, missing
+ *                       required field on Page).
+ * - `ContractError`   — the consumer violated the API contract
+ *                       (e.g. `.use()` called twice with the same
+ *                       extension, passing a non-Uint8Array to
+ *                       `.read()`).
+ * - `EncryptionError` — encryption / decryption failure (bad password,
+ *                       unsupported Security Handler revision,
+ *                       PKCS#7 verification mismatch).
+ *
+ * Each error carries a kebab-case `code` (e.g. `'pdf/bad-header'`,
+ * `'pdf/xref/truncated'`), an optional `context` object, and an
+ * optional `cause`.
+ *
+ * Classes are declared **inside the factory body** so the factory is a
+ * self-contained closure that can be serialised to a Worker via
+ * `factory.toString()`. Consumers obtain the classes by resolving the
+ * `pdfErrors` module via a `ModuleRuntime` (which caches the resolved
+ * instance, providing stable class identities for `instanceof`).
+ *
+ * ```js
+ * const { PdfError, ParseError } = runtime.resolve('pdfErrors');
+ * try { pdf.read(bytes); }
+ * catch (e) { if (e instanceof PdfError) console.log(e.code, e.context); }
+ * ```
+ *
+ * **Migration (passe 1/2/2a/2b/2c/TD-1 — complete)** — top-level error
+ * classes are no longer exported as named ESM bindings and no longer
+ * live at module scope. All consumers (source and tests) resolve them
+ * via `pdfErrors.factory()` (or, preferably, through a `ModuleRuntime`
+ * to share class identities). The transitional compatibility shim that
+ * re-exported `PdfError`, `ParseError`, `RenderError`, `ContractError`
+ * and `EncryptionError` was removed at the end of passe 2c.
+ *
+ * @module pdf/errors
+ */
+
+export const pdfErrors = {
+    name: 'pdfErrors',
+    dependencies: [],
+    factory() {
+        class PdfError extends Error {
+            constructor(code, message, opts) {
+                super(message);
+                this.name = new.target.name;
+                this.code = code;
+                if (opts && opts.context) this.context = opts.context;
+                if (opts && opts.cause)   this.cause = opts.cause;
+            }
+        }
+        class ParseError      extends PdfError {}
+        class RenderError     extends PdfError {}
+        class ContractError   extends PdfError {}
+        class EncryptionError extends PdfError {}
+
+        function isPdfError(e) { return e instanceof PdfError; }
+
+        return {
+            PdfError, ParseError, RenderError, ContractError, EncryptionError,
+            isPdfError
+        };
+    }
+};

package/src/extra/3d-richmedia.js

@@ -0,0 +1,171 @@
+// 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: 3D and RichMedia annotation typing.
+ *
+ * ISO 32000-2:2020 §13.6 defines two interactive multimedia annotation
+ * subtypes:
+ *
+ *   - `/Subtype /3D` (§13.6.2)  — references a 3D stream via `/3DD`,
+ *      default view (`/3DV`), activation dict (`/3DA`), interactive
+ *      dict (`/3DI`).
+ *
+ *   - `/Subtype /RichMedia` (§13.6.3) — `/RichMediaContent` with
+ *      `/Assets`, `/Configurations`, `/Views`; `/RichMediaSettings`
+ *      with `/Activation`, `/Deactivation`, instance state.
+ *
+ * @module pdf/extra/3d-richmedia
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdf3dRichMedia = {
+    name: 'pdf3dRichMedia',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const THREE_D_KNOWN = new Set([
+            'Type', 'Subtype', 'Rect', '3DD', '3DV', '3DA', '3DI', '3DB'
+        ]);
+        const RM_KNOWN = new Set([
+            'Type', 'Subtype', 'Rect', 'RichMediaContent', 'RichMediaSettings'
+        ]);
+
+        const RM_INSTANCE_STATES = Object.freeze({
+            A: 'active',
+            L: 'loaded',
+            U: 'uninstantiated'
+        });
+
+        const ACTIVATION_CONDITIONS = Object.freeze({
+            XA: 'explicit activate',
+            PO: 'page open',
+            PV: 'page visible'
+        });
+
+        function type3DAnnot(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/3d/not-dict',
+                    '3D annotation must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Subtype && (e.Subtype.type !== 'name' || e.Subtype.value !== '3D')) {
+                throw new ParseError('pdf/extra/3d/bad-subtype',
+                    '/Subtype must be /3D',
+                    { context: { actual: e.Subtype.value } });
+            }
+            if (!e['3DD']) {
+                throw new ParseError('pdf/extra/3d/missing-3dd',
+                    '3D annotation requires /3DD entry');
+            }
+            const out = {
+                threeDD: e['3DD'],
+                threeDV: e['3DV'] || null,
+                threeDA: isType(e['3DA'], 'dict') ? type3DActivation(e['3DA']) : null,
+                threeDI: isType(e['3DI'], 'bool') ? e['3DI'].value : null,
+                threeDB: e['3DB'] || null,
+                raw: dict,
+                _extras: {}
+            };
+            for (const k of Object.keys(e)) {
+                if (!THREE_D_KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function type3DActivation(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/3d/act/not-dict',
+                    '/3DA must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            return {
+                a:    isType(e.A,   'name') ? e.A.value   : null,
+                ais:  isType(e.AIS, 'name') ? e.AIS.value : null,
+                d:    isType(e.D,   'name') ? e.D.value   : null,
+                dis:  isType(e.DIS, 'name') ? e.DIS.value : null,
+                tb:   isType(e.TB, 'bool')  ? e.TB.value  : null,
+                np:   isType(e.NP, 'bool')  ? e.NP.value  : null,
+                raw:  dict
+            };
+        }
+
+        function typeRichMediaAnnot(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/rm/not-dict',
+                    'RichMedia annotation must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Subtype && (e.Subtype.type !== 'name' || e.Subtype.value !== 'RichMedia')) {
+                throw new ParseError('pdf/extra/rm/bad-subtype',
+                    '/Subtype must be /RichMedia',
+                    { context: { actual: e.Subtype.value } });
+            }
+            if (!e.RichMediaContent) {
+                throw new ParseError('pdf/extra/rm/missing-content',
+                    'RichMedia annotation requires /RichMediaContent');
+            }
+            const out = {
+                content:  isType(e.RichMediaContent, 'dict')
+                    ? typeRichMediaContent(e.RichMediaContent) : e.RichMediaContent,
+                settings: isType(e.RichMediaSettings, 'dict')
+                    ? e.RichMediaSettings : null,
+                raw: dict,
+                _extras: {}
+            };
+            for (const k of Object.keys(e)) {
+                if (!RM_KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function typeRichMediaContent(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/rm/content/not-dict',
+                    '/RichMediaContent must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            return {
+                assets:         e.Assets         || null,
+                configurations: e.Configurations || null,
+                views:          e.Views          || null,
+                raw: dict
+            };
+        }
+
+        function classifyRmInstanceState(name) {
+            if (name == null) return null;
+            if (typeof name !== 'string') {
+                throw new ParseError('pdf/extra/rm/state/bad',
+                    'state must be a string',
+                    { context: { type: typeof name } });
+            }
+            return RM_INSTANCE_STATES[name] || null;
+        }
+
+        return {
+            type3DAnnot,
+            type3DActivation,
+            typeRichMediaAnnot,
+            typeRichMediaContent,
+            classifyRmInstanceState,
+            RM_INSTANCE_STATES,
+            ACTIVATION_CONDITIONS
+        };
+    }
+};
+

package/src/extra/annot-extended.js

@@ -0,0 +1,200 @@
+// 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 annotation subtypes per
+ * ISO 32000-2:2020 §12.5.6.
+ *
+ * Covers: Watermark (§12.5.6.22), 3D (§13.6), RichMedia (§13.6.2),
+ * Sound (§12.5.6.16 legacy), Movie (§12.5.6.17 legacy),
+ * Screen (§12.5.6.18), PrinterMark (§12.5.6.20), TrapNet (§12.5.6.21),
+ * and FreeText-extended (`/RC`, `/DS`, `/LE`, §12.5.6.6).
+ *
+ * Each typer composes `typeBaseAnnot` from `../annot/annot.js` so the
+ * common annotation entries are preserved.
+ *
+ * @module pdf/extra/annot-extended
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParserObj } from '../syntax/parser-obj.js';
+import { pdfAnnot } from '../annot/annot.js';
+
+export const pdfAnnotExtended = {
+    name: 'pdfAnnotExtended',
+    dependencies: ['pdfErrors', 'pdfParserObj', 'pdfAnnot'],
+    deps: [pdfErrors, pdfParserObj, pdfAnnot],
+    factory(errors, parserObj, annot) {
+        const { ParseError } = errors;
+        const { isType } = parserObj;
+        const { typeBaseAnnot, captureExtras } = annot;
+
+        const SUBTYPES = new Set([
+            'Watermark', '3D', 'RichMedia', 'Sound', 'Movie', 'Screen',
+            'PrinterMark', 'TrapNet', 'FreeText'
+        ]);
+
+        const FREETEXT_LINE_ENDINGS = Object.freeze([
+            'Square', 'Circle', 'Diamond', 'OpenArrow', 'ClosedArrow', 'None',
+            'Butt', 'ROpenArrow', 'RClosedArrow', 'Slash'
+        ]);
+
+        function typeAnnotExtended(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/annot-ext/not-dict',
+                    'annotation must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const sub = dict.entries.Subtype;
+            if (!isType(sub, 'name') || !SUBTYPES.has(sub.value)) {
+                throw new ParseError('pdf/extra/annot-ext/unsupported',
+                    'unsupported extended annotation subtype',
+                    { context: { subtype: sub && sub.value } });
+            }
+            switch (sub.value) {
+                case 'Watermark':   return typeWatermarkAnnot(dict);
+                case '3D':          return type3DAnnot(dict);
+                case 'RichMedia':   return typeRichMediaAnnot(dict);
+                case 'Sound':       return typeSoundAnnot(dict);
+                case 'Movie':       return typeMovieAnnot(dict);
+                case 'Screen':      return typeScreenAnnot(dict);
+                case 'PrinterMark': return typePrinterMarkAnnot(dict);
+                case 'TrapNet':     return typeTrapNetAnnot(dict);
+                case 'FreeText':    return typeFreeTextExtended(dict);
+            }
+            /* istanbul ignore next */
+            throw new ParseError('pdf/extra/annot-ext/unreachable', 'unreachable');
+        }
+
+        function typeWatermarkAnnot(dict) {
+            const base = typeBaseAnnot(dict);
+            base.kind = 'Watermark';
+            const e = dict.entries;
+            base.fixedPrint = isType(e.FixedPrint, 'dict') ? e.FixedPrint : null;
+            captureExtras(base, dict, new Set(['FixedPrint']));
+            return base;
+        }
+
+        function type3DAnnot(dict) {
+            const base = typeBaseAnnot(dict);
+            base.kind = '3D';
+            const e = dict.entries;
+            base['3DD']  = e['3DD']  || null;
+            base['3DV']  = e['3DV']  || null;
+            base['3DA']  = e['3DA']  || null;
+            base['3DI']  = isType(e['3DI'], 'bool') ? e['3DI'].value : null;
+            base['3DB']  = e['3DB']  || null;
+            captureExtras(base, dict, new Set(['3DD', '3DV', '3DA', '3DI', '3DB']));
+            return base;
+        }
+
+        function typeRichMediaAnnot(dict) {
+            const base = typeBaseAnnot(dict);
+            base.kind = 'RichMedia';
+            const e = dict.entries;
+            base.richMediaContent  = e.RichMediaContent  || null;
+            base.richMediaSettings = e.RichMediaSettings || null;
+            captureExtras(base, dict, new Set(['RichMediaContent', 'RichMediaSettings']));
+            return base;
+        }
+
+        function typeSoundAnnot(dict) {
+            const base = typeBaseAnnot(dict);
+            base.kind = 'Sound';
+            const e = dict.entries;
+            base.sound = e.Sound || null;
+            base.name  = isType(e.Name, 'name') ? e.Name.value : null;
+            captureExtras(base, dict, new Set(['Sound', 'Name']));
+            return base;
+        }
+
+        function typeMovieAnnot(dict) {
+            const base = typeBaseAnnot(dict);
+            base.kind = 'Movie';
+            const e = dict.entries;
+            base.t          = isType(e.T, 'string') ? e.T.value : null;
+            base.movie      = e.Movie || null;
+            base.activation = e.A || null;
+            captureExtras(base, dict, new Set(['T', 'Movie', 'A']));
+            return base;
+        }
+
+        function typeScreenAnnot(dict) {
+            const base = typeBaseAnnot(dict);
+            base.kind = 'Screen';
+            const e = dict.entries;
+            base.t   = isType(e.T, 'string') ? e.T.value : null;
+            base.mk  = e.MK || null;
+            base.a   = e.A  || null;
+            base.aa  = e.AA || null;
+            captureExtras(base, dict, new Set(['T', 'MK', 'A', 'AA']));
+            return base;
+        }
+
+        function typePrinterMarkAnnot(dict) {
+            const base = typeBaseAnnot(dict);
+            base.kind = 'PrinterMark';
+            const e = dict.entries;
+            base.mn = isType(e.MN, 'name') ? e.MN.value : null;
+            captureExtras(base, dict, new Set(['MN']));
+            return base;
+        }
+
+        function typeTrapNetAnnot(dict) {
+            const base = typeBaseAnnot(dict);
+            base.kind = 'TrapNet';
+            const e = dict.entries;
+            base.lastModified = isType(e.LastModified, 'string') ? e.LastModified.value : null;
+            base.version      = e.Version || null;
+            base.annotStates  = e.AnnotStates || null;
+            base.fontFauxing  = e.FontFauxing || null;
+            captureExtras(base, dict, new Set(['LastModified', 'Version', 'AnnotStates', 'FontFauxing']));
+            return base;
+        }
+
+        function typeFreeTextExtended(dict) {
+            const base = typeBaseAnnot(dict);
+            base.kind = 'FreeText';
+            const e = dict.entries;
+            base.da = isType(e.DA, 'string') ? e.DA.value : null;
+            base.q  = (e.Q && (e.Q.type === 'int' || e.Q.type === 'real')) ? (e.Q.value | 0) : null;
+            base.rc = isType(e.RC, 'string') ? e.RC.value : (isType(e.RC, 'stream') ? e.RC : null);
+            base.ds = isType(e.DS, 'string') ? e.DS.value : null;
+            base.cl = isType(e.CL, 'array') ? toNumArray(e.CL) : null;
+            base.it = isType(e.IT, 'name') ? e.IT.value : null;
+            base.be = e.BE || null;
+            base.rd = isType(e.RD, 'array') ? toNumArray(e.RD) : null;
+            let le = null;
+            if (isType(e.LE, 'name')) le = e.LE.value;
+            else if (isType(e.LE, 'array')) {
+                le = e.LE.items.filter(it => isType(it, 'name')).map(it => it.value);
+            }
+            base.le = le;
+            captureExtras(base, dict, new Set(['DA', 'Q', 'RC', 'DS', 'CL', 'IT', 'BE', 'RD', 'LE']));
+            return base;
+        }
+
+        function toNumArray(v) {
+            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 {
+            typeAnnotExtended,
+            typeWatermarkAnnot, type3DAnnot, typeRichMediaAnnot,
+            typeSoundAnnot, typeMovieAnnot, typeScreenAnnot,
+            typePrinterMarkAnnot, typeTrapNetAnnot, typeFreeTextExtended,
+            FREETEXT_LINE_ENDINGS
+        };
+    }
+};
+

package/src/extra/associated-files.js

@@ -0,0 +1,131 @@
+// 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 /AF (Associated Files) typing.
+ *
+ * PDF 2.0 lets /AF live on the Catalog, Page, XObject (Form), Mark,
+ * StructElem, Annot, or DParams. Each item references a File
+ * Specification dictionary that MUST carry /AFRelationship.
+ *
+ * Relationship vocabulary: Source, Data, Alternative, Supplement,
+ * EncryptedPayload, FormData, Schema, Unspecified.
+ *
+ * @module pdf/extra/associated-files
+ */
+
+import { pdfErrors } from '../errors.js';
+
+export const pdfAssociatedFiles2 = {
+    name: 'pdfAssociatedFiles2',
+    dependencies: ['pdfErrors'],
+    deps: [pdfErrors],
+
+    factory(errors) {
+        const { ParseError } = errors;
+        const STANDARD_REL = new Set([
+            'Source', 'Data', 'Alternative', 'Supplement',
+            'EncryptedPayload', 'FormData', 'Schema', 'Unspecified'
+        ]);
+
+        const CARRIER_HINTS = new Set([
+            'Catalog', 'Page', 'XObject', 'StructElem', 'Annot', 'Mark', 'DParams'
+        ]);
+
+        function isDict(v) { return v && v.type === 'dict'; }
+        function isName(v) { return v && v.type === 'name'; }
+        function isArr(v) { return v && v.type === 'array'; }
+        function isRef(v) { return v && v.type === 'ref'; }
+
+        function resolveFileSpec(entry, resolveRef) {
+            if (isRef(entry)) {
+                if (typeof resolveRef === 'function') {
+                    const r = resolveRef(entry);
+                    return { resolved: true, dict: r, ref: { num: entry.num, gen: entry.gen } };
+                }
+                return { resolved: false, ref: { num: entry.num, gen: entry.gen } };
+            }
+            if (isDict(entry)) return { resolved: true, dict: entry };
+            throw new ParseError('pdf/af2/bad-entry',
+                '/AF entry must be a dict or indirect reference',
+                { context: { type: entry && entry.type } });
+        }
+
+        function typeAfEntry(entry, resolveRef, index) {
+            const res = resolveFileSpec(entry, resolveRef);
+            if (!res.resolved) {
+                return { ref: res.ref, resolved: false };
+            }
+            const dict = res.dict;
+            if (!isDict(dict)) {
+                throw new ParseError('pdf/af2/not-filespec',
+                    'resolved /AF entry must be a dict',
+                    { context: { index } });
+            }
+            const e = dict.entries;
+            if (e.Type && (!isName(e.Type) || e.Type.value !== 'Filespec')) {
+                throw new ParseError('pdf/af2/bad-filespec-type',
+                    'expected /Type /Filespec',
+                    { context: { index, actual: e.Type && e.Type.value } });
+            }
+            let rel = null, standard = false;
+            if (e.AFRelationship) {
+                if (!isName(e.AFRelationship)) {
+                    throw new ParseError('pdf/af2/bad-relationship',
+                        '/AFRelationship must be a name',
+                        { context: { index, type: e.AFRelationship.type } });
+                }
+                rel = e.AFRelationship.value;
+                standard = STANDARD_REL.has(rel);
+            }
+            const out = {
+                filespec: dict,
+                relationship: rel,
+                standard,
+                resolved: true
+            };
+            if (res.ref) out.ref = res.ref;
+            return out;
+        }
+
+        function typeAf(afArray, opts) {
+            const resolveRef = opts && opts.resolveRef;
+            const carrier = opts && opts.carrier;
+            if (carrier && !CARRIER_HINTS.has(carrier)) {
+                throw new ParseError('pdf/af2/bad-carrier',
+                    'unknown /AF carrier hint',
+                    { context: { carrier } });
+            }
+            if (!isArr(afArray)) {
+                throw new ParseError('pdf/af2/not-array',
+                    '/AF must be an array',
+                    { context: { type: afArray && afArray.type } });
+            }
+            const out = [];
+            for (let i = 0; i < afArray.items.length; i++) {
+                out.push(typeAfEntry(afArray.items[i], resolveRef, i));
+            }
+            return { entries: out, carrier: carrier || null };
+        }
+
+        function isStandardRelationship(name) {
+            return STANDARD_REL.has(String(name));
+        }
+
+        function listStandardRelationships() {
+            return Array.from(STANDARD_REL);
+        }
+
+        return {
+            typeAf,
+            typeAfEntry,
+            resolveFileSpec,
+            isStandardRelationship,
+            listStandardRelationships,
+            STANDARD_REL,
+            CARRIER_HINTS
+        };
+    }
+};