@strav/pdf 0.4.17

package/src/content/content_stream.ts

@@ -0,0 +1,373 @@
+/**
+ * Fluent, chainable content-stream builder (spec §8). Operator order matches
+ * call order and numbers use the shared serializer, so output is deterministic
+ * (§8.5). Graphics-state balance and current-path consumption are enforced;
+ * violations throw at `assertBalanced()` (called from `PdfDocument.save()`).
+ */
+
+import { ascii } from '../util/ascii.ts'
+import { PdfGenError } from '../util/errors.ts'
+import { formatNumber } from '../objects/number.ts'
+import { dict } from '../objects/types.ts'
+import type { PdfDictionary } from '../objects/types.ts'
+import type { ObjectTable } from '../document/object_table.ts'
+import type { Color } from '../color/color.ts'
+import type { PdfFont } from '../fonts/font.ts'
+import type { PdfImage } from '../images/image.ts'
+import type { Buildable } from './resources.ts'
+import { fillColorOp, strokeColorOp } from '../color/device.ts'
+import { OP } from './operators.ts'
+import {
+  type GraphicsState,
+  type Matrix,
+  cloneState,
+  initialState,
+  multiply,
+} from './graphics_state.ts'
+import { PathTracker } from './path.ts'
+import { ResourceCollector } from './resources.ts'
+import { TextObject } from './text_object.ts'
+
+function n(v: number): string {
+  return formatNumber(v)
+}
+
+export class ContentStream {
+  private readonly lines: string[] = []
+  private readonly stack: GraphicsState[] = []
+  private state: GraphicsState = initialState()
+  private readonly path = new PathTracker()
+  private readonly resources = new ResourceCollector()
+  private inText = false
+
+  private emit(line: string): this {
+    this.lines.push(line)
+    return this
+  }
+
+  /** Reject graphics/path operators that are illegal inside a BT…ET block. */
+  private assertNotInText(op: string): void {
+    if (this.inText) {
+      throw new PdfGenError(
+        'PDF_TEXT_STATE',
+        `${op} is not allowed inside a text() block (BT…ET)`
+      )
+    }
+  }
+
+  // ── Graphics state ──────────────────────────────────────────────────────
+
+  save(): this {
+    this.assertNotInText('q (save)')
+    this.path.assertClear('q (save)')
+    this.stack.push(cloneState(this.state))
+    return this.emit(OP.save)
+  }
+
+  restore(): this {
+    this.assertNotInText('Q (restore)')
+    this.path.assertClear('Q (restore)')
+    const prev = this.stack.pop()
+    if (!prev) {
+      throw new PdfGenError(
+        'PDF_UNBALANCED_GRAPHICS_STATE',
+        'restore() with no matching save()'
+      )
+    }
+    this.state = prev
+    return this.emit(OP.restore)
+  }
+
+  /** Concatenate a matrix to the CTM (`a b c d e f cm`). */
+  transform(m: Matrix): this {
+    this.assertNotInText('cm (transform)')
+    this.state.ctm = multiply(m, this.state.ctm)
+    return this.emit(`${m.map(n).join(' ')} ${OP.cm}`)
+  }
+
+  translate(tx: number, ty: number): this {
+    return this.transform([1, 0, 0, 1, tx, ty])
+  }
+
+  scale(sx: number, sy: number): this {
+    return this.transform([sx, 0, 0, sy, 0, 0])
+  }
+
+  setLineWidth(w: number): this {
+    this.state.lineWidth = w
+    return this.emit(`${n(w)} ${OP.lineWidth}`)
+  }
+
+  setLineCap(cap: 0 | 1 | 2): this {
+    this.state.lineCap = cap
+    return this.emit(`${cap} ${OP.lineCap}`)
+  }
+
+  setLineJoin(join: 0 | 1 | 2): this {
+    this.state.lineJoin = join
+    return this.emit(`${join} ${OP.lineJoin}`)
+  }
+
+  setMiterLimit(limit: number): this {
+    this.state.miterLimit = limit
+    return this.emit(`${n(limit)} ${OP.miterLimit}`)
+  }
+
+  setDash(array: number[], phase = 0): this {
+    this.state.dash = { array: [...array], phase }
+    return this.emit(`[${array.map(n).join(' ')}] ${n(phase)} ${OP.dash}`)
+  }
+
+  // ── Color ───────────────────────────────────────────────────────────────
+
+  setFillColor(c: Color): this {
+    this.state.fillColor = c
+    if (c.space === 'Managed') {
+      const cs = this.resources.useColorSpace(c.cs)
+      this.emit(`/${cs} ${OP.fillColorSpace}`)
+      return this.emit(`${c.comps.map(n).join(' ')} ${OP.fillColorN}`)
+    }
+    return this.emit(fillColorOp(c))
+  }
+
+  setStrokeColor(c: Color): this {
+    this.state.strokeColor = c
+    if (c.space === 'Managed') {
+      const cs = this.resources.useColorSpace(c.cs)
+      this.emit(`/${cs} ${OP.strokeColorSpace}`)
+      return this.emit(`${c.comps.map(n).join(' ')} ${OP.strokeColorN}`)
+    }
+    return this.emit(strokeColorOp(c))
+  }
+
+  // ── Transparency & patterns (spec §12, §13) ─────────────────────────────
+
+  /** Apply an ExtGState (alpha / blend mode) via the `gs` operator. */
+  setExtGState(gs: Buildable): this {
+    return this.emit(`/${this.resources.useExtGState(gs)} ${OP.extGState}`)
+  }
+
+  /** Use a tiling/shading pattern as the non-stroking (fill) color. */
+  setFillPattern(pattern: Buildable): this {
+    const p = this.resources.usePattern(pattern)
+    this.emit(`/Pattern ${OP.fillColorSpace}`)
+    return this.emit(`/${p} ${OP.fillColorN}`)
+  }
+
+  /** Use a tiling/shading pattern as the stroking color. */
+  setStrokePattern(pattern: Buildable): this {
+    const p = this.resources.usePattern(pattern)
+    this.emit(`/Pattern ${OP.strokeColorSpace}`)
+    return this.emit(`/${p} ${OP.strokeColorN}`)
+  }
+
+  /** Paint a shading over the current clip region (`sh` operator). */
+  shade(shading: Buildable): this {
+    this.assertNotInText('sh (shade)')
+    this.path.assertClear('sh (shade)')
+    return this.emit(`/${this.resources.useShading(shading)} ${OP.shading}`)
+  }
+
+  // ── Path construction ───────────────────────────────────────────────────
+
+  moveTo(x: number, y: number): this {
+    this.assertNotInText('m (moveTo)')
+    this.path.open()
+    return this.emit(`${n(x)} ${n(y)} ${OP.moveTo}`)
+  }
+
+  lineTo(x: number, y: number): this {
+    this.assertNotInText('l (lineTo)')
+    this.path.open()
+    return this.emit(`${n(x)} ${n(y)} ${OP.lineTo}`)
+  }
+
+  /** Cubic Bézier with both control points (`x1 y1 x2 y2 x3 y3 c`). */
+  curveTo(
+    x1: number,
+    y1: number,
+    x2: number,
+    y2: number,
+    x3: number,
+    y3: number
+  ): this {
+    this.assertNotInText('c (curveTo)')
+    this.path.open()
+    return this.emit(
+      `${n(x1)} ${n(y1)} ${n(x2)} ${n(y2)} ${n(x3)} ${n(y3)} ${OP.curveTo}`
+    )
+  }
+
+  rect(x: number, y: number, w: number, h: number): this {
+    this.assertNotInText('re (rect)')
+    this.path.open()
+    return this.emit(`${n(x)} ${n(y)} ${n(w)} ${n(h)} ${OP.rect}`)
+  }
+
+  closePath(): this {
+    this.assertNotInText('h (closePath)')
+    this.path.open()
+    return this.emit(OP.closePath)
+  }
+
+  // ── Clipping ────────────────────────────────────────────────────────────
+
+  clip(): this {
+    this.path.markClip()
+    return this.emit(OP.clip)
+  }
+
+  clipEvenOdd(): this {
+    this.path.markClip()
+    return this.emit(OP.clipEvenOdd)
+  }
+
+  // ── Path painting (each consumes the current path) ──────────────────────
+
+  stroke(): this {
+    this.path.consume()
+    return this.emit(OP.stroke)
+  }
+
+  closeStroke(): this {
+    this.path.consume()
+    return this.emit(OP.closeStroke)
+  }
+
+  fill(): this {
+    this.path.consume()
+    return this.emit(OP.fill)
+  }
+
+  fillEvenOdd(): this {
+    this.path.consume()
+    return this.emit(OP.fillEvenOdd)
+  }
+
+  fillStroke(): this {
+    this.path.consume()
+    return this.emit(OP.fillStroke)
+  }
+
+  closeFillStroke(): this {
+    this.path.consume()
+    return this.emit(OP.closeFillStroke)
+  }
+
+  /** End the path with no fill or stroke (consumes a clip without painting). */
+  endPath(): this {
+    this.path.consume()
+    return this.emit(OP.endPath)
+  }
+
+  // ── Images (spec §11.3) ─────────────────────────────────────────────────
+
+  /**
+   * Draw an image into the rectangle `(x, y)`–`(x+width, y+height)` in user
+   * space. The image's pixel dimensions are preserved in the XObject; the
+   * rectangle just sets the CTM scale. Emits `q  w 0 0 h x y cm  /Im Do  Q`.
+   */
+  drawImage(
+    image: PdfImage,
+    rect: { x: number; y: number; width: number; height: number }
+  ): this {
+    this.assertNotInText('Do (drawImage)')
+    this.path.assertClear('Do (drawImage)')
+    const resName = this.resources.useImage(image)
+    this.emit(OP.save)
+    this.emit(`${n(rect.width)} 0 0 ${n(rect.height)} ${n(rect.x)} ${n(rect.y)} ${OP.cm}`)
+    this.emit(`/${resName} ${OP.xobject}`)
+    return this.emit(OP.restore)
+  }
+
+  // ── Text (spec §8, §10.7) ───────────────────────────────────────────────
+
+  /**
+   * A text object: emits `BT`, runs `cb` with a {@link TextObject}, emits `ET`.
+   * Blocks must not nest and no path may be open (mirrors the q/Q guard).
+   */
+  text(cb: (t: TextObject) => void): this {
+    this.assertNotInText('BT (text block)')
+    this.path.assertClear('BT (text block)')
+    this.inText = true
+    this.emit(OP.beginText)
+    try {
+      cb(new TextObject(line => this.emit(line), this.resources))
+    } finally {
+      // Always close the block, even if the callback threw, so the stream
+      // can never be left structurally unbalanced (BT without ET).
+      this.inText = false
+      this.emit(OP.endText)
+    }
+    return this
+  }
+
+  // ── Finalization ────────────────────────────────────────────────────────
+
+  /** Throws on unbalanced q/Q, an open text block, or an unconsumed path. */
+  assertBalanced(): void {
+    if (this.inText) {
+      throw new PdfGenError('PDF_TEXT_STATE', 'text() block did not close (missing ET)')
+    }
+    this.path.assertClear('end of content stream')
+    if (this.stack.length !== 0) {
+      throw new PdfGenError(
+        'PDF_UNBALANCED_GRAPHICS_STATE',
+        `${this.stack.length} unmatched save() call(s) at end of content stream`
+      )
+    }
+  }
+
+  /** Fonts referenced by this stream, in first-use order. */
+  usedFonts(): PdfFont[] {
+    return this.resources.usedFonts().map(f => f.font)
+  }
+
+  /**
+   * Build the page `/Resources` dictionary. Font objects are added to the
+   * object table here and referenced by their stable resource names.
+   */
+  buildResources(table: ObjectTable): PdfDictionary {
+    if (this.resources.isEmpty) return dict({})
+    const res = dict({})
+    const fonts = this.resources.usedFonts()
+    if (fonts.length) {
+      const fontDict = dict({})
+      for (const { name: resName, font } of fonts) {
+        fontDict.entries.set(resName, font.register(table))
+      }
+      res.entries.set('Font', fontDict)
+    }
+    const images = this.resources.usedImages()
+    if (images.length) {
+      const xobjDict = dict({})
+      for (const { name: resName, image } of images) {
+        xobjDict.entries.set(resName, image.register(table))
+      }
+      res.entries.set('XObject', xobjDict)
+    }
+    const spaces = this.resources.usedColorSpaces()
+    if (spaces.length) {
+      const csDict = dict({})
+      for (const { name: resName, cs } of spaces) {
+        csDict.entries.set(resName, cs.build(table))
+      }
+      res.entries.set('ColorSpace', csDict)
+    }
+    const fill = (key: string, items: { name: string; res: Buildable }[]) => {
+      if (!items.length) return
+      const d = dict({})
+      for (const { name: resName, res: r } of items) d.entries.set(resName, r.build(table))
+      res.entries.set(key, d)
+    }
+    fill('ExtGState', this.resources.usedExtGStates())
+    fill('Pattern', this.resources.usedPatterns())
+    fill('Shading', this.resources.usedShadings())
+    return res
+  }
+
+  /** Raw, unfiltered content-stream bytes (filtering happens in the stream). */
+  toBytes(): Uint8Array {
+    return ascii(this.lines.length ? this.lines.join('\n') + '\n' : '')
+  }
+}

package/src/content/graphics_state.ts

@@ -0,0 +1,64 @@
+/**
+ * Tracked graphics state (spec §8.3). A snapshot is pushed on `q` and popped
+ * on `Q`. M1–M3 track the device-graphics fields; text-state fields are
+ * present but unused until M4/M5.
+ */
+
+import type { Color } from '../color/color.ts'
+
+export type Matrix = [number, number, number, number, number, number]
+
+export const IDENTITY: Matrix = [1, 0, 0, 1, 0, 0]
+
+export interface GraphicsState {
+  ctm: Matrix
+  strokeColor: Color
+  fillColor: Color
+  lineWidth: number
+  lineCap: 0 | 1 | 2
+  lineJoin: 0 | 1 | 2
+  miterLimit: number
+  dash: { array: number[]; phase: number }
+  renderingIntent: string | null
+}
+
+export function initialState(): GraphicsState {
+  return {
+    ctm: [...IDENTITY],
+    strokeColor: { space: 'DeviceGray', g: 0 },
+    fillColor: { space: 'DeviceGray', g: 0 },
+    lineWidth: 1,
+    lineCap: 0,
+    lineJoin: 0,
+    miterLimit: 10,
+    dash: { array: [], phase: 0 },
+    renderingIntent: null,
+  }
+}
+
+/** Deep-enough copy for the save/restore stack (colors are immutable values). */
+export function cloneState(s: GraphicsState): GraphicsState {
+  return {
+    ctm: [...s.ctm],
+    strokeColor: s.strokeColor,
+    fillColor: s.fillColor,
+    lineWidth: s.lineWidth,
+    lineCap: s.lineCap,
+    lineJoin: s.lineJoin,
+    miterLimit: s.miterLimit,
+    dash: { array: [...s.dash.array], phase: s.dash.phase },
+    renderingIntent: s.renderingIntent,
+  }
+}
+
+/** Multiply two matrices: result = a × b (PDF `cm` semantics, b applied first). */
+export function multiply(a: Matrix, b: Matrix): Matrix {
+  return [
+    a[0] * b[0] + a[1] * b[2],
+    a[0] * b[1] + a[1] * b[3],
+    a[2] * b[0] + a[3] * b[2],
+    a[2] * b[1] + a[3] * b[3],
+    a[4] * b[0] + a[5] * b[2] + b[4],
+    a[4] * b[1] + a[5] * b[3] + b[5],
+  ]
+}

package/src/content/index.ts

@@ -0,0 +1,16 @@
+export { ContentStream } from './content_stream.ts'
+export { OP } from './operators.ts'
+export type { OperatorName } from './operators.ts'
+export {
+  type GraphicsState,
+  type Matrix,
+  IDENTITY,
+  initialState,
+  cloneState,
+  multiply,
+} from './graphics_state.ts'
+export { PathTracker } from './path.ts'
+export type { PathMode } from './path.ts'
+export { TextObject } from './text_object.ts'
+export type { RunPart } from './text_object.ts'
+export { ResourceCollector } from './resources.ts'

package/src/content/operators.ts

@@ -0,0 +1,70 @@
+/**
+ * PDF 1.7 content-stream operator names (spec §8.2). The builder emits these;
+ * keeping them as named constants prevents typos and documents coverage.
+ *
+ * `BX`/`EX` (compatibility) and the marked-content operators are intentionally
+ * absent — not generated in v1 (marked content arrives with tagged PDF, v1.1).
+ */
+
+export const OP = {
+  // Graphics state
+  save: 'q',
+  restore: 'Q',
+  cm: 'cm',
+  lineWidth: 'w',
+  lineCap: 'J',
+  lineJoin: 'j',
+  miterLimit: 'M',
+  dash: 'd',
+  renderingIntent: 'ri',
+  flatness: 'i',
+  extGState: 'gs',
+
+  // Path construction
+  moveTo: 'm',
+  lineTo: 'l',
+  curveTo: 'c',
+  curveToV: 'v',
+  curveToY: 'y',
+  rect: 're',
+  closePath: 'h',
+
+  // Path painting
+  stroke: 'S',
+  closeStroke: 's',
+  fill: 'f',
+  fillEvenOdd: 'f*',
+  fillStroke: 'B',
+  fillStrokeEvenOdd: 'B*',
+  closeFillStroke: 'b',
+  closeFillStrokeEvenOdd: 'b*',
+  endPath: 'n',
+
+  // Clipping
+  clip: 'W',
+  clipEvenOdd: 'W*',
+
+  // Color
+  strokeColorSpace: 'CS',
+  fillColorSpace: 'cs',
+  strokeColor: 'SC',
+  strokeColorN: 'SCN',
+  fillColor: 'sc',
+  fillColorN: 'scn',
+  strokeGray: 'G',
+  fillGray: 'g',
+  strokeRGB: 'RG',
+  fillRGB: 'rg',
+  strokeCMYK: 'K',
+  fillCMYK: 'k',
+
+  // XObjects / shading
+  xobject: 'Do',
+  shading: 'sh',
+
+  // Text (object scaffolding only in v1; full text in M4/M5)
+  beginText: 'BT',
+  endText: 'ET',
+} as const
+
+export type OperatorName = (typeof OP)[keyof typeof OP]

package/src/content/path.ts

@@ -0,0 +1,51 @@
+/**
+ * Current-path state machine (spec §8.4).
+ *
+ * The builder maintains an explicit path mode. Path-construction operators
+ * open a path; a painting/clip/end operator consumes it. Anything that would
+ * silently discard an open path (starting a `q`/`Q`/text block, or ending the
+ * stream) throws — silent path loss is a classic handwritten-PDF bug.
+ */
+
+import { PdfGenError } from '../util/errors.ts'
+
+export type PathMode = 'none' | 'building' | 'clip-pending'
+
+export class PathTracker {
+  private mode: PathMode = 'none'
+
+  /** A path-construction operator (m, l, c, v, y, re, h) was issued. */
+  open(): void {
+    if (this.mode === 'none') this.mode = 'building'
+  }
+
+  /** A clipping operator (W/W*) was issued; next paint op consumes the path. */
+  markClip(): void {
+    if (this.mode === 'none') {
+      throw new PdfGenError('PDF_NO_PATH', 'Clip operator with no current path')
+    }
+    this.mode = 'clip-pending'
+  }
+
+  /** A painting/end operator (S, f, B, n, …) consumes the path. */
+  consume(): void {
+    if (this.mode === 'none') {
+      throw new PdfGenError('PDF_NO_PATH', 'Painting operator with no current path')
+    }
+    this.mode = 'none'
+  }
+
+  /** Guard before an operation that must not discard an open path. */
+  assertClear(context: string): void {
+    if (this.mode !== 'none') {
+      throw new PdfGenError(
+        'PDF_PATH_NOT_CONSUMED',
+        `Unconsumed path before ${context}: paint it (stroke/fill/clip) or call endPath()`
+      )
+    }
+  }
+
+  get isOpen(): boolean {
+    return this.mode !== 'none'
+  }
+}

package/src/content/resources.ts

@@ -0,0 +1,119 @@
+/**
+ * Per-content-stream resource collector (spec §6.3 Resources). Hands out
+ * deterministic resource names (`F1`/`Im1`/…) on first use and keeps insertion
+ * order so the emitted `/Resources` dictionary is byte-stable.
+ *
+ * Fonts and image XObjects are collected; ExtGState/pattern categories are
+ * added in later milestones following the same pattern.
+ */
+
+import type { ObjectTable } from '../document/object_table.ts'
+import type { PdfObject } from '../objects/types.ts'
+import type { PdfFont } from '../fonts/font.ts'
+import type { PdfImage } from '../images/image.ts'
+import type { ManagedColorSpace } from '../color/space.ts'
+
+/** Anything registered as a resource: a stable id + a builder. */
+export interface Buildable {
+  readonly id: string
+  build(table: ObjectTable): PdfObject
+}
+
+export class ResourceCollector {
+  private readonly fonts = new Map<string, { name: string; font: PdfFont }>()
+  private readonly images = new Map<PdfImage, string>()
+  private readonly colorSpaces = new Map<string, { name: string; cs: ManagedColorSpace }>()
+  private readonly extGStates = new Map<string, { name: string; res: Buildable }>()
+  private readonly patterns = new Map<string, { name: string; res: Buildable }>()
+  private readonly shadings = new Map<string, { name: string; res: Buildable }>()
+
+  /** Register a font, returning its stable `/Font` resource name. */
+  useFont(font: PdfFont): string {
+    const existing = this.fonts.get(font.id)
+    if (existing) return existing.name
+    const name = `F${this.fonts.size + 1}`
+    this.fonts.set(font.id, { name, font })
+    return name
+  }
+
+  /** Register an image, returning its stable `/XObject` resource name. */
+  useImage(image: PdfImage): string {
+    const existing = this.images.get(image)
+    if (existing) return existing
+    const name = `Im${this.images.size + 1}`
+    this.images.set(image, name)
+    return name
+  }
+
+  /** Register a managed color space, returning its `/ColorSpace` name. */
+  useColorSpace(cs: ManagedColorSpace): string {
+    const existing = this.colorSpaces.get(cs.id)
+    if (existing) return existing.name
+    const name = `CS${this.colorSpaces.size + 1}`
+    this.colorSpaces.set(cs.id, { name, cs })
+    return name
+  }
+
+  /** Fonts in first-use order. */
+  usedFonts(): { name: string; font: PdfFont }[] {
+    return [...this.fonts.values()]
+  }
+
+  /** Images in first-use order. */
+  usedImages(): { name: string; image: PdfImage }[] {
+    return [...this.images].map(([image, name]) => ({ name, image }))
+  }
+
+  /** Color spaces in first-use order. */
+  usedColorSpaces(): { name: string; cs: ManagedColorSpace }[] {
+    return [...this.colorSpaces.values()]
+  }
+
+  private use(
+    map: Map<string, { name: string; res: Buildable }>,
+    prefix: string,
+    res: Buildable
+  ): string {
+    const existing = map.get(res.id)
+    if (existing) return existing.name
+    const name = `${prefix}${map.size + 1}`
+    map.set(res.id, { name, res })
+    return name
+  }
+
+  /** Register an ExtGState → `/ExtGState` name (`GS1`, …). */
+  useExtGState(res: Buildable): string {
+    return this.use(this.extGStates, 'GS', res)
+  }
+
+  /** Register a pattern → `/Pattern` name (`P1`, …). */
+  usePattern(res: Buildable): string {
+    return this.use(this.patterns, 'P', res)
+  }
+
+  /** Register a shading → `/Shading` name (`Sh1`, …). */
+  useShading(res: Buildable): string {
+    return this.use(this.shadings, 'Sh', res)
+  }
+
+  usedExtGStates(): { name: string; res: Buildable }[] {
+    return [...this.extGStates.values()]
+  }
+  usedPatterns(): { name: string; res: Buildable }[] {
+    return [...this.patterns.values()]
+  }
+  usedShadings(): { name: string; res: Buildable }[] {
+    return [...this.shadings.values()]
+  }
+
+  get isEmpty(): boolean {
+    return (
+      this.fonts.size === 0 &&
+      this.images.size === 0 &&
+      this.colorSpaces.size === 0 &&
+      this.extGStates.size === 0 &&
+      this.patterns.size === 0 &&
+      this.shadings.size === 0
+    )
+  }
+}