@strav/pdf 0.4.17 → 0.4.18

package/src/reader/xref.ts

@@ -0,0 +1,229 @@
+/**
+ * Cross-reference resolution (spec §7.5). Locates the trailing `startxref`,
+ * then walks the section chain — classic `xref` tables and `/Type /XRef`
+ * streams, plus the hybrid `/XRefStm` pointer — following `/Prev` to older
+ * sections. Newest section wins on conflict (first-seen during the walk).
+ */
+
+import {
+  type PdfObject,
+  type PdfDictionary,
+  isNum,
+  isArr,
+  isDict,
+  isRef,
+  isStream,
+} from '../objects/types.ts'
+import { PdfParseError } from '../util/errors.ts'
+import { decodeStream } from '../streams/decode.ts'
+import { Lexer, latin1 } from './lexer.ts'
+import { ObjectParser } from './object_parser.ts'
+
+/** Uncompressed object: byte offset. Compressed: container objstm + index. */
+export type XrefEntry =
+  | { type: 'n'; offset: number; gen: number }
+  | { type: 'c'; streamObj: number; index: number }
+
+export interface XrefTable {
+  entries: Map<number, XrefEntry>
+  trailer: PdfDictionary
+}
+
+/** Scan the tail for the last `startxref` and return its offset value. */
+export function findStartXref(buf: Uint8Array): number {
+  const needle = 'startxref'
+  const from = Math.max(0, buf.length - 2048)
+  for (let p = buf.length - needle.length; p >= from; p--) {
+    if (buf[p] === 0x73 && latin1(buf, p, p + needle.length) === needle) {
+      const lex = new Lexer(buf, p + needle.length)
+      const t = lex.next()
+      if (t.type === 'num') return t.value
+    }
+  }
+  throw new PdfParseError('No startxref found')
+}
+
+export function parseXref(buf: Uint8Array): XrefTable {
+  const entries = new Map<number, XrefEntry>()
+  let trailer: PdfDictionary | undefined
+  const visited = new Set<number>()
+  const queue: number[] = [findStartXref(buf)]
+
+  while (queue.length) {
+    const off = queue.shift()!
+    if (off < 0 || off >= buf.length || visited.has(off)) continue
+    visited.add(off)
+
+    const lex = new Lexer(buf, off)
+    const t = lex.peek()
+    let sectionTrailer: PdfDictionary
+
+    if (t.type === 'kw' && t.value === 'xref') {
+      sectionTrailer = parseClassic(buf, off, entries)
+    } else {
+      sectionTrailer = parseXrefStream(buf, off, entries)
+    }
+    if (!trailer) trailer = sectionTrailer
+
+    // Hybrid: an /XRefStm points at a parallel xref stream for this section.
+    const xrefStm = sectionTrailer.entries.get('XRefStm')
+    if (xrefStm && isNum(xrefStm)) queue.push(xrefStm.value)
+    const prev = sectionTrailer.entries.get('Prev')
+    if (prev && isNum(prev)) queue.push(prev.value)
+  }
+
+  if (!trailer) throw new PdfParseError('No trailer dictionary')
+  return { entries, trailer }
+}
+
+function setIfAbsent(map: Map<number, XrefEntry>, n: number, e: XrefEntry): void {
+  if (!map.has(n)) map.set(n, e)
+}
+
+function parseClassic(
+  buf: Uint8Array,
+  off: number,
+  entries: Map<number, XrefEntry>,
+): PdfDictionary {
+  const lex = new Lexer(buf, off)
+  lex.next() // 'xref'
+  for (;;) {
+    const a = lex.next()
+    if (a.type === 'kw' && a.value === 'trailer') break
+    if (a.type === 'eof') throw new PdfParseError('Unterminated xref table')
+    if (a.type !== 'num') throw new PdfParseError('Malformed xref subsection header')
+    const count = lex.next()
+    if (count.type !== 'num') throw new PdfParseError('Malformed xref subsection header')
+    const start = a.value
+    for (let i = 0; i < count.value; i++) {
+      const offTok = lex.next()
+      const genTok = lex.next()
+      const kind = lex.next()
+      if (offTok.type !== 'num' || genTok.type !== 'num' || kind.type !== 'kw') {
+        throw new PdfParseError('Malformed xref entry')
+      }
+      if (kind.value === 'n') {
+        setIfAbsent(entries, start + i, {
+          type: 'n',
+          offset: offTok.value,
+          gen: genTok.value,
+        })
+      }
+    }
+  }
+  // trailer << … >>
+  const parser = new ObjectParser(new Lexer(buf, lex.pos))
+  const tr = parser.parseObject()
+  if (!isDict(tr)) throw new PdfParseError('Trailer is not a dictionary')
+  return tr
+}
+
+function parseXrefStream(
+  buf: Uint8Array,
+  off: number,
+  entries: Map<number, XrefEntry>,
+): PdfDictionary {
+  const parser = new ObjectParser(new Lexer(buf, off))
+  const { value } = parser.parseIndirectAt(off)
+  if (!isStream(value)) throw new PdfParseError('Expected an xref stream object')
+  const d = value.dict
+  const data = decodeStream(d, value.data, (o) => o)
+
+  const wObj = d.entries.get('W')
+  if (!wObj || !isArr(wObj)) throw new PdfParseError('Xref stream missing /W')
+  const W = wObj.items.map((x) => (isNum(x) ? x.value : 0))
+  const [w0, w1, w2] = [W[0] ?? 0, W[1] ?? 0, W[2] ?? 0]
+  const recLen = w0 + w1 + w2
+
+  const sizeObj = d.entries.get('Size')
+  const size = sizeObj && isNum(sizeObj) ? sizeObj.value : 0
+  const indexObj = d.entries.get('Index')
+  const index: number[] =
+    indexObj && isArr(indexObj)
+      ? indexObj.items.map((x) => (isNum(x) ? x.value : 0))
+      : [0, size]
+
+  const readField = (p: number, w: number, dflt: number): number => {
+    if (w === 0) return dflt
+    let v = 0
+    for (let k = 0; k < w; k++) v = v * 256 + data[p + k]!
+    return v
+  }
+
+  let pos = 0
+  for (let s = 0; s + 1 < index.length; s += 2) {
+    const start = index[s]!
+    const cnt = index[s + 1]!
+    for (let i = 0; i < cnt && pos + recLen <= data.length; i++) {
+      const objNum = start + i
+      const type = readField(pos, w0, 1)
+      const f2 = readField(pos + w0, w1, 0)
+      const f3 = readField(pos + w0 + w1, w2, 0)
+      pos += recLen
+      if (type === 1) {
+        setIfAbsent(entries, objNum, { type: 'n', offset: f2, gen: f3 })
+      } else if (type === 2) {
+        setIfAbsent(entries, objNum, { type: 'c', streamObj: f2, index: f3 })
+      }
+    }
+  }
+  return d
+}
+
+/**
+ * Last-resort recovery: scan the whole buffer for `N G obj` headers and build
+ * an xref table from scratch (latest occurrence wins). Used when the real
+ * xref is missing or corrupt.
+ */
+export function bruteForceXref(buf: Uint8Array): XrefTable {
+  const entries = new Map<number, XrefEntry>()
+  const re = /(\d+)\s+(\d+)\s+obj\b/g
+  const text = latin1(buf, 0, buf.length)
+  let m: RegExpExecArray | null
+  while ((m = re.exec(text))) {
+    const n = Number(m[1])
+    const g = Number(m[2])
+    entries.set(n, { type: 'n', offset: m.index, gen: g })
+  }
+  // Locate a trailer dict, else synthesize from a /Root /Catalog scan.
+  let trailer: PdfDictionary | undefined
+  const tIdx = text.lastIndexOf('trailer')
+  if (tIdx >= 0) {
+    try {
+      const tr = new ObjectParser(new Lexer(buf, tIdx + 7)).parseObject()
+      if (isDict(tr)) trailer = tr
+    } catch {
+      /* fall through */
+    }
+  }
+  if (!trailer || !trailer.entries.has('Root')) {
+    trailer = synthesizeTrailer(buf, entries)
+  }
+  return { entries, trailer }
+}
+
+function synthesizeTrailer(
+  buf: Uint8Array,
+  entries: Map<number, XrefEntry>,
+): PdfDictionary {
+  for (const [n, e] of entries) {
+    if (e.type !== 'n') continue
+    try {
+      const { value } = new ObjectParser(new Lexer(buf, e.offset)).parseIndirectAt(e.offset)
+      const d = isStream(value) ? value.dict : value
+      if (isDict(d)) {
+        const ty = d.entries.get('Type')
+        if (ty && 'value' in ty && ty.value === 'Catalog') {
+          const tr: PdfDictionary = { kind: 'dict', entries: new Map() }
+          tr.entries.set('Root', { kind: 'ref', num: n, gen: e.gen })
+          return tr
+        }
+      }
+    } catch {
+      /* skip unparseable objects */
+    }
+  }
+  throw new PdfParseError('Could not recover a document catalog')
+}
+
+export { isRef }

package/src/streams/decode.ts

@@ -0,0 +1,98 @@
+/**
+ * Stream filter dispatch (read side, spec §7.4). Resolves a stream's
+ * `/Filter` + `/DecodeParms` (name or parallel arrays, possibly indirect) and
+ * applies each decode filter in order. Image filters (DCT/JPX/CCITT/JBIG2) are
+ * terminal and returned unchanged — text extraction never needs their pixels.
+ */
+
+import type { PdfDictionary, PdfObject } from '../objects/types.ts'
+import { isArr, isDict, isName, isNum } from '../objects/types.ts'
+import { flateDecode, type PredictorParams } from './flate.ts'
+import { lzwDecode } from './lzw.ts'
+import { ascii85Decode } from './ascii85.ts'
+import { asciiHexDecode } from './ascii_hex.ts'
+import { runLengthDecode } from './runlength.ts'
+
+/** Filters whose output is binary image data, not byte-stream content. */
+const IMAGE_FILTERS = new Set(['DCTDecode', 'JPXDecode', 'CCITTFaxDecode', 'JBIG2Decode'])
+
+export type Resolve = (o: PdfObject | undefined) => PdfObject | undefined
+
+function dictGet(d: PdfDictionary, key: string, resolve: Resolve): PdfObject | undefined {
+  return resolve(d.entries.get(key))
+}
+
+function asList(o: PdfObject | undefined, resolve: Resolve): (PdfObject | undefined)[] {
+  if (!o) return []
+  if (isArr(o)) return o.items.map((x) => resolve(x))
+  return [o]
+}
+
+function predictorParams(o: PdfObject | undefined, resolve: Resolve): PredictorParams &
+  { earlyChange?: number } {
+  if (!o || !isDict(o)) return {}
+  const n = (k: string): number | undefined => {
+    const v = resolve(o.entries.get(k))
+    return v && isNum(v) ? v.value : undefined
+  }
+  return {
+    predictor: n('Predictor'),
+    colors: n('Colors'),
+    bitsPerComponent: n('BitsPerComponent'),
+    columns: n('Columns'),
+    earlyChange: n('EarlyChange'),
+  }
+}
+
+/**
+ * Decode the on-disk bytes of a stream into its logical content. Returns the
+ * (possibly partially) decoded bytes; stops at the first image filter.
+ */
+export function decodeStream(
+  dict: PdfDictionary,
+  data: Uint8Array,
+  resolve: Resolve = (o) => o,
+): Uint8Array {
+  const filters = asList(
+    dictGet(dict, 'Filter', resolve) ?? dictGet(dict, 'F', resolve),
+    resolve,
+  )
+  if (filters.length === 0) return data
+
+  const parmsRaw = dictGet(dict, 'DecodeParms', resolve) ?? dictGet(dict, 'DP', resolve)
+  const parmsList = asList(parmsRaw, resolve)
+
+  let out = data
+  for (let i = 0; i < filters.length; i++) {
+    const f = filters[i]
+    if (!f || !isName(f)) continue
+    const parms = predictorParams(parmsList[i], resolve)
+    switch (f.value) {
+      case 'FlateDecode':
+      case 'Fl':
+        out = flateDecode(out, parms)
+        break
+      case 'LZWDecode':
+      case 'LZW':
+        out = lzwDecode(out, parms)
+        break
+      case 'ASCII85Decode':
+      case 'A85':
+        out = ascii85Decode(out)
+        break
+      case 'ASCIIHexDecode':
+      case 'AHx':
+        out = asciiHexDecode(out)
+        break
+      case 'RunLengthDecode':
+      case 'RL':
+        out = runLengthDecode(out)
+        break
+      default:
+        if (IMAGE_FILTERS.has(f.value)) return out // terminal: leave encoded
+        // Unknown filter — return what we have rather than corrupt further.
+        return out
+    }
+  }
+  return out
+}

package/src/streams/flate.ts

@@ -1,17 +1,107 @@
 /**
  * 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.
+ * (project decision).
+ *
+ * Encoding never applies a predictor. Decoding (read side, M13) supports the
+ * PNG (10–15) and TIFF (2) predictors via /DecodeParms (spec §7.4.4.4), which
+ * real-world PDFs commonly use for xref and image streams.
  */
 
 import { deflateSync, inflateSync } from 'node:zlib'
 
+/** Predictor parameters from a stream's /DecodeParms (spec §7.4.4.4). */
+export interface PredictorParams {
+  /** 1 = none, 2 = TIFF, 10–15 = PNG (the exact PNG type is per-row). */
+  predictor?: number
+  /** Samples per pixel. Default 1. */
+  colors?: number
+  /** Bits per component. Default 8. */
+  bitsPerComponent?: number
+  /** Samples per row. Default 1. */
+  columns?: number
+}
+
 /** 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))
+/**
+ * Inflate, then reverse the predictor if one is configured. Falls back to a
+ * raw-deflate retry (`-15` window) for the malformed-zlib-header streams some
+ * producers emit.
+ */
+export function flateDecode(data: Uint8Array, params?: PredictorParams): Uint8Array {
+  let out: Uint8Array
+  try {
+    out = new Uint8Array(inflateSync(data))
+  } catch {
+    out = new Uint8Array(inflateSync(data, { finishFlush: 2 /* Z_SYNC_FLUSH */ }))
+  }
+  return params && (params.predictor ?? 1) > 1 ? unpredict(out, params) : out
+}
+
+/** Reverse a PNG/TIFF predictor (spec §7.4.4.4). Exported for other filters. */
+export function unpredict(data: Uint8Array, params: PredictorParams): Uint8Array {
+  const predictor = params.predictor ?? 1
+  if (predictor <= 1) return data
+
+  const colors = params.colors ?? 1
+  const bpc = params.bitsPerComponent ?? 8
+  const columns = params.columns ?? 1
+  const bpp = Math.ceil((colors * bpc) / 8) // bytes per pixel (≥1)
+  const rowBytes = Math.ceil((colors * bpc * columns) / 8)
+
+  if (predictor === 2) {
+    // TIFF predictor 2: horizontal differencing, per-component.
+    if (bpc !== 8) return data // sub-byte TIFF predictor: rare, left as-is
+    const out = data.slice()
+    for (let r = 0; r + rowBytes <= out.length; r += rowBytes) {
+      for (let i = bpp; i < rowBytes; i++) {
+        out[r + i] = (out[r + i]! + out[r + i - bpp]!) & 0xff
+      }
+    }
+    return out
+  }
+
+  // PNG predictors: each row is prefixed by a 1-byte filter type.
+  const rows = Math.floor(data.length / (rowBytes + 1))
+  const out = new Uint8Array(rows * rowBytes)
+  const prev = new Uint8Array(rowBytes)
+  let src = 0
+  let dst = 0
+  for (let r = 0; r < rows; r++) {
+    const type = data[src++]!
+    const row = data.subarray(src, src + rowBytes)
+    src += rowBytes
+    for (let i = 0; i < rowBytes; i++) {
+      const a = i >= bpp ? out[dst + i - bpp]! : 0 // left
+      const b = prev[i]! // up
+      const c = i >= bpp ? prev[i - bpp]! : 0 // upper-left
+      let v = row[i]!
+      switch (type) {
+        case 0: break // None
+        case 1: v = (v + a) & 0xff; break // Sub
+        case 2: v = (v + b) & 0xff; break // Up
+        case 3: v = (v + ((a + b) >> 1)) & 0xff; break // Average
+        case 4: v = (v + paeth(a, b, c)) & 0xff; break // Paeth
+        default: break
+      }
+      out[dst + i] = v
+    }
+    prev.set(out.subarray(dst, dst + rowBytes))
+    dst += rowBytes
+  }
+  return out
+}
+
+function paeth(a: number, b: number, c: number): number {
+  const p = a + b - c
+  const pa = Math.abs(p - a)
+  const pb = Math.abs(p - b)
+  const pc = Math.abs(p - c)
+  if (pa <= pb && pa <= pc) return a
+  if (pb <= pc) return b
+  return c
 }

package/src/streams/index.ts

@@ -4,6 +4,11 @@ export {
   MIN_FILTER_BYTES,
 } from './stream.ts'
 export type { FilterName, MakeStreamOptions } from './stream.ts'
-export { flateEncode, flateDecode } from './flate.ts'
+export { flateEncode, flateDecode, unpredict } from './flate.ts'
+export type { PredictorParams } from './flate.ts'
 export { ascii85Encode, ascii85Decode } from './ascii85.ts'
 export { asciiHexEncode, asciiHexDecode } from './ascii_hex.ts'
+export { lzwDecode } from './lzw.ts'
+export { runLengthDecode } from './runlength.ts'
+export { decodeStream } from './decode.ts'
+export type { Resolve } from './decode.ts'

package/src/streams/lzw.ts

@@ -0,0 +1,74 @@
+/**
+ * LZWDecode (spec §7.4.4). Variable-width codes 9–12 bits, MSB-first. Code 256
+ * = clear table, 257 = EOD. `earlyChange` (default 1) bumps the code width one
+ * code early, matching Adobe's encoder. A predictor may follow (spec §7.4.4.4).
+ *
+ * Decode-only — the writer never emits LZW.
+ */
+
+import { unpredict, type PredictorParams } from './flate.ts'
+
+const CLEAR = 256
+const EOD = 257
+
+export function lzwDecode(
+  data: Uint8Array,
+  params?: PredictorParams & { earlyChange?: number },
+): Uint8Array {
+  const earlyChange = params?.earlyChange ?? 1
+  const out: number[] = []
+
+  let bitBuf = 0
+  let bitCnt = 0
+  let pos = 0
+  const next = (width: number): number => {
+    while (bitCnt < width) {
+      if (pos >= data.length) return EOD
+      bitBuf = (bitBuf << 8) | data[pos++]!
+      bitCnt += 8
+    }
+    bitCnt -= width
+    return (bitBuf >> bitCnt) & ((1 << width) - 1)
+  }
+
+  let dict: number[][] = []
+  let width = 9
+  const reset = () => {
+    dict = []
+    for (let i = 0; i < 256; i++) dict[i] = [i]
+    dict[CLEAR] = []
+    dict[EOD] = []
+    width = 9
+  }
+  reset()
+
+  let prev: number[] | null = null
+  for (;;) {
+    const code = next(width)
+    if (code === EOD) break
+    if (code === CLEAR) {
+      reset()
+      prev = null
+      continue
+    }
+
+    let entry: number[]
+    if (dict[code]) {
+      entry = dict[code]!
+    } else if (code === dict.length && prev) {
+      entry = [...prev, prev[0]!]
+    } else {
+      break // corrupt stream — stop gracefully
+    }
+    for (const b of entry) out.push(b)
+
+    if (prev) {
+      dict.push([...prev, entry[0]!])
+      if (dict.length + earlyChange >= 1 << width && width < 12) width++
+    }
+    prev = entry
+  }
+
+  const bytes = Uint8Array.from(out)
+  return params && (params.predictor ?? 1) > 1 ? unpredict(bytes, params) : bytes
+}

package/src/streams/runlength.ts

@@ -0,0 +1,25 @@
+/**
+ * RunLengthDecode (spec §7.4.5). Length byte L:
+ *   0–127  → copy the next L+1 bytes literally
+ *   129–255→ repeat the next single byte 257−L times
+ *   128    → EOD
+ *
+ * Decode-only — the writer never emits RunLength.
+ */
+
+export function runLengthDecode(data: Uint8Array): Uint8Array {
+  const out: number[] = []
+  let i = 0
+  while (i < data.length) {
+    const len = data[i++]!
+    if (len === 128) break // EOD
+    if (len < 128) {
+      for (let k = 0; k <= len && i < data.length; k++) out.push(data[i++]!)
+    } else {
+      if (i >= data.length) break
+      const b = data[i++]!
+      for (let k = 0; k < 257 - len; k++) out.push(b)
+    }
+  }
+  return Uint8Array.from(out)
+}

package/src/util/errors.ts

@@ -23,6 +23,9 @@ export type PdfGenErrorCode =
   | 'PDF_TEXT_STATE'
   | 'PDF_TEXT_ENCODING'
   | 'PDF_NO_FONT'
+  | 'PDF_PARSE'
+  | 'PDF_ENCRYPTED'
+  | 'PDF_UNSUPPORTED_DECODE'
 
 export class PdfGenError extends Error {
   readonly code: PdfGenErrorCode
@@ -59,3 +62,20 @@ export class InvalidImageError extends PdfGenError {
     super('PDF_INVALID_IMAGE', message)
   }
 }
+
+/** Thrown when an existing PDF cannot be parsed (read side, M13). */
+export class PdfParseError extends PdfGenError {
+  constructor(message: string) {
+    super('PDF_PARSE', message)
+  }
+}
+
+/**
+ * Thrown when a PDF is encrypted in a way M13 does not support: a non-empty
+ * user password, or a non-standard / unsupported security handler.
+ */
+export class EncryptedPdfError extends PdfGenError {
+  constructor(message: string) {
+    super('PDF_ENCRYPTED', message)
+  }
+}