@gueshbzh-perso/scanner 0.5.1 → 0.7.0

package/src/grabber.ts

@@ -0,0 +1,385 @@
+// Frame pipeline: turns a video frame into the small grayscale image the decoder needs.
+//
+// The WebGL2 path does all the per-pixel work on the GPU in a single pass:
+//   upload video texture → crop to the region of interest → RGB→luma
+//   → box-filtered downscale → pack 4 luma pixels per RGBA texel
+// so the CPU readback is exactly `width × height` bytes (4× less than
+// getImageData) and, thanks to a pixel-pack buffer + fence, it does not
+// stall the main thread waiting for the GPU.
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface FrameGrabber {
+  readonly kind: 'webgl' | 'canvas';
+  /**
+   * Render `src` (cropped to `rect`, in source pixels) into `out`, a luma
+   * buffer of `width × height` bytes. `width` must be a multiple of 4.
+   */
+  grab(source: TexImageSource, rect: Rect, width: number, height: number, out: Uint8Array): Promise<void>;
+  destroy(): void;
+}
+
+type AnyCanvas = HTMLCanvasElement | OffscreenCanvas;
+
+function makeCanvas(): AnyCanvas {
+  return typeof OffscreenCanvas !== 'undefined'
+    ? new OffscreenCanvas(4, 4)
+    : document.createElement('canvas');
+}
+
+const VERT = `#version 300 es
+in vec2 a_pos;
+void main() { gl_Position = vec4(a_pos, 0.0, 1.0); }`;
+
+const FRAG = `#version 300 es
+precision highp float;
+uniform sampler2D u_src;
+uniform vec4 u_rect;     // crop rectangle in texture coordinates (origin top-left)
+uniform vec2 u_out;      // size of the luma image
+uniform vec2 u_tap;      // sub-sample offset for the 2x2 box filter
+out vec4 o_color;
+const vec3 LUMA = vec3(0.299, 0.587, 0.114);
+
+float luma(vec2 px) {
+  vec2 uv = u_rect.xy + (px + 0.5) / u_out * u_rect.zw;
+  vec3 c = texture(u_src, uv + vec2(-u_tap.x, -u_tap.y)).rgb
+         + texture(u_src, uv + vec2( u_tap.x, -u_tap.y)).rgb
+         + texture(u_src, uv + vec2(-u_tap.x,  u_tap.y)).rgb
+         + texture(u_src, uv + vec2( u_tap.x,  u_tap.y)).rgb;
+  return dot(c * 0.25, LUMA);
+}
+
+void main() {
+  // Framebuffer row 0 is read back first, so row r samples image row r from the top.
+  float y = floor(gl_FragCoord.y);
+  float x = floor(gl_FragCoord.x) * 4.0;
+  o_color = vec4(luma(vec2(x, y)), luma(vec2(x + 1.0, y)), luma(vec2(x + 2.0, y)), luma(vec2(x + 3.0, y)));
+}`;
+
+export class WebGLGrabber implements FrameGrabber {
+  readonly kind = 'webgl';
+  private gl: WebGL2RenderingContext;
+  private program: WebGLProgram;
+  private srcTex: WebGLTexture;
+  private dstTex: WebGLTexture;
+  private fbo: WebGLFramebuffer;
+  private pbo: WebGLBuffer;
+  private uniforms: Record<'rect' | 'out' | 'tap', WebGLUniformLocation | null>;
+  private size = { w: 0, h: 0 };
+  private lost = false;
+
+  /** Returns `null` when WebGL2 is not available. */
+  static create(): WebGLGrabber | null {
+    try {
+      const canvas = makeCanvas();
+      const gl = canvas.getContext('webgl2', {
+        alpha: true,
+        antialias: false,
+        depth: false,
+        stencil: false,
+        premultipliedAlpha: false,
+        preserveDrawingBuffer: false,
+        powerPreference: 'low-power',
+      }) as WebGL2RenderingContext | null;
+      return gl ? new WebGLGrabber(canvas, gl) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private constructor(canvas: AnyCanvas, gl: WebGL2RenderingContext) {
+    this.gl = gl;
+    (canvas as HTMLCanvasElement).addEventListener?.('webglcontextlost', (e) => {
+      e.preventDefault();
+      this.lost = true;
+    });
+
+    this.program = link(gl, VERT, FRAG);
+    gl.useProgram(this.program);
+
+    // Full-screen triangle.
+    const vbo = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
+    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
+    const loc = gl.getAttribLocation(this.program, 'a_pos');
+    gl.enableVertexAttribArray(loc);
+    gl.vertexAttribPointer(loc, 2, gl.FLOAT, false, 0, 0);
+
+    this.uniforms = {
+      rect: gl.getUniformLocation(this.program, 'u_rect'),
+      out: gl.getUniformLocation(this.program, 'u_out'),
+      tap: gl.getUniformLocation(this.program, 'u_tap'),
+    };
+    gl.uniform1i(gl.getUniformLocation(this.program, 'u_src'), 0);
+
+    this.srcTex = texture(gl);
+    this.dstTex = texture(gl);
+    this.fbo = must(gl.createFramebuffer(), 'framebuffer');
+    this.pbo = must(gl.createBuffer(), 'pixel buffer');
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+    gl.pixelStorei(gl.PACK_ALIGNMENT, 1);
+  }
+
+  async grab(
+    source: TexImageSource,
+    rect: Rect,
+    width: number,
+    height: number,
+    out: Uint8Array,
+  ): Promise<void> {
+    const gl = this.gl;
+    if (this.lost || gl.isContextLost()) throw new Error('WebGL context lost');
+    const [sw, sh] = sourceSize(source);
+    const texW = width / 4;
+
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, this.srcTex);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+
+    if (this.size.w !== texW || this.size.h !== height) {
+      gl.bindTexture(gl.TEXTURE_2D, this.dstTex);
+      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, texW, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+      gl.bindFramebuffer(gl.FRAMEBUFFER, this.fbo);
+      gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.dstTex, 0);
+      gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+      gl.bufferData(gl.PIXEL_PACK_BUFFER, width * height, gl.STREAM_READ);
+      this.size = { w: texW, h: height };
+      gl.bindTexture(gl.TEXTURE_2D, this.srcTex);
+    }
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.fbo);
+    gl.viewport(0, 0, texW, height);
+    gl.uniform4f(this.uniforms.rect, rect.x / sw, rect.y / sh, rect.width / sw, rect.height / sh);
+    gl.uniform2f(this.uniforms.out, width, height);
+    // Box filter footprint: a quarter of an output pixel, only when downscaling.
+    const fx = rect.width / width;
+    const fy = rect.height / height;
+    gl.uniform2f(this.uniforms.tap, fx > 1 ? (0.25 * fx) / sw : 0, fy > 1 ? (0.25 * fy) / sh : 0);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    // Asynchronous readback into the pixel-pack buffer.
+    gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+    gl.readPixels(0, 0, texW, height, gl.RGBA, gl.UNSIGNED_BYTE, 0);
+    const sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
+    gl.flush();
+    if (sync) {
+      await waitSync(gl, sync);
+      gl.deleteSync(sync);
+    }
+    gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+    gl.getBufferSubData(gl.PIXEL_PACK_BUFFER, 0, out, 0, width * height);
+    gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);
+  }
+
+  destroy() {
+    const gl = this.gl;
+    gl.deleteTexture(this.srcTex);
+    gl.deleteTexture(this.dstTex);
+    gl.deleteFramebuffer(this.fbo);
+    gl.deleteBuffer(this.pbo);
+    gl.deleteProgram(this.program);
+    gl.getExtension('WEBGL_lose_context')?.loseContext();
+  }
+}
+
+/** Fallback pipeline using Canvas 2D (`drawImage` does the crop + scale). */
+export class CanvasGrabber implements FrameGrabber {
+  readonly kind = 'canvas';
+  private canvas = makeCanvas();
+  private ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+
+  constructor() {
+    const ctx = this.canvas.getContext('2d', { willReadFrequently: true, alpha: false });
+    this.ctx = must(ctx as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null, '2D context');
+  }
+
+  async grab(
+    source: TexImageSource,
+    rect: Rect,
+    width: number,
+    height: number,
+    out: Uint8Array,
+  ): Promise<void> {
+    if (this.canvas.width !== width || this.canvas.height !== height) {
+      this.canvas.width = width;
+      this.canvas.height = height;
+    }
+    const ctx = this.ctx;
+    ctx.imageSmoothingEnabled = true;
+    ctx.imageSmoothingQuality = 'medium';
+    ctx.drawImage(source as CanvasImageSource, rect.x, rect.y, rect.width, rect.height, 0, 0, width, height);
+    const rgba = ctx.getImageData(0, 0, width, height).data;
+    rgbaToLuma(rgba, out);
+  }
+
+  destroy() {
+    this.canvas.width = this.canvas.height = 0;
+  }
+}
+
+export function createGrabber(backend: 'auto' | 'webgl' | 'canvas' = 'auto'): FrameGrabber {
+  if (backend !== 'canvas') {
+    const gl = WebGLGrabber.create();
+    if (gl) return backend === 'auto' ? new AdaptiveGrabber(gl, () => new CanvasGrabber()) : gl;
+    if (backend === 'webgl') throw new Error('WebGL2 is not available');
+  }
+  return new CanvasGrabber();
+}
+
+/** Frames timed per backend before deciding. */
+const PROBE_FRAMES = 15;
+/** WebGL is kept without probing when its median grab is below this (ms). */
+const SLOW_GRAB_MS = 20;
+/** Canvas 2D must be this much faster to be kept: it blocks the main thread. */
+const CANVAS_WIN_RATIO = 0.6;
+
+/**
+ * `'auto'` backend: WebGL2, unless Canvas 2D is measured to be much faster on
+ * this device.
+ *
+ * WebGL does the crop / luma / downscale on the GPU and reads back 4× less
+ * data, asynchronously, so it is the right default. But on some GPUs the
+ * readback itself is slow (the fence takes tens of ms to signal), and then
+ * the grab limits the frame rate now that decoding runs in parallel. So when
+ * the median WebGL grab exceeds `SLOW_GRAB_MS`, Canvas 2D is timed on the
+ * next `PROBE_FRAMES` frames and kept only if clearly faster (`drawImage` +
+ * `getImageData` run on the main thread, while WebGL waits asynchronously).
+ * The decision is made once, from measurements: no device list.
+ */
+export class AdaptiveGrabber implements FrameGrabber {
+  private active: FrameGrabber;
+  private other: FrameGrabber | null = null;
+  private samples: number[] = [];
+  private webglMedian = 0;
+  private state: 'webgl' | 'probing' | 'decided' = 'webgl';
+
+  constructor(
+    private webgl: FrameGrabber,
+    private makeCanvas: () => FrameGrabber,
+    private now: () => number = () => performance.now(),
+  ) {
+    this.active = webgl;
+  }
+
+  get kind(): 'webgl' | 'canvas' {
+    return this.active.kind;
+  }
+
+  async grab(source: TexImageSource, rect: Rect, width: number, height: number, out: Uint8Array) {
+    const grabber = this.active;
+    const t0 = this.now();
+    await grabber.grab(source, rect, width, height, out);
+    if (this.state !== 'decided' && grabber === this.active) this.record(this.now() - t0);
+  }
+
+  private record(ms: number): void {
+    this.samples.push(ms);
+    if (this.samples.length < PROBE_FRAMES) return;
+    const median = medianOf(this.samples);
+    this.samples = [];
+    if (this.state === 'webgl') {
+      if (median < SLOW_GRAB_MS) {
+        this.state = 'decided';
+        return;
+      }
+      this.webglMedian = median;
+      this.other = this.webgl;
+      this.active = this.makeCanvas();
+      this.state = 'probing';
+      return;
+    }
+    // Probing Canvas 2D: keep it, or go back to WebGL.
+    this.state = 'decided';
+    if (median < this.webglMedian * CANVAS_WIN_RATIO) {
+      this.other?.destroy();
+    } else {
+      this.active.destroy();
+      this.active = this.webgl;
+    }
+    this.other = null;
+  }
+
+  destroy(): void {
+    this.active.destroy();
+    this.other?.destroy();
+  }
+}
+
+function medianOf(values: number[]): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[sorted.length >> 1] ?? 0;
+}
+
+/** BT.601 luma with integer arithmetic (same weights as the GPU path and the engine). */
+export function rgbaToLuma(rgba: Uint8ClampedArray | Uint8Array, out: Uint8Array): void {
+  const n = Math.min(out.length, rgba.length >> 2);
+  for (let i = 0, j = 0; i < n; i++, j += 4) {
+    // In bounds by construction (`n`): `?? 0` only satisfies the type checker.
+    out[i] = (19595 * (rgba[j] ?? 0) + 38470 * (rgba[j + 1] ?? 0) + 7471 * (rgba[j + 2] ?? 0)) >> 16;
+  }
+}
+
+export function sourceSize(source: TexImageSource): [number, number] {
+  if (typeof HTMLVideoElement !== 'undefined' && source instanceof HTMLVideoElement) {
+    return [source.videoWidth, source.videoHeight];
+  }
+  if (typeof HTMLImageElement !== 'undefined' && source instanceof HTMLImageElement) {
+    return [source.naturalWidth, source.naturalHeight];
+  }
+  if (typeof VideoFrame !== 'undefined' && source instanceof VideoFrame) {
+    return [source.displayWidth, source.displayHeight];
+  }
+  const s = source as { width: number; height: number };
+  return [s.width, s.height];
+}
+
+// ── WebGL helpers ──────────────────────────────────────────────────────────
+
+function must<T>(v: T | null, what: string): T {
+  if (!v) throw new Error(`WebGL: failed to create ${what}`);
+  return v;
+}
+
+function texture(gl: WebGL2RenderingContext): WebGLTexture {
+  const t = must(gl.createTexture(), 'texture');
+  gl.bindTexture(gl.TEXTURE_2D, t);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  return t;
+}
+
+function link(gl: WebGL2RenderingContext, vs: string, fs: string): WebGLProgram {
+  const compile = (type: number, src: string) => {
+    const s = must(gl.createShader(type), 'shader');
+    gl.shaderSource(s, src);
+    gl.compileShader(s);
+    if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) throw new Error(`Shader: ${gl.getShaderInfoLog(s)}`);
+    return s;
+  };
+  const p = must(gl.createProgram(), 'program');
+  gl.attachShader(p, compile(gl.VERTEX_SHADER, vs));
+  gl.attachShader(p, compile(gl.FRAGMENT_SHADER, fs));
+  gl.linkProgram(p);
+  if (!gl.getProgramParameter(p, gl.LINK_STATUS)) throw new Error(`Program: ${gl.getProgramInfoLog(p)}`);
+  return p;
+}
+
+function waitSync(gl: WebGL2RenderingContext, sync: WebGLSync): Promise<void> {
+  return new Promise((resolve) => {
+    const started = performance.now();
+    const poll = () => {
+      const status = gl.clientWaitSync(sync, 0, 0);
+      // Give up waiting after 50 ms: getBufferSubData will then block, but never hang.
+      if (status !== gl.TIMEOUT_EXPIRED || performance.now() - started > 50) resolve();
+      else setTimeout(poll, 1);
+    };
+    poll();
+  });
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { BarcodeReader } from './reader.js';
+export { scanImage, type ImageInput, type ScanImageOptions } from './scan-image.js';
+export { createEngine, type Engine, type FrameReply } from './engine.js';
+export { listCameras } from './camera.js';
+export type {
+  AssetOptions,
+  BarcodeFormat,
+  CameraOptions,
+  CameraResolution,
+  Detection,
+  EngineOptions,
+  FeedbackOptions,
+  OverlayOptions,
+  Point,
+  ProcessingOptions,
+  ReaderEvents,
+  ReaderOptions,
+  ReaderStats,
+  Region,
+} from './types.js';

package/src/overlay.ts

@@ -0,0 +1,225 @@
+// Camera preview DOM + canvas overlay (region of interest, detection highlights, buttons).
+import type { OverlayOptions, Point, Region } from './types.js';
+
+const TORCH_ICON =
+  '<svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M6 2h12v5l-3 4v11H9V11L6 7z"/><path d="M12 14v2"/></svg>';
+const SWITCH_ICON =
+  '<svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 7h3l2-3h6l2 3h3v12H4z"/><path d="M9 13a3 3 0 0 1 5-2.2M15 13a3 3 0 0 1-5 2.2"/><path d="M14 9v2h-2M10 17v-2h2"/></svg>';
+
+const HIGHLIGHT_MS = 400;
+
+export class Preview {
+  readonly root: HTMLDivElement;
+  readonly video: HTMLVideoElement;
+  private canvas: HTMLCanvasElement;
+  private ctx: CanvasRenderingContext2D | null;
+  private controls: HTMLDivElement;
+  private torchBtn: HTMLButtonElement;
+  private switchBtn: HTMLButtonElement;
+  private resizeObserver: ResizeObserver | null = null;
+  private region: Region = { x: 0, y: 0, width: 1, height: 1 };
+  private detections: { polygons: Point[][]; at: number } = { polygons: [], at: 0 };
+  private dirty = true;
+  private opts: Required<OverlayOptions> | null;
+  private restoreHostPosition: string | null = null;
+
+  constructor(
+    private host: HTMLElement,
+    options: OverlayOptions | false | undefined,
+  ) {
+    this.opts =
+      options === false
+        ? null
+        : {
+            showRegion: true,
+            showDetections: true,
+            showTorchButton: true,
+            showCameraSwitch: true,
+            color: '#00d4aa',
+            ...options,
+          };
+
+    if (getComputedStyle(host).position === 'static') {
+      this.restoreHostPosition = host.style.position;
+      host.style.position = 'relative';
+    }
+
+    this.root = el('div', 'position:absolute;inset:0;overflow:hidden;background:#000;');
+    this.root.className = 'scanner-preview';
+
+    this.video = el('video', 'position:absolute;inset:0;width:100%;height:100%;object-fit:cover;');
+    this.video.muted = true;
+    this.video.playsInline = true;
+    this.video.autoplay = true;
+    this.video.setAttribute('playsinline', '');
+    this.video.setAttribute('muted', '');
+
+    this.canvas = el('canvas', 'position:absolute;inset:0;width:100%;height:100%;pointer-events:none;');
+    this.ctx = this.canvas.getContext('2d');
+
+    this.controls = el('div', 'position:absolute;right:12px;bottom:12px;display:flex;gap:8px;');
+    this.torchBtn = button(TORCH_ICON, 'Toggle flashlight');
+    this.switchBtn = button(SWITCH_ICON, 'Switch camera');
+    this.controls.append(this.switchBtn, this.torchBtn);
+
+    this.root.append(this.video, this.canvas, this.controls);
+    host.append(this.root);
+
+    if (typeof ResizeObserver !== 'undefined') {
+      this.resizeObserver = new ResizeObserver(() => (this.dirty = true));
+      this.resizeObserver.observe(this.root);
+    }
+  }
+
+  get width(): number {
+    return this.root.clientWidth;
+  }
+
+  get height(): number {
+    return this.root.clientHeight;
+  }
+
+  setRegion(region: Region): void {
+    this.region = region;
+    this.dirty = true;
+  }
+
+  /** Polygons in element (CSS pixel) coordinates. */
+  setDetections(polygons: Point[][]): void {
+    if (!this.opts?.showDetections) return;
+    if (polygons.length === 0 && this.detections.polygons.length === 0) return;
+    if (polygons.length > 0) this.detections = { polygons, at: performance.now() };
+    this.dirty = true;
+  }
+
+  setTorchButton(visible: boolean, on: boolean, onClick: () => void): void {
+    const show = visible && !!this.opts?.showTorchButton;
+    this.torchBtn.style.display = show ? 'flex' : 'none';
+    this.torchBtn.style.background = on ? (this.opts?.color ?? '#00d4aa') : 'rgba(0,0,0,0.55)';
+    this.torchBtn.onclick = onClick;
+  }
+
+  setSwitchButton(visible: boolean, onClick: () => void): void {
+    this.switchBtn.style.display = visible && this.opts?.showCameraSwitch ? 'flex' : 'none';
+    this.switchBtn.onclick = onClick;
+  }
+
+  /** Redraw if something changed. Cheap to call on every frame. */
+  render(): void {
+    const ctx = this.ctx;
+    if (!ctx || !this.opts) return;
+    const now = performance.now();
+    const age = now - this.detections.at;
+    const highlighting = this.detections.polygons.length > 0 && age < HIGHLIGHT_MS;
+    if (!this.dirty && !highlighting) return;
+    this.dirty = highlighting; // keep animating the fade-out
+
+    const dpr = window.devicePixelRatio || 1;
+    const w = this.width;
+    const h = this.height;
+    if (this.canvas.width !== Math.round(w * dpr) || this.canvas.height !== Math.round(h * dpr)) {
+      this.canvas.width = Math.round(w * dpr);
+      this.canvas.height = Math.round(h * dpr);
+    }
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.clearRect(0, 0, w, h);
+
+    const color = this.opts.color;
+    if (this.opts.showRegion) {
+      const r = this.region;
+      const rx = r.x * w;
+      const ry = r.y * h;
+      const rw = r.width * w;
+      const rh = r.height * h;
+      ctx.fillStyle = 'rgba(0,0,0,0.45)';
+      ctx.beginPath();
+      ctx.rect(0, 0, w, h);
+      ctx.rect(rx, ry, rw, rh);
+      ctx.fill('evenodd');
+
+      const c = Math.min(24, rw / 4, rh / 4);
+      ctx.strokeStyle = color;
+      ctx.lineWidth = 3;
+      ctx.lineCap = 'round';
+      ctx.beginPath();
+      const corners: [number, number, number, number][] = [
+        [rx, ry, 1, 1],
+        [rx + rw, ry, -1, 1],
+        [rx, ry + rh, 1, -1],
+        [rx + rw, ry + rh, -1, -1],
+      ];
+      for (const [x, y, dx, dy] of corners) {
+        ctx.moveTo(x + dx * c, y);
+        ctx.lineTo(x, y);
+        ctx.lineTo(x, y + dy * c);
+      }
+      ctx.stroke();
+    }
+
+    if (highlighting) {
+      ctx.globalAlpha = 1 - age / HIGHLIGHT_MS;
+      ctx.strokeStyle = color;
+      ctx.fillStyle = withAlpha(color, 0.25);
+      ctx.lineWidth = 3;
+      for (const poly of this.detections.polygons) {
+        drawPolygon(ctx, poly);
+      }
+      ctx.globalAlpha = 1;
+    }
+  }
+
+  destroy(): void {
+    this.resizeObserver?.disconnect();
+    this.video.srcObject = null;
+    this.root.remove();
+    if (this.restoreHostPosition !== null) this.host.style.position = this.restoreHostPosition;
+  }
+}
+
+function drawPolygon(ctx: CanvasRenderingContext2D, pts: Point[]): void {
+  const [first, second] = pts;
+  if (!first) return;
+  ctx.beginPath();
+  if (pts.length === 2 && second) {
+    // 1D codes report the two ends of the scan line: draw a thick bar.
+    ctx.save();
+    ctx.lineWidth = 10;
+    ctx.globalAlpha *= 0.6;
+    ctx.moveTo(first.x, first.y);
+    ctx.lineTo(second.x, second.y);
+    ctx.stroke();
+    ctx.restore();
+    return;
+  }
+  ctx.moveTo(first.x, first.y);
+  for (const p of pts.slice(1)) ctx.lineTo(p.x, p.y);
+  ctx.closePath();
+  ctx.fill();
+  ctx.stroke();
+}
+
+function withAlpha(color: string, alpha: number): string {
+  const hex = /^#([0-9a-f]{6})$/i.exec(color)?.[1];
+  if (!hex) return color;
+  const n = parseInt(hex, 16);
+  return `rgba(${n >> 16},${(n >> 8) & 255},${n & 255},${alpha})`;
+}
+
+function el<K extends keyof HTMLElementTagNameMap>(tag: K, css: string): HTMLElementTagNameMap[K] {
+  const e = document.createElement(tag);
+  e.style.cssText = css;
+  return e;
+}
+
+function button(icon: string, label: string): HTMLButtonElement {
+  const b = el(
+    'button',
+    'display:none;align-items:center;justify-content:center;width:44px;height:44px;border-radius:50%;' +
+      'border:none;color:#fff;background:rgba(0,0,0,0.55);cursor:pointer;padding:0;',
+  );
+  b.type = 'button';
+  b.innerHTML = icon;
+  b.title = label;
+  b.setAttribute('aria-label', label);
+  return b;
+}

package/src/protocol.ts

@@ -0,0 +1,38 @@
+// Messages exchanged between the SDK and its decoding Web Workers.
+import type { FramePlan, FrameReport } from './core.js';
+import type { PixelFormat } from './wasm/scanner_wasm.js';
+import type { Detection, EngineOptions } from './types.js';
+
+export type WorkerRequest =
+  /** `module` is compiled once on the main thread and shared by every worker. */
+  | { id: number; type: 'init'; module: WebAssembly.Module }
+  | { id: number; type: 'configure'; options: EngineOptions }
+  | {
+      id: number;
+      type: 'decode';
+      buffer: ArrayBuffer;
+      width: number;
+      height: number;
+      format: PixelFormat;
+      plan: FramePlan;
+    }
+  | {
+      id: number;
+      type: 'scan';
+      buffer: ArrayBuffer;
+      width: number;
+      height: number;
+      format: PixelFormat;
+      options: EngineOptions;
+    };
+
+export type WorkerResponse =
+  | {
+      id: number;
+      ok: true;
+      version?: string;
+      report?: FrameReport;
+      results?: Detection[];
+      buffer?: ArrayBuffer;
+    }
+  | { id: number; ok: false; error: string; fatal?: boolean; buffer?: ArrayBuffer };