✨ Add outputIntents to document definition

Consumers that need PDF/A or PDF/X conformance must register output
intents with ICC profiles. Previously this required depending on
`@ralfstx/pdf-core` directly to instantiate `ICCColorSpace`.

Add an `outputIntents` array to `DocumentDefinition` that accepts raw
ICC profile bytes as `Uint8Array`. The library auto-detects
`numComponents` from the ICC header and creates the `ICCColorSpace`
internally. The read phase validates the ICC header structure (minimum
length, `acsp` signature, supported color space).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ralfstx

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- `outputIntents` property on `DocumentDefinition` for declaring PDF
+  output intents (e.g. for PDF/A or PDF/X conformance). Accepts raw ICC
+  profile data as `Uint8Array`, removing the need for consumers to
+  depend on `@ralfstx/pdf-core`.
+
 ## [0.6.1] - 2026-03-08
 
 ### Changed

src/api/document.ts

@@ -83,6 +83,12 @@ export type DocumentDefinition = {
    */
   embeddedFiles?: EmbeddedFile[];
 
+  /**
+   * Output intents that describe the intended output conditions for the
+   * document (e.g. for PDF/A or PDF/X conformance).
+   */
+  outputIntents?: OutputIntent[];
+
   dev?: {
     /**
      * When set to true, additional guides are drawn to help analyzing
@@ -229,3 +235,41 @@ export type PageInfo = {
    */
   readonly pageCount?: number;
 };
+
+/**
+ * An output intent that describes the intended output condition for the
+ * document. Output intents are required for PDF/A and PDF/X conformance.
+ */
+export type OutputIntent = {
+  /**
+   * The output intent subtype, e.g. `'GTS_PDFA1'` for PDF/A or
+   * `'GTS_PDFX'` for PDF/X.
+   */
+  subtype: string;
+
+  /**
+   * An identifier for the intended output condition, e.g.
+   * `'sRGB IEC61966-2.1'`.
+   */
+  outputConditionIdentifier: string;
+
+  /**
+   * The raw ICC profile data for the destination output condition.
+   */
+  iccProfile: Uint8Array;
+
+  /**
+   * A human-readable description of the intended output condition.
+   */
+  outputCondition?: string;
+
+  /**
+   * A URL for an ICC profile registry where the condition is defined.
+   */
+  registryName?: string;
+
+  /**
+   * Additional information about the intended output condition.
+   */
+  info?: string;
+};

src/read/read-document.test.ts

@@ -185,4 +185,120 @@ describe('readDocumentDefinition', () => {
       ),
     );
   });
+
+  describe('outputIntents', () => {
+    it('accepts valid output intent', () => {
+      const iccProfile = mkIccProfile('RGB ');
+      const outputIntents = [
+        {
+          subtype: 'GTS_PDFA1',
+          outputConditionIdentifier: 'sRGB IEC61966-2.1',
+          iccProfile,
+          outputCondition: 'sRGB',
+          registryName: 'http://www.color.org',
+          info: 'sRGB IEC61966-2.1',
+        },
+      ];
+
+      const def = readDocumentDefinition({ ...input, outputIntents });
+
+      expect(def.outputIntents).toEqual(outputIntents);
+    });
+
+    it('accepts output intent with only required fields', () => {
+      const iccProfile = mkIccProfile('RGB ');
+      const outputIntents = [
+        { subtype: 'GTS_PDFA1', outputConditionIdentifier: 'sRGB', iccProfile },
+      ];
+
+      const def = readDocumentDefinition({ ...input, outputIntents });
+
+      expect(def.outputIntents).toEqual(outputIntents);
+    });
+
+    it('checks subtype is required', () => {
+      const outputIntents = [{ outputConditionIdentifier: 'sRGB', iccProfile: mkIccProfile() }];
+
+      expect(() => readDocumentDefinition({ ...input, outputIntents })).toThrow(
+        /Missing value for "subtype"/,
+      );
+    });
+
+    it('checks outputConditionIdentifier is required', () => {
+      const outputIntents = [{ subtype: 'GTS_PDFA1', iccProfile: mkIccProfile() }];
+
+      expect(() => readDocumentDefinition({ ...input, outputIntents })).toThrow(
+        /Missing value for "outputConditionIdentifier"/,
+      );
+    });
+
+    it('checks iccProfile is required', () => {
+      const outputIntents = [{ subtype: 'GTS_PDFA1', outputConditionIdentifier: 'sRGB' }];
+
+      expect(() => readDocumentDefinition({ ...input, outputIntents })).toThrow(
+        /Missing value for "iccProfile"/,
+      );
+    });
+
+    it('rejects non-Uint8Array iccProfile', () => {
+      const outputIntents = [
+        { subtype: 'GTS_PDFA1', outputConditionIdentifier: 'sRGB', iccProfile: 'not-bytes' },
+      ];
+
+      expect(() => readDocumentDefinition({ ...input, outputIntents })).toThrow(
+        /Invalid value for "outputIntents\/0\/iccProfile": Expected Uint8Array/,
+      );
+    });
+
+    it('rejects ICC profile that is too short', () => {
+      const outputIntents = [
+        {
+          subtype: 'GTS_PDFA1',
+          outputConditionIdentifier: 'sRGB',
+          iccProfile: new Uint8Array(10),
+        },
+      ];
+
+      expect(() => readDocumentDefinition({ ...input, outputIntents })).toThrow(
+        /Invalid value for "outputIntents\/0\/iccProfile": ICC profile is too short/,
+      );
+    });
+
+    it('rejects ICC profile with invalid signature', () => {
+      const iccProfile = new Uint8Array(128);
+      const outputIntents = [
+        { subtype: 'GTS_PDFA1', outputConditionIdentifier: 'sRGB', iccProfile },
+      ];
+
+      expect(() => readDocumentDefinition({ ...input, outputIntents })).toThrow(
+        /Invalid value for "outputIntents\/0\/iccProfile": Invalid ICC profile: expected signature 'acsp'/,
+      );
+    });
+
+    it('rejects ICC profile with unsupported color space', () => {
+      const iccProfile = mkIccProfile('Lab ');
+      const outputIntents = [
+        { subtype: 'GTS_PDFA1', outputConditionIdentifier: 'sRGB', iccProfile },
+      ];
+
+      expect(() => readDocumentDefinition({ ...input, outputIntents })).toThrow(
+        /Invalid value for "outputIntents\/0\/iccProfile": Unsupported ICC profile color space 'Lab'/,
+      );
+    });
+  });
 });
+
+function mkIccProfile(colorSpace = 'RGB '): Uint8Array {
+  const data = new Uint8Array(128);
+  // color space signature at offset 16
+  data[16] = colorSpace.charCodeAt(0);
+  data[17] = colorSpace.charCodeAt(1);
+  data[18] = colorSpace.charCodeAt(2);
+  data[19] = colorSpace.charCodeAt(3);
+  // 'acsp' signature at offset 36
+  data[36] = 0x61; // a
+  data[37] = 0x63; // c
+  data[38] = 0x73; // s
+  data[39] = 0x70; // p
+  return data;
+}

src/read/read-document.ts

@@ -38,6 +38,14 @@ export type DocumentDefinition = {
     modificationDate?: Date;
     relationship?: FileRelationShip;
   }[];
+  outputIntents?: {
+    subtype: string;
+    outputConditionIdentifier: string;
+    iccProfile: Uint8Array;
+    outputCondition?: string;
+    registryName?: string;
+    info?: string;
+  }[];
   onRenderDocument?: (pdfDoc: PDFDocument) => void | Promise<void>;
 };
 
@@ -68,6 +76,7 @@ export function readDocumentDefinition(input: unknown): DocumentDefinition {
     dev: optional(types.object({ guides: optional(types.boolean()) })),
     customData: optional(readCustomData),
     embeddedFiles: optional(types.array(readEmbeddedFiles)),
+    outputIntents: optional(types.array(readOutputIntent)),
     onRenderDocument: optional(),
   });
   if (def1.language && !def1.defaultStyle?.language) {
@@ -147,3 +156,46 @@ function readData(input: unknown): Uint8Array {
   if (input instanceof Uint8Array) return input;
   throw typeError('Uint8Array', input);
 }
+
+function readOutputIntent(input: unknown) {
+  const intent = readObject(input, {
+    subtype: required(types.string()),
+    outputConditionIdentifier: required(types.string()),
+    iccProfile: required(readIccProfile),
+    outputCondition: optional(types.string()),
+    registryName: optional(types.string()),
+    info: optional(types.string()),
+  });
+  return intent;
+}
+
+function readIccProfile(input: unknown): Uint8Array {
+  if (!(input instanceof Uint8Array)) {
+    throw typeError('Uint8Array', input);
+  }
+  if (input.length < 128) {
+    throw new TypeError('ICC profile is too short');
+  }
+  const view = new DataView(input.buffer, input.byteOffset, input.byteLength);
+  const signature = String.fromCharCode(
+    view.getUint8(36),
+    view.getUint8(37),
+    view.getUint8(38),
+    view.getUint8(39),
+  );
+  if (signature !== 'acsp') {
+    throw new TypeError(`Invalid ICC profile: expected signature 'acsp', got '${signature}'`);
+  }
+  const colorSpace = String.fromCharCode(
+    view.getUint8(16),
+    view.getUint8(17),
+    view.getUint8(18),
+    view.getUint8(19),
+  );
+  if (!['RGB ', 'CMYK', 'GRAY'].includes(colorSpace)) {
+    throw new TypeError(
+      `Unsupported ICC profile color space '${colorSpace.trim()}', expected RGB, CMYK, or GRAY`,
+    );
+  }
+  return input;
+}

src/render/render-document.test.ts

@@ -5,6 +5,19 @@ import { renderDocument } from './render-document.ts';
 
 const noObjectStreams = { useObjectStreams: false } as const;
 
+function mkIccProfile(colorSpace = 'RGB '): Uint8Array {
+  const data = new Uint8Array(128);
+  data[16] = colorSpace.charCodeAt(0);
+  data[17] = colorSpace.charCodeAt(1);
+  data[18] = colorSpace.charCodeAt(2);
+  data[19] = colorSpace.charCodeAt(3);
+  data[36] = 0x61; // a
+  data[37] = 0x63; // c
+  data[38] = 0x73; // s
+  data[39] = 0x70; // p
+  return data;
+}
+
 describe('renderDocument', () => {
   beforeEach(() => {
     vi.stubEnv('TZ', 'UTC');
@@ -117,4 +130,32 @@ describe('renderDocument', () => {
 
     expect(dataString).toMatch(/\/Title <FEFF0074006500730074002D007400690074006C0065>/);
   });
+
+  it('renders output intents', async () => {
+    const iccProfile = mkIccProfile('RGB ');
+    const def = {
+      content: [],
+      outputIntents: [
+        {
+          subtype: 'GTS_PDFA1',
+          outputConditionIdentifier: 'sRGB IEC61966-2.1',
+          iccProfile,
+          outputCondition: 'sRGB',
+          registryName: 'http://www.color.org',
+          info: 'sRGB IEC61966-2.1',
+        },
+      ],
+    };
+
+    const pdfData = await renderDocument(def, [], noObjectStreams);
+    const dataString = new TextDecoder().decode(pdfData);
+
+    expect(dataString).toMatch(/\/OutputIntents/);
+    expect(dataString).toMatch(/\/S \/GTS_PDFA1/);
+    expect(dataString).toMatch(/\/OutputConditionIdentifier \(sRGB IEC61966-2.1\)/);
+    expect(dataString).toMatch(/\/OutputCondition \(sRGB\)/);
+    expect(dataString).toMatch(/\/RegistryName \(http:\/\/www.color.org\)/);
+    expect(dataString).toMatch(/\/Info <FEFF/);
+    expect(dataString).toMatch(/\/DestOutputProfile/);
+  });
 });

src/render/render-document.ts

@@ -1,5 +1,5 @@
 import type { PDFContext, PDFDict, WriteOptions } from '@ralfstx/pdf-core';
-import { PDFDocument, PDFStream } from '@ralfstx/pdf-core';
+import { ICCColorSpace, PDFDocument, PDFStream } from '@ralfstx/pdf-core';
 
 import type { Page } from '../page.ts';
 import type { DocumentDefinition, Metadata } from '../read/read-document.ts';
@@ -29,6 +29,20 @@ export async function renderDocument(
     });
   }
 
+  for (const intent of def.outputIntents ?? []) {
+    pdfDoc.addOutputIntent({
+      subtype: intent.subtype,
+      outputConditionIdentifier: intent.outputConditionIdentifier,
+      destOutputProfile: ICCColorSpace.of({
+        data: intent.iccProfile,
+        numComponents: iccNumComponents(intent.iccProfile),
+      }),
+      outputCondition: intent.outputCondition,
+      registryName: intent.registryName,
+      info: intent.info,
+    });
+  }
+
   await def.onRenderDocument?.(pdfDoc);
 
   return pdfDoc.write(writeOptions);
@@ -62,3 +76,16 @@ function setCustomData(data: Record<string, string | Uint8Array>, doc: PDFDocume
     });
   }
 }
+
+function iccNumComponents(data: Uint8Array): 1 | 3 | 4 {
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const colorSpace = String.fromCharCode(
+    view.getUint8(16),
+    view.getUint8(17),
+    view.getUint8(18),
+    view.getUint8(19),
+  );
+  if (colorSpace === 'RGB ') return 3;
+  if (colorSpace === 'CMYK') return 4;
+  return 1;
+}