@dejadex/web 0.0.0-stage → 0.1.1

package/src/geometry/homography.ts

@@ -0,0 +1,178 @@
+/**
+ * Planar homographies for AR labels: the projective map from a card's own
+ * unit rectangle to the four corners the detector found on screen, and its
+ * CSS `matrix3d` form, so a host page can lay a DOM element on the card's
+ * plane with nothing but `transform`.
+ *
+ * Conventions, fixed for every consumer:
+ *
+ * - Card space is the unit square: (0,0) top-left, (1,0) top-right, (1,1)
+ *   bottom-right, (0,1) bottom-left of the card as printed (portrait).
+ * - Screen space is CSS pixels of the element the corners were measured in,
+ *   y pointing down.
+ * - A `Quad` lists the screen corners in that same order: TL, TR, BR, BL.
+ * - A `Homography` is a 3×3 matrix in ROW-MAJOR order, normalised so the
+ *   bottom-right entry is 1. It maps (u, v, 1) to (x·w, y·w, w).
+ *
+ * The square-to-quad solution is the closed form from P. Heckbert,
+ * "Fundamentals of Texture Mapping and Image Warping" (1989), §2.2.3: no
+ * linear solve, exact for any convex quad, and cheap enough to run per track
+ * per frame.
+ */
+
+export interface Point {
+  readonly x: number
+  readonly y: number
+}
+
+/** Screen corners in card order: top-left, top-right, bottom-right, bottom-left. */
+export type Quad = readonly [Point, Point, Point, Point]
+
+/** Row-major 3×3 matrix, `[a, b, c, d, e, f, g, h, i]` with i = 1 once normalised. */
+export type Homography = readonly [number, number, number, number, number, number, number, number, number]
+
+export const IDENTITY: Homography = [1, 0, 0, 0, 1, 0, 0, 0, 1]
+
+/** The unit card rectangle's corners, in `Quad` order. */
+export const UNIT_QUAD: Quad = [
+  { x: 0, y: 0 },
+  { x: 1, y: 0 },
+  { x: 1, y: 1 },
+  { x: 0, y: 1 },
+]
+
+/** Relative tolerance below which a quad or a matrix counts as degenerate. */
+const DEGENERATE_EPS = 1e-12
+
+const isFiniteQuad = (q: Quad): boolean => q.every((p) => Number.isFinite(p.x) && Number.isFinite(p.y))
+
+/**
+ * The homography that maps the unit card rectangle onto `quad`.
+ *
+ * Throws `RangeError` when no proper homography exists: a non-finite corner,
+ * three collinear corners (zero area), or a quad that is not convex — a
+ * concave or self-crossing quad would need the projective plane to fold, and
+ * the label would be drawn through the horizon.
+ */
+export function unitSquareToQuad(quad: Quad): Homography {
+  if (!isFiniteQuad(quad)) throw new RangeError('quad has a non-finite corner')
+  const [p0, p1, p2, p3] = quad
+
+  const dx1 = p1.x - p2.x
+  const dx2 = p3.x - p2.x
+  const dy1 = p1.y - p2.y
+  const dy2 = p3.y - p2.y
+  const sx = p0.x - p1.x + p2.x - p3.x
+  const sy = p0.y - p1.y + p2.y - p3.y
+
+  const span = Math.max(
+    ...quad.map((p) => Math.abs(p.x - p0.x)),
+    ...quad.map((p) => Math.abs(p.y - p0.y)),
+  )
+  const den = dx1 * dy2 - dx2 * dy1
+  if (span === 0 || Math.abs(den) <= DEGENERATE_EPS * span * span) {
+    throw new RangeError('quad is degenerate (zero area or collinear corners)')
+  }
+
+  const g = (sx * dy2 - dx2 * sy) / den
+  const h = (dx1 * sy - sx * dy1) / den
+
+  // w at each corner: (0,0) → 1, (1,0) → 1+g, (1,1) → 1+g+h, (0,1) → 1+h.
+  // All must share a sign, or the quad is not the image of a convex square.
+  if (1 + g <= DEGENERATE_EPS || 1 + h <= DEGENERATE_EPS || 1 + g + h <= DEGENERATE_EPS) {
+    throw new RangeError('quad is not convex')
+  }
+
+  return [
+    p1.x - p0.x + g * p1.x,
+    p3.x - p0.x + h * p3.x,
+    p0.x,
+    p1.y - p0.y + g * p1.y,
+    p3.y - p0.y + h * p3.y,
+    p0.y,
+    g,
+    h,
+    1,
+  ]
+}
+
+/** Maps a point through `m`. Throws `RangeError` for a point on the vanishing line. */
+export function applyHomography(m: Homography, p: Point): Point {
+  const [a, b, c, d, e, f, g, h, i] = m
+  const w = g * p.x + h * p.y + i
+  if (Math.abs(w) <= DEGENERATE_EPS) throw new RangeError('point maps to infinity')
+  return { x: (a * p.x + b * p.y + c) / w, y: (d * p.x + e * p.y + f) / w }
+}
+
+/** `a · b` (apply `b` first, then `a`), normalised. */
+export function multiplyHomography(a: Homography, b: Homography): Homography {
+  const r = (row: number, col: number): number =>
+    a[row * 3]! * b[col]! + a[row * 3 + 1]! * b[3 + col]! + a[row * 3 + 2]! * b[6 + col]!
+  return normalise([r(0, 0), r(0, 1), r(0, 2), r(1, 0), r(1, 1), r(1, 2), r(2, 0), r(2, 1), r(2, 2)])
+}
+
+/** The inverse map, normalised. Throws `RangeError` for a singular matrix. */
+export function invertHomography(m: Homography): Homography {
+  const [a, b, c, d, e, f, g, h, i] = m
+  const A = e * i - f * h
+  const B = -(d * i - f * g)
+  const C = d * h - e * g
+  const det = a * A + b * B + c * C
+  const scale = Math.max(...m.map(Math.abs))
+  if (!Number.isFinite(det) || Math.abs(det) <= DEGENERATE_EPS * scale * scale * scale) {
+    throw new RangeError('homography is singular')
+  }
+  // Adjugate (transposed cofactors); the 1/det factor cancels in normalise().
+  return normalise([A, -(b * i - c * h), b * f - c * e, B, a * i - c * g, -(a * f - c * d), C, -(a * h - b * g), a * e - b * d])
+}
+
+/** Scales `m` so its bottom-right entry is 1. */
+export function normalise(m: readonly number[]): Homography {
+  const k = m[8]!
+  if (Math.abs(k) <= DEGENERATE_EPS) throw new RangeError('homography cannot be normalised (h33 = 0)')
+  return m.map((v) => v / k) as unknown as Homography
+}
+
+export interface ElementSize {
+  /** The label element's layout width in CSS pixels (its `offsetWidth`). */
+  readonly width: number
+  /** The label element's layout height in CSS pixels (its `offsetHeight`). */
+  readonly height: number
+}
+
+/**
+ * The CSS `matrix3d(...)` that draws an element of `size` onto the quad that
+ * `m` maps the unit card to.
+ *
+ * The element must be absolutely positioned at the origin of the coordinate
+ * space the corners were measured in, with `transform-origin: 0 0`. Its own
+ * box (0..width, 0..height) is first scaled to the unit square, then sent
+ * through `m`. The 3×3 homography becomes the 4×4
+ *
+ *     | a b 0 c |
+ *     | d e 0 f |
+ *     | 0 0 1 0 |
+ *     | g h 0 i |
+ *
+ * which leaves z alone, and CSS takes it in COLUMN-major order.
+ */
+export function toCssMatrix3d(m: Homography, size: ElementSize = { width: 1, height: 1 }): string {
+  if (!(size.width > 0) || !(size.height > 0)) throw new RangeError('element size must be positive')
+  const scaled = multiplyHomography(m, [1 / size.width, 0, 0, 0, 1 / size.height, 0, 0, 0, 1])
+  const [a, b, c, d, e, f, g, h, i] = scaled
+  const columnMajor = [a, d, 0, g, b, e, 0, h, 0, 0, 1, 0, c, f, 0, i]
+  return `matrix3d(${columnMajor.map(formatCssNumber).join(', ')})`
+}
+
+/** Fixed precision, no `-0`, no exponent: what every engine parses identically. */
+function formatCssNumber(v: number): string {
+  if (!Number.isFinite(v)) throw new RangeError('non-finite matrix entry')
+  const fixed = Number(v.toFixed(12))
+  if (fixed === 0) return '0'
+  return fixed.toFixed(12).replace(/\.?0+$/, '')
+}
+
+/** Convenience for the common case: corners in, CSS transform out. */
+export function quadToCssMatrix3d(quad: Quad, size?: ElementSize): string {
+  return toCssMatrix3d(unitSquareToQuad(quad), size)
+}

package/src/identify/assets.ts

@@ -0,0 +1,189 @@
+/**
+ * Downloads of the manifest, the model and the shard: time-bounded, checked
+ * against the manifest's SHA-256 and size, and kept in the Cache API under
+ * their digest (content-addressed). A new manifest version downloads only the
+ * files whose digest changed; a corrupted cache entry is noticed on read,
+ * dropped and fetched again.
+ *
+ * The last manifest that loaded is cached too, so the device engine starts
+ * offline from a complete cache.
+ */
+import { ScannerError } from '../errors.js'
+import type { ManifestFile } from './manifest.js'
+
+/** The Cache API cache the SDK owns. Bump the suffix if the key scheme changes. */
+export const CACHE_NAME = 'dejadex-assets-v1'
+/** Keys are synthetic URLs; nothing is ever fetched from this origin. */
+const KEY_ORIGIN = 'https://cache.dejadex.invalid'
+
+/** Smallest download speed assumed when bounding a file's download (bytes/s). */
+const MIN_BYTES_PER_SECOND = 100_000
+const MIN_FILE_TIMEOUT_MS = 30_000
+export const MANIFEST_TIMEOUT_MS = 10_000
+
+export type FetchLike = (input: string, init: { signal: AbortSignal; cache?: RequestCache }) => Promise<Response>
+
+/** The subset of `CacheStorage` used, so tests and hosts without one can pass their own (or none). */
+export interface CacheLike {
+  match(key: string): Promise<Response | undefined>
+  put(key: string, response: Response): Promise<void>
+  delete(key: string): Promise<boolean>
+  keys(): Promise<readonly { readonly url: string }[]>
+}
+
+export interface AssetStoreOptions {
+  readonly fetch: FetchLike
+  /** null: no cache (every start downloads). */
+  readonly cache: CacheLike | null
+  /** Overrides the per-file bound (ms); default from the size, at ≥ 100 kB/s. */
+  readonly fileTimeoutMs?: number
+}
+
+export interface AssetStore {
+  /** The file's bytes, from the cache or the network, verified. */
+  get(file: ManifestFile, signal?: AbortSignal): Promise<ArrayBuffer>
+  /** The manifest document from `url`; offline, the last one that loaded from it. */
+  manifest(url: string, signal?: AbortSignal): Promise<unknown>
+  /** Drops cached files whose digest is not in `keep` (after a new manifest verified). */
+  evictExcept(keep: readonly string[]): Promise<number>
+}
+
+export async function sha256Hex(data: ArrayBuffer): Promise<string> {
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', data))
+  let out = ''
+  for (const b of digest) out += b.toString(16).padStart(2, '0')
+  return out
+}
+
+const fileKey = (sha256: string): string => `${KEY_ORIGIN}/sha256/${sha256}`
+const manifestKey = (url: string): string => {
+  // A signed URL changes its query every time; the manifest it names does not.
+  const u = new URL(url)
+  return `${KEY_ORIGIN}/manifest/${encodeURIComponent(u.origin + u.pathname)}`
+}
+
+/** `AbortSignal.any` where the runtime has it, else a controller following both. */
+export function anySignal(signals: readonly (AbortSignal | undefined)[]): AbortSignal {
+  const list = signals.filter((s): s is AbortSignal => s !== undefined)
+  if (list.length === 1) return list[0] as AbortSignal
+  if (typeof AbortSignal.any === 'function') return AbortSignal.any(list)
+  const controller = new AbortController()
+  for (const s of list) {
+    if (s.aborted) {
+      controller.abort(s.reason)
+      break
+    }
+    s.addEventListener('abort', () => controller.abort(s.reason), { once: true })
+  }
+  return controller.signal
+}
+
+const errorText = (err: unknown): string => (err instanceof Error ? err.message || err.name : String(err))
+
+export function createAssetStore(options: AssetStoreOptions): AssetStore {
+  const { fetch: doFetch, cache } = options
+
+  async function verified(buffer: ArrayBuffer, file: ManifestFile): Promise<boolean> {
+    return buffer.byteLength === file.size && (await sha256Hex(buffer)) === file.sha256
+  }
+
+  async function download(file: ManifestFile, signal: AbortSignal | undefined): Promise<ArrayBuffer> {
+    const timeoutMs = options.fileTimeoutMs ?? Math.max(MIN_FILE_TIMEOUT_MS, Math.ceil((file.size / MIN_BYTES_PER_SECOND) * 1000))
+    const bound = anySignal([AbortSignal.timeout(timeoutMs), signal])
+    try {
+      // The body is read inside this try, so the bound covers it too.
+      const res = await doFetch(file.url, { signal: bound, cache: 'no-store' })
+      if (!res.ok) throw new ScannerError('NETWORK', `${file.url} answered ${res.status}`)
+      return await res.arrayBuffer()
+    } catch (err) {
+      if (err instanceof ScannerError) throw err
+      throw new ScannerError('NETWORK', `download of ${file.url} failed: ${errorText(err)}`, { cause: err })
+    }
+  }
+
+  return {
+    async get(file, signal) {
+      const key = fileKey(file.sha256)
+      if (cache) {
+        const hit = await cache.match(key).catch(() => undefined)
+        if (hit) {
+          const buffer = await hit.arrayBuffer()
+          if (await verified(buffer, file)) return buffer
+          await cache.delete(key).catch(() => false)
+        }
+      }
+      // One retry: a truncated or corrupted transfer gets a second chance.
+      for (let attempt = 1; ; attempt++) {
+        const buffer = await download(file, signal)
+        if (await verified(buffer, file)) {
+          if (cache) {
+            await cache
+              .put(key, new Response(buffer.slice(0), { headers: { 'Content-Type': 'application/octet-stream' } }))
+              .catch(() => undefined) // a full disk only costs the next start a download
+          }
+          return buffer
+        }
+        if (attempt >= 2) {
+          throw new ScannerError('MODEL_INTEGRITY', `${file.url} does not match its manifest checksum or size`)
+        }
+      }
+    },
+
+    async manifest(url, signal) {
+      const bound = anySignal([AbortSignal.timeout(MANIFEST_TIMEOUT_MS), signal])
+      let networkError: unknown
+      try {
+        const res = await doFetch(url, { signal: bound, cache: 'no-store' })
+        if (!res.ok) throw new ScannerError('NETWORK', `manifest ${url} answered ${res.status}`)
+        const text = await res.text()
+        let doc: unknown
+        try {
+          doc = JSON.parse(text)
+        } catch {
+          throw new ScannerError('MODEL_INTEGRITY', `manifest ${url} is not JSON`)
+        }
+        if (cache) {
+          await cache.put(manifestKey(url), new Response(text, { headers: { 'Content-Type': 'application/json' } })).catch(() => undefined)
+        }
+        return doc
+      } catch (err) {
+        if (err instanceof ScannerError && err.code === 'MODEL_INTEGRITY') throw err
+        if (signal?.aborted) throw err
+        networkError = err
+      }
+      // Offline (or the CDN is down): the last manifest that loaded from this URL.
+      const hit = cache ? await cache.match(manifestKey(url)).catch(() => undefined) : undefined
+      if (hit) return JSON.parse(await hit.text()) as unknown
+      if (networkError instanceof ScannerError) throw networkError
+      throw new ScannerError('NETWORK', `manifest ${url} could not be fetched: ${errorText(networkError)}`, { cause: networkError })
+    },
+
+    async evictExcept(keep) {
+      if (!cache) return 0
+      const wanted = new Set(keep.map(fileKey))
+      let removed = 0
+      for (const req of await cache.keys()) {
+        if (req.url.startsWith(`${KEY_ORIGIN}/sha256/`) && !wanted.has(req.url)) {
+          if (await cache.delete(req.url)) removed++
+        }
+      }
+      return removed
+    },
+  }
+}
+
+/** The page's Cache API cache, or null where there is none (or it is blocked). */
+export async function openDefaultCache(): Promise<CacheLike | null> {
+  try {
+    if (typeof caches === 'undefined') return null
+    const c = await caches.open(CACHE_NAME)
+    return {
+      match: (key) => c.match(key),
+      put: (key, response) => c.put(key, response),
+      delete: (key) => c.delete(key),
+      keys: () => c.keys(),
+    }
+  } catch {
+    return null
+  }
+}

package/src/identify/decode.ts

@@ -0,0 +1,54 @@
+/**
+ * Crop `Blob` → pixels, in a Worker or on the main thread.
+ *
+ * Decoded without colour management (`colorSpaceConversion: 'none'`) and
+ * without premultiplied alpha, as the Python reference (PIL) reads a JPEG: an
+ * embedded ICC profile would otherwise shift every value the gallery was
+ * embedded from. JPEG decoders still differ by a unit here and there between
+ * libjpeg builds; that difference is the decoder's, not the resize's.
+ */
+import { ScannerError } from '../errors.js'
+import type { PixelImage } from './preprocess.js'
+
+/** A crop this large is not one card; refuse it before allocating its pixels. */
+export const MAX_CROP_PIXELS = 40_000_000
+
+export type CropDecoder = (crop: Blob) => Promise<PixelImage>
+
+export const decodeCrop: CropDecoder = async (crop) => {
+  if (typeof createImageBitmap !== 'function') throw new ScannerError('UNSUPPORTED_DEVICE', 'createImageBitmap is not available')
+  let bitmap: ImageBitmap
+  try {
+    bitmap = await createImageBitmap(crop, { colorSpaceConversion: 'none', premultiplyAlpha: 'none' })
+  } catch (err) {
+    throw new ScannerError('INVALID_OPTIONS', 'a crop could not be decoded as an image', { cause: err })
+  }
+  try {
+    const { width, height } = bitmap
+    if (width * height > MAX_CROP_PIXELS) throw new ScannerError('INVALID_OPTIONS', `a crop of ${width}x${height} is too large`)
+    const ctx = context2d(width, height)
+    ctx.drawImage(bitmap, 0, 0)
+    const image = ctx.getImageData(0, 0, width, height)
+    return { width, height, channels: 4, data: image.data }
+  } finally {
+    bitmap.close()
+  }
+}
+
+type Context2d = OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D
+
+function context2d(width: number, height: number): Context2d {
+  const opts = { willReadFrequently: true, alpha: false } as const
+  if (typeof OffscreenCanvas !== 'undefined') {
+    const ctx = new OffscreenCanvas(width, height).getContext('2d', opts)
+    if (ctx) return ctx
+  }
+  if (typeof document !== 'undefined') {
+    const canvas = document.createElement('canvas')
+    canvas.width = width
+    canvas.height = height
+    const ctx = canvas.getContext('2d', opts) as CanvasRenderingContext2D | null
+    if (ctx) return ctx
+  }
+  throw new ScannerError('UNSUPPORTED_DEVICE', 'no 2D canvas to decode crops with')
+}

package/src/identify/engine.ts

@@ -0,0 +1,167 @@
+/**
+ * The on-device identification engine: manifest → model session + shard →
+ * crops → answers. Runs wherever it is constructed; `worker.ts` runs it in a
+ * dedicated Worker (the default), `identifier.ts` talks to it through the
+ * `DeviceEngine` interface either way.
+ */
+import { ScannerError } from '../errors.js'
+import { createAssetStore, openDefaultCache, type AssetStore, type FetchLike } from './assets.js'
+import { decodeCrop, type CropDecoder } from './decode.js'
+import { parseManifest, type Manifest } from './manifest.js'
+import { preprocessCrop, type PixelImage } from './preprocess.js'
+import { createEmbedBackend, defaultRuntimeEnv, type EmbedBackend, type RuntimeEnv, type RuntimeOptions } from './runtime.js'
+import { decodeShard, parseIds, type Shard } from './shard.js'
+import { toResult, topK } from './search.js'
+import type { DeviceEngineInfo, IdentifyResult } from './types.js'
+
+/** What the engine must load: plain data, so it crosses a Worker boundary. */
+export interface EngineConfig {
+  readonly manifestUrl: string
+  /** The lease's versions and shard; a manifest that differs is refused. */
+  readonly expect: { readonly modelVersion: string; readonly indexVersion: string; readonly shard: string }
+  readonly runtime: RuntimeOptions
+}
+
+export interface DeviceEngine {
+  readonly info: DeviceEngineInfo
+  identify(crops: readonly Blob[], top: number): Promise<IdentifyResult[]>
+  release(): Promise<void>
+}
+
+export interface EngineDeps {
+  readonly assets: AssetStore
+  readonly runtimeEnv: RuntimeEnv
+  readonly decode: CropDecoder
+  readonly now: () => number
+}
+
+export async function defaultEngineDeps(): Promise<EngineDeps> {
+  const doFetch: FetchLike = (url, init) => fetch(url, init)
+  return {
+    assets: createAssetStore({ fetch: doFetch, cache: await openDefaultCache() }),
+    runtimeEnv: defaultRuntimeEnv(),
+    decode: decodeCrop,
+    now: () => performance.now(),
+  }
+}
+
+/** Checks the manifest against what the lease grants (versions are locked together). */
+export function checkManifestAgainstLease(manifest: Manifest, expect: EngineConfig['expect']): void {
+  if (manifest.shard !== expect.shard) {
+    throw new ScannerError('DOMAIN_NOT_ALLOWED', `manifest is for shard ${manifest.shard}, the lease grants ${expect.shard}`)
+  }
+  if (manifest.modelVersion !== expect.modelVersion || manifest.indexVersion !== expect.indexVersion) {
+    throw new ScannerError(
+      'MODEL_INTEGRITY',
+      `manifest is model ${manifest.modelVersion} / index ${manifest.indexVersion}, the lease is ${expect.modelVersion} / ${expect.indexVersion}`,
+    )
+  }
+}
+
+export async function loadDeviceEngine(config: EngineConfig, deps: EngineDeps): Promise<DeviceEngine> {
+  const { assets } = deps
+  const manifest = parseManifest(await assets.manifest(config.manifestUrl), config.manifestUrl)
+  checkManifestAgainstLease(manifest, config.expect)
+
+  const [indexBytes, idsBytes] = await Promise.all([assets.get(manifest.index), assets.get(manifest.ids)])
+  let idsDoc: unknown
+  try {
+    idsDoc = JSON.parse(new TextDecoder().decode(idsBytes))
+  } catch {
+    throw new ScannerError('MODEL_INTEGRITY', 'ids sidecar is not JSON')
+  }
+  const expectShard = {
+    domain: manifest.shard,
+    modelVersion: manifest.modelVersion,
+    indexVersion: manifest.indexVersion,
+    rows: manifest.rows,
+    dim: manifest.dims,
+  }
+  const shard = decodeShard(indexBytes, parseIds(idsDoc, expectShard), expectShard)
+
+  const used: string[] = [manifest.index.sha256, manifest.ids.sha256]
+  const backend = await createEmbedBackend(
+    manifest,
+    async (model) => {
+      used.push(model.sha256)
+      return assets.get(model)
+    },
+    config.runtime,
+    deps.runtimeEnv,
+  )
+  // Older versions' files go only once this one has loaded.
+  await assets.evictExcept(used).catch(() => 0)
+
+  const engine = makeEngine(manifest, shard, backend, deps)
+  await engine.warmUp()
+  return engine
+}
+
+interface WarmEngine extends DeviceEngine {
+  warmUp(): Promise<void>
+}
+
+function makeEngine(manifest: Manifest, shard: Shard, backend: EmbedBackend, deps: EngineDeps): WarmEngine {
+  const { width, height, mean, std, orientations } = manifest.preprocessing
+  const norm = { mean, std }
+  const plane = 3 * width * height
+  const perCrop = orientations.length
+  const thresholds = { notACardBelow: manifest.notACardBelow, confidentMargin: manifest.confidentMargin }
+  let perCropMs = Number.NaN
+  let released = false
+
+  const info = (): DeviceEngineInfo => ({
+    backend: backend.backend,
+    precision: backend.precision,
+    threads: backend.threads,
+    perCropMs,
+    modelVersion: manifest.modelVersion,
+    indexVersion: manifest.indexVersion,
+    shard: manifest.shard,
+    rows: shard.rows,
+  })
+
+  async function run(images: readonly PixelImage[], top: number): Promise<IdentifyResult[]> {
+    if (released) throw new ScannerError('INVALID_OPTIONS', 'the device engine was released')
+    const n = images.length
+    if (n === 0) return []
+    const input = new Float32Array(n * perCrop * plane)
+    images.forEach((img, i) => preprocessCrop(img, { width, height }, norm, orientations, input, i * perCrop * plane))
+    const emb = await backend.embed(input, n * perCrop)
+    const dims = manifest.dims
+    const k = Math.max(top, 2)
+    const results: IdentifyResult[] = []
+    for (let i = 0; i < n; i++) {
+      const queries = emb.subarray(i * perCrop * dims, (i + 1) * perCrop * dims)
+      results.push(toResult(i, topK(shard.matrix, dims, queries, k), shard.ids, top, thresholds))
+    }
+    return results
+  }
+
+  return {
+    get info() {
+      return info()
+    },
+    async identify(crops, top) {
+      const images = await Promise.all(crops.map((c) => deps.decode(c)))
+      const t0 = deps.now()
+      const results = await run(images, top)
+      // Keep the per-crop time current: a device that heats up slows down.
+      const ms = (deps.now() - t0) / Math.max(1, crops.length)
+      perCropMs = Number.isFinite(perCropMs) ? perCropMs * 0.7 + ms * 0.3 : ms
+      return results
+    },
+    async warmUp() {
+      // The first run pays for shader compilation and allocation; time the second.
+      const blank = { width, height, channels: 3 as const, data: new Uint8Array(width * height * 3) }
+      await run([blank], 2)
+      const t0 = deps.now()
+      await run([blank], 2)
+      perCropMs = deps.now() - t0
+    },
+    async release() {
+      released = true
+      await backend.release()
+    },
+  }
+}