@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/document/xrefStreamWriter.js

@@ -0,0 +1,353 @@
+// 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 Xref-stream + ObjStm writer.
+ *
+ * Provides an alternative to `pdfWriter.writeDocument` that emits the
+ * cross-reference as a `/Type /XRef` stream object (PDF 1.5+ /
+ * ISO 32000-2:2020 §7.5.8), optionally grouping non-stream indirects
+ * into `/Type /ObjStm` compressed object streams (§7.5.7).
+ *
+ * Wire format produced:
+ *
+ *     %PDF-2.0\n
+ *     %binary marker\n
+ *     <serialized indirects, including any ObjStm wrappers>
+ *     <xref-stream object>
+ *     startxref\n<offset>\n
+ *     %%EOF\n
+ *
+ * The xref stream carries fields (type, field2, field3) with widths W
+ * chosen to fit the largest values:
+ *
+ *     type=0  free                  → (0, 0, 0)
+ *     type=1  uncompressed indirect → (1, byteOffset, gen)
+ *     type=2  compressed in ObjStm  → (2, objStmNum, indexInStm)
+ *
+ * Options:
+ *
+ *   writeXrefStreamDocument({
+ *       indirects,            // [{ num, gen, value }]
+ *       root, info, id,       // same semantics as pdfWriter
+ *       version,              // default "2.0"
+ *       useObjStm: false,     // when true, group non-stream non-encrypt
+ *                             // indirects into ObjStm wrappers.
+ *       objStmCapacity: 64    // max objects per ObjStm
+ *   })
+ *
+ * @module pdf/document/xrefStreamWriter
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfSerializer } from '../syntax/serializer.js';
+import { pdfFlate } from '../syntax/filters/flate.js';
+
+export const pdfXrefStreamWriter = {
+    name: 'pdfXrefStreamWriter',
+    dependencies: ['pdfErrors', 'pdfSerializer', 'pdfFlate'],
+    deps: [pdfErrors, pdfSerializer, pdfFlate],
+    factory(errors, serializerMod, flateMod) {
+        const { RenderError } = errors;
+        const serializeIndirect = serializerMod.serializeIndirect;
+        const serializeObject   = serializerMod.serializeObject;
+        const flateEncode = flateMod && flateMod.encode;
+
+        const te = new TextEncoder();
+
+        function concat(arrays) {
+            let n = 0;
+            for (const a of arrays) n += a.length;
+            const out = new Uint8Array(n);
+            let o = 0;
+            for (const a of arrays) { out.set(a, o); o += a.length; }
+            return out;
+        }
+
+        function hexLit(bytes) {
+            const H = '0123456789ABCDEF';
+            let s = '<';
+            for (let i = 0; i < bytes.length; i++) {
+                s += H[bytes[i] >> 4] + H[bytes[i] & 0xF];
+            }
+            return s + '>';
+        }
+
+        function byteWidth(n) {
+            if (n <= 0) return 1;
+            let w = 0;
+            while (n > 0) { n = n >>> 8; w++; }
+            return w;
+        }
+
+        function writeBE(buf, off, value, w) {
+            for (let i = w - 1; i >= 0; i--) {
+                buf[off + i] = value & 0xff;
+                value = (value / 256) | 0;
+            }
+        }
+
+        function validateIndirects(list) {
+            const seen = new Set();
+            for (const it of list) {
+                if (!it || !Number.isFinite(it.num) || it.num < 1) {
+                    throw new RenderError('pdf/xrefstm-writer/bad-indirect',
+                        'each indirect requires num >= 1');
+                }
+                if (seen.has(it.num)) {
+                    throw new RenderError('pdf/xrefstm-writer/duplicate-num',
+                        'duplicate object number',
+                        { context: { num: it.num } });
+                }
+                seen.add(it.num);
+            }
+        }
+
+        function isCompressible(value) {
+            // ObjStm cannot carry stream objects; gen must be 0; and an
+            // object cannot be the xref-stream itself (we emit that
+            // last so it's not in the indirect list).
+            if (!value || typeof value.type !== 'string') return false;
+            if (value.type === 'stream') return false;
+            return true;
+        }
+
+        function buildObjStm(members, objNum) {
+            // members: [{ num, gen, value }]
+            // Per §7.5.7 the body is the concatenation of object
+            // headers (pairs "objNum offset") followed by serialized
+            // object values (no "N M obj … endobj" wrapper around each
+            // member — just the object value itself).
+            const bodyParts = [];
+            const offsets = new Array(members.length);
+
+            // First serialize all object values to compute offsets.
+            let cursor = 0;
+            for (let i = 0; i < members.length; i++) {
+                const m = members[i];
+                const bytes = serializeObject(m.value);
+                offsets[i] = cursor;
+                bodyParts.push(bytes);
+                bodyParts.push(te.encode('\n'));
+                cursor += bytes.length + 1;
+            }
+
+            let headerStr = '';
+            for (let i = 0; i < members.length; i++) {
+                if (i > 0) headerStr += ' ';
+                headerStr += `${members[i].num} ${offsets[i]}`;
+            }
+            headerStr += '\n';
+            const headerBytes = te.encode(headerStr);
+
+            const payload = concat([headerBytes, ...bodyParts]);
+            // Compress with flate.
+            const compressed = flateEncode(payload);
+            const dict = {
+                type: 'dict',
+                entries: {
+                    Type:   { type: 'name', value: 'ObjStm' },
+                    N:      { type: 'int',  value: members.length },
+                    First:  { type: 'int',  value: headerBytes.length },
+                    Filter: { type: 'name', value: 'FlateDecode' }
+                }
+            };
+            return {
+                num: objNum,
+                gen: 0,
+                value: { type: 'stream', dict, raw: compressed }
+            };
+        }
+
+        function buildXrefStreamIndirect(opts) {
+            const {
+                num, size, root, info, id,
+                w, indexPairs, payload
+            } = opts;
+            const entries = {
+                Type:   { type: 'name', value: 'XRef' },
+                Size:   { type: 'int',  value: size },
+                W:      { type: 'array', items: [
+                    { type: 'int', value: w[0] },
+                    { type: 'int', value: w[1] },
+                    { type: 'int', value: w[2] }
+                ] },
+                Root:   { type: 'ref', num: root.num, gen: root.gen | 0 },
+                Filter: { type: 'name', value: 'FlateDecode' }
+            };
+            if (info) entries.Info = { type: 'ref', num: info.num, gen: info.gen | 0 };
+            if (id) {
+                entries.ID = { type: 'array', items: [
+                    { type: 'string', value: id[0], syntax: 'hex' },
+                    { type: 'string', value: id[1], syntax: 'hex' }
+                ] };
+            }
+            // Always emit /Index — covers the contiguous run.
+            entries.Index = { type: 'array', items: [] };
+            for (const [first, count] of indexPairs) {
+                entries.Index.items.push({ type: 'int', value: first });
+                entries.Index.items.push({ type: 'int', value: count });
+            }
+            return {
+                num, gen: 0,
+                value: { type: 'stream', dict: { type: 'dict', entries }, raw: payload }
+            };
+        }
+
+        function writeXrefStreamDocument(opts) {
+            if (!opts || !Array.isArray(opts.indirects)) {
+                throw new RenderError('pdf/xrefstm-writer/bad-input',
+                    'writeXrefStreamDocument expects { indirects: [...] }');
+            }
+            if (!opts.root || !Number.isFinite(opts.root.num)) {
+                throw new RenderError('pdf/xrefstm-writer/no-root',
+                    'opts.root required');
+            }
+            if (typeof flateEncode !== 'function') {
+                throw new RenderError('pdf/xrefstm-writer/no-flate',
+                    'pdfFlate.encode is required to emit xref-streams');
+            }
+            const version = opts.version || '2.0';
+            if (!/^\d\.\d$/.test(version)) {
+                throw new RenderError('pdf/xrefstm-writer/bad-version',
+                    'version must look like "x.y"');
+            }
+            const indirects = opts.indirects.slice().sort((a, b) => a.num - b.num);
+            validateIndirects(indirects);
+
+            // Compute fresh object number for the xref-stream itself.
+            const maxInputNum = indirects.length
+                ? indirects[indirects.length - 1].num : 0;
+            let nextNum = maxInputNum + 1;
+
+            // Build ObjStm groupings (optional) and the final indirect
+            // list. We track xref entries in a Map<num, {type, f2, f3}>.
+            const xrefEntries = new Map();
+            // Always include object 0 (free head).
+            xrefEntries.set(0, { type: 0, f2: 0, f3: 65535 });
+
+            const emittedIndirects = [];
+            const useObjStm = !!opts.useObjStm;
+            const cap = (opts.objStmCapacity | 0) || 64;
+
+            if (useObjStm) {
+                const compressible = [];
+                const passthrough = [];
+                for (const it of indirects) {
+                    if (isCompressible(it.value) && (it.gen | 0) === 0) {
+                        compressible.push(it);
+                    } else {
+                        passthrough.push(it);
+                    }
+                }
+                // Group compressible into ObjStms.
+                for (let i = 0; i < compressible.length; i += cap) {
+                    const chunk = compressible.slice(i, i + cap);
+                    const objStmNum = nextNum++;
+                    const indirect = buildObjStm(chunk, objStmNum);
+                    emittedIndirects.push(indirect);
+                    for (let k = 0; k < chunk.length; k++) {
+                        xrefEntries.set(chunk[k].num, {
+                            type: 2, f2: objStmNum, f3: k
+                        });
+                    }
+                }
+                for (const it of passthrough) emittedIndirects.push(it);
+            } else {
+                for (const it of indirects) emittedIndirects.push(it);
+            }
+            emittedIndirects.sort((a, b) => a.num - b.num);
+
+            // Emit header + binary marker.
+            const parts = [];
+            let cursor = 0;
+            function push(u8) { parts.push(u8); cursor += u8.length; }
+            push(te.encode(`%PDF-${version}\n`));
+            push(new Uint8Array([0x25, 0xE2, 0xE3, 0xCF, 0xD3, 0x0A]));
+
+            for (const it of emittedIndirects) {
+                xrefEntries.set(it.num, {
+                    type: 1, f2: cursor, f3: it.gen | 0
+                });
+                push(serializeIndirect(it.num, it.gen | 0, it.value));
+            }
+
+            // Append the xref-stream indirect.
+            const xrefNum = nextNum;
+            // The xref-stream itself MUST appear in its own xref table
+            // (per §7.5.8 the xref-stream's xref entry has type=1 with
+            // the offset where the xref-stream begins).
+            const xrefOffset = cursor;
+            xrefEntries.set(xrefNum, { type: 1, f2: xrefOffset, f3: 0 });
+
+            // Build /Index pairs from sorted nums, contiguous runs.
+            const allNums = Array.from(xrefEntries.keys()).sort((a, b) => a - b);
+            const indexPairs = [];
+            let i = 0;
+            while (i < allNums.length) {
+                let j = i;
+                while (j + 1 < allNums.length
+                        && allNums[j + 1] === allNums[j] + 1) j++;
+                indexPairs.push([allNums[i], j - i + 1]);
+                i = j + 1;
+            }
+
+            // Pick W widths from observed max values.
+            let maxType = 0, maxF2 = 0, maxF3 = 0;
+            for (const e of xrefEntries.values()) {
+                if (e.type > maxType) maxType = e.type;
+                if (e.f2 > maxF2)     maxF2 = e.f2;
+                if (e.f3 > maxF3)     maxF3 = e.f3;
+            }
+            const w = [
+                Math.max(1, byteWidth(maxType)),
+                Math.max(1, byteWidth(maxF2)),
+                Math.max(1, byteWidth(maxF3))
+            ];
+
+            // Build the raw payload.
+            const recordSize = w[0] + w[1] + w[2];
+            const payload = new Uint8Array(allNums.length * recordSize);
+            let off = 0;
+            for (const n of allNums) {
+                const e = xrefEntries.get(n);
+                writeBE(payload, off,         e.type, w[0]);
+                writeBE(payload, off + w[0],  e.f2,   w[1]);
+                writeBE(payload, off + w[0] + w[1], e.f3, w[2]);
+                off += recordSize;
+            }
+            const compressed = flateEncode(payload);
+
+            const size = xrefNum + 1;
+            const xrefIndirect = buildXrefStreamIndirect({
+                num: xrefNum,
+                size,
+                root: opts.root,
+                info: opts.info,
+                id: opts.id,
+                w,
+                indexPairs,
+                payload: compressed
+            });
+            push(serializeIndirect(xrefIndirect.num, xrefIndirect.gen,
+                                   xrefIndirect.value));
+
+            // Trailer is the xref-stream object itself; we just need
+            // `startxref` + `%%EOF`.
+            push(te.encode(`startxref\n${xrefOffset}\n%%EOF\n`));
+
+            // ID note: when /ID is requested and we have no trailer to
+            // host it, /ID has been embedded in the xref-stream dict.
+            // (intentional per §7.5.8.)
+            void hexLit; // suppress unused; reserved for future trailer paths
+            return concat(parts);
+        }
+
+        return { writeXrefStreamDocument };
+    }
+};

package/src/embedded/collection.js

@@ -0,0 +1,102 @@
+// 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 Collection (PDF Portfolio) typing per ISO 32000-2:2020
+ * §7.11.6.
+ *
+ * A Collection dict (`/Type /Collection`) lives on the Catalog and
+ * describes how to display the embedded files attached to a "PDF
+ * Portfolio". Entries:
+ *   /Schema    — dict of collection field definitions.
+ *   /D         — name of the embedded file shown initially.
+ *   /View      — display mode (D/T/H — Details, Tile, Hidden, custom).
+ *   /Sort      — sort dictionary.
+ *   /Navigator — navigator extension dict.
+ *
+ * @module pdf/embedded/collection
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfCollection = {
+    name: 'pdfCollection',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const KNOWN = new Set(['Type', 'Schema', 'D', 'View', 'Sort', 'Navigator', 'Folders', 'Colors', 'Split']);
+        const VIEW_MODES = new Set(['D', 'T', 'H', 'C']);
+
+        function typeCollection(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/collection/not-dict',
+                    'Collection must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'Collection')) {
+                throw new ParseError('pdf/collection/bad-type',
+                    '/Type must be /Collection',
+                    { context: { actual: e.Type.value } });
+            }
+            const out = { raw: dict, _extras: {} };
+
+            if (e.Schema) {
+                if (e.Schema.type !== 'dict') {
+                    throw new ParseError('pdf/collection/bad-schema',
+                        '/Schema must be a dictionary',
+                        { context: { type: e.Schema.type } });
+                }
+                out.schema = e.Schema;
+            }
+            if (e.D) {
+                if (e.D.type !== 'string') {
+                    throw new ParseError('pdf/collection/bad-d',
+                        '/D must be a string',
+                        { context: { type: e.D.type } });
+                }
+                out.initialDoc = e.D.value;
+            }
+            if (e.View) {
+                if (e.View.type !== 'name' || !VIEW_MODES.has(e.View.value)) {
+                    throw new ParseError('pdf/collection/bad-view',
+                        '/View must be one of D, T, H, C',
+                        { context: { actual: e.View.value } });
+                }
+                out.view = e.View.value;
+            }
+            if (e.Sort) {
+                if (e.Sort.type !== 'dict') {
+                    throw new ParseError('pdf/collection/bad-sort',
+                        '/Sort must be a dictionary',
+                        { context: { type: e.Sort.type } });
+                }
+                out.sort = e.Sort;
+            }
+            if (e.Navigator) {
+                if (e.Navigator.type !== 'dict' && e.Navigator.type !== 'ref') {
+                    throw new ParseError('pdf/collection/bad-navigator',
+                        '/Navigator must be a dict or ref',
+                        { context: { type: e.Navigator.type } });
+                }
+                out.navigator = e.Navigator;
+            }
+
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        return { typeCollection };
+    }
+};

package/src/embedded/embeddedFile.js

@@ -0,0 +1,99 @@
+// 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 Embedded File stream typing per ISO 32000-2:2020 §7.11.4.
+ *
+ * An embedded file stream has `/Type /EmbeddedFile`, an optional
+ * `/Subtype` (MIME type encoded as a name), and an optional `/Params`
+ * sub-dictionary holding `/Size`, `/CreationDate`, `/ModDate`, and
+ * `/CheckSum` (a 16-byte MD5 hash as a hex/byte string).
+ *
+ * @module pdf/embedded/embeddedFile
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfEmbeddedFile = {
+    name: 'pdfEmbeddedFile',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const KNOWN_PARAMS = new Set(['Size', 'CreationDate', 'ModDate', 'CheckSum']);
+
+        function typeEmbeddedFile(stream) {
+            if (!isType(stream, 'stream')) {
+                throw new ParseError('pdf/embedded/not-stream',
+                    'embedded file must be a stream',
+                    { context: { type: stream && stream.type } });
+            }
+            if (!stream.dict || stream.dict.type !== 'dict') {
+                throw new ParseError('pdf/embedded/no-dict',
+                    'embedded file stream missing its dict');
+            }
+            const e = stream.dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'EmbeddedFile')) {
+                throw new ParseError('pdf/embedded/bad-type',
+                    '/Type must be /EmbeddedFile',
+                    { context: { actual: e.Type.value } });
+            }
+            const out = { bytes: stream.raw, raw: stream, _extras: {} };
+            if (e.Subtype) {
+                if (e.Subtype.type !== 'name') {
+                    throw new ParseError('pdf/embedded/bad-subtype',
+                        '/Subtype must be a name',
+                        { context: { type: e.Subtype.type } });
+                }
+                out.subtype = e.Subtype.value;
+            }
+            if (e.Params) {
+                if (e.Params.type !== 'dict') {
+                    throw new ParseError('pdf/embedded/bad-params',
+                        '/Params must be a dictionary',
+                        { context: { type: e.Params.type } });
+                }
+                out.params = typeParams(e.Params);
+            }
+            for (const k of Object.keys(e)) {
+                if (k !== 'Type' && k !== 'Subtype' && k !== 'Params'
+                    && k !== 'Length' && k !== 'Filter' && k !== 'DecodeParms'
+                    && k !== 'DL') {
+                    out._extras[k] = e[k];
+                }
+            }
+            return out;
+        }
+
+        function typeParams(dict) {
+            const e = dict.entries;
+            const out = { raw: dict, _extras: {} };
+            if (e.Size && (e.Size.type === 'int' || e.Size.type === 'real')) {
+                out.size = e.Size.value | 0;
+            }
+            if (e.CreationDate && e.CreationDate.type === 'string') {
+                out.creationDate = e.CreationDate.value;
+            }
+            if (e.ModDate && e.ModDate.type === 'string') {
+                out.modDate = e.ModDate.value;
+            }
+            if (e.CheckSum && e.CheckSum.type === 'string') {
+                out.checkSum = e.CheckSum.value;
+            }
+            for (const k of Object.keys(e)) {
+                if (!KNOWN_PARAMS.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        return { typeEmbeddedFile };
+    }
+};

package/src/embedded/fileSpec.js

@@ -0,0 +1,137 @@
+// 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 File Specification typing per ISO 32000-2:2020 §7.11.
+ *
+ * A File Specification (`/Type /Filespec` or legacy `/Type /F`) refers
+ * to an external or embedded file. Entries:
+ *   /FS              — file system (URL or absent for local).
+ *   /F /UF /DOS /Mac /Unix — file path forms (UF preferred since 1.7).
+ *   /ID              — array of two byte-strings (uniqueness).
+ *   /V               — boolean, volatile.
+ *   /EF              — dict of embedded file streams (F, UF, DOS, …).
+ *   /RF              — related files (dict of arrays).
+ *   /Desc            — description string.
+ *   /CI              — collection item dict.
+ *   /AFRelationship  — name; PDF 2.0 Associated Files relationship.
+ *
+ * @module pdf/embedded/fileSpec
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfFileSpec = {
+    name: 'pdfFileSpec',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const KNOWN = new Set([
+            'Type', 'FS', 'F', 'UF', 'DOS', 'Mac', 'Unix', 'ID', 'V',
+            'EF', 'RF', 'Desc', 'CI', 'AFRelationship', 'Thumb'
+        ]);
+        const REL = new Set([
+            'Source', 'Data', 'Alternative', 'Supplement',
+            'EncryptedPayload', 'FormData', 'Schema', 'Unspecified'
+        ]);
+
+        function typeFileSpec(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/filespec/not-dict',
+                    'File spec must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && e.Type.type === 'name'
+                && e.Type.value !== 'Filespec' && e.Type.value !== 'F') {
+                throw new ParseError('pdf/filespec/bad-type',
+                    '/Type must be /Filespec or /F when present',
+                    { context: { actual: e.Type.value } });
+            }
+
+            const out = { raw: dict, _extras: {} };
+
+            if (e.FS) {
+                if (e.FS.type !== 'name') {
+                    throw new ParseError('pdf/filespec/bad-fs',
+                        '/FS must be a name', { context: { type: e.FS.type } });
+                }
+                out.fs = e.FS.value;
+            }
+            for (const k of ['F', 'UF', 'DOS', 'Mac', 'Unix']) {
+                if (e[k]) {
+                    if (e[k].type !== 'string') {
+                        throw new ParseError('pdf/filespec/bad-path',
+                            '/' + k + ' must be a string',
+                            { context: { type: e[k].type } });
+                    }
+                    out[k.toLowerCase() === 'f' ? 'f' : k.toLowerCase()] = e[k].value;
+                }
+            }
+            if (e.ID) {
+                if (e.ID.type !== 'array') {
+                    throw new ParseError('pdf/filespec/bad-id',
+                        '/ID must be an array', { context: { type: e.ID.type } });
+                }
+                out.id = e.ID.items.filter((x) => x.type === 'string').map((x) => x.value);
+            }
+            if (e.V && e.V.type === 'bool') out.volatile = e.V.value;
+            if (e.EF) {
+                if (e.EF.type !== 'dict') {
+                    throw new ParseError('pdf/filespec/bad-ef',
+                        '/EF must be a dictionary',
+                        { context: { type: e.EF.type } });
+                }
+                out.embedded = e.EF.entries;
+            }
+            if (e.RF) {
+                if (e.RF.type !== 'dict') {
+                    throw new ParseError('pdf/filespec/bad-rf',
+                        '/RF must be a dictionary',
+                        { context: { type: e.RF.type } });
+                }
+                out.related = e.RF.entries;
+            }
+            if (e.Desc) {
+                if (e.Desc.type !== 'string') {
+                    throw new ParseError('pdf/filespec/bad-desc',
+                        '/Desc must be a string',
+                        { context: { type: e.Desc.type } });
+                }
+                out.desc = e.Desc.value;
+            }
+            if (e.CI) out.ci = e.CI;
+            if (e.AFRelationship) {
+                if (e.AFRelationship.type !== 'name') {
+                    throw new ParseError('pdf/filespec/bad-afrel',
+                        '/AFRelationship must be a name',
+                        { context: { type: e.AFRelationship.type } });
+                }
+                const v = e.AFRelationship.value;
+                out.afRelationship = v;
+                out.afRelationshipStandard = REL.has(v);
+            }
+
+            if (!out.f && !out.uf && !out.dos && !out.mac && !out.unix && !out.embedded) {
+                throw new ParseError('pdf/filespec/empty',
+                    'File spec has no path or embedded file');
+            }
+
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        return { typeFileSpec };
+    }
+};