Should extractContent() or some other call give enough details to fully reconstruct the page?

[anonghuser]

Right now extractContent() gives reasonably detailed info to accurately redraw images on a new document/page (actually it still lacks skew/rotation but those are rarely used I guess).
But it gives very few details about text - lacking render mode, colors, skew, max width, scale and rotation (btw that wasn't in the drawText arguments for some reason), as well as only giving the font name but with no way to actually extract the font and add it to another document/page.
It also is not accurate about SVG/shapes, though I can't really point out in what ways since I only did very little testing. All I know it trying to repeat them with drawSVG on a new page made a complete mess with everything being offset randomly.

Is extractContent() planned to be more detailed and accurate eventually, and is just a work in progress for now? Will it ever allow actual editing of PDF docs, as in getting the current objects, changing some in some ways, and redrawing them? It's a real bummer how the current claims about "editing" capabilities are really nothing more than overlaying stuff on top, I don't think that counts at all.

If extractContent() is not intended to be as detailed as I hoped, could the library get some lower level, not object-level but say pdf operator list level or raw decompressed text get/set functionality that will allow editing, even if with more effort and requiring knowledge of more PDF internals?

[fstandhartinger]

One thing first, because it decides where your roadmap question goes: extractContents() is not in this repo. Upstream pdf-lib is still 1.17.1, and that release has no extraction API. The method comes from the Cantoo fork, @cantoo/pdf-lib, which added it on 2026-08-12. So "will it get more detailed?" is a question for cantoo-scribe/pdf-lib. That repo has no Discussions, but its issues are open. This repo's last commit on master was in November 2021.

What you're seeing is by design in 2.11.1. A text asset has exactly getText, x, y, fontSize, fontFamily (see src/api/extraction/types.ts). The fill colour and the text matrix are tracked while the page is walked, but they are never emitted. Tr, Tc, Tw and Tz aren't interpreted at all. Two more limits I measured:

• fontSize is the raw Tf operand. /F1 1 Tf 12 0 0 12 50 100 Tm (…) Tj reports fontSize: 1, not 12. Many generators write text that way.
• Inline images (BI … ID … EI) are skipped by the parser, so they appear neither in the assets nor in the operator list.

Your third question already has an answer: the same fork exports the parser it uses. parseContentStream(bytes) returns [{ name, args }] for every operator, so you can edit at the operator level today. You need a small serializer to write the list back. This rewrites a page in place:

const fs = require('fs');
const {
  PDFDocument, PDFArray, PDFRawStream, PDFContentStream, PDFName,
  parseContentStream, decodePDFRawStream,
} = require('@cantoo/pdf-lib');

// Operand -> PDF syntax (inverse of parseContentStream)
const ser = (a) => {
  if (typeof a === 'number') return String(+a.toFixed(6));
  if (Array.isArray(a)) return '[' + a.map(ser).join(' ') + ']';
  if (a.type === 'name') return '/' + a.value;
  if (a.type === 'hexString') return '<' + Buffer.from(a.bytes).toString('hex') + '>';
  if (a.type === 'string')
    return '(' + Buffer.from(a.bytes).toString('latin1').replace(/[\\()]/g, '\\$&') + ')';
  return '<<' + Object.entries(a).map(([k, v]) => '/' + k + ' ' + ser(v)).join(' ') + '>>';
};

// All content streams of a page, decoded and parsed into [{ name, args }]
const readOps = (page) => {
  const c = page.node.Contents();
  const streams = c instanceof PDFArray
    ? c.asArray().map((r) => page.doc.context.lookup(r)) : [c];
  const parts = streams.map((s) => Buffer.from(
    s instanceof PDFRawStream ? decodePDFRawStream(s).decode()
    : s instanceof PDFContentStream ? s.getUnencodedContents() : s.getContents()));
  return parseContentStream(Buffer.concat(parts.flatMap((b) => [b, Buffer.from('\n')])));
};

const writeOps = (page, ops) => {
  const ctx = page.doc.context;
  const body = ops.map((o) => [...o.args.map(ser), o.name].join(' ')).join('\n');
  page.node.set(PDFName.of('Contents'), ctx.register(ctx.flateStream(body)));
};

(async () => {
  const doc = await PDFDocument.load(fs.readFileSync(process.argv[2]));
  const page = doc.getPage(0);
  const ops = readOps(page);

  let inText = false;
  for (const o of ops) {
    if (o.name === 'BT') inText = true;
    if (o.name === 'ET') inText = false;
    if (inText && o.name === 'rg') o.args = [0.5, 0, 0.5];          // text fill -> purple
    if (o.name === 'Tj' && o.args[0].bytes) {                        // edit the shown string
      const s = Buffer.from(o.args[0].bytes).toString('latin1').replace('Hello', 'Howdy');
      o.args[0] = { type: 'string', bytes: Buffer.from(s, 'latin1') };
    }
  }
  writeOps(page, ops);
  fs.writeFileSync(process.argv[3], await doc.save());
})();

I ran this on a page drawn with drawText(…, { rotate: degrees(15), renderMode: FillAndOutline, color: red }) plus a rectangle. The operator list held everything the asset dropped: 1 0 0 rg, 0 0 1 RG, 2 Tr, 0.965926 0.258819 -0.258819 0.965926 140 60 Tm, /Helvetica-Bold-… 24 Tf. After the edit, poppler renders purple "Howdy world" with the rotation and outline intact, and the rectangle untouched.

Caveats before you rely on it:

• String edits only work for simple fonts. With a subset-embedded Type0/CID font the Tj bytes are glyph IDs, and characters outside the subset don't exist in the file. You can recolour, move, delete or re-transform that text, but you can't type new characters into it.
• Inline images get dropped on a round trip, because the parser skips them. Check for BI in the raw bytes before writing back.
• Do operators that paint Form XObjects have their own content streams. Edit those through the XObject, not the page.

To get a page into another document, don't redraw it from extracted assets. Copy it: const [p] = await target.copyPages(src, [0]); target.addPage(p);. That carries the content stream, fonts and images verbatim. I copied the edited page this way, and re-extracting gives "Howdy world" in Helvetica-Bold. If you need the page as an object on a bigger page, use embedPage(). I didn't test whether your drawSVG offsets come from the y-flip that getSvg() applies (its comment says it flips Y). Your misaligned shapes look like that, but I can't say for sure.

Tested with @cantoo/pdf-lib 2.11.1 on Node 26, rendered with poppler pdftoppm.

Disclosure: I build a hosted HTML→PDF API. It has nothing to do with this and isn't linked. This answer was written with AI assistance (Claude Code), and every snippet and number above was run as shown.

[anonghuser]

the cantoo repo links to this repo's discussions in various md files as well as in the new issue "wizard" or whassname

[anonghuser]

"To get a page into another document..." well that's a black box approach, what I ultimately want was to understand and change some elements. In particular I have a PDF with tiling gap artifacts that I want to automatically fix, but as a more general long term goal any actual edit should be possible for a library that dares to claim it can "edit" and not just "overlay" PDFs.