We had a HEIC path. It was never tried, because the gate that decides whether to load the HEIC decoder was reading the filename.

Disclosure: this is from LensUp, which is ours. The fix is the boring one — read the bytes — but the interesting part is where naive byte-sniffing then went wrong, and the precedence rule we ended up needing.

How a HEIC ends up called .jpg

Nobody renames these on purpose. The path is mundane: an iPhone shoots HEIC, you share the photo through a messenger or copy it to a PC, and somewhere along the way the transport relabels it. The extension becomes .jpg, file.type becomes image/jpeg, and the container is still HEIC.

From the browser's side there is no hint of this. File.type is not derived from content — it is whatever the OS or the transport asserted. So:

// Cheap, synchronous gate so the page can decide whether to lazy-load the HEIC decoder
// module at all. Byte-level truth lives elsewhere — names and MIME lie often enough
// that this is only a candidate check, never a verdict.
export function isHeicCandidate(file) {
  const mime = file?.type?.toLowerCase();
  if (mime === 'image/heic' || mime === 'image/heif') return true;
  const extension = file?.name?.split('.').pop()?.toLowerCase();
  return extension === 'heic' || extension === 'heif';
}

That function is fine — as a hint for whether to lazy-load a wasm decoder you do not want to ship to everyone. It is not fine as the thing that decides which decoder runs. That was the bug: a hint had been promoted to a verdict.

Sniffing: twelve to sixteen bytes, never the file

The fix reads a small slice. Not the file — a slice:

const FTYP_READ_BYTES = 64;
export async function sniffInputSignature(file) {
  let head;
  try {
    head = new Uint8Array(await file.slice(0, FTYP_READ_BYTES).arrayBuffer());
  } catch { return null; }
  if (head.length < 4) return null;
  const ascii = (from, to) => String.fromCharCode(...head.subarray(from, Math.min(to, head.length)));

  if (head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff) return 'jpeg';
  if (head[0] === 0x89 && ascii(1, 4) === 'PNG') return 'png';
  if (ascii(0, 4) === 'GIF8') return 'gif';
  if (ascii(0, 4) === 'RIFF' && head.length >= 12 && ascii(8, 12) === 'WEBP') return 'webp';
  if (ascii(0, 2) === 'BM') return 'bmp';
  if (ascii(0, 4) === '%PDF') return 'pdf';
  // … TIFF (II*\0 / MM\0*), then the ISO-BMFF family below
}

Sixteen bytes covers every format the importer accepts, and file.slice() means the read is one small range request against the blob rather than a load of a 12-megapixel photo.

Where "just read the bytes" is not enough

ISO base media files — HEIC, HEIF, AVIF, MP4 and friends — all start the same way: bytes 4–8 spell ftyp, bytes 8–12 carry the major brand. So the naive version is: read the major brand, map heic → HEIC decoder, avif → native.

Then review found the hole. Two of those brands are generic:

const HEIC_BRANDS = new Set(['heic', 'heix', 'hevc', 'hevx', 'heim', 'heis', 'hevm', 'hevs']);
const AVIF_BRANDS = new Set(['avif', 'avis']);
const GENERIC_HEIF_BRANDS = new Set(['mif1', 'msf1']);

mif1 and msf1 mean "this is a HEIF container" and say nothing about the codec inside. An AVIF file may carry mif1 as its major brand and declare avif only further down, in the compatible-brands list. Treat mif1 as HEIC and you hand a file the browser decodes natively — losslessly, instantly — to a lossy wasm transcode. You have recompressed somebody's photo for no reason.

So a generic major brand gets resolved from the compatible brands, and the ftyp box is walked using its own declared size:

if (head.length >= 12 && ascii(4, 8) === 'ftyp') {
  const major = ascii(8, 12).trim().toLowerCase();
  if (HEIC_BRANDS.has(major)) return 'heic';
  if (AVIF_BRANDS.has(major)) return 'avif';
  if (GENERIC_HEIF_BRANDS.has(major)) {
    // ftyp box: [size:4]['ftyp'][major:4][minor version:4][compatible brands:4 each …]
    const boxSize = ((head[0] << 24) | (head[1] << 16) | (head[2] << 8) | head[3]) >>> 0;
    const end = Math.min(head.length, boxSize || head.length);
    const compatible = [];
    for (let offset = 16; offset + 4 <= end; offset += 4) {
      compatible.push(ascii(offset, offset + 4).trim().toLowerCase());
    }
    if (compatible.some((b) => AVIF_BRANDS.has(b))) return 'avif';
    if (compatible.some((b) => HEIC_BRANDS.has(b))) return 'heic';
    return 'heif';   // a HEIF container that names no codec
  }
}

Two details in there that are easy to skip. The box size is clamped with Math.min(head.length, …) so a bogus length cannot walk past the slice we actually read. And when no compatible brand is specific, the answer is the honest 'heif' — "a HEIF container, codec unknown" — rather than a guess.

The precedence rule: bytes win, the label breaks ties

"Always trust the bytes" is the slogan, and it is almost right. The generic-HEIF case is where it breaks: a file whose bytes only say heif could be a HEIC the browser cannot open, or something it can. There is no byte that settles it.

So the rule that shipped is narrower and, I think, the actually correct one: bytes win over the label; the label breaks ties only when the bytes say nothing.

export async function classifyInput(file) {
  const signature = await sniffInputSignature(file);
  const labelPdf  = isPdfCandidate(file);
  const labelHeic = isHeicCandidate(file);
  const labelTiff = isTiffCandidate(file);
  const isPdf  = signature === 'pdf'  || (labelPdf  && signature === null);
  const isHeic = !isPdf && (signature === 'heic' || (labelHeic && (signature === null || signature === 'heif')));
  const isTiff = !isPdf && !isHeic && (signature === 'tiff' || (labelTiff && signature === null));
  return { signature, isPdf, isHeic, isTiff, isImage: !isPdf && !isHeic && !isTiff,
           mislabelled: labelPdf && IMAGE_SIGNATURES.has(signature) };
}

Read the three interesting rows:

• scan.pdf whose bytes are a JPEG is an image, not a broken PDF. Before this, those went to the PDF parser and produced pdf_invalid: 39 of them between 09-06 and 09-11, most from Windows desktops retrying the same file over and over — the user's file was fine, our routing was not.

• IMG_0001.jpg whose bytes start with %PDF is a PDF. Same rule, other direction.

• A generic HEIF goes to the HEIC decoder only if the label agrees. signature === 'heif' && labelHeic → HEIC. A .jpg with those bytes stays on the native path, because that is the case where the label is the only evidence that exists.

One more lie: application/octet-stream

Worth its own line, because it is not a type:

// application/octet-stream is what browsers say when they do not know — treat it as
// undeclared so the extension map (and downstream byte sniffing) can decide.
if (declared && declared !== 'application/octet-stream') return declared;

Windows file pickers hand over .pdf files with an empty or application/octet-stream type often enough that treating it as a real MIME type poisons every branch downstream. It means "no opinion", and the code should say so.

The same file also needs a small alias table, because the same format arrives under several names: image/pjpeg, image/x-ms-bmp, image/x-png, image/jpg. Normalise first, decide second.

What I would take from this

A cheap label check and an expensive byte check are different functions and should be named differently. Our bug was one function doing both jobs — a lazy-load hint named like a verdict. isHeicCandidate and isHeicFile now sit next to each other with comments saying which is which, and that naming is doing more work than the sniffer is.

"Read the bytes" needs a tie-break rule, not just a preference. Some formats genuinely do not identify their own contents. Write the precedence down explicitly — bytes, then label, then a documented default — rather than letting it emerge from the order of your ifs.

Failures that are too fast are a routing smell. A decoder that gives up in 200 ms did not struggle with your file; it was handed the wrong file. That timing was the clue that pointed at the label, and it is the one I will look for first next time.

If you want to see the byte path do its thing, drop a HEIC — renamed or not — into a browser-based document scanner. It runs in the tab and files are never uploaded.

No corner detection. No straightening. No cropping. The output canvas keeps the exact width and height of the input, and the geometry contract is that nothing moves out of the frame. Disclosure: this is from LensUp, ours, and this piece is about the five small effects that do the work and the one bug that hid inside the first of them.

1. Tilt: never zero, never much, and never random

The single strongest cue that something was scanned is that it is slightly crooked. A page laid on a flatbed by a human hand is never perfectly square with the sensor. So:

/** The tilt a page gets: never zero (a scan is never perfectly square), never over 0.6°, and the
 *  same every time the same page renders so a re-render does not shuffle the result. */
export function scannedTilt(w, h) {
  const unit = scannedRandom(w * 131 + h * 71)() * 2 - 1;       // -1 … 1
  const degrees = Math.sign(unit || 1) * (0.25 + Math.abs(unit) * 0.35); // 0.25° … 0.6°
  return degrees * Math.PI / 180;
}

Three decisions in five lines.

Never zero. 0.25 + |unit| * 0.35 has a floor, so the tilt lands in 0.25°–0.6° and never in the middle. A page at exactly 0.00° reads as generated, because nothing physical is ever exactly anything.

Never much. Above roughly a degree it stops looking like a scanner and starts looking like a mistake.

Never Math.random(). This is the one I would have got wrong. The seed is w * 131 + h * 71 — the page's own dimensions — so the same page renders with the same tilt every single time. In a document tool, re-rendering is constant: the user toggles a setting, changes paper size, scrolls back. If the tilt reshuffles on every render, the preview shivers and the exported file does not match what was on screen. Determinism here is not a purity preference, it is the difference between a tool that feels solid and one that feels haunted.

2. The bug hiding in the tilt: rotating crops

Rotate a w × h image by any angle inside a w × h frame and the corners leave the frame. Everybody knows this in the abstract. At 0.6° it is easy to assume it is negligible.

It is not. Review caught it with a measurement: on a 1560 × 2200 page, a 0.6° tilt moved edge content 2–9 px out of frame. Nine pixels is a clipped page number, a truncated signature line, the last character of a table cell — on a document, silently.

The fix is the rotated bounding box:

/** The uniform scale that keeps a w×h page rotated by `angle` entirely inside a w×h frame: the
 *  rotated bounding box is w·cos+h·sin by w·sin+h·cos, and the page shrinks by the tighter ratio.
 *  For the tilts in use (≤ 0.6°) that is 0.98–0.995 — a hair of paper margin, never a crop. */
export function scannedFit(w, h, angle) {
  const c = Math.abs(Math.cos(angle)), s = Math.abs(Math.sin(angle));
  return Math.min(w / (w * c + h * s), h / (w * s + h * c), 1);
}

Scale down by 0.98–0.995 before drawing, and the page corners land on paper-white margin instead of outside the canvas. That is also more realistic, not less: a scan of a page has a sliver of platen around it.

The Math.min(..., 1) clamp matters too — it guarantees the function can only ever shrink, so a future angle of 0 cannot accidentally enlarge and re-introduce the crop.

3. The pixel pass, and the one term that sells it

The geometry is half the effect. The rest is a single pass over the pixels:

const vignette = 1 - 0.08 * (dx * dx + dy * dy);
let g = 0.299 * pixels[i] + 0.587 * pixels[i+1] + 0.114 * pixels[i+2];
g = 20 + g * 0.9;                             // lifted blacks, paper not quite white
g = 128 + (g - 128) * 0.94;                   // softened contrast
g = g * vignette + (random() - 0.5) * 14;     // vignette + grain
const warmth = Math.max(0, (g - 150) / 105);  // paper takes the tint, ink does not
const r = g + 2 * warmth, gr = g, b = g - 7 * warmth;

Four of these are the obvious ones. Lifted blacks (20 + g * 0.9): a scanner never returns 0, and paper is never 255. Softened contrast (×0.94 around mid-grey): optics are not a renderer. Vignette, 8 % toward the corners. Grain, ±7 levels.

The fifth line is the one that makes it work, and it is the one I would have written wrong:

const warmth = Math.max(0, (g - 150) / 105);

The naive way to warm a scan is a global sepia tint — add red, remove blue, everywhere. It looks instantly fake, and it took me a while to articulate why: a real scanner warms the paper, not the ink. The warm cast comes from the platen lamp reflecting off the sheet; black toner reflects almost nothing, so it stays neutral.

So the tint is gated on brightness. Below 150 there is no warmth at all; from 150 to 255 it ramps to full. Ink keeps its neutral grey, the paper goes cream, and the result stops looking like a filter.

4. Reproducible grain

Grain needs randomness, and the determinism requirement from section 1 applies to it too. So the noise comes from a seeded PRNG — mulberry32, nine lines, no dependency:

function scannedRandom(seed) {
  let a = seed >>> 0;
  return () => {
    a = (a + 0x6D2B79F5) >>> 0;
    let t = a;
    t = Math.imul(t ^ (t >>> 15), t | 1);
    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

Seeded per page as w * 31 + h * 17, so the grain pattern is stable across re-renders, and the pixel function is pure: scannedLookPixels(pixels, w, h, seed) takes a buffer and a seed and returns the same buffer every time. That makes it directly unit-testable, which a canvas effect otherwise is not.

5. Where this stops

It is worth being exact about the limit, because this category attracts products that are not exact about it.

Text becomes pixels. That is the entire point of the effect — a flattened page is what a scan is — and it is also its cost: the output is an image-based PDF, and text in it is no longer selectable. That belongs in the limitations, not in the fine print.

And the effect changes how a page looks, nothing else. It does not sign anything, date anything, certify anything, or make a file into an original. If a form asks for a signed and scanned copy, the requirement is about the signature: sign the page, then scan or photograph it. Presentation and content are different layers, and the honest version of this tool is the one that only touches the first.

The legitimate reasons to want it are mundane and real: upload portals that accept only image PDFs and reject a text PDF with identical content; an archive of real scans where one crisp vector page looks out of place; a page that should not be quietly editable afterwards. In all of those the content is unchanged and true, and only the presentation matches what the receiver expects.

The part I would take elsewhere

Two things generalise beyond making pages look scanned.

Deterministic "randomness" is usually what you want in a document pipeline. Anything the user might re-render should look identical when it does. Seed from the content's own dimensions and the problem disappears.

Small rotations crop. If you rotate any raster inside a fixed frame and do not compute the rotated bounding box, you are losing edge pixels — a handful at a fraction of a degree, which is exactly the amount nobody checks for and a document cannot afford.

If you want to see the effect on a page of your own, it is at a PDF-to-scanned-PDF converter — it runs in the tab and files are never uploaded, so the Network panel is a fair way to check that.

We do that client-side, in a browser tab, on a grayscale copy of the photo scaled to a long edge of 640 px. The pipeline is the textbook one:

grayscale → blur → Sobel → adaptive edge map → Hough lines → best convex quad

Two near-horizontal lines, two near-vertical lines, score every candidate quadrilateral, keep the best. Disclosure up front: this is from LensUp, which is ours. What follows is the part where the textbook pipeline quietly failed, and the one-line change that nearly doubled how often it works.

The failure: the page fills the frame and detection gets worse

The adaptive edge threshold is the standard trick. Take the histogram of Sobel magnitudes, pick the 90th percentile, call everything above it an edge. It adapts to lighting, exposure and camera noise for free.

It also has a property nobody mentions: it is set by whatever has the strongest gradients in the image. On a photo of a document, that is not the page border. It is the letter strokes. Printed text is black-on-white at high spatial frequency — it produces the sharpest gradients in the frame by a wide margin.

The paper-to-desk step, meanwhile, is weak. Measured on SmartDoc 2015, a page lying on light wood clears the surrounding surface by roughly 14 luma levels. That is the signal you actually need, and it is an order of magnitude quieter than the text sitting in the middle of it.

So the adaptive threshold, doing exactly what it was designed to do, sets itself by the text and prices the page border out of the edge map. And it does this worst in the case you most want to work: when the user fills the frame with the page, so text dominates the histogram and there is barely any desk left to argue for a lower threshold.

The fix is not clever. Cap it:

edgePercentile: 0.9,     // gradient magnitudes above this percentile are edges …
minEdgeMagnitude: 14,    // … but never below this …
maxEdgeThreshold: 30,    // … and never above this: print must not price the page edge out

Measured on 300 real frames, with every other guard unchanged:

An adaptive threshold with a hard ceiling is no longer fully adaptive, which felt wrong when we wrote it. It is also the single highest-value line in the file.

Telling paper from a block of printed text

Capping the threshold gets the page border back into the edge map. It also lets a lot of rectangles in that are not pages — and the most dangerous one is a dark block of printed text, because it is genuinely a bright-surrounded rectangle with strong edges.

The first instinct is a contrast magnitude: require the inside of the quad to be meaningfully brighter than the outside. We had that set at 14 gray levels, which is the median paper-on-light-wood step from above.

That was the wrong knob. A threshold at the median of true pages rejects about half of the true pages. What actually discriminates is not how big the step is but which way it points:

minContrast: 8,   // 40th percentile of (inside − outside) across each side, in gray levels.
                  // A page on light wood measures 14 at the median, so 14 rejected half of them;
                  // the polarity rule is what keeps text blocks out, not this magnitude.

The polarity rule is the actual test: a quad is a page only if it is brighter inside than outside, sampled at two depths, on all four sides. A text block fails that on the sides where more text continues past it. A page on a desk passes it everywhere.

There is still a case that beats local evidence: a large dark region of print can look like "the desk" if you only sample a few pixels out. So before applying a detection automatically — as opposed to just pre-positioning the handles — we probe farther outside, looking for the page continuing past that edge. If the page continues, the edge was not the page edge.

The guards that are product decisions wearing algorithm clothes

Three of the constants in that file are not computer vision. They are decisions about what to do when we are unsure, and they are the ones I would port to any similar project:

borderMargin: 0.02,        // a side within 2% of the frame edge is "on the border"
applyMinAreaRatio: 0.25,   // a smaller page is only proposed, never applied
minSideSupport: 0.42,      // every side needs this much edge support to be applied

A quad with a side lying on the image border is rejected. If the "page edge" is the edge of the photo, the page is not fully inside the frame, and the honest default is the whole frame rather than a crop that silently cuts off whatever was outside it.

The largest well-supported quad wins. This sounds like a tie-breaker and is actually a correctness rule: it makes an inner rectangle — a photo printed on the page, a bordered table — lose to the page around it.

Below a quarter of the frame, a detection is only a proposal. It pre-positions the four draggable handles and waits. Auto-applying a small quad is how you produce the single worst outcome in this whole category: a confident crop that removes two thirds of somebody's passport.

That last one generalises. The result of this module is a proposal and never the truth; every handle stays draggable, and the caller decides from a confidence value whether to apply it silently. When detection fails outright it returns null, and null means keep the entire original image. A scanner that crops wrong is worse than a scanner that does not crop.

Two features that ship turned off

weakEdgeRecovery: 0,   // Experimental: desktop cost is not yet justified by coverage gains.
contourRecovery: 0,    // Correct proposals improved, but the measured latency gate failed.

Both of these work. Both improve the numbers. Both are disabled in the shipped defaults because they did not clear a latency budget on the hardware people actually hold. Leaving them in the file at 0, with the reason written next to them, has been more useful than deleting them — the next person to look at this does not have to rediscover that the idea was tried and why it is not on.

What I would take away from this

The general shape of the bug is worth more than the specific fix: an adaptive parameter adapts to the strongest thing in your input, and the strongest thing is often not your signal. Text beats page borders. Specular highlights beat document edges. The loudest object in the frame sets your threshold, and if your target is quiet, it gets deleted.

When an adaptive method underperforms, it is worth checking whether it is adapting to something you did not intend before reaching for a better algorithm. In our case the better algorithm was a ceiling of 30.

If you want to watch this run on your own photo, it is at a browser-based document scanner — the detection happens in the tab and your files are never uploaded, so the Network panel is a fair way to check that claim.

I work on LensUp, which does exactly that — the whole pipeline runs in the tab, and files are never uploaded. Disclosure up front: it's our tool, and this post is about the parts that were harder than the pipeline itself. None of the three below are in the "how to draw an image to a canvas" tutorials, and all three cost us real debugging time.

1. Web Share can be gone by the time your file is ready

The Web Share API's file variant is the nicest way to hand a generated PDF to whatever the user actually wants to do with it. The naive version looks fine:

shareButton.addEventListener('click', async () => {
  const bytes = await buildPdf(pages);           // takes a while
  const file = new File([bytes], 'scan.pdf', { type: 'application/pdf' });
  await navigator.share({ files: [file] });      // 💥 NotAllowedError
});

navigator.share() requires transient user activation, and transient activation expires. Building a multi-page PDF from full-resolution photos on a mid-range phone takes long enough that by the time you call share(), the activation from the tap is gone. You get a NotAllowedError, the share sheet never opens, and it only reproduces on slow devices — which is the worst possible failure profile.

There is no way to extend the activation. What you can do is decouple "prepare" from "share", and check whether you still have activation before deciding which one you're doing:

let preparedShare = null;  // { file, identity }

shareButton.addEventListener('click', async () => {
  let file;
  if (preparedShare && sameOutputIdentity(preparedShare.identity, snapshotOutputIdentity())) {
    file = preparedShare.file;                   // second tap: no await before share()
  } else {
    preparedShare = null;
    const { pages, settings } = await prepareCurrentOutputPages('share');
    const bytes = await buildPdf(pages, settings);
    file = new File([bytes], `scan-${Date.now()}.pdf`, { type: 'application/pdf' });
    preparedShare = { file, identity: settings.identity };

    // A long render may outlive transient user activation. The next tap shares
    // the prepared file synchronously, only while its content/settings still match.
    if (navigator.userActivation?.isActive === false) {
      toast('Your file is ready — tap share again');
      return;
    }
  }
  await navigator.share({ files: [file], title, text });
  preparedShare = null;
});

navigator.userActivation.isActive is the part worth knowing about. It lets you tell the difference between "this will work" and "this will throw", so you can degrade to an honest two-tap flow instead of showing an error for something the user did nothing wrong in. On a fast device the second tap never happens; on a slow one the user gets a clear "ready, tap again" instead of a failure.

Two details that go with it.

Feature-detect the file variant, not the API. 'share' in navigator tells you nothing about whether files can be shared — that support is separate, and it varies. The only honest probe is to build a real File of the type you intend to send and ask:

const canShareFiles = (() => {
  try {
    const f = new File([new Uint8Array([37, 80, 68, 70])], 't.pdf', { type: 'application/pdf' });
    return !!(navigator.canShare && navigator.canShare({ files: [f] }));
  } catch {
    return false;
  }
})();
if (!canShareFiles) shareButton.hidden = true;

Those four bytes are %PDF. Building the probe file from the real MIME type matters, because canShare can accept one type and refuse another.

AbortError is not an error. When the user opens the share sheet and dismisses it, share() rejects with AbortError. If you surface that as a toast, you are telling people something failed when they simply changed their mind:

} catch (err) {
  if (!err || err.name !== 'AbortError') {
    showShareFailed(err);
  }
}

2. One worker per image beat a worker pool

Finding the page corners in a photo — the geometry that turns a trapezoid back into a rectangle — is the one genuinely CPU-heavy step, and it has no business on the main thread while someone is trying to scroll.

The obvious architecture is a long-lived worker (or a small pool) plus request IDs, so you can match a response to the request that asked for it. We ended up with the opposite: spawn a worker for one image, then terminate it.

export async function detectQuadFromBlob(blob, options = {}) {
  if (!blob || options.signal?.aborted) return null;

  // A worker owns only this image. Completion, cancellation and timeout all release
  // its bitmap/heap; older requests cannot deliver a later request's result.
  if (typeof window !== 'undefined'
      && typeof Worker === 'function'
      && typeof OffscreenCanvas === 'function') {
    let worker;
    try {
      worker = new Worker(new URL('../workers/quad-detect-worker.js', import.meta.url),
                          { type: 'module' });
    } catch {
      /* CSP / unsupported module worker: fall through to the local path. */
    }
    if (worker) return new Promise(resolve => {
      const { signal, ...settings } = options;
      let done = false;
      const finish = value => {
        if (done) return;
        done = true;
        clearTimeout(timer);
        signal?.removeEventListener('abort', abort);
        worker.terminate();
        resolve(value);
      };
      const abort = () => finish(null);
      const timer = setTimeout(abort, 10000);
      const fallback = () => { if (!done) finish(detectLocal(blob, options)); };

      worker.onmessage = e => finish(e.data?.detection ?? null);
      worker.onerror = fallback;
      worker.onmessageerror = fallback;
      signal?.addEventListener('abort', abort, { once: true });
      if (signal?.aborted) { abort(); return; }
      try { worker.postMessage({ blob, options: settings }); } catch { fallback(); }
    });
  }
  return detectLocal(blob, options);
}

Three reasons this turned out better for this particular job:

Stale results become structurally impossible. With a shared worker, a response from the image the user already replaced can arrive after you've moved on, and you are one forgotten ID comparison away from cropping photo B by photo A's corners. Terminating the worker deletes that bug class instead of guarding against it.

Memory releases deterministically. A decoded ImageBitmap from a 12-megapixel photo is tens of megabytes. terminate() takes the whole worker heap with it, which is a much shorter argument than reasoning about when the bitmap becomes unreachable inside a worker that keeps running. The worker side still closes it explicitly, because the tab may be doing several things at once:

self.onmessage = async ({ data }) => {
  let bitmap;
  try {
    bitmap = await createImageBitmap(data.blob);
    self.postMessage({ detection: detectQuadFromSource(bitmap, data.options) });
  } catch {
    // The importer keeps the full original image on every detection failure.
    self.postMessage({ detection: null });
  } finally {
    bitmap?.close();
  }
};

Cancellation is just terminate(). No cooperative abort checks inside the detection loop, no message protocol for "never mind".

The cost is real — you pay worker startup per image, and on a cold module worker that is not free. For a user importing a handful of pages, that cost is invisible; if you were detecting corners on a video stream at 30fps, you would want the pool and the request IDs.

Note what the failure path does: every error resolves to null, and null means keep the full original image. A scanner that crops wrong is worse than a scanner that doesn't crop, so the degraded state is "you get your whole photo" rather than "you get two thirds of your passport".

3. "Compress to 200 KB" is a search problem, not a setting

Government portals and university systems love a hard byte ceiling: PDF, under 200 KB, colour, A4. Developers see that requirement and go looking for the quality parameter that produces 200 KB.

There isn't one. The size of an encoded JPEG is a function of the image content as much as the quality setting — a dense page of small text and a mostly-white form at the same quality can differ several-fold. The only thing you can do is encode, measure, and step:

async function encodeTowardTarget(canvas, targetBytes) {
  let best = null;
  for (const q of [0.92, 0.85, 0.78, 0.7, 0.6, 0.5, 0.42, 0.35]) {
    const blob = await new Promise(r => canvas.toBlob(r, 'image/jpeg', q));
    best = blob;
    if (blob.size <= targetBytes) break;   // first one that fits wins
  }
  return best;                              // may still exceed the target
}

Two things follow from that, and both are product decisions rather than technical ones.

The loop has to terminate somewhere, which means the result can still be over the ceiling. You either keep degrading until the page is unreadable, or you stop and hand back something too big. We stop, which makes this a best-effort operation — and if you are building something similar, say that in your UI. Telling a user you will hit an exact byte count is a promise the format does not let you keep.

And if you are the one filling in the form: check the file, don't trust the label. A tool that claims an exact size is either lying or about to destroy your document's legibility.

The part that is genuinely easier client-side

For all three of the above, the reward is worth it. The documents people scan are passports, signed contracts, medical forms, payslips — the most sensitive paper most people own. Doing the work in the tab means the server only ever ships HTML, JavaScript and translations; it never receives a pixel of the document.

That claim is also checkable, which is the main thing I'd push for in this category: open DevTools → Network, clear the log, scan something, export it, and watch whether your file's bytes leave. If a "client-side" claim is real, the Network tab shows it. If it isn't, you'll see a POST with your document in it. Worth doing to any tool that touches your paperwork — including ours.

If you want to poke at the implementation described above, it's running at a browser-based document scanner.