@dejadex/web 0.0.0-stage → 0.1.0

package/src/identify/server.ts

@@ -0,0 +1,167 @@
+/**
+ * The client of `POST /v1/identify`: crops out, the same answer shape the
+ * device produces back. One call is one request, bounded by one deadline that
+ * covers the headers and the body; the answer is validated field by field,
+ * never trusted.
+ */
+import { anySignal } from './assets.js'
+import { MAX_TOP, type IdentifyCandidate, type IdentifyKind, type IdentifyPurpose, type IdentifyResult } from './types.js'
+
+export type ServerFetch = (input: string, init: { method: 'POST'; body: FormData; headers: Record<string, string>; signal: AbortSignal }) => Promise<Response>
+
+export interface ServerRequest {
+  readonly endpoint: string
+  readonly crops: readonly Blob[]
+  /** The lease, as bearer. */
+  readonly token: string
+  readonly top: number
+  readonly session?: string
+  readonly purpose?: IdentifyPurpose
+  readonly timeoutMs: number
+  readonly signal?: AbortSignal
+  readonly fetch: ServerFetch
+}
+
+export type ServerFailureKind =
+  /** The deadline passed. */
+  | 'timeout'
+  /** The caller aborted. */
+  | 'aborted'
+  /** No answer at all: offline, DNS, CORS, connection reset. */
+  | 'network'
+  /** 401 / 403 / 409: this lease (its origin, domains, tenant or model version) is refused. */
+  | 'refused'
+  /** 429, with `retryAfterMs`. */
+  | 'rate_limited'
+  /** 5xx. */
+  | 'server_error'
+  /** Another 4xx: something about this request (e.g. a crop that is not a JPEG). */
+  | 'bad_request'
+  /** A 2xx whose body is not the contract. */
+  | 'malformed'
+
+export type ServerAnswer =
+  | { readonly ok: true; readonly modelVersion: string; readonly results: readonly IdentifyResult[] }
+  | { readonly ok: false; readonly kind: ServerFailureKind; readonly status?: number; readonly retryAfterMs?: number; readonly detail: string }
+
+const errorText = (err: unknown): string => (err instanceof Error ? err.message || err.name : String(err))
+
+/** `Retry-After` as delay-seconds or an HTTP date; null when absent or unreadable. */
+export function parseRetryAfter(value: string | null, now: number): number | null {
+  if (value === null) return null
+  const v = value.trim()
+  if (/^\d+$/.test(v)) return Number(v) * 1000
+  const at = Date.parse(v)
+  return Number.isNaN(at) ? null : Math.max(0, at - now)
+}
+
+export async function postIdentify(req: ServerRequest): Promise<ServerAnswer> {
+  if (req.signal?.aborted) return { ok: false, kind: 'aborted', detail: 'aborted' }
+  const deadline = AbortSignal.timeout(req.timeoutMs)
+  const signal = anySignal([deadline, req.signal])
+
+  const body = new FormData()
+  req.crops.forEach((crop, i) => body.append(`crop${i}`, crop, `crop${i}.jpg`))
+  body.append('top', String(req.top))
+  if (req.session !== undefined) body.append('session', req.session)
+  if (req.purpose !== undefined) body.append('purpose', req.purpose)
+
+  // Which signal fired decides the outcome, not the error's name: runtimes
+  // disagree on what they throw for each.
+  const failed = (kind: ServerFailureKind, detail: string, extra: { status?: number; retryAfterMs?: number } = {}): ServerAnswer => {
+    if (req.signal?.aborted) return { ok: false, kind: 'aborted', detail: 'aborted' }
+    if (deadline.aborted) return { ok: false, kind: 'timeout', detail: `no answer within ${req.timeoutMs} ms` }
+    return { ok: false, kind, detail, ...extra }
+  }
+
+  let res: Response
+  try {
+    res = await req.fetch(req.endpoint, { method: 'POST', body, headers: { Authorization: `Bearer ${req.token}` }, signal })
+  } catch (err) {
+    return failed('network', errorText(err))
+  }
+  let data: unknown
+  try {
+    // Inside the same deadline as the request: a slow body is a late answer.
+    const type = res.headers.get('content-type') ?? ''
+    if (/[/+]json\b/i.test(type)) data = await res.json()
+    else await res.text() // drained, so a slow body still counts against the deadline
+  } catch (err) {
+    return failed(res.ok ? 'malformed' : 'server_error', `unreadable answer: ${errorText(err)}`, { status: res.status })
+  }
+  if (!res.ok) {
+    const detail = problemText(res.status, data)
+    if (res.status === 401 || res.status === 403 || res.status === 409) return failed('refused', detail, { status: res.status })
+    if (res.status === 429) {
+      const retryAfterMs = parseRetryAfter(res.headers.get('retry-after'), Date.now()) ?? 10_000
+      return failed('rate_limited', detail, { status: res.status, retryAfterMs })
+    }
+    if (res.status >= 500) return failed('server_error', detail, { status: res.status })
+    return failed('bad_request', detail, { status: res.status })
+  }
+  const parsed = parseAnswer(data, req.crops.length, req.top)
+  if (typeof parsed === 'string') return failed('malformed', `malformed answer: ${parsed}`, { status: res.status })
+  return { ok: true, ...parsed }
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+function problemText(status: number, data: unknown): string {
+  if (isRecord(data)) {
+    const code = typeof data.code === 'string' ? data.code : `HTTP_${status}`
+    const detail = typeof data.detail === 'string' ? data.detail : typeof data.title === 'string' ? data.title : ''
+    return detail ? `${code}: ${detail}` : code
+  }
+  return `HTTP_${status}`
+}
+
+/**
+ * The 200 body, checked field by field. Returns the results in index order,
+ * or a string naming the first thing wrong. A crop with no result is allowed:
+ * it stays unidentified, as on any failure.
+ */
+export function parseAnswer(data: unknown, cropCount: number, top: number): { modelVersion: string; results: IdentifyResult[] } | string {
+  if (!isRecord(data) || !Array.isArray(data.results)) return 'expected { modelVersion, results: [...] }'
+  if (typeof data.modelVersion !== 'string' || data.modelVersion.length === 0) return 'modelVersion is missing'
+  if (data.results.length > cropCount) return `${data.results.length} results for ${cropCount} crops`
+  const limit = Math.min(Math.max(top, 1), MAX_TOP)
+
+  const seen = new Set<number>()
+  const out: IdentifyResult[] = []
+  for (const [at, raw] of data.results.entries()) {
+    if (!isRecord(raw)) return `results[${at}] is not an object`
+    const { index, confident, candidates, kind, identificationId } = raw
+    if (typeof index !== 'number' || !Number.isInteger(index) || index < 0 || index >= cropCount) return `results[${at}].index is not a crop index`
+    if (seen.has(index)) return `index ${index} answered twice`
+    seen.add(index)
+    // An absent kind is a card (the stand-in's earlier answers had none).
+    if (kind !== undefined && kind !== 'card' && kind !== 'not_a_card') return `results[${at}].kind is not card or not_a_card`
+    const k: IdentifyKind = kind === 'not_a_card' ? 'not_a_card' : 'card'
+    if (typeof confident !== 'boolean') return `results[${at}].confident is not a boolean`
+    if (k === 'not_a_card' && confident) return `results[${at}] is a confident not_a_card`
+    if (!Array.isArray(candidates)) return `results[${at}].candidates is not an array`
+    if (candidates.length > limit) return `results[${at}] has ${candidates.length} candidates for top ${limit}`
+    if (identificationId !== undefined && identificationId !== null && (typeof identificationId !== 'string' || identificationId.length === 0)) {
+      return `results[${at}].identificationId is not a string`
+    }
+
+    const parsed: IdentifyCandidate[] = []
+    for (const [c, cand] of candidates.entries()) {
+      if (!isRecord(cand) || typeof cand.cardId !== 'string' || cand.cardId.length === 0) return `results[${at}].candidates[${c}].cardId is not a string`
+      if (typeof cand.score !== 'number' || !Number.isFinite(cand.score)) return `results[${at}].candidates[${c}].score is not a number`
+      const prev = parsed[parsed.length - 1]
+      if (prev && cand.score > prev.score) return `results[${at}].candidates are not best first`
+      parsed.push({ cardId: cand.cardId, score: cand.score })
+    }
+    if (confident && parsed.length === 0) return `results[${at}] is confident with no candidate`
+    out.push({
+      index,
+      kind: k,
+      confident,
+      candidates: parsed,
+      ...(typeof identificationId === 'string' ? { identificationId } : {}),
+    })
+  }
+  out.sort((a, b) => a.index - b.index)
+  return { modelVersion: data.modelVersion, results: out }
+}

package/src/identify/shard.ts

@@ -0,0 +1,154 @@
+/**
+ * Reads an index shard, `index_<domain>_v<N>.bin`, and its ids sidecar.
+ *
+ * The binary layout is `ml/src/dejadex_ml/index_format.py`'s, a cross-language
+ * contract (change the two together):
+ *
+ *   offset size  field
+ *   0      4     magic            "DJIX"
+ *   4      2     format_version   uint16 LE (1)
+ *   6      1     dtype            1 = fp16, 2 = int8
+ *   7      1     reserved         0
+ *   8      16    domain           ASCII, NUL-padded
+ *   24     32    model_version    ASCII, NUL-padded
+ *   56     32    index_version    ASCII, NUL-padded
+ *   88     4     rows             uint32 LE
+ *   92     2     dim              uint16 LE
+ *   94     2     reserved         0
+ *   96 …         rows × dim fp16, row-major, rows L2-normalised
+ *
+ * Only fp16 is read: the int8 layout exists in the format, and no shard ships
+ * with it yet.
+ */
+import { ScannerError } from '../errors.js'
+
+export const HEADER_SIZE = 96
+const MAGIC = 'DJIX'
+const FORMAT_VERSION = 1
+const DTYPE_FP16 = 1
+/** Typed arrays use the platform's byte order; the file is little-endian. */
+const LITTLE_ENDIAN = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1
+
+export interface ShardHeader {
+  readonly domain: string
+  readonly modelVersion: string
+  readonly indexVersion: string
+  readonly rows: number
+  readonly dim: number
+}
+
+/** A loaded shard: rows as float32, ready for the dot products. */
+export interface Shard extends ShardHeader {
+  /** rows × dim, row-major. */
+  readonly matrix: Float32Array
+  /** Row id per row (the catalogue's card id). */
+  readonly ids: readonly string[]
+}
+
+const integrity = (message: string): ScannerError => new ScannerError('MODEL_INTEGRITY', `index shard: ${message}`)
+
+function text(bytes: Uint8Array, offset: number, size: number, name: string): string {
+  const raw = bytes.subarray(offset, offset + size)
+  const nul = raw.indexOf(0)
+  const end = nul === -1 ? size : nul
+  for (let i = end; i < size; i++) if (raw[i] !== 0) throw integrity(`${name} has bytes after its NUL padding`)
+  let out = ''
+  for (let i = 0; i < end; i++) {
+    const ch = raw[i] as number
+    if (ch < 0x20 || ch > 0x7e) throw integrity(`${name} is not printable ASCII`)
+    out += String.fromCharCode(ch)
+  }
+  if (out.length === 0) throw integrity(`${name} is empty`)
+  return out
+}
+
+export function parseShardHeader(buffer: ArrayBuffer): ShardHeader & { readonly dtype: number } {
+  if (buffer.byteLength < HEADER_SIZE) throw integrity(`${buffer.byteLength} bytes is shorter than its header`)
+  const bytes = new Uint8Array(buffer, 0, HEADER_SIZE)
+  const view = new DataView(buffer, 0, HEADER_SIZE)
+  if (String.fromCharCode(...bytes.subarray(0, 4)) !== MAGIC) throw integrity('bad magic')
+  const version = view.getUint16(4, true)
+  if (version !== FORMAT_VERSION) throw integrity(`unsupported format version ${version}`)
+  if (bytes[7] !== 0 || view.getUint16(94, true) !== 0) throw integrity('reserved header bytes are not zero')
+  return {
+    dtype: bytes[6] as number,
+    domain: text(bytes, 8, 16, 'domain'),
+    modelVersion: text(bytes, 24, 32, 'model version'),
+    indexVersion: text(bytes, 56, 32, 'index version'),
+    rows: view.getUint32(88, true),
+    dim: view.getUint16(92, true),
+  }
+}
+
+/** IEEE 754 half → float, by table (65 536 entries, built once). */
+let HALF_TABLE: Float32Array | null = null
+function halfTable(): Float32Array {
+  if (HALF_TABLE) return HALF_TABLE
+  const t = new Float32Array(65536)
+  for (let h = 0; h < 65536; h++) {
+    const sign = h & 0x8000 ? -1 : 1
+    const exp = (h >> 10) & 0x1f
+    const frac = h & 0x3ff
+    if (exp === 0) t[h] = sign * frac * 2 ** -24
+    else if (exp === 31) t[h] = frac ? Number.NaN : sign * Number.POSITIVE_INFINITY
+    else t[h] = sign * (1 + frac / 1024) * 2 ** (exp - 15)
+  }
+  HALF_TABLE = t
+  return t
+}
+
+export function halfToFloat(bits: number): number {
+  return halfTable()[bits & 0xffff] as number
+}
+
+export interface ShardExpectations {
+  readonly domain: string
+  readonly modelVersion: string
+  readonly indexVersion: string
+  readonly rows: number
+  readonly dim: number
+}
+
+/** Parses and checks the binary against what the manifest promised, and decodes it to float32. */
+export function decodeShard(buffer: ArrayBuffer, ids: readonly string[], expect: ShardExpectations): Shard {
+  const header = parseShardHeader(buffer)
+  if (header.dtype !== DTYPE_FP16) throw integrity(`dtype ${header.dtype} is not supported (fp16 only)`)
+  for (const key of ['domain', 'modelVersion', 'indexVersion', 'rows', 'dim'] as const) {
+    if (header[key] !== expect[key]) {
+      throw integrity(`header ${key} ${String(header[key])} does not match the manifest's ${String(expect[key])}`)
+    }
+  }
+  const size = HEADER_SIZE + header.rows * header.dim * 2
+  if (buffer.byteLength !== size) throw integrity(`${buffer.byteLength} bytes, the header implies ${size}`)
+  if (ids.length !== header.rows) throw integrity(`${ids.length} ids for ${header.rows} rows`)
+  const n = header.rows * header.dim
+  const table = halfTable()
+  const matrix = new Float32Array(n)
+  if (LITTLE_ENDIAN) {
+    const halves = new Uint16Array(buffer, HEADER_SIZE, n)
+    for (let i = 0; i < n; i++) matrix[i] = table[halves[i] as number] as number
+  } else {
+    const view = new DataView(buffer, HEADER_SIZE)
+    for (let i = 0; i < n; i++) matrix[i] = table[view.getUint16(i * 2, true)] as number
+  }
+  return { domain: header.domain, modelVersion: header.modelVersion, indexVersion: header.indexVersion, rows: header.rows, dim: header.dim, matrix, ids }
+}
+
+/** The ids sidecar, `index_<domain>_v<N>.json`. */
+export function parseIds(json: unknown, expect: Pick<ShardExpectations, 'domain' | 'modelVersion' | 'indexVersion' | 'rows'>): string[] {
+  if (typeof json !== 'object' || json === null) throw integrity('ids sidecar is not an object')
+  const doc = json as Record<string, unknown>
+  if (doc.format !== 1) throw integrity(`ids sidecar format ${String(doc.format)} is not supported`)
+  if (doc.shard !== expect.domain || doc.modelVersion !== expect.modelVersion || doc.indexVersion !== expect.indexVersion) {
+    throw integrity('ids sidecar belongs to another shard or version')
+  }
+  const ids = doc.ids
+  if (!Array.isArray(ids) || ids.length !== expect.rows) throw integrity(`ids sidecar lists ${Array.isArray(ids) ? ids.length : 'no'} ids for ${expect.rows} rows`)
+  const seen = new Set<string>()
+  for (const id of ids) {
+    if (typeof id !== 'string' || id.length === 0) throw integrity('ids sidecar has a row id that is not a string')
+    if (seen.has(id)) throw integrity(`row id ${id} appears twice`)
+    seen.add(id)
+  }
+  return ids as string[]
+}

package/src/identify/types.ts

@@ -0,0 +1,122 @@
+/**
+ * The identifier: card crops in, catalogue ids out. This is the snapshot half
+ * of the SDK, usable on its own before the live pipeline (`createScanner`)
+ * exists. Its answer has the same shape whichever side identified the crops,
+ * the device or `POST /v1/identify`, so a host never needs to know which.
+ *
+ * Wire contract of the server route, which `httpIdentify` speaks:
+ *
+ *   POST {serverUrl}/v1/identify   multipart/form-data: crop0..crop8 (JPEG, one
+ *                                  card each) and the optional text fields
+ *                                  `top` (1..20), `purpose`, `session`
+ *     Authorization: Bearer <lease token>
+ *   → 200 { modelVersion,
+ *           results: [ { index, kind?: 'card' | 'not_a_card', confident,
+ *                        candidates: [ { cardId, score } ], identificationId? } ] }
+ *
+ * Non-2xx answers are RFC 9457 Problem Details.
+ */
+import type { DomainCode, LeaseClaims } from '../types.js'
+
+/** At most this many crops per call, as on the server route. */
+export const MAX_CROPS_PER_REQUEST = 9
+
+/** Candidates per crop when `top` is not given. */
+export const DEFAULT_TOP = 5
+
+/** The most candidates a call may ask for. */
+export const MAX_TOP = 20
+
+export interface IdentifyCandidate {
+  /** The catalogue id of the row (the shard's row id). */
+  readonly cardId: string
+  /** Cosine similarity, the max over the orientations tried. Higher is closer. */
+  readonly score: number
+}
+
+/**
+ * What a crop is: a card (identified, or not confidently), or not a card at
+ * all. There is no "unknown": a card with no confident match is
+ * `kind: 'card', confident: false`.
+ */
+export type IdentifyKind = 'card' | 'not_a_card'
+
+export interface IdentifyResult {
+  /** Position of the crop in the call. */
+  readonly index: number
+  /** `not_a_card` when the best score is below the model version's `notACardBelow`. */
+  readonly kind: IdentifyKind
+  /** `top1 - top2 >= confidentMargin`; always false for `not_a_card`. */
+  readonly confident: boolean
+  /** Best first; `top` of them (candidates are returned for `not_a_card` too). */
+  readonly candidates: readonly IdentifyCandidate[]
+  /**
+   * Set when the service counted this answer as an identification itself
+   * (usage-metering): the SDK then writes no usage event for it.
+   */
+  readonly identificationId?: string
+}
+
+/** Where an answer came from. Informational: results are the same shape either way. */
+export type IdentifySource = 'device' | 'server'
+
+export type IdentifyFailureReason = 'unavailable' | 'timeout' | 'rejected'
+
+export type IdentifyOutcome =
+  | {
+      readonly ok: true
+      /** The model version the thresholds and the candidates belong to. */
+      readonly modelVersion: string
+      readonly results: readonly IdentifyResult[]
+      readonly source: IdentifySource
+    }
+  | {
+      readonly ok: false
+      readonly reason: IdentifyFailureReason
+      /** A stable code first where there is one, e.g. `ALLOWANCE_EXHAUSTED: …`. */
+      readonly detail?: string
+    }
+
+/** Why a crop is being identified; `retry` answers are never charged. */
+export type IdentifyPurpose = 'live' | 'still' | 'retry'
+
+export interface IdentifyCallOptions {
+  readonly signal?: AbortSignal
+  /** Candidates per crop, 1..20. Default 5. */
+  readonly top?: number
+  /**
+   * The host's scan session id (≤ 128 printable characters). Usage counts one
+   * identification per distinct card per session. Default: the identifier's
+   * own session, renewed by `newSession()`.
+   */
+  readonly session?: string
+  readonly purpose?: IdentifyPurpose
+}
+
+/** Where identification may run. `local` never sends an image anywhere. */
+export type IdentificationMode = 'auto' | 'local' | 'server'
+
+/** What the on-device engine is running on, once loaded. */
+export interface DeviceEngineInfo {
+  readonly backend: 'webgpu' | 'wasm'
+  readonly precision: 'fp16' | 'fp32'
+  /** WASM threads in use (1 when the page is not cross-origin isolated). */
+  readonly threads: number
+  /** Measured at warm-up: one crop, every orientation, embed + search. */
+  readonly perCropMs: number
+  readonly modelVersion: string
+  readonly indexVersion: string
+  readonly shard: DomainCode
+  readonly rows: number
+}
+
+export interface IdentifierStatus {
+  readonly lease: LeaseClaims | null
+  /** `idle` until the first load is asked for; `failed` keeps the server path usable. */
+  readonly device: 'idle' | 'loading' | 'ready' | 'failed'
+  readonly deviceInfo: DeviceEngineInfo | null
+  /** Why the device engine failed to load, when it did. */
+  readonly deviceError: string | null
+  /** Why the server route is skipped right now, or null when it is usable. */
+  readonly serverPaused: string | null
+}

package/src/identify/worker.ts

@@ -0,0 +1,13 @@
+/**
+ * The identification Worker's entry point. `createIdentifier` starts it with
+ * `new Worker(new URL('./worker.js', import.meta.url), { type: 'module' })`,
+ * the pattern Vite, webpack 5 and Rollup bundle without configuration. A host
+ * that builds its own Worker points it at `@dejadex/web/identify-worker`.
+ *
+ * Everything that touches the model runs here: decoding the crops, the
+ * resize, the session and the search. The main thread only routes.
+ */
+import { defaultEngineDeps } from './engine.js'
+import { serveEngine, type WorkerScopeLike } from './workerProtocol.js'
+
+serveEngine(self as unknown as WorkerScopeLike, defaultEngineDeps)

package/src/identify/workerProtocol.ts

@@ -0,0 +1,136 @@
+/**
+ * The device engine across a Worker boundary: a request/response protocol by
+ * id, the Worker side (`serveEngine`) and the main-thread side
+ * (`connectWorkerEngine`). Crops cross as `Blob`s (structured-cloned, not
+ * decoded on the main thread); answers come back as plain data.
+ */
+import { ScannerError, type ScannerErrorCode } from '../errors.js'
+import type { DeviceEngine, EngineConfig, EngineDeps } from './engine.js'
+import { loadDeviceEngine } from './engine.js'
+import type { DeviceEngineInfo, IdentifyResult } from './types.js'
+
+export type EngineRequest =
+  | { readonly id: number; readonly op: 'load'; readonly config: EngineConfig }
+  | { readonly id: number; readonly op: 'identify'; readonly crops: readonly Blob[]; readonly top: number }
+  | { readonly id: number; readonly op: 'release' }
+
+export type EngineResponse =
+  | { readonly id: number; readonly ok: true; readonly info: DeviceEngineInfo | null; readonly results?: readonly IdentifyResult[] }
+  | { readonly id: number; readonly ok: false; readonly code: ScannerErrorCode | 'ERROR'; readonly message: string }
+
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
+
+/** What `serveEngine` needs of `self` in a Worker. */
+export interface WorkerScopeLike {
+  addEventListener(type: 'message', listener: (event: { readonly data: unknown }) => void): void
+  postMessage(message: EngineResponse): void
+}
+
+/** What `connectWorkerEngine` needs of a `Worker`. */
+export interface WorkerLike {
+  addEventListener(type: 'message' | 'error' | 'messageerror', listener: (event: { readonly data?: unknown; readonly message?: string }) => void): void
+  postMessage(message: EngineRequest): void
+  terminate(): void
+}
+
+const failure = (id: number, err: unknown): EngineResponse =>
+  err instanceof ScannerError
+    ? { id, ok: false, code: err.code, message: err.message }
+    : { id, ok: false, code: 'ERROR', message: err instanceof Error ? err.message || err.name : String(err) }
+
+/** Runs in the Worker: answers requests one at a time, in order. */
+export function serveEngine(scope: WorkerScopeLike, deps: () => Promise<EngineDeps>): void {
+  let engine: DeviceEngine | null = null
+  let queue: Promise<void> = Promise.resolve()
+
+  const handle = async (req: EngineRequest): Promise<EngineResponse> => {
+    switch (req.op) {
+      case 'load':
+        await engine?.release()
+        engine = null
+        engine = await loadDeviceEngine(req.config, await deps())
+        return { id: req.id, ok: true, info: engine.info }
+      case 'identify': {
+        if (!engine) throw new ScannerError('INVALID_OPTIONS', 'the device engine is not loaded')
+        const results = await engine.identify(req.crops, req.top)
+        return { id: req.id, ok: true, info: engine.info, results }
+      }
+      case 'release':
+        await engine?.release()
+        engine = null
+        return { id: req.id, ok: true, info: null }
+    }
+  }
+
+  scope.addEventListener('message', (event) => {
+    const req = event.data as EngineRequest
+    if (typeof req !== 'object' || req === null || typeof req.id !== 'number') return
+    queue = queue.then(async () => {
+      let res: EngineResponse
+      try {
+        res = await handle(req)
+      } catch (err) {
+        res = failure(req.id, err)
+      }
+      scope.postMessage(res)
+    })
+  })
+}
+
+/** Main thread: loads the engine in `worker` and returns a `DeviceEngine` that forwards to it. */
+export function connectWorkerEngine(worker: WorkerLike, config: EngineConfig): Promise<DeviceEngine> {
+  let nextId = 1
+  const pending = new Map<number, { resolve: (r: EngineResponse & { ok: true }) => void; reject: (e: Error) => void }>()
+  let dead: Error | null = null
+
+  const failAll = (err: Error) => {
+    dead = err
+    for (const p of pending.values()) p.reject(err)
+    pending.clear()
+  }
+  worker.addEventListener('message', (event) => {
+    const res = event.data as EngineResponse
+    const p = typeof res === 'object' && res !== null ? pending.get(res.id) : undefined
+    if (!p) return
+    pending.delete(res.id)
+    if (res.ok) p.resolve(res)
+    else p.reject(new ScannerError(res.code === 'ERROR' ? 'UNSUPPORTED_DEVICE' : res.code, res.message))
+  })
+  worker.addEventListener('error', (event) => {
+    failAll(new ScannerError('UNSUPPORTED_DEVICE', `the identification Worker failed: ${event.message ?? 'unknown error'}`))
+  })
+  worker.addEventListener('messageerror', () => {
+    failAll(new ScannerError('UNSUPPORTED_DEVICE', 'the identification Worker sent a message that could not be read'))
+  })
+
+  const call = (req: DistributiveOmit<EngineRequest, 'id'>): Promise<EngineResponse & { ok: true }> => {
+    if (dead) return Promise.reject(dead)
+    const id = nextId++
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject })
+      worker.postMessage({ ...req, id } as EngineRequest)
+    })
+  }
+
+  return call({ op: 'load', config }).then((loaded) => {
+    let info = loaded.info as DeviceEngineInfo
+    return {
+      get info() {
+        return info
+      },
+      async identify(crops, top) {
+        const res = await call({ op: 'identify', crops, top })
+        if (res.info) info = res.info
+        return [...(res.results ?? [])]
+      },
+      async release() {
+        try {
+          if (!dead) await call({ op: 'release' })
+        } finally {
+          worker.terminate()
+          failAll(new ScannerError('INVALID_OPTIONS', 'the device engine was released'))
+        }
+      },
+    }
+  })
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Public entry point of the web SDK.
+ *
+ * Real today: the homography maths (`geometry/`), and identification of card
+ * crops (`createIdentifier`: on the device or through the server, under a
+ * verified lease, with usage counted on the device). Stubbed with final
+ * shapes: `createScanner` (the live pipeline). See README.md.
+ */
+export { createScanner } from './scanner.js'
+export { createIdentifier, type Identifier, type IdentifierOptions } from './identify/identifier.js'
+export {
+  DEFAULT_TOP,
+  MAX_CROPS_PER_REQUEST,
+  MAX_TOP,
+  type DeviceEngineInfo,
+  type IdentificationMode,
+  type IdentifierStatus,
+  type IdentifyCallOptions,
+  type IdentifyCandidate,
+  type IdentifyFailureReason,
+  type IdentifyKind,
+  type IdentifyOutcome,
+  type IdentifyPurpose,
+  type IdentifyResult,
+  type IdentifySource,
+} from './identify/types.js'
+export type { RuntimeOptions } from './identify/runtime.js'
+export type { WorkerLike } from './identify/workerProtocol.js'
+export {
+  LeaseVerificationError,
+  verifyLease,
+  type LeaseFailure,
+  type LeasePublicKey,
+  type VerifyLeaseOptions,
+} from './lease/verify.js'
+export type { DrainResult } from './usage/meter.js'
+export { indexedDbUsageStore, memoryUsageStore, type UsageStore } from './usage/store.js'
+export { ScannerError, type ScannerErrorCode } from './errors.js'
+export {
+  IDENTITY,
+  UNIT_QUAD,
+  applyHomography,
+  invertHomography,
+  multiplyHomography,
+  quadToCssMatrix3d,
+  toCssMatrix3d,
+  unitSquareToQuad,
+  type ElementSize,
+  type Homography,
+  type Point,
+  type Quad,
+} from './geometry/homography.js'
+export type {
+  Candidate,
+  DeviceTier,
+  DomainCode,
+  ExternalIds,
+  FrameSourceInput,
+  Lease,
+  LeaseClaims,
+  LeaseGrant,
+  LeaseRequest,
+  PrintId,
+  Scanner,
+  ScannerOptions,
+  ScannerState,
+  TrackResult,
+  UsageBatch,
+  UsageReport,
+  VariantCode,
+} from './types.js'