@livx.cc/appwrap 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",

package/runtime/app/shell/capabilities.manifest.ts

@@ -135,23 +135,69 @@ export const MODULES: ModuleManifest[] = [
     ] },
     android: { permissions: ['android.permission.READ_CALENDAR', 'android.permission.WRITE_CALENDAR'] },
   },
-  {
-    name: 'reviews', group: 'system',
-    capabilities: { reviews: { ios: true, android: false } },
-  },
   {
     name: 'billing', group: 'billing',
     capabilities: { billing: { ios: true, android: false } },
   },
 
-  // ── oauth — system-browser OAuth (iOS ASWebAuthenticationSession) ──
-  // Opt-in, strippable (own handler file). No permissions/entitlements — ASWebAuthenticationSession
-  // needs none; it only relies on the app's urlScheme so the provider redirect returns to the app.
+  // ── reviews — in-app store review prompt — opt-in, STRIPPABLE (own handler + group) ──
+  // Moved out of the always-bundled parity/system handlers: the Android Play In-App Review path
+  // references `com.google.android.play:review` classes — a gradle dep that must NOT land in builds
+  // without `reviews` (missing-class crash / dead weight). iOS: SKStoreReviewController (no dep).
+  // HONEST LIMIT (Android): the dialog only surfaces for a Play-Store-track install; on a bare
+  // emulator / sideload the API resolves WITHOUT showing UI (documented; same class as billing).
+  {
+    name: 'reviews', group: 'reviews',
+    capabilities: { reviews: { ios: true, android: true } },
+    android: { gradleDeps: ['com.google.android.play:review:2.0.2'] },
+  },
+
+  // ── oauth — system-browser OAuth (iOS ASWebAuthenticationSession / Android Chrome Custom Tabs) ──
+  // Opt-in, strippable (own handler file). iOS: ASWebAuthenticationSession (auto-closes on redirect).
+  // Android: a Chrome Custom Tab — it does NOT auto-close on the provider redirect, so the callback
+  // (`callbackScheme://…`) returns via the app's EXISTING urlScheme deep-link path; the handler hooks
+  // that delivery, matches the scheme, and resolves. androidx.browser is already a baseline dep
+  // (browser.open); declared here too so the module stays self-contained (CLI dedups). No permission.
   // Lets Google et al. complete sign-in they reject inside an embedded WebView (disallowed_useragent).
-  // Android (Custom Tabs + intent callback) is a future addition.
   {
     name: 'oauth', group: 'oauth',
-    capabilities: { oauth: { ios: true, android: false } },
+    capabilities: { oauth: { ios: true, android: true } },
+    android: { gradleDeps: ['androidx.browser:browser:1.8.0'] },
+  },
+
+  // ── scanner — camera barcode/QR decode — opt-in (camera permission + decoder weight) ──
+  // Reuses the SAME camera permission as media/camera (the CLI dedups across active modules), so a
+  // scanner-only app still gets NSCameraUsageDescription / CAMERA without a second permission.
+  // iOS: AVCaptureMetadataOutput (no extra dep). Android: ZXing-android-embedded — it ships its own
+  // capture Activity, so the handler just launches it via startActivityForResult and reads the
+  // result (fewest moving parts vs ML Kit, which needs a hand-built Camera2/CameraX preview).
+  {
+    name: 'scanner', group: 'scanner',
+    capabilities: { scanner: 'native' },
+    ios: { permissions: [{ key: 'NSCameraUsageDescription', domain: 'camera', defaultUsage: 'Scan barcodes and QR codes with the camera.' }] },
+    android: {
+      permissions: ['android.permission.CAMERA'],
+      gradleDeps: ['com.journeyapps:zxing-android-embedded:4.3.0'],
+    },
+  },
+
+  // ── speech (TTS + STT) — opt-in module; ONE coherent kit.speech, TWO honest capabilities ──
+  // ONE module (not split TTS-core / STT-opt-in): TTS-only apps are rare and a split fractures
+  // `kit.speech` across tiers. The module declares the STT perms (mic + speech-recognition); the
+  // CLI only stamps them when `speech` is active, and TTS (`speak`/`voices`) rides along perm-free.
+  // It advertises TWO handshake caps so the kit gates each concern honestly:
+  //   `speech`            → TTS (synthesis), always native on a shell.
+  //   `speechRecognition` → STT (transcription), always native on a shell.
+  // iOS: AVSpeechSynthesizer (TTS, no dep) + SFSpeechRecognizer/AVAudioEngine (STT). Android:
+  // TextToSpeech + SpeechRecognizer — both plain Java → NO kotlin flag, NO gradle dep.
+  {
+    name: 'speech', group: 'speech',
+    capabilities: { speech: 'native', speechRecognition: 'native' },
+    ios: { permissions: [
+      { key: 'NSSpeechRecognitionUsageDescription', domain: 'speechRecognition', defaultUsage: 'Transcribe your speech to text.' },
+      { key: 'NSMicrophoneUsageDescription', domain: 'microphone', defaultUsage: 'Listen to your voice for speech-to-text.' },
+    ] },
+    android: { permissions: ['android.permission.RECORD_AUDIO'] },
   },
 
   // ── health (steps) — opt-in heavy module; FG live + BG via OS step store ──
@@ -204,7 +250,7 @@ export const MODULES: ModuleManifest[] = [
 
 /** Opt-in registration groups that own their own NS handler file (strippable when inactive). Core
  * groups (core/extended/parity/system/media/billing) are always bundled; only these are CLI-gated. */
-export const OPTIONAL_GROUPS = ['health', 'oauth'] as const;
+export const OPTIONAL_GROUPS = ['health', 'oauth', 'reviews', 'scanner', 'speech'] as const;
 
 /** Resolve the active capability map for the handshake from a set of active capability names. */
 export function buildCapabilityMap(

package/runtime/app/shell/config.ts

@@ -50,4 +50,8 @@ export const SHELL_CONFIG = {
    * un-provisioned build honestly reports 'none' (and a personal-team iOS build keeps `pushIos:false`). */
   pushIos: false,
   pushAndroid: false,
+  /** Optional backend URL that the shell POSTs the device token to NATIVELY as soon as it's acquired —
+   * `{ token, platform: 'ios'|'android' }`. Native HTTP avoids the WKWebView `app://` cross-origin/CORS
+   * wall, so a token reaches your server without any WebView fetch. Empty = the app handles sending. */
+  pushRegistrationUrl: '',
 };

package/runtime/app/shell/events.ts

@@ -10,8 +10,19 @@ let pendingPushTap: { data: Record<string, string> } | null = null;
 // (the cold-start-from-notification bug). So we gate delivery on the handshake.
 let pwaReady = false;
 
+/** A pending native-side consumer of an inbound deep link (e.g. the Android OAuth flow waiting for
+ * the provider's `callbackScheme://…` redirect). Returns true if it CONSUMED the URL — then it's an
+ * internal callback, not an app deep link, and must NOT reach the PWA. Set by handlers-oauth. */
+let deepLinkInterceptor: ((url: string) => boolean) | null = null;
+export function setDeepLinkInterceptor(fn: ((url: string) => boolean) | null): void {
+  deepLinkInterceptor = fn;
+}
+
 /** Called by the iOS delegate (cold start or while running) and Android intents. */
 export function onDeepLink(url: string): void {
+  // Give a native consumer (OAuth callback) first refusal — a matched OAuth redirect is internal
+  // plumbing, not an app deep link, so it's swallowed here and never forwarded to the PWA.
+  if (deepLinkInterceptor?.(url)) return;
   if (pwaReady) bridge.emit('deeplink.open', { url });
   else pendingDeepLink = url; // buffer until the PWA handshakes
 }

package/runtime/app/shell/handlers-extended.ts

@@ -127,7 +127,10 @@ export function registerExtendedHandlers(): void {
       Utils.dispatchToMainThread(() => {
         UNUserNotificationCenter.currentNotificationCenter().setBadgeCountWithCompletionHandler?.(
           count,
-          () => {}
+          // iOS silently ignores the badge unless notification authorization (incl. .badge) was granted —
+          // the completion's error is the ONLY signal, so DON'T swallow it (else the badge just never
+          // appears with no explanation). Resolve regardless (the JS call itself didn't fail).
+          (error: any) => { if (error) console.warn('[appwrap] setBadge ignored — notifications not authorized?', String(error)); }
         );
         resolve();
       });

package/runtime/app/shell/handlers-fs.ts

@@ -57,13 +57,17 @@ function registerIosFs(): void {
     if (!fm().fileExistsAtPath(full)) throw err('NATIVE_ERROR', `No such file: ${path}`);
     const data = NSData.dataWithContentsOfFile(full);
     if (!data) throw err('NATIVE_ERROR', `Read failed: ${path}`);
-    if (encoding === 'base64') return data.base64EncodedStringWithOptions(0 as unknown as NSDataBase64EncodingOptions);
-    return NSString.alloc().initWithDataEncoding(data, 4 /* NSUTF8StringEncoding */) as unknown as string;
+    // String(...) FORCES a JS string. Without it the NSString proxy goes over the bridge and
+    // JSON-serializes to `{}` — `as unknown as string` is a compile-time no-op, not a conversion.
+    if (encoding === 'base64') return String(data.base64EncodedStringWithOptions(0 as unknown as NSDataBase64EncodingOptions));
+    return String(NSString.alloc().initWithDataEncoding(data, 4 /* NSUTF8StringEncoding */));
   });
 
-  bridge.register('fs.write', ({ path, data, dir = 'data', encoding = 'utf8', recursive }: any) => {
+  bridge.register('fs.write', ({ path, data, dir = 'data', encoding = 'utf8' }: any) => {
     const full = iosResolve(path, dir);
-    if (recursive) ensureParentIos(full);
+    // Always create the parent dir — writing to a sub-path (e.g. 'demo/note.txt') otherwise fails
+    // ("Write failed"), which is a footgun. fs.append already does this; match it.
+    ensureParentIos(full);
     const blob = encoding === 'base64'
       ? NSData.alloc().initWithBase64EncodedStringOptions(data, 0 as unknown as NSDataBase64DecodingOptions)
       : (NSString.stringWithString(String(data ?? '')) as any).dataUsingEncoding(4);
@@ -245,9 +249,10 @@ function registerAndroidFs(): void {
     return new java.lang.String(bytes, 'UTF-8').toString();
   });
 
-  bridge.register('fs.write', ({ path, data, dir = 'data', encoding = 'utf8', recursive }: any) => {
+  bridge.register('fs.write', ({ path, data, dir = 'data', encoding = 'utf8' }: any) => {
     const file = androidFile(path, dir);
-    if (recursive) file.getParentFile()?.mkdirs();
+    // Always create the parent dir (match fs.append + iOS) — writing to a sub-path otherwise fails.
+    file.getParentFile()?.mkdirs();
     writeAndroid(file, data, encoding, false);
     return { uri: android.net.Uri.fromFile(file).toString() };
   });

package/runtime/app/shell/handlers-oauth.ts

@@ -1,9 +1,11 @@
-import { Utils, isIOS } from '@nativescript/core';
+import { Application, Utils, isAndroid, isIOS } from '@nativescript/core';
 import { bridge } from './bridge';
+import { setDeepLinkInterceptor } from './events';
 
 // AuthenticationServices globals (NS auto-links the framework via metadata when referenced).
 declare const ASWebAuthenticationSession: any;
 declare const ASWebAuthenticationPresentationContextProviding: any;
+declare const android: any, androidx: any;
 
 const err = (code: string, message: string) => Object.assign(new Error(message), { code });
 
@@ -19,6 +21,7 @@ let activeProvider: any = null;
  * the auth URL + does token exchange; this only opens the browser and hands back the callback.
  */
 export function registerOAuthHandlers(): void {
+  if (isAndroid) { registerAndroid(); return; }
   if (!isIOS) return;
 
   bridge.register(
@@ -67,3 +70,89 @@ export function registerOAuthHandlers(): void {
       })
   );
 }
+
+/**
+ * Android: launch the auth URL in a Chrome Custom Tab. Unlike iOS ASWebAuthenticationSession, a
+ * Custom Tab does NOT auto-close on the provider redirect — the redirect to `callbackScheme://…`
+ * re-launches our (singleTask) activity as a VIEW intent, which the shell's existing deep-link path
+ * (events.wireAndroidDeepLinks → onDeepLink) already surfaces. We register a deep-link interceptor
+ * that matches the pending callbackScheme, swallows that URL (it's OAuth plumbing, not an app deep
+ * link), and resolves the pending authorize() with the same { url } shape the iOS path returns.
+ *
+ * Cancel contract (matches iOS user-dismiss → CANCELLED): Custom Tabs gives no dismissal callback, so
+ * we infer cancellation on app.resume — if the app comes back to the foreground after the tab opened
+ * and NO matching redirect arrived within a short grace window, the user backed out → reject CANCELLED.
+ *
+ * DEVICE-UNVERIFIED (any-typed FFI, no device run this session): the CustomTabsIntent launch + the
+ * redirect→deep-link round-trip + the resume-based cancel inference. Compile-clean only.
+ */
+function registerAndroid(): void {
+  // Single in-flight authorize at a time (mirrors the iOS single-session model).
+  let pending:
+    | { scheme: string; resolve: (v: any) => void; reject: (e: any) => void; settled: boolean; resumeOff: () => void }
+    | null = null;
+
+  const finish = (fn: () => void) => {
+    if (!pending || pending.settled) return;
+    pending.settled = true;
+    pending.resumeOff();
+    const p = pending;
+    pending = null;
+    fn.call(p);
+  };
+
+  // First refusal on every inbound deep link: consume the one that matches the pending callbackScheme.
+  setDeepLinkInterceptor((url: string): boolean => {
+    if (!pending || pending.settled) return false;
+    const scheme = pending.scheme;
+    if (!scheme || !String(url ?? '').toLowerCase().startsWith(scheme.toLowerCase() + ':')) return false;
+    finish(function (this: any) { this.resolve({ url: String(url) }); });
+    return true; // swallow — internal OAuth callback, not an app deep link
+  });
+
+  bridge.register(
+    'oauth.authorize',
+    ({ url, callbackScheme, ephemeral }: { url: string; callbackScheme: string; ephemeral?: boolean }) =>
+      new Promise((resolve, reject) => {
+        const target = String(url ?? '');
+        const scheme = String(callbackScheme ?? '');
+        if (!target) { reject(err('NATIVE_ERROR', 'oauth.authorize: empty url')); return; }
+        if (!scheme) { reject(err('NATIVE_ERROR', 'oauth.authorize: empty callbackScheme')); return; }
+        if (pending && !pending.settled) { reject(err('NATIVE_ERROR', 'oauth.authorize: a flow is already in progress')); return; }
+
+        Utils.dispatchToMainThread(() => {
+          try {
+            const activity = Application.android.foregroundActivity ?? Application.android.startActivity;
+            if (!activity) { reject(err('NATIVE_ERROR', 'oauth.authorize: no foreground activity')); return; }
+
+            // Cancel inference: the tab launch will background us; the FIRST resume afterwards means
+            // the user is back in our app. If no redirect consumed the flow by then (+grace), it's a
+            // user-cancel. A small delay lets a redirect that arrives in the same resume win the race.
+            let launched = false;
+            const onResume = () => {
+              if (!launched || !pending || pending.settled) return;
+              setTimeout(() => finish(function (this: any) { this.reject(err('CANCELLED', 'oauth cancelled')); }), 400);
+            };
+            Application.on(Application.resumeEvent, onResume);
+            const resumeOff = () => Application.off(Application.resumeEvent, onResume);
+            pending = { scheme, resolve, reject, settled: false, resumeOff };
+
+            const builder = new androidx.browser.customtabs.CustomTabsIntent.Builder();
+            // `ephemeral` (fresh login) → don't share the persisted browser session. Custom Tabs has
+            // no per-launch incognito API; the closest honest knob is disabling the recents/share
+            // surface so the auth page isn't trivially resumable. Cookie isolation isn't guaranteed.
+            if (ephemeral) builder.setShareState(androidx.browser.customtabs.CustomTabsIntent.SHARE_STATE_OFF);
+            const tabs = builder.build();
+            // No extra intent flags: the `callbackScheme://…` redirect re-launches our singleTask
+            // activity to the front (consumed by the deep-link interceptor), leaving the tab behind it.
+            tabs.launchUrl(activity, android.net.Uri.parse(target));
+            launched = true;
+          } catch (e: any) {
+            const fail = err('NATIVE_ERROR', e?.message ?? 'oauth failed to start');
+            if (pending && !pending.settled) finish(function (this: any) { this.reject(fail); });
+            else reject(fail); // failed before `pending` was wired
+          }
+        });
+      })
+  );
+}

package/runtime/app/shell/handlers-parity.ts

@@ -6,7 +6,7 @@ const err = (code: string, message: string) => Object.assign(new Error(message),
 const iosOnly = () => err('UNSUPPORTED', 'iOS only for now');
 
 /**
- * Extended-parity handlers: dialogs, reviews, storage.clear, geo watch, theme color,
+ * Extended-parity handlers: dialogs, storage.clear, geo watch, theme color,
  * motion, contacts, calendar, camera. iOS-first like handlers-extended.
  */
 export function registerParityHandlers(): void {
@@ -31,18 +31,8 @@ export function registerParityHandlers(): void {
     return idx >= 0 ? idx : null;
   });
 
-  // ── reviews (SKStoreReviewController) ──────────────────────────────
-  bridge.register('reviews.requestReview', () => {
-    if (!isIOS) throw iosOnly();
-    Utils.dispatchToMainThread(() => {
-      const scene = UIApplication.sharedApplication.keyWindow?.windowScene;
-      if (scene && SKStoreReviewController.requestReviewInWindowScene) {
-        SKStoreReviewController.requestReviewInWindowScene(scene);
-      } else {
-        SKStoreReviewController.requestReview();
-      }
-    });
-  });
+  // reviews → moved to the strippable `reviews` module (handlers-reviews.ts): its Android Play
+  // In-App Review path carries a gradle dep that must not bundle into builds without `reviews`.
 
   // ── storage.clear ──────────────────────────────────────────────────
   bridge.register('storage.clear', () => {

package/runtime/app/shell/handlers-push.ts

@@ -1,4 +1,4 @@
-import { Application, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { Application, Http, Utils, isAndroid, isIOS } from '@nativescript/core';
 import { bridge } from './bridge';
 import { SHELL_CONFIG } from './config';
 
@@ -21,9 +21,32 @@ let cachedToken: string | null = null;
 
 interface PushToken { platform: 'apns' | 'fcm'; token: string; }
 
+/** POST the device token to the app's configured backend NATIVELY (no WKWebView fetch → no app://
+ * cross-origin/CORS wall). The backend stores it + sends pushes. No-op when no URL is configured. */
+function registerTokenWithBackend(platform: 'ios' | 'android', token: string): void {
+  const url = SHELL_CONFIG.pushRegistrationUrl;
+  if (!url) return;
+  // NativeScript Http (NOT the global fetch — unreliable in the NS runtime). Native HTTP, no CORS.
+  // Guarded: never let a backend-register hiccup break token resolution (this runs before resolve()).
+  try {
+    Http.request({
+      url, method: 'POST', headers: { 'Content-Type': 'application/json' },
+      content: JSON.stringify({ token, platform }),
+    })
+      .then((res) => console.log('[push] token registered with backend → ' + res.statusCode))
+      .catch((e: any) => console.log('[push] backend register failed: ' + (e?.message ?? e)));
+  } catch (e: any) {
+    console.log('[push] backend register threw: ' + (e?.message ?? e));
+  }
+}
+
 /** iOS AppDelegate → APNs device token arrived. Resolve any pending register() + cache. */
 export function onApnsToken(hexToken: string): void {
   cachedToken = hexToken;
+  // Log the FULL token so it's readable headlessly (`appwrap logs ios`) to send a test push —
+  // mirrors the Android FCM boot-log. The token alone isn't a secret (you still need the APNs key).
+  console.log('[push] APNs token: ' + hexToken);
+  registerTokenWithBackend('ios', hexToken);
   if (pendingRegister) {
     pendingRegister.resolve({ platform: 'apns', token: hexToken });
     pendingRegister = null;

package/runtime/app/shell/handlers-reviews.ts

@@ -0,0 +1,73 @@
+import { Application, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+
+// SKStoreReviewController is declared globally in ios-frameworks.d.ts. `com` is the Android namespace.
+declare const com: any;
+
+/**
+ * In-app store review prompt — opt-in, strippable (its own handler file + group). Lives apart from
+ * the always-bundled parity/system handlers because the Android path references the Play In-App
+ * Review classes (`com.google.android.play:review`), a gradle dep that must NOT land in builds that
+ * don't enable `reviews` (missing-class crash / dead weight otherwise).
+ *
+ * iOS: SKStoreReviewController — the OS rate-limits display (may show nothing). Fire-and-forget.
+ * Android: Play In-App Review (ReviewManager). HONEST LIMIT — the dialog only actually surfaces for a
+ * Play-Store-track install; on a bare emulator / sideload the API resolves WITHOUT showing UI (same
+ * class as android-billing). We call the API and resolve gracefully; we never fabricate "shown".
+ *
+ * DEVICE-UNVERIFIED (any-typed FFI, no device run this session): the Android ReviewManager
+ * requestReviewFlow → launchReviewFlow task/listener chain. Compile-clean only.
+ */
+export function registerReviewsHandlers(): void {
+  if (isIOS) registerIos();
+  else if (isAndroid) registerAndroid();
+}
+
+function registerIos(): void {
+  bridge.register('reviews.requestReview', () => {
+    Utils.dispatchToMainThread(() => {
+      const scene = UIApplication.sharedApplication.keyWindow?.windowScene;
+      if (scene && SKStoreReviewController.requestReviewInWindowScene) {
+        SKStoreReviewController.requestReviewInWindowScene(scene);
+      } else {
+        SKStoreReviewController.requestReview();
+      }
+    });
+  });
+}
+
+function registerAndroid(): void {
+  bridge.register('reviews.requestReview', () =>
+    new Promise<void>((resolve) => {
+      Utils.dispatchToMainThread(() => {
+        try {
+          const activity = Application.android.foregroundActivity ?? Application.android.startActivity;
+          if (!activity) { resolve(); return; }
+          const manager = com.google.android.play.core.review.ReviewManagerFactory.create(activity);
+          const request = manager.requestReviewFlow();
+          // requestReviewFlow() → Task<ReviewInfo>; on success launchReviewFlow() → Task<Void>.
+          // Both tasks COMPLETE even when the OS shows nothing (no Play track / rate-limited), so we
+          // resolve on completion regardless — never block, never fabricate a "shown" signal.
+          request.addOnCompleteListener(new com.google.android.gms.tasks.OnCompleteListener({
+            onComplete(infoTask: any) {
+              if (!infoTask.isSuccessful()) { resolve(); return; }
+              try {
+                const flow = manager.launchReviewFlow(activity, infoTask.getResult());
+                flow.addOnCompleteListener(new com.google.android.gms.tasks.OnCompleteListener({
+                  onComplete() { resolve(); },
+                }));
+              } catch (e) {
+                console.warn('AppWrap: reviews.launchReviewFlow failed', e);
+                resolve();
+              }
+            },
+          }));
+        } catch (e) {
+          // Play services / review lib absent (e.g. non-GMS device) → honest no-op, don't reject.
+          console.warn('AppWrap: reviews.requestReview unavailable', e);
+          resolve();
+        }
+      });
+    })
+  );
+}

package/runtime/app/shell/handlers-scanner.ts

@@ -0,0 +1,222 @@
+import { Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+import { requestPermissions, startActivityForResult } from './android-helpers';
+
+// AVFoundation / UIKit globals (NS auto-links the frameworks via metadata when referenced).
+declare const AVCaptureSession: any;
+declare const AVCaptureDevice: any;
+declare const AVCaptureDeviceInput: any;
+declare const AVCaptureMetadataOutput: any;
+declare const AVCaptureVideoPreviewLayer: any;
+declare const AVMetadataObjectTypeQRCode: any;
+declare const AVMetadataObjectTypeEAN13Code: any;
+declare const AVMetadataObjectTypeCode128Code: any;
+declare const AVLayerVideoGravityResizeAspectFill: any;
+declare const AVCaptureDevicePositionFront: any;
+declare const AVCaptureDevicePositionBack: any;
+declare const AVCaptureDeviceDiscoverySession: any;
+declare const AVMediaTypeVideo: any;
+declare const AVCaptureDeviceTypeBuiltInWideAngleCamera: any;
+declare const AVCaptureMetadataOutputObjectsDelegate: any;
+// `dispatch_get_main_queue()` is a C macro, NOT a bridged symbol — NativeScript can't see it
+// ("is not defined" at runtime). `dispatch_queue_create` IS a real bridged libdispatch function;
+// a dedicated serial queue is the correct delegate queue for AVCaptureMetadataOutput anyway.
+declare function dispatch_queue_create(label: string, attr: any): any;
+declare const android: any, com: any;
+
+const err = (code: string, message: string) => Object.assign(new Error(message), { code });
+
+/**
+ * Camera barcode / QR decoding. iOS: AVCaptureMetadataOutput in a full-screen capture VC presented
+ * over the WebView; first machine-readable code → stop session, dismiss, resolve. Android: ZXing's
+ * own capture Activity (zxing-android-embedded) launched via startActivityForResult.
+ *
+ * Contract: `scanner.scan` resolves `{ value, format, bounds? }` on first decode, or
+ * `{ cancelled: true }` if the user dismisses (or `scanner.cancel` fires). It never rejects on a
+ * plain cancel — only on a hard failure (no camera, permission denied at the OS level).
+ */
+export function registerScannerHandlers(): void {
+  if (isIOS) registerIos();
+  else if (isAndroid) registerAndroid();
+}
+
+/** Map our small enum → the platform metadata-object types. Empty/`all` = the full supported set. */
+function iosFormatTypes(formats: any): any[] {
+  const all = [AVMetadataObjectTypeQRCode, AVMetadataObjectTypeEAN13Code, AVMetadataObjectTypeCode128Code];
+  const want = Array.isArray(formats) ? formats : formats ? [formats] : [];
+  const sel = want.filter((f: string) => f && f !== 'all');
+  if (!sel.length) return all;
+  const map: Record<string, any> = {
+    qr: AVMetadataObjectTypeQRCode,
+    ean13: AVMetadataObjectTypeEAN13Code,
+    code128: AVMetadataObjectTypeCode128Code,
+  };
+  return sel.map((f: string) => map[f]).filter(Boolean);
+}
+
+function iosFormatName(type: any): string {
+  if (type === AVMetadataObjectTypeQRCode) return 'qr';
+  if (type === AVMetadataObjectTypeEAN13Code) return 'ean13';
+  if (type === AVMetadataObjectTypeCode128Code) return 'code128';
+  return 'unknown';
+}
+
+function registerIos(): void {
+  // Strong refs while the scanner is up — ARC would otherwise free the session/VC/delegate the moment
+  // the JS locals fall out of scope, killing capture mid-stream (same hazard as handlers-oauth).
+  let activeSession: any = null;
+  let activeVC: any = null;
+  let activeDelegate: any = null;
+  let pending: { resolve: (v: any) => void } | null = null;
+
+  const dismiss = () => {
+    Utils.dispatchToMainThread(() => {
+      try { activeSession?.stopRunning(); } catch { /* already stopped */ }
+      activeVC?.dismissViewControllerAnimatedCompletion(true, null);
+      activeSession = null;
+      activeVC = null;
+      activeDelegate = null;
+    });
+  };
+
+  const settle = (value: any) => {
+    const p = pending;
+    pending = null;
+    dismiss();
+    // The metadata delegate now fires on a background serial queue; the bridge reply drives
+    // WKWebView.evaluateJavaScript, which must run on the main thread — so hop back to resolve.
+    Utils.dispatchToMainThread(() => p?.resolve(value));
+  };
+
+  bridge.register('scanner.cancel', () => { if (pending) settle({ cancelled: true }); });
+
+  bridge.register('scanner.scan', (params: any) =>
+    new Promise((resolve, reject) => {
+      if (pending) { reject(err('NATIVE_ERROR', 'scanner.scan: a scan is already in progress')); return; }
+      pending = { resolve };
+
+      Utils.dispatchToMainThread(() => {
+        try {
+          const wantFront = params?.camera === 'front';
+          const position = wantFront ? AVCaptureDevicePositionFront : AVCaptureDevicePositionBack;
+          const discovery = AVCaptureDeviceDiscoverySession.discoverySessionWithDeviceTypesMediaTypePosition(
+            [AVCaptureDeviceTypeBuiltInWideAngleCamera], AVMediaTypeVideo, position
+          );
+          const device = discovery?.devices?.firstObject ?? AVCaptureDevice.defaultDeviceWithMediaType(AVMediaTypeVideo);
+          if (!device) { pending = null; reject(err('UNSUPPORTED', 'No camera available')); return; }
+
+          const input = AVCaptureDeviceInput.deviceInputWithDeviceError(device, null);
+          if (!input) { pending = null; reject(err('NATIVE_ERROR', 'Cannot open camera input')); return; }
+
+          const session = AVCaptureSession.new();
+          if (!session.canAddInput(input)) { pending = null; reject(err('NATIVE_ERROR', 'Cannot add camera input')); return; }
+          session.addInput(input);
+
+          const output = AVCaptureMetadataOutput.new();
+          if (!session.canAddOutput(output)) { pending = null; reject(err('NATIVE_ERROR', 'Cannot add metadata output')); return; }
+          session.addOutput(output);
+
+          // Delegate fires on a dedicated serial queue (see dispatch_queue_create below); settle()
+          // hops back to the main thread for the WKWebView bridge reply.
+          const DelegateClass = (NSObject as any).extend(
+            {
+              captureOutputDidOutputMetadataObjectsFromConnection(_out: any, objects: any, _conn: any) {
+                if (!pending) return;
+                const obj = objects?.firstObject;
+                const value = obj?.stringValue;
+                if (value == null) return;
+                settle({ value: String(value), format: iosFormatName(obj.type) });
+              },
+            },
+            // The protocol MUST be declared: NativeScript uses it to map the camelCase JS method to the
+            // colonated selector `captureOutput:didOutputMetadataObjects:fromConnection:`. With an empty
+            // protocols list the method registers under the wrong selector and AVFoundation never calls
+            // it — the scanner opens but never decodes.
+            { protocols: [AVCaptureMetadataOutputObjectsDelegate] }
+          );
+          activeDelegate = DelegateClass.new();
+          output.setMetadataObjectsDelegateQueue(activeDelegate, dispatch_queue_create('cc.livx.scanner.metadata', null));
+          // metadataObjectTypes must be set AFTER addOutput (the available set is session-derived).
+          output.metadataObjectTypes = iosFormatTypes(params?.formats) as any;
+
+          const vc = UIViewController.new();
+          const preview = AVCaptureVideoPreviewLayer.layerWithSession(session);
+          preview.videoGravity = AVLayerVideoGravityResizeAspectFill;
+          preview.frame = vc.view.bounds;
+          vc.view.layer.addSublayer(preview);
+
+          // Cancel button so the user can dismiss without a successful read.
+          const btn = UIButton.buttonWithType(0 /* UIButtonTypeCustom */);
+          btn.setTitleForState('Cancel', 0 /* UIControlStateNormal */);
+          btn.frame = CGRectMake(16, 56, 100, 40);
+          const Target = (NSObject as any).extend(
+            { tap() { if (pending) settle({ cancelled: true }); } },
+            { exposedMethods: { tap: { returns: interop.types.void } } }
+          );
+          activeVC = vc;
+          (vc as any)._cancelTarget = Target.new(); // retain via the (also-retained) VC
+          btn.addTargetActionForControlEvents((vc as any)._cancelTarget, 'tap', 1 << 6 /* TouchUpInside */);
+          vc.view.addSubview(btn);
+
+          activeSession = session;
+          session.startRunning();
+
+          const root = Utils.ios.getRootViewController();
+          vc.modalPresentationStyle = 0; // fullScreen
+          root.presentViewControllerAnimatedCompletion(vc, true, null);
+        } catch (e: any) {
+          pending = null;
+          reject(err('NATIVE_ERROR', e?.message ?? 'scanner failed to start'));
+        }
+      });
+    })
+  );
+}
+
+function registerAndroid(): void {
+  // ZXing-android-embedded ships its own capture Activity (CaptureActivity). We build the launch
+  // Intent via IntentIntegrator, run it through startActivityForResult, and parse the result —
+  // no hand-built Camera2 preview. IntentResult carries the decoded text + format name.
+  const formatName = (zxingName: string): string => {
+    const n = String(zxingName ?? '').toUpperCase();
+    if (n === 'QR_CODE') return 'qr';
+    if (n === 'EAN_13') return 'ean13';
+    if (n === 'CODE_128') return 'code128';
+    return 'unknown';
+  };
+
+  bridge.register('scanner.cancel', () => {
+    // The ZXing capture Activity owns its own back/up dismissal; there's no in-process handle to it
+    // once launched. Cancel is honored by the user pressing back, which returns a null-contents result.
+  });
+
+  bridge.register('scanner.scan', async (params: any) => {
+    const granted = await requestPermissions(['android.permission.CAMERA']);
+    if (!granted) throw err('DENIED', 'Camera permission denied');
+
+    const activity = Utils.android.getCurrentActivity?.() ?? undefined;
+    const integrator = activity
+      ? new com.google.zxing.integration.android.IntentIntegrator(activity)
+      : new com.google.zxing.integration.android.IntentIntegrator(Utils.android.getApplicationContext());
+
+    // Restrict to our format set (or all). IntentIntegrator names match ZXing BarcodeFormat names.
+    const want = Array.isArray(params?.formats) ? params.formats : params?.formats ? [params.formats] : [];
+    const sel = want.filter((f: string) => f && f !== 'all');
+    if (sel.length) {
+      const map: Record<string, string> = { qr: 'QR_CODE', ean13: 'EAN_13', code128: 'CODE_128' };
+      const list = new java.util.ArrayList();
+      sel.forEach((f: string) => { const z = map[f]; if (z) list.add(z); });
+      if (list.size()) integrator.setDesiredBarcodeFormats(list);
+    }
+    integrator.setBeepEnabled(false);
+    integrator.setOrientationLocked(false);
+
+    const intent = integrator.createScanIntent();
+    const { resultCode, intent: data } = await startActivityForResult(intent);
+
+    const result = com.google.zxing.integration.android.IntentIntegrator.parseActivityResult(resultCode, data);
+    const contents = result?.getContents?.();
+    if (contents == null) return { cancelled: true }; // user backed out
+    return { value: String(contents), format: formatName(result.getFormatName?.()) };
+  });
+}

package/runtime/app/shell/handlers-speech.ts

@@ -0,0 +1,336 @@
+import { Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+import { requestPermissions } from './android-helpers';
+
+// AVFoundation / Speech globals (NS auto-links the frameworks via metadata when referenced).
+declare const AVSpeechSynthesizer: any;
+declare const AVSpeechUtterance: any;
+declare const AVSpeechSynthesisVoice: any;
+declare const AVAudioEngine: any;
+declare const AVAudioSession: any;
+declare const AVAudioSessionCategoryPlayAndRecord: any;
+declare const AVAudioSessionModeMeasurement: any;
+declare const SFSpeechRecognizer: any;
+declare const SFSpeechAudioBufferRecognitionRequest: any;
+declare const SFSpeechRecognizerAuthorizationStatusAuthorized: any;
+declare const NSLocale: any;
+declare const android: any;
+declare const java: any;
+
+const err = (code: string, message: string) => Object.assign(new Error(message), { code });
+
+/**
+ * Voice I/O. TTS: iOS AVSpeechSynthesizer / Android TextToSpeech — speak resolves on finish.
+ * STT: iOS SFSpeechRecognizer + AVAudioEngine mic tap / Android SpeechRecognizer — listen resolves
+ * the FINAL transcript; partials emit `speech.partial` while listening; stopListening resolves with
+ * the best-so-far transcript.
+ *
+ * DEVICE-UNVERIFIED (any-typed FFI, no device run this session): the iOS AVAudioEngine tap +
+ * SFSpeechRecognizer authorization/lifecycle, and the Android SpeechRecognizer onResults/
+ * onPartialResults threading + TextToSpeech init race. Compile-clean only.
+ */
+export function registerSpeechHandlers(): void {
+  if (isIOS) registerIos();
+  else if (isAndroid) registerAndroid();
+}
+
+function registerIos(): void {
+  // Strong refs while a session is live — ARC would otherwise free the synthesizer/engine/delegate
+  // the moment the JS locals fall out of scope (same hazard as handlers-scanner/oauth).
+  let synth: any = null;
+  let speakDelegate: any = null;
+  let speakPending: { resolve: () => void } | null = null;
+
+  let engine: any = null;
+  let recognizer: any = null;
+  let request: any = null;
+  let task: any = null;
+  let listenPending: { resolve: (v: string) => void; reject: (e: any) => void } | null = null;
+  let best = '';
+
+  const teardownListen = () => {
+    try { task?.cancel?.(); } catch { /* noop */ }
+    try { request?.endAudio?.(); } catch { /* noop */ }
+    try {
+      engine?.inputNode?.removeTapOnBus?.(0);
+      engine?.stop?.();
+    } catch { /* noop */ }
+    task = null; request = null; engine = null;
+  };
+
+  const settleListen = () => {
+    const p = listenPending;
+    listenPending = null;
+    teardownListen();
+    p?.resolve(best);
+  };
+
+  bridge.register('speech.speak', (params: any) =>
+    new Promise<void>((resolve, reject) => {
+      Utils.dispatchToMainThread(() => {
+        try {
+          if (!synth) {
+            synth = AVSpeechSynthesizer.new();
+            const DelegateClass = (NSObject as any).extend(
+              {
+                speechSynthesizerDidFinishSpeechUtterance(_s: any, _u: any) {
+                  const p = speakPending; speakPending = null; p?.resolve();
+                },
+                speechSynthesizerDidCancelSpeechUtterance(_s: any, _u: any) {
+                  const p = speakPending; speakPending = null; p?.resolve();
+                },
+              },
+              { protocols: [] }
+            );
+            speakDelegate = DelegateClass.new();
+            synth.delegate = speakDelegate;
+          }
+          // A new speak resolves any prior pending (its utterance is being superseded).
+          speakPending?.resolve();
+          const u = AVSpeechUtterance.speechUtteranceWithString(String(params?.text ?? ''));
+          if (params?.voice) {
+            const v = AVSpeechSynthesisVoice.voiceWithIdentifier(String(params.voice));
+            if (v) u.voice = v;
+          } else if (params?.lang) {
+            const v = AVSpeechSynthesisVoice.voiceWithLanguage(String(params.lang));
+            if (v) u.voice = v;
+          }
+          if (params?.rate != null) u.rate = Number(params.rate) * AVSpeechUtterance.alloc().rate; // relative scale
+          if (params?.pitch != null) u.pitchMultiplier = Number(params.pitch);
+          speakPending = { resolve };
+          synth.speakUtterance(u);
+        } catch (e: any) {
+          reject(err('NATIVE_ERROR', e?.message ?? 'speak failed'));
+        }
+      });
+    })
+  );
+
+  bridge.register('speech.stop', () => {
+    Utils.dispatchToMainThread(() => {
+      try { synth?.stopSpeakingAtBoundary?.(0 /* immediate */); } catch { /* noop */ }
+      const p = speakPending; speakPending = null; p?.resolve();
+    });
+  });
+
+  bridge.register('speech.voices', () => {
+    const voices = AVSpeechSynthesisVoice.speechVoices();
+    const out: Array<{ id: string; name: string; lang: string }> = [];
+    const n = voices?.count ?? 0;
+    for (let i = 0; i < n; i++) {
+      const v = voices.objectAtIndex(i);
+      out.push({ id: String(v.identifier), name: String(v.name), lang: String(v.language) });
+    }
+    return out;
+  });
+
+  bridge.register('speech.stopListening', () => {
+    // End audio → the recognizer flushes a final result, then we settle with best-so-far.
+    try { engine?.inputNode?.removeTapOnBus?.(0); engine?.stop?.(); request?.endAudio?.(); } catch { /* noop */ }
+    if (listenPending) settleListen();
+  });
+
+  bridge.register('speech.listen', (params: any) =>
+    new Promise<string>((resolve, reject) => {
+      if (listenPending) { reject(err('NATIVE_ERROR', 'speech.listen: already listening')); return; }
+      best = '';
+      listenPending = { resolve, reject };
+
+      SFSpeechRecognizer.requestAuthorization((status: any) => {
+        if (status !== SFSpeechRecognizerAuthorizationStatusAuthorized) {
+          const p = listenPending; listenPending = null;
+          p?.reject(err('DENIED', 'Speech recognition not authorized'));
+          return;
+        }
+        Utils.dispatchToMainThread(() => {
+          try {
+            // Pick a locale SFSpeechRecognizer has a model for: try the requested lang, the device
+            // language code, then en-US (always supported) as a last resort. Do NOT gate on
+            // `isAvailable` — it's unreliable SYNCHRONOUSLY right after init (becomes true async via
+            // the availabilityDidChange delegate), so checking it here wrongly rejects a good recognizer
+            // (proven on-device: en-US reported unavailable). Accept any non-nil recognizer; a genuine
+            // failure surfaces in the recognitionTask error callback instead.
+            const tryRec = (id: string) => {
+              try { return SFSpeechRecognizer.alloc().initWithLocale(NSLocale.localeWithLocaleIdentifier(id)) || null; }
+              catch { return null; }
+            };
+            let langCode = 'en';
+            try { langCode = String(NSLocale.currentLocale.languageCode || 'en'); } catch { /* default */ }
+            const tried = params?.lang ? [String(params.lang)] : [langCode, 'en-US'];
+            recognizer = null;
+            for (const id of tried) { recognizer = tryRec(id); if (recognizer) break; }
+            if (!recognizer) {
+              const p = listenPending; listenPending = null;
+              p?.reject(err('UNSUPPORTED', `Speech recognizer unavailable (tried: ${tried.join(', ')})`));
+              return;
+            }
+
+            const session = AVAudioSession.sharedInstance();
+            session.setCategoryModeOptionsError(AVAudioSessionCategoryPlayAndRecord, AVAudioSessionModeMeasurement, 1 /* duckOthers */, null);
+            session.setActiveWithOptionsError(true, 0, null);
+
+            engine = AVAudioEngine.new();
+            request = SFSpeechAudioBufferRecognitionRequest.new();
+            request.shouldReportPartialResults = !!params?.partial;
+
+            task = recognizer.recognitionTaskWithRequestResultHandler(request, (result: any, error: any) => {
+              if (result) {
+                best = String(result.bestTranscription?.formattedString ?? best);
+                if (params?.partial && !result.isFinal) bridge.emit('speech.partial', { transcript: best });
+                if (result.isFinal && listenPending) settleListen();
+              }
+              if (error && listenPending) {
+                const p = listenPending; listenPending = null;
+                teardownListen();
+                p?.resolve(best); // resolve with whatever we have — stopListening contract
+              }
+            });
+
+            const input = engine.inputNode;
+            const format = input.outputFormatForBus(0);
+            input.installTapOnBusBufferSizeFormatBlock(0, 1024, format, (buffer: any, _when: any) => {
+              request?.appendAudioPCMBuffer(buffer);
+            });
+            engine.prepare();
+            engine.startAndReturnError(null);
+          } catch (e: any) {
+            const p = listenPending; listenPending = null;
+            teardownListen();
+            p?.reject(err('NATIVE_ERROR', e?.message ?? 'listen failed'));
+          }
+        });
+      });
+    })
+  );
+}
+
+function registerAndroid(): void {
+  // TextToSpeech + SpeechRecognizer are plain Java → direct interop, no kotlin flag, no gradle dep.
+  let tts: any = null;
+  let ttsReady = false;
+  const ctx = () => Utils.android.getApplicationContext();
+
+  const ensureTts = (): Promise<any> =>
+    new Promise((resolve) => {
+      if (tts && ttsReady) { resolve(tts); return; }
+      tts = new android.speech.tts.TextToSpeech(
+        ctx(),
+        new android.speech.tts.TextToSpeech.OnInitListener({
+          onInit(status: number) {
+            ttsReady = status === android.speech.tts.TextToSpeech.SUCCESS;
+            resolve(ttsReady ? tts : null);
+          },
+        })
+      );
+    });
+
+  bridge.register('speech.speak', async (params: any) => {
+    const engine = await ensureTts();
+    if (!engine) throw err('NATIVE_ERROR', 'TextToSpeech init failed');
+    const text = String(params?.text ?? '');
+    if (params?.lang) {
+      try { engine.setLanguage(new java.util.Locale.Builder().setLanguageTag(String(params.lang)).build()); } catch { /* keep default */ }
+    }
+    if (params?.rate != null) engine.setSpeechRate(Number(params.rate));
+    if (params?.pitch != null) engine.setPitch(Number(params.pitch));
+    const id = 'u' + Date.now();
+    return new Promise<void>((resolve) => {
+      engine.setOnUtteranceProgressListener(
+        new android.speech.tts.UtteranceProgressListener({
+          onStart() {},
+          onDone() { resolve(); },
+          onError() { resolve(); }, // resolve regardless — speak() promises completion, not success
+        })
+      );
+      engine.speak(text, android.speech.tts.TextToSpeech.QUEUE_FLUSH, null, id);
+    });
+  });
+
+  bridge.register('speech.stop', () => { try { tts?.stop?.(); } catch { /* noop */ } });
+
+  bridge.register('speech.voices', () => {
+    const out: Array<{ id: string; name: string; lang: string }> = [];
+    try {
+      const voices = tts?.getVoices?.();
+      if (voices) {
+        const it = voices.iterator();
+        while (it.hasNext()) {
+          const v = it.next();
+          out.push({ id: String(v.getName()), name: String(v.getName()), lang: String(v.getLocale().toLanguageTag()) });
+        }
+      }
+    } catch { /* TTS not yet init — return empty */ }
+    return out;
+  });
+
+  // STT — SpeechRecognizer must be created + driven on the main (UI) thread.
+  let recognizer: any = null;
+  let listenPending: { resolve: (v: string) => void; reject: (e: any) => void } | null = null;
+  let best = '';
+
+  const settle = () => {
+    const p = listenPending; listenPending = null;
+    try { recognizer?.stopListening?.(); recognizer?.destroy?.(); } catch { /* noop */ }
+    recognizer = null;
+    p?.resolve(best);
+  };
+
+  bridge.register('speech.stopListening', () => {
+    Utils.dispatchToMainThread(() => { if (listenPending) settle(); });
+  });
+
+  bridge.register('speech.listen', async (params: any) => {
+    const granted = await requestPermissions(['android.permission.RECORD_AUDIO']);
+    if (!granted) throw err('DENIED', 'Microphone permission denied');
+    if (listenPending) throw err('NATIVE_ERROR', 'speech.listen: already listening');
+
+    return new Promise<string>((resolve, reject) => {
+      best = '';
+      listenPending = { resolve, reject };
+      Utils.dispatchToMainThread(() => {
+        try {
+          if (!android.speech.SpeechRecognizer.isRecognitionAvailable(ctx())) {
+            const p = listenPending; listenPending = null;
+            p?.reject(err('UNSUPPORTED', 'No speech recognition service'));
+            return;
+          }
+          recognizer = android.speech.SpeechRecognizer.createSpeechRecognizer(ctx());
+          const pickText = (b: any): string => {
+            const arr = b?.getStringArrayList(android.speech.SpeechRecognizer.RESULTS_RECOGNITION);
+            return arr && arr.size() ? String(arr.get(0)) : '';
+          };
+          recognizer.setRecognitionListener(
+            new android.speech.RecognitionListener({
+              onReadyForSpeech() {}, onBeginningOfSpeech() {}, onRmsChanged() {},
+              onBufferReceived() {}, onEndOfSpeech() {}, onEvent() {},
+              onPartialResults(b: any) {
+                if (!params?.partial) return;
+                const t = pickText(b);
+                if (t) { best = t; bridge.emit('speech.partial', { transcript: t }); }
+              },
+              onResults(b: any) {
+                const t = pickText(b);
+                if (t) best = t;
+                if (listenPending) settle();
+              },
+              onError(_code: number) {
+                if (listenPending) settle(); // resolve with best-so-far (e.g. timeout/no-match)
+              },
+            })
+          );
+          const intent = new android.content.Intent(android.speech.RecognizerIntent.ACTION_RECOGNIZE_SPEECH);
+          intent.putExtra(
+            android.speech.RecognizerIntent.EXTRA_LANGUAGE_MODEL,
+            android.speech.RecognizerIntent.LANGUAGE_MODEL_FREE_FORM
+          );
+          if (params?.lang) intent.putExtra(android.speech.RecognizerIntent.EXTRA_LANGUAGE, String(params.lang));
+          if (params?.partial) intent.putExtra(android.speech.RecognizerIntent.EXTRA_PARTIAL_RESULTS, true);
+          recognizer.startListening(intent);
+        } catch (e: any) {
+          const p = listenPending; listenPending = null;
+          p?.reject(err('NATIVE_ERROR', e?.message ?? 'listen failed'));
+        }
+      });
+    });
+  });
+}

package/runtime/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appwrap-shell",
   "main": "app/app.ts",
-  "version": "0.21.0",
+  "version": "0.28.0",
   "private": true,
   "scripts": {
     "dev:ios": "ns run ios",

package/src/cli.ts

@@ -172,6 +172,9 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
 const OPTIONAL_GROUP_HANDLERS: Record<string, { file: string; fn: string }> = {
   health: { file: './handlers-health', fn: 'registerHealthHandlers' },
   oauth: { file: './handlers-oauth', fn: 'registerOAuthHandlers' },
+  reviews: { file: './handlers-reviews', fn: 'registerReviewsHandlers' },
+  scanner: { file: './handlers-scanner', fn: 'registerScannerHandlers' },
+  speech: { file: './handlers-speech', fn: 'registerSpeechHandlers' },
 };
 
 /** Generate the two composition artifacts in the wrapper: the active capability list (drives the
@@ -366,6 +369,7 @@ export const SHELL_CONFIG = {
   openNewWindowsInBrowser: ${JSON.stringify(cfg.openNewWindowsInBrowser ?? false)},
   pushIos: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.ios !== false)},
   pushAndroid: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.android !== false)},
+  pushRegistrationUrl: ${JSON.stringify(cfg.push?.registrationUrl ?? '')},
 };
 `;
   writeFileSync(join(outDir, 'app/shell/config.ts'), content);
@@ -434,7 +438,15 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
 
 function stampTeamId(outDir: string, cfg: AppwrapConfig): void {
   const xcconfig = join(outDir, 'App_Resources/iOS/build.xcconfig');
-  if (!existsSync(xcconfig) || !cfg.teamId) return;
+  // A placeholder/empty teamId silently produces an unsignable build (DEVELOPMENT_TEAM = YOUR_APPLE_TEAM_ID
+  // → xcodebuild "No Account for Team"). Warn loudly rather than let a long build fail cryptically.
+  if (!cfg.teamId || /YOUR_APPLE_TEAM_ID|^$/.test(cfg.teamId)) {
+    console.warn(`⚠ teamId is unset/placeholder ("${cfg.teamId ?? ''}") — device builds won't sign.\n` +
+      '  Set it to your Apple Team ID in appwrap.config (Xcode → Settings → Accounts shows it; ' +
+      'Individual = paid, Personal Team = free).');
+    return;
+  }
+  if (!existsSync(xcconfig)) return;
   let src = readFileSync(xcconfig, 'utf8');
   src = /DEVELOPMENT_TEAM\s*=/.test(src)
     ? src.replace(/DEVELOPMENT_TEAM\s*=\s*[^;\n]*;?/, `DEVELOPMENT_TEAM = ${cfg.teamId};`)
@@ -1147,7 +1159,21 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
   // Dev deploy → debug mode: keep-awake + WebView inspector for continuous troubleshooting.
   stampShellConfig(outDir, { ...cfg, debug: true });
   console.log('▶ ns build ios --for-device  (debug: keep-awake + inspector on)');
-  execFileSync('ns', ['build', 'ios', '--for-device'], { cwd: outDir, stdio: 'inherit' });
+  try {
+    execFileSync('ns', ['build', 'ios', '--for-device'], { cwd: outDir, stdio: 'inherit' });
+  } catch (e) {
+    // The xcodebuild dump above is cryptic; surface the two signing failures we actually hit most.
+    console.error(
+      '\n✖ Device build failed — if the errors above mention signing:\n' +
+        `  • "Failed Registering Bundle Identifier … not available" → the App ID "${cfg.id}" is already\n` +
+        '    registered to another team (e.g. a prior free-team build). Change `id` in appwrap.config to a\n' +
+        '    unique string and re-deploy.\n' +
+        '  • "profile doesn\'t include the … entitlement" (e.g. HealthKit) → that capability needs a PAID\n' +
+        '    team (Individual). A free Personal Team can\'t hold it — switch teamId or drop the module.\n' +
+        '  • "No Account for Team" → sign that Apple ID into Xcode → Settings → Accounts first.'
+    );
+    process.exit(1);
+  }
 
   const ipaDir = join(outDir, 'platforms/ios/build/Debug-iphoneos');
   const ipa = existsSync(ipaDir) ? readdirSync(ipaDir).find((f) => f.endsWith('.ipa')) : undefined;

package/src/config.ts

@@ -139,6 +139,10 @@ export interface AppwrapConfig {
     apsEnvironment?: 'development' | 'production';
     /** Path (relative to the PWA project) to the Firebase `google-services.json` for Android FCM. */
     googleServicesJson?: string;
+    /** Optional backend URL the shell POSTs the device token to NATIVELY on acquisition (`{token,
+     * platform}`). Native HTTP sidesteps the WKWebView app:// cross-origin wall — the token reaches
+     * your server with no WebView fetch. Your backend stores it + sends pushes (provider-agnostic). */
+    registrationUrl?: string;
   };
 }