@saeris/hanko 0.0.0 → 0.2.1

package/dist/worker-DxbdBA2z.d.mts

@@ -0,0 +1,164 @@
+//#region src/scan/types.d.ts
+/**
+ * The vocabulary every symbology decoder shares.
+ *
+ * Kept separate from any one decoder so that adding DataMatrix or Aztec later
+ * means writing a `SymbolDecoder`, not restructuring the session around it.
+ */
+/**
+ * A greyscale image.
+ *
+ * Greyscale rather than RGBA because every stage after acquisition works on
+ * luminance: binarization, finder detection, and sampling all discard colour
+ * immediately. Converting once at the boundary means the pipeline never
+ * carries three redundant channels through its hot loops.
+ */
+interface GrayImage {
+  /** One byte per pixel, row-major, `width * height` long. */
+  readonly data: Uint8ClampedArray;
+  readonly width: number;
+  readonly height: number;
+}
+/**
+ * A bit matrix — the output of binarization and the input to every decoder.
+ *
+ * `true` is a *set* module, which by QR convention means DARK. Polarity is
+ * resolved during binarization, not here, so a decoder never has to ask which
+ * way round its input is. That question is exactly what broke the approval
+ * screen against an inverted symbol.
+ */
+interface BitMatrix {
+  /** Row-major bits, `width * height` long. */
+  readonly bits: Uint8Array;
+  readonly width: number;
+  readonly height: number;
+}
+/** A point in image space. Sub-pixel, because finder centres rarely land on one. */
+interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+/** What a successful decode yields. */
+interface DecodedSymbol {
+  /** The decoded payload. */
+  readonly value: string;
+  /**
+   * The symbology that produced it, as a BarcodeDetector-compatible name.
+   *
+   * Shaped to match that API without depending on it: if it ever ships, a
+   * compatibility layer is a rename, not a redesign.
+   */
+  readonly format: `qr_code`;
+  /** Corners in image space, clockwise from top-left. */
+  readonly cornerPoints: readonly Point[];
+}
+/**
+ * What the session needs from a decoder.
+ *
+ * One method, deliberately. A decoder that also owned frame acquisition or
+ * camera lifecycle could not be tested without a browser — and the whole point
+ * of this seam is that everything below it is pure.
+ *
+ * Returns `null` rather than throwing when no symbol is present: a camera
+ * pointed at a room sees frames without codes constantly, and that is a
+ * non-event, not an error. Throwing is reserved for a genuine fault.
+ */
+interface SymbolDecoder {
+  decode(image: GrayImage): DecodedSymbol | null;
+}
+//#endregion
+//#region src/scan/qr/decoder.d.ts
+/** Options for {@link createQrDecoder}. */
+interface QrDecoderOptions {
+  /**
+   * Which polarities to attempt.
+   *
+   * `both` by default. `dark-on-light` is the conventional rendering and is
+   * marginally faster; choose it only when you control every symbol the
+   * scanner will ever see.
+   */
+  polarity?: `both` | `dark-on-light` | `light-on-dark`;
+  /**
+   * Milliseconds to spend before giving up, or `0` for no limit.
+   *
+   * The retry ladder is what reads difficult images, and it is priced for a
+   * still photograph rather than a viewfinder. Measured on 1024x768 frames, a
+   * symbol that decodes costs 12 to 32ms while one that cannot be read at all
+   * costs 570 to 700 — roughly 25 times more, and the early exit cannot help
+   * because a finder pattern genuinely is present.
+   *
+   * That asymmetry is backwards for a camera: the expensive case happens
+   * exactly when someone is holding the phone at a bad angle and moving it, so
+   * a scanner that reads 43% of stills would stutter at under two frames a
+   * second precisely when the user is trying to line up a shot. The next frame
+   * is nearly free and probably better, so spending 700ms on this one is a bad
+   * trade in a live loop and a good one for a single still.
+   *
+   * Defaults to 120ms, which fits comfortably inside a frame at 5 scans per
+   * second. Set `0` when decoding a still image, where the whole ladder is
+   * worth running.
+   */
+  timeBudgetMs?: number;
+  /**
+   * Retry with a low-pass filter when the sharp pass finds nothing.
+   *
+   * On by default, and it is what makes a code on a SCREEN readable: moire
+   * banding is frequency aliasing between the camera sensor and the display's
+   * sub-pixel grid, so it sits at a higher spatial frequency than the modules
+   * and blurs away while they survive. Measured on the benchmark corpus this
+   * takes the `monitor` category from 0 of 25 to 10 of 25 — and since this
+   * library's own device screen is scanned off a TV, that is not a niche case.
+   *
+   * A retry rather than a default pass, because the same filter destroys
+   * already-blurry photographs: `blurred` drops from 5 of 14 to 1, `nominal`
+   * from 3 to 0. Costs nothing on images that decode sharp.
+   */
+  retryBlurred?: boolean;
+}
+/**
+ * Create a QR decoder.
+ *
+ * The returned decoder is pure and synchronous: it holds no camera, no canvas,
+ * and no DOM reference, which is what lets the same instance run on a worker,
+ * a server, or in a test with no browser at all.
+ */
+declare const createQrDecoder: ({ polarity, retryBlurred, timeBudgetMs }?: QrDecoderOptions) => SymbolDecoder;
+//#endregion
+//#region src/scan/worker.d.ts
+/** A frame handed to the worker. */
+interface DecodeRequest {
+  /** Correlates the reply, since frames may be in flight concurrently. */
+  readonly id: number;
+  readonly data: Uint8ClampedArray;
+  readonly width: number;
+  readonly height: number;
+}
+/** The worker's reply. */
+interface DecodeResponse {
+  readonly id: number;
+  readonly result: DecodedSymbol | null;
+  /** Wall-clock time the decode took, for callers pacing their own requests. */
+  readonly elapsedMs: number;
+}
+/**
+ * Wire a worker scope to a decoder.
+ *
+ * Call from a worker entry module:
+ *
+ * ```ts
+ * import { serveDecoder } from "@saeris/hanko/scan/worker";
+ * serveDecoder(self);
+ * ```
+ *
+ * The scope is passed in rather than reached for, so this stays testable
+ * without a worker and works under any host that provides the same two
+ * methods — a DOM `Worker`, a Node `parentPort`, or a stub.
+ */
+declare const serveDecoder: (scope: {
+  addEventListener?: (type: string, listener: (event: unknown) => void) => void;
+  on?: (type: string, listener: (message: unknown) => void) => void;
+  postMessage: (message: unknown) => void;
+}, options?: QrDecoderOptions) => void;
+//#endregion
+export { createQrDecoder as a, GrayImage as c, QrDecoderOptions as i, Point as l, DecodeResponse as n, BitMatrix as o, serveDecoder as r, DecodedSymbol as s, DecodeRequest as t, SymbolDecoder as u };
+//# sourceMappingURL=worker-DxbdBA2z.d.mts.map

package/dist/worker-DxbdBA2z.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-DxbdBA2z.d.mts","names":[],"sources":["../src/scan/types.ts","../src/scan/qr/decoder.ts","../src/scan/worker.ts"],"mappings":";;;;;;;;;;;;;;;UAeiB;;WAEN,MAAM;WACN;WACA;;;;;;;;;;UAWM;;WAEN,MAAM;WACN;WACA;;;UAIM;WACN;WACA;;;UAIM;;WAEN;;;;;;;WAOA;;WAEA,uBAAuB;;;;;;;;;;;;;UAcjB;EACf,OAAO,OAAO,YAAY;;;;;UCRX;;;;;;;;EAQf;;;;;;;;;;;;;;;;;;;;;EAsBA;;;;;;;;;;;;;;;EAgBA;;;;;;;;;cA2eW,oBAAmB,UAAA,cAAA,iBAI7B,qBAAwB;;;;UC/jBV;;WAEN;WACA,MAAM;WACN;WACA;;;UAIM;WACN;WACA,QAAQ;;WAER;;;;;;;;;;;;;;;;cAiBE,eACX;EACE,oBACE,cACA,WAAW;EAEb,MAAM,cAAc,WAAW;EAC/B,cAAc;GAEhB,UAAS"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saeris/hanko",
-  "version": "0.0.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",
@@ -14,11 +14,124 @@
     "tv",
     "kiosk"
   ],
+  "homepage": "https://github.com/Saeris/hanko#readme",
+  "bugs": "https://github.com/Saeris/hanko/issues",
   "license": "MIT",
   "author": "Drake Costa <drake@saeris.gg> (https://saeris.gg)",
-  "homepage": "https://github.com/Saeris/hanko#readme",
   "repository": {
     "type": "git",
     "url": "https://github.com/Saeris/hanko.git"
+  },
+  "workspaces": [
+    ".",
+    "examples/*"
+  ],
+  "files": [
+    "dist/**/*"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "development": "./src/index.ts",
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    },
+    "./qr": {
+      "import": {
+        "development": "./src/qr.ts",
+        "types": "./dist/qr.d.mts",
+        "default": "./dist/qr.mjs"
+      }
+    },
+    "./client": {
+      "import": {
+        "development": "./src/client/index.ts",
+        "types": "./dist/client/index.d.mts",
+        "default": "./dist/client/index.mjs"
+      }
+    },
+    "./approve": {
+      "import": {
+        "development": "./src/approve/index.ts",
+        "types": "./dist/approve/index.d.mts",
+        "default": "./dist/approve/index.mjs"
+      }
+    },
+    "./scan": {
+      "import": {
+        "development": "./src/scan/index.ts",
+        "types": "./dist/scan/index.d.mts",
+        "default": "./dist/scan/index.mjs"
+      }
+    },
+    "./scan/worker": {
+      "import": {
+        "development": "./src/scan/worker.ts",
+        "types": "./dist/scan/worker.d.mts",
+        "default": "./dist/scan/worker.mjs"
+      }
+    },
+    "./handlers": {
+      "import": {
+        "development": "./src/handlers.ts",
+        "types": "./dist/handlers.d.mts",
+        "default": "./dist/handlers.mjs"
+      }
+    },
+    "./stores/memory": {
+      "import": {
+        "development": "./src/stores/memory.ts",
+        "types": "./dist/stores/memory.d.mts",
+        "default": "./dist/stores/memory.mjs"
+      }
+    },
+    "./stores/kv": {
+      "import": {
+        "development": "./src/stores/kv.ts",
+        "types": "./dist/stores/kv.d.mts",
+        "default": "./dist/stores/kv.mjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "bench": "node bench/decode.mjs",
+    "bench:corpus": "node bench/corpus.mjs",
+    "build": "vp pack",
+    "check": "vp check",
+    "ci": "vp pack && vp check && vp test",
+    "corpus": "node scripts/fetch-corpus.mjs",
+    "demo": "vp pack && yarn workspace @saeris/hanko-example-astro run dev",
+    "demo:share": "vp pack && yarn workspace @saeris/hanko-example-astro run share",
+    "format": "vp check --fix",
+    "test": "vp test --fileParallelism"
+  },
+  "devDependencies": {
+    "@saeris/configs": "1.6.1",
+    "@types/node": "^25.9.1",
+    "@varlock/bumpy": "^1.7.0",
+    "etiket": "^0.12.0",
+    "typescript": "^6.0.3",
+    "vite-plus": "0.2.9",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "yarn@4.18.0",
+  "peerDependencies": {
+    "etiket": "^0.12.0"
+  },
+  "peerDependenciesMeta": {
+    "etiket": {
+      "optional": true
+    }
   }
-}
+}