@strav/pdf 0.4.17

package/README.md

@@ -0,0 +1,79 @@
+# @strav/pdf
+
+Low-level, **zero-dependency** PDF generation (the *write* side of PDF) for
+the Strav ecosystem. Produces conformant PDF 1.7 byte streams — it does not
+parse, render or display PDFs. No `@strav/*` dependency and no npm runtime
+dependency; only Node/Bun built-ins.
+
+## Install
+
+```bash
+bun add @strav/pdf
+```
+
+## Quick start
+
+```typescript
+import { PdfDocument, PdfFont, rgb, mm } from '@strav/pdf'
+
+const doc = PdfDocument.create({ info: { title: 'Hello', author: 'Acme' } })
+const page = doc.addPage({ size: { widthPt: mm(210), heightPt: mm(297) } })
+
+page.content()
+  .save()
+  .setFillColor(rgb(0.1, 0.1, 0.4))
+  .rect(mm(20), mm(240), mm(60), mm(30)).fill()
+  .text((t) =>
+    t.setFont(PdfFont.standard('Helvetica-Bold'), 24)
+      .moveTo(mm(20), mm(210))
+      .show('Hello, print world.'),
+  )
+  .restore()
+
+await Bun.write('out.pdf', await doc.save())
+```
+
+## Streaming output
+
+`save()` buffers and returns a `Uint8Array`. For large documents or HTTP
+responses, stream straight to a Node `Writable` instead — nothing is buffered:
+
+```typescript
+import { createWriteStream } from 'node:fs'
+
+await doc.saveToStream(createWriteStream('out.pdf'))
+```
+
+`saveToStream` resolves once the stream has flushed; it rejects on a stream
+error or a build/conformance error, exactly like `save()`.
+
+## What's supported
+
+Object model & serialization, pages, the full content-stream operator set,
+device + ICC/Separation/DeviceN/CIE color, FlateDecode/ASCII85/ASCIIHex
+filters, Standard-14 and embedded (subsetted) TrueType + OpenType/CFF fonts
+with ToUnicode, JPEG/PNG images with alpha, transparency (ExtGState) and
+tiling/shading patterns, XMP metadata, and PDF/A-2b / PDF/X-4 conformance
+validation. Output is byte-deterministic with a fixed creation date and id.
+
+Browser builds, encryption, signatures, forms, and reading/parsing PDFs are
+out of scope.
+
+## Documentation
+
+Full guides live in [`docs/pdf`](../../docs/pdf/pdf.md): the content builder,
+fonts, images, color, transparency/patterns, and conformance.
+
+## Examples
+
+Runnable under Bun (`packages/pdf/examples/`):
+
+```bash
+bun packages/pdf/examples/basic_page.ts
+bun packages/pdf/examples/multi_font.ts
+bun packages/pdf/examples/print_ready_pdfx4.ts <font.ttf> <cmyk.icc>
+```
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@strav/pdf",
+  "version": "0.4.17",
+  "type": "module",
+  "description": "Low-level, zero-dependency PDF generation (write side) for the Strav ecosystem",
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "pdf",
+    "typescript",
+    "strav"
+  ],
+  "files": [
+    "src/",
+    "README.md",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./objects": "./src/objects/index.ts",
+    "./objects/*": "./src/objects/*.ts",
+    "./streams": "./src/streams/index.ts",
+    "./streams/*": "./src/streams/*.ts",
+    "./content": "./src/content/index.ts",
+    "./content/*": "./src/content/*.ts",
+    "./fonts": "./src/fonts/index.ts",
+    "./fonts/*": "./src/fonts/*.ts",
+    "./images": "./src/images/index.ts",
+    "./images/*": "./src/images/*.ts",
+    "./ext-gstate": "./src/ext-gstate/index.ts",
+    "./ext-gstate/*": "./src/ext-gstate/*.ts",
+    "./patterns": "./src/patterns/index.ts",
+    "./patterns/*": "./src/patterns/*.ts",
+    "./metadata": "./src/metadata/index.ts",
+    "./metadata/*": "./src/metadata/*.ts",
+    "./standards": "./src/standards/index.ts",
+    "./standards/*": "./src/standards/*.ts",
+    "./color": "./src/color/index.ts",
+    "./color/*": "./src/color/*.ts",
+    "./document": "./src/document/index.ts",
+    "./document/*": "./src/document/*.ts"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.9"
+  }
+}

package/src/color/cie.ts

@@ -0,0 +1,61 @@
+/**
+ * CIE-based color spaces (spec §9.1): CalGray, CalRGB and Lab. These are
+ * device-independent array color spaces with a parameter dictionary; no
+ * profile is embedded. D50 is the default white point.
+ */
+
+import { arr, dict, name, num } from '../objects/types.ts'
+import type { PdfObject } from '../objects/types.ts'
+import type { ManagedColorSpace } from './space.ts'
+import { managedColor } from './space.ts'
+import type { Color } from './color.ts'
+
+const D50: [number, number, number] = [0.9505, 1.0, 1.089]
+
+class ArrayColorSpace implements ManagedColorSpace {
+  constructor(
+    readonly id: string,
+    readonly components: number,
+    private readonly obj: PdfObject
+  ) {}
+  build(): PdfObject {
+    return this.obj
+  }
+  color(...comps: number[]): Color {
+    return managedColor(this, comps)
+  }
+}
+
+let cieCounter = 0
+
+export function calGray(opts: { whitePoint?: [number, number, number]; gamma?: number } = {}) {
+  const params = dict({ WhitePoint: arr((opts.whitePoint ?? D50).map(num)) })
+  if (opts.gamma !== undefined) params.entries.set('Gamma', num(opts.gamma))
+  return new ArrayColorSpace(`calgray:${cieCounter++}`, 1, arr([name('CalGray'), params]))
+}
+
+export function calRGB(
+  opts: {
+    whitePoint?: [number, number, number]
+    gamma?: [number, number, number]
+    matrix?: number[]
+  } = {}
+) {
+  const params = dict({ WhitePoint: arr((opts.whitePoint ?? D50).map(num)) })
+  if (opts.gamma) params.entries.set('Gamma', arr(opts.gamma.map(num)))
+  if (opts.matrix) params.entries.set('Matrix', arr(opts.matrix.map(num)))
+  return new ArrayColorSpace(`calrgb:${cieCounter++}`, 3, arr([name('CalRGB'), params]))
+}
+
+/** Lab color space. `range` bounds the a and b axes (default [-100,100,-100,100]). */
+export function lab(
+  opts: { whitePoint?: [number, number, number]; range?: number[] } = {}
+) {
+  const params = dict({
+    WhitePoint: arr((opts.whitePoint ?? D50).map(num)),
+    Range: arr((opts.range ?? [-100, 100, -100, 100]).map(num)),
+  })
+  return new ArrayColorSpace(`lab:${cieCounter++}`, 3, arr([name('Lab'), params]))
+}
+
+export type { ArrayColorSpace }

package/src/color/color.ts

@@ -0,0 +1,77 @@
+/**
+ * Color values and factories (spec §9).
+ *
+ * M1–M3 ship the three device color spaces. CIE-based, ICCBased, Indexed,
+ * Separation, DeviceN and Pattern arrive in M9 — the union is designed to grow
+ * without breaking existing callers.
+ */
+
+import { PdfGenError } from '../util/errors.ts'
+import type { ManagedColor } from './space.ts'
+
+/** Device color space names. */
+export type ColorSpace = 'DeviceGray' | 'DeviceRGB' | 'DeviceCMYK'
+
+export type DeviceColor =
+  | { space: 'DeviceGray'; g: number }
+  | { space: 'DeviceRGB'; r: number; g: number; b: number }
+  | { space: 'DeviceCMYK'; c: number; m: number; y: number; k: number }
+
+/** A color in any space — device or managed (ICCBased/Separation/…). */
+export type Color = DeviceColor | ManagedColor
+
+/** Components of a device color, in PDF operand order. */
+export function deviceComponents(c: DeviceColor): number[] {
+  switch (c.space) {
+    case 'DeviceGray':
+      return [c.g]
+    case 'DeviceRGB':
+      return [c.r, c.g, c.b]
+    case 'DeviceCMYK':
+      return [c.c, c.m, c.y, c.k]
+  }
+}
+
+/** The device color-space name for a device color. */
+export function deviceSpaceName(c: DeviceColor): ColorSpace {
+  return c.space
+}
+
+function unit(name: string, v: number): number {
+  if (!Number.isFinite(v) || v < 0 || v > 1) {
+    throw new PdfGenError(
+      'PDF_INVALID_COLOR',
+      `${name} component must be in [0, 1], got ${v}`
+    )
+  }
+  return v
+}
+
+/** DeviceGray. `g` in [0,1] (0 = black, 1 = white). */
+export function gray(g: number): Color {
+  return { space: 'DeviceGray', g: unit('Gray', g) }
+}
+
+/** DeviceRGB. Components in [0,1]. */
+export function rgb(r: number, g: number, b: number): Color {
+  return {
+    space: 'DeviceRGB',
+    r: unit('R', r),
+    g: unit('G', g),
+    b: unit('B', b),
+  }
+}
+
+/** DeviceCMYK. Components in [0,1]. */
+export function cmyk(c: number, m: number, y: number, k: number): Color {
+  return {
+    space: 'DeviceCMYK',
+    c: unit('C', c),
+    m: unit('M', m),
+    y: unit('Y', y),
+    k: unit('K', k),
+  }
+}
+
+/** Namespace form of the factories (spec §16 exports `Color` as a value). */
+export const Color = { gray, rgb, cmyk } as const

package/src/color/conversion.ts

@@ -0,0 +1,26 @@
+/**
+ * Naïve device-space color conversions (spec §9.4).
+ *
+ * ⚠️ Preview only — NOT color-accurate. Callers needing accurate conversion
+ * must use a real CMM externally and pass pre-converted values.
+ */
+
+import type { Color } from './color.ts'
+import { gray, rgb, cmyk } from './color.ts'
+
+/** Rec.601 luma. */
+export function rgbToGray(r: number, g: number, b: number): Color {
+  return gray(0.299 * r + 0.587 * g + 0.114 * b)
+}
+
+/** Simple CMYK → RGB. */
+export function cmykToRgb(c: number, m: number, y: number, k: number): Color {
+  return rgb((1 - c) * (1 - k), (1 - m) * (1 - k), (1 - y) * (1 - k))
+}
+
+/** Simple RGB → CMYK with black generation. */
+export function rgbToCmyk(r: number, g: number, b: number): Color {
+  const k = 1 - Math.max(r, g, b)
+  if (k >= 1) return cmyk(0, 0, 0, 1)
+  return cmyk((1 - r - k) / (1 - k), (1 - g - k) / (1 - k), (1 - b - k) / (1 - k), k)
+}

package/src/color/device.ts

@@ -0,0 +1,37 @@
+/**
+ * Device color-space operator emission (spec §9.1). Maps a {@link Color} to
+ * the shortcut color operators (`g`/`rg`/`k` for fill, `G`/`RG`/`K` for
+ * stroke). Numbers go through the shared serializer for determinism (§8.5).
+ */
+
+import { formatNumber } from '../objects/number.ts'
+import { OP } from '../content/operators.ts'
+import type { DeviceColor } from './color.ts'
+
+function n(v: number): string {
+  return formatNumber(v)
+}
+
+/** Operator line that sets the non-stroking (fill) color. */
+export function fillColorOp(c: DeviceColor): string {
+  switch (c.space) {
+    case 'DeviceGray':
+      return `${n(c.g)} ${OP.fillGray}`
+    case 'DeviceRGB':
+      return `${n(c.r)} ${n(c.g)} ${n(c.b)} ${OP.fillRGB}`
+    case 'DeviceCMYK':
+      return `${n(c.c)} ${n(c.m)} ${n(c.y)} ${n(c.k)} ${OP.fillCMYK}`
+  }
+}
+
+/** Operator line that sets the stroking color. */
+export function strokeColorOp(c: DeviceColor): string {
+  switch (c.space) {
+    case 'DeviceGray':
+      return `${n(c.g)} ${OP.strokeGray}`
+    case 'DeviceRGB':
+      return `${n(c.r)} ${n(c.g)} ${n(c.b)} ${OP.strokeRGB}`
+    case 'DeviceCMYK':
+      return `${n(c.c)} ${n(c.m)} ${n(c.y)} ${n(c.k)} ${OP.strokeCMYK}`
+  }
+}

package/src/color/devicen.ts

@@ -0,0 +1,74 @@
+/**
+ * DeviceN color space (spec §9.5) — N named colorants mapped to an alternate
+ * device space by a tint transform. The transform is an N→M Type 4 PostScript
+ * function supplied by the caller (multi-input, so Type 2 doesn't apply).
+ */
+
+import { arr, name, num } from '../objects/types.ts'
+import type { PdfObject } from '../objects/types.ts'
+import type { ObjectTable } from '../document/object_table.ts'
+import type { ManagedColorSpace } from './space.ts'
+import { managedColor } from './space.ts'
+import type { Color } from './color.ts'
+import type { ColorSpace } from './color.ts'
+import { type4Function } from './separation.ts'
+
+class DeviceNColorSpace implements ManagedColorSpace {
+  readonly id: string
+  readonly components: number
+
+  constructor(
+    private readonly names: string[],
+    private readonly alternate: ColorSpace,
+    private readonly fn: (t: ObjectTable) => PdfObject,
+    tag: number
+  ) {
+    this.components = names.length
+    this.id = `devn:${names.join(',')}:${tag}`
+  }
+
+  build(table: ObjectTable): PdfObject {
+    return arr([
+      name('DeviceN'),
+      arr(this.names.map(name)),
+      name(this.alternate),
+      this.fn(table),
+    ])
+  }
+
+  /** A color with one tint per colorant (each in [0,1]). */
+  color(...tints: number[]): Color {
+    return managedColor(this, tints)
+  }
+}
+
+let devnCounter = 0
+
+/**
+ * A DeviceN color space. `postscript` is a Type 4 calculator program mapping
+ * the N colorant tints to the alternate space's components.
+ *
+ * ```ts
+ * const duotone = deviceN(['Black', 'PANTONE 877 C'], 'DeviceCMYK',
+ *   '{ exch dup 0 0 4 1 roll }')   // illustrative
+ * ```
+ */
+export function deviceN(
+  names: string[],
+  alternate: ColorSpace,
+  postscript: string
+): DeviceNColorSpace {
+  const altComps = alternate === 'DeviceGray' ? 1 : alternate === 'DeviceRGB' ? 3 : 4
+  const domain: number[] = []
+  for (let i = 0; i < names.length; i++) domain.push(0, 1)
+  const range: number[] = []
+  for (let i = 0; i < altComps; i++) range.push(0, 1)
+  return new DeviceNColorSpace(
+    names,
+    alternate,
+    type4Function(domain, range, postscript),
+    devnCounter++
+  )
+}
+
+export type { DeviceNColorSpace }

package/src/color/icc.ts

@@ -0,0 +1,103 @@
+/**
+ * ICC profile reading + embedding (spec §9.2).
+ *
+ * We do **no** color transforms. The profile is an opaque blob embedded for
+ * the consumer (RIP, Acrobat). We parse only the 128-byte header to learn the
+ * data color space (→ component count) and validate the `acsp` signature.
+ */
+
+import { PdfGenError } from '../util/errors.ts'
+import { arr, name, num } from '../objects/types.ts'
+import type { PdfObject } from '../objects/types.ts'
+import type { ObjectTable } from '../document/object_table.ts'
+import { makeStream } from '../streams/stream.ts'
+import type { ManagedColorSpace } from './space.ts'
+import { managedColor } from './space.ts'
+import type { Color } from './color.ts'
+
+export type IccColorSpace = 'GRAY' | 'RGB' | 'CMYK' | 'Lab'
+
+export interface IccProfile {
+  /** Data color space (from header offset 16). */
+  colorSpace: IccColorSpace
+  /** Component count: GRAY 1, RGB/Lab 3, CMYK 4. */
+  components: 1 | 3 | 4
+  /** Profile/device class fourcc (offset 12), e.g. `prtr`, `mntr`. */
+  profileClass: string
+  /** Profile connection space (offset 20), e.g. `XYZ ` or `Lab `. */
+  pcs: string
+  bytes: Uint8Array
+}
+
+function fourcc(b: Uint8Array, o: number): string {
+  return String.fromCharCode(b[o]!, b[o + 1]!, b[o + 2]!, b[o + 3]!)
+}
+
+export function parseIccProfile(bytes: Uint8Array): IccProfile {
+  if (bytes.length < 128) {
+    throw new PdfGenError('PDF_INVALID_COLOR', 'ICC profile too short (need ≥128-byte header)')
+  }
+  if (fourcc(bytes, 36) !== 'acsp') {
+    throw new PdfGenError('PDF_INVALID_COLOR', "Not an ICC profile (missing 'acsp' signature)")
+  }
+  const sig = fourcc(bytes, 16)
+  const map: Record<string, { cs: IccColorSpace; n: 1 | 3 | 4 }> = {
+    'GRAY': { cs: 'GRAY', n: 1 },
+    'RGB ': { cs: 'RGB', n: 3 },
+    'CMYK': { cs: 'CMYK', n: 4 },
+    'Lab ': { cs: 'Lab', n: 3 },
+  }
+  const m = map[sig]
+  if (!m) {
+    throw new PdfGenError('PDF_INVALID_COLOR', `Unsupported ICC data color space '${sig}'`)
+  }
+  return {
+    colorSpace: m.cs,
+    components: m.n,
+    profileClass: fourcc(bytes, 12),
+    pcs: fourcc(bytes, 20),
+    bytes,
+  }
+}
+
+function altName(components: 1 | 3 | 4): string {
+  return components === 1 ? 'DeviceGray' : components === 3 ? 'DeviceRGB' : 'DeviceCMYK'
+}
+
+class IccBasedColorSpace implements ManagedColorSpace {
+  readonly id: string
+  readonly components: number
+
+  constructor(
+    private readonly profile: IccProfile,
+    private readonly tag: number
+  ) {
+    this.components = profile.components
+    this.id = `icc:${profile.colorSpace}:${tag}`
+  }
+
+  build(table: ObjectTable): PdfObject {
+    const stream = makeStream(this.profile.bytes, {
+      filter: 'FlateDecode',
+      extra: {
+        N: num(this.profile.components),
+        Alternate: name(altName(this.profile.components)),
+      },
+    })
+    return arr([name('ICCBased'), table.add(stream)])
+  }
+
+  /** A color in this profile's space (components in [0,1]). */
+  color(...comps: number[]): Color {
+    return managedColor(this, comps)
+  }
+}
+
+let iccCounter = 0
+
+/** An ICCBased color space from raw ICC profile bytes (`.icc`/`.icm`). */
+export function iccBased(profileBytes: Uint8Array): IccBasedColorSpace {
+  return new IccBasedColorSpace(parseIccProfile(profileBytes), iccCounter++)
+}
+
+export type { IccBasedColorSpace }

package/src/color/index.ts

@@ -0,0 +1,15 @@
+export type { ColorSpace, Color as ColorValue, DeviceColor } from './color.ts'
+// A named re-export carries both the type and value meanings of `Color`.
+export { Color, gray, rgb, cmyk, deviceComponents, deviceSpaceName } from './color.ts'
+export { rgbToGray, cmykToRgb, rgbToCmyk } from './conversion.ts'
+export { fillColorOp, strokeColorOp } from './device.ts'
+
+export type { ManagedColorSpace, ManagedColor } from './space.ts'
+export { managedColor } from './space.ts'
+export { parseIccProfile, iccBased } from './icc.ts'
+export type { IccProfile, IccColorSpace, IccBasedColorSpace } from './icc.ts'
+export { separation, type4Function } from './separation.ts'
+export type { SeparationColorSpace } from './separation.ts'
+export { deviceN } from './devicen.ts'
+export type { DeviceNColorSpace } from './devicen.ts'
+export { calGray, calRGB, lab } from './cie.ts'

package/src/color/separation.ts

@@ -0,0 +1,94 @@
+/**
+ * Separation color space (spec §9.5) — a single spot colorant with an
+ * alternate space and a tint transform.
+ *
+ * The high-level helper emits a Type 2 (exponential) function interpolating
+ * between the alternate's zero color at tint 0 and the supplied full-strength
+ * color at tint 1 (`N = 1`, linear). Type 4 PostScript tint transforms are
+ * available via {@link deviceN} for advanced callers.
+ */
+
+import { arr, dict, name, num } from '../objects/types.ts'
+import type { PdfObject } from '../objects/types.ts'
+import { ascii } from '../util/ascii.ts'
+import type { ObjectTable } from '../document/object_table.ts'
+import type { ManagedColorSpace } from './space.ts'
+import { managedColor } from './space.ts'
+import type { Color, DeviceColor } from './color.ts'
+import { deviceComponents, deviceSpaceName } from './color.ts'
+
+class SeparationColorSpace implements ManagedColorSpace {
+  readonly id: string
+  readonly components = 1
+  private readonly altName: string
+  private readonly c1: number[]
+
+  constructor(
+    private readonly colorant: string,
+    full: DeviceColor,
+    private readonly tag: number
+  ) {
+    this.altName = deviceSpaceName(full)
+    this.c1 = deviceComponents(full)
+    this.id = `sep:${colorant}:${tag}`
+  }
+
+  build(table: ObjectTable): PdfObject {
+    const c0 = this.c1.map(() => 0)
+    const tintFn = table.add(
+      dict({
+        FunctionType: num(2),
+        Domain: arr([num(0), num(1)]),
+        C0: arr(c0.map(num)),
+        C1: arr(this.c1.map(num)),
+        N: num(1),
+      })
+    )
+    return arr([
+      name('Separation'),
+      name(this.colorant),
+      name(this.altName),
+      tintFn,
+    ])
+  }
+
+  /** A color at tint `t` in [0,1] (0 = no ink, 1 = full strength). */
+  tint(t: number): Color {
+    return managedColor(this, [t])
+  }
+}
+
+let sepCounter = 0
+
+/**
+ * A Separation (spot) color space. `full` is the colour the colorant prints
+ * at 100% tint, given in a device space (usually CMYK).
+ *
+ * ```ts
+ * const pantone = separation('PANTONE 185 C', cmyk(0, 0.91, 0.76, 0))
+ * c.setFillColor(pantone.tint(0.6))
+ * ```
+ */
+export function separation(colorant: string, full: DeviceColor): SeparationColorSpace {
+  return new SeparationColorSpace(colorant, full, sepCounter++)
+}
+
+export type { SeparationColorSpace }
+
+/** A PostScript-calculator (Type 4) function stream, for DeviceN/advanced use. */
+export function type4Function(
+  domain: number[],
+  range: number[],
+  postscript: string
+): (table: ObjectTable) => PdfObject {
+  return table =>
+    table.add({
+      kind: 'stream',
+      dict: dict({
+        FunctionType: num(4),
+        Domain: arr(domain.map(num)),
+        Range: arr(range.map(num)),
+      }),
+      data: ascii(postscript),
+    })
+}

package/src/color/space.ts

@@ -0,0 +1,47 @@
+/**
+ * Managed (non-device) color spaces (spec §9.1).
+ *
+ * DeviceGray/RGB/CMYK use the shortcut operators and need no resources. The
+ * remaining spaces — ICCBased, Separation, DeviceN, CalGray/CalRGB/Lab — are
+ * objects (a name or array, sometimes with indirect children) registered in
+ * the page `/Resources /ColorSpace` map and selected with `cs`/`CS` + `scn`.
+ *
+ * Each implementation builds its PDF object via `build(table)` and produces
+ * tinted {@link Color} values via `color(...)`.
+ */
+
+import { PdfGenError } from '../util/errors.ts'
+import type { ObjectTable } from '../document/object_table.ts'
+import type { PdfObject } from '../objects/types.ts'
+
+export interface ManagedColorSpace {
+  /** Stable identity for resource deduplication. */
+  readonly id: string
+  /** Number of colour components (operands for `scn`/`SCN`). */
+  readonly components: number
+  /** Build the color-space object, adding any child objects to the table. */
+  build(table: ObjectTable): PdfObject
+}
+
+/** A color value in a managed color space (selected via `cs`/`CS`). */
+export type ManagedColor = {
+  space: 'Managed'
+  cs: ManagedColorSpace
+  comps: number[]
+}
+
+/** Validate + build a {@link ManagedColor} for a managed space. */
+export function managedColor(cs: ManagedColorSpace, comps: number[]): ManagedColor {
+  if (comps.length !== cs.components) {
+    throw new PdfGenError(
+      'PDF_INVALID_COLOR',
+      `${cs.id} expects ${cs.components} component(s), got ${comps.length}`
+    )
+  }
+  for (const v of comps) {
+    if (!Number.isFinite(v)) {
+      throw new PdfGenError('PDF_INVALID_COLOR', `Non-finite color component in ${cs.id}`)
+    }
+  }
+  return { space: 'Managed', cs, comps }
+}