@gueshbzh-perso/scanner 0.8.0 → 0.10.0

package/src/core.ts

@@ -6,6 +6,8 @@
 // - `SessionCore`: the session. Cheap calls (`plan`, `commit`), main thread.
 // - `DecoderCore`: the expensive decoding, one per Web Worker.
 // The inline engine (no Worker support) uses both on the main thread.
+// Codes read by the browser's native `BarcodeDetector` enter the session with
+// `SessionCore.commitExternal` (see `native.ts`).
 import init, { WasmFrameDecoder, WasmScanner, WasmScanSession, version } from './wasm/scanner_wasm.js';
 import type { FramePlan, FrameReport, PixelFormat, ScanResult, WasmScanConfig } from './wasm/scanner_wasm.js';
 import type { Detection, EngineOptions } from './types.js';
@@ -72,6 +74,12 @@ export function toDetection(r: ScanResult): Detection {
   return d;
 }
 
+function toScanResult(d: Detection): ScanResult {
+  const r: ScanResult = { text: d.text, format: d.format, points: d.points, timestampMs: d.timestamp };
+  if (d.rawBytes) r.rawBytes = d.rawBytes;
+  return r;
+}
+
 export interface FrameOutcome {
   /** New codes, or `null`. */
   results: Detection[] | null;
@@ -89,9 +97,14 @@ export class SessionCore {
     this.session = new WasmScanSession(streamConfig(options));
   }
 
-  /** Strategy plan of the next frame, for a `DecoderCore` configured the same way. */
-  plan(): FramePlan {
-    return this.active().plan();
+  /**
+   * Strategy plan of the next frame, for a `DecoderCore` configured the same
+   * way. `fastPath: false` when the native `BarcodeDetector` already searched
+   * the frame: the decoder then runs the fallback strategy only.
+   */
+  plan(fastPath = true): FramePlan {
+    const session = this.active();
+    return fastPath ? session.plan() : session.planFallbackOnly();
   }
 
   /** Record a decoded frame; returns the new codes and the live ones. */
@@ -102,16 +115,16 @@ export class SessionCore {
     return { results, live: results ?? session.lastDetections.map(toDetection), decodeMs: report.elapsedMs };
   }
 
-  /** Decode on this thread (inline engine): plan, decode and commit at once. */
-  process(pixels: Uint8Array, width: number, height: number, format: PixelFormat): FrameOutcome {
+  /**
+   * Record codes read by the native `BarcodeDetector`: same format filter,
+   * confirmation and de-duplication as decoded frames. Points are kept as
+   * given (video pixels).
+   */
+  commitExternal(codes: Detection[], elapsedMs: number): FrameOutcome {
     const session = this.active();
-    // Write straight into WASM memory: avoids one more copy of the frame.
-    session.frameBuffer(pixels.length).set(pixels);
-    const t0 = performance.now();
-    const fresh = session.processFrameBuffer(width, height, format);
-    const decodeMs = performance.now() - t0;
+    const fresh = session.commitExternal(codes.map(toScanResult), elapsedMs);
     const results = fresh ? fresh.map(toDetection) : null;
-    return { results, live: results ?? session.lastDetections.map(toDetection), decodeMs };
+    return { results, live: results ?? session.lastDetections.map(toDetection), decodeMs: elapsedMs };
   }
 
   reset(): void {

package/src/engine.ts

@@ -9,7 +9,7 @@
 // with many slow cores (Galaxy A14: decode ~125 ms) the pool multiplies the
 // frame rate.
 import { DecoderCore, SessionCore, compileWasm, defaultWasmUrl, loadWasm } from './core.js';
-import type { FramePlan, FrameReport } from './core.js';
+import type { FrameOutcome, FramePlan, FrameReport } from './core.js';
 import type { WorkerRequest, WorkerResponse } from './protocol.js';
 import type { PixelFormat } from './wasm/scanner_wasm.js';
 import type { AssetOptions, Detection, EngineOptions } from './types.js';
@@ -28,8 +28,24 @@ export interface Engine {
   /** Frames that can be decoded at the same time (number of workers). */
   readonly concurrency: number;
   configure(options: EngineOptions): Promise<void>;
-  /** Decode a camera frame. `buffer` is transferred and returned in the reply. */
-  processFrame(buffer: ArrayBuffer, width: number, height: number, format: PixelFormat): Promise<FrameReply>;
+  /**
+   * Decode a camera frame. `buffer` is transferred and returned in the reply.
+   * `fastPath: false` runs the fallback strategy only, for a frame the
+   * native `BarcodeDetector` already searched without finding anything.
+   */
+  processFrame(
+    buffer: ArrayBuffer,
+    width: number,
+    height: number,
+    format: PixelFormat,
+    fastPath?: boolean,
+  ): Promise<FrameReply>;
+  /**
+   * Record codes read by the native `BarcodeDetector` in a frame: same
+   * format filter, multi-frame confirmation and de-duplication as decoded
+   * frames. Points are returned as given.
+   */
+  commitExternal(codes: Detection[], elapsedMs: number): Promise<FrameOutcome>;
   /** One-shot scan of a still image, running every strategy. */
   scanImage(
     buffer: ArrayBuffer,
@@ -186,10 +202,11 @@ class WorkerPoolEngine implements Engine {
     width: number,
     height: number,
     format: PixelFormat,
+    fastPath = true,
   ): Promise<FrameReply> {
     if (!this.configured) throw new Error('Engine not configured');
     const generation = this.generation;
-    const plan = this.session.plan();
+    const plan = this.session.plan(fastPath);
     let res: OkResponse;
     try {
       res = await this.idleWorker().ok({ type: 'decode', buffer, width, height, format, plan }, [buffer]);
@@ -205,6 +222,11 @@ class WorkerPoolEngine implements Engine {
     return { ...this.session.commit(res.report), buffer: returned };
   }
 
+  async commitExternal(codes: Detection[], elapsedMs: number) {
+    if (!this.configured) throw new Error('Engine not configured');
+    return this.session.commitExternal(codes, elapsedMs);
+  }
+
   async scanImage(
     buffer: ArrayBuffer,
     width: number,
@@ -265,7 +287,10 @@ class InlineEngine implements Engine {
   constructor(readonly version: string) {}
 
   async configure(options: EngineOptions) {
+    // Same configuration for both: a plan is an index in the decoder's list
+    // of fallback strategies (as with workers).
     this.session.configure(options);
+    this.decoder.configure(options);
   }
 
   async processFrame(
@@ -273,8 +298,21 @@ class InlineEngine implements Engine {
     width: number,
     height: number,
     format: PixelFormat,
+    fastPath = true,
   ): Promise<FrameReply> {
-    return { ...this.session.process(new Uint8Array(buffer), width, height, format), buffer };
+    const plan = this.session.plan(fastPath);
+    let report: FrameReport;
+    try {
+      report = this.decoder.decode(new Uint8Array(buffer), width, height, format, plan);
+    } catch (err) {
+      this.session.commit(emptyReport(plan));
+      throw err;
+    }
+    return { ...this.session.commit(report), buffer };
+  }
+
+  async commitExternal(codes: Detection[], elapsedMs: number) {
+    return this.session.commitExternal(codes, elapsedMs);
   }
 
   async scanImage(

package/src/native.ts

@@ -0,0 +1,140 @@
+// The browser's native barcode decoder (`BarcodeDetector`, Shape Detection API).
+//
+// Available in Chrome on Android (Google Play Services), macOS (Apple Vision)
+// and ChromeOS; not in Safari, Firefox, nor Chrome on Windows / Linux. Where it
+// exists it decodes outside the page's threads, so it can replace the engine's
+// **fast path**: the engine then only runs its fallback strategies (Linear,
+// CLAHE, Sauvola, inverted…) on the frames the native decoder found nothing
+// in. The native decoder has no such preprocessing, and those strategies are
+// what reads the hard codes (laser-engraved tags, labels in shadow).
+import type { Rect } from './grabber.js';
+import type { BarcodeFormat, Detection, Point } from './types.js';
+
+// The API is not in TypeScript's `lib.dom` yet: minimal local declarations.
+
+/** A code found by `BarcodeDetector.detect()`. */
+export interface NativeBarcode {
+  rawValue: string;
+  format: string;
+  /** Corners in pixels of the source (for a `<video>`: `videoWidth` space). */
+  cornerPoints: readonly Point[];
+}
+
+interface BarcodeDetectorInstance {
+  detect(source: CanvasImageSource): Promise<NativeBarcode[]>;
+}
+
+/** The `BarcodeDetector` constructor. */
+export interface BarcodeDetectorClass {
+  new (options?: { formats?: string[] }): BarcodeDetectorInstance;
+  getSupportedFormats(): Promise<string[]>;
+}
+
+/**
+ * Formats of this SDK, all spelled like the native ones (`qr_code`, `ean_13`…)
+ * except `micro_qr`, which the native API does not have: when it is asked
+ * for, it is still read by the engine's fallback strategies (`Hard` decodes
+ * the raw frame with every format), only less often than by a fast path.
+ */
+const NATIVE_FORMATS: readonly BarcodeFormat[] = [
+  'qr_code',
+  'data_matrix',
+  'aztec',
+  'pdf417',
+  'code_128',
+  'code_39',
+  'code_93',
+  'ean_13',
+  'ean_8',
+  'upc_a',
+  'upc_e',
+  'itf',
+  'codabar',
+];
+
+/** Native decoder serving one reader configuration. */
+export class NativeDetector {
+  private constructor(
+    private detector: BarcodeDetectorInstance,
+    /** Formats the detector looks for. */
+    readonly formats: readonly BarcodeFormat[],
+  ) {}
+
+  /**
+   * A detector for `formats` (default: all), or `undefined` when the native
+   * decoder cannot replace the engine's fast path: API absent, or one of the
+   * requested formats not supported natively (codes of that format would
+   * then only be read by the slower fallbacks).
+   */
+  static async create(
+    formats: readonly BarcodeFormat[] | undefined,
+    api: BarcodeDetectorClass | undefined = nativeApi(),
+  ): Promise<NativeDetector | undefined> {
+    if (!api) return undefined;
+    let supported: string[];
+    try {
+      supported = await api.getSupportedFormats();
+    } catch {
+      return undefined;
+    }
+    // On Android the list is empty until Google Play Services has downloaded
+    // its barcode module (first use on the device, in the background): the
+    // detector is unavailable *for now*, the engine does the whole job.
+    const wanted = (formats?.length ? formats : NATIVE_FORMATS).filter((f) => f !== 'micro_qr');
+    if (wanted.length === 0 || !wanted.every((f) => supported.includes(f))) return undefined;
+    try {
+      return new NativeDetector(new api({ formats: [...wanted] }), wanted);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Codes in `source` whose center lies in `rect` (the region of interest, in
+   * source pixels), as detections in source pixels. Throws when the native
+   * decoder fails.
+   */
+  async detect(source: CanvasImageSource, rect: Rect): Promise<Detection[]> {
+    const found = await this.detector.detect(source);
+    const timestamp = Date.now();
+    return found.flatMap((code) => {
+      const format = code.format as BarcodeFormat;
+      if (!this.formats.includes(format) || code.cornerPoints.length === 0) return [];
+      if (!contains(rect, center(code.cornerPoints))) return [];
+      const points = code.cornerPoints.map((p) => ({ x: p.x, y: p.y }));
+      return [{ text: code.rawValue, format, points, timestamp }];
+    });
+  }
+}
+
+/**
+ * The browser's own `BarcodeDetector`, if any. Feature detection only (no
+ * list of browsers or devices): any browser that ships the API is used.
+ *
+ * Polyfills are rejected: packages such as `barcode-detector` install a
+ * `BarcodeDetector` that runs ZXing in WebAssembly on the main thread,
+ * slower than this SDK's own engine in its workers. A built-in class
+ * stringifies as `function BarcodeDetector() { [native code] }`.
+ */
+function nativeApi(): BarcodeDetectorClass | undefined {
+  const api: unknown = Reflect.get(globalThis, 'BarcodeDetector');
+  if (typeof api !== 'function' || !isBuiltIn(api)) return undefined;
+  return api as BarcodeDetectorClass;
+}
+
+/** `true` for a function implemented by the browser, not in JavaScript. */
+export function isBuiltIn(fn: object): boolean {
+  return /\{\s*\[native code\]\s*\}\s*$/.test(Function.prototype.toString.call(fn));
+}
+
+function center(points: readonly Point[]): Point {
+  const n = points.length;
+  return {
+    x: points.reduce((s, p) => s + p.x, 0) / n,
+    y: points.reduce((s, p) => s + p.y, 0) / n,
+  };
+}
+
+function contains(r: Rect, p: Point): boolean {
+  return p.x >= r.x && p.x <= r.x + r.width && p.y >= r.y && p.y <= r.y + r.height;
+}

package/src/overlay.ts

@@ -181,7 +181,8 @@ function drawPolygon(ctx: CanvasRenderingContext2D, pts: Point[]): void {
   if (!first) return;
   ctx.beginPath();
   if (pts.length === 2 && second) {
-    // 1D codes report the two ends of the scan line: draw a thick bar.
+    // Fallback for a 1D code whose box could not be measured: the two ends
+    // of the scan line, drawn as a thick bar.
     ctx.save();
     ctx.lineWidth = 10;
     ctx.globalAlpha *= 0.6;

package/src/reader.ts

@@ -1,7 +1,7 @@
 // BarcodeReader: camera preview + frame pipeline + engine, wired together.
 import { capabilities, listCameras, openCamera, rememberCamera, setTorch, setZoom } from './camera.js';
 import { pickEngineOptions } from './core.js';
-import { createEngine, type Engine } from './engine.js';
+import { createEngine, type Engine, type FrameReply } from './engine.js';
 import { Feedback } from './feedback.js';
 import {
   clampRegion,
@@ -11,22 +11,36 @@ import {
   regionToVideoRect,
   videoToElement,
 } from './geometry.js';
-import { CanvasGrabber, createGrabber, type FrameGrabber } from './grabber.js';
+import { CanvasGrabber, createGrabber, type FrameGrabber, type Rect } from './grabber.js';
+import type { FrameOutcome } from './core.js';
+import { NativeDetector } from './native.js';
 import { Preview } from './overlay.js';
 import type { Detection, EngineOptions, ReaderEvents, ReaderOptions, ReaderStats, Region } from './types.js';
 
 const DEFAULT_REGION: Region = { x: 0.1, y: 0.2, width: 0.8, height: 0.6 };
 
+/**
+ * With the native detector, delay between two engine frames while the
+ * native decoder finds nothing (~3 fallbacks per second). A code that only
+ * the fallbacks read is still found within a couple of seconds (the
+ * strategies share CPU time, the cheap Linear one runs most often), while
+ * the workers stay idle most of the time. After a frame where the engine saw
+ * a code, the next one is immediate: a 1D code needs a second read.
+ */
+const FALLBACK_INTERVAL_MS = 300;
+
 /** A frame read from the video, waiting for (or being decoded by) the engine. */
 interface GrabbedFrame {
   buffer: ArrayBuffer;
   width: number;
   height: number;
   /** Region of the video the frame was cropped from (to map points back). */
-  rect: ReturnType<typeof regionToVideoRect>;
+  rect: Rect;
   grabMs: number;
   /** Grab order: decodes finish out of order when several workers run. */
   seq: number;
+  /** Run the engine's fast path (`false`: the native detector already searched this frame). */
+  fastPath: boolean;
 }
 
 type Listener<T> = (payload: T) => void;
@@ -55,8 +69,20 @@ export class BarcodeReader {
   private engineOptions: EngineOptions;
   private running = false;
   private paused = false;
-  /** A grab (GPU readback) is in progress. */
+  /** A frame is being acquired: grab (GPU readback) and native detection. */
   private grabbing = false;
+  /** Native `BarcodeDetector` used as the fast path, when enabled and available. */
+  private native: NativeDetector | undefined;
+  /** Bumped when the native detector is replaced: results of the old one are dropped. */
+  private nativeGeneration = 0;
+  /** The native detector failed once: not used again by this reader. */
+  private nativeFailed = false;
+  /** Native detector active: a fallback-only frame is being grabbed or decoded. */
+  private fallbackInFlight = false;
+  /** Native detector active: earliest time of the next fallback-only frame. */
+  private nextFallbackAt = 0;
+  /** Which decoder drew the current highlights: each one only clears its own. */
+  private highlightSource: 'native' | 'engine' | null = null;
   /** Frames being decoded (at most `engine.concurrency`). */
   private decoding = 0;
   /** Sequence number of the last grabbed frame, and of the last one drawn. */
@@ -77,13 +103,15 @@ export class BarcodeReader {
   private torchOn = false;
   private buffers: ArrayBuffer[] = [];
   private frameHandle = 0;
-  private perf = { frames: 0, since: 0, fps: 0, decodeMs: 0, grabMs: 0, w: 0, h: 0 };
+  private perf = { frames: 0, since: 0, fps: 0, decodeMs: 0, grabMs: 0, nativeMs: 0, w: 0, h: 0 };
 
   private constructor(
     private engine: Engine,
     private options: ReaderOptions,
     host: HTMLElement,
+    native: NativeDetector | undefined,
   ) {
+    this.native = native;
     this.region = clampRegion(options.regionOfInterest ?? DEFAULT_REGION);
     this.engineOptions = pickEngineOptions(options);
     this.preview = new Preview(host, options.overlay);
@@ -101,8 +129,10 @@ export class BarcodeReader {
       typeof options.host === 'string' ? document.querySelector<HTMLElement>(options.host) : options.host;
     if (!host) throw new Error(`BarcodeReader: host element not found (${String(options.host)})`);
     const engine = await createEngine(options);
-    await engine.configure(pickEngineOptions(options));
-    return new BarcodeReader(engine, options, host);
+    const engineOptions = pickEngineOptions(options);
+    await engine.configure(engineOptions);
+    const native = await createNative(options, engineOptions);
+    return new BarcodeReader(engine, options, host, native);
   }
 
   /** Video input devices (labels are empty until permission is granted). */
@@ -134,6 +164,8 @@ export class BarcodeReader {
       backend: this.grabber.kind,
       worker: this.engine.inWorker,
       workers: this.engine.concurrency,
+      native: this.native !== undefined,
+      nativeMs: this.perf.nativeMs,
     };
   }
 
@@ -282,7 +314,11 @@ export class BarcodeReader {
   async configure(options: EngineOptions): Promise<void> {
     this.assertAlive();
     this.engineOptions = { ...this.engineOptions, ...options };
+    // Detections in flight were made for the old formats: dropped.
+    const generation = ++this.nativeGeneration;
     await this.engine.configure(this.engineOptions);
+    const native = this.nativeFailed ? undefined : await createNative(this.options, this.engineOptions);
+    if (generation === this.nativeGeneration) this.native = native;
   }
 
   /** Allow `text` to be reported again right away. */
@@ -352,13 +388,14 @@ export class BarcodeReader {
    * Back-pressure: at most one grab in flight and one frame waiting for a
    * free worker. While a frame waits, no new grab starts, so frames are
    * skipped, never queued, and the waiting frame is at most one decode old.
+   * The native detection is part of the grab stage, so the same rule keeps
+   * at most one `detect()` in flight.
    */
   private tick(): void {
     if (!this.running) return;
     if (!this.grabbing && !this.pending && !this.paused && this.preview.video.videoWidth > 0) {
       this.grabbing = true;
-      this.grabFrame()
-        .then((frame) => this.enqueue(frame))
+      this.acquire()
         .catch((err) => this.handleFrameError(err))
         .finally(() => (this.grabbing = false));
     }
@@ -366,11 +403,84 @@ export class BarcodeReader {
     this.schedule();
   }
 
-  private async grabFrame(): Promise<GrabbedFrame> {
+  /**
+   * Grab stage. With the native `BarcodeDetector`, the frame is searched
+   * natively first, straight from the `<video>` (Chrome reads it outside the
+   * page's threads): no grab of our own. Codes it finds are committed right
+   * away. When it finds nothing, the engine gets a frame **from time to
+   * time** (`FALLBACK_INTERVAL_MS`), without its fast path, for one fallback
+   * strategy: the safety net for what the native decoder has no
+   * preprocessing for (laser engraving, light-on-dark codes, `micro_qr`…).
+   * Grabbing and decoding every frame as well would double the reads of the
+   * frame and keep the workers busy on frames the native decoder handles,
+   * costing battery and CPU it also needs.
+   */
+  private async acquire(): Promise<void> {
+    const native = this.native;
+    const rect = this.videoRect();
+    if (!native) {
+      this.enqueue(await this.grabFrame(rect, true));
+      return;
+    }
+    const generation = this.nativeGeneration;
+    const t0 = performance.now();
+    let codes: Detection[];
+    try {
+      codes = await native.detect(this.preview.video, rect);
+    } catch (err) {
+      this.disableNative(err);
+      this.enqueue(await this.grabFrame(rect, true));
+      return;
+    }
+    const nativeMs = performance.now() - t0;
+    // Replaced by `configure()` meanwhile: results made for the old formats.
+    if (generation !== this.nativeGeneration || !this.running || this.paused) return;
+
+    if (codes.length === 0 && this.fallbackDue()) {
+      this.fallbackInFlight = true;
+      this.updatePerf({ nativeMs, counted: false });
+      try {
+        this.enqueue(await this.grabFrame(rect, false));
+      } catch (err) {
+        this.fallbackInFlight = false;
+        throw err;
+      }
+      return;
+    }
+    const outcome = await this.engine.commitExternal(codes, nativeMs);
+    if (generation !== this.nativeGeneration || !this.running || this.paused) return;
+    this.failures = 0;
+    this.updatePerf({ nativeMs });
+    // Native points are already in video pixels.
+    this.present(outcome, ++this.grabbed, 'native', (d) => d);
+  }
+
+  /** The engine may decode a frame for its fallbacks (native detector active). */
+  private fallbackDue(): boolean {
+    return !this.fallbackInFlight && performance.now() >= this.nextFallbackAt;
+  }
+
+  /** The native decoder threw: decode with the engine only from now on. */
+  private disableNative(err: unknown): void {
+    if (this.nativeFailed) return;
+    // Like the WebGL → Canvas 2D fallback: the reader keeps working, so this
+    // is a warning, not an `error` event.
+    console.warn('[scanner] native BarcodeDetector failed, decoding with the engine only:', err);
+    this.nativeFailed = true;
+    this.native = undefined;
+    this.nativeGeneration++;
+  }
+
+  /** The region of interest, in video pixels. */
+  private videoRect(): Rect {
     const video = this.preview.video;
     const ew = this.preview.width || video.videoWidth;
     const eh = this.preview.height || video.videoHeight;
-    const rect = regionToVideoRect(this.region, video.videoWidth, video.videoHeight, ew, eh);
+    return regionToVideoRect(this.region, video.videoWidth, video.videoHeight, ew, eh);
+  }
+
+  private async grabFrame(rect: Rect, fastPath: boolean): Promise<GrabbedFrame> {
+    const video = this.preview.video;
     const { width, height } = outputSize(rect, this.options.processing?.maxDimension ?? 1024);
 
     const t0 = performance.now();
@@ -381,12 +491,21 @@ export class BarcodeReader {
       this.buffers.push(buffer);
       throw new GrabError(err);
     }
-    return { buffer, width, height, rect, grabMs: performance.now() - t0, seq: ++this.grabbed };
+    return {
+      buffer,
+      width,
+      height,
+      rect,
+      grabMs: performance.now() - t0,
+      seq: ++this.grabbed,
+      fastPath,
+    };
   }
 
   private enqueue(frame: GrabbedFrame): void {
     if (!this.running || this.paused) {
       this.buffers.push(frame.buffer);
+      if (!frame.fastPath) this.fallbackInFlight = false;
     } else if (this.decoding >= this.engine.concurrency) {
       this.pending = frame;
     } else {
@@ -408,31 +527,58 @@ export class BarcodeReader {
 
   private async decodeFrame(frame: GrabbedFrame): Promise<void> {
     const { width, height, rect } = frame;
-    const reply = await this.engine.processFrame(frame.buffer, width, height, 'luma');
+    let reply: FrameReply;
+    try {
+      reply = await this.engine.processFrame(frame.buffer, width, height, 'luma', frame.fastPath);
+    } finally {
+      if (!frame.fastPath) {
+        this.fallbackInFlight = false;
+        this.nextFallbackAt = performance.now() + FALLBACK_INTERVAL_MS;
+      }
+    }
     this.buffers.push(reply.buffer);
     if (!this.running) return;
     this.failures = 0;
-
-    this.updatePerf(frame.grabMs, reply.decodeMs, width, height);
-
-    const video = this.preview.video;
-    const vw = video.videoWidth;
-    const vh = video.videoHeight;
-    const toVideo = (d: Detection): Detection => ({
+    if (!frame.fastPath && reply.live.length > 0) this.nextFallbackAt = 0;
+
+    this.updatePerf({ grab: frame, decodeMs: reply.decodeMs });
+    // Fallback-only frames (native detector active) are decoded one at a
+    // time, so they cannot finish out of order: numbered when they finish,
+    // after the native frames that ran meanwhile.
+    const seq = frame.fastPath ? frame.seq : ++this.grabbed;
+    this.present(reply, seq, 'engine', (d) => ({
       ...d,
       points: decoderToVideo(d.points, rect, width, height),
-    });
-    // An older frame finishing after a newer one must not move the highlights back.
-    if (frame.seq > this.drawn) {
-      this.drawn = frame.seq;
-      const live = reply.live.map(toVideo);
+    }));
+  }
+
+  /** Draw the live codes of frame `seq` and report the new ones, mapped to video pixels by `toVideo`. */
+  private present(
+    outcome: Pick<FrameOutcome, 'results' | 'live'>,
+    seq: number,
+    source: 'native' | 'engine',
+    toVideo: (d: Detection) => Detection,
+  ): void {
+    // An older frame finishing after a newer one must not move the highlights
+    // back. With the native detector, a decoder that found nothing does not
+    // erase what the other one drew: the native decoder would otherwise
+    // erase, ~30 times per second, a code only the fallbacks can read.
+    const owns = outcome.live.length > 0 || this.highlightSource === source || !this.highlightSource;
+    if (seq > this.drawn && owns) {
+      this.drawn = seq;
+      this.highlightSource = outcome.live.length > 0 ? source : null;
+      const video = this.preview.video;
+      const vw = video.videoWidth;
+      const vh = video.videoHeight;
       const layout = coverLayout(vw, vh, this.preview.width || vw, this.preview.height || vh);
-      this.preview.setDetections(live.map((d) => d.points.map((p) => videoToElement(p, layout))));
+      this.preview.setDetections(
+        outcome.live.map((d) => toVideo(d).points.map((p) => videoToElement(p, layout))),
+      );
     }
 
-    if (reply.results && reply.results.length > 0) {
+    if (outcome.results && outcome.results.length > 0) {
       this.feedback.play();
-      this.emit('detected', reply.results.map(toVideo));
+      this.emit('detected', outcome.results.map(toVideo));
     }
   }
 
@@ -461,13 +607,26 @@ export class BarcodeReader {
     return new ArrayBuffer(size);
   }
 
-  private updatePerf(grabMs: number, decodeMs: number, w: number, h: number): void {
+  /**
+   * Account for a processed frame. `counted: false` for a native miss handed
+   * to the engine: that frame is counted once, when the engine is done.
+   */
+  private updatePerf(s: {
+    grab?: GrabbedFrame;
+    decodeMs?: number;
+    nativeMs?: number;
+    counted?: boolean;
+  }): void {
     const p = this.perf;
-    p.frames++;
-    p.grabMs = p.grabMs ? p.grabMs * 0.9 + grabMs * 0.1 : grabMs;
-    p.decodeMs = p.decodeMs ? p.decodeMs * 0.9 + decodeMs * 0.1 : decodeMs;
-    p.w = w;
-    p.h = h;
+    const ema = (avg: number, v: number) => (avg ? avg * 0.9 + v * 0.1 : v);
+    if (s.counted !== false) p.frames++;
+    if (s.grab) {
+      p.grabMs = ema(p.grabMs, s.grab.grabMs);
+      p.w = s.grab.width;
+      p.h = s.grab.height;
+    }
+    if (s.decodeMs !== undefined) p.decodeMs = ema(p.decodeMs, s.decodeMs);
+    if (s.nativeMs !== undefined) p.nativeMs = ema(p.nativeMs, s.nativeMs);
     const now = performance.now();
     if (now - p.since >= 1000) {
       p.fps = (p.frames * 1000) / (now - p.since);
@@ -518,6 +677,18 @@ class GrabError extends Error {
   }
 }
 
+/** The native detector unless `processing.nativeDetector` is `'off'`, when it can serve `engineOptions`. */
+function createNative(
+  options: ReaderOptions,
+  engineOptions: EngineOptions,
+): Promise<NativeDetector | undefined> {
+  // On by default: on a Galaxy A14 (Chrome, Play Services) it read codes very
+  // well whatever the orientation of the phone, where the engine's fast pass
+  // only reads 1D codes roughly aligned with the image rows.
+  if (options.processing?.nativeDetector === 'off') return Promise.resolve(undefined);
+  return NativeDetector.create(engineOptions.formats);
+}
+
 function waitForVideo(video: HTMLVideoElement): Promise<void> {
   if (video.readyState >= 2 && video.videoWidth > 0) return Promise.resolve();
   return new Promise((resolve, reject) => {