@strav/pdf 0.4.17

package/src/metadata/xmp.ts

@@ -0,0 +1,110 @@
+/**
+ * XMP metadata packet (spec §14.2). The authoritative metadata in PDF 1.7+
+ * and required for PDF/A-2b and PDF/X-4. Emitted as an **uncompressed**
+ * `/Metadata` stream (PDF/A forensic-readability requirement); the document
+ * Info dictionary carries the same values.
+ *
+ * `bfrange`-free, deterministic: with a fixed creation date the bytes are
+ * byte-identical across runs (the xpacket id is a fixed constant).
+ */
+
+import { utf8 } from '../util/ascii.ts'
+import { name } from '../objects/types.ts'
+import type { PdfStream } from '../objects/types.ts'
+import { makeStream } from '../streams/stream.ts'
+import type { DocumentInfo } from '../document/types.ts'
+import type { ConformanceLevel } from '../document/types.ts'
+
+const XPACKET_ID = 'W5M0MpCehiHzreSzNTczkc9d'
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+/** ISO 8601 UTC, e.g. `2026-05-18T09:30:00+00:00`. */
+function isoDate(d: Date): string {
+  const p = (n: number, w = 2) => String(n).padStart(w, '0')
+  return (
+    `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())}` +
+    `T${p(d.getUTCHours())}:${p(d.getUTCMinutes())}:${p(d.getUTCSeconds())}+00:00`
+  )
+}
+
+export interface XmpOptions {
+  info: DocumentInfo
+  creationDate: Date
+  producer: string
+  conformance: ConformanceLevel
+}
+
+export function buildXmpPacket(o: XmpOptions): string {
+  const date = isoDate(o.creationDate)
+  const lines: string[] = []
+  const ns = [
+    'xmlns:dc="http://purl.org/dc/elements/1.1/"',
+    'xmlns:xmp="http://ns.adobe.com/xap/1.0/"',
+    'xmlns:pdf="http://ns.adobe.com/pdf/1.3/"',
+  ]
+  if (o.conformance === 'PDF/A-2b') ns.push('xmlns:pdfaid="http://www.aiim.org/pdfa/ns/id/"')
+  if (o.conformance === 'PDF/X-4') ns.push('xmlns:pdfxid="http://www.npes.org/pdfx/ns/id/"')
+
+  if (o.info.title) {
+    lines.push(
+      `<dc:title><rdf:Alt><rdf:li xml:lang="x-default">${esc(o.info.title)}</rdf:li></rdf:Alt></dc:title>`
+    )
+  }
+  if (o.info.author) {
+    lines.push(
+      `<dc:creator><rdf:Seq><rdf:li>${esc(o.info.author)}</rdf:li></rdf:Seq></dc:creator>`
+    )
+  }
+  if (o.info.subject) {
+    lines.push(
+      `<dc:description><rdf:Alt><rdf:li xml:lang="x-default">${esc(o.info.subject)}</rdf:li></rdf:Alt></dc:description>`
+    )
+  }
+  if (o.info.keywords) {
+    const bag = o.info.keywords
+      .split(/[,;]\s*/)
+      .filter(Boolean)
+      .map(k => `<rdf:li>${esc(k)}</rdf:li>`)
+      .join('')
+    lines.push(`<dc:subject><rdf:Bag>${bag}</rdf:Bag></dc:subject>`)
+    lines.push(`<pdf:Keywords>${esc(o.info.keywords)}</pdf:Keywords>`)
+  }
+  lines.push('<dc:format>application/pdf</dc:format>')
+  lines.push(`<xmp:CreateDate>${date}</xmp:CreateDate>`)
+  lines.push(`<xmp:ModifyDate>${date}</xmp:ModifyDate>`)
+  lines.push(`<xmp:MetadataDate>${date}</xmp:MetadataDate>`)
+  if (o.info.creator) lines.push(`<xmp:CreatorTool>${esc(o.info.creator)}</xmp:CreatorTool>`)
+  lines.push(`<pdf:Producer>${esc(o.producer)}</pdf:Producer>`)
+  if (o.conformance === 'PDF/A-2b') {
+    lines.push('<pdfaid:part>2</pdfaid:part>')
+    lines.push('<pdfaid:conformance>B</pdfaid:conformance>')
+  }
+  if (o.conformance === 'PDF/X-4') {
+    lines.push('<pdfxid:GTS_PDFXVersion>PDF/X-4</pdfxid:GTS_PDFXVersion>')
+  }
+
+  return (
+    `<?xpacket begin="" id="${XPACKET_ID}"?>\n` +
+    '<x:xmpmeta xmlns:x="adobe:ns:meta/">\n' +
+    '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">\n' +
+    `<rdf:Description rdf:about="" ${ns.join(' ')}>\n` +
+    lines.map(l => '  ' + l).join('\n') +
+    '\n</rdf:Description>\n</rdf:RDF>\n</x:xmpmeta>\n' +
+    '<?xpacket end="w"?>'
+  )
+}
+
+/** The `/Metadata` stream object — uncompressed, no filters (PDF/A). */
+export function buildXmpStream(o: XmpOptions): PdfStream {
+  return makeStream(utf8(buildXmpPacket(o)), {
+    filter: 'none',
+    extra: { Type: name('Metadata'), Subtype: name('XML') },
+  })
+}

package/src/objects/encode.ts

@@ -0,0 +1,77 @@
+/**
+ * Object → bytes (spec §5.1).
+ *
+ * Pure and deterministic: the same {@link PdfObject} always encodes to the
+ * same bytes. Dictionary keys are emitted in `Map` insertion order.
+ *
+ * This encodes the *value* of an object. Wrapping a value in `N G obj … endobj`
+ * is the document serializer's job (document/xref.ts).
+ */
+
+import { ascii, concatBytes, SPACE, LF } from '../util/ascii.ts'
+import { PdfGenError } from '../util/errors.ts'
+import type { PdfObject, PdfDictionary } from './types.ts'
+import { formatNumber } from './number.ts'
+import { encodeName } from './name.ts'
+import { encodeLiteral, encodeHex } from './string.ts'
+import { refToken } from './indirect_ref.ts'
+
+const TRUE = ascii('true')
+const FALSE = ascii('false')
+const NULL = ascii('null')
+const DICT_OPEN = ascii('<<')
+const DICT_CLOSE = ascii('>>')
+const STREAM_KW = ascii('stream\n')
+const ENDSTREAM_KW = ascii('\nendstream')
+
+export function encodeObject(o: PdfObject): Uint8Array {
+  switch (o.kind) {
+    case 'null':
+      return NULL
+    case 'bool':
+      return o.value ? TRUE : FALSE
+    case 'num':
+      return ascii(formatNumber(o.value))
+    case 'str':
+      return o.encoding === 'hex' ? encodeHex(o.value) : encodeLiteral(o.value)
+    case 'name':
+      return encodeName(o.value)
+    case 'ref':
+      return ascii(refToken(o))
+    case 'arr': {
+      const parts: Uint8Array[] = [Uint8Array.of(0x5b)] // [
+      for (let i = 0; i < o.items.length; i++) {
+        if (i > 0) parts.push(Uint8Array.of(SPACE))
+        parts.push(encodeObject(o.items[i]!))
+      }
+      parts.push(Uint8Array.of(0x5d)) // ]
+      return concatBytes(parts)
+    }
+    case 'dict':
+      return encodeDict(o)
+    case 'stream': {
+      // /Length must equal the post-filter data length (spec §5.1).
+      o.dict.entries.set('Length', { kind: 'num', value: o.data.length })
+      return concatBytes([
+        encodeDict(o.dict),
+        Uint8Array.of(LF),
+        STREAM_KW,
+        o.data,
+        ENDSTREAM_KW,
+      ])
+    }
+    default: {
+      const _exhaustive: never = o
+      throw new PdfGenError('PDF_INVALID_OBJECT', `Unknown object: ${_exhaustive}`)
+    }
+  }
+}
+
+function encodeDict(d: PdfDictionary): Uint8Array {
+  const parts: Uint8Array[] = [DICT_OPEN]
+  for (const [key, value] of d.entries) {
+    parts.push(encodeName(key), Uint8Array.of(SPACE), encodeObject(value), Uint8Array.of(SPACE))
+  }
+  parts.push(DICT_CLOSE)
+  return concatBytes(parts)
+}

package/src/objects/index.ts

@@ -0,0 +1,43 @@
+export type {
+  PdfObject,
+  PdfNull,
+  PdfBoolean,
+  PdfNumber,
+  PdfString,
+  PdfName,
+  PdfArray,
+  PdfDictionary,
+  PdfStream,
+  IndirectRef,
+} from './types.ts'
+export {
+  NULL,
+  bool,
+  num,
+  name,
+  arr,
+  dict,
+  ref,
+  dictSet,
+  isNull,
+  isBool,
+  isNum,
+  isStr,
+  isName,
+  isArr,
+  isDict,
+  isStream,
+  isRef,
+} from './types.ts'
+export { refToken, objHeader } from './indirect_ref.ts'
+export { formatNumber } from './number.ts'
+export { encodeName } from './name.ts'
+export {
+  literalBytes,
+  hexBytes,
+  textString,
+  dateString,
+  encodeLiteral,
+  encodeHex,
+} from './string.ts'
+export { encodeObject } from './encode.ts'

package/src/objects/indirect_ref.ts

@@ -0,0 +1,17 @@
+/**
+ * Indirect reference helpers (spec §5.2). The {@link IndirectRef} type itself
+ * lives in objects/types.ts; this module holds formatting used by both the
+ * object encoder and the xref writer.
+ */
+
+import type { IndirectRef } from './types.ts'
+
+/** `"<num> <gen> R"` — the in-body reference token. */
+export function refToken(r: IndirectRef): string {
+  return `${r.num} ${r.gen} R`
+}
+
+/** `"<num> <gen> obj"` — the indirect object definition header. */
+export function objHeader(num: number, gen: number): string {
+  return `${num} ${gen} obj`
+}

package/src/objects/name.ts

@@ -0,0 +1,50 @@
+/**
+ * Name token escaping (spec §5.1).
+ *
+ * A name is written as `/` followed by its characters. Any byte outside the
+ * regular range `! (0x21) … ~ (0x7e)`, plus the delimiters and `#` itself,
+ * is written as `#XX` (two uppercase hex digits).
+ */
+
+import { ascii, concatBytes } from '../util/ascii.ts'
+
+const HEX = '0123456789ABCDEF'
+
+function needsEscape(b: number): boolean {
+  if (b < 0x21 || b > 0x7e) return true
+  switch (b) {
+    case 0x23: // #
+    case 0x28: // (
+    case 0x29: // )
+    case 0x3c: // <
+    case 0x3e: // >
+    case 0x5b: // [
+    case 0x5d: // ]
+    case 0x7b: // {
+    case 0x7d: // }
+    case 0x2f: // /
+    case 0x25: // %
+      return true
+    default:
+      return false
+  }
+}
+
+/** Encode a name's value (without the leading `/`) to escaped bytes. */
+export function encodeName(value: string): Uint8Array {
+  const src = ascii(value)
+  const parts: Uint8Array[] = []
+  let runStart = 0
+
+  for (let i = 0; i < src.length; i++) {
+    const b = src[i]!
+    if (needsEscape(b)) {
+      if (i > runStart) parts.push(src.subarray(runStart, i))
+      parts.push(Uint8Array.from([0x23, HEX.charCodeAt(b >> 4), HEX.charCodeAt(b & 0x0f)]))
+      runStart = i + 1
+    }
+  }
+  if (runStart < src.length) parts.push(src.subarray(runStart))
+
+  return concatBytes([Uint8Array.from([0x2f]), ...parts]) // leading '/'
+}

package/src/objects/number.ts

@@ -0,0 +1,43 @@
+/**
+ * PDF number formatting (spec §5.1).
+ *
+ * - Integers serialized without a decimal point.
+ * - Reals serialized with up to 6 decimal places; trailing zeros stripped;
+ *   never in exponential notation.
+ * - Infinity, NaN, and -0 throw at the boundary.
+ *
+ * The same formatter is used for object encoding AND content-stream operands
+ * (spec §8.5) so numeric output is byte-identical everywhere.
+ */
+
+import { PdfGenError } from '../util/errors.ts'
+
+const MAX_DECIMALS = 6
+
+export function formatNumber(value: number): string {
+  if (!Number.isFinite(value)) {
+    throw new PdfGenError(
+      'PDF_INVALID_NUMBER',
+      `Cannot serialize non-finite number: ${value}`
+    )
+  }
+  // Reject negative zero explicitly: Object.is distinguishes -0 from 0.
+  if (Object.is(value, -0)) {
+    throw new PdfGenError('PDF_INVALID_NUMBER', 'Cannot serialize negative zero')
+  }
+
+  if (Number.isInteger(value)) {
+    return String(value)
+  }
+
+  // toFixed avoids exponential notation for the magnitudes PDF uses.
+  let s = value.toFixed(MAX_DECIMALS)
+
+  // Strip trailing zeros, then a trailing decimal point if all decimals went.
+  s = s.replace(/(\.\d*?)0+$/, '$1').replace(/\.$/, '')
+
+  // Rounding at 6 dp can yield "-0" or "-0.000000" → "-0"; normalize.
+  if (s === '-0') return '0'
+
+  return s
+}

package/src/objects/string.ts

@@ -0,0 +1,136 @@
+/**
+ * PDF strings (spec §5.1).
+ *
+ * A {@link PdfString} stores raw bytes plus a serialization hint. This module
+ * provides:
+ *  - constructors that turn JS strings / dates into the right byte sequence
+ *    (UTF-16BE with BOM by default for text strings, PDFDocEncoding opt-in);
+ *  - the literal and hex serializers used by objects/encode.ts.
+ */
+
+import { PdfGenError } from '../util/errors.ts'
+import { ascii } from '../util/ascii.ts'
+import type { PdfString } from './types.ts'
+
+// ── Constructors ──────────────────────────────────────────────────────────
+
+/** A string from raw bytes, serialized as a literal `( )` string. */
+export function literalBytes(value: Uint8Array): PdfString {
+  return { kind: 'str', value, encoding: 'literal' }
+}
+
+/** A string from raw bytes, serialized as a hex `< >` string. */
+export function hexBytes(value: Uint8Array): PdfString {
+  return { kind: 'str', value, encoding: 'hex' }
+}
+
+/**
+ * A human-readable "text string". Defaults to UTF-16BE with a leading
+ * `\xFE\xFF` BOM (PDF's text-string convention). With `encoding:'pdfdoc'`,
+ * characters must be representable in a single byte (Latin-1 subset of
+ * PDFDocEncoding) and are written verbatim.
+ */
+export function textString(
+  s: string,
+  opts: { encoding?: 'utf16be' | 'pdfdoc' } = {}
+): PdfString {
+  if (opts.encoding === 'pdfdoc') {
+    const out = new Uint8Array(s.length)
+    for (let i = 0; i < s.length; i++) {
+      const c = s.charCodeAt(i)
+      if (c > 0xff) {
+        throw new PdfGenError(
+          'PDF_INVALID_STRING',
+          `Character U+${c.toString(16)} not representable in PDFDocEncoding; use UTF-16BE`
+        )
+      }
+      out[i] = c
+    }
+    return { kind: 'str', value: out, encoding: 'literal' }
+  }
+
+  // UTF-16BE with BOM. Iterate code points so astral chars become surrogate
+  // pairs (two 16-bit units), which is the correct UTF-16 representation.
+  const units: number[] = [0xfe, 0xff]
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i)
+    units.push(code >> 8, code & 0xff)
+  }
+  return { kind: 'str', value: Uint8Array.from(units), encoding: 'hex' }
+}
+
+/**
+ * A PDF date string: `D:YYYYMMDDHHmmSSOHH'mm'` (ISO 32000-1 §7.9.4).
+ * Always UTC (`Z`-equivalent rendered as `+00'00'`) for determinism.
+ */
+export function dateString(date: Date): PdfString {
+  const p = (n: number, w = 2) => String(n).padStart(w, '0')
+  const s =
+    `D:${date.getUTCFullYear()}${p(date.getUTCMonth() + 1)}${p(date.getUTCDate())}` +
+    `${p(date.getUTCHours())}${p(date.getUTCMinutes())}${p(date.getUTCSeconds())}+00'00'`
+  return { kind: 'str', value: ascii(s), encoding: 'literal' }
+}
+
+// ── Serializers ───────────────────────────────────────────────────────────
+
+const HEX = '0123456789ABCDEF'
+
+/** Serialize bytes as a literal string `( ... )` with the minimal escaping. */
+export function encodeLiteral(value: Uint8Array): Uint8Array {
+  const out: number[] = [0x28] // (
+  for (const b of value) {
+    switch (b) {
+      case 0x5c: // backslash
+        out.push(0x5c, 0x5c)
+        break
+      case 0x28: // (
+        out.push(0x5c, 0x28)
+        break
+      case 0x29: // )
+        out.push(0x5c, 0x29)
+        break
+      case 0x0a: // \n
+        out.push(0x5c, 0x6e)
+        break
+      case 0x0d: // \r
+        out.push(0x5c, 0x72)
+        break
+      case 0x09: // \t
+        out.push(0x5c, 0x74)
+        break
+      case 0x08: // \b
+        out.push(0x5c, 0x62)
+        break
+      case 0x0c: // \f
+        out.push(0x5c, 0x66)
+        break
+      default:
+        if (b < 0x20 || b > 0x7e) {
+          // Octal escape \ddd for non-printable / high bytes.
+          out.push(
+            0x5c,
+            0x30 + ((b >> 6) & 0x7),
+            0x30 + ((b >> 3) & 0x7),
+            0x30 + (b & 0x7)
+          )
+        } else {
+          out.push(b)
+        }
+    }
+  }
+  out.push(0x29) // )
+  return Uint8Array.from(out)
+}
+
+/** Serialize bytes as a hex string `<...>`. */
+export function encodeHex(value: Uint8Array): Uint8Array {
+  const out = new Uint8Array(value.length * 2 + 2)
+  out[0] = 0x3c // <
+  let i = 1
+  for (const b of value) {
+    out[i++] = HEX.charCodeAt(b >> 4)
+    out[i++] = HEX.charCodeAt(b & 0x0f)
+  }
+  out[i] = 0x3e // >
+  return out
+}

package/src/objects/types.ts

@@ -0,0 +1,86 @@
+/**
+ * The PDF object model (spec §5). The seven PDF object types plus the
+ * indirect reference, modelled as a discriminated union on `kind`.
+ */
+
+export type PdfObject =
+  | PdfNull
+  | PdfBoolean
+  | PdfNumber
+  | PdfString
+  | PdfName
+  | PdfArray
+  | PdfDictionary
+  | PdfStream
+  | IndirectRef
+
+export type PdfNull = { kind: 'null' }
+export type PdfBoolean = { kind: 'bool'; value: boolean }
+/** Integer or real. Serialization decides formatting (objects/number.ts). */
+export type PdfNumber = { kind: 'num'; value: number }
+export type PdfString = {
+  kind: 'str'
+  /** Raw bytes — already in the final on-disk byte sequence. */
+  value: Uint8Array
+  /** Serialization hint: literal `( )` or hex `< >`. */
+  encoding: 'literal' | 'hex'
+}
+/** Unescaped name value (no leading slash, decoded #XX). */
+export type PdfName = { kind: 'name'; value: string }
+export type PdfArray = { kind: 'arr'; items: PdfObject[] }
+export type PdfDictionary = { kind: 'dict'; entries: Map<string, PdfObject> }
+export type PdfStream = {
+  kind: 'stream'
+  /** Includes /Length and /Filter. */
+  dict: PdfDictionary
+  /** Already-filtered bytes (final on-disk data). */
+  data: Uint8Array
+}
+export type IndirectRef = { kind: 'ref'; num: number; gen: number }
+
+// ── Constructors ──────────────────────────────────────────────────────────
+
+export const NULL: PdfNull = { kind: 'null' }
+
+export function bool(value: boolean): PdfBoolean {
+  return { kind: 'bool', value }
+}
+
+export function num(value: number): PdfNumber {
+  return { kind: 'num', value }
+}
+
+export function name(value: string): PdfName {
+  return { kind: 'name', value }
+}
+
+export function arr(items: PdfObject[] = []): PdfArray {
+  return { kind: 'arr', items }
+}
+
+/** Build a dictionary from an object literal (insertion order preserved). */
+export function dict(entries: Record<string, PdfObject> = {}): PdfDictionary {
+  return { kind: 'dict', entries: new Map(Object.entries(entries)) }
+}
+
+export function ref(num: number, gen = 0): IndirectRef {
+  return { kind: 'ref', num, gen }
+}
+
+// ── Type guards ───────────────────────────────────────────────────────────
+
+export const isNull = (o: PdfObject): o is PdfNull => o.kind === 'null'
+export const isBool = (o: PdfObject): o is PdfBoolean => o.kind === 'bool'
+export const isNum = (o: PdfObject): o is PdfNumber => o.kind === 'num'
+export const isStr = (o: PdfObject): o is PdfString => o.kind === 'str'
+export const isName = (o: PdfObject): o is PdfName => o.kind === 'name'
+export const isArr = (o: PdfObject): o is PdfArray => o.kind === 'arr'
+export const isDict = (o: PdfObject): o is PdfDictionary => o.kind === 'dict'
+export const isStream = (o: PdfObject): o is PdfStream => o.kind === 'stream'
+export const isRef = (o: PdfObject): o is IndirectRef => o.kind === 'ref'
+
+/** Set a dictionary entry, returning the dictionary for chaining. */
+export function dictSet(d: PdfDictionary, key: string, value: PdfObject): PdfDictionary {
+  d.entries.set(key, value)
+  return d
+}

package/src/output/buffer_sink.ts

@@ -0,0 +1,40 @@
+/**
+ * A {@link ByteSink} that accumulates everything into a single Uint8Array,
+ * returned by `PdfDocument.save()` (spec §3.3).
+ *
+ * Uses a geometrically-growing backing buffer to keep appends amortized O(1)
+ * and peak memory bounded (spec §18.6).
+ */
+
+import type { ByteSink } from './byte_sink.ts'
+
+export class BufferSink implements ByteSink {
+  private buf: Uint8Array
+  private len = 0
+
+  constructor(initialCapacity = 64 * 1024) {
+    this.buf = new Uint8Array(initialCapacity)
+  }
+
+  get length(): number {
+    return this.len
+  }
+
+  write(bytes: Uint8Array): void {
+    const needed = this.len + bytes.length
+    if (needed > this.buf.length) {
+      let cap = this.buf.length * 2
+      while (cap < needed) cap *= 2
+      const next = new Uint8Array(cap)
+      next.set(this.buf.subarray(0, this.len))
+      this.buf = next
+    }
+    this.buf.set(bytes, this.len)
+    this.len = needed
+  }
+
+  /** Return the exact written bytes (a copy sized to `length`). */
+  toBytes(): Uint8Array {
+    return this.buf.slice(0, this.len)
+  }
+}

package/src/output/byte_sink.ts

@@ -0,0 +1,12 @@
+/**
+ * The serialize pass writes through a {@link ByteSink} (spec §3.3). This keeps
+ * the document serializer agnostic to whether output is buffered in memory or
+ * streamed to a Writable. M1–M3 ship the buffer sink; StreamSink is M12.
+ */
+
+export interface ByteSink {
+  /** Append bytes. Implementations must not retain the passed array. */
+  write(bytes: Uint8Array): void
+  /** Total number of bytes written so far (used for xref offsets). */
+  readonly length: number
+}

package/src/output/index.ts

@@ -0,0 +1,3 @@
+export type { ByteSink } from './byte_sink.ts'
+export { BufferSink } from './buffer_sink.ts'
+export { StreamSink } from './stream_sink.ts'

package/src/output/stream_sink.ts

@@ -0,0 +1,62 @@
+/**
+ * A {@link ByteSink} that streams to a Node `Writable` (spec §3.3) — for
+ * HTTP responses or files without buffering the whole PDF in memory.
+ *
+ * The serialize pass calls `write()` synchronously many times; chunks are
+ * handed straight to the stream (Node applies its own backpressure buffering).
+ * `done()` ends the stream and resolves once it has fully flushed; a stream
+ * error at any point (including during the synchronous write burst, which
+ * surfaces asynchronously) makes `done()` reject.
+ */
+
+import type { Writable } from 'node:stream'
+import type { ByteSink } from './byte_sink.ts'
+
+export class StreamSink implements ByteSink {
+  private len = 0
+  private err?: Error
+
+  constructor(private readonly out: Writable) {
+    // Capture errors that occur during the write burst, before done().
+    out.on('error', e => {
+      this.err ??= e as Error
+    })
+  }
+
+  get length(): number {
+    return this.len
+  }
+
+  write(bytes: Uint8Array): void {
+    if (this.err) return
+    try {
+      // Copy: the serializer may reuse buffers; Node keeps the chunk async.
+      // The per-write callback reports failures even when no 'error' event
+      // is emitted (some runtimes don't emit one for a failed write).
+      this.out.write(Buffer.from(bytes), e => {
+        if (e) this.err ??= e
+      })
+    } catch (e) {
+      this.err ??= e as Error
+    }
+    this.len += bytes.length
+  }
+
+  /** End the stream; resolves on flush, rejects on any stream error. */
+  done(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      if (this.err) return reject(this.err)
+      const onError = (e?: Error) => {
+        this.out.off('finish', onFinish)
+        reject(this.err ?? e ?? new Error('stream error'))
+      }
+      const onFinish = () => {
+        this.out.off('error', onError)
+        this.err ? reject(this.err) : resolve()
+      }
+      this.out.once('error', onError)
+      this.out.once('finish', onFinish)
+      this.out.end()
+    })
+  }
+}