The QR code that scans itself before you let it print

Every "artistic" QR code you have ever scanned was a gamble that happened to pay off. Someone dropped a logo in the middle, trusted the code's built-in error correction to absorb the damage, and printed 500 flyers without ever checking how close they cut it. Usually it reads. Sometimes, under a cheap phone camera in bad light, it does not, and there is no way to know which flyer you are holding until you point a camera at it.

QR Alchemist blends art into a QR code the same way those tools do, with one difference: it treats the error correction as a budget it is allowed to spend, tracks the spend to the codeword, and then decodes its own output to prove the code still reads before it ever shows you the result.

The error budget nobody counts

A QR code is not just a grid of black and white squares. Under the ISO/IEC 18004 standard, the data is encoded with Reed-Solomon error correction, the same family of math that keeps CDs playing through scratches. At a given version and error-correction level, the code can recover from a fixed, computable number of corrupted codewords. That is the whole trick behind center-logo QR codes: the logo corrupts some modules, and if the corruption stays under the recovery limit, the code still decodes.

The four EC levels spell out the budget. Level L recovers roughly 7% of the codewords, M about 15%, Q about 25%, and H about 30%. Pick H and nearly a third of the code can be wrong and it still reads. Most logo tools know this number exists and ignore it completely. They paste the logo, hope it landed under the limit, and ship.

QR Alchemist computes that limit exactly for your data and level, then treats it as money. It scores every module in the grid by how expendable it is. The finder patterns (the three big corner squares), the timing lines, the alignment blocks, and the format information are structural and never get touched. The remaining data modules get ranked, and the tool spends the budget greedily, blending your artwork into the cheapest-to-change modules first and stopping when the budget runs out. You get the most art the code can afford, and not one codeword more.

Theoretical is not the same as scannable

Here is the part that turns a clever idea into a shippable one. The Reed-Solomon budget is a theoretical limit. Real scanners are messier: a phone in a dim restaurant, a smudged print, a camera held at an angle all eat into margin that the math says you had. So spending exactly to the theoretical edge produces a code that decodes in a lab and fails on a table.

So QR Alchemist does not trust the math. After it blends, it runs the finished code back through a real Reed-Solomon-correcting decoder, hand-rolled in the same TypeScript as the encoder. If the decode fails, it backs the blend intensity down and tries again, shrinking the artwork's footprint until the code reads cleanly. The confidence badge under the preview reflects that actual decode, not an estimate. When it says the code scans, it is because the tool just scanned it.

Writing both halves from scratch was the point, not a flex. The whole engine is GF(256) field arithmetic, Reed-Solomon encode and decode, mask selection, and the blend, living in src/lib/qr/. A wrapper around some library's logo option could never do budget-aware blending, because it has no idea what the budget is. You have to own the decoder to check your own work.

The honest limit: the more art you push in, the more you lean on the backoff, and a code near the edge of its budget is still a code near the edge. QR Alchemist will tell you when you are there (that is what the badge is for), but it cannot conjure margin that the data density did not leave. Shorter URLs and level H buy you a bigger canvas. Everything runs client-side, so your artwork and your data never leave the browser tab.

Try it

Paste a link, drag the intensity slider, and drop in a PNG or SVG. Watch the confidence badge as you push the slider: at some point the blend backs itself off rather than lie to you, and that is the tool doing its one real job. Export a print-resolution PNG or a clean SVG when the badge is happy, and print your 500 flyers knowing the answer to "but does it scan?" before the ink dries.