@strav/pdf 0.4.17

package/src/patterns/index.ts

@@ -0,0 +1,10 @@
+export { tilingPattern } from './tiling_pattern.ts'
+export type { TilingPattern, TilingPatternOptions } from './tiling_pattern.ts'
+export { axialShading, radialShading, shadingPattern } from './shading.ts'
+export type {
+  Shading,
+  ShadingPattern,
+  ColorStop,
+  AxialOptions,
+  RadialOptions,
+} from './shading.ts'

package/src/patterns/shading.ts

@@ -0,0 +1,162 @@
+/**
+ * Axial (type 2) and radial (type 3) shadings (spec §12.2). The color ramp is
+ * a Type-2 exponential function for two stops, or a Type-3 stitching function
+ * for more. Types 1 and 4–7 are reachable by adding raw objects.
+ *
+ * A `Shading` paints via the `sh` operator; wrap it with `shadingPattern` to
+ * use it as a fill/stroke pattern (PatternType 2).
+ */
+
+import { PdfGenError } from '../util/errors.ts'
+import { arr, bool, dict, name, num } from '../objects/types.ts'
+import type { PdfObject } from '../objects/types.ts'
+import type { ObjectTable } from '../document/object_table.ts'
+import type { DeviceColor } from '../color/color.ts'
+import { deviceComponents, deviceSpaceName } from '../color/color.ts'
+
+export interface ColorStop {
+  /** Position in [0,1]. */
+  offset: number
+  color: DeviceColor
+}
+
+function buildFunction(stops: ColorStop[]): PdfObject {
+  if (stops.length < 2) {
+    throw new PdfGenError('PDF_INVALID_COLOR', 'A shading needs at least two color stops')
+  }
+  const space = stops[0]!.color.space
+  for (const s of stops) {
+    if (s.color.space !== space) {
+      throw new PdfGenError('PDF_INVALID_COLOR', 'All shading stops must share one color space')
+    }
+  }
+  const seg = (a: DeviceColor, b: DeviceColor): PdfObject =>
+    dict({
+      FunctionType: num(2),
+      Domain: arr([num(0), num(1)]),
+      C0: arr(deviceComponents(a).map(num)),
+      C1: arr(deviceComponents(b).map(num)),
+      N: num(1),
+    })
+
+  if (stops.length === 2) return seg(stops[0]!.color, stops[1]!.color)
+
+  // Type-3 stitching of consecutive Type-2 segments.
+  const fns: PdfObject[] = []
+  const bounds: PdfObject[] = []
+  const encode: PdfObject[] = []
+  for (let i = 0; i < stops.length - 1; i++) {
+    fns.push(seg(stops[i]!.color, stops[i + 1]!.color))
+    encode.push(num(0), num(1))
+    if (i > 0) bounds.push(num(stops[i]!.offset))
+  }
+  return dict({
+    FunctionType: num(3),
+    Domain: arr([num(0), num(1)]),
+    Functions: arr(fns),
+    Bounds: arr(bounds),
+    Encode: arr(encode),
+  })
+}
+
+function colorSpaceName(stops: ColorStop[]): string {
+  return deviceSpaceName(stops[0]!.color)
+}
+
+function normalizeStops(colors: DeviceColor[] | ColorStop[]): ColorStop[] {
+  const first = colors[0]
+  if (first && 'color' in first) return colors as ColorStop[]
+  const cs = colors as DeviceColor[]
+  return cs.map((color, i) => ({ offset: i / (cs.length - 1), color }))
+}
+
+class Shading {
+  readonly id: string
+  constructor(
+    private readonly shadingType: 2 | 3,
+    private readonly coords: number[],
+    private readonly stops: ColorStop[],
+    private readonly extend: [boolean, boolean],
+    tag: number
+  ) {
+    this.id = `sh${shadingType}:${tag}`
+  }
+
+  build(_table: ObjectTable): PdfObject {
+    return dict({
+      ShadingType: num(this.shadingType),
+      ColorSpace: name(colorSpaceName(this.stops)),
+      Coords: arr(this.coords.map(num)),
+      Function: buildFunction(this.stops),
+      Extend: arr([bool(this.extend[0]), bool(this.extend[1])]),
+    })
+  }
+}
+
+let shCounter = 0
+
+export interface AxialOptions {
+  from: [number, number]
+  to: [number, number]
+  colors: DeviceColor[] | ColorStop[]
+  extend?: [boolean, boolean]
+}
+
+/** A type-2 (axial / linear-gradient) shading. */
+export function axialShading(o: AxialOptions): Shading {
+  return new Shading(
+    2,
+    [o.from[0], o.from[1], o.to[0], o.to[1]],
+    normalizeStops(o.colors),
+    o.extend ?? [true, true],
+    shCounter++
+  )
+}
+
+export interface RadialOptions {
+  from: { x: number; y: number; r: number }
+  to: { x: number; y: number; r: number }
+  colors: DeviceColor[] | ColorStop[]
+  extend?: [boolean, boolean]
+}
+
+/** A type-3 (radial) shading. */
+export function radialShading(o: RadialOptions): Shading {
+  return new Shading(
+    3,
+    [o.from.x, o.from.y, o.from.r, o.to.x, o.to.y, o.to.r],
+    normalizeStops(o.colors),
+    o.extend ?? [true, true],
+    shCounter++
+  )
+}
+
+class ShadingPattern {
+  readonly id: string
+  constructor(
+    private readonly shading: Shading,
+    private readonly matrix: number[] | undefined,
+    tag: number
+  ) {
+    this.id = `shp:${shading.id}:${tag}`
+  }
+
+  build(table: ObjectTable): PdfObject {
+    const d = dict({
+      Type: name('Pattern'),
+      PatternType: num(2),
+      Shading: this.shading.build(table),
+    })
+    if (this.matrix) d.entries.set('Matrix', arr(this.matrix.map(num)))
+    return table.add(d)
+  }
+}
+
+let shpCounter = 0
+
+/** Wrap a shading as a pattern (use with `setFillPattern`/`setStrokePattern`). */
+export function shadingPattern(shading: Shading, matrix?: number[]): ShadingPattern {
+  return new ShadingPattern(shading, matrix, shpCounter++)
+}
+
+export type { Shading, ShadingPattern }

package/src/patterns/tiling_pattern.ts

@@ -0,0 +1,68 @@
+/**
+ * Tiling pattern (spec §12.1). The draw callback receives a content-stream
+ * builder scoped to the pattern cell; its own resources (colors, images,
+ * fonts) are collected into the pattern's `/Resources`. A colored pattern
+ * (PaintType 1) carries its own color; an uncolored one (PaintType 2) is
+ * tinted by the caller's current color.
+ */
+
+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 { ContentStream } from '../content/content_stream.ts'
+
+export interface TilingPatternOptions {
+  /** Pattern cell bounding box `[llx lly urx ury]`. */
+  bbox: [number, number, number, number]
+  xStep: number
+  yStep: number
+  /** `'colored'` (default) carries its own color; `'uncolored'` is tinted. */
+  paintType?: 'colored' | 'uncolored'
+  /** Optional pattern→page transform. */
+  matrix?: number[]
+  draw: (c: ContentStream) => void
+}
+
+class TilingPattern {
+  readonly id: string
+  /** `'colored'` patterns set color in the cell; `'uncolored'` are tinted. */
+  readonly paintType: 'colored' | 'uncolored'
+
+  constructor(
+    private readonly opts: TilingPatternOptions,
+    tag: number
+  ) {
+    this.paintType = opts.paintType ?? 'colored'
+    this.id = `tile:${tag}`
+  }
+
+  build(table: ObjectTable): PdfObject {
+    const cell = new ContentStream()
+    this.opts.draw(cell)
+    cell.assertBalanced()
+    const resources = cell.buildResources(table) // children added to table
+    const [x0, y0, x1, y1] = this.opts.bbox
+    const extra: Record<string, PdfObject> = {
+      Type: name('Pattern'),
+      PatternType: num(1),
+      PaintType: num(this.paintType === 'colored' ? 1 : 2),
+      TilingType: num(1),
+      BBox: arr([x0, y0, x1, y1].map(num)),
+      XStep: num(this.opts.xStep),
+      YStep: num(this.opts.yStep),
+      Resources: resources,
+    }
+    if (this.opts.matrix) extra.Matrix = arr(this.opts.matrix.map(num))
+    return table.add(makeStream(cell.toBytes(), { filter: 'FlateDecode', extra }))
+  }
+}
+
+let tileCounter = 0
+
+/** Create a tiling pattern (use with `ContentStream.setFillPattern`). */
+export function tilingPattern(opts: TilingPatternOptions): TilingPattern {
+  return new TilingPattern(opts, tileCounter++)
+}
+
+export type { TilingPattern }

package/src/standards/context.ts

@@ -0,0 +1,10 @@
+/** Inputs to the conformance validators (gathered by PdfDocument at save). */
+export interface ConformanceContext {
+  /** One entry per page; whether it has a TrimBox or ArtBox set. */
+  pages: { hasTrimOrArt: boolean }[]
+  outputIntent: {
+    present: boolean
+    /** ICC data color space of the destination profile, if present. */
+    profileColorSpace?: 'GRAY' | 'RGB' | 'CMYK' | 'Lab'
+  }
+}

package/src/standards/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Conformance dispatch (spec §15). `setConformance(...)` opts in; validation
+ * runs at `save()` and a non-empty result becomes a `ConformanceError`.
+ */
+
+import type { ConformanceLevel } from '../document/types.ts'
+import type { ConformanceContext } from './context.ts'
+import { validatePdfA } from './pdf_a.ts'
+import { validatePdfX } from './pdf_x.ts'
+
+export type { ConformanceContext } from './context.ts'
+export { validatePdfA } from './pdf_a.ts'
+export { validatePdfX } from './pdf_x.ts'
+
+/** Returns all conformance violations for `level` (empty = conforms). */
+export function validateConformance(
+  level: ConformanceLevel,
+  ctx: ConformanceContext
+): string[] {
+  if (level === 'PDF/A-2b') return validatePdfA(ctx)
+  if (level === 'PDF/X-4') return validatePdfX(ctx)
+  return []
+}

package/src/standards/pdf_a.ts

@@ -0,0 +1,23 @@
+/**
+ * PDF/A-2b conformance checks (spec §15.1). Returns the list of violations
+ * (empty = conforms). Font rules — all fonts embedded, ToUnicode present, no
+ * Standard-14 — are enforced earlier: a Standard-14 font under a conformance
+ * mode throws `UnsupportedFontError`, and embedded fonts always carry a
+ * ToUnicode CMap and are subsetted, so they need no check here.
+ *
+ * Not checked (out of scope / not producible by this library): encryption,
+ * LZWDecode, JavaScript, external references — none are ever emitted.
+ */
+
+import type { ConformanceContext } from './context.ts'
+
+export function validatePdfA(ctx: ConformanceContext): string[] {
+  const v: string[] = []
+  if (!ctx.outputIntent.present) {
+    v.push(
+      'PDF/A-2b requires an OutputIntent (the all-DeviceGray exception is not ' +
+        'auto-detected — call setOutputIntent)'
+    )
+  }
+  return v
+}

package/src/standards/pdf_x.ts

@@ -0,0 +1,31 @@
+/**
+ * PDF/X-4 conformance checks (spec §15.2). Returns the list of violations.
+ *
+ * Enforced here: an OutputIntent with a CMYK/Gray destination profile, and a
+ * TrimBox or ArtBox on every page (MediaBox always exists). Embedded-and-
+ * subsetted fonts and the `/ID` array are guaranteed by the library; the
+ * no-Standard-14 rule throws `UnsupportedFontError` earlier.
+ */
+
+import type { ConformanceContext } from './context.ts'
+
+export function validatePdfX(ctx: ConformanceContext): string[] {
+  const v: string[] = []
+
+  if (!ctx.outputIntent.present) {
+    v.push('PDF/X-4 requires an OutputIntent — call setOutputIntent()')
+  } else {
+    const cs = ctx.outputIntent.profileColorSpace
+    if (cs !== 'CMYK' && cs !== 'GRAY') {
+      v.push(`PDF/X-4 output intent profile must be CMYK or Gray (got ${cs ?? 'unknown'})`)
+    }
+  }
+
+  ctx.pages.forEach((p, i) => {
+    if (!p.hasTrimOrArt) {
+      v.push(`PDF/X-4 page ${i + 1} requires a TrimBox or ArtBox (MediaBox alone is not enough)`)
+    }
+  })
+
+  return v
+}

package/src/streams/ascii85.ts

@@ -0,0 +1,61 @@
+/**
+ * ASCII85Decode (spec §7.1). Available; not used by default. Adobe variant:
+ * 4-byte groups → 5 chars offset by '!' (0x21); an all-zero group is 'z';
+ * the stream ends with the `~>` EOD marker.
+ */
+
+export function ascii85Encode(data: Uint8Array): Uint8Array {
+  const out: number[] = []
+  for (let i = 0; i < data.length; i += 4) {
+    const len = Math.min(4, data.length - i)
+    let word = 0
+    for (let j = 0; j < 4; j++) {
+      word = (word * 256 + (j < len ? data[i + j]! : 0)) >>> 0
+    }
+    if (len === 4 && word === 0) {
+      out.push(0x7a) // 'z'
+      continue
+    }
+    const group = [0, 0, 0, 0, 0]
+    for (let k = 4; k >= 0; k--) {
+      group[k] = word % 85
+      word = Math.floor(word / 85)
+    }
+    for (let k = 0; k < len + 1; k++) out.push(group[k]! + 0x21)
+  }
+  out.push(0x7e, 0x3e) // ~>
+  return Uint8Array.from(out)
+}
+
+export function ascii85Decode(data: Uint8Array): Uint8Array {
+  const out: number[] = []
+  const group: number[] = []
+  for (let i = 0; i < data.length; i++) {
+    const b = data[i]!
+    if (b === 0x7e) break // ~ (start of ~>)
+    if (b === 0x20 || b === 0x09 || b === 0x0a || b === 0x0d || b === 0x0c) continue
+    if (b === 0x7a) {
+      // 'z' — only valid between groups
+      if (group.length !== 0) throw new Error('Unexpected z in ASCII85 group')
+      out.push(0, 0, 0, 0)
+      continue
+    }
+    group.push(b - 0x21)
+    if (group.length === 5) {
+      let word = 0
+      for (const g of group) word = word * 85 + g
+      out.push((word >>> 24) & 0xff, (word >>> 16) & 0xff, (word >>> 8) & 0xff, word & 0xff)
+      group.length = 0
+    }
+  }
+  if (group.length === 1) throw new Error('Truncated ASCII85 group')
+  if (group.length > 1) {
+    const n = group.length
+    while (group.length < 5) group.push(84)
+    let word = 0
+    for (const g of group) word = word * 85 + g
+    const bytes = [(word >>> 24) & 0xff, (word >>> 16) & 0xff, (word >>> 8) & 0xff, word & 0xff]
+    for (let k = 0; k < n - 1; k++) out.push(bytes[k]!)
+  }
+  return Uint8Array.from(out)
+}

package/src/streams/ascii_hex.ts

@@ -0,0 +1,33 @@
+/**
+ * ASCIIHexDecode (spec §7.1). Available; not used by default. Each byte → two
+ * uppercase hex digits, terminated by the `>` EOD marker.
+ */
+
+const HEX = '0123456789ABCDEF'
+
+export function asciiHexEncode(data: Uint8Array): Uint8Array {
+  const out = new Uint8Array(data.length * 2 + 1)
+  let i = 0
+  for (const b of data) {
+    out[i++] = HEX.charCodeAt(b >> 4)
+    out[i++] = HEX.charCodeAt(b & 0x0f)
+  }
+  out[i] = 0x3e // >
+  return out
+}
+
+export function asciiHexDecode(data: Uint8Array): Uint8Array {
+  const nibbles: number[] = []
+  for (const b of data) {
+    if (b === 0x3e) break // > EOD
+    if (b === 0x20 || b === 0x09 || b === 0x0a || b === 0x0d || b === 0x0c) continue
+    const c = String.fromCharCode(b)
+    const v = parseInt(c, 16)
+    if (Number.isNaN(v)) throw new Error(`Invalid ASCIIHex digit: ${c}`)
+    nibbles.push(v)
+  }
+  if (nibbles.length % 2 === 1) nibbles.push(0) // odd → last nibble is 0
+  const out = new Uint8Array(nibbles.length / 2)
+  for (let j = 0; j < out.length; j++) out[j] = (nibbles[2 * j]! << 4) | nibbles[2 * j + 1]!
+  return out
+}

package/src/streams/flate.ts

@@ -0,0 +1,17 @@
+/**
+ * FlateDecode (spec §7.2). Node/Bun build only — `node:zlib` at level 9 for
+ * deterministic output (level affects the byte sequence). No browser fallback
+ * (project decision); no PNG/TIFF predictor in v1.
+ */
+
+import { deflateSync, inflateSync } from 'node:zlib'
+
+/** Deflate (zlib) encode at level 9. */
+export function flateEncode(data: Uint8Array): Uint8Array {
+  return new Uint8Array(deflateSync(data, { level: 9 }))
+}
+
+/** Inflate — not used in production output; provided for round-trip tests. */
+export function flateDecode(data: Uint8Array): Uint8Array {
+  return new Uint8Array(inflateSync(data))
+}

package/src/streams/index.ts

@@ -0,0 +1,9 @@
+export {
+  makeStream,
+  makeContentStream,
+  MIN_FILTER_BYTES,
+} from './stream.ts'
+export type { FilterName, MakeStreamOptions } from './stream.ts'
+export { flateEncode, flateDecode } from './flate.ts'
+export { ascii85Encode, ascii85Decode } from './ascii85.ts'
+export { asciiHexEncode, asciiHexDecode } from './ascii_hex.ts'

package/src/streams/stream.ts

@@ -0,0 +1,66 @@
+/**
+ * Stream construction (spec §7). Filters are applied *here*, at construction
+ * time: the resulting {@link PdfStream}'s `data` is always the final on-disk
+ * bytes and `/Length` is its filtered length. The library never stores
+ * unfiltered data alongside a filter chain.
+ */
+
+import type { PdfObject, PdfStream } from '../objects/types.ts'
+import { dict, name, num } from '../objects/types.ts'
+import { flateEncode } from './flate.ts'
+import { ascii85Encode } from './ascii85.ts'
+import { asciiHexEncode } from './ascii_hex.ts'
+
+export type FilterName = 'FlateDecode' | 'ASCII85Decode' | 'ASCIIHexDecode'
+
+/** Streams below this size aren't worth filtering (spec §7.3). */
+export const MIN_FILTER_BYTES = 64
+
+export interface MakeStreamOptions {
+  /**
+   * `'auto'` (default) FlateDecodes when worthwhile; `'none'` never filters;
+   * or force a specific filter.
+   */
+  filter?: 'auto' | 'none' | FilterName
+  /** Data is already compressed (e.g. JPEG/DCT) — never re-filter (§7.3). */
+  alreadyCompressed?: boolean
+  /** Extra dictionary entries (e.g. /Type, /Subtype for XObjects). */
+  extra?: Record<string, PdfObject>
+}
+
+function applyFilter(data: Uint8Array, f: FilterName): Uint8Array {
+  switch (f) {
+    case 'FlateDecode':
+      return flateEncode(data)
+    case 'ASCII85Decode':
+      return ascii85Encode(data)
+    case 'ASCIIHexDecode':
+      return asciiHexEncode(data)
+  }
+}
+
+export function makeStream(raw: Uint8Array, opts: MakeStreamOptions = {}): PdfStream {
+  const mode = opts.filter ?? 'auto'
+
+  let filter: FilterName | null
+  if (mode === 'none' || opts.alreadyCompressed) {
+    filter = null
+  } else if (mode === 'auto') {
+    filter = raw.length >= MIN_FILTER_BYTES ? 'FlateDecode' : null
+  } else {
+    filter = mode
+  }
+
+  const data = filter ? applyFilter(raw, filter) : raw
+
+  const entries: Record<string, PdfObject> = { ...opts.extra }
+  if (filter) entries.Filter = name(filter)
+  entries.Length = num(data.length)
+
+  return { kind: 'stream', dict: dict(entries), data }
+}
+
+/** Page/Form content stream: auto-compressed (spec §7.1 default). */
+export function makeContentStream(raw: Uint8Array): PdfStream {
+  return makeStream(raw, { filter: 'auto' })
+}

package/src/util/ascii.ts

@@ -0,0 +1,63 @@
+/**
+ * ASCII byte helpers. PDF tokens are ASCII; we work at the byte level to keep
+ * serialization deterministic and free of platform text-encoding surprises.
+ */
+
+const encoder = new TextEncoder()
+
+/** Encode an ASCII/Latin-1 string to bytes. Throws on non-Latin-1 input. */
+export function ascii(s: string): Uint8Array {
+  const out = new Uint8Array(s.length)
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    if (c > 0xff) {
+      throw new Error(`Non-Latin-1 character at index ${i}: U+${c.toString(16)}`)
+    }
+    out[i] = c
+  }
+  return out
+}
+
+/** Encode a string as UTF-8 bytes (used for XMP, ToUnicode CMap text, etc.). */
+export function utf8(s: string): Uint8Array {
+  return encoder.encode(s)
+}
+
+/** Concatenate byte chunks into a single Uint8Array. */
+export function concatBytes(chunks: readonly Uint8Array[]): Uint8Array {
+  let total = 0
+  for (const c of chunks) total += c.length
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const c of chunks) {
+    out.set(c, offset)
+    offset += c.length
+  }
+  return out
+}
+
+// Common single bytes used by the encoder.
+export const SPACE = 0x20
+export const LF = 0x0a
+export const CR = 0x0d
+
+/** True for PDF whitespace bytes (ISO 32000-1 Table 1). */
+export function isWhitespace(b: number): boolean {
+  return b === 0x00 || b === 0x09 || b === 0x0a || b === 0x0c || b === 0x0d || b === 0x20
+}
+
+/** True for PDF delimiter bytes (ISO 32000-1 Table 2). */
+export function isDelimiter(b: number): boolean {
+  return (
+    b === 0x28 || // (
+    b === 0x29 || // )
+    b === 0x3c || // <
+    b === 0x3e || // >
+    b === 0x5b || // [
+    b === 0x5d || // ]
+    b === 0x7b || // {
+    b === 0x7d || // }
+    b === 0x2f || // /
+    b === 0x25 // %
+  )
+}

package/src/util/binary.ts

@@ -0,0 +1,71 @@
+/**
+ * Big-endian binary readers and fixed-point helpers.
+ *
+ * Minimal in M1–M3 (only needed by document ID hashing helpers and future
+ * font/image parsers). SFNT/JPEG/PNG parsing in later milestones builds on
+ * this without restructuring.
+ */
+
+export class BinaryReader {
+  private readonly view: DataView
+  private offset = 0
+
+  constructor(
+    private readonly bytes: Uint8Array,
+    offset = 0
+  ) {
+    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+    this.offset = offset
+  }
+
+  get position(): number {
+    return this.offset
+  }
+
+  seek(offset: number): void {
+    this.offset = offset
+  }
+
+  u8(): number {
+    return this.view.getUint8(this.offset++)
+  }
+
+  u16(): number {
+    const v = this.view.getUint16(this.offset, false)
+    this.offset += 2
+    return v
+  }
+
+  i16(): number {
+    const v = this.view.getInt16(this.offset, false)
+    this.offset += 2
+    return v
+  }
+
+  u32(): number {
+    const v = this.view.getUint32(this.offset, false)
+    this.offset += 4
+    return v
+  }
+
+  /** Read `n` raw bytes as a subarray (no copy). */
+  bytesOf(n: number): Uint8Array {
+    const out = this.bytes.subarray(this.offset, this.offset + n)
+    this.offset += n
+    return out
+  }
+
+  get remaining(): number {
+    return this.bytes.length - this.offset
+  }
+}
+
+/** Convert a signed 16.16 fixed-point value to a float. */
+export function fixed1616(raw: number): number {
+  return raw / 65536
+}
+
+/** Convert a signed 2.14 fixed-point value (F2Dot14) to a float. */
+export function f2dot14(raw: number): number {
+  return (raw << 16) / (1 << 30)
+}