Coder Legion - Recent posts tagged pdf

Fine in Chrome, broken in Preview: two PDFKit gotchas for anyone who writes PDFs

Mon, 26 Oct 2026 00:16:01 +0000

This article was originally published on Hashnode: Fine in Chrome, broken in Preview. It is republished here with light edits.

Disclosure: we make LensUp's PDF editor, the browser tool where we ran into both bugs, so we have a direct connection to the product mentioned here. This write-up was drafted and edited with AI assistance; the bugs, test results and reproduction scripts come from our own testing, and the scripts are public so you can check every claim yourself.

We build a PDF editor that runs in the browser. It opens a PDF, lets you add text, a signature or a highlight, fill in form fields, and writes the result back as an incremental update. We checked every save with three renderers: pdf.js (Firefox and many web viewers), pdfium (Chrome) and poppler (most Linux tools). All three were happy.

Then we rendered the same files with Apple's PDFKit, the engine behind Preview on the Mac, the Files app on iOS and PDFs in Safari. It showed two problems none of the others did: a translucent highlighter that turned into an opaque bar or a sentence that vanished, and form answers printed twice on top of each other.

Neither problem shows up if you only test on Linux or in Chrome. Here are both, with small scripts that reproduce them on any Mac in a few seconds: github.com/ppop123/pdfkit-pitfalls.

Gotcha 1: an incremental update must use the same cross-reference form as the file it updates

Some background

An incremental update appends to a PDF instead of rewriting it. The new and changed objects go at the end, followed by a new cross-reference section that points back to the previous one. That's how signed PDFs stay signed, and it's why saving an edit doesn't mean rewriting the whole file: only the edit is written.

The cross-reference section comes in two forms. The classic one is an xref table followed by a trailer. PDF 1.5 added cross-reference streams (/Type /XRef), which usually come with object streams (/Type /ObjStm): many small non-stream objects compressed together into one stream.

We opened files for incremental update with pdf-lib (the @cantoo/pdf-lib fork, which supports incremental updates) and saved with the defaults, which turn object streams on. So whatever the original file used, our update ended in an XRef stream, with our new dictionaries packed into an object stream.

What PDFKit does with that

Take a one-page PDF that ends in a classic xref table and append a highlighter stroke: a yellow rectangle drawn through an ExtGState with 60% opacity and the Multiply blend mode. Written as a table-based update, it renders the same everywhere. Written as an XRef stream with the ExtGState inside an object stream, poppler still draws it correctly, but PDFKit shows an opaque yellow bar where the sentence was.

Render it with CG_PDF_VERBOSE=1 set, and CoreGraphics says why:

encountered unexpected object type: 7.
missing or invalid object number.
missing or invalid cross-reference stream.

It gives up on the update's XRef stream. Objects the update wrote out on their own are still found: the rectangle itself is drawn. Objects inside the update's object stream are not, and the ExtGState is one of them. Without it the rectangle is painted fully opaque, on top of the text.

The reverse breaks too. Over an original that ends in an XRef stream, an update written with a classic table gets:

failed to find start of cross-reference section.
font `Helvetica-7098480789' not found in document.

This time it's the original's object stream that gets lost, and the font was in it. The highlight is there; the sentence is gone.

Original's last section	Update written as	PDFKit
`xref` table	`xref` table	fine
`xref` table	XRef stream with object streams	loses the objects in the update's object stream
XRef stream	`xref` table	loses the objects in the original's object streams
XRef stream	XRef stream	fine

In our editor's checks, pdf.js, pdfium and poppler accepted all four combinations. That's exactly why a Linux-only test suite never caught it.

The fix

Look at where the original's last startxref points. If it lands on the keyword xref, the last section is a table; otherwise it's a stream. Then write the update in the same form:

// The form of the original's last cross-reference section: 'table' or 'stream'.
function xrefForm(bytes) {
  const tail = new TextDecoder('latin1').decode(bytes.subarray(Math.max(0, bytes.length - 2048)));
  const found = [...tail.matchAll(/startxref\s+(\d+)/g)];
  const offset = found.length ? Number(found[found.length - 1][1]) : NaN;
  if (!(offset >= 0 && offset < bytes.length)) return 'table';
  let i = offset;
  while (i < bytes.length && /\s/.test(String.fromCharCode(bytes[i]))) i += 1;
  return new TextDecoder('latin1').decode(bytes.subarray(i, i + 4)) === 'xref' ? 'table' : 'stream';
}

const doc = await PDFDocument.load(bytes, { forIncrementalUpdate: true });
// … edit …
const saved = await doc.save({ useObjectStreams: xrefForm(bytes) === 'stream' });

Hybrid-reference files, whose trailer is a table that also points to an XRef stream, end in a table, so they count as 'table' here.

Gotcha 2: PDFKit draws filled text fields itself

What PDFKit does

A form field's look is supposed to come from its appearance stream (/AP): a small content stream in which the writer draws the value. For a text field that has a value, PDFKit does something else. It draws the value (/V) itself with CoreText, in the font named by the field's default appearance string (/DA), and it drops the text-showing operators (BT … Tj … ET) from the appearance stream. Everything else in the appearance stream it still paints, such as paths and Form XObjects.

You can see the first half even with pdf-lib's own appearance. In the first row below, poppler draws pdf-lib's auto-sized Helvetica, while PDFKit ignores it and draws its own rendering of the value at a different size.

Why that bit us

Our text engine shapes text itself (joining Persian and Arabic, ordering mixed-direction text, falling back between fonts) and draws the result as glyph outlines, so every reader shows exactly the same glyphs. In a field's appearance, those outlines are paths. PDFKit painted the paths and then drew /V again with CoreText on top: two copies of every answer, as in the second row. On a real IRS W-9 the two copies didn't even line up, because PDFKit left-aligned its copy while our appearance was right-aligned.

None of these stopped the second drawing: making the field read-only, setting /NeedAppearances to false, removing the /Tx BMC … EMC marked content, or changing the font or color in /DA.

The fix

Write the value as text after all, just not in a real font: use a Type 3 font whose glyph procedures are the same outlines. PDFKit drops text-showing operators, Type 3 included, and draws the value once in its own rendering. pdf.js, pdfium and poppler draw the Type 3 glyphs, which are our outlines. That's the third row.

The trade-off is that in Preview you get PDFKit's rendering of the value (its font from /DA, its alignment), not yours. For us that was acceptable, since CoreText shapes Persian correctly.

Two related notes:

Dropdowns and list boxes are different. PDFKit doesn't redraw them, so for choice fields we kept the outlines.
Acrobat had its own problem with outlines. Acrobat Reader drew our outline appearances in some forms but left the box blank in others (fields created by pdf-lib, with a /MK background color). It drew the Type 3 version in both.

Bonus gotcha from Acrobat: Reader extensions (`/UR3`)

Many official forms, the W-9 among them, carry usage rights (/Perms /UR3, "Reader extensions"): a signature over the file as issued. Change the file and Acrobat Reader opens it with:

This document enabled extended features in Adobe Acrobat Reader. The document has been changed since it was created and use of extended features is no longer available.

Every save changes the file, so on save we now remove /UR3 and the older /UR from /Perms (and /Perms itself if nothing else is left). A certification signature (/DocMDP) stays. iText does the same thing with removeUsageRights. To be clear about what we've checked: we saw the warning in Acrobat Reader, and we haven't re-tested the fixed files there yet.

How to test with PDFKit without clicking through Preview

PDFKit is scriptable from Swift in about twenty lines: open the file with PDFDocument, draw page 1 into a bitmap with PDFPage.draw(with:to:) (form widgets included), and write a PNG. Run it with CG_PDF_VERBOSE=1 and CoreGraphics prints what it didn't like. The repo's render-pdfkit.swift does exactly that. qlmanage -t, the Quick Look thumbnailer, goes through PDFKit too.

If you compare against pdfium from Python: pypdfium2 doesn't draw form fields unless you call pdf.init_forms() first. Without it, every field looks empty, which is easy to mistake for a bug in your writer.

Takeaways

Three renderers agreeing on a file doesn't mean the viewer on every Mac and iPhone will. If your PDFs reach Apple devices, render them with PDFKit, in CI on a macOS runner or at least by hand.
In an incremental update, match the cross-reference form of the file you're updating.
For a filled text field, PDFKit draws the value itself. Avoid drawing the value into the appearance as paths; text in a Type 3 font works everywhere we tested.

The reproductions, in Node and Swift, are MIT-licensed: github.com/ppop123/pdfkit-pitfalls.

About the author: the team behind this post builds LensUp Scanner, a free set of browser tools for scanning documents and working with PDFs. If you have seen other PDFKit quirks, the pdfkit-pitfalls repo is open to issues and pull requests.

Designing a Clear Upload-to-Export Flow for Four Document Jobs

Fri, 25 Sep 2026 14:56:23 +0000

An upload control can look simple while hiding a product decision: what does the person want to accomplish with the file? A scanned page, a photo of a document, searchable text, and a spreadsheet-ready receipt are related, but they are not the same job. A useful interface makes those paths legible before the user starts.

ScanPDF AI presents four entry points—Scan PDF, Photo to PDF, OCR PDF, and Receipt to Excel. The interface gives us a concrete example of organizing around outcomes rather than asking everyone to start with one generic “upload” action.

A task selector is part of the product model

Designing workflow labels means deciding which distinctions matter to users. For document work, the source file may be a PDF, a phone image, or a photo of a receipt. Yet the source alone does not tell us the desired result. Someone may want a portable document, extracted text, or structured transaction details.

Putting those options near the start lets people choose by intent. It also helps a team keep each workflow’s promise narrow. A photo-to-PDF path can focus on document conversion. An OCR path can explain recognized-text exports. A receipt path can set expectations about fields and spreadsheet output.

Show an output contract before upload

The OCR page lists PDF, JPG, PNG, and WebP inputs and describes PDF, TXT, and DOCX exports. The receipt page describes PDF, TXT, and CSV output, and names merchant, date, total, tax, currency, and line items. This is a useful pattern: tell users what kind of artifact a workflow is intended to produce before they invest time in it.

For product designers, the next improvement to look for is whether that contract remains visible after selection. Are supported formats near the file picker? Is the output type clear before a potentially lengthy upload? Does the result screen distinguish editable text from a formatted document? These are practical review questions, not assumptions about any one implementation.

Keep “recognized” separate from “verified”

OCR and extraction outputs can look authoritative because they are neatly formatted. That presentation should not imply perfect recognition. A receipt total might be confused with a subtotal; a date can be ambiguous; a low-quality image can omit a line. Products should make it easy to inspect extracted values and correct them before export.

An example on a marketing page can explain the shape of the result, but it is not evidence of performance on arbitrary files. Teams evaluating a tool should test varied samples, including skewed photos, faded print, multiple currencies, and receipts with several tax or line-item formats. Review actual outputs before incorporating them into an operational workflow.

Design for the whole handoff

The interaction does not end when a file is accepted. People need to know how the document will be processed, where the result appears, which export fits their next tool, and what they should verify. Good labels and clear output options can remove uncertainty without adding more controls.

That is the broader lesson from these four paths: map the interface to the user’s next decision. When scanning, conversion, OCR, and structured extraction are presented as distinct jobs, the product can explain each one honestly—and users can pick the outcome they actually need.

Shipping Internal Tools: Why Build Automation Matters More Than Code Quality

Thu, 17 Sep 2026 13:51:38 +0000

A practitioner's guide to shipping PDF tools and automation to non-technical users. Lessons from three years of production tooling at a legal process serving company.

The Setup: Why This Matters

I've been building PDF tools for a legal process serving company for three years. The most valuable lesson didn't come from Python—it came from learning that packaged tools are infrastructure, not applications. The difference is profound.

Most tutorials teach you to write a Python script and hand it to PyInstaller. This post teaches you something different: how internal tools actually ship in production, what trade-offs matter, and why the boring build script is where the real engineering lives.

Last year, we shipped a batch PDF page extractor. Nothing fancy—extract the last page of a PDF, name it consistently, process an entire folder in one click. Our filing staff use it dozens of times daily.

Here's what surprised me: the code quality barely matters. The build automation, UX design, and reproducibility matter infinitely more. A tool with mediocre code that ships, iterates, and doesn't break is better than perfect code that doesn't exist.

This post walks through the real decisions: library choices with tradeoffs, packaging alternatives with honest pros/cons, and build infrastructure that scales from one tool to fifty.

Part 1: Choosing Your PDF Library — The Tradeoff Matrix

Most posts gloss over this. They'll say "use PyMuPDF" and move on. But for production tools, library choice cascades into build size, speed, and compatibility. Let's actually compare.

PyMuPDF (fitz)

import fitz
doc = fitz.open("file.pdf")
new_doc = fitz.open()
new_doc.insert_pdf(doc, from_page=5, to_page=5)
new_doc.save("output.pdf")

✓ Pros:

Fastest page extraction (C backend via SWIG)
No re-encoding—copies raw page bytes, preserves quality
Handles complex PDFs (annotations, forms, transparencies) better than pure Python
Lowest memory footprint for large files

✗ Cons:

~25 MB added to .exe (largest of all options)
Commercial licensing required for some use cases (read the terms for your scenario)
Smaller community than PyPDF2

Best for: Batch processing, large files, production tools where speed/reliability > size

PyPDF2

from PyPDF2 import PdfReader, PdfWriter
reader = PdfReader("file.pdf")
writer = PdfWriter()
writer.add_page(reader.pages[0])
writer.write("output.pdf")

✓ Pros:

Pure Python, no native dependencies
Adds only ~3 MB to .exe
Permissive BSD license
Large, well-documented community

✗ Cons:

Slower on large files (pages are re-encoded in Python)
Poor handling of complex PDFs
Higher memory use
Recent versions have performance regression issues

Best for: Simple PDFs, license-conscious projects, minimal file size

pdfplumber

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    page = pdf.pages[0]
    # Good for extraction/analysis, not for rewriting

✓ Pros:

Designed for text/table extraction (excels here)
Built on pdfminer.six + PyPDF2
Cleaner API for reading

✗ Cons:

Not meant for page manipulation
Slower than PyMuPDF for batch operations
Adds ~10 MB to .exe

Best for: Data extraction, not page manipulation

Nuitka (Compilation, Not a Library)

Some will suggest compiling the entire thing with Nuitka instead of PyInstaller. Don't. For internal tools:

Nuitka compilation takes 20–60 seconds per build (vs. 5 seconds for PyInstaller)
Final binary is only 5–10% smaller (marginal)
Debugging is harder
Not worth it unless you're shipping to thousands of users

Verdict: Use PyMuPDF for production tools. The 25 MB is negligible on modern systems, and the speed/reliability gain is real.

Part 2: The Actual Tool (With Lessons Baked In)

Here's a production-ready extractor:

#!/usr/bin/env python3
"""
last_page_extractor.py — Extract last pages from PDFs in bulk.

Modes:
  • Double-click in folder with PDFs → processes all .pdf files
  • Drag-drop files → processes only those files
  • Command line → same as drag-drop
"""

import sys
from pathlib import Path

try:
    import fitz
except ImportError:
    print("ERROR: pymupdf not installed. Install with: pip install pymupdf")
    sys.exit(1)


def extract_last_page(input_pdf: str) -> bool:
    """Extract last page. Return True if successful."""
    input_path = Path(input_pdf)
    
    if not input_path.exists():
        print(f"  ✗ Not found: {input_pdf}")
        return False
    
    if not input_path.suffix.lower() == ".pdf":
        print(f"  ✗ Not PDF: {input_pdf}")
        return False
    
    try:
        doc = fitz.open(input_pdf)
        page_count = len(doc)
        
        if page_count == 0:
            print(f"  ✗ Empty: {input_pdf}")
            doc.close()
            return False
        
        # Extract last page
        new_doc = fitz.open()
        new_doc.insert_pdf(doc, from_page=page_count - 1, to_page=page_count - 1)
        
        # Output: consistent naming
        output_path = input_path.parent / f"{input_path.stem}_last_page.pdf"
        new_doc.save(output_path)
        new_doc.close()
        doc.close()
        
        print(f"  ✓ {input_path.name} ({page_count} pages)")
        return True
        
    except Exception as e:
        print(f"  ✗ Error: {input_pdf}: {e}")
        return False


def process_folder() -> None:
    """Batch mode: scan folder for all PDFs."""
    cwd = Path.cwd()
    pdf_files = sorted(cwd.glob("*.pdf"))
    
    if not pdf_files:
        print(f"No PDFs found in: {cwd}")
        input("Press Enter to exit...")
        return
    
    print(f"\nFound {len(pdf_files)} PDF(s). Processing...\n")
    
    success = sum(1 for f in pdf_files if extract_last_page(str(f)))
    
    print(f"\n✓ {success}/{len(pdf_files)} successful")
    input("Press Enter to exit...")


def process_files(files: list) -> None:
    """Drag-drop mode: process specific files."""
    print(f"\nProcessing {len(files)} file(s)...\n")
    success = sum(1 for f in files if extract_last_page(f))
    print(f"\n✓ {success}/{len(files)} successful")


if __name__ == "__main__":
    if len(sys.argv) == 1:
        process_folder()
    else:
        process_files(sys.argv[1:])

Design decisions that matter:

Return boolean, not exit on error — Allows batch processing to continue when one file fails
Consistent naming — _last_page suffix is predictable (staff can glob these later)
Two modes baked in — Same binary, context-aware behavior
Output format — Checkmarks + filename + page count. Users see what happened.
Pause at end — input("Press Enter...") is intentional. Windows closes console windows instantly; this gives users a moment to see results.

Part 3: Packaging Alternatives (Beyond PyInstaller)

Everyone reaches for PyInstaller. Here's why it's right for this use case—and when it isn't.

PyInstaller (Our Choice)

pyinstaller --onefile --console last_page_extractor.py
# Creates: dist/last_page_extractor.exe (~35 MB)
# Build time: ~5 seconds

Trade-offs:

Size: 35 MB (PyMuPDF + Python + runtime)
Speed: Instant startup for small tools, 2–3 sec for complex ones
Debuggability: Can inspect .exe with --debug all if needed
Compatibility: Works on Windows 7+; no C++ redistributables needed

When to use: Internal tools, small teams, iterative development. Build automation is frictionless.

cx_Freeze

cxfreeze --target-dir dist last_page_extractor.py
# Creates: dist/last_page_extractor.exe + libraries/ folder

Trade-offs:

Size: Smaller .exe (~20 MB) but requires library folder
Distribution: Users get a folder, not one file (friction)
Build time: 8–12 seconds
Debuggability: Less mature than PyInstaller

Verdict: Never, honestly. The folder distribution kills the benefit of smaller size.

Auto-py-to-exe

This is a GUI wrapper around PyInstaller. Don't use for automation.

Why? You can't script it, you can't version it, you can't integrate it into CI/CD. Build infrastructure needs to be reproducible code.

Nuitka (Honest Assessment)

python -m nuitka --onefile last_page_extractor.py
# Creates: last_page_extractor.exe (~28 MB)
# Build time: 45–120 seconds (!!)

Trade-offs:

Size: 5–10% smaller (~28 MB vs. 35 MB)
Speed: Compiled Python is faster, but doesn't matter for this workload
Build time: 10–20x slower than PyInstaller
Debugging: Harder to debug; less community resources

Verdict: Not worth it. The 7 MB savings costs you 100+ extra seconds per build. On your 50th build, you've wasted 1.5 hours.

Recommendation: Use PyInstaller for anything under 100 MB final size or under 10 seconds build time. If you hit that limit, reconsider your approach—probably your tool is doing too much.

Part 4: Build Automation (The Real Infrastructure)

Here's the honest truth: the Python code is 20% of shipping. The build script is 80%.

Most tutorials ignore this. They'll show you pyinstaller --onefile and say "now you have an exe." They don't mention:

What Python version the user has installed
Whether PyInstaller is in their PATH
Whether they're on a network drive (UNC paths break PyInstaller)
What happens when their venv is stale
How to version builds
How to handle rebuilds without pollution

Here's a production build script:

<#
.SYNOPSIS
  Build last_page_extractor.py → last_page_extractor.exe
.DESCRIPTION
  Handles venv creation, dependency installation, PyInstaller build.
  Detects Python variant (py, python, python3).
  Handles UNC paths by staging to %LOCALAPPDATA%.
  Creates dist/last_page_extractor.exe.
#>

$ErrorActionPreference = "Stop"
$scriptDir = $PSScriptRoot

# ── UNC path handling (network drives cause PyInstaller to fail) ──────────
$isUNC = $scriptDir -match '^\\\\' -or $scriptDir -match '^//'
if ($isUNC) {
    $stageDir = Join-Path $env:LOCALAPPDATA "lpe_build_berman"
    Write-Host "[UNC Path] Staging to local: $stageDir"
    if (Test-Path $stageDir) { Remove-Item $stageDir -Recurse -Force }
    Copy-Item $scriptDir $stageDir -Recurse
    Set-Location $stageDir
} else {
    Set-Location $scriptDir
}

# ── Find Python (works with py, python, python3) ───────────────────────
$py = $null
foreach ($candidate in @("py -3", "python", "python3")) {
    try {
        $ver = & ([scriptblock]::Create("$candidate --version")) 2>&1
        if ($ver -match "Python 3\.([8-9]|1[0-9])") { 
            $py = $candidate
            break 
        }
    } catch {}
}
if (-not $py) {
    Write-Host "ERROR: Python 3.8+ not found" -ForegroundColor Red
    exit 1
}
Write-Host "Python: $py ($ver)"

# ── Clean old build artifacts ─────────────────────────────────────────
if (Test-Path "build") { Remove-Item "build" -Recurse -Force }
if (Test-Path "dist") { Remove-Item "dist" -Recurse -Force }
if (Test-Path ".venv") { Remove-Item ".venv" -Recurse -Force }

# ── Create venv ───────────────────────────────────────────────────────
Write-Host "Creating venv..."
& ([scriptblock]::Create("$py -m venv .venv"))

$pip = Join-Path ".venv" "Scripts\pip.exe"
$pyVenv = Join-Path ".venv" "Scripts\python.exe"

# ── Install dependencies ─────────────────────────────────────────────
Write-Host "Installing dependencies..."
& $pip install --upgrade pip --quiet
& $pip install pymupdf pyinstaller --quiet
if ($LASTEXITCODE -ne 0) {
    Write-Host "Dependency installation failed" -ForegroundColor Red
    exit 1
}

# ── Build with PyInstaller ────────────────────────────────────────────
Write-Host "Building exe..."
& $pyVenv -m PyInstaller `
    --onefile `
    --console `
    --name last_page_extractor `
    --clean `
    last_page_extractor.py

if ($LASTEXITCODE -ne 0) {
    Write-Host "PyInstaller build failed" -ForegroundColor Red
    exit 1
}

# ── Verify and copy back ──────────────────────────────────────────────
$exe = Join-Path "dist" "last_page_extractor.exe"
if (-not (Test-Path $exe)) {
    Write-Host "ERROR: .exe not found at $exe" -ForegroundColor Red
    exit 1
}

Write-Host "SUCCESS: Built $exe" -ForegroundColor Green

if ($isUNC) {
    Copy-Item $exe (Join-Path $scriptDir "last_page_extractor.exe") -Force
    Write-Host "Copied to: $scriptDir\last_page_extractor.exe"
}

Write-Host "`nBuild complete. Ready to ship."

Wrap in a .cmd for non-technical users:

@echo off
REM BuildExe.cmd — double-click to build
powershell -ExecutionPolicy Bypass -File "%~dp0build_exe.ps1"
pause

Why this script matters:

Python detection — Works whether user has py, python, or python3
UNC path handling — Network drives fail with PyInstaller; script detects and stages locally
Clean builds — Removes old artifacts each time (prevents stale builds)
Version check — Requires Python 3.8+ (PyMuPDF requirement)
Error handling — Fails loudly if any step breaks
One-click for users — BuildExe.cmd is trivial to run

The script is 50 lines. The gain is automatic rebuilds without friction. That's the real shipping.

Part 5: Learnings from Three Years of Shipping

1. Batch UX > Code Quality

A mediocre tool that processes a whole folder beats a beautiful tool that only works on one file. Users don't care about your code. They care about not doing it manually.

2. The Build Script is Your Insurance Policy

When you find a bug, you fix the Python file. Your build script proves it works reproducibly. In three years, we've shipped bug fixes in <10 minutes because the build was automated. Without it? 30+ minutes of manual setup each time.

3. Console Output is Richer Than You Think

We use --console (not --windowed) specifically so staff see output. Checkmarks (✓) vs crosses (✗) are scannable. File counts are proof the tool worked. input("Press Enter...") at the end is the pause button—Windows closes console windows instantly; you need to force it to stay.

4. Venv Per Build, Not Shared

Some shops keep a single venv and rebuild from it. Don't. Create fresh each time:

5 extra seconds
Guarantees clean isolation
Catches hidden dependency issues
Avoids "works on mine" errors

5. PyInstaller + Fresh Venv Beats All Alternatives

We considered Nuitka, cx_Freeze, even .NET (C#). PyInstaller wins because:

Simplest to automate
Fastest builds (under 10 seconds)
Easiest to debug
Smallest mental overhead

Optimize elsewhere. Not here.

6. Output Naming is Part of UX

<name>_last_page.pdf is predictable. Staff know what happened. If you shipped output_1.pdf, they'd hate you. Boring naming is invisible—that's good.

7. Two-Mode UX (Folder + Files) is Invisible

Same binary, no config, no menus. Double-click → scan folder. Drag files → process those. The code detects context (sys.argv length) and does the right thing. Users see one tool with two behaviors. This is underrated engineering.

Part 6: Scaling to a Tool Suite

We've shipped 12+ tools on this foundation:

Batch PDF splitters (first page, last page, even pages, ranges)
Missouri county filing fee lookups (CSV + web scraping)
Case.net metadata extractors (Selenium + PDF parsing)
Court PACER integrations
File renaming utilities

The pattern:

First tool: invest in build script (one-time cost)
Second tool: copy script, change filename
Tenth tool: you have a template; new tools are 1–2 hours of work

We've paid off the build script investment 12x over in dev time saved.

The Complete Package

You need three files:

last_page_extractor.py (100 lines)

# (code from Part 2 above)

build_exe.ps1 (60 lines)

# (script from Part 4 above)

BuildExe.cmd (4 lines)

@echo off
powershell -ExecutionPolicy Bypass -File "%~dp0build_exe.ps1"
pause

Workflow

Double-click BuildExe.cmd
Wait 10 seconds
Get dist/last_page_extractor.exe
Give to staff
They double-click it in a folder of PDFs
All last pages extract automatically
They see results; they know it worked

No terminal knowledge required anywhere.

Conclusion: Boring Infrastructure Wins

The software development world obsesses over code elegance, design patterns, and frameworks. But shipping tools to non-technical users teaches you something different: boring infrastructure beats clever code.

A well-built tool with mediocre Python code ships faster, iterates faster, and scales better than a beautifully architected tool with no build automation.

This is what separates teams that ship one thing and declare victory from teams that ship a suite of tools.

The formula: Write the code. Automate the build. Iterate without friction. That's how you build infrastructure instead of toys.

What's your experience shipping tools to non-technical users? Where does your build automation fail?

One report, rendered to HTML, PDF and Excel without a headless browser

Wed, 16 Sep 2026 07:04:07 +0000

The ticket says "let customers export their statement." You read it twice looking for the catch, because there doesn't seem to be one. Then the follow-ups arrive. It should look right on screen. It should print to a PDF with the column headers repeated on page two. And finance wants the same thing as a spreadsheet they can pivot, please, by Friday.

Nobody volunteers for this ticket twice.

The three code paths you end up with

The first instinct is to render HTML and print it. You already have the markup, Puppeteer will turn a page into a PDF, done by lunch. Then you containerise it.

The image. I ran npm install puppeteer on this machine today: 29 MB of packages, plus a 372 MB Chrome download into the cache before anything renders. That is not a rounding error in a deployment.
The race. Your PDF is a screenshot of a page load, so it inherits every timing problem a page load has. Fonts that weren't ready. An image still in flight. A layout that settled one tick after the capture.
The second stylesheet. Print CSS disagrees with screen CSS, and you now maintain both. Page numbers and running headers mean @page margin boxes and a hopeful attitude.

So you skip the browser and reach for a PDF library instead. Now the bytes are yours, which sounds like a win until you notice what came with them: pagination, keeping a group heading with its first row, repeating a table header across a page break, embedding and subsetting a font. Typesetting, in other words. By hand, per report.

And the spreadsheet is still a separate code path. Same columns, same totals, written twice. The two copies start drifting the week after they ship, usually in the direction of whichever one the customer looks at more.

There's a fourth trap for anyone doing this in the browser. Plenty of template engines build their expressions with new Function under the hood, which works fine right up to the security review that asks why script-src needs unsafe-eval.

A report is one problem, not four

Those four headaches have one thing in common: the report itself never changed. The bands, the grouping, the totals, the columns are identical in all of them. Only the output differs.

quario is my attempt to put the shared part in one place. You write the report once as a JSON document, compile it once, and then pick an output at the call:

import { quario } from "quario";
import { html } from "@quario/html";

const schema = {
  data: "$.orders[*]",
  detail: {
    columns: [
      { header: "Product", value: "{{ @.product }}" },
      { header: "Price", value: "{{ @.price }}" },
    ],
  },
};

const data = {
  orders: [
    { product: "Desk", price: 250 },
    { product: "Chair", price: 120 },
    { product: "Lamp", price: 40 },
  ],
};

const report = quario().report(schema);
const page = await report.render(html(), data);

page is a fragment you drop into your own shell:

<div class="q-report">
  <table class="q-table">
    <colgroup><col><col></colgroup>
    <thead><tr><th>Product</th><th>Price</th></tr></thead>
    <tbody>
      <tr><td>Desk</td><td>250</td></tr>
      <tr><td>Chair</td><td>120</td></tr>
      <tr><td>Lamp</td><td>40</td></tr>
    </tbody>
  </table>
</div>

One thing up front, because finding it out in paragraph nine is annoying: quario is commercial, source-available software. The evaluation build is free forever and does everything, it just stamps a watermark line on what it renders. More on the licence at the end.

Change the import, not the report

Keep that schema exactly as it is. Swap which target you hand to render:

import { pdf } from "@quario/pdf";
import { xlsx } from "@quario/xlsx";
import { csv } from "@quario/csv";

await report.render(pdf(), data);   // 1,411 bytes, a paginated document
await report.render(xlsx(), data);  // 6,711 bytes, a real workbook
await report.render(csv(), data);   // "Product,Price\nDesk,250\n..."

Those byte counts are from running it, not from a spec sheet. Render the PDF twice and you get the same bytes both times, which means your golden-file tests can compare the file instead of parsing it.

quario does the typesetting itself. Pagination, keep-together, repeating table headers, font embedding and subsetting, a document outline built from your group tree. @cantoo/pdf-lib writes the final bytes. npm install quario @quario/pdf puts 32 MB on disk and there is no browser in it.

The same layout pass also drives the on-screen preview in the <quario-viewer> element, so the preview breaks its pages exactly where the PDF does, instead of looking fine in the modal and wrong in the download.

Why the spreadsheet gets a real number

A cell's value isn't a string on its way through the engine. It's a token stream: literal runs, plus interpolations carrying the value before it gets stringified or escaped. So {{ @.price }} reaches the XLSX target as the number 250, and reaches the HTML target as escaped text.

Unzip that workbook and look at the sheet:

<c r="A3" s="2" t="s"><v>3</v></c>
<c r="B3" s="2"><v>250</v></c>

A3 is the product name, carrying t="s" for a shared string. B3 has no type attribute at all, which in OOXML means a number. Excel will sum that column. You wrote one column definition and both targets did the correct, different thing with it.

So if you want a typed cell, interpolate the bare value and let the target format it. {{ money(@.price) }} is a string everywhere, by your own request.

Two asymmetries you'll notice eventually, both deliberate:

CSV prefixes formula-shaped text with an apostrophe. A product literally named =SUM(A1) comes out as '=SUM(A1). A CSV field has no way to say "this is inert text," so the guard goes in the data.
XLSX doesn't. It writes that same value as a shared string, which is inert, so no guard is needed.

Different behaviour, same reason: use the format's own mechanism when it has one.

Reports are data, not code

Because the report is plain JSON, it's an ordinary value in your system. You can store it in a row, diff it in a pull request, send it between services, and hand it to a visual designer that's just another consumer of the same schema. <quario-editor> is exactly that: it edits the band structure and gives you back the document.

Reading any report definition takes three syntaxes:

Syntax	Means
`"{{ @.product }}"`	A template, a text cell's value. Interpolations are always escaped.
`"=@.price * @.qty"`	An expression. A leading `=` on any other property makes it dynamic.
`"sum:=@.price"`	A reducer spec, an aggregate: a reducer name plus an expression.

And four anchors those expressions can reach: @ is the current row, $ is the report root, a named group handle like region carries .key plus its own aggregates, and run.<name> holds running totals on a detail row.

That's the whole vocabulary. A grouped sales report with subtotals, a grand total and your own money() formatter is those same four ideas, just more of them.

Every target uses the same seam

report.stream(data) gives you the raw event stream, and it is ordered the way you'd read the report out loud: report-start, header items, then groups and detail rows (group-start, table-start, row, total-row, table-end, group-end), then footers, then report-end.

A target is { name, compile } and nothing else. The shipped ones get no privileged access to the engine, which is what makes an official target and one you wrote yourself indistinguishable to it.

The repo carries the proof as a tested example: a complete Markdown target in 55 lines of code.

export function markdown() {
  return {
    name: "markdown",
    compile: (stream) => async (data) => {
      let out = "";
      await walk(stream(data), {
        item: (e) => { out += inline(e) + "\n"; },
        "table-start": (e) => {
          out += cells(e.header.cells) + "\n";
          out += "| " + e.columns.map(() => "---").join(" | ") + " |\n";
        },
        row: (e) => { out += cells(e.cells) + "\n"; },
      });
      return out;
    },
  };
}

Run the grouped sales example through it and you get GFM pipe tables, subtotals and all. If your company's output is a fixed-width bank file or an ancient EDI format, that's the shape of the work.

Nothing here compiles to JavaScript

Expressions and templates parse to closures. Every operator and every interpolation is a small function that already exists in the shipped source, and the parser wires them together. There's no eval and no new Function anywhere in the stack, so script-src never needs unsafe-eval.

That's enforced three ways: the unit suites run under Node's --disallow-code-generation-from-strings, a per-package source scan fails the build if the strings even appear, and Playwright harnesses load the published files under a strict CSP in a real browser.

The three primitives underneath are separately published, and all three are open source: xprsn for expressions, sjabloon for templates, and padvinder for RFC 9535 JSONPath. I wrote those up separately, because each one turned out to be a post of its own.

One honest caveat. "CSP-safe" here means no string ever becomes code. It does not mean every directive is happy: conditional formatting emits inline style attributes, so a restrictive style-src has to allow them.

Escaping has one home, too. The stream is never markup-escaped, and the HTML target escapes every interpolated value plus every class, style and attribute value it emits. There's no {{{ raw }}} syntax to reach for, because it doesn't exist and asking for it is a definition error. The line quario draws: it trusts report definitions and registered functions, and it does not trust their data.

The total that wasn't a floating point bug

A receipt total came out of the workbook as 83.75999999999999.

I knew that number on sight, and I was wrong about it. The obvious suspect was drift accumulating inside sum:, so I went looking at the aggregate. Every aggregate was exact. Kahan summation would have fixed nothing at all.

The drift was in the cell, in the plain addition the author had written: 72 + 2.52 + 9.24. Try it in a REPL and you'll get the same thing. The actual defect wasn't arithmetic, it was that the person writing the report had no declarative way to say "two decimals, please."

So round, floor, ceil and abs went in as built-in scalar functions. Both of the one-liners everyone reaches for get a different case wrong:

Math.round(1.005 * 100) / 100;  // => 1     (want 1.01)
Number((2.675).toFixed(2));     // => 2.67  (want 2.68)

These functions round the decimal the author actually wrote, through Intl.NumberFormat's roundingMode, which is the one place in the platform that reasons about decimals instead of doubles.

What it deliberately isn't

The non-goals are in the spec on purpose, and they're the part I'd read first if I were you:

Not a query tool. data is a JSONPath into the object you pass in. There's no database connector and no SQL, so it renders whatever you hand it.
No charts, no barcodes. Deferred rather than declined. Both would compile down to the existing image item. Today you rasterize with your own tool and pass the bytes.
No hyperlinks. Declined, not deferred. Only one of five targets could honour it, and it is the only declaration whose failure mode is a security question, namely a javascript: URL in a slot an author fills.
Row groups only. No crosstabs, no matrix, no column groups. A second grouping axis isn't there.
No subreports, table of contents or drill-down. Those want runtime state or forward references that a pagination-agnostic core doesn't carry.
Not a WYSIWYG page designer. The editor edits band structure, not pixels. Bands stack, items stack, tables have columns, and there is no free positioning.

It's also 0.9.0 today. The plan is to freeze the authoring surface at 1.0, the document plus the semantics you can observe without knowing which target you're rendering to. That freeze isn't in effect yet, so a breaking authoring change right now is an ordinary, named, breaking change.

Getting started

npm install quario @quario/html

Swap @quario/html for @quario/pdf, @quario/xlsx, @quario/csv or @quario/docx, or install several. Each target declares the engine as a peer dependency, so your app carries one copy of it. Everything is ESM-only and wants Node 22 or newer, and there's no build step in any package: they publish plain JavaScript with hand-written type declarations.

The evaluation licence is free, needs no key and has no time limit, and it watermarks whatever it renders. A paid seat takes the watermark off. Whichever you end up on, the check runs offline through WebCrypto: it never phones home, never throws and never gates a feature. The pricing page has the terms.

The getting started guide builds an invoice from scratch, subtotals and all, and the scopes page is the one to read next.

Closing thoughts

Most of "make it a PDF" turned out to have nothing to do with PDFs. It was about writing the report down somewhere a second renderer could read it.

Once the definition was data instead of code, the spreadsheet stopped being a rewrite and became another reader of the same document. The Markdown target took an afternoon. What actually cost me weeks was deciding what a width or a size should mean when one target has a stylesheet, one has a fixed page, and one has no styling model at all. A target is allowed to approximate what you declared. It is not allowed to resolve it against something you never declared.

If you're maintaining two copies of the same report right now, one for the screen and one for the export, I'd like to hear how far apart they've drifted.

Magics PDF Converter

Thu, 03 Sep 2026 20:13:29 +0000

Experience the next generation of document management with Magics PDF PRO — the powerful, all-in-one desktop PDF Editor, 15-Format Universal Converter, AI OCR Scanner, and Military-Grade AES-256 Cyber Vault Security Suite.

Designed with a strict 100% Local-First architecture, Magics PDF PRO processes all your sensitive documents, financial reports, and confidential files directly on your computer. Your files never leave your PC and are never uploaded to third-party cloud servers.

═══════════════════════════════════════════
FREE TRIAL LIMITATIONS & PRO PRICING DISCLOSURE
═══════════════════════════════════════════
• Free Evaluation Tier: Free download includes unlimited PDF viewing and reading, plus 1 free trial attempt for each sensitive tool (1 free 15-format document conversion, 1 free Cyber Vault encryption, 1 free Cyber Vault decryption, 1 free AI OCR text extraction, 1 free smart redaction, and 1 free page manipulation).

═══════════════════════════════════════════
KEY CAPABILITIES & CORE FEATURES
═══════════════════════════════════════════

🛡️ CYBER VAULT — MILITARY-GRADE AES-256 ENCRYPTION & DECRYPTION
• Lock and secure confidential PDF documents with unbreakable AES-256-CBC encryption and PBKDF2 key derivation.
• Instant one-click decryption with authorized password access.
• Protect intellectual property, legal contracts, and personal data from unauthorized access, leaks, and ransomware.

🔄 UNIVERSAL 15-FORMAT DOCUMENT CONVERTER
• PDF to Word (DOCX / DOC) & Word to PDF
• PDF to Excel (XLSX / CSV) & Excel to PDF
• PDF to PowerPoint (PPTX) & PPTX to PDF
• PDF to High-Resolution Images (PNG, JPEG, BMP, TIFF, SVG, WebP)
• PDF to Structured Data (HTML5, XML, RTF, Plain Text)

🤖 LOCAL AI OPTICAL CHARACTER RECOGNITION (OCR)
• Extract editable text from scanned PDFs, receipts, book pages, and images.
• High-accuracy local neural OCR processing without internet connection.
• Export recognized text directly into editable formats.

✏️ FULL PDF EDITING & PAGE MANIPULATION
• Merge multiple PDF documents into a single organized file.
• Split multi-page PDFs into separate chapters or individual pages.
• Rotate, reorder, delete, and extract specific pages.
• Compress and optimize large PDF file sizes without losing visual quality.

🔒 SMART REDACTION & SECURITY PERMISSIONS
• Permanently redact and black out sensitive numbers, names, and credit card data.

⚡ ULTRA-FAST NATIVE 64-BIT PERFORMANCE
• Built with native 64-bit C++ architecture and Google PDFium rendering core.
• Smooth multi-tab viewing, continuous vertical scroll, and instant search.

Making a screenshot PDF searchable — no OCR, because we rendered the page

Thu, 20 Aug 2026 13:13:18 +0000

If you generate PDFs from web pages by screenshotting them, you've probably hit this: the PDF looks perfect and is completely useless the moment you want to use the text. Ctrl+F finds nothing. You can't copy a sentence. A screen reader opens the document and sees one big image on an otherwise empty page.

We archive whole pages this way — a full-height screenshot dropped onto a PDF page — so we had exactly this problem. Here's how we gave those PDFs a real, invisible, searchable text layer with pdf-lib and @pdf-lib/fontkit, and the one part that turned out to be genuinely hard.

The trick is the same one a "searchable scan" uses: draw the real text invisibly over the image, at the exact coordinates where each word appears. The difference is that a scanner needs OCR to guess the text — we rendered the page ourselves, so we already have the ground truth. No OCR, no guessing.

The shape of it

While the page is still open in the headless browser, ask the DOM where every word is.
Assemble the PDF: embed the screenshot as the page background.
For each word, drawText it at its coordinates with opacity: 0.

Steps 1 and 3 are easy. The trap is in which words you're allowed to draw.

Step 1 — ask the browser where the words are

Running inside the page (Puppeteer's page.evaluate), walk every text node and measure each word with a Range:

const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
// ...for each word in each text node:
const range = document.createRange();
range.setStart(node, start);
range.setEnd(node, end);
const rects = range.getClientRects();
if (!rects.length) continue;           // display:none or empty line box
const b = rects[0];                    // first rect = where the word starts
out.push({
  t: word,
  x: b.left + window.scrollX,          // document coordinates, not viewport
  y: b.top  + window.scrollY,
  w: b.width, h: b.height,
  fs: parseFloat(getComputedStyle(el).fontSize) || 12,
});

getClientRects() returns viewport coordinates, so we add scrollX/scrollY to get document coordinates — the ones that line up with a full-page screenshot. A word wrapped across two lines returns several rects; the first is where a search should land, so that's the one we keep.

Step 2 — the hidden-text trap (the hard part)

The naive version above shipped a bug immediately. On a real page, search started highlighting words that weren't in the picture — items inside a collapsed dropdown, off-canvas nav, text-indent: -9999px screen-reader text. The image showed them collapsed; the text layer had them anyway.

The tempting assumption is "hidden text has no client rects." It's false. Only display: none produces no rects. Every other way of hiding something still reports perfectly good coordinates:

visibility: hidden
opacity: 0
max-height: 0 + overflow: hidden (the collapsed accordion / submenu)
parked offscreen with text-indent: -9999px or a negative position

So each word has to be checked against its whole ancestor chain, not just its own box. Memoise one walk up the tree per element (a deep DOM would otherwise re-read computed styles thousands of times):

function chainInfo(el) {
  if (cache.has(el)) return cache.get(el);
  const above = el.parentElement ? chainInfo(el.parentElement)
                                 : { visible: true, opacity: 1, clips: [] };
  let info;
  if (!above.visible) {
    info = { visible: false, opacity: 0, clips: above.clips };
  } else {
    const cs      = getComputedStyle(el);
    const opacity = above.opacity * (parseFloat(cs.opacity) || 0);   // multiplied down the chain
    const visible = cs.visibility === 'visible' && opacity > 0.05;
    const clips   = /\b(hidden|clip)\b/.test(cs.overflow)
      ? above.clips.concat([el.getBoundingClientRect()])
      : above.clips;
    info = { visible, opacity, clips };
  }
  cache.set(el, info);
  return info;
}

A word survives only if its chain is visible, its multiplied opacity is above a floor, it intersects every clipping ancestor (a zero-height collapsed container clips its contents to nothing), and it isn't parked entirely outside the document box. Clipping is judged on zero intersection, not partial — a word half-cut by a container is still half in the picture, and dropping it would lose real text.

That single ancestor-walk is the difference between "searchable PDF" and "PDF that lies about what's in it."

Step 3 — flip the Y axis

The DOM measures from the top-left; PDF space is bottom-left. So when we draw, Y inverts, plus a small nudge so the selection highlight sits on the glyphs rather than below them:

const y = imageH - b.y - b.h + b.h * 0.2;

Step 4 — the font problem

pdf-lib's built-in fonts are WinAnsi. They can't encode Cyrillic, Greek or CJK — and they even choke on curly typographic quotes, of which there are four on our own English blog. Draw an unencodable glyph and the call throws.

So embed a real TrueType font, subset to only the glyphs actually used, via fontkit:

const fontkit = require('@pdf-lib/fontkit');
doc.registerFontkit(fontkit);
const font = await doc.embedFont(fs.readFileSync(fontPath), { subset: true });

subset: true is what keeps the cost near zero — only the handful of glyphs on the page get embedded, not the whole 300 KB face. We probe a small candidate list and take the first that exists on the box (DejaVu Sans on our Linux servers covers Latin + Cyrillic + Greek; Arial/Segoe locally). If none is found, we ship the image without a text layer rather than failing the capture — losing search is not losing the archive.

Step 5 — draw it invisibly, and don't let one glyph kill the archive

for (const b of boxes) {
  const y = imageH - b.y - b.h + b.h * 0.2;
  try {
    pdfPage.drawText(b.t, { x: b.x, y, size: b.fs, font, opacity: 0 });
    drawn++;
  } catch (e) {
    skipped++;   // a glyph even this font can't encode — skip the word, keep the PDF
  }
}

opacity: 0 is the whole point: the image is what you see, the text is what you search. And the per-word try/catch matters — a single exotic glyph should cost you one unsearchable word, not the entire multi-page document.

Did it actually work?

Measured on a Cyrillic page, before/after:

626 of 626 visible words got coordinates and a text entry
file grew 7086 KB → 7147 KB — +0.9%
/ToUnicode is present in the output, so the text is genuinely searchable and copyable, not just present

That +0.9% buys you Ctrl+F, copy-paste, and a document a screen reader can actually read — on what is still, pixel for pixel, an exact image of the page.

How to Convert Word to PDF in the Browser with Vue 3, mammoth, and html2pdf.js

Sat, 13 Jun 2026 13:24:06 +0000

Converting Word documents to PDFs on the server is the classic approach: upload the file, run LibreOffice or a cloud API, send the result back. But that means your users’ resumes, contracts, and reports touch your infrastructure.

I wanted something simpler for en.sotool.top: pick a .docx file in the browser, preview the parsed content, and download a PDF. No server involved.

Here is how I built it with Vue 3, mammoth, and html2pdf.js.

Why Client-Side?

The main reason is privacy. Resumes, contracts, tax documents — users do not want them on a stranger’s server. Client-side conversion also means:

No upload bandwidth limits
No file size caps from your server
No storage to clean up
Works offline after the page loads

The trade-off is that very complex documents are limited by the browser’s rendering capabilities. For typical office documents, that is fine.

The Stack

Vue 3 — UI, file handling, and reactive state
mammoth — Parse .docx files into clean HTML
html2pdf.js — Render the HTML into a PDF using html2canvas + jsPDF
Native File API — File selection

npm install mammoth html2pdf.js

Loading the Word Document

The first step is reading the uploaded .docx file into an ArrayBuffer, then converting it to HTML with mammoth.

import mammoth from 'mammoth';

async function convertDocxToHtml(file) {
  const arrayBuffer = await file.arrayBuffer();
  const result = await mammoth.convertToHtml({ arrayBuffer });
  return result.value;
}

mammoth intentionally produces simple, clean HTML. It ignores complex formatting like text boxes and embedded fonts, which makes the output predictable.

I keep the HTML in a reactive ref and render it in a preview panel:

<template>
  <div ref="previewRef" class="word-preview" v-html="htmlContent"></div>
</template>

<script setup>
import { ref } from 'vue';

const htmlContent = ref('');
const previewRef = ref(null);
</script>

Generating the PDF

Once the user is happy with the preview, html2pdf.js turns the preview element into a PDF. It uses html2canvas to rasterize the HTML and jsPDF to create the PDF file.

import html2pdf from 'html2pdf.js';

async function convertToPdf() {
  const element = previewRef.value;
  if (!element) return;

  await html2pdf()
    .from(element)
    .set({
      margin: [10, 10, 10, 10],
      filename: 'document.pdf',
      image: { type: 'jpeg', quality: 0.98 },
      html2canvas: { scale: 2, useCORS: true },
      jsPDF: { unit: 'mm', format: 'a4', orientation: 'portrait' },
    })
    .save();
}

The scale: 2 setting gives crisp text and images on high-DPI screens. useCORS: true helps if the preview contains external images.

Styling the Preview

html2pdf.js renders whatever is in the DOM, so the preview styles directly affect the output. I use scoped CSS with :deep() to style the converted HTML:

.word-preview :deep(h1) {
  font-size: 1.5rem;
  font-weight: 700;
  margin-bottom: 1rem;
}

.word-preview :deep(p) {
  margin-bottom: 0.75rem;
  line-height: 1.7;
}

.word-preview :deep(table) {
  width: 100%;
  border-collapse: collapse;
  margin-bottom: 1rem;
}

.word-preview :deep(td),
.word-preview :deep(th) {
  border: 1px solid #d1d5db;
  padding: 0.5rem;
}

Keep the preview background white. Dark mode UI is nice for the app, but a white page produces a clean PDF.

Handling Errors Gracefully

Not every file is a valid .docx. I wrap the conversion in a try/catch and reset the state on failure:

async function handleFile(file) {
  try {
    const arrayBuffer = await file.arrayBuffer();
    const result = await mammoth.convertToHtml({ arrayBuffer });
    htmlContent.value = result.value;
  } catch (e) {
    console.error(e);
    alert('Failed to parse the document. Please check the file format.');
  }
}

You can also surface mammoth warnings if you want to show the user which styles or elements were ignored.

Lessons Learned

1. Mammoth is opinionated by design
It strips complex Word features to produce clean HTML. If your users need pixel-perfect fidelity, a server-side converter is still a better fit.

2. Page size matters
If the document contains wide tables or landscape sections, A4 portrait may clip them. Consider letting users choose the output format.

3. html2canvas is heavy on large documents
Very long documents with many images can take several seconds and block the main thread. For heavy usage, consider chunking or using a Web Worker.

4. Keep the original file around
If users want to adjust settings and re-convert, you will need the original File object or ArrayBuffer because mammoth does not expose an editable model.

Try It

The Word to PDF tool is live at en.sotool.top/word-to-pdf.

Free, no signup, and nothing uploads to a server.

Full source code is on GitHub. The conversion logic lives in src/views/WordToPdf.vue.

Want More Advanced PDF Features?

If you need OCR, form editing, digital signatures, or batch processing beyond what a browser tool can do, Wondershare PDFelement is a solid desktop option. It keeps everything local and adds professional tools on top.

This post contains affiliate links.

Have you built client-side document converters? What did you use — mammoth, pdf-lib, or a server-side tool?

How to Split PDF Files in the Browser (No Server Required)

Fri, 12 Jun 2026 13:20:17 +0000

In the last post, I covered merging PDFs in the browser using pdf-lib. Today we're doing the opposite: splitting them.

Splitting is surprisingly common:

A 200-page report where you only need chapters 3 and 7
A scanned contract where the signature page needs to go to legal
A PDF that's too large to email, so you split it into two attachments
Extracting specific pages from a bulk download

Just like merging, we'll do this entirely in the browser — no server uploads, no privacy trade-offs.

Why Browser-Side Splitting Matters

The same privacy argument applies. When you upload a PDF to an online splitter, your file leaves your device. For documents containing personal data, financial records, or client contracts, that's a risk you don't need to take.

Browser-side splitting keeps everything local. The PDF loads into your browser tab, pdf-lib manipulates it in memory, and you download the result. The server never sees the content.

The trade-off: Browser memory. A 300MB scanned document will strain a tab. For typical office documents (under 50-100MB), splitting is instant.

Basic Split: Extract a Single Page Range

The simplest use case: "Give me pages 5 through 10."

import { PDFDocument } from 'pdf-lib';

async function extractPages(file, startPage, endPage) {
  // Load the source PDF
  const arrayBuffer = await file.arrayBuffer();
  const sourcePdf = await PDFDocument.load(arrayBuffer);

  // Create a new empty PDF
  const newPdf = await PDFDocument.create();

  // Convert to 0-based indices
  const pageIndices = [];
  for (let i = startPage - 1; i < endPage; i++) {
    pageIndices.push(i);
  }

  // Copy pages from source to new document
  const copiedPages = await newPdf.copyPages(sourcePdf, pageIndices);
  copiedPages.forEach(page => newPdf.addPage(page));

  // Save and return
  const pdfBytes = await newPdf.save();
  return new Blob([pdfBytes], { type: 'application/pdf' });
}

// Usage: extract pages 5-10
const blob = await extractPages(file, 5, 10);
downloadBlob(blob, 'pages-5-to-10.pdf');

What's happening:

Load the full source PDF into memory
Create a blank destination PDF
Copy only the requested pages using copyPages()
Save the new, smaller document

The source PDF isn't modified — we're creating a new document containing only the pages we want.

Split by Page Ranges: One Input, Multiple Outputs

Real-world scenario: a user uploads a 50-page document and wants three separate files — pages 1-10, 11-30, and 31-50.

async function splitByRanges(file, ranges) {
  // ranges = [{ name: 'intro', start: 1, end: 10 }, ...]
  const arrayBuffer = await file.arrayBuffer();
  const sourcePdf = await PDFDocument.load(arrayBuffer);

  const results = [];

  for (const range of ranges) {
    const newPdf = await PDFDocument.create();

    const pageIndices = [];
    for (let i = range.start - 1; i < range.end; i++) {
      pageIndices.push(i);
    }

    const copiedPages = await newPdf.copyPages(sourcePdf, pageIndices);
    copiedPages.forEach(page => newPdf.addPage(page));

    const pdfBytes = await newPdf.save();
    results.push({
      name: range.name,
      blob: new Blob([pdfBytes], { type: 'application/pdf' })
    });
  }

  return results;
}

// Usage
const ranges = [
  { name: 'chapter-1', start: 1, end: 10 },
  { name: 'chapter-2', start: 11, end: 30 },
  { name: 'chapter-3', start: 31, end: 50 }
];

const files = await splitByRanges(pdfFile, ranges);
files.forEach(f => downloadBlob(f.blob, `${f.name}.pdf`));

Memory note: We load the source PDF once, then create multiple new documents from it. Each new document only holds the pages it needs, so memory usage stays proportional to the output size, not the input size.

Advanced: Split by File Size (Email-Friendly Chunks)

Here's a trickier problem: "Split this PDF into chunks under 20MB each so I can email it."

Unlike page-range splitting, we don't know the page count in advance. We need to accumulate pages until adding one more would exceed the limit, then start a new chunk.

async function splitBySize(file, maxSizeBytes = 20 * 1024 * 1024) {
  const arrayBuffer = await file.arrayBuffer();
  const sourcePdf = await PDFDocument.load(arrayBuffer);
  const totalPages = sourcePdf.getPageCount();

  const chunks = [];
  let currentChunk = await PDFDocument.create();
  let currentSize = 0;
  let currentStartPage = 1;

  for (let i = 0; i < totalPages; i++) {
    // Try adding this page to the current chunk
    const testChunk = await PDFDocument.create();

    // Copy all pages currently in the chunk plus the new one
    const pagesToCopy = [];
    for (let j = currentStartPage - 1; j <= i; j++) {
      pagesToCopy.push(j);
    }

    const copiedPages = await testChunk.copyPages(sourcePdf, pagesToCopy);
    copiedPages.forEach(page => testChunk.addPage(page));

    const testBytes = await testChunk.save();

    if (testBytes.length > maxSizeBytes && currentStartPage <= i) {
      // This page would push us over the limit. Finalize current chunk.
      const finalChunk = await PDFDocument.create();
      const finalPages = [];
      for (let j = currentStartPage - 1; j < i; j++) {
        finalPages.push(j);
      }
      const finalCopied = await finalChunk.copyPages(sourcePdf, finalPages);
      finalCopied.forEach(page => finalChunk.addPage(page));

      const finalBytes = await finalChunk.save();
      chunks.push(new Blob([finalBytes], { type: 'application/pdf' }));

      // Start new chunk with current page
      currentStartPage = i + 1;
    }
  }

  // Don't forget the last chunk
  if (currentStartPage <= totalPages) {
    const finalChunk = await PDFDocument.create();
    const finalPages = [];
    for (let j = currentStartPage - 1; j < totalPages; j++) {
      finalPages.push(j);
    }
    const finalCopied = await finalChunk.copyPages(sourcePdf, finalPages);
    finalCopied.forEach(page => finalChunk.addPage(page));

    const finalBytes = await finalChunk.save();
    chunks.push(new Blob([finalBytes], { type: 'application/pdf' }));
  }

  return chunks;
}

Why this is expensive: We save a test document on every page to check the size. For a 100-page document, that's 100 save operations. In practice, I optimize this by:

Estimating page size from the first few pages
Using binary search instead of linear checking
Adding a small buffer (aim for 18MB instead of exactly 20MB)

For production, a simpler heuristic works well: if the original is 45MB and 50 pages, each page is roughly 0.9MB. Split every 22 pages to stay safely under 20MB.

Extracting Every Nth Page

Another common pattern: "I only need the odd pages" or "Extract every 5th page for a summary."

async function extractEveryNthPage(file, n, offset = 0) {
  const arrayBuffer = await file.arrayBuffer();
  const sourcePdf = await PDFDocument.load(arrayBuffer);
  const totalPages = sourcePdf.getPageCount();

  const newPdf = await PDFDocument.create();
  const pageIndices = [];

  for (let i = offset; i < totalPages; i += n) {
    pageIndices.push(i);
  }

  const copiedPages = await newPdf.copyPages(sourcePdf, pageIndices);
  copiedPages.forEach(page => newPdf.addPage(page));

  const pdfBytes = await newPdf.save();
  return new Blob([pdfBytes], { type: 'application/pdf' });
}

// Extract odd pages only
const oddPages = await extractEveryNthPage(file, 2, 0);

// Extract even pages only
const evenPages = await extractEveryNthPage(file, 2, 1);

Handling Page Rotation and Metadata

When you split a PDF, you might want to preserve or modify metadata:

async function splitWithMetadata(file, startPage, endPage) {
  const arrayBuffer = await file.arrayBuffer();
  const sourcePdf = await PDFDocument.load(arrayBuffer);
  const newPdf = await PDFDocument.create();

  // Copy pages
  const pageIndices = [];
  for (let i = startPage - 1; i < endPage; i++) {
    pageIndices.push(i);
  }
  const copiedPages = await newPdf.copyPages(sourcePdf, pageIndices);
  copiedPages.forEach(page => newPdf.addPage(page));

  // Preserve or update metadata
  const author = sourcePdf.getAuthor();
  const creator = sourcePdf.getCreator();

  newPdf.setTitle(`Extracted Pages ${startPage}-${endPage}`);
  newPdf.setAuthor(author || 'Unknown');
  newPdf.setCreator('sotool PDF Splitter');
  newPdf.setProducer('pdf-lib');
  newPdf.setCreationDate(new Date());

  const pdfBytes = await newPdf.save();
  return new Blob([pdfBytes], { type: 'application/pdf' });
}

This is useful when the recipient needs to know where the extract came from.

Performance: The 200-Page Test

I tested the page-range splitter on a 200-page, 85MB scanned document:

Operation	Time	Memory Peak
Load PDF	2.1s	180MB
Extract pages 50-100	1.8s	95MB
Split into 4 chunks	4.2s	210MB
Extract every 10th page	0.9s	45MB

The key insight: copyPages() is fast because it copies page references and shared resources efficiently. You're not deep-cloning the entire document for each output.

Optimization tip: If you're splitting a PDF into many small chunks, load the source once and reuse the PDFDocument instance. Don't reload it for each chunk.

Limitations (Honest Assessment)

Limitation	Why	Workaround
Bookmarks lost	Splitting creates new document trees	Acceptable for most extracts
Internal links break	Page references change	Rarely an issue for extracts
Large scans choke	Browser memory limits	Split server-side for 500MB+ files
Form data complexity	Some forms have cross-page dependencies	Test thoroughly with fillable PDFs

For 95% of use cases — extracting a chapter, splitting a contract, creating email-friendly chunks — these limitations don't matter.

Try the Live Tool

If you want to test browser-based PDF splitting without writing code:

en.sotool.top/split

Features:

Extract specific page ranges
Split by fixed page count (every N pages)
Split by file size (email-friendly chunks)
Visual page thumbnails for selection
Pure browser-side processing
Free, no signup

The source code is open source if you want to see how the Vue 3 + pdf-lib integration works.

What's Next?

If you enjoyed this post, check out the companion piece on merging PDFs in the browser.

Next up in the series:

Compressing PDFs by downsampling embedded images
Adding watermarks with text and image overlays
Encrypting and password-protecting PDFs client-side

Have you built browser-based document tools? What's your approach to handling large files or complex page operations? Let me know in the comments.

Binary PDF Modification Detection: How It Works and Where It Fails

Wed, 27 May 2026 08:26:25 +0000

The question sounds simple: has this PDF been edited after it was originally created? The answer, it turns out, requires understanding how PDF files store their history at the byte level.

This article explains the technical approach behind binary PDF modification detection — what signals we look for, why they are reliable, and critically, where the method breaks down. If you want a quick answer without the technical detail, HTPBE.tech is an online tool that tells you whether a PDF has been edited (yes/no) in seconds. If you want to understand how that answer is produced, read on.

How a PDF File Is Structured

Before discussing detection, you need to understand the PDF file format at a structural level.

A PDF file consists of four components:

Header — declares the PDF version (%PDF-1.7)
Body — a collection of numbered objects (pages, fonts, images, metadata)
Cross-reference table (xref) — an index mapping object numbers to byte offsets
Trailer — points to the xref table and the document root object

A minimal trailer looks like this:

trailer
<<
  /Size 42
  /Root 1 0 R
  /Info 2 0 R
>>
startxref
9876
%%EOF

The /Info entry points to the document information dictionary — this is where metadata lives.

The Metadata Dictionary

The PDF Information Dictionary (/Info) contains fields that describe the document’s origin and history:

Field	Meaning
`/CreationDate`	When the document was originally created
`/ModDate`	When the document was last modified
`/Creator`	Application that created the source document (e.g., Microsoft Word)
`/Producer`	PDF library or printer that generated the PDF (e.g., macOS Quartz PDFContext)
`/Author`	Document author
`/Title`	Document title

Dates are encoded in a specific format:

D:20231015143022+03'00'

This means: 2023-10-15 at 14:30:22, UTC+3. The timezone offset is significant — we will come back to it.

The Creator/Producer distinction matters enormously. When someone writes a document in Microsoft Word and exports it to PDF:

Creator = Microsoft Word
Producer = Microsoft Word (or a Word-internal PDF engine)

When someone then opens that PDF in Adobe Acrobat and edits it:

Creator stays as Microsoft Word (preserved from original)
Producer changes to Adobe Acrobat 23.0 (the tool that wrote the new version)

This mismatch is a strong signal of modification.

The Incremental Save Mechanism

This is the core of PDF modification detection, and it is what makes PDFs fundamentally different from most other file formats.

When you edit a PDF and save it, most PDF editors do not rewrite the entire file. Instead, they append changes to the end:

The original file body is left intact
New or modified objects are appended after %%EOF
A new cross-reference table is appended, containing entries for the changed objects
A new trailer is appended with a /Prev field pointing to the byte offset of the previous xref table

[original body]
%%EOF
[new objects]
xref
[new xref entries]
trailer
<<
  /Size 55
  /Root 1 0 R
  /Prev 9876          ← points to original xref
>>
startxref
14523
%%EOF

This incremental update mechanism exists for good reasons: it enables fast partial saves, supports undo history, and is required for certain digital signature workflows. But it also leaves a clear paper trail.

A PDF with multiple %%EOF markers, multiple xref sections, or a trailer with /Prev has been saved more than once. This does not automatically mean fraud — legitimate workflows involve multiple saves. But it is a definitive indicator that the file was modified after initial creation.

What Automated Detection Actually Examines

A detection tool like HTPBE examines several independent signals and combines them into a confidence score.

1. Timestamp Consistency

The simplest check: is ModDate later than CreationDate? If yes, the file was modified. But there are subtleties:

ModDate == CreationDate does not mean the file was never edited. Some editors reset ModDate to match CreationDate to hide modifications.
ModDate earlier than CreationDate is impossible under normal conditions and indicates tampering with metadata.
Timezone changes between CreationDate and ModDate (e.g., creation in +03'00' but modification in Z) suggest the file was modified on a different machine or with a different tool.

2. Cross-Reference Table Analysis

Counting xref sections reveals the number of save operations:

1 xref section: the file was saved exactly once — typical for freshly exported PDFs
2+ xref sections: the file was modified at least once after initial creation
3+ xref sections: multiple rounds of editing

The content of the xref updates also matters. If the updated objects include the /Info dictionary (metadata), it suggests metadata was modified after the fact.

3. Creator/Producer Mismatch Analysis

We maintain a knowledge base of known PDF creation tool combinations. Some mismatches are routine:

Creator: Word + Producer: Adobe PDF Printer — normal, Word printed to PDF
Creator: Google Docs + Producer: Skia/PDF — normal Google Docs export

Some mismatches are suspicious:

Creator: Microsoft Excel + Producer: iLovePDF — the file was processed by an online editor
Creator: LibreOffice + Producer: Adobe Acrobat — the file was opened and re-saved in Acrobat
Creator: (empty) + Producer: FPDF — programmatically generated, may be a reconstructed document

The tool also looks for editors known to be used for document fraud: certain online PDF editors, specific versions of commercial tools with known history-stripping features.

4. Digital Signature Integrity

PDF supports cryptographic digital signatures (/Sig objects). When a signed PDF is modified:

The signature covers specific byte ranges of the file
If content outside those byte ranges is modified, the signature becomes invalid
If the signature object itself is removed and the document re-saved, the absence of a previously-present signature is detectable via the revision history

5. Object Stream Anomalies

PDF 1.5+ supports compressed object streams. Legitimate PDF generators produce consistent, well-formed object streams. Anomalies we check for:

Objects with inconsistent generation numbers
Orphaned objects not reachable from the document root
Objects that exist in the xref table but whose byte offsets point to different object types (indicates partial overwrite attempts)

Putting It Together: The Confidence Score

No single signal is conclusive. A document with ModDate > CreationDate might be completely legitimate. A document with matching timestamps might have been forged with a tool that resets them.

Detection tools combine multiple signals into a weighted confidence score:

Signal	Weight	Rationale
Multiple xref sections	High	Hard to fake without specialized knowledge
Creator/Producer mismatch with known editor	Medium-High	Common in legitimate workflows too
Timestamp anomaly (impossible date)	High	Never legitimate
Timestamp anomaly (reset to match)	Medium	Detectable but requires suspicion
Known fraud-associated producer	Medium	Context-dependent
Digital signature removed	High	Strong indicator of post-signing modification

A score above a threshold produces a “Modified” verdict. Below the threshold: “Original”. The threshold is calibrated to minimize false positives on legitimate documents.

False Positives: When Unmodified PDFs Look Modified

This is where the method has real limitations.

Legitimate workflows that trigger modification signals:

PDF/A conversion — archival format conversion modifies the file structure. ModDate will differ from CreationDate even if content is unchanged.
Digital signing — adding a digital signature is a modification. A signed-after-creation document will show multiple xref sections even if the content was never altered.
Optimization — tools like Ghostscript, qpdf, or Adobe Acrobat’s “Reduce File Size” rewrite the entire file, resetting the xref structure but potentially preserving old timestamps.
Printer workflows — some enterprise print systems re-process PDFs (adding watermarks, headers, or compliance stamps) as a routine step.
Email clients — some email clients modify PDF attachments (adding metadata, stripping features) during send or receive.
Merging or splitting — combining PDFs with tools like PDFtk or iLovePDF creates a new document with a new Producer and potentially inconsistent metadata from the source files.

In all these cases, the document content may be perfectly authentic, but the structural signals indicate modification. This is why results should always be interpreted in context.

False Negatives: When Modified PDFs Look Original

More dangerous is the opposite case: a forged document that passes detection.

Techniques that evade detection:

Full reconstruction — printing to PDF (or using print → save as PDF) creates a completely new file with a fresh xref, consistent timestamps, and a single clean structure. All modification traces are lost. The resulting PDF looks freshly created, even if it was forged.
Metadata scrubbing — tools like exiftool or custom scripts can overwrite all metadata fields, including timestamps and creator information, before the file is distributed. A sophisticated forger resets CreationDate = ModDate and sets Producer to match the expected original tool.
Re-export from source format — if the forger has access to the source document (a Word file, for example), they can modify the source and re-export to PDF. The resulting PDF has no modification traces because it was never “modified” — it was created fresh from a modified source.
PDF reconstruction tools — specialized tools can parse a modified PDF and reconstruct it as a clean single-revision file, stripping all incremental save history.

The fundamental limitation: binary detection works on file structure, not content. We can detect that a file’s structure shows signs of modification, but we cannot verify whether the visible text or numbers are correct. A forger skilled enough to reconstruct the PDF properly can evade structural detection entirely.

What This Means in Practice

Binary PDF modification detection is a fast, automated first-line check. It catches:

Naive modifications made with standard PDF editors (the vast majority of document fraud cases)
Metadata inconsistencies that reveal post-creation editing
Structural anomalies that indicate multiple save operations

It does not catch:

Sophisticated forgeries where the PDF was fully reconstructed
Source-level modifications (edit the Word doc, re-export)
Cases where the file was “legitimately” processed by a PDF workflow tool

For high-stakes verification (legal documents, financial instruments, regulated industries), automated detection should be combined with:

Human review of the document content for semantic consistency
Verification of the document’s origin through the issuing party
Cryptographic verification if the original was digitally signed
Chain-of-custody controls that prevent the question from arising

Technical Implementation Notes

For developers building similar tools, the key libraries:

pdf-lib (JavaScript/Node.js) — parse PDF structure, read xref tables, access object streams
PyMuPDF / fitz (Python) — comprehensive PDF analysis, supports most PDF versions
pdfminer.six (Python) — lower-level access to PDF internals
iTextSharp (.NET) — commercial-grade PDF analysis

The core algorithm:

Parse the xref table(s) — count revisions
Extract /Info dictionary — compare timestamps, analyze Creator/Producer
Walk the xref chain via /Prev pointers — identify which objects changed between revisions
Check for /Sig objects — verify digital signature presence and coverage
Score each signal — weight by reliability and combine

The implementation challenge is handling malformed PDFs. Real-world documents frequently deviate from the PDF specification. A robust tool must handle:

Missing or corrupted xref tables (PDF readers use recovery mode)
Linearized PDFs (a different structure used for web-optimized files)
Encrypted PDFs (metadata may be accessible even if content is not)
PDF 2.0 documents with new structural features

Conclusion

Binary PDF modification detection is a reliable heuristic, not a cryptographic proof. It answers the question “does this file’s structure suggest modification?” with high accuracy for everyday document fraud. Against a skilled adversary who understands PDF internals, structural detection alone is insufficient.

The honest answer to “has this PDF been edited?” is: we can tell you what the file’s structure reveals. For most fraud cases — edited invoices, tampered bank statements, modified contracts — that is enough.

HTPBE.tech implements the detection approach described in this article. The web tool is free, requires no registration, and processes PDFs in seconds. The API is available for integration into document verification workflows.

[ROADMAP] Beyond the CSV: Statements as a Product Surface

Wed, 06 May 2026 11:33:00 +0000

Beyond the CSV: Statements as a Product Surface

Part 10 looks past today’s CSV importers at broker statements (often PDF). The architecture below is directional: we are spelling out constraints and a credible pipeline, not announcing a finished PDF-to-portfolio feature in production.

What you can use today

Broker adapters and universal CSV — importer package and in-app CSV flow. Heavy parsing stays in the browser; where cloud-assisted mapping exists, only bounded previews go upstream (for example headers plus a small sample of rows).
Ask AI context — always the buildPortfolioContext string (Parts 2–3), no matter how trades entered the app.

Why PDF is harder than CSV

Layout — multi-column tables, repeated headers, page breaks.
Noise — footnotes, disclaimers, mixed fonts.
Scans — OCR errors break deterministic parsers.
Trust — people should confirm extracted rows before anything merges into a ledger—the same bar we set on universal CSV mapping.

Target pipeline (when we ship it)

Extract — client-side or trusted worker → row-like text or tables.
Map — the same schema discipline as CSV (still bounded if the cloud helps).
Parse deterministically — Trade[] in the same spirit as today’s genericParse.
Review — explicit user confirmation before merge.

Scope. This installment is engineering intent and product reasoning. End-to-end PDF statement import is not described here as something you can do in the live app today; when we ship it, we will say so in release notes and product copy, not only in a serial essay.

Part 10 of Sovereign Engineering.

Read the full Sovereign Intelligence book or try the app.

The document could not be saved. A number is out of range- Fixed

Mon, 23 Mar 2026 09:43:47 +0000

The 'The document could not be saved. A number is out of range` error happens when Acrobat detects an issue with the PDF file's underlying structure. The solution for this problem is exporting a PDF to PostScript, and then convert the PostScript file back to PDF. Other solutions are also discussed in this article.

Photo by Rachel Vine

What is "The document could not be saved. A number is out of range"?
Why "The document could not be saved. A number is out of range " happens?
How to resolve "The document could not be saved. A number is out of range":
1. Solution 1: Export the PDF as a PostScript
2. Solution 2: Rename and open PDF
Conclusion

What is “The document could not be saved. A number is out of range”?

We may wonder why Adobe allows this BUG to exist when everyone does not have Acrobat. The problem here arises due to a faulty PDF. The structure of a PDF file is complicated so such issues can arise.

Why does “The document could not be saved. A number is out of range“ happens?

When the user tries to view a PDF or delete a page from a PDF, then you see an error message;

Following is the error message you get:

`A number is out of range`

A user can also get the same error when you try to perform other actions on the PDF, such as combining it with another PDF or inserting a new page.

How to resolve “The document could not be saved. A number is out of range”?

Please take the following actions outlined below to remedy the issue.

Solution 1:

Export the PDF as a PostScript file and then convert it into a PDF using Distiller. The “A number is out of range” error occurs when Acrobat finds some problem with the underlying structure of the PDF file. The best solution is to get a new PDF from the owner. If you can’t get one, then follow the below steps to resolve the problem.

Steps to follow:

Open the PDF in Acrobat.
Select File > Export To > PostScript from the File menu.
Enter a new name for the file in the Save As PDF dialogue box, then click Save.
Go to the folder where the PostScript file was saved. Right-click the file and select Adobe Acrobat Distiller from the context menu.
The PostScript file is converted to a PDF file by Acrobat Distiller. In the same folder, the PDF file is saved.
Acrobat should be used to open the PDF file. Now try seeing the pages in the PDF or deleting, inserting, or adding a page.

⚠️ This method works effectively for PDFs that do not contain interactive features like multimedia or form fields.

Solution 2: Rename and open PDF

1. Rename the original file's name
2. Go to Chrome Browser and open this file
3. Print> Save as .pdf
4. Open in Adobe

ℹ If you're a Mac user, you can avoid the problem by using Preview or avoiding Acrobat.

Conclusion:

The document could not be saved. A number is out of range is the issue we might face due to corrupted PDF files, in this article we discussed a number of resolutions such as renaming pdf files and exporting pdf files et. I hope this article will be useful, happy exploring !!

Auto-Generate PDF Receipts After Stripe Payments

Thu, 19 Mar 2026 08:27:15 +0000

Every app that takes payments needs to send receipts. Stripe has built-in receipts, but they're Stripe-branded and limited. If you need custom receipts — with your company info, tax breakdowns, payment details — you have to generate them yourself.

The typical approach is setting up Puppeteer, writing an HTML template, managing CSS, and rendering PDFs on your server. It works, but it's heavy and annoying to maintain.

Here's a simpler approach: listen for Stripe's payment_intent.succeeded webhook, call a receipt API, and email the PDF to your customer. No HTML templates. No Puppeteer. Under 50 lines of code.

The Setup

We need three things:

A Stripe webhook listener
A receipt PDF generator (we'll use Kagyz)
An email sender (SendGrid, Resend, or any SMTP)

Step 1: Listen for Stripe Payments

import Stripe from "stripe";
import express from "express";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

app.post(
  "/webhook/stripe",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const sig = req.headers["stripe-signature"];

    let event;
    try {
      event = stripe.webhooks.constructEvent(
        req.body,
        sig,
        process.env.STRIPE_WEBHOOK_SECRET
      );
    } catch (err) {
      return res.status(400).send(`Webhook Error: ${err.message}`);
    }

    if (event.type === "payment_intent.succeeded") {
      await handlePayment(event.data.object);
    }

    res.json({ received: true });
  }
);

app.listen(3000);

Standard Stripe webhook setup. Nothing special here — we verify the signature and handle payment_intent.succeeded.

Step 2: Generate the Receipt PDF

This is where it gets simple. Instead of rendering HTML with Puppeteer, we send JSON to Kagyz and get a PDF back:

async function generateReceipt(paymentData) {
  const response = await fetch("https://api.kagyz.com/v1/receipt", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.KAGYZ_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      receipt_number: `REC-${paymentData.id.slice(-8)}`,
      date: new Date().toISOString().split("T")[0],
      currency: paymentData.currency.toUpperCase(),
      payment_method: paymentData.payment_method_types[0],
      transaction_id: paymentData.id,
      from: {
        name: "Your Company Name",
        email: "billing@yourcompany.com",
        address: "123 Business St\nNew York, NY 10001",
      },
      to: {
        name: paymentData.metadata.customer_name || "Customer",
        email: paymentData.receipt_email,
      },
      items: [
        {
          description: paymentData.description || "Payment",
          quantity: 1,
          unit_price: paymentData.amount / 100,
        },
      ],
      notes: "Thank you for your purchase!",
    }),
  });

  return await response.arrayBuffer();
}

That's it. No HTML template. No CSS. No Puppeteer running on your server. The API returns a professionally formatted PDF with a PAID badge, payment method, transaction ID, and all the details your customer needs.

Step 3: Email it to the Customer

import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY);

async function emailReceipt(email, pdfBuffer, receiptNumber) {
  await resend.emails.send({
    from: "billing@yourcompany.com",
    to: email,
    subject: `Receipt ${receiptNumber} — Thank you for your payment`,
    html: `<p>Hi,</p><p>Thanks for your payment. Your receipt is attached.</p><p>— Your Company</p>`,
    attachments: [
      {
        filename: `receipt-${receiptNumber}.pdf`,
        content: Buffer.from(pdfBuffer).toString("base64"),
      },
    ],
  });
}

Putting It All Together

async function handlePayment(paymentIntent) {
  // Skip if no email
  if (!paymentIntent.receipt_email) return;

  const receiptNumber = `REC-${paymentIntent.id.slice(-8)}`;

  // Generate PDF
  const pdfBuffer = await generateReceipt(paymentIntent);

  // Email to customer
  await emailReceipt(
    paymentIntent.receipt_email,
    pdfBuffer,
    receiptNumber
  );

  console.log(`Receipt ${receiptNumber} sent to ${paymentIntent.receipt_email}`);
}

When a Stripe payment succeeds:

Webhook fires
We build receipt data from the payment intent
Kagyz generates the PDF
We email it to the customer

The whole flow runs in under a second.

Adding Tax Support

If you need tax on receipts (VAT, GST, sales tax), add a tax field:

// Invoice-level tax — applies to all items
tax: { rate: 20 }  // 20% VAT

// Or item-level tax — different rates per item
items: [
  {
    description: "Software License",
    quantity: 1,
    unit_price: 99,
    tax: { rate: 20 }  // 20% on this item
  },
  {
    description: "Support Plan",
    quantity: 1,
    unit_price: 29,
    tax: { rate: 0 }   // Tax-exempt
  }
]

Item-level tax overrides invoice-level tax for that item — useful for EU VAT where digital services and physical goods have different rates.

Why Not Just Use Stripe's Built-in Receipts?

Stripe's receipts work, but they have limitations:

Stripe branding — the receipt says Stripe, not your company
Limited customization — you can't add custom fields, detailed tax breakdowns, or your own notes
No PDF file — Stripe sends an email with a link, not a downloadable PDF attachment
Inconsistent with your other documents — if you also generate invoices and quotes, they'll look different from Stripe's receipts

With Kagyz, your receipts match your invoices. Same design, same layout, same professional look — just different content.

Testing Locally

Use the Stripe CLI to forward webhooks to your local server:

# Install Stripe CLI, then:
stripe listen --forward-to localhost:3000/webhook/stripe

# In another terminal, trigger a test payment:
stripe trigger payment_intent.succeeded

The Full Picture

Once this is running, you have automated receipts with zero manual work. But the same pattern works for other documents too:

payment_intent.succeeded → generate receipt via POST /v1/receipt
Subscription created → generate invoice via POST /v1/invoice
Deal closed in your CRM → generate quote via POST /v1/quote
Refund issued → generate credit note via POST /v1/credit-note

Same API, same design language, four document types. Full docs here.

Kagyz is a JSON-to-PDF API for business documents. Free tier: 100 PDFs/month, no credit card needed.

→ kagyz.com
→ API docs
→ Receipt endpoint docs

We Added a Dashboard and Custom Branding to Our JSON-to-PDF API

Thu, 19 Mar 2026 08:27:01 +0000

Two weeks ago Kagyz was a simple API: send JSON, get a PDF. That's still the core, but we just shipped two features that make it feel like a real product.

Dashboard

Every API product needs a dashboard eventually. Ours lives at app.kagyz.com and covers the basics:

API key management — create, delete, copy keys. Keys are shown once on creation and never again.
Usage stats — see how many PDFs you've generated this month, broken down by day.
Billing — see your current plan, upgrade, or manage your subscription.

Custom Branding

This one was requested from day one. You can now:

Upload your company logo — it appears in the top corner of every document.
Set an accent color — applied to document titles, table headers, and dividers.

Upload once in the dashboard. Every PDF you generate after that carries your branding. You can also override the accent color per-request if you need different colors for different clients:

{
  "invoice_number": "INV-001",
  "branding": {
    "accent_color": "#ff6600"
  },
  "from": { "name": "Acme Corp" },
  "to": { "name": "Client Inc." },
  "items": [
    { "description": "Consulting", "quantity": 10, "unit_price": 150 }
  ]
}

What Kagyz Does

If you haven't seen it before — Kagyz is a JSON-to-PDF API for business documents. Send structured JSON, get a clean PDF back. No HTML templates, no CSS debugging, no Puppeteer.

Currently supports 5 document types:

Invoice
Receipt
Quote / Estimate
Credit Note
Packing Slip

Plus Arabic/RTL support, multi-currency, and item-level tax rates.

What's Next

We're working on email delivery (generate + send in one API call) and PDF storage (get a hosted URL instead of binary). After that, a proper comparison article against the alternatives.

Free tier is 100 PDFs/month with all features included. No feature gating between plans — you just pay for volume.

Try it: kagyz.com
Dashboard: app.kagyz.com
Docs: kagyz.com/docs
GitHub: github.com/kagyz

Kagyz vs PDFShift vs CraftMyPDF — Which PDF API Should You Use?

Thu, 19 Mar 2026 08:26:35 +0000

I spent a lot of time evaluating PDF generation APIs before building my own. Here's an honest comparison of three tools — what they're good at, where they fall short, and who each one is for.

The Short Version

	Kagyz	PDFShift	CraftMyPDF
Approach	Send JSON, get a PDF	Send HTML, get a PDF	Design template in editor, fill with JSON
Templates	Built-in (no design needed)	You build HTML/CSS yourself	Drag-and-drop visual editor
Best for	Invoices, receipts, quotes, business docs	Any HTML-to-PDF conversion	Custom-designed documents, reports
Free tier	100 PDFs/month	50 credits/month	50 PDFs/month, 3 templates
Paid from	$19/month	$9/month	$29/month
Arabic/RTL	Built-in	Not supported	Supported
Custom branding	Logo + accent color (all plans)	N/A (you control the HTML)	Full template control
Dashboard	Yes (API keys, usage, billing)	Yes	Yes
Setup time	5 minutes	15-30 minutes	30-60 minutes

Kagyz — JSON In, PDF Out

Website: kagyz.com

Kagyz takes a different approach. Instead of converting HTML to PDF, you send structured JSON and get back a formatted business document. No templates to build, no CSS to debug.

It currently supports five document types: invoices, receipts, quotes/estimates, credit notes, and packing slips. All five share a clean, consistent design.

What I like:

Zero setup. Send JSON, get a PDF. No HTML, no CSS, no template design.
Arabic/RTL support is built in — add direction: "rtl" to any request and it works. 12+ Arabic currencies supported.
Custom branding — upload your logo and pick an accent color. Every document comes out branded.
All features available on every plan, including free. You only pay for volume.
Dashboard for managing API keys, tracking usage, and handling billing.

What it doesn't do:

Only business documents. You can't generate arbitrary PDFs from HTML.
Five document types currently — no reports, certificates, or contracts.
Template design is fixed. You can add a logo and change the accent color, but you can't rearrange the layout.
Newer product with a smaller community.

Best for: Developers who need invoice/receipt/quote PDFs and don't want to deal with HTML templates. Especially strong for Arabic/MENA markets.

Example request:

POST https://api.kagyz.com/v1/invoice
{
  "invoice_number": "INV-001",
  "currency": "USD",
  "branding": { "accent_color": "#22c55e" },
  "from": { "name": "Acme Corp" },
  "to": { "name": "Client Inc." },
  "items": [
    { "description": "Consulting", "quantity": 10, "unit_price": 150 }
  ],
  "tax": { "rate": 8.25 }
}

That's it. No HTML. No CSS. You get a branded invoice PDF back.

PDFShift — HTML to PDF Conversion

Website: pdfshift.io

PDFShift is the most straightforward HTML-to-PDF converter. Give it a URL or raw HTML, and it returns a PDF. It uses headless Chromium under the hood, so the output matches what you'd see in a browser.

What I like:

Dead simple API. One endpoint, one job.
Supports modern CSS — flexbox, grid, web fonts, Tailwind, Bootstrap.
Parallel conversions for batch processing.
Webhook support for async generation.
HIPAA compliant — doesn't store documents by default.
Good documentation with examples in multiple languages.

What it doesn't do:

You have to build and maintain your own HTML templates. That's the whole point — but it's also the main work.
No visual template editor. Everything is code.
No built-in document types. You're starting from scratch.
No Arabic/RTL support out of the box.
Pricing is credit-based (1 credit per 5MB of output), which can be unpredictable.

Best for: Teams that already have HTML templates and just need a reliable rendering engine. Great for converting existing web pages to PDF.

CraftMyPDF — Visual Template Editor + API

Website: craftmypdf.com

CraftMyPDF is the most feature-rich option. It offers a drag-and-drop template editor where you design your PDF layout visually, then fill it with data via API or no-code tools like Zapier and Make.

What I like:

Visual drag-and-drop editor is genuinely good. Non-developers can design templates.
Huge component library: text, images, QR codes, barcodes, charts, tables.
Import existing PDFs as templates — overlay dynamic data on top.
Fillable PDF forms (text fields, checkboxes, dropdowns).
Regional API endpoints (US, EU, Singapore, Australia).
Integrations with Zapier, Make, Bubble, Coda.
Multi-language support including Arabic.

What it doesn't do:

More complex to set up. You need to design a template before making your first API call.
Steeper learning curve for the editor.
Paid plans start at $29/month — more expensive entry point.
Template limit on free tier (3 templates).
Overkill if you just need standard invoices and receipts.

Best for: Businesses that need custom-designed documents (reports, certificates, contracts) and want visual control over every pixel. Great for no-code teams using Zapier/Make.

When to Use Which

Choose Kagyz if:

You need invoices, receipts, quotes, credit notes, or packing slips
You want zero template work — just send JSON
You serve Arabic/MENA markets and need RTL support
You want all features on every plan (no feature gating)

Choose PDFShift if:

You already have HTML templates and need a rendering engine
You need to convert existing web pages to PDF
You want the simplest possible API (URL in, PDF out)
You need HIPAA compliance

Choose CraftMyPDF if:

You need full visual control over document design
You generate documents beyond invoices (reports, certificates, contracts)
Your team includes non-developers who need to edit templates
You use no-code tools like Zapier or Make

Pricing Comparison

Plan	Kagyz	PDFShift	CraftMyPDF
Free	100 PDFs/month, all features	50 credits/month	50 PDFs/month, 3 templates
Entry paid	$19/month — 2,000 PDFs	$9/month — 500 credits	$29/month — 1,200 PDFs
Mid	$49/month — 10,000 PDFs	$24/month — 2,500 credits	$59/month — 5,000 PDFs

Note: PDFShift's credit system means 1 credit = 1 PDF up to 5MB. Larger documents cost more credits.

My Take

These tools solve different problems. PDFShift is a rendering engine — bring your own HTML. CraftMyPDF is a design platform — build templates visually. Kagyz is a document API — send data, get a finished document.

If you're a developer building a SaaS and you just need invoice PDFs without the headache, Kagyz is the fastest path. If you need pixel-perfect custom layouts, CraftMyPDF gives you the most control. If you already have HTML and just need it converted, PDFShift is the simplest.

I built Kagyz because I kept setting up Puppeteer for invoice PDFs in every project. Now I don't have to.

Links:

Kagyz: kagyz.com | Docs | GitHub
PDFShift: pdfshift.io
CraftMyPDF: craftmypdf.com

Easily Convert PDF Files to Word Documents in R

Wed, 19 Mar 2025 17:31:00 +0000

In this post, I will show you how you can very easily convert your PDF files into Word documents in the R programming language using the Convert2Docx R package.

Convert2Docx is a lightweight R package that R developers can readily use in their workflow to convert PDF files to Word documents easily.

I wrote the package as an R wrapper for the pdf2docx Python module, which converts PDF files to Word documents in Python.

The package contains just three functions for converting your PDF file to Word or DOCX.

Now, let us see this package in action.

Install Package

At the moment, the Convert2Docx R package is only available on GitHub. Therefore, to install it, you will need to first of all install devtools. Therefore, in your R console, run the code below to install devtools:

# install devtools 
install. Packages("devtools")

Having installed devtools, we can now install Convert2Docx package from GitHub. Run the code below to install it:

# install Convert2Docx from Github
devtools::install_github("Ifeanyi55/Convert2Docx")

Awesome! We are now ready to do some conversion. The next thing to do now is to install the conversion engine. Run the below code to install it:

# install engine
install_engine()

Please note that you only need to run this code once, and should you encounter any problem installing the engine, go to your terminal and run:

pip install pdf2docx

This should take care of any dependency issues. Make sure you have the latest version of Python installed on your machine before running the code, though.

After doing that, try installing the conversion engine again, and if all goes well, you should be able to access the full functionality of the package.

Let us now start converting files!

Convert Entire PDF File

It is good to mention at this point that you do not have to read the PDF file into your R environment before you can convert it. All you need to do is just specify the relative path to the file from your current working directory like so and run the converter:

# convert entire pdf file
pdf_file <- "myFile.pdf"

Converter(pdf_file = pdf_file,
          docx_filename = "myFile.docx")

Now, if you check your current working directory, you should see the converted file there. Let us explore this package further by converting from one page to another.

Convert From One Page to the Other

Here, we will use another function in the package to convert pages 3 to 5 of the PDF file to Word

# convert from one page to the other
pdf_file <- "myFile.pdf"

startANDend(pdf_file = pdf_file,
            docx_filename = "threetofive.docx",
            start = 2,
            end = 5)

It is good to mention here that the pages of some PDF files might not be correctly numbered.

Therefore, when the conversion to Word is done, especially when converting from one page to another, you could find that the page numbering is slightly different from what you were expecting.

In the example above, page 3 of the PDF file starts at page 2 by page count, which is why you see start = 2 in the code instead of 3.

However, this “problem” does not occur when you convert the entire document to Word as demonstrated earlier.

Now, let us convert selected pages in the PDF file.

Convert Selected Pages

To do this, you will need to parse a numeric vector representing the pages from the PDF file you want to convert

# convert selected pages
pdf_file <- "myFile.pdf"

selectPages(pdf_file = pdf_file,
            docx_filename = "mySelectedPages.docx",
            pages = c(2,4,6))

In the above code, I selected pages 2, 4, and 6 from the PDF file to be converted to Word, and it did a good job.

As you convert, don’t forget to check your current working directory for the converted files.

So, there you have it! Now you can easily convert your PDF files to Word documents in the R programming language thanks to the Convert2Docx R package.

Please, do not forget to give the Convert2Docx R package’s GitHub repository a ⭐️ if you find it helpful.

I hope you enjoyed reading this post.

You can follow me on GitHub: Ifeanyi55 and on X: @Ifeanyidiaye.

Coder Legion - Recent posts tagged pdf

Fine in Chrome, broken in Preview: two PDFKit gotchas for anyone who writes PDFs

Gotcha 1: an incremental update must use the same cross-reference form as the file it updates

Some background

What PDFKit does with that

The fix

Gotcha 2: PDFKit draws filled text fields itself

What PDFKit does

Why that bit us

The fix

Bonus gotcha from Acrobat: Reader extensions (/UR3)

How to test with PDFKit without clicking through Preview

Takeaways

Designing a Clear Upload-to-Export Flow for Four Document Jobs

A task selector is part of the product model

Show an output contract before upload

Keep “recognized” separate from “verified”

Design for the whole handoff

Shipping Internal Tools: Why Build Automation Matters More Than Code Quality

The Setup: Why This Matters

Part 1: Choosing Your PDF Library — The Tradeoff Matrix

PyMuPDF (fitz)

PyPDF2

pdfplumber

Nuitka (Compilation, Not a Library)

Part 2: The Actual Tool (With Lessons Baked In)

Design decisions that matter:

Part 3: Packaging Alternatives (Beyond PyInstaller)

PyInstaller (Our Choice)

cx_Freeze

Auto-py-to-exe

Nuitka (Honest Assessment)

Part 4: Build Automation (The Real Infrastructure)

Why this script matters:

Part 5: Learnings from Three Years of Shipping

1. Batch UX > Code Quality

2. The Build Script is Your Insurance Policy

3. Console Output is Richer Than You Think

4. Venv Per Build, Not Shared

5. PyInstaller + Fresh Venv Beats All Alternatives

6. Output Naming is Part of UX

7. Two-Mode UX (Folder + Files) is Invisible

Part 6: Scaling to a Tool Suite

The Complete Package

last_page_extractor.py (100 lines)

build_exe.ps1 (60 lines)

BuildExe.cmd (4 lines)

Workflow

Conclusion: Boring Infrastructure Wins

One report, rendered to HTML, PDF and Excel without a headless browser

The three code paths you end up with

A report is one problem, not four

Change the import, not the report

Why the spreadsheet gets a real number

Reports are data, not code

Every target uses the same seam

Nothing here compiles to JavaScript

The total that wasn't a floating point bug

What it deliberately isn't

Getting started

Closing thoughts

Magics PDF Converter

Making a screenshot PDF searchable — no OCR, because we rendered the page

The shape of it

Step 1 — ask the browser where the words are

Step 2 — the hidden-text trap (the hard part)

Step 3 — flip the Y axis

Step 4 — the font problem

Step 5 — draw it invisibly, and don't let one glyph kill the archive

Did it actually work?

How to Convert Word to PDF in the Browser with Vue 3, mammoth, and html2pdf.js

Why Client-Side?

The Stack

Loading the Word Document

Generating the PDF

Styling the Preview

Handling Errors Gracefully

Lessons Learned

Try It

Want More Advanced PDF Features?

Bonus gotcha from Acrobat: Reader extensions (`/UR3`)