@livx.cc/native-kit 0.31.0 → 0.31.1

package/package.json

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

package/src/core/web-adapter.ts

@@ -1,3 +1,4 @@
+/// <reference path="../web-experimental.d.ts" />
 import { Capability, Handshake, KitError, NativeKitAdapter, Unsubscribe } from './types';
 
 /** Decode raw base64 → an ArrayBuffer for File construction (no `data:` prefix expected). */
@@ -17,7 +18,7 @@ function bufferToBase64(buf: ArrayBuffer): string {
 }
 
 /** Map our lock vocabulary to valid ScreenOrientation `OrientationLockType` values. */
-function toWebOrientation(o: string): any {
+function toWebOrientation(o: string): string {
   switch (o) {
     case 'portrait-upside-down': return 'portrait-secondary';
     case 'landscape-left': return 'landscape-primary';
@@ -26,6 +27,20 @@ function toWebOrientation(o: string): any {
   }
 }
 
+/** Options accepted by `speech.speak` (a subset of the wire params, all optional). */
+interface SpeakOptions {
+  lang?: string;
+  rate?: number;
+  pitch?: number;
+  voice?: string;
+}
+
+/** Options accepted by `speech.listen`. */
+interface ListenOptions {
+  lang?: string;
+  partial?: boolean;
+}
+
 /**
  * Browser fallback adapter. Fulfills what the Web Platform can, reports honest
  * capability flags for the rest. Methods for unsupported capabilities resolve
@@ -34,7 +49,7 @@ function toWebOrientation(o: string): any {
 export class WebAdapter implements NativeKitAdapter {
   readonly kind = 'web' as const;
   private toastEl: HTMLElement | null = null;
-  private wakeLock: any = null;
+  private wakeLock: WakeLockSentinel | null = null;
   private listeners = new Map<string, Set<(payload: unknown) => void>>();
   private geoWatchId: number | null = null;
   private motionHandler: ((e: DeviceMotionEvent) => void) | null = null;
@@ -48,29 +63,29 @@ export class WebAdapter implements NativeKitAdapter {
   }
 
   async handshake(): Promise<Handshake> {
-    const n = navigator as any;
+    const n = navigator;
     const caps: Record<string, Capability> = {
       haptics: 'vibrate' in navigator ? 'web' : 'none',
       share: 'share' in navigator ? 'web' : 'none',
       shareFiles: typeof n.canShare === 'function' ? 'web' : 'none', // navigator.canShare({files}) gates at call time
-      orientation: (screen as any)?.orientation ? 'web' : 'none', // Screen Orientation API (lock needs fullscreen)
+      orientation: screen?.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',
+      fs: typeof n.storage?.getDirectory === 'function' || typeof document !== 'undefined' ? 'web' : 'none',
       toast: 'web',
       statusBar: 'none',
       device: 'web',
       clipboard: navigator.clipboard ? 'web' : 'none',
       notifications: 'Notification' in window ? 'web' : 'none',
-      badge: typeof (navigator as any).setAppBadge === 'function' ? 'web' : 'none', // Badging API (PWA icon badge)
+      badge: typeof navigator.setAppBadge === 'function' ? 'web' : 'none', // Badging API (PWA icon badge)
       biometrics: 'none',
       geo: 'geolocation' in navigator ? 'web' : 'none',
       photos: 'web',
       network: 'web',
       screen: 'wakeLock' in n ? 'web' : 'none',
-      keyboard: (window as any).visualViewport ? 'web' : 'none', // VisualViewport resize ≈ keyboard show/hide
+      keyboard: window.visualViewport ? 'web' : 'none', // VisualViewport resize ≈ keyboard show/hide
       dialogs: 'web',
       reviews: 'none',
       themeColor: 'web', // the browser honors <meta name="theme-color"> itself
@@ -78,14 +93,14 @@ export class WebAdapter implements NativeKitAdapter {
       contacts: n.contacts?.select ? 'web' : 'none',
       calendar: 'none',
       camera: 'web', // <input capture> — mobile browsers open the camera
-      media: (navigator as any).mediaDevices?.getUserMedia ? 'web' : 'none',
+      media: typeof navigator.mediaDevices?.getUserMedia === 'function' ? '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',
+      scanner: typeof window.BarcodeDetector !== 'undefined' && typeof navigator.mediaDevices?.getUserMedia === 'function' ? 'web' : 'none',
       // TTS: SpeechSynthesis API (broad support). STT: SpeechRecognition (Chrome/webkit only).
-      speech: typeof (window as any).speechSynthesis !== 'undefined' ? 'web' : 'none',
+      speech: typeof window.speechSynthesis !== 'undefined' ? 'web' : 'none',
       speechRecognition:
-        typeof (window as any).SpeechRecognition !== 'undefined' ||
-        typeof (window as any).webkitSpeechRecognition !== 'undefined'
+        typeof window.SpeechRecognition !== 'undefined' ||
+        typeof window.webkitSpeechRecognition !== 'undefined'
           ? 'web'
           : 'none',
       app: 'web', // openUrl via window.open; openSettings/canOpenUrl unsupported
@@ -111,6 +126,8 @@ export class WebAdapter implements NativeKitAdapter {
   }
 
   async invoke<T>(method: string, params?: unknown): Promise<T> {
+    // no type: untyped JSON-wire param bag dispatched dynamically — fields flow into ~50 typed sinks
+    // (String()/Notification/etc.); `unknown` would force a cast at every read for zero real safety.
     const p = (params ?? {}) as Record<string, any>;
     switch (method) {
       case 'haptics.impact':
@@ -170,7 +187,7 @@ export class WebAdapter implements NativeKitAdapter {
       case 'ui.brightness.set':
         throw new KitError('UNSUPPORTED', 'No brightness control on web');
       case 'ui.keepAwake': {
-        const wl = (navigator as any).wakeLock;
+        const wl = navigator.wakeLock;
         if (!wl) throw new KitError('UNSUPPORTED', 'Wake Lock API unavailable');
         if (p.on) this.wakeLock = await wl.request('screen');
         else { await this.wakeLock?.release(); this.wakeLock = null; }
@@ -197,7 +214,7 @@ export class WebAdapter implements NativeKitAdapter {
       }
 
       case 'screen.orientation.lock': {
-        const so = (screen as any)?.orientation;
+        const so = screen?.orientation;
         if (!so?.lock) throw new KitError('UNSUPPORTED', 'Screen orientation lock unavailable');
         // Most browsers require fullscreen before locking; surface the real reason.
         await so.lock(toWebOrientation(String(p.orientation))).catch((e: Error) => {
@@ -206,10 +223,10 @@ export class WebAdapter implements NativeKitAdapter {
         return undefined as T;
       }
       case 'screen.orientation.unlock':
-        (screen as any)?.orientation?.unlock?.();
+        screen?.orientation?.unlock?.();
         return undefined as T;
       case 'screen.orientation.current':
-        return (((screen as any)?.orientation?.type ?? '').startsWith('landscape') ? 'landscape' : 'portrait') as T;
+        return ((screen?.orientation?.type ?? '').startsWith('landscape') ? 'landscape' : 'portrait') as T;
 
       case 'keyboard.hide':
         // No programmatic IME on web — blurring the focused field dismisses it.
@@ -220,7 +237,7 @@ export class WebAdapter implements NativeKitAdapter {
         throw new KitError('UNSUPPORTED', 'No in-app review prompt on web');
 
       case 'device.info': {
-        const battery = await (navigator as any).getBattery?.().catch(() => null);
+        const battery = await navigator.getBattery?.().catch(() => null);
         return {
           model: navigator.userAgent.replace(/^Mozilla\/\d+\.\d+\s*/, '').slice(0, 64),
           os: 'web',
@@ -252,7 +269,7 @@ export class WebAdapter implements NativeKitAdapter {
       case 'notifications.pending':
         return 0 as T; // web timers aren't introspectable
       case 'notifications.setBadge': {
-        const setAppBadge = (navigator as any).setAppBadge?.bind(navigator);
+        const setAppBadge = navigator.setAppBadge?.bind(navigator);
         if (!setAppBadge) throw new KitError('UNSUPPORTED', 'Badging API unavailable');
         await setAppBadge(p.count);
         return undefined as T;
@@ -293,7 +310,7 @@ export class WebAdapter implements NativeKitAdapter {
       case 'motion.start': {
         if (typeof DeviceMotionEvent === 'undefined') throw new KitError('UNSUPPORTED', 'No motion sensors on this browser');
         // iOS Safari gates motion behind an explicit permission prompt
-        const req = (DeviceMotionEvent as any).requestPermission;
+        const req = (DeviceMotionEvent as unknown as DeviceMotionEventWithPermission).requestPermission;
         if (req) {
           const state = await req().catch((e: Error) => { throw new KitError('DENIED', e.message); });
           if (state !== 'granted') throw new KitError('DENIED', 'Motion permission not granted');
@@ -323,9 +340,9 @@ export class WebAdapter implements NativeKitAdapter {
         return undefined as T;
 
       case 'contacts.pick': {
-        const select = (navigator as any).contacts?.select;
+        const select = navigator.contacts?.select;
         if (!select) throw new KitError('UNSUPPORTED', 'Contact Picker API unavailable');
-        const picked = await (navigator as any).contacts
+        const picked = await navigator.contacts!
           .select(['name', 'tel', 'email'])
           .catch((e: Error) => { throw new KitError('DENIED', e.message); });
         const c = picked?.[0];
@@ -348,7 +365,7 @@ export class WebAdapter implements NativeKitAdapter {
       case 'speech.speak':
         return this.speak(String(p.text ?? ''), p) as Promise<T>;
       case 'speech.stop':
-        (window as any).speechSynthesis?.cancel?.();
+        window.speechSynthesis?.cancel?.();
         return undefined as T;
       case 'speech.voices':
         return this.listVoices() as Promise<T>;
@@ -387,7 +404,7 @@ export class WebAdapter implements NativeKitAdapter {
         return undefined as T; // browser owns the audio session — nothing to tune
 
       case 'network.status': {
-        const conn = (navigator as any).connection;
+        const conn = navigator.connection;
         return { online: navigator.onLine, type: conn?.type ?? (navigator.onLine ? 'unknown' : 'none') } as T;
       }
 
@@ -454,14 +471,14 @@ export class WebAdapter implements NativeKitAdapter {
       };
     }
     if (event === 'screen.orientation.change') {
-      const so = (screen as any)?.orientation;
+      const so = screen?.orientation;
       if (!so) return () => {};
       const fire = () => cb(String(so.type ?? '').startsWith('landscape') ? 'landscape' : 'portrait');
       so.addEventListener('change', fire);
       return () => so.removeEventListener('change', fire);
     }
     if (event === 'keyboard.show' || event === 'keyboard.hide') {
-      const vv = (window as any).visualViewport;
+      const vv = window.visualViewport;
       if (!vv) return () => {};
       let shown = false;
       const onResize = () => {
@@ -521,9 +538,9 @@ export class WebAdapter implements NativeKitAdapter {
   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);
+  ): Promise<{ value: string; format: string; bounds?: { x: number; y: number; width: number; height: number } } | { cancelled: true }> {
+    const Detector = window.BarcodeDetector;
+    const getUserMedia = navigator.mediaDevices?.getUserMedia?.bind(navigator.mediaDevices);
     if (!Detector || !getUserMedia) throw new KitError('UNSUPPORTED', 'BarcodeDetector / camera unavailable in this browser');
 
     return new Promise(async (resolve, reject) => {
@@ -552,7 +569,7 @@ export class WebAdapter implements NativeKitAdapter {
         video.setAttribute('playsinline', '');
         video.muted = true;
         video.style.cssText = 'flex:1;width:100%;height:100%;object-fit:cover';
-        (video as any).srcObject = stream;
+        video.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';
@@ -581,9 +598,11 @@ export class WebAdapter implements NativeKitAdapter {
           raf = requestAnimationFrame(tick);
         };
         raf = requestAnimationFrame(tick);
-      } catch (e: any) {
+      } catch (e: unknown) {
         teardown();
-        reject(new KitError(e?.name === 'NotAllowedError' ? 'DENIED' : 'NATIVE_ERROR', e?.message ?? 'scan failed'));
+        const name = e instanceof Error ? e.name : '';
+        const message = e instanceof Error ? e.message : 'scan failed';
+        reject(new KitError(name === 'NotAllowedError' ? 'DENIED' : 'NATIVE_ERROR', message));
       }
     });
   }
@@ -591,29 +610,29 @@ export class WebAdapter implements NativeKitAdapter {
   // ── speech (Web Speech API) ─────────────────────────────────────────
 
   /** Speak via SpeechSynthesis; resolve when the utterance ends (or rejects on synth error). */
-  private speak(text: string, opts: Record<string, any>): Promise<void> {
-    const synth = (window as any).speechSynthesis;
+  private speak(text: string, opts: SpeakOptions): Promise<void> {
+    const synth = window.speechSynthesis;
     if (!synth) throw new KitError('UNSUPPORTED', 'SpeechSynthesis unavailable');
     return new Promise((resolve, reject) => {
-      const u = new (window as any).SpeechSynthesisUtterance(text);
+      const u = new window.SpeechSynthesisUtterance(text);
       if (opts.lang) u.lang = opts.lang;
       if (opts.rate != null) u.rate = opts.rate;
       if (opts.pitch != null) u.pitch = opts.pitch;
       if (opts.voice) {
-        const v = synth.getVoices().find((vc: any) => vc.voiceURI === opts.voice || vc.name === opts.voice);
+        const v = synth.getVoices().find((vc) => vc.voiceURI === opts.voice || vc.name === opts.voice);
         if (v) u.voice = v;
       }
       u.onend = () => resolve();
-      u.onerror = (e: any) => reject(new KitError('NATIVE_ERROR', e?.error ?? 'speech synthesis failed'));
+      u.onerror = (e: SpeechSynthesisErrorEvent) => reject(new KitError('NATIVE_ERROR', e?.error ?? 'speech synthesis failed'));
       synth.speak(u);
     });
   }
 
   /** List synthesizer voices, awaiting the async `voiceschanged` event when the list is empty. */
   private listVoices(): Promise<Array<{ id: string; name: string; lang: string }>> {
-    const synth = (window as any).speechSynthesis;
+    const synth = window.speechSynthesis;
     if (!synth) throw new KitError('UNSUPPORTED', 'SpeechSynthesis unavailable');
-    const map = (vs: any[]) => vs.map((v) => ({ id: v.voiceURI ?? v.name, name: v.name, lang: v.lang }));
+    const map = (vs: SpeechSynthesisVoice[]) => vs.map((v) => ({ id: v.voiceURI ?? v.name, name: v.name, lang: v.lang }));
     const ready = synth.getVoices();
     if (ready.length) return Promise.resolve(map(ready));
     // Chrome populates voices asynchronously — wait once for voiceschanged, with a short fallback.
@@ -630,8 +649,8 @@ export class WebAdapter implements NativeKitAdapter {
   }
 
   /** Capture the mic via SpeechRecognition; resolve the FINAL transcript, stream partials. */
-  private listen(opts: Record<string, any>): Promise<string> {
-    const Rec = (window as any).SpeechRecognition || (window as any).webkitSpeechRecognition;
+  private listen(opts: ListenOptions): Promise<string> {
+    const Rec = window.SpeechRecognition || window.webkitSpeechRecognition;
     if (!Rec) throw new KitError('UNSUPPORTED', 'SpeechRecognition unavailable (Chrome only)');
     return new Promise((resolve, reject) => {
       const rec = new Rec();
@@ -648,7 +667,7 @@ export class WebAdapter implements NativeKitAdapter {
       };
       const stop = () => { try { rec.stop(); } catch { /* already stopped */ } };
       this.listenStop = stop;
-      rec.onresult = (e: any) => {
+      rec.onresult = (e) => {
         let interim = '';
         let finalText = '';
         for (let i = 0; i < e.results.length; i++) {
@@ -659,7 +678,7 @@ export class WebAdapter implements NativeKitAdapter {
         best = (finalText || interim).trim();
         if (opts.partial && interim) this.emit('speech.partial', { transcript: interim.trim() });
       };
-      rec.onerror = (e: any) => {
+      rec.onerror = (e) => {
         if (settled) return;
         settled = true;
         if (this.listenStop === stop) this.listenStop = null;
@@ -713,10 +732,10 @@ export class WebAdapter implements NativeKitAdapter {
   // 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;
+  private async opfsRoot(): Promise<FileSystemDirectoryHandle> {
+    const dir = navigator.storage?.getDirectory;
     if (!dir) throw new KitError('UNSUPPORTED', 'No OPFS in this browser');
-    return (navigator as any).storage.getDirectory();
+    return navigator.storage.getDirectory();
   }
 
   /** Split a path into clean segments, rejecting any `..` so it can't escape the OPFS root. */
@@ -727,7 +746,7 @@ export class WebAdapter implements NativeKitAdapter {
   }
 
   /** 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 }> {
+  private async opfsResolveParent(path: string, create: boolean): Promise<{ parent: FileSystemDirectoryHandle; name: string }> {
     const parts = this.opfsSegments(path);
     const name = parts.pop();
     if (!name) throw new KitError('NATIVE_ERROR', 'Empty path');
@@ -764,7 +783,7 @@ export class WebAdapter implements NativeKitAdapter {
     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()) {
+    for await (const [name, handle] of dir.entries()) {
       out.push({ name, type: handle.kind === 'directory' ? 'dir' : 'file' });
     }
     return out;

package/src/modules/billing/http.ts

@@ -14,8 +14,8 @@ export interface HttpJsonOptions {
 }
 
 /** POST/GET JSON, throwing on non-2xx. Keeps validators + providers DRY. */
-export async function httpJson(opts: HttpJsonOptions): Promise<any> {
-  const f = opts.fetch ?? (globalThis as any).fetch;
+export async function httpJson(opts: HttpJsonOptions): Promise<unknown> {
+  const f = opts.fetch ?? globalThis.fetch;
   if (!f) throw new Error('billing: no fetch available — pass one via options.fetch');
   const h = typeof opts.headers === 'function' ? await opts.headers() : opts.headers;
   const res = await f(opts.url, {

package/src/modules/billing/providers.ts

@@ -13,8 +13,10 @@ export class HttpBillingProviderOptions {
   redirect: (url: string) => void = (url) => {
     if (typeof window !== 'undefined') window.location.assign(url);
   };
-  mapProducts: (json: any) => Product[] = (j) => (j?.products ?? j ?? []) as Product[];
-  mapEntitlements: (json: any) => Entitlement[] = (j) => (j?.entitlements ?? j ?? []) as Entitlement[];
+  mapProducts: (json: unknown) => Product[] = (j) =>
+    ((j as { products?: Product[] } | null)?.products ?? (j as Product[] | null) ?? []);
+  mapEntitlements: (json: unknown) => Entitlement[] = (j) =>
+    ((j as { entitlements?: Entitlement[] } | null)?.entitlements ?? (j as Entitlement[] | null) ?? []);
 }
 
 /**
@@ -39,8 +41,9 @@ export class HttpBillingProvider implements BillingProvider {
 
   async purchase(productId: string): Promise<Entitlement[]> {
     const json = await httpJson({ ...this.req(), url: `${this.base()}/checkout`, method: 'POST', body: { productId } });
-    if (json?.url) {
-      this.options.redirect(String(json.url)); // hosted checkout — page navigates away
+    const url = (json as { url?: unknown } | null)?.url;
+    if (url) {
+      this.options.redirect(String(url)); // hosted checkout — page navigates away
       return []; // entitlements arrive via entitlements() after redirect-back
     }
     return this.options.mapEntitlements(json); // backend completed inline
@@ -56,7 +59,8 @@ export class HttpBillingProvider implements BillingProvider {
 
   async manageSubscriptions(): Promise<void> {
     const json = await httpJson({ ...this.req(), url: `${this.base()}/portal`, method: 'POST', body: {} });
-    if (json?.url) this.options.redirect(String(json.url)); // Stripe Billing Portal, etc.
+    const url = (json as { url?: unknown } | null)?.url;
+    if (url) this.options.redirect(String(url)); // Stripe Billing Portal, etc.
   }
 
   private base() {

package/src/modules/billing/validators.ts

@@ -32,7 +32,8 @@ export class HttpValidatorOptions {
   /** Static headers or a thunk (e.g. to inject a fresh bearer token). */
   headers?: HeaderProvider;
   /** Map the provider's response JSON → `Entitlement[]`. Default expects `{ entitlements: [...] }`. */
-  mapResponse: (json: any) => Entitlement[] = (j) => (j?.entitlements ?? []) as Entitlement[];
+  mapResponse: (json: unknown) => Entitlement[] = (j) =>
+    ((j as { entitlements?: Entitlement[] } | null)?.entitlements ?? []);
   /** Injected for tests / non-DOM runtimes. Defaults to global `fetch`. */
   fetch?: typeof fetch;
 }

package/src/modules/updates.ts

@@ -156,7 +156,7 @@ export class UpdatesModule {
  * `<meta name="app-version">` tag. '' (unknown) when neither is present — in which case we never
  * raise a false update prompt. */
 function bootVersion(): string {
-  const g = typeof window !== 'undefined' ? (window as any).__APP_VERSION__ : undefined;
+  const g = typeof window !== 'undefined' ? (window as { __APP_VERSION__?: string }).__APP_VERSION__ : undefined;
   if (g) return String(g);
   if (typeof document !== 'undefined') {
     const meta = document.querySelector('meta[name="app-version"]');

package/src/web-experimental.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Ambient augmentations for the non-standard / experimental Web APIs the WebAdapter
+ * feature-detects. These are NOT in the current TS DOM lib, so without these decls
+ * each touch would need an `as any` cast. Shapes are intentionally MINIMAL — only the
+ * members web-adapter.ts actually reads — but REAL (no `any`), so call sites stay typed.
+ *
+ * Anything the DOM lib already types (setAppBadge/clearAppBadge, speechSynthesis,
+ * SpeechSynthesisUtterance, visualViewport, mediaDevices, wakeLock, ScreenOrientation
+ * core, storage.getDirectory, HTMLVideoElement.playsInline/srcObject) is deliberately
+ * absent here and used straight off the lib types.
+ */
+
+export {};
+
+/** A picked contact from the Contact Picker API (navigator.contacts.select). */
+interface WebContact {
+  name?: string[];
+  tel?: string[];
+  email?: string[];
+}
+
+/** A detected code from the Barcode Detection API. */
+interface DetectedBarcode {
+  rawValue: string;
+  format: string;
+  boundingBox?: { x: number; y: number; width: number; height: number };
+}
+
+/** Minimal BarcodeDetector surface (Chrome/Android). */
+interface BarcodeDetectorLike {
+  detect(source: CanvasImageSource): Promise<DetectedBarcode[]>;
+}
+interface BarcodeDetectorCtor {
+  new (options?: { formats?: string[] }): BarcodeDetectorLike;
+}
+
+/** Minimal Web Speech `SpeechRecognition` surface (Chrome/webkit). */
+interface SpeechRecognitionLike {
+  lang: string;
+  interimResults: boolean;
+  continuous: boolean;
+  onresult: ((event: { results: ArrayLike<ArrayLike<{ transcript: string }> & { isFinal: boolean }> }) => void) | null;
+  onerror: ((event: { error?: string }) => void) | null;
+  onend: (() => void) | null;
+  start(): void;
+  stop(): void;
+}
+interface SpeechRecognitionCtor {
+  new (): SpeechRecognitionLike;
+}
+
+declare global {
+  interface Navigator {
+    /** Battery Status API — resolves a snapshot the adapter reads `level`/`charging` off. */
+    getBattery?(): Promise<{ level: number; charging: boolean }>;
+    /** Contact Picker API. */
+    contacts?: {
+      select(properties: string[], options?: { multiple?: boolean }): Promise<WebContact[]>;
+    };
+    /** Network Information API (non-standard `connection`). */
+    connection?: { type?: string };
+  }
+
+  interface Window {
+    BarcodeDetector?: BarcodeDetectorCtor;
+    SpeechRecognition?: SpeechRecognitionCtor;
+    webkitSpeechRecognition?: SpeechRecognitionCtor;
+  }
+
+  /** Screen Orientation lock/unlock — newer than the lib's ScreenOrientation interface. */
+  interface ScreenOrientation {
+    lock?(orientation: string): Promise<void>;
+    unlock?(): void;
+  }
+
+  /** OPFS directory async iterator — newer than the lib's FileSystemDirectoryHandle interface. */
+  interface FileSystemDirectoryHandle {
+    entries(): AsyncIterableIterator<[string, FileSystemHandle]>;
+  }
+
+  /** iOS Safari gates DeviceMotion behind an explicit permission prompt (static method) — the lib
+   * already declares `DeviceMotionEvent` as a `var`, so this can't merge onto it; web-adapter casts
+   * the constructor to this shape at the single call site instead. */
+  interface DeviceMotionEventWithPermission {
+    requestPermission?(): Promise<'granted' | 'denied' | 'prompt'>;
+  }
+}