@saeris/hanko 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+
+## 0.2.1
+<sub>2026-09-02</sub>
+
+- Refresh the README, and give the example real navigation.
+
 ## 0.2.0
 <sub>2026-09-02</sub>
 

package/README.md

@@ -1,605 +1,346 @@
-# hanko
+<div align="center">
 
-QR-assisted device sign-in for screens without a keyboard — TVs, kiosks, set-top
-boxes. An implementation of [RFC 8628][rfc], the OAuth 2.0 Device Authorization
-Grant, which is the flow behind Plex, Steam, and Discord's TV sign-in.
+# 💮 hanko「判子」
 
-The device shows a short code and a QR. The user authorizes on their phone. The
-device polls until it hears back, then signs in.
+[![CI status][ci_badge]][ci] [![npm][npm_badge]][npm] [![License][license_badge]][license]
 
-```
-┌──────────────────────────────┐
-│   Sign in                    │
-│                              │
-│   Visit example.com/link     │        ▌▌▌ ▌ ▌▌▌
-│   and enter this code        │   OR   ▌ ▌▌▌▌ ▌▌
-│                              │        ▌▌ ▌ ▌▌▌▌
-│      W D J B - M J H T       │        ▌▌▌▌ ▌ ▌▌
-└──────────────────────────────┘
-```
+QR-assisted device sign-in for screens without a keyboard, with a QR decoder of its own.
 
-Zero dependencies beyond [`etiket`][etiket] for QR rendering. Runs anywhere with
-WinterTC primitives: Node, browsers, Deno, Bun, Cloudflare Workers.
+</div>
 
-## Three places this flow lives
+---
 
-hanko ships a baseline for each, and no UI components for any of them — state
-and lifecycle hooks instead, so React, Vue, Svelte, Solid, Angular, and React
-Native each bind it with their own conventions.
+**判子** (_hanko_) is the personal seal used in Japan in place of a signature —
+pressed once to authorize something on your behalf. Which is the whole flow: a
+TV asks, you approve it from your phone, the TV is signed in.
 
-| Entry                         | Runs on                | Gives you                                  |
-| ----------------------------- | ---------------------- | ------------------------------------------ |
-| `@saeris/hanko` + `/handlers` | your API               | grant lifecycle, `Request`→`Response` glue |
-| `@saeris/hanko/client`        | the device signing in  | poll loop, QR rendering                    |
-| `@saeris/hanko/approve`       | the device granting it | QR reading, confirmation challenges        |
+## 🎯 What it does
 
-## Install
+An implementation of [RFC 8628][rfc], the OAuth 2.0 Device Authorization Grant
+— the flow behind Plex and Steam's TV sign-in, and Discord's device
+authorization. A device that is awkward to type on shows a short code and a QR;
+the user authorizes on a phone they are already signed in on; the device polls
+until it hears back.
 
-```sh
-yarn add @saeris/hanko
-```
-
-hanko has **no runtime dependencies**. Its job is RFC 8628 — the grant
-lifecycle — and that is all it ships.
-
-Drawing a QR is a different class of problem, so it lives behind
-`@saeris/hanko/qr` and defers to [`etiket`](https://www.npmjs.com/package/etiket),
-declared as an optional peer. Add it only if you render the device screen:
+```mermaid
+sequenceDiagram
+    participant TV as 📺 Device
+    participant API as ⚙️ Your API
+    participant Phone as 📱 Phone
 
-```sh
-yarn add etiket
-```
+    TV->>API: POST /device/authorize
+    API-->>TV: user_code, device_code, verification_uri
+    Note over TV: shows WDJB-MJHT<br/>and a QR of the link
 
-## Server
+    loop until approved or expired
+        TV->>API: POST /device/token
+        API-->>TV: authorization_pending
+    end
 
-hanko owns the grant lifecycle and nothing else. It never mints sessions or
-tokens: `approve()` records an opaque `subject`, a successful poll hands it
-back, and your app issues whatever credential it already knows how to issue.
-That is what lets it sit alongside Better-Auth or Supabase rather than competing
-with them.
+    Phone->>Phone: scans the QR
+    Phone->>API: POST /link (approve)
+    API-->>Phone: approved
 
-```ts
-import { HankoServer } from "@saeris/hanko";
-import { MemoryDeviceGrantStore } from "@saeris/hanko/stores/memory";
-
-const hanko = new HankoServer({
-  store: new MemoryDeviceGrantStore(),
-  verificationUri: `https://example.com/link`
-});
-
-// POST /device/authorize — the device starts here
-const grant = await hanko.requestAuthorization();
-// → { device_code, user_code, verification_uri, verification_uri_complete, ... }
-
-// POST /device/token — the device polls here
-const result = await hanko.poll(deviceCode);
-if (result.status === `approved`) {
-  const session = await createSession(result.subject);
-}
-
-// POST /link — the phone approves here, after the user confirms the code
-await hanko.approve(userCode, session.userId);
+    TV->>API: POST /device/token
+    API-->>TV: access_token
 ```
 
-### Rendering the screen
+Three entry points, one per device in the flow. No UI components for any of
+them — state and lifecycle hooks instead, so React, Vue, Svelte, Solid, Angular
+and React Native each bind it with their own conventions.
 
-```ts
-// From the /qr subpath, not the barrel: this is the one entry point that
-// needs a dependency, and a server that only issues grants never pays for it.
-import { renderDeviceQr } from "@saeris/hanko/qr";
-
-const svg = renderDeviceQr(grant.verification_uri_complete, { size: 512 });
-```
+| Entry                         | Runs on                | Gives you                                  |
+| ----------------------------- | ---------------------- | ------------------------------------------ |
+| `@saeris/hanko` + `/handlers` | your API               | grant lifecycle, `Request`→`Response` glue |
+| `@saeris/hanko/client`        | the device signing in  | poll loop, QR rendering                    |
+| `@saeris/hanko/approve`       | the device granting it | QR reading, confirmation challenges        |
 
-Defaults are tuned for a TV viewed from across a room. Error correction is `M`,
-not `H`: higher correction needs more modules to encode the same URL, so at a
-fixed size each module gets smaller — and on a clean screen, module size matters
-more than damage tolerance.
+## 📷 The QR decoder
 
-**Show the code on both screens, and let the user compare.**
-[RFC 8628 §3.3.1][rfc] is explicit about the mitigation:
+`@saeris/hanko/scan` reads QR codes. Pixels in, string out — no camera, no DOM,
+no dependencies — so the same code runs in a browser, in a worker, on a server,
+or in a test.
 
-> The server SHOULD display the `user_code` to the user and ask them to verify
-> that it matches the `user_code` being displayed on the device to confirm they
-> are authorizing the correct device.
+It exists because every JavaScript alternative is unmaintained: jsQR's last code
+commit was August 2021, qr-scanner's November 2022, and `BarcodeDetector` is
+still a WICG incubation that Safari has never shipped.
 
-So `createApprovalHandler` returns the code, and the approval screen shows it
-next to which client is asking. The check is a **visual comparison against a
-physically separate screen** — not a memory test. Making someone re-type a code
-they can see proves nothing extra and is friction no production implementation
-of this flow imposes.
+Measured against the 718-image [BoofCV benchmark][boofcv] — photographs, not
+renders:
 
-`device_code` is never returned. That one is the bearer credential.
+| Decoder   | Recognition |
+| --------- | ----------- |
+| **hanko** | **74.4%**   |
+| BoofCV    | 60.69%      |
+| ZBar      | 38.95%      |
+| ZXing     | 31.87%      |
+| jsQR      | 24.8%       |
 
-## Device
+### Decoding one image
 
 ```ts
-import { DeviceAuthClient } from "@saeris/hanko/client";
-
-const client = new DeviceAuthClient({
-  tokenUrl: `https://example.com/device/token`,
-  deviceCode: grant.device_code,
-  interval: grant.interval,
-  expiresIn: grant.expires_in,
-  hooks: {
-    onTransition: (from, to) => render(to),
-    onSlowDown: (seconds) => console.log(`slowing to ${seconds}s`)
-  }
-});
-
-const outcome = await client.run(signal);
-// → { status: "authorized", tokens } | "denied" | "expired" | "aborted"
-```
+import { createQrDecoder, toGray } from "@saeris/hanko/scan";
 
-Polling only — no SSE or WebSocket. A sign-in screen may stay powered on for
-days, and a persistent connection is one more thing to leak and reconnect on
-hardware you cannot attach a profiler to.
+const decoder = createQrDecoder();
+const symbol = decoder.decode(toGray(rgba, width, height));
 
-For the common case where you only want the outcome:
-
-```ts
-import { pollUntilAuthorized } from "@saeris/hanko/client";
-
-const outcome = await pollUntilAuthorized({
-  tokenUrl,
-  deviceCode,
-  interval,
-  expiresIn
-});
+symbol?.value; // the payload, or null if nothing was found
 ```
 
-## Approving device
+### Scanning with a camera
 
-The phone that is already signed in. Two topologies exist in the wild and hanko
-supports both through one flow:
+Three pieces: a worker holding the decoder, something to turn a camera into
+greyscale frames, and a loop between them.
 
-- **Plex**: the OS camera opens `verification_uri_complete` in a browser. The
-  code arrives in the query string — no scanning step.
-- **Discord / Steam**: the app scans in-place and the user never leaves it.
+The worker is not optional. The retry ladder deliberately outruns its own time
+budget — the budget is checked between attempts, not inside them — so a
+synchronous decode stalls the preview on exactly the frames someone is lining
+up.
 
 ```ts
-import { ApprovalClient, codeEntryChallenge } from "@saeris/hanko/approve";
-
-const client = new ApprovalClient({
-  resolve: async (code) =>
-    await fetch(`/link?user_code=${code}`).then((r) =>
-      r.ok ? r.json() : null
-    ),
-  submit: async (code, approved) => {
-    await fetch(`/link`, {
-      method: `POST`,
-      body: new URLSearchParams({ user_code: code, approved: String(approved) })
-    });
-  },
-  challenge: codeEntryChallenge(),
-  hooks: { onTransition: (from, to) => render(to) }
-});
-
-// Plex path — code came from the URL
-await client.submitCode(new URL(location.href).searchParams.get(`user_code`));
-
-// Discord/Steam path — scan frames until one carries a code
-client.startScanning();
-await client.scan(videoElement);
-
-// Then, once the user answers the challenge
-await client.confirm(typedCode);
-await client.approve();
-```
-
-`approve()` refuses until the challenge passes. `deny()` never does — a user who
-cannot confirm a code is the one most likely to be looking at a phishing
-attempt, and they must always be able to say no.
-
-### Reading QR codes
-
-hanko defines a two-method `QrScanner` interface and lets you bring a decoder.
-It deliberately does not pick one for you.
-
-**`BarcodeDetector` is not a web standard.** It is a WICG incubation that MDN
-flags as outside Baseline; Safari has never shipped it, and no vendor has
-committed to it. Building against it directly means the scanner silently does
-nothing on an iPhone — the device most people approve from.
+// decoder.worker.ts
+import { serveDecoder } from "@saeris/hanko/scan/worker";
 
-The recommendation is [`qr-scanner`][qr-scanner]: ~6 kB gzipped,
-self-contained, and it uses a native `BarcodeDetector` where one exists and its
-own worker otherwise. It owns the camera too, which is most of the work.
-
-```ts
-import QrScanner from "qr-scanner";
-import { parseApprovalLink } from "@saeris/hanko/approve";
-
-const scanner = new QrScanner(
-  videoElement,
-  ({ data }) => {
-    const link = parseApprovalLink(data);
-    if (link) void client.submitCode(link.userCode);
-  },
-  { preferredCamera: `environment`, maxScansPerSecond: 10 }
-);
-await scanner.start();
+// No time budget: a worker has no preview to block, so the ladder may run to
+// exhaustion. Worth roughly twenty points of recognition over the 120ms a
+// synchronous decode has to respect.
+serveDecoder(self, { timeBudgetMs: 0 });
 ```
 
-Alternatives, and what they cost:
-
-| Decoder                  | Size         | Note                                                     |
-| ------------------------ | ------------ | -------------------------------------------------------- |
-| `qr-scanner`             | ~6 kB gz     | self-contained, manages the camera                       |
-| `barcode-detector`       | ~1.5 MB WASM | more formats, but fetches its WASM from a CDN at runtime |
-| native `BarcodeDetector` | 0            | absent on Safari; use `createBarcodeDetectorScanner()`   |
-| `expo-camera`            | —            | React Native, where no web API exists                    |
-
-Anything satisfying `QrScanner` works, including a React Native camera:
-
 ```ts
-const scanner: QrScanner = {
-  detect: async (frame) => [{ rawValue: await scanWithExpoCamera(frame) }]
+// camera.ts
+export const openCamera = async (video: HTMLVideoElement) => {
+  const stream = await navigator.mediaDevices.getUserMedia({
+    // A preference, not a guarantee — a laptop with one camera ignores it.
+    video: { facingMode: { ideal: `environment` } },
+    audio: false
+  });
+
+  video.srcObject = stream;
+  // Without this iOS opens the system player full-screen instead of playing
+  // inline, and there is no preview to aim with.
+  video.setAttribute(`playsinline`, ``);
+  await video.play();
+
+  const canvas = document.createElement(`canvas`);
+  // `willReadFrequently` matters: without it the browser keeps the canvas on
+  // the GPU and every `getImageData` is a synchronous readback, which is the
+  // most expensive thing in this loop.
+  const context = canvas.getContext(`2d`, { willReadFrequently: true })!;
+
+  return {
+    grab: () => {
+      const width = video.videoWidth;
+      const height = video.videoHeight;
+      // Zero before the first paint, and on iOS while the element is paused.
+      if (width === 0 || height === 0) return null;
+
+      canvas.width = width;
+      canvas.height = height;
+      context.drawImage(video, 0, 0);
+      const { data } = context.getImageData(0, 0, width, height);
+
+      // Converted here rather than in the worker: it quarters the bytes
+      // transferred per frame.
+      const grey = new Uint8ClampedArray(width * height);
+      for (let i = 0, p = 0; i < grey.length; i++, p += 4) {
+        grey[i] = (data[p] * 77 + data[p + 1] * 150 + data[p + 2] * 29) >> 8;
+      }
+
+      return { data: grey, width, height };
+    },
+
+    stop: () => {
+      for (const track of stream.getTracks()) track.stop();
+      video.srcObject = null;
+    }
+  };
 };
 ```
 
-`createBarcodeDetectorScanner` restricts detection to `qr_code`. An EAN-13 in
-the same frame would otherwise be posted to your approval endpoint as though it
-were a user code.
-
-### Confirmation challenges
-
-Scanning a QR removes the moment where the user would have noticed the code was
-wrong. [RFC 8628 §5.4][rfc-security] asks you to put it back. How much friction
-that deserves is a product decision, so it is pluggable:
-
-| Strategy                              | Pattern                    | Friction            |
-| ------------------------------------- | -------------------------- | ------------------- |
-| `noChallenge()`                       | Discord, Steam             | one tap             |
-| `tripletChallenge({ generate })`      | Google mobile approval     | one tap, real check |
-| `codeEntryChallenge()`                | GitHub sudo, Plex          | types the code      |
-| `platformChallenge({ authenticate })` | FaceID, WebAuthn, passcode | biometric           |
-
-`allOf([...])` composes them. The pairing worth knowing: a biometric proves
-possession of the phone, a code check proves the user is looking at the screen
-being authorized. Neither covers both.
-
-```ts
-import {
-  allOf,
-  codeEntryChallenge,
-  platformChallenge
-} from "@saeris/hanko/approve";
-
-const challenge = allOf([
-  platformChallenge({
-    authenticate: () => LocalAuthentication.authenticateAsync()
-  }),
-  codeEntryChallenge()
-]);
-```
-
-For a public screen — a taproom TV anyone can walk up to — do not use
-`noChallenge()`.
-
-## Opening the app from a scanned code
-
-One QR should open the native app when it is installed, and the web page when it
-is not — without the device ever showing an error.
-
-That rules out custom schemes as the QR payload. A `beerjournal://` code read by
-the OS camera on a phone without the app fails silently and unrecoverably: the
-user sees "cannot open" with nowhere to go. **Universal Links (iOS) and App
-Links (Android)** solve this by making the payload an ordinary `https://` URL
-that the OS _routes_ to the app when the domain and app are associated.
-
-So the QR keeps encoding `verification_uri_complete` unchanged. The routing
-lives in association files served from the same origin:
-
 ```ts
-import { createWellKnownHandler } from "@saeris/hanko/handlers";
-
-const wellKnown = createWellKnownHandler({
-  appleAppIds: [`QQ57RJ5UTD.gg.saeris.beerjournal`],
-  androidPackageName: `gg.saeris.beerjournal`,
-  // SHA-256 of the PLAY-signed cert, not your local keystore.
-  androidFingerprints: [`AA:BB:...`]
-});
-```
-
-Both files must be served from the **same origin** as the approval page, over
-HTTPS, **with no redirects**. A redirect or a wrong content-type makes the
-association fail silently, with nothing in any log — the usual reason universal
-links "just don't work".
-
-### Expo
-
-```ts
-import { expoLinkingConfig } from "@saeris/hanko";
-
-// Merge into app.json
-expoLinkingConfig({ origin: `https://example.com`, scheme: `beerjournal` });
-// → { scheme, ios: { associatedDomains: ["applinks:example.com"] },
-//     android: { intentFilters: [{ autoVerify: true, ... }] } }
-```
-
-Two things that silently break this:
-
-- `associatedDomains` takes **no protocol** — `applinks:example.com`, never
-  `applinks:https://example.com`.
-- `autoVerify: true` is what makes Android fetch `assetlinks.json` and open the
-  app without a chooser dialog. Without it the link is registered and
-  practically useless.
-
-**Universal links do not work in Expo Go.** The entitlement is registered at
-build time, so this needs a development or production build. A project pinned to
-Expo Go uses the web fallback until it moves to dev builds — which is a
-sequencing constraint, not a blocker: the same QR already works.
-
-Receiving the link:
-
-```ts
-import * as Linking from "expo-linking";
-import { parseApprovalLink } from "@saeris/hanko/approve";
-
-const initial = await Linking.getInitialURL();
-const link = initial && parseApprovalLink(initial, { scheme: `beerjournal` });
-if (link) await client.submitCode(link.userCode);
-```
-
-### PWAs on both ends
-
-The whole flow works PWA-to-PWA, with one caveat worth knowing up front.
-
-**The signing-in device** (the TV) is the easy half: it renders a code and an
-SVG QR, then polls. No camera, no install, no platform APIs. A Fire Stick or Pi
-browser runs it as-is.
-
-**The approving device** is where PWAs get thin:
-
-| Capability                          | Status                                |
-| ----------------------------------- | ------------------------------------- |
-| Receive an https link               | works everywhere                      |
-| `launch_handler: navigate-existing` | Chromium only; falls back cleanly     |
-| Camera scanning (`getUserMedia`)    | works, but see below                  |
-| Being the OS camera's target        | **installed PWAs cannot claim links** |
-
-The last row is the real constraint: a PWA cannot register for Universal Links.
-The OS camera opens the _browser_, not your installed PWA. `launch_handler` only
-controls what happens once the link reaches your origin.
-
-Camera access inside an installed iOS PWA was broken from iOS 18 until 18.4, and
-permission still is not persisted the way it is in Safari proper. So on the
-approving side, **the typed-code path is the reliability floor, not a nicety** —
-build the scanner as an enhancement over it, never the only way in.
-
-```ts
-import { consumeLaunchTarget, parseApprovalLink } from "@saeris/hanko/approve";
-
-// Reads launchQueue where supported. Safari and Firefox have none, and the
-// `location.href` fallback is opt-in (`fallbackToLocation: true`) because it
-// cannot tell a launch from an ordinary page load — it fires on every visit.
-// Turn it on only for a page reached exclusively by launch; otherwise a plain
-// visit submits its own URL as a code and fails.
-consumeLaunchTarget((href) => {
-  const link = parseApprovalLink(href);
-  if (link) void client.submitCode(link.userCode);
-});
-```
-
-Add `pwaLaunchHandler()` to your manifest so a scanned link reuses the open
-window rather than stacking a second one behind it.
-
-### What each device actually gets
-
-| Approving device                      | Scanned QR opens            | Notes                     |
-| ------------------------------------- | --------------------------- | ------------------------- |
-| Native app installed (dev/prod build) | the app, directly           | best case                 |
-| Native app absent                     | the web page                | same QR, no error         |
-| Installed PWA                         | the browser, then your page | PWA cannot claim the link |
-| Desktop browser                       | the web page                | typed code only           |
+// the loop
+import { createWorkerScanner } from "@saeris/hanko/scan";
+import { openCamera } from "./camera";
+
+const camera = await openCamera(document.querySelector(`video`)!);
+const scanner = createWorkerScanner(
+  new Worker(new URL("./decoder.worker.ts", import.meta.url), {
+    type: `module`
+  })
+);
 
-Every row reaches a working approval screen. That is the property worth
-protecting — and the reason the payload stays an `https://` URL.
+let scanning = true;
 
-## Edge runtimes
+while (scanning) {
+  const frame = camera.grab();
 
-The server half is stateless by construction: every request loads its grant,
-applies one transition, and writes it back. Nothing is held between
-invocations, so a flow survives its requests landing on different workers, or
-on an instance frozen mid-flow.
+  if (frame !== null) {
+    // Awaited one at a time on purpose. A camera produces frames faster than
+    // they decode, and `scan` drops anything offered while a decode is in
+    // flight rather than queueing it — the next frame is always a better
+    // input than a backlogged one.
+    const symbol = await scanner.scan(frame);
 
-```ts
-// Cloudflare Workers
-import { createHandlers } from "@saeris/hanko/handlers";
-import { HankoServer } from "@saeris/hanko";
-import { KvDeviceGrantStore, kvFromOptionsApi } from "@saeris/hanko/stores/kv";
-
-export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
-    const handlers = createHandlers({
-      server: new HankoServer({
-        store: new KvDeviceGrantStore({
-          kv: kvFromOptionsApi({
-            get: (k) => env.GRANTS.get(k),
-            set: (k, v, o) => env.GRANTS.put(k, v, o),
-            remove: (k) => env.GRANTS.delete(k)
-          })
-        }),
-        verificationUri: `https://example.com/link`
-      }),
-      // Read from YOUR session — never from the request body.
-      authenticate: (req) => getSession(req)?.userId ?? null,
-      createSession: (subject) => mintToken(subject),
-      rateLimit: (req, code) =>
-        limiter.check(req.headers.get(`CF-Connecting-IP`), code)
-    });
-    return handlers.fetch(request);
+    if (symbol !== null) {
+      console.log(symbol.value);
+      scanning = false;
+      break;
+    }
   }
-};
-```
-
-The individual handlers — `authorize`, `token`, `approval` — are exported
-separately for file-based routing (Astro, Next, SvelteKit, Vercel Functions).
-
-### Multiple hostnames, one deployment
 
-The QR has to encode the host the device is actually talking to. One deployment
-is commonly reachable through several — a preview URL, a custom domain, a
-tunnel during development — and a `verificationUri` fixed at construction time
-points at only one of them. The failure is silent: the code renders correctly
-and the phone lands nowhere.
-
-`createAuthorizationHandler` therefore derives the origin per request from
-`x-forwarded-host` and `x-forwarded-proto`, which every common proxy sets —
-ngrok, Cloudflare, Vercel, nginx. The configured `verificationUri` remains the
-fallback for direct requests that carry no forwarded headers.
+  // Yield to the compositor. The decode happens on another thread, but this
+  // loop still runs on the main one.
+  await new Promise((resolve) => requestAnimationFrame(resolve));
+}
 
-```ts
-createAuthorizationHandler({
-  server,
-  verificationPath: `/link`, // appended to the detected origin
-  trustForwardedHost: true // the default
-});
+scanner.close();
+camera.stop();
 ```
 
-Set `trustForwardedHost: false` to always use the configured value. Worth doing
-if your platform does not strip client-sent `x-forwarded-*` headers and you
-would rather pin the origin: those headers are client-controllable in that
-case. They are safe for building a URL the same client will visit — which is
-all this does — but never use them for an authorization decision.
+A scanned payload is untrusted input. If you turn one into a link, restrict it
+to `http:` and `https:` and show the raw text beside it — `new URL()` happily
+accepts `javascript:`.
 
-Calling the server directly takes the same override:
+For a camera that should keep trying across frames rather than exhausting the
+ladder on one, `createProgressiveScanner` spends a small budget per frame and
+raises it while a symbol is in view.
 
-```ts
-await server.requestAuthorization({
-  verificationUri: `https://${request.headers.get("x-forwarded-host")}/link`
-});
-```
-
-### Persistence
-
-| Layer                               | Adapter                                                     |
-| ----------------------------------- | ----------------------------------------------------------- |
-| Upstash Redis, Vercel KV, `ioredis` | `KvDeviceGrantStore` + `kvFromOptionsApi({ ttlKey: "ex" })` |
-| Cloudflare Workers KV               | `kvFromOptionsApi({ ttlKey: "expirationTtl" })`             |
-| Deno KV                             | `KeyValueAdapter` directly                                  |
-| Supabase / Postgres                 | implement `DeviceGrantStore` (four methods)                 |
-| Durable Objects                     | implement `DeviceGrantStore` over `ctx.storage`             |
+Coverage per condition, and the negative results behind it, live in
+[plan/qr-coverage.md](plan/qr-coverage.md). Both move often.
 
-TTL does the pruning, with a grace window past the deadline so the server can
-answer `expired_token` honestly instead of "unknown code" — which a client
-cannot distinguish from a typo.
+## 🏗️ How it works
 
-**Rate limiting is your job.** [§5.1][rfc-security] requires it, and hanko
-cannot do it portably: an effective limiter needs the client IP, which lives in
-a platform-specific header. The `rateLimit` seam exists so the requirement is
-not silently skipped.
+hanko owns the **grant lifecycle** and nothing else. It never mints sessions or
+touches your user table: it tells you a grant was approved and by whom, and
+issuing a token from that is your application's decision.
 
-## State machines
+```mermaid
+flowchart LR
+    subgraph device["📺 Device"]
+        client["@saeris/hanko/client"]
+    end
 
-Both halves are explicit state machines with declarative transition tables. The
-transitions are data, so they can be read against the RFC side by side — and
-illegal moves are impossible by construction rather than guarded against.
+    subgraph api["⚙️ Your API"]
+        server["@saeris/hanko + /handlers"]
+        store[("DeviceGrantStore")]
+        server <--> store
+    end
 
-**Grant** (server):
+    subgraph phone["📱 Phone"]
+        approve["@saeris/hanko/approve"]
+        scan["@saeris/hanko/scan"]
+        approve --> scan
+    end
 
+    client -->|authorize, then poll| server
+    approve -->|approve| server
 ```
-pending ──APPROVE──▶ approved ──REDEEM──▶ consumed
-   │                     │
-   ├──DENY────▶ denied   └──EXPIRE──▶ expired
-   └──EXPIRE──▶ expired
-```
-
-Redemption, not approval, is what ends the flow — a `device_code` that stayed
-redeemable after approval would be a replayable bearer credential. And an
-approval nobody collected still expires.
 
-**Poll** (device):
+### Decisions worth knowing
+
+- **Zero runtime dependencies.** The grant lifecycle is the product; rendering a
+  QR is a different class of problem, so it sits behind `@saeris/hanko/qr` and
+  defers to [`etiket`][etiket] as an optional peer. Reading one had no
+  maintained option at all, which is why `/scan` exists.
+- **WinterTC primitives only.** `Request`, `Response`, `crypto.getRandomValues` —
+  so one build runs on Node, Deno, Bun, Cloudflare Workers and in a browser,
+  with no adapter per runtime.
+- **A short code is a small keyspace.** That is the deliberate trade for
+  readability, and [RFC 8628 §5.1][rfc-security] **requires you to rate-limit
+  attempts**. hanko does not do it for you: that belongs at your HTTP boundary,
+  where you can see IPs.
+- **Approval is two steps, not one.** Scanning a code that says "approve this"
+  and approving it are separate, because a QR is a link anyone can point a
+  camera at. `/approve` ships the confirmation challenge that closes that gap.
+- **The store is four methods.** `create`, `findByDeviceCode`, `findByUserCode`
+  and `update`, plus an optional `prune` — small enough that an adapter for your
+  database is a short file. The bundled memory store is for development only.
+
+## 📦 Install
 
-```
-idle ──START──▶ waiting ──TICK──▶ polling
-                   ▲                 │
-                   └── pending ──────┤── SUCCESS ────────▶ authorized
-                       slow_down     ├── ACCESS_DENIED ──▶ denied
-                       network error └── EXPIRED_TOKEN ──▶ expired
+```sh
+yarn add @saeris/hanko
 ```
 
-The interval lives in context, not state: `waiting` at 5s and `waiting` at 20s
-are the same state. That separation keeps the two pacing rules distinct —
-`slow_down` adds a fixed 5s permanently ([§3.5][rfc-token]), while a network
-failure doubles with a cap. Conflating them either hammers a struggling server
-or crawls when it only asked for a small delay.
+Add `etiket` only if you render the device screen:
 
-**Approval** (the phone):
-
-```
-idle ──SCAN──▶ scanning ──CODE──▶ resolving ──RESOLVED──▶ confirming
-  │                                    │                      │
-  └──CODE (from URL)───────────────────┘                      │
-                                       └──REJECTED──▶ invalid │
-                                                              ▼
-                          approved ◀──SUBMITTED── submitting ─┘
-                          denied   ◀──SUBMITTED──
+```sh
+yarn add etiket
 ```
 
-`confirming` accepts `CHALLENGE_FAILED` back into itself: a mistyped code is a
-retry, not a dead end. Both entry paths — scanned in-app or arriving by URL —
-converge on the same confirmation, so the security-sensitive half is written
-once.
-
-All three machines are exported if you want to drive them yourself — persisting
-grant state in a Durable Object, say, or rendering a screen straight from the
-state:
-
-```ts
-import {
-  grantTransition,
-  pollTransition,
-  approvalTransition,
-  canTransitionGrant
-} from "@saeris/hanko";
+Codes follow the spec's worked example: 8 characters from a 20-consonant
+alphabet, shown as `WDJB-MJHT`. No vowels, so a code cannot spell a word; no
+digits, so there is no `0`/`O` or `1`/`l`/`I` to misread.
+
+## 🔧 Examples
+
+The whole sign-in flow, wired end to end, lives in
+[`examples/astro`](examples/astro) — three surfaces, a store, rate limiting and
+the confirmation challenge, with the framework-specific parts explained in
+[its README](examples/astro/README.md). That is the reference for building the
+flow; this README covers the pieces rather than the assembly.
+
+More are planned — Next.js first, mirroring the Astro one closely enough to
+diff, then other frameworks and UI stacks.
+
+| Route            | What it is                                                           |
+| ---------------- | -------------------------------------------------------------------- |
+| `/`              | the map — what to open where, and whether the URL reaches a phone    |
+| `/tv`            | the device screen — a short code and a QR for a pending grant        |
+| `/signin`        | the phone's own sign-in; this identity is what the device inherits   |
+| `/account`       | approved devices, and revoking them                                  |
+| `/link`          | the approval page — scans that QR, or takes a typed code             |
+| `/scanner`       | a bare scanner, showing the payload raw and as a link                |
+| `/scanner-debug` | the same, reporting each stage on screen for a phone with no console |
+
+```bash
+yarn demo        # builds the library, then serves the example
+yarn demo:share  # the same, over TLS so a phone can reach it
 ```
 
-## Codes
+A camera needs a secure context, so a bare LAN IP will not do — `demo:share`
+puts a TLS proxy in front, which is what makes the phone half testable at all.
 
-Defaults follow the spec's worked example: 8 characters from a 20-consonant
-alphabet, displayed as `WDJB-MJHT`. No vowels, so codes cannot spell words; no
-digits, so there is no `0`/`O` or `1`/`l`/`I` confusion.
+## 🧪 Checks
 
-```ts
-import { generateUserCode, NUMERIC_ALPHABET } from "@saeris/hanko";
+| What           | Command             | Notes                                           |
+| -------------- | ------------------- | ----------------------------------------------- |
+| Everything     | `vp run ci`         | `vp pack && vp check && vp test`, what CI runs. |
+| Tests          | `vp test`           | Pure TypeScript; never imports react-native.    |
+| Recognition    | `yarn bench:corpus` | The 718-image corpus, sharded across workers.   |
+| Decode profile | `yarn bench`        | A still image, for `deoptkit`.                  |
 
-generateUserCode(); // "WDJB-MJHT"
-generateUserCode({ alphabet: NUMERIC_ALPHABET, length: 9 }); // "0194-5073-0"
-```
+`vp pack` has to run before `vp check`: the example resolves `@saeris/hanko`
+through the `exports` map, which points at `dist/`, so a clean checkout cannot
+typecheck it until the library is built.
 
-A short code is a small keyspace, which is the deliberate trade for
-readability. **[RFC 8628 §5.1][rfc-security] requires you to rate-limit
-attempts** — the code alone is not brute-force resistant, and hanko does not
-rate-limit for you. That belongs at your HTTP boundary, where you can see IPs.
+## 🚀 Releasing
 
-## Storage
+Driven by [bumpy][bumpy]. Every change carries a **bump file** in `.bumpy/`
+saying what moved and how far, so the changelog cannot fall behind the code.
 
-`DeviceGrantStore` is four methods, so adapters are small:
-
-```ts
-interface DeviceGrantStore {
-  create(grant: DeviceGrant): Promise<void> | void;
-  findByDeviceCode(
-    deviceCode: string
-  ): Promise<DeviceGrant | null> | DeviceGrant | null;
-  findByUserCode(
-    userCode: string
-  ): Promise<DeviceGrant | null> | DeviceGrant | null;
-  update(grant: DeviceGrant): Promise<void> | void;
-  prune?(now: number): Promise<void> | void;
-}
+```bash
+yarn bumpy add
 ```
 
-The bundled `MemoryDeviceGrantStore` is for development only — state dies with
-the process and is not shared across instances.
+Merging that opens a **Version PR**; merging _that_ tags the release and
+publishes to npm over OIDC trusted publishing, so no token is stored. The
+example deploys to Vercel on push, independently of releases.
 
-## License
+## 🥂 License
 
-MIT © [Drake Costa](https://saeris.gg)
+[MIT][license] © [Drake Costa][personal-website]
 
 [rfc]: https://datatracker.ietf.org/doc/html/rfc8628
-[rfc-token]: https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
 [rfc-security]: https://datatracker.ietf.org/doc/html/rfc8628#section-5
 [etiket]: https://github.com/productdevbook/etiket
-[qr-scanner]: https://github.com/nimiq/qr-scanner
+[boofcv]: https://boofcv.org/index.php?title=Performance:QrCode
+[bumpy]: https://github.com/dmno-dev/bumpy
+[ci_badge]: https://github.com/Saeris/hanko/actions/workflows/ci.yml/badge.svg
+[ci]: https://github.com/Saeris/hanko/actions/workflows/ci.yml
+[npm_badge]: https://img.shields.io/npm/v/@saeris/hanko.svg
+[npm]: https://www.npmjs.com/package/@saeris/hanko
+[license_badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[license]: https://github.com/Saeris/hanko/blob/main/LICENSE.md
+[personal-website]: https://saeris.gg

package/dist/scan/index.d.mts

@@ -88,7 +88,10 @@ interface WorkerScanner {
  * would be wrong for most consumers.
  */
 declare const createWorkerScanner: (worker: {
-  postMessage: (message: unknown, transfer?: ArrayBufferLike[]) => void;
+  postMessage: {
+    (message: unknown, transfer: never[]): void;
+    (message: unknown, options?: unknown): void;
+  };
   addEventListener?: (type: string, listener: (event: {
     data: unknown;
   }) => void) => void;

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

@@ -1 +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"}
+{"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;EAUE;KACG,kBAAkB;KAClB,kBAAkB;;EAErB,oBACE,cACA,WAAW;IAAS;;EAEtB,MAAM,cAAc,WAAW;EAC/B;KAEF,iBAAA,aAAA,WAIG,uBACF;;;;UCtLc;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"}

package/dist/scan/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/scan/qr/progressive.ts","../../src/scan/gpu.ts","../../src/scan/machine.ts"],"sourcesContent":["/**\n * Scanning across frames rather than within one.\n *\n * The retry ladder is what makes difficult symbols readable, and it costs far\n * more than one frame can afford. Measured on the benchmark corpus, the\n * decoder reads **61.6%** with no time limit and **41.9%** at the 120ms\n * default a viewfinder needs — so a third of its capability is unreachable in\n * the configuration people actually run, and no budget recovers it: a sweep\n * showed recognition still climbing at 700ms.\n *\n * That is a false choice, because a camera is not a still image. It supplies\n * thirty frames a second, each nearly free and each slightly different. Ten\n * frames at 120ms is 1.2 seconds of decoding work at full frame rate, without\n * ever stalling the preview.\n *\n * So this spends a small budget per frame and ADVANCES through the ladder\n * across successive frames: cheap rungs on every frame, expensive ones only\n * once the cheap ones have failed repeatedly. A code held steadily in view\n * gets the whole ladder within a second; a frame with nothing in it costs one\n * cheap pass.\n *\n * The decoder itself stays pure and synchronous — this wraps it rather than\n * changing it, so a still image can still run the whole ladder at once.\n */\n\nimport type { DecodedSymbol, GrayImage } from \"../types.js\";\nimport { createQrDecoder, type QrDecoderOptions } from \"./decoder.js\";\n\n/** A scanner that improves its effort as frames arrive. */\nexport interface ProgressiveScanner {\n  /**\n   * Offer one frame.\n   *\n   * Returns a symbol as soon as one is read, and `null` otherwise — including\n   * while effort is still ramping up.\n   */\n  scan(image: GrayImage): DecodedSymbol | null;\n\n  /**\n   * Reset the effort ramp.\n   *\n   * Call when the scene changes — a new code presented, the camera moved\n   * somewhere else — so the next frame starts cheap again rather than\n   * inheriting effort earned by a symbol that is no longer there.\n   */\n  reset(): void;\n\n  /** How much effort the next frame will receive, in milliseconds. */\n  readonly budgetMs: number;\n}\n\n/** Options for {@link createProgressiveScanner}. */\nexport interface ProgressiveOptions extends Omit<\n  QrDecoderOptions,\n  `timeBudgetMs`\n> {\n  /**\n   * Budget for the first frame, in milliseconds.\n   *\n   * Deliberately small. Most frames a camera delivers contain no code at all,\n   * and this is what every one of them costs.\n   */\n  initialBudgetMs?: number;\n\n  /**\n   * Ceiling on the per-frame budget.\n   *\n   * 400ms by default: beyond that a single frame stalls the preview\n   * noticeably, and at 30fps the ladder has had a dozen frames to work with\n   * by the time the ramp reaches it.\n   */\n  maxBudgetMs?: number;\n\n  /**\n   * How much the budget grows per consecutive frame that shows a symbol.\n   *\n   * Growth is conditional on there being something to find: a frame with no\n   * finder candidate at all should not earn the next frame more time, or a\n   * camera pointed at a wall would ramp to its ceiling and stay there.\n   */\n  growth?: number;\n}\n\n/**\n * Create a scanner that spreads decoding effort across frames.\n *\n * The ramp is driven by evidence rather than by a timer. A frame in which the\n * decoder finds nothing resets it, because nothing is there to spend effort\n * on; a frame that finds a symbol but cannot read it raises the budget,\n * because that is exactly the case where more effort pays.\n */\nexport const createProgressiveScanner = ({\n  initialBudgetMs = 40,\n  maxBudgetMs = 400,\n  growth = 1.6,\n  ...decoderOptions\n}: ProgressiveOptions = {}): ProgressiveScanner => {\n  let budget = initialBudgetMs;\n\n  // One decoder per budget level, cached: constructing one is cheap, but a\n  // camera loop calls this thirty times a second and there are only a handful\n  // of distinct budgets in the ramp.\n  const decoders = new Map<number, ReturnType<typeof createQrDecoder>>();\n  const decoderFor = (ms: number): ReturnType<typeof createQrDecoder> => {\n    const existing = decoders.get(ms);\n    if (existing !== undefined) return existing;\n\n    const created = createQrDecoder({ ...decoderOptions, timeBudgetMs: ms });\n    decoders.set(ms, created);\n    return created;\n  };\n\n  return {\n    get budgetMs(): number {\n      return budget;\n    },\n\n    scan: (image: GrayImage): DecodedSymbol | null => {\n      const rounded = Math.round(budget);\n      const result = decoderFor(rounded).decode(image);\n\n      if (result !== null) {\n        // Read it. Drop back to the cheap budget: whatever comes next is a\n        // different scan, and starting expensive would waste effort on the\n        // frames after a successful read.\n        budget = initialBudgetMs;\n        return result;\n      }\n\n      // Nothing read. Spend more next time, up to the ceiling — the symbol may\n      // simply need more of the ladder than this frame could afford.\n      budget = Math.min(maxBudgetMs, budget * growth);\n      return null;\n    },\n\n    reset: (): void => {\n      budget = initialBudgetMs;\n    }\n  };\n};\n\n/**\n * Drive a decoder running in a worker.\n *\n * Same shape as {@link createProgressiveScanner} but asynchronous, because\n * the work happens elsewhere. The main thread stays free: measured on a hard\n * frame, an in-thread decode blocks 208ms at a 40ms budget and 481ms at\n * 400ms, which at 60fps is 12 and 28 dropped frames respectively — a visible\n * freeze on exactly the frames where someone is lining up a shot.\n *\n * Frames offered while a decode is in flight are DROPPED rather than queued.\n * A camera produces frames faster than they can be decoded, and a queue would\n * grow without bound while returning increasingly stale results; the next\n * frame is always a better input than a backlogged one.\n */\nexport interface WorkerScanner {\n  /** Offer a frame. Resolves `null` if dropped, still ramping, or unreadable. */\n  scan(image: GrayImage): Promise<DecodedSymbol | null>;\n  /** Reset the effort ramp — call when the scene changes. */\n  reset(): void;\n  /** Stop the worker and release it. */\n  close(): void;\n  /** Whether a decode is currently in flight. */\n  readonly busy: boolean;\n}\n\n/**\n * Wrap a worker in the progressive interface.\n *\n * The worker is supplied rather than constructed here, because how a worker\n * is created is a bundler question — `new Worker(new URL(...), { type:\n * \"module\" })` in Vite, a blob URL elsewhere — and a library that guessed\n * would be wrong for most consumers.\n */\nexport const createWorkerScanner = (\n  worker: {\n    // `ArrayBufferLike[]` rather than `Transferable[]`: this package compiles\n    // without the DOM lib on purpose, and a buffer is the only thing\n    // transferred here.\n    postMessage: (message: unknown, transfer?: ArrayBufferLike[]) => void;\n    addEventListener?: (\n      type: string,\n      listener: (event: { data: unknown }) => void\n    ) => void;\n    on?: (type: string, listener: (message: unknown) => void) => void;\n    terminate?: () => void;\n  },\n  {\n    initialBudgetMs = 40,\n    maxBudgetMs = 400,\n    growth = 1.6\n  }: ProgressiveOptions = {}\n): WorkerScanner => {\n  let budget = initialBudgetMs;\n  let nextId = 0;\n  let inFlight = false;\n  const pending = new Map<\n    number,\n    (response: { result: DecodedSymbol | null }) => void\n  >();\n\n  const receive = (payload: unknown): void => {\n    // Narrowed by runtime checks rather than a cast: a DOM MessageEvent\n    // carries the payload on `.data` while a Node message IS the payload, and\n    // asserting one shape would silently misread the other.\n    if (payload === null || typeof payload !== `object`) return;\n\n    const envelope = payload as { data?: unknown };\n    const body: unknown =\n      typeof envelope.data === `object` && envelope.data !== null\n        ? envelope.data\n        : payload;\n\n    if (body === null || typeof body !== `object`) return;\n    if (!(`id` in body) || typeof body.id !== `number`) return;\n\n    const response = body as { id: number; result: DecodedSymbol | null };\n    const resolve = pending.get(response.id);\n    if (resolve === undefined) return;\n\n    pending.delete(response.id);\n    inFlight = false;\n    resolve(response);\n  };\n\n  if (typeof worker.addEventListener === `function`) {\n    worker.addEventListener(`message`, receive);\n  } else if (typeof worker.on === `function`) {\n    worker.on(`message`, receive);\n  }\n\n  return {\n    get busy(): boolean {\n      return inFlight;\n    },\n\n    scan: async (image: GrayImage): Promise<DecodedSymbol | null> => {\n      // Dropped rather than queued: a camera outruns the decoder, and a queue\n      // would grow unbounded while returning ever staler results.\n      if (inFlight) return null;\n\n      inFlight = true;\n      const id = nextId++;\n\n      const settled = new Promise<{ result: DecodedSymbol | null }>(\n        (resolve) => {\n          pending.set(id, resolve);\n        }\n      );\n\n      // Copied before transfer: transferring detaches the caller's buffer,\n      // and a caller reusing one frame buffer across frames — which is the\n      // normal pattern — would find it empty on the next read.\n      const copy = new Uint8ClampedArray(image.data);\n      worker.postMessage(\n        { id, data: copy, width: image.width, height: image.height },\n        [copy.buffer]\n      );\n\n      const { result } = await settled;\n\n      budget =\n        result === null\n          ? Math.min(maxBudgetMs, budget * growth)\n          : initialBudgetMs;\n\n      return result;\n    },\n\n    reset: (): void => {\n      budget = initialBudgetMs;\n    },\n\n    close: (): void => {\n      pending.clear();\n      inFlight = false;\n      worker.terminate?.();\n    }\n  };\n};\n","/**\n * GPU-accelerated transform scoring.\n *\n * One stage of this decoder is worth moving to the GPU and the rest are not.\n * Profiling a 1024x768 frame: binarization costs 16ms, blur 28ms, downscale\n * 6ms — all far too small to survive the cost of uploading a buffer,\n * dispatching a shader and reading the result back. But the corner search\n * makes **625 independent calls** to `scoreTransform` for about 179ms, which\n * is 78% of that stage and the largest single cost in the decoder.\n *\n * Those 625 calls score the same image under different transforms, share no\n * state, and each reads a few hundred pixels. That is the shape GPU compute\n * exists for: one upload of the image, 625 workgroups, one small readback.\n *\n * Availability is unusually good for a modern web API. WebGPU shipped\n * enabled-by-default in iOS 26, macOS Tahoe 26 and iPadOS 26, which removed\n * the last major holdout — so unlike `BarcodeDetector`, this is something the\n * target platforms actually have. It still degrades to the CPU path\n * everywhere else, because a scanner that only works on new hardware is not a\n * scanner.\n */\n\nimport type { BitMatrix } from \"./types.js\";\nimport type { Transform } from \"./qr/sample.js\";\n\n/**\n * The scoring kernel.\n *\n * Mirrors `scoreTransform` exactly — same nine-point module sampling, same\n * ring structure, same weights. Any divergence would make GPU and CPU\n * disagree about which transform is best, which is worse than not\n * accelerating at all: results would depend on the device.\n */\nconst SHADER = `\nstruct Params {\n  width: u32,\n  height: u32,\n  size: u32,\n  centerCount: u32,\n};\n\n@group(0) @binding(0) var<storage, read> bits: array<u32>;\n@group(0) @binding(1) var<storage, read> transforms: array<f32>;\n@group(0) @binding(2) var<storage, read> centers: array<u32>;\n@group(0) @binding(3) var<storage, read_write> scores: array<i32>;\n@group(0) @binding(4) var<uniform> params: Params;\n\nfn pixel(x: i32, y: i32) -> i32 {\n  if (x < 0 || y < 0 || x >= i32(params.width) || y >= i32(params.height)) {\n    return 0;\n  }\n  let index = u32(y) * params.width + u32(x);\n  // Bits are packed one per u32 for simplicity: the readback is tiny and the\n  // upload happens once per frame, so the memory is not the bottleneck.\n  return select(-1, 1, bits[index] == 1u);\n}\n\nfn mapPoint(base: u32, x: f32, y: f32) -> vec2<f32> {\n  let a11 = transforms[base + 0u];\n  let a12 = transforms[base + 1u];\n  let a13 = transforms[base + 2u];\n  let a21 = transforms[base + 3u];\n  let a22 = transforms[base + 4u];\n  let a23 = transforms[base + 5u];\n  let a31 = transforms[base + 6u];\n  let a32 = transforms[base + 7u];\n  let a33 = transforms[base + 8u];\n\n  let w = a13 * x + a23 * y + a33;\n  if (abs(w) < 1e-9) { return vec2<f32>(-1.0, -1.0); }\n  return vec2<f32>((a11 * x + a21 * y + a31) / w, (a12 * x + a22 * y + a32) / w);\n}\n\nfn cell(base: u32, span: f32, mx: f32, my: f32) -> i32 {\n  var score = 0;\n  let offsets = array<f32, 3>(0.3, 0.5, 0.7);\n  for (var v = 0u; v < 3u; v = v + 1u) {\n    for (var u = 0u; u < 3u; u = u + 1u) {\n      let p = mapPoint(base, (mx + offsets[u] - 3.5) / span, (my + offsets[v] - 3.5) / span);\n      score = score + pixel(i32(round(p.x)), i32(round(p.y)));\n    }\n  }\n  return score;\n}\n\nfn ring(base: u32, span: f32, cx: f32, cy: f32, radius: f32) -> i32 {\n  var score = 0;\n  let steps = i32(radius * 2.0);\n  for (var i = 0; i < steps; i = i + 1) {\n    let f = f32(i);\n    score = score + cell(base, span, cx - radius + f, cy - radius);\n    score = score + cell(base, span, cx - radius, cy + radius - f);\n    score = score + cell(base, span, cx + radius, cy - radius + f);\n    score = score + cell(base, span, cx + radius - f, cy + radius);\n  }\n  return score;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  let index = id.x;\n  if (index >= arrayLength(&scores)) { return; }\n\n  let base = index * 9u;\n  let size = f32(params.size);\n  let span = size - 7.0;\n  var score = 0;\n\n  // Timing patterns alternate; the expected value flips each module.\n  for (var i = 0u; i < params.size - 14u; i = i + 1u) {\n    let expected = select(-1, 1, (i & 1u) == 1u);\n    score = score + cell(base, span, f32(i) + 7.0, 6.0) * expected;\n    score = score + cell(base, span, 6.0, f32(i) + 7.0) * expected;\n  }\n\n  // Finders: dark centre, dark ring, light ring, dark ring.\n  let corners = array<vec2<f32>, 3>(\n    vec2<f32>(0.0, 0.0),\n    vec2<f32>(size - 7.0, 0.0),\n    vec2<f32>(0.0, size - 7.0)\n  );\n  for (var c = 0u; c < 3u; c = c + 1u) {\n    let x = corners[c].x + 3.0;\n    let y = corners[c].y + 3.0;\n    score = score + cell(base, span, x, y)\n          + ring(base, span, x, y, 1.0)\n          - ring(base, span, x, y, 2.0)\n          + ring(base, span, x, y, 3.0);\n  }\n\n  // Alignment patterns: dark centre, light ring, dark ring.\n  //\n  // Two groups, matching the CPU exactly. The edge row and column come first\n  // (skipping the last, which overlaps a finder), then the interior grid.\n  // Scoring only the interior would give systematically different totals, and\n  // since the whole technique ranks transforms against each other, GPU and\n  // CPU would disagree about which corner is best — decoding that depends on\n  // the device is worse than not accelerating at all.\n  for (var i = 1u; i + 1u < params.centerCount; i = i + 1u) {\n    let c = f32(centers[i]);\n    score = score + cell(base, span, 6.0, c)\n          - ring(base, span, 6.0, c, 1.0)\n          + ring(base, span, 6.0, c, 2.0);\n    score = score + cell(base, span, c, 6.0)\n          - ring(base, span, c, 6.0, 1.0)\n          + ring(base, span, c, 6.0, 2.0);\n  }\n\n  for (var i = 1u; i < params.centerCount; i = i + 1u) {\n    for (var j = 1u; j < params.centerCount; j = j + 1u) {\n      let cx = f32(centers[i]);\n      let cy = f32(centers[j]);\n      score = score + cell(base, span, cx, cy)\n            - ring(base, span, cx, cy, 1.0)\n            + ring(base, span, cx, cy, 2.0);\n    }\n  }\n\n  scores[index] = score;\n}\n`;\n\n/** Scores many transforms against one image, on the GPU. */\nexport interface GpuScorer {\n  score(\n    image: BitMatrix,\n    transforms: readonly Transform[],\n    size: number,\n    alignmentCenters: readonly number[]\n  ): Promise<Int32Array>;\n  destroy(): void;\n}\n\n/** Whether this runtime exposes WebGPU at all. */\nexport const hasWebGpu = (): boolean =>\n  typeof navigator === `object` && `gpu` in navigator;\n\n/**\n * Create a GPU scorer, or `null` where WebGPU is unavailable.\n *\n * Returns `null` rather than throwing: every caller must have a CPU path\n * anyway, so an absent GPU is a normal condition and not an error.\n */\nexport const createGpuScorer = async (): Promise<GpuScorer | null> => {\n  if (!hasWebGpu()) return null;\n\n  // Narrowed through a runtime check rather than a cast: `navigator.gpu` is\n  // absent on every server runtime and on older browsers.\n  const gpu: unknown = (navigator as unknown as { gpu?: unknown }).gpu;\n  if (typeof gpu !== `object` || gpu === null) return null;\n\n  const adapter = await (\n    gpu as { requestAdapter: () => Promise<unknown> }\n  ).requestAdapter();\n  if (adapter === null || typeof adapter !== `object`) return null;\n\n  const device = await (\n    adapter as { requestDevice: () => Promise<GpuDeviceLike> }\n  ).requestDevice();\n\n  const module = device.createShaderModule({ code: SHADER });\n  const pipeline = device.createComputePipeline({\n    layout: `auto`,\n    compute: { module, entryPoint: `main` }\n  });\n\n  return {\n    score: async (image, transforms, size, alignmentCenters) => {\n      const count = transforms.length;\n      if (count === 0) return new Int32Array(0);\n\n      // One u32 per pixel. Packing to bits would quarter the upload but adds\n      // shifting in the inner loop, and the upload is not what costs here.\n      const bits = new Uint32Array(image.bits.length);\n      for (let i = 0; i < image.bits.length; i++) bits[i] = image.bits[i]!;\n\n      const flat = new Float32Array(count * 9);\n      for (const [index, transform] of transforms.entries()) {\n        const base = index * 9;\n        flat[base] = transform.a11;\n        flat[base + 1] = transform.a12;\n        flat[base + 2] = transform.a13;\n        flat[base + 3] = transform.a21;\n        flat[base + 4] = transform.a22;\n        flat[base + 5] = transform.a23;\n        flat[base + 6] = transform.a31;\n        flat[base + 7] = transform.a32;\n        flat[base + 8] = transform.a33;\n      }\n\n      const centers = Uint32Array.from(alignmentCenters);\n      const params = new Uint32Array([\n        image.width,\n        image.height,\n        size,\n        centers.length\n      ]);\n\n      const upload = (data: ArrayBufferView, usage: number): GpuBufferLike => {\n        const buffer = device.createBuffer({\n          size: Math.max(4, data.byteLength),\n          usage,\n          mappedAtCreation: true\n        });\n        new Uint8Array(buffer.getMappedRange()).set(\n          new Uint8Array(data.buffer, data.byteOffset, data.byteLength)\n        );\n        buffer.unmap();\n        return buffer;\n      };\n\n      const STORAGE = 0x80 | 0x4;\n      const UNIFORM = 0x40 | 0x4;\n      const COPY_SRC = 0x4;\n      const COPY_DST = 0x8;\n      const MAP_READ = 0x1;\n\n      const bitsBuffer = upload(bits, STORAGE);\n      const transformBuffer = upload(flat, STORAGE);\n      const centerBuffer = upload(\n        centers.length > 0 ? centers : new Uint32Array(1),\n        STORAGE\n      );\n      const paramsBuffer = upload(params, UNIFORM);\n\n      const scoreBuffer = device.createBuffer({\n        size: count * 4,\n        usage: 0x80 | COPY_SRC\n      });\n      const readBuffer = device.createBuffer({\n        size: count * 4,\n        usage: COPY_DST | MAP_READ\n      });\n\n      const bindGroup = device.createBindGroup({\n        layout: pipeline.getBindGroupLayout(0),\n        entries: [\n          { binding: 0, resource: { buffer: bitsBuffer } },\n          { binding: 1, resource: { buffer: transformBuffer } },\n          { binding: 2, resource: { buffer: centerBuffer } },\n          { binding: 3, resource: { buffer: scoreBuffer } },\n          { binding: 4, resource: { buffer: paramsBuffer } }\n        ]\n      });\n\n      const encoder = device.createCommandEncoder();\n      const pass = encoder.beginComputePass();\n      pass.setPipeline(pipeline);\n      pass.setBindGroup(0, bindGroup);\n      pass.dispatchWorkgroups(Math.ceil(count / 64));\n      pass.end();\n      encoder.copyBufferToBuffer(scoreBuffer, 0, readBuffer, 0, count * 4);\n      device.queue.submit([encoder.finish()]);\n\n      await readBuffer.mapAsync(MAP_READ);\n      const scores = new Int32Array(readBuffer.getMappedRange().slice(0));\n      readBuffer.unmap();\n\n      for (const buffer of [\n        bitsBuffer,\n        transformBuffer,\n        centerBuffer,\n        paramsBuffer,\n        scoreBuffer,\n        readBuffer\n      ]) {\n        buffer.destroy();\n      }\n\n      return scores;\n    },\n\n    destroy: () => {\n      device.destroy();\n    }\n  };\n};\n\n/**\n * The subset of WebGPU this module uses.\n *\n * Declared locally rather than pulled from a types package: this library ships\n * zero dependencies, and `@webgpu/types` would be one for a surface this\n * small.\n */\ninterface GpuBufferLike {\n  getMappedRange(): ArrayBuffer;\n  unmap(): void;\n  destroy(): void;\n  mapAsync(mode: number): Promise<void>;\n}\n\ninterface GpuDeviceLike {\n  createShaderModule(descriptor: { code: string }): unknown;\n  createComputePipeline(descriptor: {\n    layout: string;\n    compute: { module: unknown; entryPoint: string };\n  }): { getBindGroupLayout(index: number): unknown };\n  createBuffer(descriptor: {\n    size: number;\n    usage: number;\n    mappedAtCreation?: boolean;\n  }): GpuBufferLike;\n  createBindGroup(descriptor: {\n    layout: unknown;\n    entries: Array<{ binding: number; resource: { buffer: GpuBufferLike } }>;\n  }): unknown;\n  createCommandEncoder(): {\n    beginComputePass(): {\n      setPipeline(pipeline: unknown): void;\n      setBindGroup(index: number, group: unknown): void;\n      dispatchWorkgroups(count: number): void;\n      end(): void;\n    };\n    copyBufferToBuffer(\n      source: GpuBufferLike,\n      sourceOffset: number,\n      destination: GpuBufferLike,\n      destinationOffset: number,\n      size: number\n    ): void;\n    finish(): unknown;\n  };\n  queue: { submit(buffers: unknown[]): void };\n  destroy(): void;\n}\n","/**\n * A scan session, as a state machine.\n *\n * Modeled the way `machine.ts` models the device flow: states, events, and a\n * declarative transition table, hand-rolled so this stays dependency-free.\n *\n * Deliberately NOT applied to the decode pipeline itself. Binarize → locate →\n * extract → decode is a fallible sequential pipeline, not a machine: each\n * stage runs once per frame and either produces a value or does not. Modeling\n * it as states would add ceremony without making a single illegal move\n * impossible, which is the only thing a transition table buys.\n *\n * What IS a machine is the session around it — permission, camera lifecycle,\n * pause and resume — and that part is identical whether the frames are being\n * searched for a QR, a DataMatrix, or an Aztec code. So it lives here,\n * symbology-agnostic, and the decoders plug into it.\n */\n\n/**\n * Lifecycle of one scanning session.\n *\n * `scanning` is the only state that consumes frames. `decoded` is terminal\n * rather than a return to `scanning`: a scanner that kept reading after a\n * successful decode would fire twice on the same symbol, and every consumer\n * would have to debounce it. Restarting is explicit.\n *\n * `denied` is separate from `failed` because they are different conversations\n * with the user — one asks them to change a browser setting, the other is a\n * fault they cannot act on. Collapsing them is how a permission prompt ends up\n * reported as \"something went wrong\".\n */\nexport type ScanState =\n  | `idle`\n  | `starting`\n  | `scanning`\n  | `paused`\n  | `decoded`\n  | `denied`\n  | `failed`\n  | `stopped`;\n\n/** Why a scan session ended without a result. */\nexport type ScanFailure =\n  /** No camera on this device, or none matching the requested facing mode. */\n  | `no-camera`\n  /** The page is not a secure context, so `getUserMedia` is unavailable. */\n  | `insecure-context`\n  /** The camera was lost mid-session — unplugged, or claimed by another app. */\n  | `camera-lost`\n  /** The decoder itself threw. Distinct from \"no code in this frame\". */\n  | `decoder-error`;\n\n/** Events driving a scan session. */\nexport type ScanEvent =\n  /** Consumer asked to begin. */\n  | { type: `START` }\n  /** Camera acquired and frames are flowing. */\n  | { type: `READY` }\n  /** A frame decoded successfully. Terminal — restarting is explicit. */\n  | { type: `DECODE`; value: string }\n  /** The user refused camera access. */\n  | { type: `DENY` }\n  /** Something broke that the user cannot act on. */\n  | { type: `FAIL`; reason: ScanFailure }\n  /** Tab hidden, or the consumer suspended scanning. */\n  | { type: `PAUSE` }\n  /** Visible again. */\n  | { type: `RESUME` }\n  /** Consumer tore the session down. */\n  | { type: `STOP` };\n\n/**\n * Transitions, as a table.\n *\n * Everything absent is illegal by construction. That is what makes a `DECODE`\n * arriving after `STOP` a no-op rather than a race — a real hazard here,\n * because a decode in flight when the camera stops would otherwise resolve\n * into a torn-down session.\n */\nconst SCAN_TRANSITIONS: {\n  readonly [S in ScanState]?: {\n    readonly [E in ScanEvent[`type`]]?: ScanState;\n  };\n} = {\n  idle: {\n    START: `starting`\n  },\n  // Permission is resolved here, so this is the only state that can be denied.\n  starting: {\n    READY: `scanning`,\n    DENY: `denied`,\n    FAIL: `failed`,\n    STOP: `stopped`\n  },\n  scanning: {\n    DECODE: `decoded`,\n    PAUSE: `paused`,\n    FAIL: `failed`,\n    STOP: `stopped`\n  },\n  // No DECODE here: a paused session is not reading frames, and accepting one\n  // would mean a frame queued before the pause could resolve after it.\n  paused: {\n    RESUME: `scanning`,\n    FAIL: `failed`,\n    STOP: `stopped`\n  }\n};\n\n/** Whether `event` would move `state`. */\nexport const canTransitionScan = (\n  state: ScanState,\n  event: ScanEvent[`type`]\n): boolean => SCAN_TRANSITIONS[state]?.[event] !== undefined;\n\n/** Apply an event. Unknown events for the current state are no-ops. */\nexport const scanTransition = (state: ScanState, event: ScanEvent): ScanState =>\n  SCAN_TRANSITIONS[state]?.[event.type] ?? state;\n\n/**\n * Terminal states accept no further events.\n *\n * Derived from the table rather than listed, so a new state cannot be added\n * without its terminality following automatically.\n */\nexport const isScanSettled = (state: ScanState): boolean =>\n  SCAN_TRANSITIONS[state] === undefined;\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/scan/qr/progressive.ts","../../src/scan/gpu.ts","../../src/scan/machine.ts"],"sourcesContent":["/**\n * Scanning across frames rather than within one.\n *\n * The retry ladder is what makes difficult symbols readable, and it costs far\n * more than one frame can afford. Measured on the benchmark corpus, the\n * decoder reads **61.6%** with no time limit and **41.9%** at the 120ms\n * default a viewfinder needs — so a third of its capability is unreachable in\n * the configuration people actually run, and no budget recovers it: a sweep\n * showed recognition still climbing at 700ms.\n *\n * That is a false choice, because a camera is not a still image. It supplies\n * thirty frames a second, each nearly free and each slightly different. Ten\n * frames at 120ms is 1.2 seconds of decoding work at full frame rate, without\n * ever stalling the preview.\n *\n * So this spends a small budget per frame and ADVANCES through the ladder\n * across successive frames: cheap rungs on every frame, expensive ones only\n * once the cheap ones have failed repeatedly. A code held steadily in view\n * gets the whole ladder within a second; a frame with nothing in it costs one\n * cheap pass.\n *\n * The decoder itself stays pure and synchronous — this wraps it rather than\n * changing it, so a still image can still run the whole ladder at once.\n */\n\nimport type { DecodedSymbol, GrayImage } from \"../types.js\";\nimport { createQrDecoder, type QrDecoderOptions } from \"./decoder.js\";\n\n/** A scanner that improves its effort as frames arrive. */\nexport interface ProgressiveScanner {\n  /**\n   * Offer one frame.\n   *\n   * Returns a symbol as soon as one is read, and `null` otherwise — including\n   * while effort is still ramping up.\n   */\n  scan(image: GrayImage): DecodedSymbol | null;\n\n  /**\n   * Reset the effort ramp.\n   *\n   * Call when the scene changes — a new code presented, the camera moved\n   * somewhere else — so the next frame starts cheap again rather than\n   * inheriting effort earned by a symbol that is no longer there.\n   */\n  reset(): void;\n\n  /** How much effort the next frame will receive, in milliseconds. */\n  readonly budgetMs: number;\n}\n\n/** Options for {@link createProgressiveScanner}. */\nexport interface ProgressiveOptions extends Omit<\n  QrDecoderOptions,\n  `timeBudgetMs`\n> {\n  /**\n   * Budget for the first frame, in milliseconds.\n   *\n   * Deliberately small. Most frames a camera delivers contain no code at all,\n   * and this is what every one of them costs.\n   */\n  initialBudgetMs?: number;\n\n  /**\n   * Ceiling on the per-frame budget.\n   *\n   * 400ms by default: beyond that a single frame stalls the preview\n   * noticeably, and at 30fps the ladder has had a dozen frames to work with\n   * by the time the ramp reaches it.\n   */\n  maxBudgetMs?: number;\n\n  /**\n   * How much the budget grows per consecutive frame that shows a symbol.\n   *\n   * Growth is conditional on there being something to find: a frame with no\n   * finder candidate at all should not earn the next frame more time, or a\n   * camera pointed at a wall would ramp to its ceiling and stay there.\n   */\n  growth?: number;\n}\n\n/**\n * Create a scanner that spreads decoding effort across frames.\n *\n * The ramp is driven by evidence rather than by a timer. A frame in which the\n * decoder finds nothing resets it, because nothing is there to spend effort\n * on; a frame that finds a symbol but cannot read it raises the budget,\n * because that is exactly the case where more effort pays.\n */\nexport const createProgressiveScanner = ({\n  initialBudgetMs = 40,\n  maxBudgetMs = 400,\n  growth = 1.6,\n  ...decoderOptions\n}: ProgressiveOptions = {}): ProgressiveScanner => {\n  let budget = initialBudgetMs;\n\n  // One decoder per budget level, cached: constructing one is cheap, but a\n  // camera loop calls this thirty times a second and there are only a handful\n  // of distinct budgets in the ramp.\n  const decoders = new Map<number, ReturnType<typeof createQrDecoder>>();\n  const decoderFor = (ms: number): ReturnType<typeof createQrDecoder> => {\n    const existing = decoders.get(ms);\n    if (existing !== undefined) return existing;\n\n    const created = createQrDecoder({ ...decoderOptions, timeBudgetMs: ms });\n    decoders.set(ms, created);\n    return created;\n  };\n\n  return {\n    get budgetMs(): number {\n      return budget;\n    },\n\n    scan: (image: GrayImage): DecodedSymbol | null => {\n      const rounded = Math.round(budget);\n      const result = decoderFor(rounded).decode(image);\n\n      if (result !== null) {\n        // Read it. Drop back to the cheap budget: whatever comes next is a\n        // different scan, and starting expensive would waste effort on the\n        // frames after a successful read.\n        budget = initialBudgetMs;\n        return result;\n      }\n\n      // Nothing read. Spend more next time, up to the ceiling — the symbol may\n      // simply need more of the ladder than this frame could afford.\n      budget = Math.min(maxBudgetMs, budget * growth);\n      return null;\n    },\n\n    reset: (): void => {\n      budget = initialBudgetMs;\n    }\n  };\n};\n\n/**\n * Drive a decoder running in a worker.\n *\n * Same shape as {@link createProgressiveScanner} but asynchronous, because\n * the work happens elsewhere. The main thread stays free: measured on a hard\n * frame, an in-thread decode blocks 208ms at a 40ms budget and 481ms at\n * 400ms, which at 60fps is 12 and 28 dropped frames respectively — a visible\n * freeze on exactly the frames where someone is lining up a shot.\n *\n * Frames offered while a decode is in flight are DROPPED rather than queued.\n * A camera produces frames faster than they can be decoded, and a queue would\n * grow without bound while returning increasingly stale results; the next\n * frame is always a better input than a backlogged one.\n */\nexport interface WorkerScanner {\n  /** Offer a frame. Resolves `null` if dropped, still ramping, or unreadable. */\n  scan(image: GrayImage): Promise<DecodedSymbol | null>;\n  /** Reset the effort ramp — call when the scene changes. */\n  reset(): void;\n  /** Stop the worker and release it. */\n  close(): void;\n  /** Whether a decode is currently in flight. */\n  readonly busy: boolean;\n}\n\n/**\n * Wrap a worker in the progressive interface.\n *\n * The worker is supplied rather than constructed here, because how a worker\n * is created is a bundler question — `new Worker(new URL(...), { type:\n * \"module\" })` in Vite, a blob URL elsewhere — and a library that guessed\n * would be wrong for most consumers.\n */\nexport const createWorkerScanner = (\n  worker: {\n    // Declared as an overload pair, mirroring the DOM's own signature.\n    //\n    // This package compiles without the DOM lib on purpose, so the type is\n    // written out rather than referencing `Worker`. It has to be written out\n    // FAITHFULLY: the DOM declares postMessage as two overloads, one of which\n    // takes a REQUIRED transfer list. A single signature with an optional\n    // `transfer?` cannot match that — parameters are contravariant — so a real\n    // `new Worker(...)` fails to compile against it under `strict` while\n    // working perfectly at runtime, which is the worst kind of type error.\n    postMessage: {\n      (message: unknown, transfer: never[]): void;\n      (message: unknown, options?: unknown): void;\n    };\n    addEventListener?: (\n      type: string,\n      listener: (event: { data: unknown }) => void\n    ) => void;\n    on?: (type: string, listener: (message: unknown) => void) => void;\n    terminate?: () => void;\n  },\n  {\n    initialBudgetMs = 40,\n    maxBudgetMs = 400,\n    growth = 1.6\n  }: ProgressiveOptions = {}\n): WorkerScanner => {\n  let budget = initialBudgetMs;\n  let nextId = 0;\n  let inFlight = false;\n  const pending = new Map<\n    number,\n    (response: { result: DecodedSymbol | null }) => void\n  >();\n\n  const receive = (payload: unknown): void => {\n    // Narrowed by runtime checks rather than a cast: a DOM MessageEvent\n    // carries the payload on `.data` while a Node message IS the payload, and\n    // asserting one shape would silently misread the other.\n    if (payload === null || typeof payload !== `object`) return;\n\n    const envelope = payload as { data?: unknown };\n    const body: unknown =\n      typeof envelope.data === `object` && envelope.data !== null\n        ? envelope.data\n        : payload;\n\n    if (body === null || typeof body !== `object`) return;\n    if (!(`id` in body) || typeof body.id !== `number`) return;\n\n    const response = body as { id: number; result: DecodedSymbol | null };\n    const resolve = pending.get(response.id);\n    if (resolve === undefined) return;\n\n    pending.delete(response.id);\n    inFlight = false;\n    resolve(response);\n  };\n\n  if (typeof worker.addEventListener === `function`) {\n    worker.addEventListener(`message`, receive);\n  } else if (typeof worker.on === `function`) {\n    worker.on(`message`, receive);\n  }\n\n  return {\n    get busy(): boolean {\n      return inFlight;\n    },\n\n    scan: async (image: GrayImage): Promise<DecodedSymbol | null> => {\n      // Dropped rather than queued: a camera outruns the decoder, and a queue\n      // would grow unbounded while returning ever staler results.\n      if (inFlight) return null;\n\n      inFlight = true;\n      const id = nextId++;\n\n      const settled = new Promise<{ result: DecodedSymbol | null }>(\n        (resolve) => {\n          pending.set(id, resolve);\n        }\n      );\n\n      // Copied before transfer: transferring detaches the caller's buffer,\n      // and a caller reusing one frame buffer across frames — which is the\n      // normal pattern — would find it empty on the next read.\n      const copy = new Uint8ClampedArray(image.data);\n      worker.postMessage(\n        { id, data: copy, width: image.width, height: image.height },\n        [copy.buffer]\n      );\n\n      const { result } = await settled;\n\n      budget =\n        result === null\n          ? Math.min(maxBudgetMs, budget * growth)\n          : initialBudgetMs;\n\n      return result;\n    },\n\n    reset: (): void => {\n      budget = initialBudgetMs;\n    },\n\n    close: (): void => {\n      pending.clear();\n      inFlight = false;\n      worker.terminate?.();\n    }\n  };\n};\n","/**\n * GPU-accelerated transform scoring.\n *\n * One stage of this decoder is worth moving to the GPU and the rest are not.\n * Profiling a 1024x768 frame: binarization costs 16ms, blur 28ms, downscale\n * 6ms — all far too small to survive the cost of uploading a buffer,\n * dispatching a shader and reading the result back. But the corner search\n * makes **625 independent calls** to `scoreTransform` for about 179ms, which\n * is 78% of that stage and the largest single cost in the decoder.\n *\n * Those 625 calls score the same image under different transforms, share no\n * state, and each reads a few hundred pixels. That is the shape GPU compute\n * exists for: one upload of the image, 625 workgroups, one small readback.\n *\n * Availability is unusually good for a modern web API. WebGPU shipped\n * enabled-by-default in iOS 26, macOS Tahoe 26 and iPadOS 26, which removed\n * the last major holdout — so unlike `BarcodeDetector`, this is something the\n * target platforms actually have. It still degrades to the CPU path\n * everywhere else, because a scanner that only works on new hardware is not a\n * scanner.\n */\n\nimport type { BitMatrix } from \"./types.js\";\nimport type { Transform } from \"./qr/sample.js\";\n\n/**\n * The scoring kernel.\n *\n * Mirrors `scoreTransform` exactly — same nine-point module sampling, same\n * ring structure, same weights. Any divergence would make GPU and CPU\n * disagree about which transform is best, which is worse than not\n * accelerating at all: results would depend on the device.\n */\nconst SHADER = `\nstruct Params {\n  width: u32,\n  height: u32,\n  size: u32,\n  centerCount: u32,\n};\n\n@group(0) @binding(0) var<storage, read> bits: array<u32>;\n@group(0) @binding(1) var<storage, read> transforms: array<f32>;\n@group(0) @binding(2) var<storage, read> centers: array<u32>;\n@group(0) @binding(3) var<storage, read_write> scores: array<i32>;\n@group(0) @binding(4) var<uniform> params: Params;\n\nfn pixel(x: i32, y: i32) -> i32 {\n  if (x < 0 || y < 0 || x >= i32(params.width) || y >= i32(params.height)) {\n    return 0;\n  }\n  let index = u32(y) * params.width + u32(x);\n  // Bits are packed one per u32 for simplicity: the readback is tiny and the\n  // upload happens once per frame, so the memory is not the bottleneck.\n  return select(-1, 1, bits[index] == 1u);\n}\n\nfn mapPoint(base: u32, x: f32, y: f32) -> vec2<f32> {\n  let a11 = transforms[base + 0u];\n  let a12 = transforms[base + 1u];\n  let a13 = transforms[base + 2u];\n  let a21 = transforms[base + 3u];\n  let a22 = transforms[base + 4u];\n  let a23 = transforms[base + 5u];\n  let a31 = transforms[base + 6u];\n  let a32 = transforms[base + 7u];\n  let a33 = transforms[base + 8u];\n\n  let w = a13 * x + a23 * y + a33;\n  if (abs(w) < 1e-9) { return vec2<f32>(-1.0, -1.0); }\n  return vec2<f32>((a11 * x + a21 * y + a31) / w, (a12 * x + a22 * y + a32) / w);\n}\n\nfn cell(base: u32, span: f32, mx: f32, my: f32) -> i32 {\n  var score = 0;\n  let offsets = array<f32, 3>(0.3, 0.5, 0.7);\n  for (var v = 0u; v < 3u; v = v + 1u) {\n    for (var u = 0u; u < 3u; u = u + 1u) {\n      let p = mapPoint(base, (mx + offsets[u] - 3.5) / span, (my + offsets[v] - 3.5) / span);\n      score = score + pixel(i32(round(p.x)), i32(round(p.y)));\n    }\n  }\n  return score;\n}\n\nfn ring(base: u32, span: f32, cx: f32, cy: f32, radius: f32) -> i32 {\n  var score = 0;\n  let steps = i32(radius * 2.0);\n  for (var i = 0; i < steps; i = i + 1) {\n    let f = f32(i);\n    score = score + cell(base, span, cx - radius + f, cy - radius);\n    score = score + cell(base, span, cx - radius, cy + radius - f);\n    score = score + cell(base, span, cx + radius, cy - radius + f);\n    score = score + cell(base, span, cx + radius - f, cy + radius);\n  }\n  return score;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  let index = id.x;\n  if (index >= arrayLength(&scores)) { return; }\n\n  let base = index * 9u;\n  let size = f32(params.size);\n  let span = size - 7.0;\n  var score = 0;\n\n  // Timing patterns alternate; the expected value flips each module.\n  for (var i = 0u; i < params.size - 14u; i = i + 1u) {\n    let expected = select(-1, 1, (i & 1u) == 1u);\n    score = score + cell(base, span, f32(i) + 7.0, 6.0) * expected;\n    score = score + cell(base, span, 6.0, f32(i) + 7.0) * expected;\n  }\n\n  // Finders: dark centre, dark ring, light ring, dark ring.\n  let corners = array<vec2<f32>, 3>(\n    vec2<f32>(0.0, 0.0),\n    vec2<f32>(size - 7.0, 0.0),\n    vec2<f32>(0.0, size - 7.0)\n  );\n  for (var c = 0u; c < 3u; c = c + 1u) {\n    let x = corners[c].x + 3.0;\n    let y = corners[c].y + 3.0;\n    score = score + cell(base, span, x, y)\n          + ring(base, span, x, y, 1.0)\n          - ring(base, span, x, y, 2.0)\n          + ring(base, span, x, y, 3.0);\n  }\n\n  // Alignment patterns: dark centre, light ring, dark ring.\n  //\n  // Two groups, matching the CPU exactly. The edge row and column come first\n  // (skipping the last, which overlaps a finder), then the interior grid.\n  // Scoring only the interior would give systematically different totals, and\n  // since the whole technique ranks transforms against each other, GPU and\n  // CPU would disagree about which corner is best — decoding that depends on\n  // the device is worse than not accelerating at all.\n  for (var i = 1u; i + 1u < params.centerCount; i = i + 1u) {\n    let c = f32(centers[i]);\n    score = score + cell(base, span, 6.0, c)\n          - ring(base, span, 6.0, c, 1.0)\n          + ring(base, span, 6.0, c, 2.0);\n    score = score + cell(base, span, c, 6.0)\n          - ring(base, span, c, 6.0, 1.0)\n          + ring(base, span, c, 6.0, 2.0);\n  }\n\n  for (var i = 1u; i < params.centerCount; i = i + 1u) {\n    for (var j = 1u; j < params.centerCount; j = j + 1u) {\n      let cx = f32(centers[i]);\n      let cy = f32(centers[j]);\n      score = score + cell(base, span, cx, cy)\n            - ring(base, span, cx, cy, 1.0)\n            + ring(base, span, cx, cy, 2.0);\n    }\n  }\n\n  scores[index] = score;\n}\n`;\n\n/** Scores many transforms against one image, on the GPU. */\nexport interface GpuScorer {\n  score(\n    image: BitMatrix,\n    transforms: readonly Transform[],\n    size: number,\n    alignmentCenters: readonly number[]\n  ): Promise<Int32Array>;\n  destroy(): void;\n}\n\n/** Whether this runtime exposes WebGPU at all. */\nexport const hasWebGpu = (): boolean =>\n  typeof navigator === `object` && `gpu` in navigator;\n\n/**\n * Create a GPU scorer, or `null` where WebGPU is unavailable.\n *\n * Returns `null` rather than throwing: every caller must have a CPU path\n * anyway, so an absent GPU is a normal condition and not an error.\n */\nexport const createGpuScorer = async (): Promise<GpuScorer | null> => {\n  if (!hasWebGpu()) return null;\n\n  // Narrowed through a runtime check rather than a cast: `navigator.gpu` is\n  // absent on every server runtime and on older browsers.\n  const gpu: unknown = (navigator as unknown as { gpu?: unknown }).gpu;\n  if (typeof gpu !== `object` || gpu === null) return null;\n\n  const adapter = await (\n    gpu as { requestAdapter: () => Promise<unknown> }\n  ).requestAdapter();\n  if (adapter === null || typeof adapter !== `object`) return null;\n\n  const device = await (\n    adapter as { requestDevice: () => Promise<GpuDeviceLike> }\n  ).requestDevice();\n\n  const module = device.createShaderModule({ code: SHADER });\n  const pipeline = device.createComputePipeline({\n    layout: `auto`,\n    compute: { module, entryPoint: `main` }\n  });\n\n  return {\n    score: async (image, transforms, size, alignmentCenters) => {\n      const count = transforms.length;\n      if (count === 0) return new Int32Array(0);\n\n      // One u32 per pixel. Packing to bits would quarter the upload but adds\n      // shifting in the inner loop, and the upload is not what costs here.\n      const bits = new Uint32Array(image.bits.length);\n      for (let i = 0; i < image.bits.length; i++) bits[i] = image.bits[i]!;\n\n      const flat = new Float32Array(count * 9);\n      for (const [index, transform] of transforms.entries()) {\n        const base = index * 9;\n        flat[base] = transform.a11;\n        flat[base + 1] = transform.a12;\n        flat[base + 2] = transform.a13;\n        flat[base + 3] = transform.a21;\n        flat[base + 4] = transform.a22;\n        flat[base + 5] = transform.a23;\n        flat[base + 6] = transform.a31;\n        flat[base + 7] = transform.a32;\n        flat[base + 8] = transform.a33;\n      }\n\n      const centers = Uint32Array.from(alignmentCenters);\n      const params = new Uint32Array([\n        image.width,\n        image.height,\n        size,\n        centers.length\n      ]);\n\n      const upload = (data: ArrayBufferView, usage: number): GpuBufferLike => {\n        const buffer = device.createBuffer({\n          size: Math.max(4, data.byteLength),\n          usage,\n          mappedAtCreation: true\n        });\n        new Uint8Array(buffer.getMappedRange()).set(\n          new Uint8Array(data.buffer, data.byteOffset, data.byteLength)\n        );\n        buffer.unmap();\n        return buffer;\n      };\n\n      const STORAGE = 0x80 | 0x4;\n      const UNIFORM = 0x40 | 0x4;\n      const COPY_SRC = 0x4;\n      const COPY_DST = 0x8;\n      const MAP_READ = 0x1;\n\n      const bitsBuffer = upload(bits, STORAGE);\n      const transformBuffer = upload(flat, STORAGE);\n      const centerBuffer = upload(\n        centers.length > 0 ? centers : new Uint32Array(1),\n        STORAGE\n      );\n      const paramsBuffer = upload(params, UNIFORM);\n\n      const scoreBuffer = device.createBuffer({\n        size: count * 4,\n        usage: 0x80 | COPY_SRC\n      });\n      const readBuffer = device.createBuffer({\n        size: count * 4,\n        usage: COPY_DST | MAP_READ\n      });\n\n      const bindGroup = device.createBindGroup({\n        layout: pipeline.getBindGroupLayout(0),\n        entries: [\n          { binding: 0, resource: { buffer: bitsBuffer } },\n          { binding: 1, resource: { buffer: transformBuffer } },\n          { binding: 2, resource: { buffer: centerBuffer } },\n          { binding: 3, resource: { buffer: scoreBuffer } },\n          { binding: 4, resource: { buffer: paramsBuffer } }\n        ]\n      });\n\n      const encoder = device.createCommandEncoder();\n      const pass = encoder.beginComputePass();\n      pass.setPipeline(pipeline);\n      pass.setBindGroup(0, bindGroup);\n      pass.dispatchWorkgroups(Math.ceil(count / 64));\n      pass.end();\n      encoder.copyBufferToBuffer(scoreBuffer, 0, readBuffer, 0, count * 4);\n      device.queue.submit([encoder.finish()]);\n\n      await readBuffer.mapAsync(MAP_READ);\n      const scores = new Int32Array(readBuffer.getMappedRange().slice(0));\n      readBuffer.unmap();\n\n      for (const buffer of [\n        bitsBuffer,\n        transformBuffer,\n        centerBuffer,\n        paramsBuffer,\n        scoreBuffer,\n        readBuffer\n      ]) {\n        buffer.destroy();\n      }\n\n      return scores;\n    },\n\n    destroy: () => {\n      device.destroy();\n    }\n  };\n};\n\n/**\n * The subset of WebGPU this module uses.\n *\n * Declared locally rather than pulled from a types package: this library ships\n * zero dependencies, and `@webgpu/types` would be one for a surface this\n * small.\n */\ninterface GpuBufferLike {\n  getMappedRange(): ArrayBuffer;\n  unmap(): void;\n  destroy(): void;\n  mapAsync(mode: number): Promise<void>;\n}\n\ninterface GpuDeviceLike {\n  createShaderModule(descriptor: { code: string }): unknown;\n  createComputePipeline(descriptor: {\n    layout: string;\n    compute: { module: unknown; entryPoint: string };\n  }): { getBindGroupLayout(index: number): unknown };\n  createBuffer(descriptor: {\n    size: number;\n    usage: number;\n    mappedAtCreation?: boolean;\n  }): GpuBufferLike;\n  createBindGroup(descriptor: {\n    layout: unknown;\n    entries: Array<{ binding: number; resource: { buffer: GpuBufferLike } }>;\n  }): unknown;\n  createCommandEncoder(): {\n    beginComputePass(): {\n      setPipeline(pipeline: unknown): void;\n      setBindGroup(index: number, group: unknown): void;\n      dispatchWorkgroups(count: number): void;\n      end(): void;\n    };\n    copyBufferToBuffer(\n      source: GpuBufferLike,\n      sourceOffset: number,\n      destination: GpuBufferLike,\n      destinationOffset: number,\n      size: number\n    ): void;\n    finish(): unknown;\n  };\n  queue: { submit(buffers: unknown[]): void };\n  destroy(): void;\n}\n","/**\n * A scan session, as a state machine.\n *\n * Modeled the way `machine.ts` models the device flow: states, events, and a\n * declarative transition table, hand-rolled so this stays dependency-free.\n *\n * Deliberately NOT applied to the decode pipeline itself. Binarize → locate →\n * extract → decode is a fallible sequential pipeline, not a machine: each\n * stage runs once per frame and either produces a value or does not. Modeling\n * it as states would add ceremony without making a single illegal move\n * impossible, which is the only thing a transition table buys.\n *\n * What IS a machine is the session around it — permission, camera lifecycle,\n * pause and resume — and that part is identical whether the frames are being\n * searched for a QR, a DataMatrix, or an Aztec code. So it lives here,\n * symbology-agnostic, and the decoders plug into it.\n */\n\n/**\n * Lifecycle of one scanning session.\n *\n * `scanning` is the only state that consumes frames. `decoded` is terminal\n * rather than a return to `scanning`: a scanner that kept reading after a\n * successful decode would fire twice on the same symbol, and every consumer\n * would have to debounce it. Restarting is explicit.\n *\n * `denied` is separate from `failed` because they are different conversations\n * with the user — one asks them to change a browser setting, the other is a\n * fault they cannot act on. Collapsing them is how a permission prompt ends up\n * reported as \"something went wrong\".\n */\nexport type ScanState =\n  | `idle`\n  | `starting`\n  | `scanning`\n  | `paused`\n  | `decoded`\n  | `denied`\n  | `failed`\n  | `stopped`;\n\n/** Why a scan session ended without a result. */\nexport type ScanFailure =\n  /** No camera on this device, or none matching the requested facing mode. */\n  | `no-camera`\n  /** The page is not a secure context, so `getUserMedia` is unavailable. */\n  | `insecure-context`\n  /** The camera was lost mid-session — unplugged, or claimed by another app. */\n  | `camera-lost`\n  /** The decoder itself threw. Distinct from \"no code in this frame\". */\n  | `decoder-error`;\n\n/** Events driving a scan session. */\nexport type ScanEvent =\n  /** Consumer asked to begin. */\n  | { type: `START` }\n  /** Camera acquired and frames are flowing. */\n  | { type: `READY` }\n  /** A frame decoded successfully. Terminal — restarting is explicit. */\n  | { type: `DECODE`; value: string }\n  /** The user refused camera access. */\n  | { type: `DENY` }\n  /** Something broke that the user cannot act on. */\n  | { type: `FAIL`; reason: ScanFailure }\n  /** Tab hidden, or the consumer suspended scanning. */\n  | { type: `PAUSE` }\n  /** Visible again. */\n  | { type: `RESUME` }\n  /** Consumer tore the session down. */\n  | { type: `STOP` };\n\n/**\n * Transitions, as a table.\n *\n * Everything absent is illegal by construction. That is what makes a `DECODE`\n * arriving after `STOP` a no-op rather than a race — a real hazard here,\n * because a decode in flight when the camera stops would otherwise resolve\n * into a torn-down session.\n */\nconst SCAN_TRANSITIONS: {\n  readonly [S in ScanState]?: {\n    readonly [E in ScanEvent[`type`]]?: ScanState;\n  };\n} = {\n  idle: {\n    START: `starting`\n  },\n  // Permission is resolved here, so this is the only state that can be denied.\n  starting: {\n    READY: `scanning`,\n    DENY: `denied`,\n    FAIL: `failed`,\n    STOP: `stopped`\n  },\n  scanning: {\n    DECODE: `decoded`,\n    PAUSE: `paused`,\n    FAIL: `failed`,\n    STOP: `stopped`\n  },\n  // No DECODE here: a paused session is not reading frames, and accepting one\n  // would mean a frame queued before the pause could resolve after it.\n  paused: {\n    RESUME: `scanning`,\n    FAIL: `failed`,\n    STOP: `stopped`\n  }\n};\n\n/** Whether `event` would move `state`. */\nexport const canTransitionScan = (\n  state: ScanState,\n  event: ScanEvent[`type`]\n): boolean => SCAN_TRANSITIONS[state]?.[event] !== undefined;\n\n/** Apply an event. Unknown events for the current state are no-ops. */\nexport const scanTransition = (state: ScanState, event: ScanEvent): ScanState =>\n  SCAN_TRANSITIONS[state]?.[event.type] ?? state;\n\n/**\n * Terminal states accept no further events.\n *\n * Derived from the table rather than listed, so a new state cannot be added\n * without its terminality following automatically.\n */\nexport const isScanSettled = (state: ScanState): boolean =>\n  SCAN_TRANSITIONS[state] === undefined;\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saeris/hanko",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "QR-assisted device sign-in (OAuth 2.0 Device Authorization Grant, RFC 8628) for TVs, kiosks, and anything without a keyboard",
   "keywords": [
     "oauth",