@saeris/hanko 0.0.0 → 0.2.0

package/dist/scan/index.d.mts

@@ -0,0 +1,381 @@
+import { a as createQrDecoder, c as GrayImage, i as QrDecoderOptions, l as Point, n as DecodeResponse, o as BitMatrix, r as serveDecoder, s as DecodedSymbol, t as DecodeRequest, u as SymbolDecoder } from "../worker-DxbdBA2z.mjs";
+//#region src/scan/qr/progressive.d.ts
+/** A scanner that improves its effort as frames arrive. */
+interface ProgressiveScanner {
+  /**
+   * Offer one frame.
+   *
+   * Returns a symbol as soon as one is read, and `null` otherwise — including
+   * while effort is still ramping up.
+   */
+  scan(image: GrayImage): DecodedSymbol | null;
+  /**
+   * Reset the effort ramp.
+   *
+   * Call when the scene changes — a new code presented, the camera moved
+   * somewhere else — so the next frame starts cheap again rather than
+   * inheriting effort earned by a symbol that is no longer there.
+   */
+  reset(): void;
+  /** How much effort the next frame will receive, in milliseconds. */
+  readonly budgetMs: number;
+}
+/** Options for {@link createProgressiveScanner}. */
+interface ProgressiveOptions extends Omit<QrDecoderOptions, `timeBudgetMs`> {
+  /**
+   * Budget for the first frame, in milliseconds.
+   *
+   * Deliberately small. Most frames a camera delivers contain no code at all,
+   * and this is what every one of them costs.
+   */
+  initialBudgetMs?: number;
+  /**
+   * Ceiling on the per-frame budget.
+   *
+   * 400ms by default: beyond that a single frame stalls the preview
+   * noticeably, and at 30fps the ladder has had a dozen frames to work with
+   * by the time the ramp reaches it.
+   */
+  maxBudgetMs?: number;
+  /**
+   * How much the budget grows per consecutive frame that shows a symbol.
+   *
+   * Growth is conditional on there being something to find: a frame with no
+   * finder candidate at all should not earn the next frame more time, or a
+   * camera pointed at a wall would ramp to its ceiling and stay there.
+   */
+  growth?: number;
+}
+/**
+ * Create a scanner that spreads decoding effort across frames.
+ *
+ * The ramp is driven by evidence rather than by a timer. A frame in which the
+ * decoder finds nothing resets it, because nothing is there to spend effort
+ * on; a frame that finds a symbol but cannot read it raises the budget,
+ * because that is exactly the case where more effort pays.
+ */
+declare const createProgressiveScanner: ({ initialBudgetMs, maxBudgetMs, growth, ...decoderOptions }?: ProgressiveOptions) => ProgressiveScanner;
+/**
+ * Drive a decoder running in a worker.
+ *
+ * Same shape as {@link createProgressiveScanner} but asynchronous, because
+ * the work happens elsewhere. The main thread stays free: measured on a hard
+ * frame, an in-thread decode blocks 208ms at a 40ms budget and 481ms at
+ * 400ms, which at 60fps is 12 and 28 dropped frames respectively — a visible
+ * freeze on exactly the frames where someone is lining up a shot.
+ *
+ * Frames offered while a decode is in flight are DROPPED rather than queued.
+ * A camera produces frames faster than they can be decoded, and a queue would
+ * grow without bound while returning increasingly stale results; the next
+ * frame is always a better input than a backlogged one.
+ */
+interface WorkerScanner {
+  /** Offer a frame. Resolves `null` if dropped, still ramping, or unreadable. */
+  scan(image: GrayImage): Promise<DecodedSymbol | null>;
+  /** Reset the effort ramp — call when the scene changes. */
+  reset(): void;
+  /** Stop the worker and release it. */
+  close(): void;
+  /** Whether a decode is currently in flight. */
+  readonly busy: boolean;
+}
+/**
+ * Wrap a worker in the progressive interface.
+ *
+ * The worker is supplied rather than constructed here, because how a worker
+ * is created is a bundler question — `new Worker(new URL(...), { type:
+ * "module" })` in Vite, a blob URL elsewhere — and a library that guessed
+ * would be wrong for most consumers.
+ */
+declare const createWorkerScanner: (worker: {
+  postMessage: (message: unknown, transfer?: ArrayBufferLike[]) => void;
+  addEventListener?: (type: string, listener: (event: {
+    data: unknown;
+  }) => void) => void;
+  on?: (type: string, listener: (message: unknown) => void) => void;
+  terminate?: () => void;
+}, { initialBudgetMs, maxBudgetMs, growth }?: ProgressiveOptions) => WorkerScanner;
+//#endregion
+//#region src/scan/qr/locate.d.ts
+/** A located finder pattern. */
+interface FinderPattern {
+  readonly center: Point;
+  /** Estimated module size in pixels, from the pattern's own width. */
+  readonly moduleSize: number;
+}
+/**
+ * Drop candidates that have no clear space around them.
+ *
+ * Returns the original list when filtering would leave fewer than three, so a
+ * symbol photographed without its full quiet zone — against a dark table
+ * edge, say — is never made undecodable by this check.
+ */
+declare const withClearance: (matrix: BitMatrix, patterns: readonly FinderPattern[]) => FinderPattern[];
+//#endregion
+//#region src/scan/binarize.d.ts
+/** Convert RGBA pixels to greyscale using perceptual luminance weights. */
+declare const toGray: (rgba: Uint8ClampedArray, width: number, height: number) => GrayImage;
+/**
+ * Binarize against one threshold chosen from the whole image's histogram.
+ *
+ * The opposite trade to {@link binarize}. A single threshold cannot follow a
+ * shadow across a page — which is why local thresholding exists and why it
+ * takes the `brightness` and `monitor` categories from nothing to something.
+ * But local thresholding invents structure in flat regions, and on a clean,
+ * evenly-lit image a global threshold is both more faithful and less prone to
+ * that.
+ *
+ * Neither dominates, so this is a retry rather than a replacement. zxing-cpp
+ * reached the same conclusion from the other direction: its issue #809 is an
+ * image its local binarizer cannot read and its global one can, and its
+ * issue #500 is a prototype for supporting several binarizers for exactly
+ * this reason.
+ *
+ * The threshold is the midpoint between the two dominant peaks of the
+ * histogram rather than the mean. A QR is mostly two tones, so the histogram
+ * is bimodal, and the mean of a symbol with more light area than dark sits
+ * inside the light peak and thresholds half the modules away.
+ */
+declare const binarizeGlobal: (image: GrayImage, { invert }?: {
+  invert?: boolean;
+}) => BitMatrix;
+/**
+ * Morphological closing on a bit matrix — dilate, then erode.
+ *
+ * Fills small light specks inside dark regions while leaving real structure
+ * intact, because dilation closes a gap smaller than the kernel and the
+ * following erosion restores every boundary the dilation moved.
+ *
+ * The failure this targets is specific: zxing-cpp issue #951 diagnoses an
+ * undetected symbol as "white pixels inside the black square that disrupt
+ * their detection" of the finder patterns, and its remedy is exactly this
+ * operation. Speckle inside a finder breaks the run-length signature — a
+ * single light pixel splits one dark run into two — so the pattern stops
+ * matching 1:1:3:1:1 even though a human sees it perfectly well.
+ *
+ * A 3x3 kernel: large enough for sensor speckle and dust, small enough that
+ * it cannot close a real one-module gap at any usable resolution.
+ */
+declare const close: (matrix: BitMatrix) => BitMatrix;
+/**
+ * Downscale by box-averaging whole blocks of pixels.
+ *
+ * Not for speed — for signal. A symbol photographed from a distance on a
+ * 12-megapixel sensor has modules two or three pixels wide, and at that scale
+ * neither run-length scanning nor shape detection produces reliable
+ * structure: measured on the corpus, both detectors return module-size
+ * estimates spanning 1.1 to 137.9 pixels within a single image, which is
+ * noise rather than measurement.
+ *
+ * Averaging blocks of pixels down trades resolution the symbol does not have
+ * for a cleaner signal it does. BoofCV builds an image pyramid for the same
+ * reason and scores 100% on that corpus category.
+ *
+ * Box averaging rather than nearest-neighbour sampling, because dropping
+ * pixels aliases a module grid badly — the very structure being looked for
+ * beats against the sampling lattice.
+ */
+declare const downscale: (image: GrayImage, factor: number) => GrayImage;
+/**
+ * Blur an image with a separable box filter, approximating a Gaussian.
+ *
+ * Two passes of a box filter — one horizontal, one vertical — is a standard
+ * cheap stand-in for a true Gaussian, and it is separable, so cost is linear
+ * in radius rather than quadratic.
+ *
+ * This exists for one specific failure: photographing a screen. Moire banding
+ * is frequency ALIASING between the camera sensor grid and the display's
+ * sub-pixel grid, so the interference sits at a much higher spatial frequency
+ * than the modules do. Low-pass filtering suppresses the banding and leaves
+ * the modules — measured on the benchmark corpus, it takes the `monitor`
+ * category from 0 of 25 to 10 of 25.
+ *
+ * It is NOT a free win and must not be applied by default: the same filter
+ * takes `blurred` from 5 of 14 down to 1, and `nominal` from 3 to 0. A blurred
+ * photograph blurred again is unreadable. Use it as a retry after a sharp
+ * pass fails.
+ */
+declare const blur: (image: GrayImage, radius: number) => GrayImage;
+/**
+ * Binarize a greyscale image into a bit matrix.
+ *
+ * `true` (1) means DARK, matching the QR convention where a set module is a
+ * dark one. Fixing polarity here — at the single boundary where pixels become
+ * bits — is deliberate: every stage above this one can then assume one
+ * orientation, and none of them has to ask which way round the image was.
+ *
+ * @param invert Treat light modules as set. Needed for symbols rendered
+ *   light-on-dark, which decoders that assume dark-on-light read as nothing at
+ *   all. Callers that do not know should try both.
+ */
+declare const binarize: (image: GrayImage, { invert }?: {
+  invert?: boolean;
+}) => BitMatrix;
+//#endregion
+//#region src/scan/qr/format.d.ts
+/** Error-correction level, in the order the format field encodes them. */
+type ErrorCorrectionLevel = `L` | `M` | `Q` | `H`;
+//#endregion
+//#region src/scan/qr/decode-matrix.d.ts
+/** What a successful matrix decode yields. */
+interface MatrixDecodeResult {
+  readonly value: string;
+  readonly version: number;
+  readonly errorCorrectionLevel: ErrorCorrectionLevel;
+  readonly mask: number;
+}
+/**
+ * Decode a bit matrix into the text it encodes.
+ *
+ * Returns `null` for anything unreadable. Every failure here is a normal
+ * outcome rather than an exception: a camera sees far more non-symbols than
+ * symbols, and a decoder that threw on each one would make its callers write
+ * try/catch around their hot loop.
+ */
+declare const decodeMatrix: (matrix: BitMatrix,
+/**
+ * Modules the imaging layer could not read confidently, as a mask the same
+ * shape as `matrix` where 1 marks "do not trust this".
+ *
+ * Reed-Solomon corrects twice as many codewords when it is told WHERE the
+ * damage is: the bound is `2 * errors + erasures <= check codewords`. A
+ * region blown out by glare or crushed by shadow is visibly untrustworthy,
+ * and thresholding it into a confident bit throws that away. Measured on a
+ * version 3 symbol at ecM, a blob covering 15% of the area decodes 0% of the
+ * time as errors and 100% as erasures.
+ *
+ * Optional because it costs a per-frame allocation the ordinary path does
+ * not need, and because a decoder handed no mask must behave exactly as it
+ * did before.
+ */
+unreliable?: Uint8Array) => MatrixDecodeResult | null;
+//#endregion
+//#region src/scan/qr/sample.d.ts
+/**
+ * A projective (homography) transform between two quadrilaterals.
+ *
+ * Affine is not enough. An affine transform preserves parallel lines, and
+ * perspective does not — the far edge of a tilted square is genuinely shorter
+ * than the near one. Only a projective transform models that, which is why
+ * this carries the two extra terms an affine matrix lacks.
+ */
+interface Transform {
+  readonly a11: number;
+  readonly a12: number;
+  readonly a13: number;
+  readonly a21: number;
+  readonly a22: number;
+  readonly a23: number;
+  readonly a31: number;
+  readonly a32: number;
+  readonly a33: number;
+}
+//#endregion
+//#region src/scan/gpu.d.ts
+/** Scores many transforms against one image, on the GPU. */
+interface GpuScorer {
+  score(image: BitMatrix, transforms: readonly Transform[], size: number, alignmentCenters: readonly number[]): Promise<Int32Array>;
+  destroy(): void;
+}
+/** Whether this runtime exposes WebGPU at all. */
+declare const hasWebGpu: () => boolean;
+/**
+ * Create a GPU scorer, or `null` where WebGPU is unavailable.
+ *
+ * Returns `null` rather than throwing: every caller must have a CPU path
+ * anyway, so an absent GPU is a normal condition and not an error.
+ */
+declare const createGpuScorer: () => Promise<GpuScorer | null>;
+//#endregion
+//#region src/scan/machine.d.ts
+/**
+ * A scan session, as a state machine.
+ *
+ * Modeled the way `machine.ts` models the device flow: states, events, and a
+ * declarative transition table, hand-rolled so this stays dependency-free.
+ *
+ * Deliberately NOT applied to the decode pipeline itself. Binarize → locate →
+ * extract → decode is a fallible sequential pipeline, not a machine: each
+ * stage runs once per frame and either produces a value or does not. Modeling
+ * it as states would add ceremony without making a single illegal move
+ * impossible, which is the only thing a transition table buys.
+ *
+ * What IS a machine is the session around it — permission, camera lifecycle,
+ * pause and resume — and that part is identical whether the frames are being
+ * searched for a QR, a DataMatrix, or an Aztec code. So it lives here,
+ * symbology-agnostic, and the decoders plug into it.
+ */
+/**
+ * Lifecycle of one scanning session.
+ *
+ * `scanning` is the only state that consumes frames. `decoded` is terminal
+ * rather than a return to `scanning`: a scanner that kept reading after a
+ * successful decode would fire twice on the same symbol, and every consumer
+ * would have to debounce it. Restarting is explicit.
+ *
+ * `denied` is separate from `failed` because they are different conversations
+ * with the user — one asks them to change a browser setting, the other is a
+ * fault they cannot act on. Collapsing them is how a permission prompt ends up
+ * reported as "something went wrong".
+ */
+type ScanState = `idle` | `starting` | `scanning` | `paused` | `decoded` | `denied` | `failed` | `stopped`;
+/** Why a scan session ended without a result. */
+type ScanFailure =
+/** No camera on this device, or none matching the requested facing mode. */
+`no-camera` |
+/** The page is not a secure context, so `getUserMedia` is unavailable. */
+`insecure-context` |
+/** The camera was lost mid-session — unplugged, or claimed by another app. */
+`camera-lost` |
+/** The decoder itself threw. Distinct from "no code in this frame". */
+`decoder-error`;
+/** Events driving a scan session. */
+type ScanEvent =
+/** Consumer asked to begin. */
+{
+  type: `START`;
+} |
+/** Camera acquired and frames are flowing. */
+{
+  type: `READY`;
+} |
+/** A frame decoded successfully. Terminal — restarting is explicit. */
+{
+  type: `DECODE`;
+  value: string;
+} |
+/** The user refused camera access. */
+{
+  type: `DENY`;
+} |
+/** Something broke that the user cannot act on. */
+{
+  type: `FAIL`;
+  reason: ScanFailure;
+} |
+/** Tab hidden, or the consumer suspended scanning. */
+{
+  type: `PAUSE`;
+} |
+/** Visible again. */
+{
+  type: `RESUME`;
+} |
+/** Consumer tore the session down. */
+{
+  type: `STOP`;
+};
+/** Whether `event` would move `state`. */
+declare const canTransitionScan: (state: ScanState, event: ScanEvent[`type`]) => boolean;
+/** Apply an event. Unknown events for the current state are no-ops. */
+declare const scanTransition: (state: ScanState, event: ScanEvent) => ScanState;
+/**
+ * Terminal states accept no further events.
+ *
+ * Derived from the table rather than listed, so a new state cannot be added
+ * without its terminality following automatically.
+ */
+declare const isScanSettled: (state: ScanState) => boolean;
+//#endregion
+export { type BitMatrix, type DecodeRequest, type DecodeResponse, type DecodedSymbol, type GpuScorer, type GrayImage, type MatrixDecodeResult, type Point, type ProgressiveOptions, type ProgressiveScanner, type QrDecoderOptions, type ScanEvent, type ScanFailure, type ScanState, type SymbolDecoder, type WorkerScanner, binarize, binarizeGlobal, blur, canTransitionScan, close, createGpuScorer, createProgressiveScanner, createQrDecoder, createWorkerScanner, decodeMatrix, downscale, hasWebGpu, isScanSettled, scanTransition, serveDecoder, toGray, withClearance };
+//# sourceMappingURL=index.d.mts.map

package/dist/scan/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/scan/qr/progressive.ts","../../src/scan/qr/locate.ts","../../src/scan/binarize.ts","../../src/scan/qr/format.ts","../../src/scan/qr/decode-matrix.ts","../../src/scan/qr/sample.ts","../../src/scan/gpu.ts","../../src/scan/machine.ts"],"mappings":";;;UA6BiB;;;;;;;EAOf,KAAK,OAAO,YAAY;;;;;;;;EASxB;;WAGS;;;UAIM,2BAA2B,KAC1C;;;;;;;EASA;;;;;;;;EASA;;;;;;;;EASA;;;;;;;;;;cAWW,6BAA4B,iBAAA,aAAA,WAAA,mBAKtC,uBAA0B;;;;;;;;;;;;;;;UA2DZ;;EAEf,KAAK,OAAO,YAAY,QAAQ;;EAEhC;;EAEA;;WAES;;;;;;;;;;cAWE,sBACX;EAIE,cAAc,kBAAkB,WAAW;EAC3C,oBACE,cACA,WAAW;IAAS;;EAEtB,MAAM,cAAc,WAAW;EAC/B;KAEF,iBAAA,aAAA,WAIG,uBACF;;;;UC7Kc;WACN,QAAQ;;WAER;;;;;;;;;cAynBE,gBACX,QAAQ,WACR,mBAAmB,oBAClB;;;;cCpmBU,SACX,MAAM,mBACN,eACA,mBACC;;;;;;;;;;;;;;;;;;;;;;cAiNU,iBACX,OAAO,aACP;EAAsB;MACrB;;;;;;;;;;;;;;;;;;cAmEU,QAAS,QAAQ,cAAY;;;;;;;;;;;;;;;;;;;cAkF7B,YAAa,OAAO,WAAW,mBAAiB;;;;;;;;;;;;;;;;;;;;cAgEhD,OAAQ,OAAO,WAAW,mBAAiB;;;;;;;;;;;;;cAmL3C,WACX,OAAO,aACP;EAAsB;MACrB;;;;KC5nBS;;;;UCKK;WACN;WACA;WACA,sBAAsB;WACtB;;;;;;;;;;cAWE,eACX,QAAQ,WAgBR;;;;;;;;;;;;;;;;AAAA,aAAa,eACZ;;;;;;;;;;;UC9Bc;WACN;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;;;;UC6HM;EACf,MACE,OAAO,WACP,qBAAqB,aACrB,cACA,sCACC,QAAQ;EACX;;;cAIW;;;;;;;cASA,uBAA4B,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KCxJrC;;KAWA;;;;;;;;;;KAWA;;;EAEN;;;;EAEA;;;;EAEA;EAAgB;;;;EAEhB;;;;EAEA;EAAc,QAAQ;;;;EAEtB;;;;EAEA;;;;EAEA;;;cAyCO,oBACX,OAAO,WACP,OAAO;;cAII,iBAAkB,OAAO,WAAW,OAAO,cAAY;;;;;;;cASvD,gBAAiB,OAAO"}