@livx.cc/native-kit 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Isomorphic native-capabilities kit for PWAs — same API in browser and in an appwrap native shell. Zero dependencies.",
   "license": "MIT",
   "author": "Elya Livshitz",

package/src/core/NativeKit.ts

@@ -9,6 +9,7 @@ import { CalendarModule } from '../modules/calendar';
 import { ClipboardModule } from '../modules/clipboard';
 import { ContactsModule } from '../modules/contacts';
 import { DeviceModule } from '../modules/device';
+import { FsModule } from '../modules/fs';
 import { GeoModule } from '../modules/geo';
 import { HapticsModule } from '../modules/haptics';
 import { HealthModule } from '../modules/health';
@@ -22,6 +23,7 @@ import { OAuthModule } from '../modules/oauth';
 import { PhotosModule } from '../modules/photos';
 import { PushModule } from '../modules/push';
 import { ReviewsModule } from '../modules/reviews';
+import { ScannerModule } from '../modules/scanner';
 import { ScreenModule } from '../modules/screen';
 import { ShareModule } from '../modules/share';
 import { StorageModule } from '../modules/storage';
@@ -73,6 +75,7 @@ export class NativeKit {
   public readonly screen = new ScreenModule(this);
   public readonly keyboard = new KeyboardModule(this);
   public readonly storage = new StorageModule(this);
+  public readonly fs = new FsModule(this);
   public readonly toast = new ToastModule(this);
   public readonly ui = new UiModule(this);
   public readonly device = new DeviceModule(this);
@@ -89,6 +92,7 @@ export class NativeKit {
   public readonly health = new HealthModule(this);
   public readonly media = new MediaModule(this);
   public readonly contacts = new ContactsModule(this);
+  public readonly scanner = new ScannerModule(this);
   public readonly calendar = new CalendarModule(this);
   public readonly app = new AppModule(this);
   public readonly browser = new BrowserModule(this);

package/src/core/web-adapter.ts

@@ -8,6 +8,14 @@ function base64ToBuffer(b64: string): ArrayBuffer {
   return out.buffer;
 }
 
+/** Encode an ArrayBuffer → raw base64 (no `data:` prefix). */
+function bufferToBase64(buf: ArrayBuffer): string {
+  const bytes = new Uint8Array(buf);
+  let bin = '';
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin);
+}
+
 /** Map our lock vocabulary to valid ScreenOrientation `OrientationLockType` values. */
 function toWebOrientation(o: string): any {
   switch (o) {
@@ -30,6 +38,8 @@ export class WebAdapter implements NativeKitAdapter {
   private listeners = new Map<string, Set<(payload: unknown) => void>>();
   private geoWatchId: number | null = null;
   private motionHandler: ((e: DeviceMotionEvent) => void) | null = null;
+  /** Tear-down for an in-progress scanner.scan loop (stops the camera, removes the overlay). */
+  private scanCancel: (() => void) | null = null;
 
   detect(): boolean {
     return typeof window !== 'undefined';
@@ -44,6 +54,9 @@ export class WebAdapter implements NativeKitAdapter {
       orientation: (screen as any)?.orientation ? 'web' : 'none', // Screen Orientation API (lock needs fullscreen)
       storage: 'web',
       secureStorage: 'none',
+      // OPFS (navigator.storage.getDirectory) backs read/write/list; pickFile falls back to
+      // <input type=file> even without OPFS, so 'web' whenever either surface exists.
+      fs: n.storage?.getDirectory || typeof document !== 'undefined' ? 'web' : 'none',
       toast: 'web',
       statusBar: 'none',
       device: 'web',
@@ -64,6 +77,8 @@ export class WebAdapter implements NativeKitAdapter {
       calendar: 'none',
       camera: 'web', // <input capture> — mobile browsers open the camera
       media: (navigator as any).mediaDevices?.getUserMedia ? 'web' : 'none',
+      // BarcodeDetector (Chrome/Android) decodes; needs a getUserMedia stream to feed it. Both → 'web'.
+      scanner: typeof (window as any).BarcodeDetector !== 'undefined' && (navigator as any).mediaDevices?.getUserMedia ? 'web' : 'none',
       app: 'web', // openUrl via window.open; openSettings unsupported
       browser: 'web', // new tab/window
       billing: 'none', // no IAP in a plain browser — wire a web checkout yourself
@@ -310,11 +325,37 @@ export class WebAdapter implements NativeKitAdapter {
       case 'calendar.createEvent':
         throw new KitError('UNSUPPORTED', 'No calendar access on web');
 
+      case 'scanner.scan':
+        return this.scanBarcode(p.formats, p.camera === 'front' ? 'user' : 'environment') as Promise<T>;
+      case 'scanner.cancel':
+        this.scanCancel?.();
+        return undefined as T;
+
       case 'photos.pick':
         return this.pickImageFile(false, !!p.dataUrl, p.maxSize) as Promise<T>;
       case 'camera.capture':
         return this.pickImageFile(true, !!p.dataUrl, p.maxSize) as Promise<T>;
 
+      case 'fs.read':
+        return this.opfsRead(p.path, p.encoding === 'base64' ? 'base64' : 'utf8') as Promise<T>;
+      case 'fs.write':
+        return this.opfsWrite(p.path, p.data, p.encoding === 'base64' ? 'base64' : 'utf8', false, !!p.recursive) as Promise<T>;
+      case 'fs.append':
+        return this.opfsWrite(p.path, p.data, p.encoding === 'base64' ? 'base64' : 'utf8', true, true) as Promise<T>;
+      case 'fs.delete':
+        return this.opfsDelete(p.path) as Promise<T>;
+      case 'fs.list':
+        return this.opfsList(p.path) as Promise<T>;
+      case 'fs.mkdir':
+        return this.opfsMkdir(p.path) as Promise<T>;
+      case 'fs.stat':
+        return this.opfsStat(p.path) as Promise<T>;
+      case 'fs.getUri':
+        // OPFS files have no URL the page can hand around — be honest rather than fake one.
+        throw new KitError('UNSUPPORTED', 'No file URI on web (OPFS is opaque) — read the bytes instead');
+      case 'fs.pickFile':
+        return this.pickDocuments(p.types, !!p.multiple) as Promise<T>;
+
       case 'media.configureAudio':
         return undefined as T; // browser owns the audio session — nothing to tune
 
@@ -416,6 +457,96 @@ export class WebAdapter implements NativeKitAdapter {
     this.listeners.get(event)?.forEach((cb) => cb(payload));
   }
 
+  /** Map our small format enum → BarcodeDetector `formats` strings. Omit/`'all'` = detector default. */
+  private toDetectorFormats(formats?: string | string[]): string[] | undefined {
+    const want = (Array.isArray(formats) ? formats : formats ? [formats] : []).filter((f) => f && f !== 'all');
+    if (!want.length) return undefined;
+    const map: Record<string, string> = { qr: 'qr_code', ean13: 'ean_13', code128: 'code_128' };
+    return want.map((f) => map[f] ?? f);
+  }
+
+  /** Reverse map a detector format string → our enum (best-effort). */
+  private fromDetectorFormat(f: string): 'qr' | 'ean13' | 'code128' | 'unknown' {
+    if (f === 'qr_code') return 'qr';
+    if (f === 'ean_13') return 'ean13';
+    if (f === 'code_128') return 'code128';
+    return 'unknown';
+  }
+
+  /**
+   * Open a full-screen camera overlay, run a BarcodeDetector loop, resolve the FIRST hit then tear
+   * down. Resolves `{ cancelled: true }` if the user taps the close button or `scanner.cancel` fires.
+   */
+  private scanBarcode(
+    formats: string | string[] | undefined,
+    facingMode: 'environment' | 'user'
+  ): Promise<{ value: string; format: string; bounds?: any } | { cancelled: true }> {
+    const Detector = (window as any).BarcodeDetector;
+    const getUserMedia = (navigator as any).mediaDevices?.getUserMedia?.bind((navigator as any).mediaDevices);
+    if (!Detector || !getUserMedia) throw new KitError('UNSUPPORTED', 'BarcodeDetector / camera unavailable in this browser');
+
+    return new Promise(async (resolve, reject) => {
+      let stream: MediaStream | null = null;
+      let raf = 0;
+      let done = false;
+      const wrap = document.createElement('div');
+      const video = document.createElement('video');
+
+      const teardown = () => {
+        if (done) return;
+        done = true;
+        cancelAnimationFrame(raf);
+        stream?.getTracks().forEach((t) => t.stop());
+        wrap.remove();
+        // Only clear if it's still OUR handler — a newer scan may have replaced it.
+        if (this.scanCancel === cancelHandler) this.scanCancel = null;
+      };
+      const cancelHandler = () => { teardown(); resolve({ cancelled: true }); };
+      this.scanCancel = cancelHandler;
+
+      try {
+        const detector = new Detector(this.toDetectorFormats(formats) ? { formats: this.toDetectorFormats(formats) } : undefined);
+        stream = await getUserMedia({ video: { facingMode } });
+        wrap.style.cssText = 'position:fixed;inset:0;background:#000;z-index:99999;display:flex;flex-direction:column';
+        video.setAttribute('playsinline', '');
+        video.muted = true;
+        video.style.cssText = 'flex:1;width:100%;height:100%;object-fit:cover';
+        (video as any).srcObject = stream;
+        const close = document.createElement('button');
+        close.textContent = 'Cancel';
+        close.style.cssText = 'position:absolute;top:max(12px,env(safe-area-inset-top));right:16px;z-index:1;background:rgba(0,0,0,.5);color:#fff;border:0;border-radius:18px;padding:8px 16px;font:15px system-ui';
+        close.onclick = () => { teardown(); resolve({ cancelled: true }); };
+        wrap.appendChild(video);
+        wrap.appendChild(close);
+        document.body.appendChild(wrap);
+        await video.play();
+
+        const tick = async () => {
+          if (done) return;
+          try {
+            const codes = await detector.detect(video);
+            if (codes?.length) {
+              const c = codes[0];
+              const b = c.boundingBox;
+              teardown();
+              resolve({
+                value: c.rawValue,
+                format: this.fromDetectorFormat(c.format),
+                bounds: b ? { x: b.x, y: b.y, width: b.width, height: b.height } : undefined,
+              });
+              return;
+            }
+          } catch { /* transient detect error — keep looping */ }
+          raf = requestAnimationFrame(tick);
+        };
+        raf = requestAnimationFrame(tick);
+      } catch (e: any) {
+        teardown();
+        reject(new KitError(e?.name === 'NotAllowedError' ? 'DENIED' : 'NATIVE_ERROR', e?.message ?? 'scan failed'));
+      }
+    });
+  }
+
   private pickImageFile(
     capture: boolean,
     wantDataUrl = false,
@@ -455,6 +586,105 @@ export class WebAdapter implements NativeKitAdapter {
     });
   }
 
+  // ── filesystem (Origin Private File System) ─────────────────────────
+  // OPFS is one private root per origin — our `dir` enum has no meaning here, so paths resolve
+  // straight off the root. Slash-separated paths walk nested dirs.
+
+  private async opfsRoot(): Promise<any> {
+    const dir = (navigator as any).storage?.getDirectory;
+    if (!dir) throw new KitError('UNSUPPORTED', 'No OPFS in this browser');
+    return (navigator as any).storage.getDirectory();
+  }
+
+  /** Split a path into clean segments, rejecting any `..` so it can't escape the OPFS root. */
+  private opfsSegments(path: string): string[] {
+    const parts = String(path).split('/').filter(Boolean);
+    if (parts.some((seg) => seg === '..')) throw new KitError('NATIVE_ERROR', `Path traversal rejected: ${path}`);
+    return parts;
+  }
+
+  /** Walk `path` to its parent dir handle + leaf name. `create` makes intermediate dirs. */
+  private async opfsResolveParent(path: string, create: boolean): Promise<{ parent: any; name: string }> {
+    const parts = this.opfsSegments(path);
+    const name = parts.pop();
+    if (!name) throw new KitError('NATIVE_ERROR', 'Empty path');
+    let dir = await this.opfsRoot();
+    for (const seg of parts) dir = await dir.getDirectoryHandle(seg, { create });
+    return { parent: dir, name };
+  }
+
+  private async opfsRead(path: string, encoding: 'utf8' | 'base64'): Promise<string> {
+    const { parent, name } = await this.opfsResolveParent(path, false);
+    const handle = await parent.getFileHandle(name).catch(() => { throw new KitError('NATIVE_ERROR', `No such file: ${path}`); });
+    const file = await handle.getFile();
+    if (encoding === 'base64') return bufferToBase64(await file.arrayBuffer());
+    return file.text();
+  }
+
+  private async opfsWrite(path: string, data: string, encoding: 'utf8' | 'base64', append: boolean, recursive: boolean): Promise<{ uri: string }> {
+    const { parent, name } = await this.opfsResolveParent(path, recursive);
+    const handle = await parent.getFileHandle(name, { create: true });
+    const writable = await handle.createWritable({ keepExistingData: append });
+    if (append) writable.seek?.((await handle.getFile()).size);
+    const payload: BlobPart = encoding === 'base64' ? base64ToBuffer(data) : data;
+    await writable.write(payload);
+    await writable.close();
+    return { uri: `opfs:/${path}` };
+  }
+
+  private async opfsDelete(path: string): Promise<void> {
+    const { parent, name } = await this.opfsResolveParent(path, false);
+    await parent.removeEntry(name, { recursive: false }).catch(() => {}); // no-throw if absent
+  }
+
+  private async opfsList(path: string): Promise<Array<{ name: string; type: 'file' | 'dir' }>> {
+    let dir = await this.opfsRoot();
+    for (const seg of this.opfsSegments(path)) dir = await dir.getDirectoryHandle(seg);
+    const out: Array<{ name: string; type: 'file' | 'dir' }> = [];
+    for await (const [name, handle] of (dir as any).entries()) {
+      out.push({ name, type: handle.kind === 'directory' ? 'dir' : 'file' });
+    }
+    return out;
+  }
+
+  private async opfsMkdir(path: string): Promise<void> {
+    let dir = await this.opfsRoot();
+    for (const seg of this.opfsSegments(path)) dir = await dir.getDirectoryHandle(seg, { create: true });
+  }
+
+  private async opfsStat(path: string): Promise<{ name: string; type: 'file' | 'dir'; size?: number; mtime?: number }> {
+    const { parent, name } = await this.opfsResolveParent(path, false);
+    const fileHandle = await parent.getFileHandle(name).catch(() => null);
+    if (fileHandle) {
+      const f = await fileHandle.getFile();
+      return { name, type: 'file', size: f.size, mtime: f.lastModified };
+    }
+    await parent.getDirectoryHandle(name).catch(() => { throw new KitError('NATIVE_ERROR', `No such path: ${path}`); });
+    return { name, type: 'dir' };
+  }
+
+  /** Document picker via a hidden `<input type=file>` (works everywhere; reuses the photos pattern). */
+  private pickDocuments(types?: string[], multiple = false): Promise<Array<{ name: string; mimeType: string; size: number; base64: string }>> {
+    const toPicked = async (file: File) => ({
+      name: file.name,
+      mimeType: file.type || 'application/octet-stream',
+      size: file.size,
+      base64: bufferToBase64(await file.arrayBuffer()),
+    });
+    return new Promise((resolve) => {
+      const input = document.createElement('input');
+      input.type = 'file';
+      if (multiple) input.multiple = true;
+      if (types?.length) input.accept = types.join(',');
+      input.onchange = async () => {
+        const files = Array.from(input.files ?? []);
+        resolve(await Promise.all(files.map(toPicked)));
+      };
+      input.oncancel = () => resolve([]);
+      input.click();
+    });
+  }
+
   /** Minimal action sheet — fixed bottom panel, resolves option index or null on cancel. */
   private showActionSheet(title: string | undefined, options: string[], cancel: string): Promise<number | null> {
     return new Promise((resolve) => {

package/src/index.ts

@@ -23,6 +23,7 @@ export type { ImpactStyle, NotifyType } from './modules/haptics';
 export type { SharePayload, ShareFile } from './modules/share';
 export type { Orientation, OrientationLock } from './modules/screen';
 export type { KeyboardInfo } from './modules/keyboard';
+export type { FsDirectory, FsEncoding, FsEntry, PickedFile } from './modules/fs';
 export type { DeviceInfo } from './modules/device';
 export type { ScheduleOptions } from './modules/notifications';
 export type { PushMessage, PushPlatform, PushToken } from './modules/push';
@@ -34,6 +35,8 @@ export type { ActionOptions, AlertOptions, ConfirmOptions, SafeAreaInsets } from
 export type { MotionSample } from './modules/motion';
 export type { UpdateStatus, UpdatesOptions } from './modules/updates';
 export type { PickedContact } from './modules/contacts';
+export type { ScanFormat, ScanOptions, ScanResult, ScanCancelled } from './modules/scanner';
+export { isScanResult } from './modules/scanner';
 export type { CalendarEventOptions } from './modules/calendar';
 export type { BrowserOptions } from './modules/browser';
 export type { OAuthAuthorizeParams, OAuthResult } from './modules/oauth';

package/src/modules/fs.ts

@@ -0,0 +1,109 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/** App-scoped storage roots — paths are resolved relative to one of these.
+ *  - `documents`: user-visible (iOS Documents — iCloud-backed-up · Android getExternalFilesDir —
+ *    NOT auto-backed-up, lives on shared/external storage).
+ *  - `data`: app-private (iOS Application Support — backed up · Android getFilesDir — included in
+ *    Auto Backup by default, subject to the app's backup rules). Default.
+ *  - `cache`: evictable, the OS may purge it and it isn't backed up (iOS Caches · Android getCacheDir). */
+export type FsDirectory = 'documents' | 'data' | 'cache';
+
+/** Text vs binary payload encoding. `utf8` reads/writes a string; `base64` a raw byte blob. */
+export type FsEncoding = 'utf8' | 'base64';
+
+/** One entry returned by {@link FsModule.list} / {@link FsModule.stat}. */
+export interface FsEntry {
+  /** Base name (list) or full relative path (stat input echo). */
+  name: string;
+  type: 'file' | 'dir';
+  /** Bytes for a file; omitted/0 for a dir. */
+  size?: number;
+  /** Last-modified epoch ms. */
+  mtime?: number;
+  /** Native URI (`file://` on native, omitted on web). */
+  uri?: string;
+}
+
+/** A document chosen via {@link FsModule.pickFile}. `base64` carries the bytes inline. */
+export interface PickedFile {
+  name: string;
+  mimeType: string;
+  size: number;
+  base64?: string;
+}
+
+export interface FsReadOptions { dir?: FsDirectory; encoding?: FsEncoding }
+export interface FsWriteOptions { dir?: FsDirectory; encoding?: FsEncoding; recursive?: boolean }
+export interface FsDirOptions { dir?: FsDirectory }
+export interface FsMkdirOptions { dir?: FsDirectory; recursive?: boolean }
+export interface FsPickOptions {
+  /** MIME types / extensions to allow (e.g. `['application/pdf', 'image/*']`). Omit = any. */
+  types?: string[];
+  /** Allow multi-select (default false). */
+  multiple?: boolean;
+}
+
+/**
+ * Native filesystem + document picker — ONE API across platforms.
+ *
+ * Read/write/list/stat files under three app-scoped roots ({@link FsDirectory}) plus a system
+ * document picker. No runtime permission is needed: every root lives inside the app sandbox and
+ * the picker hands back security-scoped (iOS) / SAF (Android) URIs the user explicitly chose.
+ *
+ * Native (iOS `FileManager`, Android `java.io.File`) → `capability === 'native'`. Web maps file
+ * I/O to the Origin Private File System (`'web'` where present, else `'none'`) and `pickFile` to
+ * the File System Access API / a hidden `<input type=file>` fallback. Branch on {@link capability}.
+ */
+export class FsModule {
+  constructor(private kit: NativeKit) {}
+
+  /** 'native' on a shell · 'web' where OPFS exists · else 'none'. */
+  get capability() {
+    return this.kit.capability('fs');
+  }
+
+  /** Read a file. `utf8` (default) → string; `base64` → base64 string. */
+  read(path: string, opts: FsReadOptions = {}): Promise<string> {
+    return this.kit.invoke('fs.read', { path, ...opts });
+  }
+
+  /** Write `data` to `path` (overwrites). `recursive` creates missing parent dirs. → `{ uri }`. */
+  write(path: string, data: string, opts: FsWriteOptions = {}): Promise<{ uri: string }> {
+    return this.kit.invoke('fs.write', { path, data, ...opts });
+  }
+
+  /** Append `data` to `path` (creates it if absent). */
+  append(path: string, data: string, opts: FsWriteOptions = {}): Promise<void> {
+    return this.kit.invoke('fs.append', { path, data, ...opts });
+  }
+
+  /** Delete a file or empty directory. No-throw if it doesn't exist. */
+  delete(path: string, opts: FsDirOptions = {}): Promise<void> {
+    return this.kit.invoke('fs.delete', { path, ...opts });
+  }
+
+  /** List a directory's immediate children. */
+  list(path: string, opts: FsDirOptions = {}): Promise<FsEntry[]> {
+    return this.kit.invoke('fs.list', { path, ...opts });
+  }
+
+  /** Create a directory. `recursive` (default true) makes intermediate dirs. */
+  mkdir(path: string, opts: FsMkdirOptions = {}): Promise<void> {
+    return this.kit.invoke('fs.mkdir', { path, ...opts });
+  }
+
+  /** Stat a file/dir → `{ name, type, size, mtime, uri }`. */
+  stat(path: string, opts: FsDirOptions = {}): Promise<FsEntry> {
+    return this.kit.invoke('fs.stat', { path, ...opts });
+  }
+
+  /** Resolve a path to a URI suitable for `kit.share` (`file://` native, content:// Android). */
+  getUri(path: string, opts: FsDirOptions = {}): Promise<string> {
+    return this.kit.invoke('fs.getUri', { path, ...opts });
+  }
+
+  /** Open the system document picker. Resolves with the chosen files (bytes inline as base64). */
+  pickFile(opts: FsPickOptions = {}): Promise<PickedFile[]> {
+    return this.kit.invoke('fs.pickFile', opts);
+  }
+}

package/src/modules/scanner.ts

@@ -0,0 +1,63 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/** Symbologies the scanner can decode. `'all'` (default) accepts every supported format. */
+export type ScanFormat = 'qr' | 'ean13' | 'code128' | 'all';
+
+/** A successfully decoded code. */
+export interface ScanResult {
+  /** Decoded payload (the string the barcode/QR encodes). */
+  value: string;
+  /** Detected symbology — one of {@link ScanFormat} minus `'all'`, or `'unknown'`. */
+  format: ScanFormat | 'unknown';
+  /** Bounding box of the code in the camera preview (CSS px), when the platform reports it. */
+  bounds?: { x: number; y: number; width: number; height: number };
+}
+
+/** Scan resolved without a code because the user dismissed the scanner. */
+export interface ScanCancelled {
+  cancelled: true;
+}
+
+export interface ScanOptions {
+  /** Symbology filter — a single format or a list. Omit / `'all'` = any supported code. */
+  formats?: ScanFormat | ScanFormat[];
+  /** Which camera to open. Default `'back'`. */
+  camera?: 'back' | 'front';
+}
+
+/** True when a {@link ScanResult.value} is present (not the cancelled shape). */
+export function isScanResult(r: ScanResult | ScanCancelled): r is ScanResult {
+  return (r as ScanCancelled).cancelled !== true;
+}
+
+/**
+ * Camera barcode / QR decoding — ONE API across platforms.
+ *
+ * {@link scan} opens a native full-screen capture UI, returns the FIRST decoded code, then
+ * auto-dismisses. If the user dismisses it first, it resolves to `{ cancelled: true }` (NOT a
+ * rejection) — branch with {@link isScanResult}. {@link cancel} dismisses an in-progress scan
+ * programmatically, which makes that same pending {@link scan} resolve `{ cancelled: true }`.
+ *
+ * Native (iOS `AVCaptureMetadataOutput`, Android ZXing capture Activity) reports
+ * `capability === 'native'`. Web maps to the `BarcodeDetector` API where present (Chrome/Android
+ * → `'web'`); where absent (Safari/Firefox today) it's `'none'` and {@link scan} throws
+ * `KitError('UNSUPPORTED')` — no heavy JS decoder fallback. Branch on {@link capability}.
+ */
+export class ScannerModule {
+  constructor(private kit: NativeKit) {}
+
+  /** 'native' on a shell · 'web' where BarcodeDetector exists · else 'none'. */
+  get capability() {
+    return this.kit.capability('scanner');
+  }
+
+  /** Open the scanner; resolve the first code, or `{ cancelled: true }` if dismissed. */
+  scan(opts: ScanOptions = {}): Promise<ScanResult | ScanCancelled> {
+    return this.kit.invoke('scanner.scan', opts);
+  }
+
+  /** Dismiss an in-progress {@link scan} (its promise then resolves `{ cancelled: true }`). */
+  cancel(): Promise<void> {
+    return this.kit.invoke('scanner.cancel');
+  }
+}