@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/bundles/pdf-large.js

@@ -0,0 +1,81 @@
+// 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 `@awacloud/pdf/bundles/pdf-large` — extended PDF coverage bundle.
+ *
+ * Pure fw factory descriptor. Declares the core `pdf` orchestrator and
+ * the P0+P1 opt-in extras as dependencies. The runtime resolves every
+ * dependency transitively and passes the already-constructed instances
+ * to the factory, which wires them into the `pdf` core via `pdf.use(...)`
+ * and returns the enriched instance.
+ *
+ * Consumption is exclusively declarative — register the descriptor in a
+ * `ModuleRuntime` and call `runtime.resolve('pdfLargeBundle')`.
+ *
+ * For 100% PDF 2.0 strict coverage (adds P2 phases + misc + deprecated
+ * info dict), use `pdf-full`. For PDF 1.7 read + 1.7→2.0 conversion,
+ * use `pdf-legacy`.
+ *
+ * @module pdf/bundles/pdf-large
+ */
+
+import { pdf } from '../pdf.js';
+import { pdfContentOpsExtended } from '../extra/content-ops-extended.js';
+import { pdfFontCidTyped } from '../extra/font-cid-typed.js';
+import { pdfFontColorTagging } from '../extra/font-color-tagging.js';
+import { pdfTaggedPdfTyped } from '../extra/tagged-pdf-typed.js';
+import { pdfAnnotExtended } from '../extra/annot-extended.js';
+import { pdfAOutputIntent } from '../extra/pdf-a-output-intent.js';
+import { pdfUaTagged } from '../extra/pdf-ua-tagged.js';
+import { pdfFormActionsExtended } from '../extra/form-actions-extended.js';
+import { pdfColorSpacesExtended } from '../extra/color-spaces-extended.js';
+import { pdfShadingTyped } from '../extra/shading-typed.js';
+import { pdfTransparencyTyped } from '../extra/transparency-typed.js';
+import { pdfSigPades } from '../extra/sig-pades.js';
+import { pdfSigAesGcm } from '../extra/sig-aes-gcm.js';
+import { pdfDocumentParts } from '../extra/document-parts.js';
+import { pdfRedactionIso32005 } from '../extra/redaction-iso32005.js';
+import { pdfXPrepress } from '../extra/pdf-x-prepress.js';
+import { pdfWellTagged } from '../extra/well-tagged-pdf.js';
+import { pdfOptionalContentExtended } from '../extra/optional-content-extended.js';
+import { pdfEmbeddedFilesPortfolio } from '../extra/embedded-files-portfolio.js';
+import { pdfAssociatedFiles2 } from '../extra/associated-files.js';
+import { pdfXmpExtended } from '../extra/xmp-extended.js';
+
+export const pdfLargeBundle = {
+    name: 'pdfLargeBundle',
+    dependencies: [
+        'pdf',
+        'pdfContentOpsExtended', 'pdfFontCidTyped', 'pdfFontColorTagging',
+        'pdfTaggedPdfTyped', 'pdfAnnotExtended', 'pdfAOutputIntent', 'pdfUaTagged',
+        'pdfFormActionsExtended', 'pdfColorSpacesExtended', 'pdfShadingTyped',
+        'pdfTransparencyTyped', 'pdfSigPades', 'pdfSigAesGcm', 'pdfDocumentParts',
+        'pdfRedactionIso32005', 'pdfXPrepress', 'pdfWellTagged',
+        'pdfOptionalContentExtended', 'pdfEmbeddedFilesPortfolio',
+        'pdfAssociatedFiles2', 'pdfXmpExtended'
+    ],
+    deps: [pdf, pdfContentOpsExtended, pdfFontCidTyped, pdfFontColorTagging, pdfTaggedPdfTyped, pdfAnnotExtended, pdfAOutputIntent, pdfUaTagged, pdfFormActionsExtended, pdfColorSpacesExtended, pdfShadingTyped, pdfTransparencyTyped, pdfSigPades, pdfSigAesGcm, pdfDocumentParts, pdfRedactionIso32005, pdfXPrepress, pdfWellTagged, pdfOptionalContentExtended, pdfEmbeddedFilesPortfolio, pdfAssociatedFiles2, pdfXmpExtended],
+    factory(pdf, ...instances) {
+        const names = [
+            'pdfContentOpsExtended', 'pdfFontCidTyped', 'pdfFontColorTagging',
+            'pdfTaggedPdfTyped', 'pdfAnnotExtended', 'pdfAOutputIntent', 'pdfUaTagged',
+            'pdfFormActionsExtended', 'pdfColorSpacesExtended', 'pdfShadingTyped',
+            'pdfTransparencyTyped', 'pdfSigPades', 'pdfSigAesGcm', 'pdfDocumentParts',
+            'pdfRedactionIso32005', 'pdfXPrepress', 'pdfWellTagged',
+            'pdfOptionalContentExtended', 'pdfEmbeddedFilesPortfolio',
+            'pdfAssociatedFiles2', 'pdfXmpExtended'
+        ];
+        for (let i = 0; i < names.length; i++) {
+            const name = names[i];
+            const inst = instances[i];
+            pdf.use({
+                name,
+                register() { return { [name]: inst }; }
+            });
+        }
+        return pdf;
+    }
+};

package/src/bundles/pdf-legacy.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 `@awacloud/pdf/bundles/pdf-legacy` — full + PDF 1.7 legacy read.
+ *
+ * Pure fw factory descriptor. Declares the core `pdf` orchestrator,
+ * every PDF 2.0 strict extra, and the
+ * `legacy-*` extras as dependencies. The runtime resolves every
+ * dependency transitively and passes the already-constructed instances
+ * to the factory, which wires them into the `pdf` core via
+ * `pdf.use(...)` and returns the enriched instance.
+ *
+ * Consumption is exclusively declarative — register the descriptor in a
+ * `ModuleRuntime` and call `runtime.resolve('pdfLegacyBundle')`.
+ *
+ * Adds the `legacy-*` extras on top of `pdf-full`:
+ *
+ * - `legacy-xfa-read` — accepts /XFA on read, surfaces as opaque XML.
+ * - `legacy-rc4-read` — RC4 v2/v3 password validation + stream decrypt.
+ * - `legacy-deprecated-filters` — LZWDecode (via fw) + CCITTFax + DCT/JPX passthrough.
+ * - `legacy-deprecated-annots` — full Sound/Movie/Screen typing.
+ * - `info-dict-deprecated` — Info dict lint (deprecated PDF 2.0).
+ *
+ * Write never converts: `pdf.write` emits a `%PDF-2.0` header and `pdfWriter`
+ * re-emits the model's objects as they were read, legacy content included.
+ *
+ * @module pdf/bundles/pdf-legacy
+ */
+
+import { pdf } from '../pdf.js';
+import { pdfContentOpsExtended } from '../extra/content-ops-extended.js';
+import { pdfFontCidTyped } from '../extra/font-cid-typed.js';
+import { pdfFontColorTagging } from '../extra/font-color-tagging.js';
+import { pdfTaggedPdfTyped } from '../extra/tagged-pdf-typed.js';
+import { pdfAnnotExtended } from '../extra/annot-extended.js';
+import { pdfAOutputIntent } from '../extra/pdf-a-output-intent.js';
+import { pdfUaTagged } from '../extra/pdf-ua-tagged.js';
+import { pdfFormActionsExtended } from '../extra/form-actions-extended.js';
+import { pdfColorSpacesExtended } from '../extra/color-spaces-extended.js';
+import { pdfShadingTyped } from '../extra/shading-typed.js';
+import { pdfTransparencyTyped } from '../extra/transparency-typed.js';
+import { pdfSigPades } from '../extra/sig-pades.js';
+import { pdfSigAesGcm } from '../extra/sig-aes-gcm.js';
+import { pdfDocumentParts } from '../extra/document-parts.js';
+import { pdfRedactionIso32005 } from '../extra/redaction-iso32005.js';
+import { pdfXPrepress } from '../extra/pdf-x-prepress.js';
+import { pdfWellTagged } from '../extra/well-tagged-pdf.js';
+import { pdfOptionalContentExtended } from '../extra/optional-content-extended.js';
+import { pdfEmbeddedFilesPortfolio } from '../extra/embedded-files-portfolio.js';
+import { pdfAssociatedFiles2 } from '../extra/associated-files.js';
+import { pdfXmpExtended } from '../extra/xmp-extended.js';
+import { pdfLinearizationWrite } from '../extra/linearization-write.js';
+import { pdf3dRichMedia } from '../extra/3d-richmedia.js';
+import { pdfJbig2Read } from '../extra/jbig2-read.js';
+import { pdfMisc } from '../extra/misc.js';
+import { pdfInfoDictDeprecated } from '../extra/info-dict-deprecated.js';
+import { pdfSandbox } from '../extra/pdf-sandbox.js';
+import { pdfLegacyXfaRead } from '../extra/legacy-xfa-read.js';
+import { pdfLegacyRc4Read } from '../extra/legacy-rc4-read.js';
+import { pdfLegacyDeprecatedFilters } from '../extra/legacy-deprecated-filters.js';
+import { pdfLegacyDeprecatedAnnots } from '../extra/legacy-deprecated-annots.js';
+
+export const pdfLegacyBundle = {
+    name: 'pdfLegacyBundle',
+    dependencies: [
+        'pdf',
+        'pdfContentOpsExtended', 'pdfFontCidTyped', 'pdfFontColorTagging',
+        'pdfTaggedPdfTyped', 'pdfAnnotExtended', 'pdfAOutputIntent', 'pdfUaTagged',
+        'pdfFormActionsExtended', 'pdfColorSpacesExtended', 'pdfShadingTyped',
+        'pdfTransparencyTyped', 'pdfSigPades', 'pdfSigAesGcm', 'pdfDocumentParts',
+        'pdfRedactionIso32005', 'pdfXPrepress', 'pdfWellTagged',
+        'pdfOptionalContentExtended', 'pdfEmbeddedFilesPortfolio',
+        'pdfAssociatedFiles2', 'pdfXmpExtended',
+        'pdfLinearizationWrite', 'pdf3dRichMedia', 'pdfJbig2Read', 'pdfMisc',
+        'pdfInfoDictDeprecated', 'pdfSandbox',
+        'pdfLegacyXfaRead', 'pdfLegacyRc4Read', 'pdfLegacyDeprecatedFilters',
+        'pdfLegacyDeprecatedAnnots'
+    ],
+    deps: [pdf, pdfContentOpsExtended, pdfFontCidTyped, pdfFontColorTagging, pdfTaggedPdfTyped, pdfAnnotExtended, pdfAOutputIntent, pdfUaTagged, pdfFormActionsExtended, pdfColorSpacesExtended, pdfShadingTyped, pdfTransparencyTyped, pdfSigPades, pdfSigAesGcm, pdfDocumentParts, pdfRedactionIso32005, pdfXPrepress, pdfWellTagged, pdfOptionalContentExtended, pdfEmbeddedFilesPortfolio, pdfAssociatedFiles2, pdfXmpExtended, pdfLinearizationWrite, pdf3dRichMedia, pdfJbig2Read, pdfMisc, pdfInfoDictDeprecated, pdfSandbox, pdfLegacyXfaRead, pdfLegacyRc4Read, pdfLegacyDeprecatedFilters, pdfLegacyDeprecatedAnnots],
+    factory(pdf, ...instances) {
+        const names = [
+            'pdfContentOpsExtended', 'pdfFontCidTyped', 'pdfFontColorTagging',
+            'pdfTaggedPdfTyped', 'pdfAnnotExtended', 'pdfAOutputIntent', 'pdfUaTagged',
+            'pdfFormActionsExtended', 'pdfColorSpacesExtended', 'pdfShadingTyped',
+            'pdfTransparencyTyped', 'pdfSigPades', 'pdfSigAesGcm', 'pdfDocumentParts',
+            'pdfRedactionIso32005', 'pdfXPrepress', 'pdfWellTagged',
+            'pdfOptionalContentExtended', 'pdfEmbeddedFilesPortfolio',
+            'pdfAssociatedFiles2', 'pdfXmpExtended',
+            'pdfLinearizationWrite', 'pdf3dRichMedia', 'pdfJbig2Read', 'pdfMisc',
+            'pdfInfoDictDeprecated', 'pdfSandbox',
+            'pdfLegacyXfaRead', 'pdfLegacyRc4Read', 'pdfLegacyDeprecatedFilters',
+            'pdfLegacyDeprecatedAnnots'
+        ];
+        for (let i = 0; i < names.length; i++) {
+            const name = names[i];
+            const inst = instances[i];
+            pdf.use({
+                name,
+                register() { return { [name]: inst }; }
+            });
+        }
+        return pdf;
+    }
+};

package/src/content/color.js

@@ -0,0 +1,114 @@
+// 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 Color operators + DeviceGray/RGB/CMYK helpers per
+ * ISO 32000-2:2020 §8.6.
+ *
+ * Applies `g`/`G`/`rg`/`RG`/`k`/`K`/`cs`/`CS`/`sc`/`SC`/`scn`/`SCN`
+ * operators to the graphics state. Returns the typed color record
+ * `{ space: string, components: number[] }`.
+ *
+ * Patterns and Separation/DeviceN spaces accept a trailing `/PatternName`
+ * argument via `scn`/`SCN` — captured in the record as
+ * `{ space, components, pattern? }`.
+ *
+ * @module pdf/content/color
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+
+export const pdfColor = {
+    name: 'pdfColor',
+    dependencies: ['pdfErrors'],
+    deps: [pdfErrors],
+    factory(errors) {
+        const { ContractError } = errors;
+
+        function nameArg(args, i) {
+            const a = args[i];
+            if (!a || a.type !== 'name') {
+                throw new ContractError('pdf/color/bad-name',
+                    `expected name arg at position ${i}`,
+                    { context: { index: i, kind: a && a.type } });
+            }
+            return a.value;
+        }
+
+        function nums(args, n) {
+            if (args.length < n) {
+                throw new ContractError('pdf/color/short-args',
+                    `expected ${n} numeric args, got ${args.length}`);
+            }
+            const out = new Array(n);
+            for (let i = 0; i < n; i++) {
+                const a = args[i];
+                if (!a || (a.type !== 'int' && a.type !== 'real')) {
+                    throw new ContractError('pdf/color/bad-num',
+                        `arg ${i} is not numeric`,
+                        { context: { index: i, kind: a && a.type } });
+                }
+                out[i] = a.value;
+            }
+            return out;
+        }
+
+        function numArgs(args) {
+            return args
+                .filter(a => a && (a.type === 'int' || a.type === 'real'))
+                .map(a => a.value);
+        }
+
+        function deviceDefault(spaceName) {
+            if (spaceName === 'DeviceGray') return [0];
+            if (spaceName === 'DeviceRGB')  return [0, 0, 0];
+            if (spaceName === 'DeviceCMYK') return [0, 0, 0, 1];
+            return [];
+        }
+
+        function applyScn(gstate, slot, args) {
+            if (args.length === 0) return;
+            const last = args[args.length - 1];
+            if (last && last.type === 'name') {
+                gstate[slot].components = numArgs(args.slice(0, -1));
+                gstate[slot].pattern    = last.value;
+            } else {
+                gstate[slot].components = numArgs(args);
+                delete gstate[slot].pattern;
+            }
+        }
+
+        /**
+         * Apply a color operator to a gstate.
+         *
+         * @param {object} gstate
+         * @param {{ op: string, args: object[] }} ops
+         */
+        function applyColorOp(gstate, ops) {
+            switch (ops.op) {
+                case 'g':   gstate.fillColor   = { space: 'DeviceGray', components: nums(ops.args, 1) }; break;
+                case 'G':   gstate.strokeColor = { space: 'DeviceGray', components: nums(ops.args, 1) }; break;
+                case 'rg':  gstate.fillColor   = { space: 'DeviceRGB',  components: nums(ops.args, 3) }; break;
+                case 'RG':  gstate.strokeColor = { space: 'DeviceRGB',  components: nums(ops.args, 3) }; break;
+                case 'k':   gstate.fillColor   = { space: 'DeviceCMYK', components: nums(ops.args, 4) }; break;
+                case 'K':   gstate.strokeColor = { space: 'DeviceCMYK', components: nums(ops.args, 4) }; break;
+                case 'cs':  gstate.fillColor   = { space: nameArg(ops.args, 0), components: deviceDefault(nameArg(ops.args, 0)) }; break;
+                case 'CS':  gstate.strokeColor = { space: nameArg(ops.args, 0), components: deviceDefault(nameArg(ops.args, 0)) }; break;
+                case 'sc':  gstate.fillColor.components   = numArgs(ops.args); break;
+                case 'SC':  gstate.strokeColor.components = numArgs(ops.args); break;
+                case 'scn': applyScn(gstate, 'fillColor', ops.args); break;
+                case 'SCN': applyScn(gstate, 'strokeColor', ops.args); break;
+                default:
+                    throw new ContractError('pdf/color/unknown-op',
+                        `applyColorOp called with non-color op "${ops.op}"`);
+            }
+        }
+
+        return { applyColorOp };
+    }
+};

package/src/content/graphics.js

@@ -0,0 +1,192 @@
+// 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 Graphics state stack per ISO 32000-2:2020 §8.4.
+ *
+ * Implements a saveable / restorable state for a content-stream
+ * interpreter. The set of state parameters covered here is the
+ * **device-independent** subset (§8.4.1, Table 53) that L2 needs:
+ *
+ * - CTM (current transformation matrix, 2x3 affine)
+ * - line width, cap, join, miter limit, dash pattern
+ * - rendering intent, flatness tolerance
+ * - text state nested via `text.js`
+ * - color state (stroking + non-stroking) — see `color.js`
+ *
+ * Output is **not** a renderer; it is a faithful model of the
+ * `gstate` chain that downstream layers (tagged-PDF MCID tracking,
+ * text extraction, redaction) consume.
+ *
+ * @module pdf/content/graphics
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+
+export const pdfGraphics = {
+    name: 'pdfGraphics',
+    dependencies: ['pdfErrors'],
+    deps: [pdfErrors],
+    factory(errors) {
+        const { ContractError } = errors;
+
+        /**
+         * Construct an identity initial graphics state.
+         */
+        function initialGState() {
+            return {
+                ctm: [1, 0, 0, 1, 0, 0],
+                lineWidth: 1.0,
+                lineCap: 0,        // butt
+                lineJoin: 0,       // miter
+                miterLimit: 10.0,
+                dash: { array: [], phase: 0 },
+                renderingIntent: 'RelativeColorimetric',
+                flatness: 1.0,
+                text: {
+                    charSpace: 0,
+                    wordSpace: 0,
+                    scale: 100,
+                    leading: 0,
+                    font: null,
+                    fontSize: 0,
+                    renderMode: 0,
+                    rise: 0
+                },
+                strokeColor: { space: 'DeviceGray', components: [0] },
+                fillColor:   { space: 'DeviceGray', components: [0] }
+            };
+        }
+
+        /**
+         * Multiply two 2x3 affine matrices (PDF row-vector convention).
+         */
+        function mulCtm(a, b) {
+            return [
+                a[0] * b[0] + a[1] * b[2],
+                a[0] * b[1] + a[1] * b[3],
+                a[2] * b[0] + a[3] * b[2],
+                a[2] * b[1] + a[3] * b[3],
+                a[4] * b[0] + a[5] * b[2] + b[4],
+                a[4] * b[1] + a[5] * b[3] + b[5]
+            ];
+        }
+
+        // Closure-based stack constructor — avoids `this.` references so
+        // `factory.toString()` stays transportable across the worker
+        // boundary (integration test contract). Returned objects support
+        // `instanceof GStateStack` via the shared prototype path.
+        function GStateStack() {
+            const stack = [initialGState()];
+            const api = Object.create(GStateStack.prototype);
+            api.current = function () { return stack[stack.length - 1]; };
+            api.save = function () {
+                const cur = stack[stack.length - 1];
+                stack.push({
+                    ...cur,
+                    ctm: cur.ctm.slice(),
+                    dash: { array: cur.dash.array.slice(), phase: cur.dash.phase },
+                    text: { ...cur.text },
+                    strokeColor: { space: cur.strokeColor.space, components: cur.strokeColor.components.slice() },
+                    fillColor:   { space: cur.fillColor.space,   components: cur.fillColor.components.slice() }
+                });
+            };
+            api.restore = function () {
+                if (stack.length <= 1) {
+                    throw new ContractError('pdf/gstate/unbalanced-Q',
+                        'Q without matching q');
+                }
+                stack.pop();
+            };
+            api.depth = function () { return stack.length; };
+            api.concatCtm = function (matrix) {
+                if (!Array.isArray(matrix) || matrix.length !== 6) {
+                    throw new ContractError('pdf/gstate/bad-cm',
+                        'cm matrix must have 6 elements');
+                }
+                const cur = stack[stack.length - 1];
+                cur.ctm = mulCtm(matrix, cur.ctm);
+            };
+            return api;
+        }
+
+        function numArg(args, i) {
+            const a = args[i];
+            if (!a || (a.type !== 'int' && a.type !== 'real')) {
+                throw new ContractError('pdf/gstate/bad-arg-type',
+                    `expected numeric argument at position ${i}`,
+                    { context: { index: i, kind: a && a.type } });
+            }
+            return a.value;
+        }
+
+        function numArgs(args, n) {
+            const out = new Array(n);
+            for (let i = 0; i < n; i++) out[i] = numArg(args, i);
+            return out;
+        }
+
+        function nameArg(args, i) {
+            const a = args[i];
+            if (!a || a.type !== 'name') {
+                throw new ContractError('pdf/gstate/bad-name-arg',
+                    `expected name argument at position ${i}`,
+                    { context: { index: i, kind: a && a.type } });
+            }
+            return a.value;
+        }
+
+        function arrArg(args, i) {
+            const a = args[i];
+            if (!a || a.type !== 'array') return [];
+            return a.items
+                .filter(x => x.type === 'int' || x.type === 'real')
+                .map(x => x.value);
+        }
+
+        /**
+         * Apply an op + args pair to a `GStateStack` instance.
+         */
+        function applyOp(stack, ops, handlers) {
+            const cur = stack.current();
+            switch (ops.op) {
+                case 'q':  stack.save(); break;
+                case 'Q':  stack.restore(); break;
+                case 'cm':
+                    stack.concatCtm(numArgs(ops.args, 6));
+                    break;
+                case 'w':  cur.lineWidth = numArg(ops.args, 0); break;
+                case 'J':  cur.lineCap   = numArg(ops.args, 0) | 0; break;
+                case 'j':  cur.lineJoin  = numArg(ops.args, 0) | 0; break;
+                case 'M':  cur.miterLimit = numArg(ops.args, 0); break;
+                case 'd':
+                    cur.dash = {
+                        array: arrArg(ops.args, 0),
+                        phase: numArg(ops.args, 1)
+                    };
+                    break;
+                case 'ri': cur.renderingIntent = nameArg(ops.args, 0); break;
+                case 'i':  cur.flatness = numArg(ops.args, 0); break;
+                default:
+                    if (handlers && typeof handlers.unhandled === 'function') {
+                        handlers.unhandled(ops, stack);
+                    }
+            }
+        }
+
+        function createStack() { return new GStateStack(); }
+
+        return {
+            GStateStack,
+            createStack,
+            applyOp,
+            initialGState,
+            mulCtm
+        };
+    }
+};

package/src/content/images.js

@@ -0,0 +1,160 @@
+// 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 Image XObject + Form XObject typing per
+ * ISO 32000-2:2020 §8.9.
+ *
+ * Image XObject (`/Subtype /Image`) carries Width, Height, ColorSpace,
+ * BitsPerComponent, Filter, DecodeParms, Decode, ImageMask, Mask,
+ * SMask, Interpolate, Intent, Metadata, OC.
+ *
+ * Form XObject (`/Subtype /Form`) carries FormType, BBox, Matrix,
+ * Resources, Group, Ref, Metadata, PieceInfo, LastModified,
+ * StructParent(s), OPI, OC, Name (deprecated).
+ *
+ * Both are streams whose raw bytes pass through unchanged at L2 ; the
+ * caller (renderer) decodes `Filter` on demand via
+ * `pdfFilterDispatch`.
+ *
+ * @module pdf/content/images
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfImages = {
+    name: 'pdfImages',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parserMod) {
+        const { ParseError } = errors;
+        const isType = (parserMod && parserMod.isType)
+            || ((v, kind) => !!(v && v.type === kind));
+
+        function intOrZero(entry, label) {
+            if (!entry || entry.type !== 'int') {
+                if (label === 'Width' || label === 'Height') {
+                    throw new ParseError('pdf/image/missing-dim',
+                        `Image XObject missing required /${label}`);
+                }
+                return 0;
+            }
+            return entry.value;
+        }
+
+        function toBox(v) {
+            if (!v || v.type !== 'array' || v.items.length !== 4) return null;
+            const r = new Array(4);
+            for (let i = 0; i < 4; i++) {
+                const it = v.items[i];
+                if (!it || (it.type !== 'int' && it.type !== 'real')) return null;
+                r[i] = it.value;
+            }
+            return r;
+        }
+
+        function toMatrix(v) {
+            if (!v || v.type !== 'array' || v.items.length !== 6) {
+                return [1, 0, 0, 1, 0, 0];
+            }
+            const r = new Array(6);
+            for (let i = 0; i < 6; i++) {
+                const it = v.items[i];
+                if (!it || (it.type !== 'int' && it.type !== 'real')) {
+                    return [1, 0, 0, 1, 0, 0];
+                }
+                r[i] = it.value;
+            }
+            return r;
+        }
+
+        function typeImageXObject(stream) {
+            if (!isType(stream, 'stream')) {
+                throw new ParseError('pdf/image/not-stream',
+                    'Image XObject must be a stream object');
+            }
+            const e = stream.dict.entries;
+            if (e.Subtype && (e.Subtype.type !== 'name' || e.Subtype.value !== 'Image')) {
+                throw new ParseError('pdf/image/wrong-subtype',
+                    'Image XObject /Subtype must be /Image',
+                    { context: { actual: e.Subtype.value } });
+            }
+            return {
+                kind: 'image',
+                width:  intOrZero(e.Width, 'Width'),
+                height: intOrZero(e.Height, 'Height'),
+                bitsPerComponent: e.BitsPerComponent && e.BitsPerComponent.type === 'int'
+                    ? e.BitsPerComponent.value : null,
+                colorSpace: e.ColorSpace || null,
+                filter:     e.Filter || null,
+                decodeParms: e.DecodeParms || null,
+                decode:     e.Decode || null,
+                imageMask:  e.ImageMask && e.ImageMask.type === 'bool' ? e.ImageMask.value : false,
+                mask:       e.Mask  || null,
+                sMask:      e.SMask || null,
+                interpolate: e.Interpolate && e.Interpolate.type === 'bool' ? e.Interpolate.value : false,
+                intent:     e.Intent && e.Intent.type === 'name' ? e.Intent.value : null,
+                metadata:   e.Metadata || null,
+                raw:        stream.raw,
+                dict:       stream.dict
+            };
+        }
+
+        function typeFormXObject(stream) {
+            if (!isType(stream, 'stream')) {
+                throw new ParseError('pdf/form-xobj/not-stream',
+                    'Form XObject must be a stream object');
+            }
+            const e = stream.dict.entries;
+            if (e.Subtype && (e.Subtype.type !== 'name' || e.Subtype.value !== 'Form')) {
+                throw new ParseError('pdf/form-xobj/wrong-subtype',
+                    'Form XObject /Subtype must be /Form',
+                    { context: { actual: e.Subtype.value } });
+            }
+            return {
+                kind: 'form',
+                formType: e.FormType && e.FormType.type === 'int' ? e.FormType.value : 1,
+                bbox:     toBox(e.BBox),
+                matrix:   toMatrix(e.Matrix),
+                resources: e.Resources || null,
+                group:    e.Group  || null,
+                metadata: e.Metadata || null,
+                structParents:  e.StructParents && e.StructParents.type === 'int'
+                    ? e.StructParents.value : null,
+                structParent:   e.StructParent && e.StructParent.type === 'int'
+                    ? e.StructParent.value : null,
+                raw:      stream.raw,
+                dict:     stream.dict
+            };
+        }
+
+        function typeXObject(stream) {
+            if (!isType(stream, 'stream')) {
+                throw new ParseError('pdf/xobject/not-stream',
+                    'XObject must be a stream object');
+            }
+            const t = stream.dict.entries.Type;
+            if (t && (t.type !== 'name' || t.value !== 'XObject')) {
+                throw new ParseError('pdf/xobject/bad-type',
+                    '/Type must be /XObject when present',
+                    { context: { actual: t.value } });
+            }
+            const s = stream.dict.entries.Subtype;
+            if (!s || s.type !== 'name') {
+                throw new ParseError('pdf/xobject/missing-subtype',
+                    'XObject must have /Subtype');
+            }
+            if (s.value === 'Image') return typeImageXObject(stream);
+            if (s.value === 'Form')  return typeFormXObject(stream);
+            return { kind: s.value, raw: stream.raw, dict: stream.dict };
+        }
+
+        return { typeImageXObject, typeFormXObject, typeXObject };
+    }
+};