@livx.cc/native-kit 0.28.0 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.28.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/NativeKit.ts

@@ -2,6 +2,7 @@ import { AppwrapAdapter } from './appwrap-adapter';
 import { WebAdapter } from './web-adapter';
 import { Capability, Handshake, InvokeOptions, KIT_PROTOCOL, KitError, NativeKitAdapter, Platform, Unsubscribe } from './types';
 import { AppModule } from '../modules/app';
+import { BackgroundTaskModule } from '../modules/backgroundTask';
 import { BillingModule } from '../modules/billing/billing';
 import { BiometricsModule } from '../modules/biometrics';
 import { BrowserModule } from '../modules/browser';
@@ -101,6 +102,7 @@ export class NativeKit {
   public readonly oauth = new OAuthModule(this);
   public readonly billing = new BillingModule(this);
   public readonly updates = new UpdatesModule(this);
+  public readonly backgroundTask = new BackgroundTaskModule(this);
 
   public handshakeInfo: Handshake | null = null;
   public options: NativeKitOptions;
@@ -133,6 +135,9 @@ export class NativeKit {
         this.handshakeInfo = handshake;
         // Zero-config: a native server-loader app begins polling for remote updates.
         this.updates.__autostart();
+        // A background launch carries the wake id in the handshake → dispatch the registered handler
+        // (the app's boot register() may have already run, or land moments later — both dispatch).
+        this.backgroundTask.__onReady(handshake.backgroundTaskId);
         return this.handshakeInfo;
       })();
     }

package/src/core/types.ts

@@ -24,6 +24,11 @@ export interface Handshake {
   platform: Platform;
   app: AppInfo;
   capabilities: Record<string, Capability>;
+  /** Set ONLY on a background launch: the OS woke the app (possibly cold, headless, no visible
+   * WebView) to run this registered background-task id. The shell populates it; `kit.backgroundTask`
+   * reads it from {@link NativeKit.handshakeInfo} and dispatches the registered handler. Absent on a
+   * normal foreground launch. See {@link BackgroundTaskModule}. */
+  backgroundTaskId?: string;
   /** Optional diagnostic payload (breadcrumbs, etc.). */
   debug?: Record<string, unknown>;
 }

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,20 +93,25 @@ 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 unsupported
+      app: 'web', // openUrl via window.open; openSettings/canOpenUrl unsupported
+      shortcuts: 'none', // no home-screen quick actions for a PWA
+      privacyScreen: 'none', // a browser can't hide content in the app-switcher or block screenshots
       browser: 'web', // new tab/window
       billing: 'none', // no IAP in a plain browser — wire a web checkout yourself
       push: 'none', // remote push (APNs/FCM) is native-only — web push (VAPID) is the app's own concern
+      // headless background execution is native-only — a PWA's Background/Periodic Sync lives in a
+      // service worker the kit doesn't own → honest 'none' (schedule/cancel resolve as no-ops).
+      backgroundTask: 'none',
     };
     return {
       protocol: 1,
@@ -106,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':
@@ -165,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; }
@@ -192,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) => {
@@ -201,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.
@@ -215,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',
@@ -247,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;
@@ -288,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');
@@ -318,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];
@@ -343,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>;
@@ -382,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;
       }
 
@@ -395,6 +417,14 @@ export class WebAdapter implements NativeKitAdapter {
       case 'app.openSettings':
         throw new KitError('UNSUPPORTED', 'No app settings page on web');
 
+      case 'app.canOpenUrl':
+        // A PWA can't probe installed apps — be honest rather than guess from the scheme.
+        return false as T;
+      case 'app.setShortcuts':
+        return undefined as T; // no home-screen quick actions in a browser — no-op (cap reported 'none')
+      case 'screen.setPrivacy':
+        return undefined as T; // a browser can't hide content in the app-switcher — no-op (cap 'none')
+
       case 'app.environment':
         // On web there's no install — report the honest 'web' source. is_emulator is native-only.
         return { source: 'web', isEmulator: false } as T;
@@ -417,9 +447,14 @@ export class WebAdapter implements NativeKitAdapter {
       case 'push.requestPermission':
       case 'push.register':
       case 'push.unregister':
-      case 'push.sendTest':
         throw new KitError('UNSUPPORTED', 'No native remote push on web — use Web Push (VAPID) in your app, or run inside the appwrap shell');
 
+      case 'backgroundTask.schedule':
+      case 'backgroundTask.cancel':
+        // Honest no-op: a browser has no OS-scheduled headless wake the kit owns (that's a service
+        // worker's Background/Periodic Sync). Resolve so callers don't have to branch on platform.
+        return undefined as T;
+
       default:
         throw new KitError('UNSUPPORTED', `Unknown method: ${method}`);
     }
@@ -436,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 = () => {
@@ -503,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) => {
@@ -534,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';
@@ -563,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));
       }
     });
   }
@@ -573,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.
@@ -612,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();
@@ -630,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++) {
@@ -641,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;
@@ -695,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. */
@@ -709,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');
@@ -746,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/index.ts

@@ -1,6 +1,6 @@
 export { NativeKit, NativeKitOptions, kit } from './core/NativeKit';
 export type { KitContext } from './core/NativeKit';
-export type { AppEnvironment, InstallSource } from './modules/app';
+export type { AppEnvironment, AppShortcut, InstallSource } from './modules/app';
 export { AppwrapAdapter } from './core/appwrap-adapter';
 export { WebAdapter } from './core/web-adapter';
 export { KitError } from './core/types';
@@ -45,6 +45,8 @@ export { ClientTrustedValidator, HttpValidator, HttpValidatorOptions } from './m
 export { HttpBillingProvider, HttpBillingProviderOptions } from './modules/billing/providers';
 export type { HeaderProvider } from './modules/billing/http';
 export { HealthModule } from './modules/health';
+export { BackgroundTaskModule } from './modules/backgroundTask';
+export type { BackgroundTaskHandler, ScheduleBackgroundTaskOptions } from './modules/backgroundTask';
 export type {
   BillingProvider,
   BillingValidator,

package/src/modules/app.ts

@@ -1,4 +1,13 @@
 import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+/** A home-screen long-press quick action. `id` is echoed back to {@link AppModule.onShortcut} when
+ *  the user activates it; keep it stable so your router can map it. Custom icons are v1-omitted. */
+export interface AppShortcut {
+  id: string;
+  title: string;
+  subtitle?: string;
+}
 
 /** Where this build was installed from. Drives beta-vs-prod analytics cohorts.
  *  - `appstore` / `playstore` — public store install
@@ -57,8 +66,49 @@ export class AppModule {
     return this.kit.invoke('app.openUrl', { url });
   }
 
+  /**
+   * Probe whether the OS can open `url` — i.e. some installed app (or the OS) handles its scheme.
+   * Use it to hide a "Open in <App>" button when the target app isn't installed.
+   *
+   * Common schemes (http/https/tel/mailto/sms) resolve without any declaration. To probe a CUSTOM
+   * scheme (e.g. `whatsapp://`) it MUST be declared up-front, else the OS reports false for privacy:
+   *  - Custom scheme, BOTH platforms — list the scheme in `appwrap.json.queryUrlSchemes`. It stamps iOS
+   *    Info.plist `LSApplicationQueriesSchemes` AND Android `<queries>` (a VIEW `<intent>` per scheme),
+   *    so a scheme probe works identically on iOS and Android with one declaration.
+   *  - Android explicit package (optional) — to probe a specific package directly, list it in
+   *    `appwrap.json.queryPackages` (→ AndroidManifest `<queries><package>`). Android-only.
+   * Web is always `false` — a PWA can't probe installed apps (honest).
+   */
+  canOpenUrl(url: string): Promise<boolean> {
+    return this.kit.invoke('app.canOpenUrl', { url });
+  }
+
   /** Open this app's page in the OS Settings app (to toggle permissions, etc.). */
   openSettings(): Promise<void> {
     return this.kit.invoke('app.openSettings');
   }
+
+  /** 'native' where the OS exposes home-screen quick actions (iOS 3D-Touch/long-press shortcut items;
+   *  Android 7.1+ app shortcuts) · else 'none'. Branch on this, not try/catch. */
+  get shortcutsCapability() {
+    return this.kit.capability('shortcuts');
+  }
+
+  /**
+   * Set the app's home-screen long-press quick actions (replaces any previously set). Pass `[]` to
+   * clear. iOS assigns `UIApplication.shortcutItems`; Android sets dynamic shortcuts (API 25+, no-op
+   * below); web is a no-op. Activation is delivered via {@link onShortcut}. Custom icons are v1-omitted.
+   */
+  setShortcuts(items: AppShortcut[]): Promise<void> {
+    return this.kit.invoke('app.setShortcuts', { items });
+  }
+
+  /**
+   * Fire when the user activates a home-screen shortcut, with its `id`. Like deep links, a shortcut
+   * that COLD-LAUNCHED the app is buffered natively until the handshake, so a listener registered at
+   * startup still receives it.
+   */
+  onShortcut(cb: (id: string) => void): Unsubscribe {
+    return this.kit.on('app.shortcut', (p) => cb((p as { id: string }).id));
+  }
 }

package/src/modules/backgroundTask.ts

@@ -0,0 +1,122 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/**
+ * A headless background-task handler. Runs (possibly cold, with no visible WebView) when the OS wakes
+ * the app for `ctx.id`. `ctx.signal` aborts when the OS budget is nearly spent (~25s, below the iOS
+ * ~30s ceiling) or the OS calls the expiration handler — observe it for any long await and bail
+ * promptly, or the OS may kill the app and refuse future wakes. Resolve when done; a rejection is
+ * reported to the OS as a failed run (it still reschedules).
+ */
+export type BackgroundTaskHandler = (ctx: { id: string; signal: AbortSignal }) => Promise<void>;
+
+/** Constraints for {@link BackgroundTaskModule.schedule}. The OS treats these as HINTS — actual wake
+ * timing is the OS's call (it batches by power/network/usage), so a wake is opportunistic, not a timer. */
+export interface ScheduleBackgroundTaskOptions {
+  /** Task id — must be one of `appwrap.json.backgroundTasks` (iOS requires identifiers declared at
+   * build time). The same id is matched against the wake handshake + the registered handler. */
+  id: string;
+  /** Earliest the OS should consider waking again (a floor, not a guarantee). iOS clamps app-refresh
+   * to its own minimum; Android `WorkManager` periodic work has a 15-min platform minimum. */
+  minIntervalMs?: number;
+  /** Only run when the network is reachable (iOS `BGProcessingTaskRequest.requiresNetworkConnectivity`
+   * / Android `NetworkType.CONNECTED`). */
+  requiresNetwork?: boolean;
+  /** Only run while charging (iOS `BGProcessingTaskRequest.requiresExternalPower` / Android
+   * `setRequiresCharging`). */
+  requiresCharging?: boolean;
+}
+
+/** Wall-clock guard below the iOS ~30s background budget. The kit aborts the signal at this point so a
+ * handler that ignores the OS expiration still releases the task before the OS force-kills the app. */
+const SAFETY_TIMEOUT_MS = 25_000;
+
+/**
+ * Headless background execution with a JS-handler contract — ONE API across platforms.
+ *
+ * Flow: at EVERY launch the app calls {@link register} (idempotent) for each task id. When the OS woke
+ * the app for a task, the handshake carries that id ({@link import('../core/types').Handshake.backgroundTaskId});
+ * the kit invokes the matching handler with an {@link AbortSignal}, arms a {@link SAFETY_TIMEOUT_MS}
+ * abort, and on resolve/reject/timeout calls `backgroundTask.finish` so the shell completes the OS
+ * task + reschedules (BGTask is one-shot — it MUST resubmit). Registration may land before OR after
+ * {@link NativeKit.ready} resolves; both orderings dispatch (a pending wake is replayed to a late
+ * registration, and an early registration is dispatched the moment ready resolves with a wake id).
+ *
+ * Native (iOS `BGTaskScheduler` + an offscreen `WKWebView`, Android `WorkManager` + a headless
+ * `WebView`) reports `capability === 'native'`. Web is honestly `'none'`: a PWA's background-sync
+ * lives in a service worker the kit doesn't own — {@link schedule}/{@link cancel} resolve as no-ops
+ * and {@link register} records nothing.
+ */
+export class BackgroundTaskModule {
+  private handlers = new Map<string, BackgroundTaskHandler>();
+  /** A wake id seen before its handler was registered — replayed on the late {@link register}. */
+  private pendingWakeId: string | null = null;
+  /** Ids already dispatched this session — guards against a double-fire (replay + ready both matching). */
+  private dispatched = new Set<string>();
+
+  constructor(private kit: NativeKit) {}
+
+  /** Called by {@link NativeKit.ready} once the handshake resolves (never triggers the handshake
+   * itself — same lazy contract as the rest of the kit). A background launch carries the wake id in
+   * the handshake: if its handler already registered (early) → dispatch now; else remember it for the
+   * late {@link register}. @internal */
+  __onReady(backgroundTaskId?: string): void {
+    if (!backgroundTaskId) return;
+    if (this.handlers.has(backgroundTaskId)) this.dispatch(backgroundTaskId);
+    else this.pendingWakeId = backgroundTaskId;
+  }
+
+  /** 'native' on a shell · 'none' on web (PWA background-sync is the app's service-worker concern). */
+  get capability() {
+    return this.kit.capability('backgroundTask');
+  }
+
+  /**
+   * Record the handler for `id`. Call at boot on EVERY launch (idempotent — re-registering replaces).
+   * If the app was woken for this id (the handshake carried it), the handler dispatches immediately,
+   * whether the wake was already known (ready resolved first) or arrives later.
+   */
+  register(id: string, handler: BackgroundTaskHandler): void {
+    this.handlers.set(id, handler);
+    if (this.pendingWakeId === id) {
+      this.pendingWakeId = null;
+      this.dispatch(id);
+    }
+  }
+
+  /** Ask the OS to (re)schedule a wake for `id`. No-op resolve on web. */
+  schedule(opts: ScheduleBackgroundTaskOptions): Promise<void> {
+    return this.kit.invoke<void>('backgroundTask.schedule', opts);
+  }
+
+  /** Cancel a scheduled task. No-op resolve on web. */
+  cancel(id: string): Promise<void> {
+    return this.kit.invoke<void>('backgroundTask.cancel', { id });
+  }
+
+  /** Run the registered handler under an abort-guarded budget, then report completion to the shell so
+   * it finishes the OS task + reschedules. Idempotent per id per session. */
+  private async dispatch(id: string): Promise<void> {
+    if (this.dispatched.has(id)) return;
+    this.dispatched.add(id);
+    const handler = this.handlers.get(id);
+    if (!handler) return;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SAFETY_TIMEOUT_MS);
+    let success = true;
+    try {
+      await handler({ id, signal: controller.signal });
+    } catch (e) {
+      success = false;
+      console.warn('[native-kit] backgroundTask handler rejected', id, e);
+    } finally {
+      clearTimeout(timer);
+      // Tell the shell to complete the OS task + resubmit the next request. The handler's own work is
+      // done; a finish-report failure must not mask it, so swallow (logged) — the OS budget is spent
+      // either way.
+      await this.kit
+        .invoke<void>('backgroundTask.finish', { id, success })
+        .catch((e) => console.warn('[native-kit] backgroundTask.finish failed', id, e));
+    }
+  }
+}

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/push.ts

@@ -65,13 +65,6 @@ export class PushModule {
     return this.kit.invoke('push.unregister');
   }
 
-  /** Dev/demo: ask your backend (via `push.registrationUrl`) to push THIS device on demand. The shell
-   *  POSTs the token natively (no WebView CORS) with `test:true`. Resolves `{ status }` (the backend's
-   *  HTTP code). Requires a configured registrationUrl + a registered token. */
-  sendTest(): Promise<{ status: number }> {
-    return this.kit.invoke('push.sendTest', undefined, { timeoutMs: 20_000 });
-  }
-
   /** Foreground message delivery (app open, no tap). */
   onMessage(cb: (m: PushMessage) => void): Unsubscribe {
     return this.kit.on('push.message', (p) => cb(p as PushMessage));

package/src/modules/screen.ts

@@ -11,13 +11,29 @@ export type OrientationLock =
   | 'landscape-right'
   | 'any';
 
-/** Screen-level controls. Today: orientation; brightness/keepAwake live on `kit.ui`. */
+/** Screen-level controls. Today: orientation + privacy screen; brightness/keepAwake live on `kit.ui`. */
 export class ScreenModule {
   readonly orientation: OrientationController;
 
-  constructor(kit: NativeKit) {
+  constructor(private kit: NativeKit) {
     this.orientation = new OrientationController(kit);
   }
+
+  /** 'native' on a shell · else 'none' — the browser can't hide content in the app-switcher or block
+   *  screenshots. Branch on this, not try/catch. */
+  get privacyCapability() {
+    return this.kit.capability('privacyScreen');
+  }
+
+  /**
+   * Privacy screen — hide app content in the app-switcher / on backgrounding and block screenshots.
+   * `true` enables, `false` disables (the state persists across background/foreground until changed).
+   * iOS covers the window with a blur while inactive/backgrounded; Android sets `FLAG_SECURE` (which
+   * also blocks screenshots and screen recording — expected). Web is an honest no-op.
+   */
+  setPrivacy(enabled: boolean): Promise<void> {
+    return this.kit.invoke('screen.setPrivacy', { enabled });
+  }
 }
 
 /**

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'>;
+  }
+}