Project: bounded local scan analysis

Last updated: 7 Oct 20268 min read

project

Build a private document-review editor for reviewer 29. It loads a pinned processing module only after the reviewer chooses local analysis. A selected 47-megabyte scan stays in the browser unless the reviewer explicitly chooses a separate server path. The adapter validates dimensions, allocates bounded tiles, copies input into linear memory, copies output back before release, and refreshes any typed view after ordinary memory growth. Run processing in one worker. Each job carries a generation; if scan 62 replaces scan 47, the older result cannot overwrite the current editor. A cancellation request stops work between tiles, while a stuck synchronous export can be isolated by terminating its worker. Preserve the selected file and typed notes if binary delivery, compilation, worker startup, or allocation fails. A JavaScript fallback must produce the same output contract. Compare complete task latency, main-thread long tasks, peak memory, and fallback rate on a low-memory device before accepting the binary path.

Build contract

Pin adapter and binary versions and test a content-type or compilation failure.
Exercise memory growth, an allocation failure, and cleanup after cancellation.
Send two jobs in reverse completion order and keep only the latest selection.
Compare cold and warm total task time against the JavaScript fallback.

Implementation checkpoint

function visibleResult(activeGeneration, candidateGeneration, bytesReady) {
  return bytesReady && activeGeneration === candidateGeneration;
}
console.log(visibleResult(62, 47, true));
// Output: false

Cost and boundaries

The inner transform can be fast while download, decode, byte copies, and worker startup dominate user time. Tile processing costs O(n) bytes and bounds peak allocation; it does not eliminate the source and output buffers. One worker limits contention but can queue work. A transfer avoids a copy only when the sender can give up ownership. Track the whole interaction and retained bytes rather than a microbenchmark of one exported function.

Failure drill

Block the module request after a file is chosen and verify the editor preserves the file. Force a stale adapter version and show the fallback, not a blank panel. Grow memory between tile calls and refresh the view. Start scan 47, then scan 62; deliver scan 47 last and verify it is ignored. Crash the worker while a tile is allocated, then leave the page and inspect whether the worker, object URL, and buffer references have been released.

Acceptance checks

No unconsented upload occurs in the local path.
Old jobs cannot replace a newer result.
Failure keeps the review form recoverable.
Measured total time and memory justify the module.

Common Mistakes

Timing only an exported function.
Retaining a typed view after memory growth.
Assuming a cancellation message interrupts synchronous native work.

web-tech

web-development