DEV Community: Yan Wang

Report missing and repeated pages in a PDF split plan

Yan Wang — Sun, 01 Nov 2026 12:02:12 +0000

A split plan for a PDF is a list of parts, and each part is an array of zero-based page indices. When the parts are meant to divide a four-page document without overlap, counting four page references is not enough to establish coverage. [[0,1],[1,3]] contains four references, but index 1 appears twice and index 2 is absent.

For a well-formed plan like that, the function below returns the evidence instead of throwing: a missing list and a duplicates list that the caller can show or log before anything consumes the parts. It answers one small question: does every index from zero through pageCount - 1 occur exactly once across the parts? It does not establish that the parts are in the intended order or that a resulting PDF is correct.

Return the evidence, not just a count

The function takes arrays of zero-based indices. It records seen indices and repeated indices separately, then builds a sorted list of duplicates and a list of missing indices. A well-formed but incomplete plan returns those details. Malformed input throws instead: an empty part, a non-integer index, or an index outside the document is not treated as an ordinary coverage result.

The bounds belong to this teaching example: a page count from 1 to 1,000, one to 100 nonempty parts, and at most 2,000 total occurrences. They limit the inputs this function accepts and do not describe the limits of a PDF product. The function reads the arrays without changing them.

export function partitionCoverage(parts, pageCount) {
  if (!Number.isSafeInteger(pageCount) || pageCount < 1 || pageCount > 1000 ||
      !Array.isArray(parts) || parts.length < 1 || parts.length > 100) {
    throw new TypeError('invalid partition input');
  }
  const seen = new Set(), repeated = new Set();
  let occurrences = 0;
  for (const part of parts) {
    if (!Array.isArray(part) || !part.length || (occurrences += part.length) > 2000) {
      throw new TypeError('invalid part');
    }
    for (const page of part) {
      if (!Number.isSafeInteger(page) || page < 0 || page >= pageCount) {
        throw new TypeError('invalid zero-based page index');
      }
      if (seen.has(page)) repeated.add(page);
      seen.add(page);
    }
  }
  const missing = Array.from({length: pageCount}, (_, i) => i).filter(i => !seen.has(i));
  const duplicates = [...repeated].sort((a, b) => a - b);
  return {complete: missing.length === 0 && duplicates.length === 0, missing, duplicates};
}

A complete result is not an order check

For [[0,1],[1,3]], the result reports missing: [2] and duplicates: [1]. [[3,2],[1,0]], on the other hand, is a complete partition under this contract: each index occurs once, even though the sequence is reversed. If the application needs consecutive parts in source order, it needs a separate, explicitly defined order check.

Paste these assertions after the function in the same .mjs file. The valid cases include incomplete results; “valid” here means the function can evaluate the input, not that the partition is complete. The assertions also check that the inputs remain unchanged.

import assert from 'node:assert/strict';
const valid = [
 [[[0,1],[2,3]],4,{complete:true,missing:[],duplicates:[]}],
 [[[0,1],[1,3]],4,{complete:false,missing:[2],duplicates:[1]}],
 [[[3,2],[1,0]],4,{complete:true,missing:[],duplicates:[]}],
 [[[0,0]],1,{complete:false,missing:[],duplicates:[0]}],
 [[[0]],3,{complete:false,missing:[1,2],duplicates:[]}]
];
for (const [parts,count,expected] of valid) {
 const before=JSON.stringify(parts);assert.deepEqual(partitionCoverage(parts,count),expected);
 assert.equal(JSON.stringify(parts),before);
}
const invalid = [[[],3],[[[]],3],[[[3]],3],[[[-1]],3],[[['1']],3],[[[0.5]],3],[[[0]],0],[[[0]],1001],[[Array(2001).fill(0)],1],[Array(101).fill([0]),1]];
for(const [parts,count] of invalid) assert.throws(()=>partitionCoverage(parts,count));
console.log(JSON.stringify({valid:valid.length,rejected:invalid.length,boundary:'coverage only, not order or real PDF output'}));

The saved November 1 Node v22.23.4 run records five valid inputs and 10 rejected inputs. The stub exited with code 1 and the implementation with code 0. These synthetic assertions do not inspect page identity, printed numbering, rendering, navigation, or a real output file. No PDF decoding or writing, ZIP creation, browser or device behavior, or conversion was tested.

Disclosure: Drafted with GPT-6.1 Terra for Yan Wang / LensUp; Yan Wang is affiliated with LensUp. Polished by an independent editorial AI (lensup 主编); Codex (AI) fact-checked the text and checked the code against the retained synthetic runs. No human editor or owner reviewed or tested it. The background is November 1 source and public-page inspection plus the saved synthetic Node run described above.

Parse a page selection completely or not at all

Yan Wang — Sun, 01 Nov 2026 07:26:10 +0000

A page-selection field looks small until you ask what should happen with 1,, 2junk, or 1-1000,1. A forgiving parser might quietly keep the part it understands. For a document operation, that can leave the user with a different selection from the one they meant.

This example takes a narrower approach: under an explicit teaching policy, it accepts the entire input or returns null. It converts displayed page numbers, which start at one, into zero-based indices. It does not open or modify a PDF.

Define the contract before parsing

The grammar accepts ASCII positive integers and inclusive ranges separated by commas. Whitespace is allowed around tokens but not inside a range. Descending ranges are valid. If a page occurs more than once, the output keeps its first occurrence, so 4-2,2,6 becomes [3,2,1,5] for a six-page document.

The policy rejects leading zeroes, full-width digits, semicolons, empty tokens, trailing text, and out-of-range pages. Those choices help only if the interface tells users what it accepts. They are not a universal definition of page selection, and they do not describe a production parser's complete grammar.

The limits are part of this example's contract: at most 120 UTF-16 code units, 20 tokens, and 1,000 expanded occurrences, with a page count between 1 and 10,000. Expansion is counted before deduplication, so 1-1000,1 exceeds the budget even though the unique result would contain only 1,000 pages. A selection can be syntactically valid and still fail the budget.

export function parsePages(text, pageCount) {
  if (typeof text !== 'string' || text.length > 120 ||
      !Number.isSafeInteger(pageCount) || pageCount < 1 || pageCount > 10000) return null;
  const tokens = text.trim().split(',');
  if (tokens.length > 20) return null;
  const pages = [], seen = new Set();
  let expanded = 0;
  for (const token of tokens) {
    const match = /^([1-9]\d*)(?:-([1-9]\d*))?$/.exec(token.trim());
    if (!match) return null;
    const from = Number(match[1]), to = Number(match[2] ?? match[1]);
    if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) ||
        from > pageCount || to > pageCount) return null;
    expanded += Math.abs(to - from) + 1;
    if (expanded > 1000) return null;
    const step = to >= from ? 1 : -1;
    for (let page = from; page !== to + step; page += step) {
      if (!seen.has(page)) { seen.add(page); pages.push(page - 1); }
    }
  }
  return pages;
}

Check the policy, including rejections

Paste the assertions below after the function in the same .mjs file. The tests compare complete arrays, so they exercise both the indexing and the first-occurrence order. They also make the rejection policy visible to anyone who changes the parser later.

import assert from 'node:assert/strict';
const valid = [
 ['1-3,5',6,[0,1,2,4]],
 ['4-2,2,6',6,[3,2,1,5]],
 [' 1 , 3-2 ',3,[0,2,1]],
 ['2,2',3,[1]],
 ['1-1000',1000,Array.from({length:1000},(_,i)=>i)]
];
for (const [text,count,expected] of valid) assert.deepEqual(parsePages(text,count),expected);
const invalid = [
 ['',3],['1,',3],['2junk',3],['0',3],['4',3],['01',3],['１',3],
 ['1;2',3],['1 - 2',3],['1-1001',1001],['1-1000,1',1000],
 ['1',0],['1',2.5],['1',10001],[null,3],['1'.repeat(121),3],
 [Array(21).fill('1').join(','),3]
];
for (const [text,count] of invalid) assert.equal(parsePages(text,count),null);
console.log(JSON.stringify({valid:valid.length,rejected:invalid.length,boundary:'synthetic text and page indices only'}));

Number.isSafeInteger guards the numeric inputs and the parsed endpoints, and a Set records pages already emitted. Neither one decides how an application should report a rejection. This function returns the same value for every invalid case, so a user interface that needs specific explanations would need a separate, carefully defined diagnostic contract.

The saved November 1 Node v22.23.4 run records five valid and 17 rejected synthetic cases. The stub exited with code 1 and the implementation with code 0. That evidence covers these text and index examples, not PDF decoding or writing, ZIP creation, browser or device behavior, or conversion.

Test a JPG Name Collision Policy With Executable Examples

Yan Wang — Sat, 31 Oct 2026 02:50:29 +0000

Two successful results can end up with the same output name. If a ZIP builder stores entries under those names as object keys, a later entry can replace an earlier one before the archive is written. Resolving the names first makes the collision visible and gives both results distinct names within that allocation.

The allocator below is an educational policy, not the implementation of a product. Its input is an array of JPG leaf candidates after conversion, such as scan.jpg, not arbitrary source paths or source extensions. It only allocates names. It doesn't decode images or write archives.

Allocate within one run

The comparison key is NFC-normalized and lowercased. A noncolliding candidate is returned unchanged. A collision keeps the stem's spelling and adds -N.jpg with a lowercase extension, so scan.JPG can become scan-2.jpg. Suffixes start at -2, then -3, and so on, and an already occupied suffix is skipped. The set is local to the call, so each new call starts a fresh allocation.

export function allocateJpgNames(names) {
  if (!Array.isArray(names)) throw new TypeError('names must be an array');
  const taken = new Set();
  const key = name => name.normalize('NFC').toLowerCase();
  return names.map(name => {
    if (typeof name !== 'string' || !/\.jpg$/i.test(name) ||
        name.length <= 4 || /[\\/]/.test(name) || name.includes(String.fromCharCode(0))) {
      throw new TypeError('expected a JPG leaf candidate');
    }
    const stem = name.slice(0, -4);
    let candidate = name;
    let suffix = 2;
    while (taken.has(key(candidate))) candidate = `${stem}-${suffix++}.jpg`;
    taken.add(key(candidate));
    return candidate;
  });
}

Exercise the contract

Put both blocks, in order, in one .mjs file and run it with Node. The second block keeps the assertions from the supplied test. Only the allocator import was removed, because the function is in the same file.

import assert from 'node:assert/strict';
const cases = [
 [['scan.jpg','scan.jpg'],['scan.jpg','scan-2.jpg']],
 [['Scan.jpg','scan.JPG'],['Scan.jpg','scan-2.jpg']],
 [['caf\u00e9.jpg','cafe\u0301.jpg'],['caf\u00e9.jpg','cafe\u0301-2.jpg']],
 [['scan.jpg','scan-2.jpg','scan.jpg'],['scan.jpg','scan-2.jpg','scan-3.jpg']],
 [[],[]]
];
for(const [input,expected] of cases) {
 const saved=[...input];assert.deepEqual(allocateJpgNames(input),expected);assert.deepEqual(input,saved);
}
assert.deepEqual(allocateJpgNames(['scan.jpg','scan.jpg']),allocateJpgNames(['scan.jpg','scan.jpg']));
for(const invalid of [null,'a.jpg',[null],[''],['.jpg'],['a.png'],['dir/a.jpg'],['dir\\a.jpg'],['a\0.jpg']]) assert.throws(()=>allocateJpgNames(invalid));
console.log(JSON.stringify({valid_cases:cases.length,fresh_run_repeat:1,reject_cases:9,boundary:'synthetic candidate names only; no image/ZIP/filesystem operation'}));

The five valid lists cover an exact duplicate, case differences, canonically equivalent Unicode spellings, an occupied suffix, and an empty list. Each one also checks that the input array is unchanged. The repeat assertion compares two fresh calls; it doesn't simulate concurrent calls or persistent allocation. The nine invalid inputs exercise the function's stated input checks, including non-arrays, non-JPG candidates, separators, and NUL.

The retained run on October 31, 2026 used Node v22.23.4 and exited with code 0. Its output reported valid_cases: 5, fresh_run_repeat: 1, and reject_cases: 9. A red stub run exited 1 with an assertion failure. These are synthetic naming checks, not a conversion or ZIP test.

Keep identity separate from a name

Take two source records with different IDs that both yield scan.jpg. Their allocated names may be scan.jpg and scan-2.jpg, but the suffix encodes neither source ID. Keep a separate mapping from each source ID (and, where relevant, page) to its allocated output. A fresh run or a different candidate order can change that mapping. A name is not a content digest either.

NFC handles canonical equivalence; it is not NFKC, and JavaScript lowercasing is not full Unicode case folding. The comparison policy doesn't guarantee that every extraction filesystem will agree. The input checks also don't make this a secure, portable filename sanitizer. For example, they don't cover every reserved name or character. See MDN's String.prototype.normalize() reference for the normalization forms.

Disclosure: This article was drafted with GPT-6.1 Terra for Yan Wang / LensUp; Yan Wang is affiliated with LensUp. The text was polished by an independent editorial AI and fact-checked by Codex, with an independent code review. No human editor or owner reviewed or tested it. The evidence is source and public-page inspection and the retained synthetic Node checks, dated October 31, 2026. The Node checks covered synthetic JPG candidate names only: 5 valid lists including an empty list, 1 fresh-run repeat check, and 9 rejected inputs (Node v22.23.4, exit 0). No real image conversion, TIFF decoding, ZIP creation, filesystem, or device test was performed, and these checks do not establish product-function conformance.

Count OOXML Payload Bytes Without Pretending to Predict Compression

Yan Wang — Fri, 30 Oct 2026 02:38:43 +0000

An inventory can answer a narrow question before anyone tries to optimize a document: how many compressed entry-payload bytes were reported, and how many belong to rows the caller marked as candidates for rewriting? That’s useful accounting, and it isn’t a prediction of the output file size.

The function below takes metadata that is already normalized. It doesn’t open an Office document or decide whether an entry is an image. The caller supplies rewriteCandidate; a true value classifies the row for this calculation and doesn’t prove that the entry can actually be replaced or made smaller.

export function summarizePayloads(entries) {
  if (!Array.isArray(entries) || entries.length > 1000) {
    throw new TypeError('Expected at most 1000 metadata rows');
  }
  const seen = new Set();
  let payloadBytes = 0;
  let candidateBytes = 0;
  for (const row of entries) {
    if (!row || typeof row.path !== 'string' || row.path.length === 0 ||
        row.path.length > 200 || row.path.includes('\0') || seen.has(row.path) ||
        !Number.isSafeInteger(row.compressedBytes) || row.compressedBytes < 0 ||
        typeof row.rewriteCandidate !== 'boolean') {
      throw new TypeError('Invalid or duplicate metadata row');
    }
    seen.add(row.path);
    if (row.compressedBytes > Number.MAX_SAFE_INTEGER - payloadBytes) {
      throw new RangeError('Payload total exceeds safe integer range');
    }
    payloadBytes += row.compressedBytes;
    if (row.rewriteCandidate) candidateBytes += row.compressedBytes;
  }
  return { entryCount: entries.length, payloadBytes, candidateBytes,
    otherBytes: payloadBytes - candidateBytes };
}

The synthetic fixture below has three rows. To try it as one module, append this second block after the function in an .mjs file; the function is then already in scope. The duplicate assertion is there so that counting the same key twice can’t silently inflate a total.

import assert from 'node:assert/strict';

const fixture = [
  { path: 'ppt/presentation.xml', compressedBytes: 400, rewriteCandidate: false },
  { path: 'ppt/media/image1.jpeg', compressedBytes: 1200, rewriteCandidate: true },
  { path: 'ppt/media/video1.mp4', compressedBytes: 8400, rewriteCandidate: false },
];
const expected = { entryCount: 3, payloadBytes: 10000, candidateBytes: 1200, otherBytes: 8800 };
assert.deepEqual(summarizePayloads(fixture), expected);
assert.deepEqual(summarizePayloads([]), { entryCount: 0, payloadBytes: 0, candidateBytes: 0, otherBytes: 0 });
assert.equal(summarizePayloads([{ path: 'a', compressedBytes: 0, rewriteCandidate: true }]).candidateBytes, 0);
assert.equal(summarizePayloads([{ path: 'a', compressedBytes: Number.MAX_SAFE_INTEGER, rewriteCandidate: true }]).candidateBytes, Number.MAX_SAFE_INTEGER);
assert.throws(() => summarizePayloads([fixture[0], fixture[0]]), TypeError);

The result splits 10,000 reported payload bytes into 1,200 candidate bytes and 8,800 other bytes. The extension in a path plays no part in the classification; change the supplied boolean and the accounting changes. A candidate may still be unsuitable for rewriting, and a rewrite may fail to save bytes.

The checks make exact integer arithmetic a precondition. Each byte count must be a nonnegative safe integer, and the function rejects a row if adding it would push the total beyond Number.MAX_SAFE_INTEGER. Because candidate rows are a nonnegative subset of the total, a safe total also bounds the candidate sum. Paths are compared as exact strings to find duplicates. Empty paths, NUL characters, non-boolean flags, and more than 1,000 rows are rejected. The 1,000-row and 200-character limits are illustrative choices for this example; they are not Office format or product limits.

An empty array returns zero totals. It is valid input to this metadata function, but it is not a valid Office package. Paths are opaque accounting keys, not validated safe filenames or extraction destinations.

Compressed entry payloads omit ZIP structures and other archive overhead. The candidate total is neither a forecast of the next ZIP’s size nor a strict achievable lower bound. Parsing archives, validating untrusted files or relationships, performing file I/O, rewriting content, and predicting output are outside this function’s scope.

Disclosure: This manuscript was substantially drafted by GPT-6.1 Terra for Yan Wang / LensUp, with agent execution and fact review; Yan Wang is affiliated with LensUp. Source and live-page text were inspected on 2026-10-30. On 2026-10-30, a separately retained full metadata-test harness, code/checks.mjs, ran on Node 22.23.4 on Darwin: 4 valid assertions, 16 rejected cases, and 2 negative controls passed. The two code blocks shown in this article contain only 4 valid assertions and 1 rejection assertion. It did not test real Office optimization or archive, relationship, or renderer acceptance. The text was polished by an independent editorial AI and fact-checked by Codex, with an independent code review. No human editor or owner reviewed or tested it.

Plan EPUB Reading Order From the Spine, Not ZIP Filenames

Yan Wang — Thu, 29 Oct 2026 02:36:54 +0000

A ZIP listing can look like a reading plan: Text/02.xhtml, then Text/10.xhtml, then a notes file. It’s a tempting shortcut that answers the wrong question. Archive entry order and lexical filename order describe storage; they do not establish the EPUB’s intended reading order.

The EPUB package has a manifest of resources and a spine that references manifest items in order. The EPUB 3.3 spine specification describes that relationship. A navigation table of contents is separate, and a spine item is not necessarily a human chapter. A conversion pipeline that sorts archive names before reading the spine can produce a plausible-looking document in the wrong order.

The small planner below operates on already normalized JavaScript metadata. It is standalone example code, not LensUp production code. Its job is to preserve the order of spine references while checking a deliberately narrow contract. It does not open an EPUB, parse XML, or validate an archive.

Contract before implementation

Both inputs must be nonempty, dense arrays of at most 1,000 entries. The limit is a deliberately chosen budget for this example, not an EPUB rule or a LensUp product limit. A caller can choose a different budget after assessing the resources in its own environment.

Each manifest entry needs a unique, nonblank string id and a nonblank string href. Each spine reference needs a nonblank idref resolving to a manifest ID, and each ID may be referenced at most once. A linear value may be absent, yes, or no. An absent value defaults to primary reading order; no marks auxiliary content. The planner retains auxiliary entries and their position, with an explicit Boolean flag. It rejects an all-auxiliary plan under this example’s contract rather than silently returning a plan with no primary item.

Strings are checked for blankness but are not trimmed or rewritten. IDs are matched exactly. Hrefs remain opaque text: their presence is checked, but they must not be treated as trusted filesystem or network paths. This function does not validate URLs, verify resource presence, or establish that an EPUB is safe to process.

Put this block followed by the test block in one .mjs file, then run that file with Node. The export is valid in the same module as the assertions.

export function planSpine(manifest, spine) {
  const bounded = value => Array.isArray(value) &&
    value.length > 0 && value.length <= 1000 &&
    Array.from({ length: value.length }, (_, i) => i in value).every(Boolean);
  const text = value => typeof value === "string" && value.trim().length > 0;
  if (!bounded(manifest) || !bounded(spine)) throw new TypeError("bounded lists required");
  const byId = new Map();
  for (const item of manifest) {
    if (!item || !text(item.id) || !text(item.href) || byId.has(item.id)) {
      throw new TypeError("unique manifest ids and nonempty hrefs required");
    }
    byId.set(item.id, item.href);
  }
  const seen = new Set();
  const plan = spine.map((ref, sourceIndex) => {
    if (!ref || !text(ref.idref) || !byId.has(ref.idref) || seen.has(ref.idref) ||
        ![undefined, "yes", "no"].includes(ref.linear)) {
      throw new TypeError("invalid spine reference");
    }
    seen.add(ref.idref);
    return { id: ref.idref, href: byId.get(ref.idref),
      linear: ref.linear !== "no", sourceIndex };
  });
  if (!plan.some(item => item.linear)) throw new TypeError("a primary item is required");
  return plan;
}

import assert from "node:assert/strict";
const manifest = [
  { id: "later", href: "Text/02.xhtml" },
  { id: "start", href: "Text/10.xhtml" },
  { id: "notes", href: "Text/notes.xhtml" },
];
const spine = [{ idref: "start" }, { idref: "notes", linear: "no" },
  { idref: "later", linear: "yes" }];
const plan = planSpine(manifest, spine);
assert.deepEqual(plan.map(item => item.id), ["start", "notes", "later"]);
assert.deepEqual(plan.map(item => item.linear), [true, false, true]);
assert.deepEqual(plan.map(item => item.sourceIndex), [0, 1, 2]);
assert.deepEqual(planSpine([...manifest].reverse(), spine), plan);

What the assertions establish

The fixture deliberately puts Text/10.xhtml before Text/02.xhtml in the spine. The first assertion checks the resulting ID order; the second checks the default, auxiliary, and explicit primary flags; the third checks retained source positions. Reversing the manifest then demonstrates that manifest order does not change this plan. The two blocks contain only those four valid assertions, not the separate invalid-case checks.

An actual Node run of the normalized-metadata check suite reported four valid assertions, 14 invalid cases, and two negative controls with exit code zero. Those results concern the pure planner, not a rendered or converted book. In particular, this example does not implement fallback chains, inspect scripts or media-type support, check assets or DRM, resolve crosslinks, paginate, perform file I/O, or defend against archive bombs. Those concerns need their own processing and validation stages.

Treat the planner’s output as an ordered set of references for a later stage, not as proof that those resources can be safely read or faithfully converted. Retaining the auxiliary flag lets that later stage make an explicit policy decision without confusing linear="no" with a deletion instruction.

This article was substantially drafted by GPT-6.1 Terra for Yan Wang / LensUp. A Codex agent inspected formal source and live page text on 2026-10-29 and ran the pure normalized-metadata checks described above. No new EPUB conversion, browser or reader rendering, device test, or human-owner test was performed.

A contain rectangle is a contract, not a PDF fidelity test

Yan Wang — Wed, 28 Oct 2026 02:32:02 +0000

A rectangle helper can answer a narrow question: given image dimensions and a page-sized box, where should the image be drawn so it fits proportionally? That answer is useful only when its assumptions and boundaries are explicit.

The contract below accepts image width and height, page width and height, and a uniform margin. It returns a centered draw rectangle. It does not read an image, interpret orientation metadata, or create a PDF.

Define the policy first

For this standalone example, all four dimensions must be finite JavaScript numbers from 1 through 1,000,000, inclusive. The margin must be finite and nonnegative, and twice the margin must be smaller than both page dimensions. That leaves a nonempty usable rectangle.

The numeric range is a chosen example budget, not a universal standard or a claim about identical production input validation. The function treats source width and height as values in the same numeric mapping used for page units. Capping the scale at one means one source unit maps to at most one page unit. This is a policy for this example, not a physical DPI conversion.

A successful result should satisfy four invariants:

Aspect ratio: width and height share one scale, so their ratio follows the source ratio, subject to floating-point precision.
Bounds: the draw rectangle fits inside both dimensions of the usable page area.
Centering: the remaining space is split equally on opposite sides.
No upscale: neither output dimension exceeds its corresponding source dimension under the chosen unit mapping.

export function containRect(iw, ih, pw, ph, margin) {
  if (![iw, ih, pw, ph].every(v =>
    typeof v === "number" && Number.isFinite(v) && v >= 1 && v <= 1e6
  )) throw new RangeError("dimensions must be numbers from 1 to 1000000");
  if (typeof margin !== "number" || !Number.isFinite(margin) ||
      margin < 0 || 2 * margin >= Math.min(pw, ph)) {
    throw new RangeError("margin leaves no usable rectangle");
  }
  const scale = Math.min(1, (pw - 2 * margin) / iw, (ph - 2 * margin) / ih);
  const width = iw * scale;
  const height = ih * scale;
  return { x: (pw - width) / 2, y: (ph - height) / 2, width, height };
}

Taking the minimum picks whichever of width or height is the limiting side, with one as the upper bound. Centering uses the full page dimensions; because the margins are equal on opposite sides, the resulting rectangle remains centered inside the usable area too.

Run the example

Place the function and the following assertions in the same file named example.mjs, with the function first. Run node example.mjs. The import supplies Node’s strict assertions; a successful run prints nothing. The examples check a wide image, a small image, and three rejected inputs.

import assert from "node:assert/strict";

assert.deepEqual(containRect(1200, 600, 600, 800, 20),
  { x: 20, y: 260, width: 560, height: 280 });
assert.deepEqual(containRect(100, 50, 600, 800, 20),
  { x: 250, y: 375, width: 100, height: 50 });
for (const args of [
  ["1200", 600, 600, 800, 20],
  [1200, 600, 600, 800, 300],
  [0, 600, 600, 800, 20],
]) assert.throws(() => containRect(...args), RangeError);

For the first case, the usable area is 560 by 760. Width limits the scale, producing a 560 by 280 rectangle at (20, 260). For the second, the scale cap keeps the 100 by 50 image at that size and centers it at (250, 375).

The broader numeric harness also checks two deliberately wrong calculations: stretching to 560 by 760 breaks the source’s 2:1 ratio, and uncapped fitting would enlarge a 100 by 50 source. Those comparisons expose the need for aspect and no-upscale policies. The short assertion block above does not include those two comparisons.

Know what the numbers establish

On 2026-10-28, a Codex agent ran pure numeric cases using Node v22.23.4 on Darwin: nine valid cases, 12 invalid cases, nine comparisons with the production helper for valid numeric draw dimensions, and two negative controls. The comparison does not establish full implementation equivalence or matching input policies.

A correct rectangle cannot prove that the intended image was decoded, rotated correctly, embedded without an unwanted change, serialized into the right page box, or displayed as a recipient expects. Those require separate artifact and reader checks. No encoded image or PDF was tested in this numeric exercise.

Disclosure: GPT-6.1 Terra drafted this article for Yan Wang / LensUp. The Codex agent checked formal source and live-page text and ran the numeric cases on 2026-10-28. No new HEIC or image-to-PDF conversion, browser, phone, printer, or human-owner test was performed.

A Centimeter-to-Pixel Contract With Explicit Limits

Yan Wang — Tue, 27 Oct 2026 02:37:38 +0000

A request for an image in centimeters is not yet an encoded image. It becomes easier to validate when the work is split into four layers: a physical-size request, an integer pixel plan, an encoded file, and a possible print. Each layer has its own inputs and evidence.

This standalone JavaScript example handles only the pixel plan. It accepts two positive centimeter values and an integer pixels-per-inch density, rounds each axis to the nearest whole pixel, and rejects plans outside an example resource budget. It is not a production patch or a complete image-processing pipeline.

Define the input contract

For each axis, the calculation is cm / 2.54 * ppi, rounded with Math.round. Width and height are validated independently. All three inputs must be JavaScript numbers that are finite and positive: a numeric-looking string, NaN, infinity, zero, or a negative value is rejected. Density must additionally be an integer from 1 through 65535.

The result must contain safe integer dimensions of at least one pixel. That matters even when a centimeter input is positive: a sufficiently small value can round to zero. This example rejects such a request. The formal product uses a different policy and clamps that boundary; the example should not be read as an identical implementation.

The 10,000-pixel edge and 40-million-pixel area limits below are choices made for this example. They are not universal browser or codec limits. The area check happens after rounding, using the actual planned integer dimensions.

export function rasterPlan(widthCm, heightCm, ppi) {
  if (![widthCm, heightCm, ppi].every(
    value => typeof value === "number" && Number.isFinite(value) && value > 0
  )) throw new RangeError("dimensions and density must be finite positive numbers");
  if (!Number.isInteger(ppi) || ppi > 65535) {
    throw new RangeError("density must be an integer from 1 to 65535");
  }
  const width = Math.round((widthCm / 2.54) * ppi);
  const height = Math.round((heightCm / 2.54) * ppi);
  if (![width, height].every(n => Number.isSafeInteger(n) && n >= 1)) {
    throw new RangeError("requested size does not produce a valid pixel grid");
  }
  if (width > 10000 || height > 10000 || width * height > 40000000) {
    throw new RangeError("requested pixel grid exceeds the example budget");
  }
  return { width, height, ppi };
}

A per-edge check alone is not enough. At 300 ppi, 60 × 60 cm rounds to 7087 × 7087 pixels. Each edge is below 10,000, but the area exceeds 40 million pixels, so this contract rejects it.

Run a small example

Place the function and the following block, in that order, in one file named one.mjs, then run node one.mjs. The export is valid because the file is an ES module. A successful run produces no assertion output. This is a Node reproduction, not a live-browser demonstration.

import assert from "node:assert/strict";

assert.deepEqual(rasterPlan(5, 7, 300), { width: 591, height: 827, ppi: 300 });
for (const args of [
  ["5", 7, 300],
  [5, 7, 300.5],
  [0.001, 0.001, 1],
  [60, 60, 300],
]) {
  assert.throws(() => rasterPlan(...args));
}

The parent numeric harness covered six valid cases, 16 invalid cases and four rounding cases. Its negative control showed that a width-only guard misses the area cap. Those counts describe pure numeric checks and read-only comparisons with the formal helper, not human testing, browser conversion or image generation.

What the return value cannot establish

The returned ppi is requested plan metadata. It does not prove that a JPEG contains the intended JFIF density, that a PNG contains the intended pHYs value, or that a downstream application will honor either field. Encoding requires its own format-specific write and read-back checks. PNG density is stored in pixels per meter, so conversion to that unit can introduce quantization.

Likewise, a valid pixel grid does not say how an image was fitted into it. Preserving the whole image, cropping and stretching produce different compositions. A lossy JPEG can also change visual detail without changing the grid. Printing introduces another layer of page geometry, scaling and device behavior. Keep those checks separate from the arithmetic contract.

Disclosure: GPT-6.1 Terra generated the initial draft for Yan Wang / LensUp, and an independent AI editor revised it. On October 27, a Codex agent checked the live page text, local formal source and pure numeric cases, including factual, code and disclosure checks. No new image conversion, phone or printer test, recipient acceptance, or personal check by the account owner is claimed.

Validate a PDF reorder as a permutation before you test the export

Yan Wang — Mon, 26 Oct 2026 02:33:07 +0000

AI and affiliation disclosure: Codex generated this article and its JavaScript example for Yan Wang / LensUp. Codex ran the local checks described below; this does not claim personal execution or independent validation by the human account owner. The example is a standalone plan validator, not a production patch or a PDF exporter.

A reorder UI can display the expected number of thumbnails while its export plan contains the same source page twice. Checking the plan's length catches a missing slot, but not a duplicate that replaced another page.

For a pure reorder of one document, the useful input contract is narrow: every original physical page index appears exactly once. Deletion, repetition and insertion are different operations. They need different validators.

Define the index space first

The example accepts zero-based physical page indexes. For a four-page document, the allowed set is 0 through 3. It does not interpret printed numbers or PDF page labels.

The array [3, 0, 1, 2] means “take original physical page four first.” It is a valid permutation. It may still be the wrong reading order for the user. Validation can confirm the structure of the request, not its intent.

Check every slot

export function validateReorder(order, pageCount) {
  if (!Number.isSafeInteger(pageCount) || pageCount < 1) {
    throw new RangeError("pageCount must be a positive safe integer");
  }
  if (!Array.isArray(order) || order.length !== pageCount) {
    throw new TypeError("order must contain one slot per source page");
  }

  const seen = new Set();
  for (let i = 0; i < order.length; i += 1) {
    const page = order[i];
    if (!Number.isInteger(page) ||
        page < 0 || page >= pageCount || seen.has(page)) {
      throw new RangeError("order must be a permutation of source indexes");
    }
    seen.add(page);
  }
  return order.slice();
}

The indexed loop is deliberate. An ordinary sparse array has a length, but a missing slot reads as undefined. The integer check rejects it. Array methods that skip holes can make an incomplete plan look more complete than it is.

The returned array is a copy, so later changes to the caller's array don't change the accepted plan. This is not a deep-copy utility or a guard against hostile proxies and accessors; it expects ordinary application arrays containing numbers.

Test failures with the same page count

import assert from "node:assert/strict";

assert.deepEqual(validateReorder([3, 0, 1, 2], 4), [3, 0, 1, 2]);
assert.throws(() => validateReorder([0, 1, 1, 3], 4));
assert.throws(() => validateReorder([0, 1, 2, 4], 4));
assert.throws(() => validateReorder([0, 1, 2, "3"], 4));
assert.throws(() => validateReorder([0, 1, , 3], 4));

const requested = [1, 0];
const accepted = validateReorder(requested, 2);
requested.reverse();
assert.deepEqual(accepted, [1, 0]);

These assertions can follow the function in one ES module. The harness used for this article also checks invalid counts, non-array inputs, negative and fractional indexes, NaN, Infinity and shorter plans. Results and the actual runtime are retained with the manuscript; they do not constitute a browser or PDF-format compatibility test.

Snapshot the request, then test the artifact

Use the accepted plan as the input to the export job. If the user can continue editing while a save runs, decide how that job's snapshot is isolated from later UI changes. Copying this one array does not snapshot the entire document or solve asynchronous state management.

After export, open the saved PDF and check identifiable page content against the expected physical sequence. The validator never reads that PDF. It cannot detect an exporter using a stale array, writing pages in a different order, dropping content, breaking a link or changing a form.

So there are two separate questions: is this a structurally valid reorder request, and did this particular saved artifact implement it?

A valid permutation with the wrong intended sequence should pass the first test and fail the user's acceptance check. Keeping that distinction explicit gives each failure somewhere useful to go.

The article's two JavaScript blocks were executed together as an ES module with Node.js v22.23.4 on macOS. To reproduce the displayed checks, save them together as reorder-check.mjs and run node reorder-check.mjs. The separate retained harness adds the wider counterexample set described above.

Keep the scope small

This example intentionally has no “skip invalid entries” mode. Silently repairing [0, 1, 1, 3] would require deciding what the user meant. Fail the plan and return control to the UI instead.

It also does not claim that source indexes survive a mutation to the source document. Bind the plan to the document version being exported. A plan that was valid for an earlier page set is not automatically valid for a later one.

References: Number.isInteger, Array holes and iteration.

Test PDF merge navigation separately from page order

Yan Wang — Sun, 25 Oct 2026 08:00:00 +0000

AI disclosure: Codex generated this article and its code, created the synthetic PDFs, and performed the conversion and file checks. No personal execution or independent validation by the human account owner is claimed.

A merged PDF can have the expected page count and still send a bookmark to the wrong place. A useful acceptance check needs to name three requirements separately: page order, bookmark hierarchy and destinations, and in-page link destinations.

The case here uses two two-page synthetic documents. Both have an Overview bookmark with a Details child. Each first page also contains a link to its own second page. The files were merged in Beta, then Alpha order, deliberately reversing their alphabetical filenames.

Define page identity before checking navigation

The source pages carry visible identity tokens: ALPHA-1, ALPHA-2, BETA-1 and BETA-2. The required output sequence is:

output index 0: BETA-1
output index 1: BETA-2
output index 2: ALPHA-1
output index 3: ALPHA-2

Indices in the code are zero-based. A reader showing page 1 is displaying index 0.

The expected bookmarks are an ordered list, including depth and target identity:

Depth	Title	Target index	Target token
0	Overview	0	BETA-1
1	Details	1	BETA-2
0	Overview	2	ALPHA-1
1	Details	3	ALPHA-2

A dictionary keyed only by title cannot represent this requirement. It retains two keys from four nodes and overwrites the first document's entries. The duplicate labels are deliberate fixture data, not a reason to discard a branch.

The two page links have their own contract: output index 0 must lead to index 1, and index 2 must lead to index 3. Correct bookmarks do not prove these annotation targets are correct.

Reproduce the source documents

Start in a new, empty working directory.

The tested environment was macOS with Python 3.12.14, pypdf 6.10.0 and ReportLab 4.4.9. Use a virtual environment for the example dependencies:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install pypdf==6.10.0 reportlab==4.4.9

Save this as make_source.py:

"""Standalone reader recipe; writes two synthetic PDFs only when run as a script."""
import io
from pathlib import Path
from reportlab.pdfgen import canvas
from reportlab.lib.pagesizes import A4

def make_source(name):
    stream = io.BytesIO()
    pdf = canvas.Canvas(stream, pagesize=A4, invariant=1, pageCompression=1)
    pdf.setTitle(f'{name.title()} fictional handbook')
    pdf.setAuthor('Synthetic fixture')
    for page in (1, 2):
        pdf.setFont('Helvetica-Bold', 22)
        pdf.drawString(50, 770, f'{name.upper()} / PAGE {page}')
        pdf.setFont('Helvetica', 12)
        pdf.drawString(50, 735, 'Fictional navigation test. Not a customer document.')
        pdf.drawString(50, 708, f'Identity token: {name.upper()}-{page}')
        if page == 1:
            pdf.bookmarkPage('overview')
            pdf.addOutlineEntry('Overview', 'overview', level=0, closed=False)
            pdf.setFillColorRGB(0, 0.2, 0.65)
            pdf.drawString(50, 660, 'Jump to this handbook\'s Details page')
            pdf.linkRect('', 'details', (48, 653, 330, 677), relative=0, thickness=1)
            pdf.setFillColorRGB(0, 0, 0)
            pdf.drawString(50, 620, 'Expected local target before merge: the second page.')
        else:
            pdf.bookmarkPage('details')
            pdf.addOutlineEntry('Details', 'details', level=1, closed=False)
            pdf.drawString(50, 660, f'This is the Details page of {name.title()}.')
        pdf.showPage()
    pdf.save()
    return stream.getvalue()

if __name__ == '__main__':
    for name in ('alpha', 'beta'):
        Path(f'{name}-handbook.pdf').write_bytes(make_source(name))

Run python make_source.py. The agent independently ran this standalone recipe in memory and obtained bytes identical to the two retained source files with those tested package versions. This is a reproducible input recipe, not a promise of identical output bytes from different PDF mergers.

Merge beta-handbook.pdf before alpha-handbook.pdf in the merger you are testing. Save the actual downloaded result as merged.pdf; inspect that file rather than the source documents or the on-page preview.

Inspect the encoded page targets

The following inspector is deliberately limited to this synthetic fixture. It accepts explicit local page-reference destinations, either /Dest or a simple /A /GoTo action. Named destinations, URI/remote actions, action chains and destination-free group headings need a different inspector. They are outside this example's accepted scope.

Save this as navigation.py:

"""Bounded synthetic-fixture inspector: simple explicit local destinations only."""
import json
import re
import sys
from pypdf import PdfReader
from pypdf.generic import ArrayObject, DictionaryObject, IndirectObject

class OutOfScope(ValueError):
    pass

def inspect_pdf(source):
    reader = PdfReader(source)
    page_map = {(page.indirect_reference.idnum, page.indirect_reference.generation): i
                for i, page in enumerate(reader.pages)}
    tokens = []
    for page in reader.pages:
        found = re.findall(r'Identity token: ((?:ALPHA|BETA)-[12])\b', page.extract_text() or '')
        if len(found) != 1:
            raise OutOfScope('Each fixture page needs exactly one known text identity token')
        tokens.append(found[0])

    def target(item):
        if '/Dest' in item and '/A' in item:
            raise OutOfScope('Mixed destination and action is outside this fixture')
        if '/Dest' in item:
            destination = item['/Dest']
        else:
            action = item.get('/A')
            action = action.get_object() if action is not None else None
            if not isinstance(action, DictionaryObject) or action.get('/S') != '/GoTo' or '/Next' in action:
                raise OutOfScope('Only a simple local GoTo action is supported')
            destination = action.get('/D')
        destination = destination.get_object() if destination is not None else None
        if not isinstance(destination, ArrayObject) or not destination or not isinstance(destination[0], IndirectObject):
            raise OutOfScope('Only explicit local page-reference arrays are supported; no named destinations')
        ref = destination[0]
        index = page_map.get((ref.idnum, ref.generation))
        if index is None:
            raise OutOfScope('Destination does not reference a page in this document')
        return index

    outline = []
    visited = set()
    def walk(first, depth=0):
        current = first
        while current is not None:
            node = current.get_object()
            if not isinstance(node, DictionaryObject):
                raise OutOfScope('Malformed outline node')
            key = (current.idnum, current.generation) if isinstance(current, IndirectObject) else id(node)
            if key in visited or depth > 64 or len(visited) >= 1000:
                raise OutOfScope('Repeated, cyclic or overly deep outline is outside this fixture')
            visited.add(key)
            index = target(node)
            outline.append({'depth': depth, 'title': str(node.get('/Title', '')),
                            'target_page_index': index, 'target_token': tokens[index]})
            if '/First' in node:
                walk(node.raw_get('/First'), depth + 1)
            current = node.raw_get('/Next') if '/Next' in node else None

    root = reader.root_object.get('/Outlines')
    if root is not None:
        root = root.get_object()
        if '/First' in root:
            walk(root.raw_get('/First'))
    links = []
    for i, page in enumerate(reader.pages):
        for ref in page.get('/Annots', []):
            annotation = ref.get_object()
            if annotation.get('/Subtype') == '/Link':
                index = target(annotation)
                links.append({'source_page_index': i, 'target_page_index': index,
                              'target_token': tokens[index]})
    return {'page_tokens': tokens, 'outline': outline, 'links': links}

def compare_fixture(snapshot):
    expected_tokens = ['BETA-1', 'BETA-2', 'ALPHA-1', 'ALPHA-2']
    expected_outline = [
        {'depth': depth, 'title': title, 'target_page_index': index, 'target_token': expected_tokens[index]}
        for depth, title, index in [(0, 'Overview', 0), (1, 'Details', 1),
                                    (0, 'Overview', 2), (1, 'Details', 3)]
    ]
    expected_links = [{'source_page_index': source, 'target_page_index': target,
                       'target_token': expected_tokens[target]} for source, target in [(0, 1), (2, 3)]]
    result = {'page_order_match': snapshot['page_tokens'] == expected_tokens,
              'outline_match': snapshot['outline'] == expected_outline,
              'links_match': snapshot['links'] == expected_links}
    return {**result, 'all_match': all(result.values())}

if __name__ == '__main__':
    try:
        snapshot = inspect_pdf(sys.argv[1])
        checks = compare_fixture(snapshot)
        print(json.dumps({'snapshot': snapshot, 'checks': checks}, indent=2))
        raise SystemExit(0 if checks['all_match'] else 1)
    except OutOfScope as error:
        print(json.dumps({'status': 'OUT_OF_SCOPE', 'reason': str(error)}))
        raise SystemExit(2)

Run:

python navigation.py merged.pdf

For the retained browser download, all three checks were true. The file had four pages, four outline nodes and two internal links. Each destination resolved to the expected page object and its expected text token. The downloaded file was 3,235 bytes; that is a property of this run, not a size target.

pypdf's reader API also exposes outline and get_destination_page_number(). The raw destination inspection above makes this fixture's accepted action shapes explicit. It does not validate every destination operand, zoom setting, hit rectangle, outline count flag or PDF conformance rule.

Make the negative examples change different requirements

The retained file passed. The check was also exercised against in-memory constructed variants: a wrong destination on the second Overview, a wrong page-link target with unchanged bookmarks, missing bookmarks, missing links, and a different page order. Each relevant comparison failed. These were constructed counterexamples, not failures observed in the live merger.

A separate simple /A /GoTo encoding passed the same fixture contract. Named targets, a URI action and an action chain reported outside the inspector's scope. The ten-case suite includes the retained download and these constructed variants; it does not represent ten browser runs.

The four output pages were also rendered with Poppler at 85 DPI and compared with their corresponding source pages. Their decoded RGB pixels matched in this fixture. Visual inspection of those renders agreed. That checks the simple page appearance separately from the navigation data.

No PDF-reader bookmark or link clicks were exercised, and no cross-viewer behavior is claimed. This test also says nothing about forms, signatures, accessibility structure, encryption or other action types. For a real acceptance requirement, keep the encoded-target check and a representative reader-click check as distinct evidence.

Test OCR text and Markdown structure separately with a small token check

Yan Wang — Sun, 25 Oct 2026 02:00:00 +0000

AI disclosure: Codex, an AI agent, wrote this article and code and performed the checks. The observed export is a retained browser-test artifact. The edited examples are constructed comparisons, not additional OCR runs or claims of firsthand human testing.

An OCR note can keep every word you need and still miss the structure your template expects. This article builds a small token check that answers those as two separate questions: does the content match a known source, and does the Markdown have the headings and paragraphs a downstream template requires? It is not an OCR benchmark and not a product fix.

The fixture

The fixture is a single retained export from a browser OCR-to-Markdown test on October 23, 2026. The input was a clean English PNG with a workshop title, a subtitle, a meeting time, a room and two item counts. The downloaded Markdown began:

WORKSHOP NOTE Fictional OCR sample

Start time: 09:30

Room: Cedar 12

Bring 3 notebooks.

Return 2 markers.

Keep this image for comparison.

In the source image, WORKSHOP NOTE and Fictional OCR sample sit on separate lines. The export joined them into one paragraph. The time, room and quantities came through intact. This export is the only observed output in the article, and it doesn't establish OCR accuracy. Because the engine's block tree wasn't retained, there's also no way to trace the merge to a particular recognition or formatting step.

Give each acceptance question its own result

The profile for this fixture defines four checks:

The content equals the known source after whitespace normalization.
The time, room and two quantity statements appear as complete paragraphs.
The title is a level-two Markdown heading.
The subtitle is a separate paragraph.

The heading level is a choice made for this downstream note template, not a promise every OCR converter makes. Another workflow might accept plain text and need no heading at all. OCR tooling keeps these concerns apart as well. Tesseract.js's versioned type definitions expose text, confidence and layout blocks as separate fields, and none of them supplies an application's publishing profile.

Inspect Markdown tokens rather than heading-shaped strings

A substring check finds WORKSHOP NOTE whether it sits in a heading or a paragraph. A token check asks which structure the parser actually recognized.

The example uses Marked's lexer and deliberately supports only plain headings and paragraphs. Lists, code fences, links, inline formatting and HTML fall outside this small profile and raise an explicit error. It is not a general Markdown-to-text extractor.

Start in a fresh working directory with a Node.js version that supports ESM. The checks here ran with Node.js 24.19.0 and Marked 17.0.5:

npm init -y
npm install --save-exact marked@17.0.5

Save this as audit-note.mjs:

import { marked } from 'marked';

const normalize = (text) => text.replace(/\s+/gu, ' ').trim();

export function auditNote(markdown, profile) {
  const blocks = marked.lexer(markdown).filter((token) => token.type !== 'space');
  for (const token of blocks) {
    if (!['heading', 'paragraph'].includes(token.type)
        || token.tokens?.some((inline) => inline.type !== 'text')) {
      const error = new Error('Only plain headings and paragraphs are in scope');
      error.code = 'OUT_OF_SCOPE';
      throw error;
    }
  }
  const paragraphs = blocks.filter((token) => token.type === 'paragraph')
    .map((token) => normalize(token.text));
  return {
    contentMatches: normalize(blocks.map((token) => token.text).join(' '))
      === normalize(profile.sourceLines.join(' ')),
    criticalParagraphsMatch: profile.criticalParagraphs.every(
      (text) => paragraphs.includes(normalize(text))),
    titleIsH2: blocks.some((token) => token.type === 'heading'
      && token.depth === 2 && normalize(token.text) === normalize(profile.title)),
    subtitleIsParagraph: paragraphs.includes(normalize(profile.subtitle)),
  };
}

The content comparison normalizes whitespace on purpose, so differences in wrapping and blank lines don't count. Case and punctuation still do. The check doesn't calculate a character error rate or judge an unknown document. The critical-paragraph check is exact too: a field that ends up inside a heading fails that template rule.

Run the retained export and two constructed comparisons

Save the following as demo-note.mjs next to the module, then run node demo-note.mjs:

import { auditNote } from './audit-note.mjs';

const sourceLines = [
  "WORKSHOP NOTE",
  "Fictional OCR sample",
  "Start time: 09:30",
  "Room: Cedar 12",
  "Bring 3 notebooks.",
  "Return 2 markers.",
  "Keep this image for comparison."
];
const profile = {
  sourceLines,
  title: sourceLines[0],
  subtitle: sourceLines[1],
  criticalParagraphs: sourceLines.slice(2, 6),
};
const actual = "WORKSHOP NOTE Fictional OCR sample\n\nStart time: 09:30\n\nRoom: Cedar 12\n\nBring 3 notebooks.\n\nReturn 2 markers.\n\nKeep this image for comparison.";
const authored = ['## ' + sourceLines[0], ...sourceLines.slice(1)].join('\n\n');
console.log('retained export', auditNote(actual, profile));
console.log('authored layout example', auditNote(authored, profile));
console.log('constructed time typo', auditNote(authored.replace('09:30', '09:3O'), profile));

The retained export reports true for content and critical paragraphs, and false for the title and subtitle rules. The authored layout example reports true for all four. Changing 09:30 to 09:3O in the authored example makes the content and critical-paragraph checks fail, while the title and subtitle checks still pass.

Only the first input is observed output. The authored layout is a constructed example of the desired structure. It isn't a second OCR result or evidence of a product repair. The typo is a deliberate mutation, not an observed recognition error.

Test the limits of the check

The local verification also tried an equivalent Setext level-two heading, a changed room, a missing quantity statement, a wrong heading level, a duplicated field and unsupported Markdown constructs. The Setext heading passes, because the lexer recognizes what it means. A fenced copy of all the expected text is rejected rather than treated as a ready note. These cases test the validator's scope. They don't turn one OCR sample into a benchmark.

Keep the original image, the unedited export, the expected content and the chosen profile together. Then a failure report can say which of three things happened: the words changed, a critical field moved, or a structural rule was missed. Each one calls for a different fix.

Page positions, page labels, and printed numbers are different PDF data

Yan Wang — Sat, 24 Oct 2026 02:00:00 +0000

A PDF subset can contain exactly the right pages while reporting misleading page labels. Page-count and extracted-text checks can both pass.

In a small browser extraction check, a six-page synthetic PDF was reduced to source positions 3, 4, and 6. The saved PDF contained the expected chapter and appendix text. Its logical labels, however, were COVER, i, and 1—the labels associated with the beginning of the source, not with the selected source pages.

AI disclosure: an AI agent prepared this article and the inspection code. The case uses fictional documents and two actual browser downloads. The code was exercised with pypdf 6.10.0; this article does not claim a production fix or a survey of PDF tools.

Define which “page number” you mean

Three values can differ:

Position: where a page occurs in the document. A UI commonly starts this count at 1; an array commonly starts at 0.
Logical label: metadata a reader can display, such as i, 1, or A-2.
Printed number: text or graphics drawn on the page itself.

These are separate inputs to an extraction contract. Changing the page list does not, by itself, rewrite the number printed in a footer. A reader's label also need not equal that printed number.

PDF.js documents the distinction in its API: getPage() takes a position starting at 1, getPageIndex() returns an index starting at 0, and getPageLabels() returns labels associated with those indexes. Treating a label as an array offset conflates different values.

Follow the source-to-output mapping

The fixture's source labels were COVER, i, 1, 2, A-1, A-2. The intended policy for this check was to preserve each selected source page's label. Here is the observed mapping:

Output position	Source position	Label expected under preservation	Downloaded label
1	3	1	COVER
2	4	2	i
3	6	A-2	1

Both downloads reopened with three pages, and their complete extracted text matched the corresponding source pages. The input file's hash stayed unchanged. This establishes a label mismatch in that fixture, rather than a wrong-page selection or a modified source file.

The source and downloaded files also contained the same /PageLabels /Nums entries, including rules starting at source indexes 0, 1, 2, and 4. In this flat number-tree example, those rules were being interpreted against the new page sequence. The persisted dictionaries support that observation; they do not identify the exact writer function responsible for retaining the metadata.

Add the label policy to a small checker

The following read-only script expects readable PDFs and an ordered list of 1-based source positions. It checks a preservation policy: the output labels must equal the selected source labels. It is not a general PDF validator.

Save it as audit-labels.py. With Python and pypdf available, run it against your test files:

python audit-labels.py source.pdf subset.pdf 3 4 6

The positions are separate command-line arguments, not a hyphenated range string. The inspected example was run with pypdf 6.10.0. Its page_labels property returns labels in document order.

import argparse
import json
from pypdf import PdfReader

parser = argparse.ArgumentParser(
    description="Check a PDF subset against an ordered source-page selection."
)
parser.add_argument("source")
parser.add_argument("subset")
parser.add_argument("positions", nargs="+", type=int, help="1-based source positions")
args = parser.parse_args()

source = PdfReader(args.source)
subset = PdfReader(args.subset)
if any(n < 1 or n > len(source.pages) for n in args.positions):
    parser.error("Every source position must be between 1 and the source page count")

expected_text = [source.pages[n - 1].extract_text() for n in args.positions]
actual_text = [page.extract_text() for page in subset.pages]
text_available = all(t and t.strip() for t in expected_text + actual_text)
expected_labels = [source.page_labels[n - 1] for n in args.positions]
result = {
    "page_count_matches": len(subset.pages) == len(args.positions),
    "text_matches": expected_text == actual_text if text_available else None,
    "expected_labels": expected_labels,
    "actual_labels": subset.page_labels,
    "labels_match": expected_labels == subset.page_labels,
}
print(json.dumps(result, ensure_ascii=False, indent=2))
raise SystemExit(0 if all(result[k] is True for k in (
    "page_count_matches", "text_matches", "labels_match"
)) else 1)

For the actual failing download, the report was:

{
  "page_count_matches": true,
  "text_matches": true,
  "expected_labels": [
    "1",
    "2",
    "A-2"
  ],
  "actual_labels": [
    "COVER",
    "i",
    "1"
  ],
  "labels_match": false
}

The script exits 0 only if all three checks pass. Exit 1 means a mismatch or insufficient text evidence; invalid source positions are rejected by argparse with exit 2. A positive reference file with the selected labels passed. A reference with swapped pages failed, and source position 0 was rejected. These checks test the inspector, not a repaired production exporter.

A different numbering policy needs a different assertion

An excerpt might intentionally receive labels 1, 2, 3. That is a valid product choice if it is stated clearly. This preservation checker would reject that output by design; the mismatch does not make an otherwise readable PDF universally invalid.

Choose the policy before comparing results. If you preserve source labels, remap them to the output positions. If you renumber the excerpt, generate a new label sequence. Neither choice automatically changes the printed footer. Also avoid treating labels as unique identifiers: the extraction mapping should refer to source pages, not depend on labels being unique.

This fixture has selectable text. For a scan or a deliberately blank page, an empty extracted string is not evidence that the visual content survived; the checker reports text_matches: null when the text comparison is not informative. It does not verify rendering, bookmarks, links, forms, signatures, or accessibility structure. Those require their own checks.

The useful regression is a source-to-output mapping with separate expectations for content and labels. A correct page count is only one field in that mapping.

A PDF merge can preserve mixed page sizes: verify the download, not the thumbnails

Yan Wang — Fri, 23 Oct 2026 02:58:29 +0000

An A4 cover followed by a Letter report can be a correct merged PDF. A viewer may fit every page into the same window width, so a neat preview does not tell you whether the downloaded file kept each page's dimensions.

For a merger whose contract is “append these pages in this order,” a useful test is to start with different page sizes and check that they remain different. Making them uniform is a separate operation, with separate scaling and cropping choices.

AI disclosure: an AI agent prepared this article and performed the local checks. The case uses fictional plain-text documents and an actual browser download, reopened with pypdf and inspected with Poppler. It is a narrow acceptance check, not a claim about arbitrary PDFs.

Use a fixture that can expose accidental resizing

The test used two files: a one-page A4 cover and a two-page report whose pages were Letter and A4. Each page had a distinct text marker. The download was checked against the intended sequence: cover.pdf first, followed by both pages of report.pdf.

This is the expected output sequence. Dimensions are the actual MediaBox width and height in default PDF user-space units for these fixtures, rounded here to four decimal places.

Output page	Source file / page	Width × height
1	cover.pdf / 1	595.2756 × 841.8898
2	report.pdf / 1	612.0000 × 792.0000
3	report.pdf / 2	595.2756 × 841.8898

The sample pages have origin (0, 0), rotation 0, and UserUnit 1. In that case a unit is 1/72 inch. Do not generalize that assumption to every file: pypdf documents UserUnit as a multiplier of 1/72 inch.

Ask for information about every page

With Poppler installed and on your PATH, name your own downloaded test output merged.pdf and run:

pdfinfo -f 1 -l 3 -box merged.pdf

For a different fixture, change -l 3 to its last page number. The -f and -l pair matters: pdfinfo's manual says that without a multipage range, it examines page one for the page-size report. Checking only that page would miss the Letter page in the middle.

This is the size-and-rotation excerpt from the actual download, checked with Poppler on macOS:

Page    1 size:  595.276 x 841.89 pts (A4)
Page    1 rot:   0
Page    2 size:  612 x 792 pts (letter)
Page    2 rot:   0
Page    3 size:  595.276 x 841.89 pts (A4)
Page    3 rot:   0
File size:       2371 bytes

The -box output also includes MediaBox and CropBox. A width and height alone are not enough for files with offset boxes, cropping, rotation, or a non-default UserUnit. Compare those properties against the source page too, according to the behavior your merger promises. This fixture checks only zero-origin, unrotated pages with effective CropBox equal to MediaBox.

Check order separately from dimensions

Two pages can have identical dimensions and still be swapped. Use distinctive markers in a synthetic fixture, then inspect the extracted text:

pdftotext -layout merged.pdf -

The markers in this run appeared as COVER - START HERE, REPORT PAGE 1, and REPORT PAGE 2 - END, in that order. A separate pypdf comparison checked the complete extracted text of each output page against its corresponding source page. That is stronger than checking only the markers, but it still does not prove visual fidelity or semantic reading order for every document. Image-only scans may have no extractable text at all.

Render the saved file as another check

Create an output directory and render the same file:

mkdir -p check
pdftoppm -f 1 -l 3 -scale-to 1400 -png merged.pdf check/page

The PNGs are inspection copies. The scale limit controls those images; it does not rewrite the PDF's page dimensions. Inspect all pages for missing text, clipped edges, and unexpected blank areas, especially around the join between files. Open them as images rather than executing or otherwise trusting document content.

All pages of this fixture were also rendered and inspected during acceptance. No missing text or visible clipping was found in that small sample. The text and box comparisons are persisted evidence for this download, not a guarantee about another browser session or another file.

Keep resizing out of the merge contract unless it is requested

If a downstream system requires every page to be A4, describe that as normalization and define its behavior: preserve aspect ratio, fit or crop, page placement, and handling of rotation and boxes. pypdf's transformation guide treats changing content and changing page dimensions as distinct operations. Altering a box without applying the intended content transformation can hide content rather than fit it.

For a page-preserving merge, a practical regression assertion is an ordered list of source-page properties matched to output-page properties. Pair it with content and rendered-page checks. Do not use whole-file byte equality as the acceptance condition: a rewritten PDF can have different serialization while retaining the properties you need.

This run did not exercise forms, signatures, passwords, rotated pages, offset boxes, scanned images, or large batches. Those belong in their own fixtures. The small mixed-size case has a specific job: catch a merger that quietly substitutes one page size for all the others.