@strav/pdf 0.4.17

package/src/content/text_object.ts

@@ -0,0 +1,140 @@
+/**
+ * Text object — the `BT … ET` block (spec §8, §10.7). Created by
+ * `ContentStream.text(cb)`; the callback drives it fluently. A font must be
+ * set before any `show`; the builder enforces BT/ET-only text operators and
+ * (via ContentStream) that no path is open and blocks don't nest.
+ */
+
+import { PdfGenError } from '../util/errors.ts'
+import { formatNumber } from '../objects/number.ts'
+import { encodeLiteral } from '../objects/string.ts'
+import type { PdfFont } from '../fonts/font.ts'
+import type { ResourceCollector } from './resources.ts'
+
+function n(v: number): string {
+  return formatNumber(v)
+}
+
+/** A literal PDF string token built from already-encoded font bytes. */
+function strToken(bytes: Uint8Array): string {
+  // encodeLiteral octal-escapes everything outside printable ASCII, so the
+  // result is pure ASCII; map bytes straight to chars (no TextDecoder).
+  const lit = encodeLiteral(bytes)
+  let s = ''
+  for (let i = 0; i < lit.length; i++) s += String.fromCharCode(lit[i]!)
+  return s
+}
+
+/** A segment of a positioned run for `showRun` (spec §10.7). */
+export type RunPart = { text: string } | { adjust: number }
+
+export class TextObject {
+  private font?: PdfFont
+
+  constructor(
+    private readonly emit: (line: string) => void,
+    private readonly resources: ResourceCollector
+  ) {}
+
+  /** Select a font at `sizePt` points. */
+  setFont(font: PdfFont, sizePt: number): this {
+    this.font = font
+    const resName = this.resources.useFont(font)
+    this.emit(`/${resName} ${n(sizePt)} Tf`)
+    return this
+  }
+
+  /**
+   * Set the **absolute** text position in user space (`1 0 0 1 x y Tm`).
+   * This resets the text matrix, so successive calls position independently —
+   * unlike `Td`, which is relative to the current line.
+   */
+  moveTo(x: number, y: number): this {
+    this.emit(`1 0 0 1 ${n(x)} ${n(y)} Tm`)
+    return this
+  }
+
+  /** Set the full text matrix (`a b c d e f Tm`) for scale/rotate/skew. */
+  setTextMatrix(a: number, b: number, c: number, d: number, e: number, f: number): this {
+    this.emit(`${n(a)} ${n(b)} ${n(c)} ${n(d)} ${n(e)} ${n(f)} Tm`)
+    return this
+  }
+
+  /** Move to the next line, offset `(tx, ty)` from the current line (`Td`). */
+  nextLine(tx: number, ty: number): this {
+    this.emit(`${n(tx)} ${n(ty)} Td`)
+    return this
+  }
+
+  setLeading(leading: number): this {
+    this.emit(`${n(leading)} TL`)
+    return this
+  }
+
+  /** Move to the next line using the current leading (`T*`). */
+  newLine(): this {
+    this.emit('T*')
+    return this
+  }
+
+  setCharSpacing(v: number): this {
+    this.emit(`${n(v)} Tc`)
+    return this
+  }
+
+  setWordSpacing(v: number): this {
+    this.emit(`${n(v)} Tw`)
+    return this
+  }
+
+  /** Horizontal scaling as a percentage (`p Tz`). */
+  setHorizScale(percent: number): this {
+    this.emit(`${n(percent)} Tz`)
+    return this
+  }
+
+  setRise(v: number): this {
+    this.emit(`${n(v)} Ts`)
+    return this
+  }
+
+  /** Text render mode 0–7 (`m Tr`). */
+  setRenderMode(mode: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7): this {
+    this.emit(`${mode} Tr`)
+    return this
+  }
+
+  private requireFont(): PdfFont {
+    if (!this.font) {
+      throw new PdfGenError('PDF_NO_FONT', 'setFont() must be called before show()/showRun()')
+    }
+    return this.font
+  }
+
+  /** Show a string (`(...) Tj`). */
+  show(text: string): this {
+    const font = this.requireFont()
+    this.emit(`${strToken(font.encode(text))} Tj`)
+    return this
+  }
+
+  /**
+   * Show a positioned run (`[ ... ] TJ`). `adjust` is in 1/1000 em and is
+   * subtracted from the current position (spec §10.7).
+   */
+  showRun(parts: RunPart[]): this {
+    const font = this.requireFont()
+    const items: string[] = []
+    for (const part of parts) {
+      if ('text' in part) items.push(strToken(font.encode(part.text)))
+      else items.push(n(part.adjust))
+    }
+    this.emit(`[${items.join(' ')}] TJ`)
+    return this
+  }
+
+  /** Move to the next line and show (`T*` then `Tj`); needs leading set. */
+  newLineShow(text: string): this {
+    return this.newLine().show(text)
+  }
+}

package/src/document/catalog.ts

@@ -0,0 +1,16 @@
+/**
+ * The document catalog (`/Type /Catalog`, spec §6.1). v1 populates the
+ * required `/Pages` and `/Version` entries. `/Metadata`, `/OutputIntents`,
+ * etc. are added by later milestones (M9/M11).
+ */
+
+import type { IndirectRef } from '../objects/types.ts'
+import { dict, name } from '../objects/types.ts'
+
+export function buildCatalog(pagesRoot: IndirectRef) {
+  return dict({
+    Type: name('Catalog'),
+    Version: name('1.7'),
+    Pages: pagesRoot,
+  })
+}

package/src/document/index.ts

@@ -0,0 +1,13 @@
+export { PdfDocument } from './pdf_document.ts'
+export { Page } from './page.ts'
+export type {
+  PageSize,
+  Rect,
+  ConformanceLevel,
+  DocumentInfo,
+  CreateOptions,
+  AddPageOptions,
+} from './types.ts'
+export { rectToBox } from './types.ts'
+export { ObjectTable } from './object_table.ts'
+export { serializeDocument } from './xref.ts'

package/src/document/object_table.ts

@@ -0,0 +1,67 @@
+/**
+ * Registry of indirect objects (spec §5.2, §3.2).
+ *
+ * Implements the two-pass model: during the build pass every indirect object
+ * is allocated a number (1, 2, 3, …) and its value stored; during the
+ * serialize pass the values are emitted in number order and byte offsets
+ * recorded. Generation is always 0 in v1 (no incremental updates).
+ */
+
+import { PdfGenError } from '../util/errors.ts'
+import type { PdfObject, IndirectRef } from '../objects/types.ts'
+import { ref } from '../objects/types.ts'
+
+export class ObjectTable {
+  /** num → object value. Object 0 is the free-list head, never stored here. */
+  private readonly slots = new Map<number, PdfObject>()
+  private next = 1
+
+  /** Reserve the next object number without assigning a value yet. */
+  allocate(): IndirectRef {
+    const num = this.next++
+    return ref(num, 0)
+  }
+
+  /** Assign (or replace) the value for a previously allocated number. */
+  set(r: IndirectRef, value: PdfObject): void {
+    if (r.num <= 0 || r.num >= this.next) {
+      throw new PdfGenError('PDF_INVALID_OBJECT', `Object ${r.num} was not allocated`)
+    }
+    this.slots.set(r.num, value)
+  }
+
+  /** Allocate + assign in one step; returns the reference. */
+  add(value: PdfObject): IndirectRef {
+    const r = this.allocate()
+    this.slots.set(r.num, value)
+    return r
+  }
+
+  get(num: number): PdfObject | undefined {
+    return this.slots.get(num)
+  }
+
+  /** Highest allocated object number (0 if none). */
+  get maxNumber(): number {
+    return this.next - 1
+  }
+
+  /** Total slot count including object 0 (the `/Size` trailer value). */
+  get size(): number {
+    return this.next
+  }
+
+  /** Iterate assigned objects in ascending number order. */
+  *entries(): IterableIterator<[number, PdfObject]> {
+    for (let n = 1; n < this.next; n++) {
+      const v = this.slots.get(n)
+      if (v === undefined) {
+        throw new PdfGenError(
+          'PDF_INVALID_OBJECT',
+          `Object ${n} was allocated but never assigned a value`
+        )
+      }
+      yield [n, v]
+    }
+  }
+}

package/src/document/page.ts

@@ -0,0 +1,74 @@
+/**
+ * A page (spec §6.3). Holds geometry and a lazily-created content stream.
+ * The page dictionary itself is built by the document serializer at save time.
+ */
+
+import { ContentStream } from '../content/content_stream.ts'
+import type { PageSize, Rect } from './types.ts'
+
+export class Page {
+  readonly index: number
+  readonly size: PageSize
+  readonly rotation: 0 | 90 | 180 | 270
+
+  /** Optional page boxes (points). MediaBox defaults to the page size. */
+  private mediaBox?: Rect
+  private cropBox?: Rect
+  private bleedBox?: Rect
+  private trimBox?: Rect
+  private artBox?: Rect
+
+  private contentStream?: ContentStream
+
+  constructor(index: number, size: PageSize, rotation: 0 | 90 | 180 | 270 = 0) {
+    this.index = index
+    this.size = size
+    this.rotation = rotation
+  }
+
+  setMediaBox(box: Rect): void {
+    this.mediaBox = box
+  }
+  setCropBox(box: Rect): void {
+    this.cropBox = box
+  }
+  /** For PDF/X-4 (enforced in M11). */
+  setBleedBox(box: Rect): void {
+    this.bleedBox = box
+  }
+  /** For PDF/X-4 (enforced in M11). */
+  setTrimBox(box: Rect): void {
+    this.trimBox = box
+  }
+  setArtBox(box: Rect): void {
+    this.artBox = box
+  }
+
+  /** Append-only content-stream builder for this page (spec §8). */
+  content(): ContentStream {
+    if (!this.contentStream) this.contentStream = new ContentStream()
+    return this.contentStream
+  }
+
+  // ── Internal: consumed by the document serializer ───────────────────────
+
+  /** @internal */
+  getContentStream(): ContentStream | undefined {
+    return this.contentStream
+  }
+
+  /** @internal The effective MediaBox (defaults to the page size). */
+  getMediaBox(): Rect {
+    return this.mediaBox ?? { x: 0, y: 0, w: this.size.widthPt, h: this.size.heightPt }
+  }
+
+  /** @internal Optional boxes, present only when explicitly set. */
+  getOptionalBoxes(): { key: string; rect: Rect }[] {
+    const out: { key: string; rect: Rect }[] = []
+    if (this.cropBox) out.push({ key: 'CropBox', rect: this.cropBox })
+    if (this.bleedBox) out.push({ key: 'BleedBox', rect: this.bleedBox })
+    if (this.trimBox) out.push({ key: 'TrimBox', rect: this.trimBox })
+    if (this.artBox) out.push({ key: 'ArtBox', rect: this.artBox })
+    return out
+  }
+}

package/src/document/page_tree.ts

@@ -0,0 +1,78 @@
+/**
+ * Page tree builder (spec §6.2). A single-level tree (one `/Pages` node) until
+ * the page count exceeds 50, after which it is balanced into fan-out-of-8
+ * intermediate nodes. Intermediate `/Pages` node dictionaries are written into
+ * the {@link ObjectTable}; the caller builds the leaf `/Page` dictionaries
+ * using the returned parent map.
+ */
+
+import type { IndirectRef, PdfObject } from '../objects/types.ts'
+import { arr, dict, name, num } from '../objects/types.ts'
+import type { ObjectTable } from './object_table.ts'
+
+const FAN_OUT = 8
+const SINGLE_LEVEL_MAX = 50
+
+export interface PageTreeResult {
+  /** The `/Pages` root reference (goes in the catalog). */
+  rootRef: IndirectRef
+  /** leaf object number → its immediate parent `/Pages` node reference. */
+  parentOf: Map<number, IndirectRef>
+}
+
+function pagesNode(kids: IndirectRef[], count: number, parent: IndirectRef | null) {
+  const entries: Record<string, PdfObject> = {
+    Type: name('Pages'),
+    Kids: arr([...kids]),
+    Count: num(count),
+  }
+  if (parent) entries.Parent = parent
+  return dict(entries)
+}
+
+function chunk<T>(items: T[], size: number): T[][] {
+  const out: T[][] = []
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size))
+  return out
+}
+
+/**
+ * @param leafRefs pre-allocated references for the leaf `/Page` objects, in
+ *                  page order.
+ */
+export function buildPageTree(table: ObjectTable, leafRefs: IndirectRef[]): PageTreeResult {
+  const parentOf = new Map<number, IndirectRef>()
+
+  if (leafRefs.length <= SINGLE_LEVEL_MAX) {
+    const rootRef = table.allocate()
+    for (const leaf of leafRefs) parentOf.set(leaf.num, rootRef)
+    table.set(rootRef, pagesNode(leafRefs, leafRefs.length, null))
+    return { rootRef, parentOf }
+  }
+
+  // Multi-level: build intermediate nodes bottom-up, deferring each node's
+  // dictionary until its own parent is known.
+  const deferred = new Map<number, { ref: IndirectRef; kids: IndirectRef[]; count: number }>()
+  let level: { ref: IndirectRef; count: number }[] = leafRefs.map(ref => ({ ref, count: 1 }))
+
+  while (level.length > 1) {
+    const next: { ref: IndirectRef; count: number }[] = []
+    for (const group of chunk(level, FAN_OUT)) {
+      const nodeRef = table.allocate()
+      let count = 0
+      for (const child of group) {
+        parentOf.set(child.ref.num, nodeRef)
+        count += child.count
+      }
+      deferred.set(nodeRef.num, { ref: nodeRef, kids: group.map(g => g.ref), count })
+      next.push({ ref: nodeRef, count })
+    }
+    level = next
+  }
+
+  const rootRef = level[0]!.ref
+  for (const { ref, kids, count } of deferred.values()) {
+    table.set(ref, pagesNode(kids, count, parentOf.get(ref.num) ?? null))
+  }
+  return { rootRef, parentOf }
+}

package/src/document/pdf_document.ts

@@ -0,0 +1,310 @@
+/**
+ * Public facade (spec §16). Owns the object table, builds the document graph
+ * during the build pass, and emits bytes during the serialize pass.
+ */
+
+import { createHash, randomBytes } from 'node:crypto'
+import { PdfGenError, UnsupportedFontError, ConformanceError } from '../util/errors.ts'
+import type { IndirectRef, PdfObject } from '../objects/types.ts'
+import { arr, dict, name, num } from '../objects/types.ts'
+import { textString } from '../objects/string.ts'
+import { encodeObject } from '../objects/encode.ts'
+import { makeContentStream, makeStream } from '../streams/stream.ts'
+import { parseIccProfile } from '../color/icc.ts'
+import { buildInfoDict } from '../metadata/info_dict.ts'
+import { buildXmpStream } from '../metadata/xmp.ts'
+import { validateConformance } from '../standards/index.ts'
+import { extGState, type ExtGStateOptions } from '../ext-gstate/ext_gstate.ts'
+import { tilingPattern, type TilingPatternOptions } from '../patterns/tiling_pattern.ts'
+import {
+  axialShading,
+  radialShading,
+  shadingPattern,
+  type AxialOptions,
+  type RadialOptions,
+  type Shading,
+} from '../patterns/shading.ts'
+import type { Writable } from 'node:stream'
+import type { ByteSink } from '../output/byte_sink.ts'
+import { BufferSink } from '../output/buffer_sink.ts'
+import { StreamSink } from '../output/stream_sink.ts'
+import { ObjectTable } from './object_table.ts'
+import { buildPageTree } from './page_tree.ts'
+import { buildCatalog } from './catalog.ts'
+import { serializeDocument } from './xref.ts'
+import { Page } from './page.ts'
+import { rectToBox } from './types.ts'
+import type {
+  AddPageOptions,
+  CreateOptions,
+  DocumentInfo,
+  ConformanceLevel,
+  OutputIntentConfig,
+} from './types.ts'
+
+const PRODUCER = '@strav/pdf'
+
+export class PdfDocument {
+  private readonly info: DocumentInfo
+  private conformance: ConformanceLevel
+  private readonly creationDate: Date
+  private readonly fixedId?: Uint8Array
+  private readonly pages: Page[] = []
+  private outputIntent?: OutputIntentConfig
+  private saved = false
+
+  private constructor(opts: CreateOptions) {
+    this.info = opts.info ?? {}
+    this.conformance = opts.conformance ?? null
+    this.creationDate = opts.creationDate ?? new Date()
+    this.fixedId = opts.documentId ? normalizeId(opts.documentId) : undefined
+  }
+
+  /** Create a new, empty document. */
+  static create(opts: CreateOptions = {}): PdfDocument {
+    return new PdfDocument(opts)
+  }
+
+  addPage(opts: AddPageOptions): Page {
+    if (this.saved) {
+      throw new PdfGenError('PDF_DOCUMENT_FINALIZED', 'Cannot add a page after save()')
+    }
+    const page = new Page(this.pages.length, opts.size, opts.rotation ?? 0)
+    this.pages.push(page)
+    return page
+  }
+
+  /**
+   * Set the document's output intent (spec §9.3). Embeds the destination ICC
+   * profile and adds it to the catalog `/OutputIntents`. Required for PDF/X-4.
+   */
+  setOutputIntent(cfg: OutputIntentConfig): this {
+    if (this.saved) {
+      throw new PdfGenError('PDF_DOCUMENT_FINALIZED', 'Cannot set output intent after save()')
+    }
+    parseIccProfile(cfg.destOutputProfile) // validate eagerly
+    this.outputIntent = cfg
+    return this
+  }
+
+  /** Create an ExtGState (spec §13). Convenience for {@link extGState}. */
+  createExtGState(opts: ExtGStateOptions) {
+    return extGState(opts)
+  }
+
+  /** Create a tiling pattern (spec §12.1). */
+  createTilingPattern(opts: TilingPatternOptions) {
+    return tilingPattern(opts)
+  }
+
+  /** Create an axial (linear) shading (spec §12.2). */
+  createAxialShading(opts: AxialOptions) {
+    return axialShading(opts)
+  }
+
+  /** Create a radial shading (spec §12.2). */
+  createRadialShading(opts: RadialOptions) {
+    return radialShading(opts)
+  }
+
+  /** Wrap a shading as a fill/stroke pattern. */
+  createShadingPattern(shading: Shading, matrix?: number[]) {
+    return shadingPattern(shading, matrix)
+  }
+
+  /** Conformance target. */
+  getConformance(): ConformanceLevel {
+    return this.conformance
+  }
+
+  /**
+   * Opt into a conformance mode (spec §15). Validated at `save()`, which
+   * throws `ConformanceError` listing every violation. A Standard-14 font
+   * used under any mode throws `UnsupportedFontError` (fail-fast).
+   */
+  setConformance(level: ConformanceLevel): this {
+    if (this.saved) {
+      throw new PdfGenError('PDF_DOCUMENT_FINALIZED', 'Cannot set conformance after save()')
+    }
+    this.conformance = level
+    return this
+  }
+
+  /** Serialize and return the complete PDF bytes (spec §3.2, §3.3). */
+  async save(): Promise<Uint8Array> {
+    const sink = new BufferSink()
+    this.finalize(sink)
+    return sink.toBytes()
+  }
+
+  /**
+   * Serialize, streaming to a Node `Writable` (spec §3.3) — no full-document
+   * buffer. Resolves once the stream has flushed; rejects on a stream error
+   * or a build/conformance error (the same as {@link save}).
+   */
+  async saveToStream(writable: Writable): Promise<void> {
+    const sink = new StreamSink(writable)
+    this.finalize(sink)
+    await sink.done()
+  }
+
+  private finalize(sink: ByteSink): void {
+    if (this.saved) {
+      throw new PdfGenError('PDF_DOCUMENT_FINALIZED', 'Document already saved')
+    }
+    if (this.pages.length === 0) {
+      throw new PdfGenError('PDF_INVALID_PAGE', 'Document has no pages')
+    }
+
+    // Conformance (spec §15) — before finalizing so the caller may fix and
+    // retry. Standard-14 fails fast (a distinct, typed error) ahead of the
+    // aggregate validation.
+    if (this.conformance) {
+      for (const page of this.pages) {
+        const cs = page.getContentStream()
+        for (const font of cs ? cs.usedFonts() : []) {
+          if (font.isStandard14) {
+            throw new UnsupportedFontError(
+              `Standard-14 font "${font.baseFont}" cannot be used under ${this.conformance}; ` +
+                'embed a TrueType/OpenType font instead'
+            )
+          }
+        }
+      }
+      const profileColorSpace = this.outputIntent
+        ? parseIccProfile(this.outputIntent.destOutputProfile).colorSpace
+        : undefined
+      const violations = validateConformance(this.conformance, {
+        pages: this.pages.map(p => ({
+          hasTrimOrArt: p
+            .getOptionalBoxes()
+            .some(b => b.key === 'TrimBox' || b.key === 'ArtBox'),
+        })),
+        outputIntent: { present: !!this.outputIntent, profileColorSpace },
+      })
+      if (violations.length) {
+        throw new ConformanceError(
+          `${this.conformance} conformance failed:\n  - ${violations.join('\n  - ')}`,
+          violations
+        )
+      }
+    }
+
+    this.saved = true
+
+    const table = new ObjectTable()
+
+    // Info dictionary (spec §14.1). ModDate == CreateDate for determinism.
+    const infoRef = table.add(buildInfoDict(this.info, this.creationDate, PRODUCER))
+
+    // Leaf page refs, then the page tree, then the leaf page dicts.
+    const leafRefs = this.pages.map(() => table.allocate())
+    const { rootRef, parentOf } = buildPageTree(table, leafRefs)
+
+    this.pages.forEach((page, i) => {
+      const leafRef = leafRefs[i]!
+      const parent = parentOf.get(leafRef.num)!
+      table.set(leafRef, this.buildPageDict(table, page, parent))
+    })
+
+    const catalog = buildCatalog(rootRef)
+    if (this.outputIntent) {
+      catalog.entries.set('OutputIntents', arr([this.buildOutputIntent(table)]))
+    }
+    // XMP is always present (spec §14.2) — uncompressed /Metadata stream.
+    catalog.entries.set(
+      'Metadata',
+      table.add(
+        buildXmpStream({
+          info: this.info,
+          creationDate: this.creationDate,
+          producer: PRODUCER,
+          conformance: this.conformance,
+        })
+      )
+    )
+    const catalogRef = table.add(catalog)
+
+    const id = this.computeId(infoRef, table)
+
+    serializeDocument({ table, root: catalogRef, info: infoRef, id, sink })
+  }
+
+  // ── build helpers ───────────────────────────────────────────────────────
+
+  private buildOutputIntent(table: ObjectTable): PdfObject {
+    const cfg = this.outputIntent!
+    const profile = parseIccProfile(cfg.destOutputProfile)
+    const profileRef = table.add(
+      makeStream(cfg.destOutputProfile, {
+        filter: 'FlateDecode',
+        extra: { N: num(profile.components) },
+      })
+    )
+    // These identifier fields are ASCII by convention (FOGRA39, URLs);
+    // PDF/X readers expect a readable literal string, not UTF-16BE.
+    const ascii = (s: string) => textString(s, { encoding: 'pdfdoc' })
+    const d = dict({
+      Type: name('OutputIntent'),
+      S: name(cfg.subtype),
+      OutputConditionIdentifier: ascii(cfg.outputConditionIdentifier),
+      DestOutputProfile: profileRef,
+    })
+    if (cfg.outputCondition) d.entries.set('OutputCondition', ascii(cfg.outputCondition))
+    if (cfg.registryName) d.entries.set('RegistryName', ascii(cfg.registryName))
+    if (cfg.info) d.entries.set('Info', ascii(cfg.info))
+    return d
+  }
+
+  private buildPageDict(table: ObjectTable, page: Page, parent: IndirectRef) {
+    const mb = page.getMediaBox()
+    const entries: Record<string, PdfObject> = {
+      Type: name('Page'),
+      Parent: parent,
+      MediaBox: arr(rectToBox(mb).map(num)),
+      Resources: dict({}),
+    }
+    if (page.rotation !== 0) entries.Rotate = num(page.rotation)
+    for (const { key, rect } of page.getOptionalBoxes()) {
+      entries[key] = arr(rectToBox(rect).map(num))
+    }
+
+    const cs = page.getContentStream()
+    if (cs) {
+      cs.assertBalanced()
+      // Standard-14-under-conformance is checked up front in save().
+      const contentRef = table.add(makeContentStream(cs.toBytes()))
+      entries.Contents = contentRef
+      entries.Resources = cs.buildResources(table)
+    }
+    return dict(entries)
+  }
+
+  /**
+   * `/ID` array (spec §6.5): a permanent id and a per-save id. With a fixed
+   * `documentId` (or fixed creationDate-driven content) the output is
+   * byte-identical across runs (spec §16.3).
+   */
+  private computeId(infoRef: IndirectRef, table: ObjectTable): [Uint8Array, Uint8Array] {
+    if (this.fixedId) return [this.fixedId, this.fixedId]
+    const infoObj = table.get(infoRef.num)!
+    const permanent = createHash('md5').update(encodeObject(infoObj)).digest()
+    const perSave = new Uint8Array(randomBytes(16))
+    return [new Uint8Array(permanent), perSave]
+  }
+}
+
+function normalizeId(id: string | Uint8Array): Uint8Array {
+  if (typeof id !== 'string') {
+    if (id.length !== 16) {
+      throw new PdfGenError('PDF_INVALID_OBJECT', 'documentId bytes must be exactly 16 long')
+    }
+    return id
+  }
+  if (!/^[0-9a-fA-F]{32}$/.test(id)) {
+    throw new PdfGenError('PDF_INVALID_OBJECT', 'documentId hex string must be 32 hex chars')
+  }
+  const out = new Uint8Array(16)
+  for (let i = 0; i < 16; i++) out[i] = parseInt(id.slice(i * 2, i * 2 + 2), 16)
+  return out
+}