@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/ocg/config.js

@@ -0,0 +1,156 @@
+// 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 Optional Content Configuration dictionary typing per
+ * ISO 32000-2:2020 §8.11.4.
+ *
+ * `/OCProperties./D` (default config) and entries of `/OCProperties./Configs`
+ * are dictionaries describing the visibility state of a set of OCGs. The
+ * L3 typing exposes `name`, `creator`, `baseState`, `on`, `off`, `intent`,
+ * `as`, `order`, `listMode`, `rbGroups`, `locked`.
+ *
+ * Unknown entries are preserved in `_extras`.
+ *
+ * @module pdf/ocg/config
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfOCConfig = {
+    name: 'pdfOCConfig',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const KNOWN = new Set([
+            'Name', 'Creator', 'BaseState', 'ON', 'OFF',
+            'Intent', 'AS', 'Order', 'ListMode', 'RBGroups', 'Locked'
+        ]);
+        const BASE_STATES = new Set(['ON', 'OFF', 'Unchanged']);
+
+        function refsOf(node, label) {
+            if (node.type !== 'array') {
+                throw new ParseError('pdf/ocg/config/bad-refs',
+                    '/' + label + ' must be an array of refs',
+                    { context: { type: node.type } });
+            }
+            return node.items.filter((r) => r && r.type === 'ref');
+        }
+
+        function typeUsageApp(d) {
+            if (!isType(d, 'dict')) {
+                throw new ParseError('pdf/ocg/config/as/not-dict',
+                    '/AS entry must be a dictionary',
+                    { context: { type: d && d.type } });
+            }
+            const e = d.entries;
+            const out = { raw: d };
+            if (e.Event && e.Event.type === 'name') out.event = e.Event.value;
+            if (e.OCGs  && e.OCGs.type  === 'array') {
+                out.ocgs = e.OCGs.items.filter((r) => r.type === 'ref');
+            }
+            if (e.Category && e.Category.type === 'array') {
+                out.category = e.Category.items
+                    .filter((c) => c.type === 'name').map((c) => c.value);
+            }
+            return out;
+        }
+
+        function typeOCConfig(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/ocg/config/not-dict',
+                    'OCConfig must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            const out = { raw: dict, _extras: {} };
+
+            if (e.Name) {
+                if (e.Name.type !== 'string') {
+                    throw new ParseError('pdf/ocg/config/bad-name',
+                        '/Name must be a string', { context: { type: e.Name.type } });
+                }
+                out.name = e.Name.value;
+            }
+            if (e.Creator) {
+                if (e.Creator.type !== 'string') {
+                    throw new ParseError('pdf/ocg/config/bad-creator',
+                        '/Creator must be a string', { context: { type: e.Creator.type } });
+                }
+                out.creator = e.Creator.value;
+            }
+            if (e.BaseState) {
+                if (e.BaseState.type !== 'name' || !BASE_STATES.has(e.BaseState.value)) {
+                    throw new ParseError('pdf/ocg/config/bad-base-state',
+                        '/BaseState must be ON|OFF|Unchanged',
+                        { context: { actual: e.BaseState.value } });
+                }
+                out.baseState = e.BaseState.value;
+            }
+            if (e.ON)  out.on  = refsOf(e.ON, 'ON');
+            if (e.OFF) out.off = refsOf(e.OFF, 'OFF');
+            if (e.Locked) out.locked = refsOf(e.Locked, 'Locked');
+
+            if (e.Intent) {
+                if (e.Intent.type === 'name') out.intent = [e.Intent.value];
+                else if (e.Intent.type === 'array') {
+                    out.intent = e.Intent.items
+                        .filter((x) => x && x.type === 'name')
+                        .map((x) => x.value);
+                } else {
+                    throw new ParseError('pdf/ocg/config/bad-intent',
+                        '/Intent must be name or array of names',
+                        { context: { type: e.Intent.type } });
+                }
+            }
+            if (e.AS) {
+                if (e.AS.type !== 'array') {
+                    throw new ParseError('pdf/ocg/config/bad-as',
+                        '/AS must be an array', { context: { type: e.AS.type } });
+                }
+                out.as = e.AS.items.map(typeUsageApp);
+            }
+            if (e.Order) {
+                if (e.Order.type !== 'array') {
+                    throw new ParseError('pdf/ocg/config/bad-order',
+                        '/Order must be an array', { context: { type: e.Order.type } });
+                }
+                out.order = e.Order.items;
+            }
+            if (e.ListMode) {
+                if (e.ListMode.type !== 'name') {
+                    throw new ParseError('pdf/ocg/config/bad-list-mode',
+                        '/ListMode must be a name',
+                        { context: { type: e.ListMode.type } });
+                }
+                out.listMode = e.ListMode.value;
+            }
+            if (e.RBGroups) {
+                if (e.RBGroups.type !== 'array') {
+                    throw new ParseError('pdf/ocg/config/bad-rb',
+                        '/RBGroups must be an array',
+                        { context: { type: e.RBGroups.type } });
+                }
+                out.rbGroups = e.RBGroups.items
+                    .filter((it) => it && it.type === 'array')
+                    .map((it) => it.items.filter((r) => r.type === 'ref'));
+            }
+
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        return { typeOCConfig, typeUsageApp };
+    }
+};

package/src/ocg/ocg.js

@@ -0,0 +1,124 @@
+// 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 Optional Content Group (OCG) typing per ISO 32000-2:2020
+ * §8.11.2.
+ *
+ * An OCG is a dictionary `/Type /OCG` referenced by content streams,
+ * annotations and form XObjects whose visibility can be toggled at view
+ * time. The L3 typing decodes `/Name`, `/Intent`, and the `/Usage`
+ * sub-dictionary (CreatorInfo, Language, Export, Zoom, Print, View,
+ * User, PageElement plus state convenience entries).
+ *
+ * Unknown entries are preserved in `_extras`.
+ *
+ * @module pdf/ocg/ocg
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfOCG = {
+    name: 'pdfOCG',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const KNOWN_TOP   = new Set(['Type', 'Name', 'Intent', 'Usage']);
+        const KNOWN_USAGE = new Set([
+            'CreatorInfo', 'Language', 'Export', 'Zoom', 'Print', 'View',
+            'User', 'PageElement', 'ViewState', 'PrintState', 'ExportState'
+        ]);
+
+        function lower(s) { return s.charAt(0).toLowerCase() + s.slice(1); }
+
+        function typeUsage(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/ocg/usage/not-dict',
+                    'Usage must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            const out = { raw: dict, _extras: {} };
+
+            for (const k of KNOWN_USAGE) {
+                if (e[k] !== undefined) {
+                    const v = e[k];
+                    if (k === 'PrintState' || k === 'ViewState' || k === 'ExportState') {
+                        if (v.type !== 'name') {
+                            throw new ParseError('pdf/ocg/usage/bad-state',
+                                '/' + k + ' must be a name',
+                                { context: { type: v.type } });
+                        }
+                        out[lower(k)] = v.value;
+                    } else {
+                        out[lower(k)] = v;
+                    }
+                }
+            }
+            for (const k of Object.keys(e)) {
+                if (!KNOWN_USAGE.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function typeOCG(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/ocg/not-dict',
+                    'OCG must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'OCG')) {
+                throw new ParseError('pdf/ocg/bad-type',
+                    '/Type entry must be /OCG',
+                    { context: { actual: e.Type.value } });
+            }
+            if (!e.Name || e.Name.type !== 'string') {
+                throw new ParseError('pdf/ocg/missing-name',
+                    'OCG is missing required /Name string',
+                    { context: { type: e.Name && e.Name.type } });
+            }
+
+            const out = {
+                name: e.Name.value,
+                raw: dict,
+                _extras: {}
+            };
+
+            if (e.Intent) {
+                if (e.Intent.type === 'name') {
+                    out.intent = [e.Intent.value];
+                } else if (e.Intent.type === 'array') {
+                    out.intent = e.Intent.items
+                        .filter((it) => it && it.type === 'name')
+                        .map((it) => it.value);
+                }
+            }
+
+            if (e.Usage) {
+                if (e.Usage.type !== 'dict') {
+                    throw new ParseError('pdf/ocg/bad-usage',
+                        '/Usage must be a dictionary',
+                        { context: { type: e.Usage.type } });
+                }
+                out.usage = typeUsage(e.Usage);
+            }
+
+            for (const k of Object.keys(e)) {
+                if (!KNOWN_TOP.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        return { typeOCG, typeUsage };
+    }
+};

package/src/outline/outline.js

@@ -0,0 +1,157 @@
+// 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 Outline (bookmarks) tree walker per ISO 32000-2:2020
+ * §12.3.3.
+ *
+ * The outline is a doubly-linked tree of `/Type /Outlines` (root) and
+ * outline items. Each item carries `/Title`, `/Parent`, `/Prev`, `/Next`,
+ * `/First`, `/Last`, `/Count`, `/A` (action), `/Dest`, `/C` (color, 3
+ * numbers), `/F` (style flags). `/SE` (structure element) is deprecated.
+ *
+ * `walkOutline(rootDict, resolveRef)` returns a flat depth-first list of
+ * typed records:
+ *   `{ ref, title, dest?, action?, count?, parent, prev, next, first,
+ *      last, color?, F?, _extras }`
+ *
+ * The caller resolves indirect refs; the walker enforces cycle
+ * detection and maxDepth, similarly to pageTree.
+ *
+ * @module pdf/outline/outline
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfOutline = {
+    name: 'pdfOutline',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const KNOWN = new Set([
+            'Title', 'Parent', 'Prev', 'Next', 'First', 'Last',
+            'Count', 'A', 'Dest', 'SE', 'C', 'F', 'Type'
+        ]);
+
+        function typeOutlineItem(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/outline/item/not-dict',
+                    'outline item must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (!e.Title || e.Title.type !== 'string') {
+                throw new ParseError('pdf/outline/missing-title',
+                    'outline item missing /Title string',
+                    { context: { type: e.Title && e.Title.type } });
+            }
+            const out = { title: e.Title.value, raw: dict, _extras: {} };
+            if (e.Parent && e.Parent.type === 'ref') out.parent = e.Parent;
+            if (e.Prev   && e.Prev.type   === 'ref') out.prev   = e.Prev;
+            if (e.Next   && e.Next.type   === 'ref') out.next   = e.Next;
+            if (e.First  && e.First.type  === 'ref') out.first  = e.First;
+            if (e.Last   && e.Last.type   === 'ref') out.last   = e.Last;
+            if (e.Count  && (e.Count.type === 'int' || e.Count.type === 'real')) {
+                out.count = e.Count.value | 0;
+            }
+            if (e.A)    out.action = e.A;
+            if (e.Dest) out.dest   = e.Dest;
+            if (e.C && e.C.type === 'array') {
+                const c = e.C.items.filter((x) => x.type === 'int' || x.type === 'real')
+                    .map((x) => x.value);
+                if (c.length === 3) out.color = c;
+            }
+            if (e.F && (e.F.type === 'int' || e.F.type === 'real')) {
+                out.F = e.F.value | 0;
+            }
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function walkOutline(rootDict, resolveRef, opts) {
+            if (!isType(rootDict, 'dict')) {
+                throw new ParseError('pdf/outline/not-dict',
+                    'outline root must be a dictionary',
+                    { context: { type: rootDict && rootDict.type } });
+            }
+            const maxDepth = (opts && opts.maxDepth) || 64;
+            const maxItems = (opts && opts.maxItems) || 100000;
+            const out = [];
+            const visited = new Set();
+            const first = rootDict.entries.First;
+            if (!first) return out;
+            if (first.type !== 'ref') {
+                throw new ParseError('pdf/outline/bad-first',
+                    '/First must be an indirect reference',
+                    { context: { type: first.type } });
+            }
+            if (typeof resolveRef !== 'function') {
+                throw new ParseError('pdf/outline/no-resolver',
+                    'walkOutline requires a resolveRef function');
+            }
+
+            function walkSiblings(ref, depth) {
+                if (depth > maxDepth) {
+                    throw new ParseError('pdf/outline/max-depth',
+                        'outline depth limit exceeded',
+                        { context: { depth, maxDepth } });
+                }
+                let cur = ref;
+                let guard = 0;
+                while (cur) {
+                    if (cur.type !== 'ref') {
+                        throw new ParseError('pdf/outline/non-ref-sibling',
+                            'outline sibling must be an indirect ref',
+                            { context: { kind: cur.type } });
+                    }
+                    const key = cur.num + ':' + cur.gen;
+                    if (visited.has(key)) {
+                        throw new ParseError('pdf/outline/cycle',
+                            'cycle detected in outline siblings',
+                            { context: { ref: cur } });
+                    }
+                    visited.add(key);
+
+                    const node = resolveRef(cur);
+                    if (!isType(node, 'dict')) {
+                        throw new ParseError('pdf/outline/not-dict',
+                            'outline item must be a dictionary',
+                            { context: { ref: cur } });
+                    }
+                    const rec = typeOutlineItem(node);
+                    rec.ref = { num: cur.num, gen: cur.gen };
+                    out.push(rec);
+                    if (out.length > maxItems) {
+                        throw new ParseError('pdf/outline/too-many',
+                            'outline item limit exceeded',
+                            { context: { maxItems } });
+                    }
+
+                    if (rec.first) walkSiblings(rec.first, depth + 1);
+
+                    cur = rec.next || null;
+                    if (++guard > maxItems) {
+                        throw new ParseError('pdf/outline/runaway',
+                            'outline sibling chain exceeded item cap');
+                    }
+                }
+            }
+
+            walkSiblings(first, 0);
+            return out;
+        }
+
+        return { walkOutline, typeOutlineItem };
+    }
+};

package/src/pdf.js

@@ -0,0 +1,133 @@
+// 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 Top-level `@awacloud/pdf` orchestrator — public entry-point
+ * factory that binds the syntax + document layer modules into an
+ * ergonomic read/write API exposing `.use(...)` extensions.
+ *
+ * Strict factory-only descriptor — same pattern as
+ * `@awacloud/ooxml/src/docx/docx.js`. All dependencies are declared in
+ * `dependencies[]` and received as parameters ; no top-level `import`,
+ * no internal bootstrap.
+ *
+ * Resolution path : register the four arrays of `src/main.js` into a
+ * `@awacloud/fw` `ModuleRuntime` and call `runtime.resolve('pdf')`. Tests
+ * materialise via the helper `tests/_helpers/build.js` `bootstrapPdf()`.
+ *
+ * Extension hook — `.use(extension)` is idempotent on `extension.name`.
+ *
+ * @module pdf/pdf
+ */
+
+import { pdfErrors } from './errors.js';
+import { pdfShared } from './_shared/index.js';
+import { pdfTokenizer } from './syntax/tokenizer.js';
+import { pdfParserObj } from './syntax/parser-obj.js';
+import { pdfParser } from './syntax/parser.js';
+import { pdfXref } from './syntax/xref.js';
+import { pdfTrailer } from './syntax/trailer.js';
+import { pdfSerializer } from './syntax/serializer.js';
+import { pdfCatalog } from './document/catalog.js';
+import { pdfPages } from './document/pages.js';
+import { pdfPage } from './document/page.js';
+import { pdfDocument } from './document/document.js';
+import { pdfWriter } from './document/writer.js';
+
+export const pdf = {
+    name: 'pdf',
+    dependencies: [
+        'pdfErrors', 'pdfShared',
+        'pdfTokenizer', 'pdfParserObj', 'pdfParser',
+        'pdfXref', 'pdfTrailer', 'pdfSerializer',
+        'pdfCatalog', 'pdfPages', 'pdfPage',
+        'pdfDocument', 'pdfWriter'
+    ],
+    deps: [pdfErrors, pdfShared, pdfTokenizer, pdfParserObj, pdfParser, pdfXref, pdfTrailer, pdfSerializer, pdfCatalog, pdfPages, pdfPage, pdfDocument, pdfWriter],
+
+    factory(errors, shared, tokenizer, parserObj, parser,
+            xref, trailer, serializer,
+            catalog, pages, page,
+            docMod, writerMod) {
+        const { ContractError } = errors;
+
+        const readDocument      = docMod.readDocument;
+        const readHeader        = docMod.readHeader;
+        const writeDocument     = writerMod.writeDocument;
+        const assembleIndirects = writerMod.assembleIndirects;
+
+        const usedExtensions = new Set();
+        const api = {
+            read(bytes, opts) { return readDocument(bytes, opts); },
+            header(bytes) { return readHeader(bytes); },
+            /**
+             * Serialize a document model back to bytes.
+             *
+             * For a `read()` Document, `opts.strict === true` (strictly `true`,
+             * a truthy non-boolean is NOT strict) throws
+             * `pdf/writer/unresolvable-objects` instead of silently dropping
+             * an in-use xref entry that cannot be resolved. In lenient mode
+             * the dropped entries are listed on the result's non-enumerable
+             * `skippedObjects` property and handed once to `opts.onSkipped`
+             * (a copy of the list) when it is non-empty. A WriteModel carries
+             * no resolvable xref, so `opts` is ignored for it.
+             *
+             * @param {object} model  A `read()` Document or a raw WriteModel.
+             * @param {{ strict?: boolean, onSkipped?: (skipped: Array<{num:number, gen:number, code:string}>) => void }} [opts]
+             * @returns {Uint8Array} bytes; non-enumerable `skippedObjects` (always an
+             *   array, `[]` for a WriteModel or a clean Document).
+             */
+            write(model, opts) {
+                const o = opts && typeof opts === 'object' ? opts : {};
+                let skipped = [];
+                let bytes;
+                if (model && model._raw && typeof model._raw.resolve === 'function') {
+                    const indirects = assembleIndirects(model, o.strict === true ? { strict: true } : undefined);
+                    skipped = indirects.skippedObjects || [];
+                    bytes = writeDocument({
+                        indirects,
+                        root: model.catalog.pages
+                            ? { num: model.trailer.root.num, gen: model.trailer.root.gen }
+                            : model.trailer.root,
+                        info: model.trailer.info,
+                        id:   model.trailer.id,
+                        version: '2.0'
+                    });
+                } else {
+                    bytes = writeDocument(model);
+                }
+                if (skipped.length > 0 && typeof o.onSkipped === 'function') o.onSkipped(skipped.slice());
+                Object.defineProperty(bytes, 'skippedObjects', {
+                    value: skipped, enumerable: false, writable: true, configurable: true
+                });
+                return bytes;
+            },
+            use(ext) {
+                if (!ext || typeof ext.name !== 'string' || typeof ext.register !== 'function') {
+                    throw new ContractError('pdf/use/bad-extension',
+                        '.use() requires { name: string, register: function }',
+                        { context: { keys: ext && Object.keys(ext) } });
+                }
+                if (usedExtensions.has(ext.name)) return api;
+                usedExtensions.add(ext.name);
+                const next = ext.register(api, { usedExtensions });
+                if (next && typeof next === 'object') {
+                    for (const k of Object.keys(next)) {
+                        if (k !== 'use') api[k] = next[k];
+                    }
+                }
+                return api;
+            },
+            usedExtension(name) { return usedExtensions.has(name); }
+        };
+
+        // Touch unused but declared deps so the runtime warns on mis-wiring.
+        void shared; void tokenizer; void parserObj; void parser;
+        void xref; void trailer; void serializer;
+        void catalog; void pages; void page;
+
+        return api;
+    }
+};