@leumas/qr

The QR engine behind qr.leumas.tech: what text goes in a code, what it looks like, whether it will actually scan, and how it comes out as SVG, PDF or PNG.

Absorbs and replaces the payload builders that used to live inside shared/engines/adapters/domain/qr/index.js (themselves ported from leumas-middleware/lib/a.qr). That adapter now imports this package rather than keeping its own copy, so a fix to WIFI escaping lands everywhere at once.

The split, and why it matters

Everything on the barrel is pure and browser-safe. ./raster is the only subpath that touches sharp, and it is separate for the same reason @leumas/artwork splits ./dpi from ./prepare: a libvips binding of tens of megabytes must not sit on the boot path of a page that wanted a mailto: string.

The practical payoff is that the generator page renders a live, fully styled preview with no server call, and the download rasterises the same SVG string. Preview and export cannot drift, because they are one function.

generateSvg({payload, style}) runs the first five for the common case; generatePlan(…) stops one step earlier so a caller exporting three formats encodes once.

Payload types

url · text · wifi · email · tel · sms · geo · vcard · event · whatsapp · crypto · dynamic

dynamic is the commercial one. It builds <base>/api/qr/r/<code> — the short link whose destination stays editable after the code is printed. It is a builder rather than a string assembled at three call sites because the redirect route, the generator and the printed artwork must agree on that URL for ever; a printed code cannot be reissued when they drift.

There is deliberately no pay builder. A payment link is a plain URL whose shape differs per provider and changes without notice, and getting one wrong sends somebody's money nowhere. Build the URL you have verified and pass it to url. whatsapp and crypto are here because both have a published, stable URI scheme rather than a marketing URL that happens to work today.

[warning] crypto amounts are not one unit. BIP-21 (bitcoin: and friends) takes whole coins; EIP-681 (ethereum:) takes wei. This package passes each through unchanged and converts nothing — a form must label its own field.

Styling

Module shapes square · dot · rounded · diamond. Eye frames square · rounded · circle · leaf. Pupils square · dot · rounded. Plus flat or gradient foreground, per-eye colours, quiet zone, error-correction level, a centred logo, and a caption bar.

Four module shapes, not six, and none of them joins to its neighbours. The connected "classy" look every styling library ships needs each module to know which neighbours are filled, and gets subtly wrong results at the finder boundaries and the timing rows. Four that are exactly right beat six with two quietly deformed.

The readability check is the point

resolveStyle always returns a usable style plus a list of warnings — it never throws. Almost every bad style is still drawable: a pale code on white renders beautifully and no phone reads it; a logo over a third of the modules produces a lovely image that fails at the till. Throwing would block a preview the user is entitled to see; staying silent would ship the failure.

• low_contrast — error below 3:1, warning below 4.5:1.
• inverted — warning. Light-on-dark scans on modern phones and fails on older and industrial readers.
• logo_too_large — error above 25% width, where even level H starts to fail.
• quiet_zone_small — warning below the 4 modules ISO/IEC 18004 requires.
• ec_raised — informational: a logo silently raises error correction to H, because that repair has

no downside and forgetting it has a large one. It happens before encoding; raising it afterwards would change nothing.

scannable is false when any warning is an error. A save lane must read it.

Formats

• SVG — the vector deliverable, and what a printer wants.
• PDF — a real vector PDF, written here with no library: because ./plan.js emits only

rectangles-with-radii and polygons, every shape converts to Bézier operators with no loss. Gradients become PDF axial/radial shadings. A logo is omitted and reported as logoOmitted — embedding an arbitrary image means owning a PNG decoder or putting JPEG ringing on the hard edges a scanner samples. Export PNG or SVG for a logo'd code.

• PNG / JPEG / WebP — ./raster, via sharp rendering the SVG. rasterizeForPrint({mm, dpi})

sizes by physical width, because "2000px" says nothing about whether a module survives the press.

[warning] rasterize's density is the grid sharp rasterises the SVG at before scaling to width. Left low, a large width produces a big fuzzy image rather than a big sharp one — that is the actual cause of soft QR exports.

Tests

node --test test/ — 24 checks. The central one rasterises at an odd number of pixels per module, samples the centre of every module, and asserts the result is the source matrix, for every module shape and at all three finders. There is no QR decoder in this workspace, and adding one would test somebody else's library; what this package can get wrong is the drawing — a transposed matrix, an eye one module out, a shape that misses its own cell — and every one of those produces a plausible image that throws nothing.