@livx.cc/appwrap 0.19.0

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

@@ -0,0 +1,405 @@
+import { Application, ApplicationSettings, Connectivity, Device, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+import { onDeepLink } from './events';
+import { onRemoteMessage } from './handlers-push';
+import { uiImageToDataUrl } from './ios-image';
+import { maskForLock, setIosOrientationMask } from './orientation';
+
+/**
+ * Extended capability handlers — iOS-first (Android arrives with the transport upgrade).
+ * Each handler is small and self-contained; heavy domains (push, files) come later.
+ */
+export function registerExtendedHandlers(): void {
+  // ── device ─────────────────────────────────────────────────────────
+  bridge.register('device.info', () => {
+    let battery: { level: number; charging: boolean } | undefined;
+    if (isIOS) {
+      const dev = UIDevice.currentDevice;
+      dev.batteryMonitoringEnabled = true;
+      if (dev.batteryLevel >= 0) {
+        battery = {
+          level: dev.batteryLevel,
+          charging:
+            dev.batteryState === UIDeviceBatteryState.Charging ||
+            dev.batteryState === UIDeviceBatteryState.Full,
+        };
+      }
+    }
+    return {
+      model: Device.model,
+      os: Device.os,
+      osVersion: Device.osVersion,
+      language: Device.language,
+      region: Device.region,
+      manufacturer: Device.manufacturer,
+      battery,
+    };
+  });
+
+  // ── clipboard ──────────────────────────────────────────────────────
+  bridge.register('clipboard.copy', ({ text }: { text: string }) => {
+    if (isIOS) {
+      UIPasteboard.generalPasteboard.string = String(text ?? '');
+    } else if (isAndroid) {
+      const context = Utils.android.getApplicationContext();
+      const cm = context.getSystemService(android.content.Context.CLIPBOARD_SERVICE);
+      cm.setPrimaryClip(android.content.ClipData.newPlainText('appwrap', String(text ?? '')));
+    }
+  });
+  bridge.register('clipboard.read', () => {
+    if (isIOS) return UIPasteboard.generalPasteboard.string ?? null;
+    if (isAndroid) {
+      const context = Utils.android.getApplicationContext();
+      const cm = context.getSystemService(android.content.Context.CLIPBOARD_SERVICE);
+      const clip = cm.getPrimaryClip();
+      return clip && clip.getItemCount() > 0 ? String(clip.getItemAt(0).getText() ?? '') : null;
+    }
+    return null;
+  });
+
+  // ── secure storage (Keychain/Keystore via @nativescript/secure-storage) ──
+  const secure = new (require('@nativescript/secure-storage').SecureStorage)();
+  bridge.register('storage.secure.get', async ({ key }: { key: string }) =>
+    (await secure.get({ key: `kit:${key}` })) ?? null
+  );
+  bridge.register('storage.secure.set', ({ key, value }: { key: string; value: string }) =>
+    secure.set({ key: `kit:${key}`, value: String(value ?? '') }).then(() => undefined)
+  );
+  bridge.register('storage.secure.remove', ({ key }: { key: string }) =>
+    secure.remove({ key: `kit:${key}` }).then(() => undefined)
+  );
+
+  // ── notifications (UNUserNotificationCenter, iOS) ──────────────────
+  // iOS suppresses banners while the app is foreground unless a delegate opts in.
+  // Without this, a scheduled local notification fires but is never shown on-device.
+  installForegroundNotificationDelegate();
+
+  bridge.register('notifications.requestPermission', () => {
+    if (!isIOS) throw Object.assign(new Error('iOS only for now'), { code: 'UNSUPPORTED' });
+    return new Promise<string>((resolve) => {
+      const center = UNUserNotificationCenter.currentNotificationCenter();
+      center.requestAuthorizationWithOptionsCompletionHandler(
+        UNAuthorizationOptions.Alert | UNAuthorizationOptions.Badge | UNAuthorizationOptions.Sound,
+        (granted) => resolve(granted ? 'granted' : 'denied')
+      );
+    });
+  });
+
+  bridge.register('notifications.schedule', ({ id, title, body, delaySec, deepLink }: any) => {
+    if (!isIOS) throw Object.assign(new Error('iOS only for now'), { code: 'UNSUPPORTED' });
+    const nid = id ?? Math.floor(Math.random() * 100000);
+    return new Promise((resolve, reject) => {
+      const content = UNMutableNotificationContent.new();
+      content.title = String(title ?? '');
+      if (body) content.body = String(body);
+      // Carry the deep-link on the notification; the tap delegate re-emits it.
+      // Plain JS object → NativeScript marshals it to NSDictionary (more reliable
+      // than dictionaryWithObjectForKey across NS versions).
+      if (deepLink) content.userInfo = { url: String(deepLink) } as any;
+      const trigger = UNTimeIntervalNotificationTrigger.triggerWithTimeIntervalRepeats(
+        Math.max(1, delaySec ?? 1),
+        false
+      );
+      const request = UNNotificationRequest.requestWithIdentifierContentTrigger(
+        String(nid),
+        content,
+        trigger
+      );
+      UNUserNotificationCenter.currentNotificationCenter().addNotificationRequestWithCompletionHandler(
+        request,
+        (error) => (error ? reject(new Error(error.localizedDescription)) : resolve({ id: nid }))
+      );
+    });
+  });
+
+  bridge.register('notifications.pending', () => {
+    if (!isIOS) return 0;
+    return new Promise<number>((resolve) => {
+      UNUserNotificationCenter.currentNotificationCenter().getPendingNotificationRequestsWithCompletionHandler(
+        (requests) => resolve(requests.count)
+      );
+    });
+  });
+
+  bridge.register('notifications.setBadge', ({ count }: { count: number }) => {
+    if (!isIOS) return;
+    return new Promise<void>((resolve) => {
+      Utils.dispatchToMainThread(() => {
+        UNUserNotificationCenter.currentNotificationCenter().setBadgeCountWithCompletionHandler?.(
+          count,
+          () => {}
+        );
+        resolve();
+      });
+    });
+  });
+
+  bridge.register('notifications.clear', () => {
+    if (!isIOS) return;
+    const center = UNUserNotificationCenter.currentNotificationCenter();
+    center.removeAllPendingNotificationRequests();
+    center.removeAllDeliveredNotifications();
+  });
+
+  // ── biometrics (LAContext) ─────────────────────────────────────────
+  bridge.register('biometrics.available', () => {
+    if (!isIOS) return { available: false, type: 'none' };
+    const ctx = LAContext.new();
+    const available = ctx.canEvaluatePolicyError(
+      LAPolicy.DeviceOwnerAuthenticationWithBiometrics
+    );
+    const type =
+      ctx.biometryType === LABiometryType.FaceID ? 'face'
+      : ctx.biometryType === LABiometryType.TouchID ? 'touch'
+      : 'none';
+    return { available, type };
+  });
+
+  bridge.register('biometrics.authenticate', ({ reason }: { reason?: string }) => {
+    if (!isIOS) throw Object.assign(new Error('iOS only for now'), { code: 'UNSUPPORTED' });
+    return new Promise((resolve, reject) => {
+      const ctx = LAContext.new();
+      ctx.evaluatePolicyLocalizedReasonReply(
+        LAPolicy.DeviceOwnerAuthenticationWithBiometrics,
+        String(reason ?? 'Authenticate'),
+        (success, error) => {
+          if (success) resolve({ success: true });
+          else reject(Object.assign(new Error(error?.localizedDescription ?? 'failed'), { code: 'DENIED' }));
+        }
+      );
+    });
+  });
+
+  // ── geolocation (CLLocationManager) ────────────────────────────────
+  bridge.register('geo.current', () => {
+    if (!isIOS) throw Object.assign(new Error('iOS only for now'), { code: 'UNSUPPORTED' });
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(Object.assign(new Error('location timeout'), { code: 'TIMEOUT' }));
+      }, 15000);
+
+      let manager: CLLocationManager | null = null;
+      let delegate: any = null;
+      const cleanup = () => {
+        clearTimeout(timer);
+        manager?.stopUpdatingLocation();
+        manager = null;
+        delegate = null;
+      };
+
+      const DelegateClass = (NSObject as any).extend(
+        {
+          locationManagerDidUpdateLocations(_m: CLLocationManager, locations: NSArray<CLLocation>) {
+            const loc = locations.lastObject;
+            if (!loc) return;
+            const result = {
+              lat: loc.coordinate.latitude,
+              lng: loc.coordinate.longitude,
+              accuracy: loc.horizontalAccuracy,
+            };
+            cleanup();
+            resolve(result);
+          },
+          locationManagerDidFailWithError(_m: CLLocationManager, error: NSError) {
+            cleanup();
+            reject(Object.assign(new Error(error.localizedDescription), { code: 'DENIED' }));
+          },
+          locationManagerDidChangeAuthorization(m: CLLocationManager) {
+            const st = m.authorizationStatus;
+            if (st === CLAuthorizationStatus.kCLAuthorizationStatusAuthorizedWhenInUse ||
+                st === CLAuthorizationStatus.kCLAuthorizationStatusAuthorizedAlways) {
+              m.startUpdatingLocation();
+            } else if (st === CLAuthorizationStatus.kCLAuthorizationStatusDenied) {
+              cleanup();
+              reject(Object.assign(new Error('location permission denied'), { code: 'DENIED' }));
+            }
+          },
+        },
+        { protocols: [CLLocationManagerDelegate] }
+      );
+
+      Utils.dispatchToMainThread(() => {
+        manager = CLLocationManager.new();
+        delegate = DelegateClass.new();
+        manager.delegate = delegate;
+        manager.desiredAccuracy = kCLLocationAccuracyHundredMeters;
+        const st = manager.authorizationStatus;
+        if (st === CLAuthorizationStatus.kCLAuthorizationStatusNotDetermined) {
+          manager.requestWhenInUseAuthorization();
+        } else {
+          manager.startUpdatingLocation();
+        }
+      });
+    });
+  });
+
+  // ── photos (PHPickerViewController) ────────────────────────────────
+  bridge.register('photos.pick', ({ dataUrl, maxSize }: any = {}) => {
+    if (!isIOS) throw Object.assign(new Error('iOS only for now'), { code: 'UNSUPPORTED' });
+    return new Promise((resolve) => {
+      Utils.dispatchToMainThread(() => {
+        const config = PHPickerConfiguration.new();
+        config.selectionLimit = 1;
+        const DelegateClass = (NSObject as any).extend(
+          {
+            pickerDidFinishPicking(picker: PHPickerViewController, results: NSArray<PHPickerResult>) {
+              picker.dismissViewControllerAnimatedCompletion(true, null);
+              const result = results.count > 0 ? results.objectAtIndex(0) : null;
+              if (!result) return resolve({ picked: false });
+              result.itemProvider.loadObjectOfClassCompletionHandler(UIImage.class(), (img: UIImage) => {
+                if (!img) return resolve({ picked: true });
+                const out: any = { picked: true, width: img.size.width, height: img.size.height };
+                if (dataUrl) out.dataUrl = uiImageToDataUrl(img, maxSize ?? 1024);
+                resolve(out);
+              });
+            },
+          },
+          { protocols: [PHPickerViewControllerDelegate] }
+        );
+        const picker = PHPickerViewController.alloc().initWithConfiguration(config);
+        const delegate = DelegateClass.new();
+        (picker as any)._appwrapDelegate = delegate; // retain
+        picker.delegate = delegate;
+        Utils.ios.getRootViewController().presentViewControllerAnimatedCompletion(picker, true, null);
+      });
+    });
+  });
+
+  // ── network (NS Connectivity) ──────────────────────────────────────
+  bridge.register('network.status', () => connectivityStatus());
+
+  // ── ui extras ──────────────────────────────────────────────────────
+  bridge.register('ui.safeArea', () => {
+    if (!isIOS) return { top: 0, bottom: 0, left: 0, right: 0 };
+    const insets = Utils.ios.getRootViewController().view.safeAreaInsets;
+    return { top: insets.top, bottom: insets.bottom, left: insets.left, right: insets.right };
+  });
+
+  bridge.register('ui.brightness.get', () => (isIOS ? UIScreen.mainScreen.brightness : 0.5));
+  bridge.register('ui.brightness.set', ({ level }: { level: number }) => {
+    if (isIOS) {
+      Utils.dispatchToMainThread(() => {
+        UIScreen.mainScreen.brightness = Math.max(0, Math.min(1, level));
+      });
+    }
+  });
+
+  bridge.register('ui.keepAwake', ({ on }: { on: boolean }) => {
+    if (isIOS) {
+      Utils.dispatchToMainThread(() => {
+        UIApplication.sharedApplication.idleTimerDisabled = !!on;
+      });
+    }
+  });
+
+  // ── screen orientation ─────────────────────────────────────────────
+  // current() is cross-platform via core; lock/unlock are iOS here and
+  // overridden for Android in registerAndroidHandlers (runs last).
+  bridge.register('screen.orientation.current', () =>
+    Application.orientation() === 'landscape' ? 'landscape' : 'portrait'
+  );
+  bridge.register('screen.orientation.lock', ({ orientation }: { orientation: string }) => {
+    if (isIOS) applyIosOrientation(maskForLock(String(orientation)));
+  });
+  bridge.register('screen.orientation.unlock', () => {
+    if (isIOS) applyIosOrientation(maskForLock('any'));
+  });
+}
+
+/** Set the supported-orientation mask and force UIKit to re-evaluate it now (iOS 16+ geometry update). */
+function applyIosOrientation(mask: number): void {
+  setIosOrientationMask(mask);
+  Utils.dispatchToMainThread(() => {
+    const rootVC: any = Utils.ios.getRootViewController();
+    rootVC?.setNeedsUpdateOfSupportedInterfaceOrientations?.();
+    const G: any = global as any;
+    const Prefs = G.UIWindowSceneGeometryPreferencesIOS;
+    const scenes: any = UIApplication.sharedApplication.connectedScenes?.allObjects;
+    if (!Prefs || !scenes) return; // pre-iOS-16: the mask alone takes effect on next rotation
+    for (let i = 0; i < scenes.count; i++) {
+      const scene = scenes.objectAtIndex(i);
+      if (scene?.requestGeometryUpdateWithPreferencesErrorHandler) {
+        const prefs = Prefs.alloc().initWithInterfaceOrientations(mask);
+        scene.requestGeometryUpdateWithPreferencesErrorHandler(prefs, null);
+      }
+    }
+  });
+}
+
+let notifDelegate: any = null; // retained for the app's lifetime
+/**
+ * Install the UNUserNotificationCenter delegate. MUST run before
+ * `didFinishLaunching` returns, else a tap that COLD-LAUNCHES the app never
+ * reaches `didReceiveNotificationResponse` (Apple delivers it only to a
+ * delegate set during launch) — the deep link is lost and you land on home.
+ * Idempotent; also called from registerExtendedHandlers as a warm fallback.
+ */
+export function installForegroundNotificationDelegate(): void {
+  if (!isIOS || notifDelegate) return;
+  const DelegateClass = (NSObject as any).extend(
+    {
+      userNotificationCenterWillPresentNotificationWithCompletionHandler(
+        _center: UNUserNotificationCenter,
+        notification: UNNotification,
+        completionHandler: (opts: number) => void
+      ): void {
+        // Foreground REMOTE push (push trigger) → surface to kit.push.onMessage.
+        if (isRemotePush(notification)) onRemoteMessage(notification.request.content.userInfo, false);
+        // Present banner + list + sound + badge even while foreground (min target iOS 16).
+        completionHandler(
+          UNNotificationPresentationOptions.Banner |
+            UNNotificationPresentationOptions.List |
+            UNNotificationPresentationOptions.Sound |
+            UNNotificationPresentationOptions.Badge
+        );
+      },
+      // Notification tapped → route its deep link through the same path as an external open.
+      userNotificationCenterDidReceiveNotificationResponseWithCompletionHandler(
+        _center: UNUserNotificationCenter,
+        response: UNNotificationResponse,
+        completionHandler: () => void
+      ): void {
+        // Tapped REMOTE push → kit.push.onTap (with payload). Local notifs keep the deep-link path below.
+        if (isRemotePush(response.notification)) onRemoteMessage(response.notification.request.content.userInfo, true);
+        // userInfo may come back as an NSDictionary or an auto-marshalled JS object.
+        const info: any = response.notification.request.content.userInfo;
+        const url = info ? (typeof info.objectForKey === 'function' ? info.objectForKey('url') : info.url) : null;
+        // Diagnostic breadcrumb (persists across the cold relaunch) — surfaced in the handshake's debug field.
+        try {
+          ApplicationSettings.setString(
+            'kit:__notifTap',
+            JSON.stringify({ at: Date.now(), url: url ? String(url) : null, hadInfo: !!info })
+          );
+        } catch {
+          /* diagnostic only */
+        }
+        if (url) onDeepLink(String(url));
+        completionHandler();
+      },
+    },
+    { protocols: [UNUserNotificationCenterDelegate] }
+  );
+  notifDelegate = DelegateClass.new();
+  UNUserNotificationCenter.currentNotificationCenter().delegate = notifDelegate;
+}
+
+/** A remote (APNs) notification has a UNPushNotificationTrigger; local ones have a time/calendar trigger. */
+function isRemotePush(notification: UNNotification): boolean {
+  const trigger = notification?.request?.trigger;
+  return !!trigger && trigger instanceof UNPushNotificationTrigger;
+}
+
+export function connectivityStatus(): { online: boolean; type: string } {
+  const t = Connectivity.getConnectionType();
+  const map: Record<number, string> = {
+    [Connectivity.connectionType.none]: 'none',
+    [Connectivity.connectionType.wifi]: 'wifi',
+    [Connectivity.connectionType.mobile]: 'cellular',
+    [Connectivity.connectionType.ethernet]: 'ethernet',
+    [Connectivity.connectionType.bluetooth]: 'bluetooth',
+    [Connectivity.connectionType.vpn]: 'vpn',
+  };
+  const type = map[t] ?? 'unknown';
+  return { online: type !== 'none', type };
+}

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

@@ -0,0 +1,134 @@
+import { Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+import { requestPermissions, startActivityForResult } from './android-helpers';
+
+declare const android: any;
+declare const cc: any; // generated from the HealthConnectBridge.kt shim (overrides/)
+
+const err = (code: string, message: string) => Object.assign(new Error(message), { code });
+
+/** Step counting from the platform health store — today's total, global, survives an app kill.
+ * iOS: HealthKit. Android: Health Connect (via the HealthConnectBridge.kt shim) with a
+ * SensorManager TYPE_STEP_COUNTER fallback when Health Connect isn't available. */
+export function registerHealthHandlers(): void {
+  if (isIOS) registerIos();
+  else if (isAndroid) registerAndroid();
+}
+
+/** NSNumber/JS-number tolerant read. */
+function num(v: any): number {
+  if (typeof v === 'number') return v;
+  if (v && typeof v.doubleValue === 'number') return v.doubleValue; // NSNumber
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function registerIos(): void {
+  // HealthKit reads the Health app's AGGREGATED step total (iPhone + Apple Watch + other sources) —
+  // recorded by the OS regardless of the app, so it's global and survives kill. Count = today's sum.
+  const store = HKHealthStore.new();
+  const stepType = HKObjectType.quantityTypeForIdentifier('HKQuantityTypeIdentifierStepCount');
+  const startOfToday = () => {
+    const d = new Date();
+    d.setHours(0, 0, 0, 0); // local midnight
+    return NSDate.dateWithTimeIntervalSince1970(d.getTime() / 1000);
+  };
+
+  bridge.register('health.requestAccess', () =>
+    new Promise((resolve) => {
+      if (!HKHealthStore.isHealthDataAvailable()) { resolve(false); return; }
+      const readSet = NSSet.setWithObject(stepType);
+      store.requestAuthorizationToShareTypesReadTypesCompletion(null, readSet, (ok: boolean, e: any) => {
+        Utils.dispatchToMainThread(() => resolve(!!ok && !e));
+      });
+    })
+  );
+
+  bridge.register('health.start', () => {
+    if (!HKHealthStore.isHealthDataAvailable()) throw err('UNSUPPORTED', 'HealthKit unavailable on this device');
+  });
+  bridge.register('health.stop', () => {});
+
+  // HKStatisticsQuery completion fires off-main — settle the bridge promise on the main thread so the
+  // WKWebView response delivery (evaluateJavaScript) is main-thread.
+  bridge.register('health.count', () =>
+    new Promise((resolve, reject) => {
+      const predicate = HKQuery.predicateForSamplesWithStartDateEndDateOptions(startOfToday(), NSDate.date(), 0);
+      const q = HKStatisticsQuery.alloc().initWithQuantityTypeQuantitySamplePredicateOptionsCompletionHandler(
+        stepType, predicate, HKStatisticsOptions.CumulativeSum, (_q: any, stats: any, e: any) => {
+          Utils.dispatchToMainThread(() => {
+            if (e) { reject(err('NATIVE_ERROR', e.localizedDescription ?? 'health query failed')); return; }
+            const sum = stats && stats.sumQuantity ? stats.sumQuantity() : null;
+            resolve({ steps: sum ? Math.round(sum.doubleValueForUnit(HKUnit.countUnit())) : 0 });
+          });
+        }
+      );
+      store.executeQuery(q);
+    })
+  );
+}
+
+function registerAndroid(): void {
+  const ctx = () => Utils.android.getApplicationContext();
+  const HCB = () => cc.livx.appwrap.HealthConnectBridge;
+  // Primary path = Health Connect (system store, Wear-inclusive, survives kill). Cached once.
+  let hc: boolean | null = null;
+  const hcAvailable = () => {
+    if (hc == null) {
+      try { hc = !!HCB().isAvailable(ctx()); } catch (e) { hc = false; }
+    }
+    return hc;
+  };
+
+  // ── sensor fallback (TYPE_STEP_COUNTER) — when Health Connect isn't available ──
+  let sensorManager: any = null;
+  let listener: any = null;
+  let baseline: number | null = null;
+  let latest: number | null = null;
+  let registered = false;
+  const ensureSensor = () => {
+    if (!sensorManager) sensorManager = ctx().getSystemService(android.content.Context.SENSOR_SERVICE);
+  };
+  const stopSensor = () => {
+    if (registered) { sensorManager.unregisterListener(listener); registered = false; }
+  };
+  const startSensor = () => {
+    ensureSensor();
+    const sensor = sensorManager.getDefaultSensor(android.hardware.Sensor.TYPE_STEP_COUNTER);
+    if (!sensor) throw err('UNSUPPORTED', 'No step-counter sensor on this device');
+    stopSensor();
+    baseline = null;
+    latest = null;
+    listener = new android.hardware.SensorEventListener({
+      onSensorChanged: (ev: any) => { const v = num(ev.values[0]); latest = v; if (baseline == null) baseline = v; },
+      onAccuracyChanged: () => {},
+    });
+    sensorManager.registerListener(listener, sensor, android.hardware.SensorManager.SENSOR_DELAY_NORMAL);
+    registered = true;
+  };
+  const sensorCount = () => ({ steps: baseline != null && latest != null ? Math.max(0, Math.round(latest - baseline)) : 0 });
+
+  bridge.register('health.requestAccess', async () => {
+    if (hcAvailable()) {
+      // Launch the Health Connect permission UI, then re-check what was granted.
+      await startActivityForResult(HCB().permissionIntent(ctx())).catch((e) => console.warn('[health] HC permission intent failed', e));
+      return new Promise((resolve) =>
+        HCB().hasPermission(ctx(), new (HCB().BoolCallback)({ onResult: (g: boolean) => resolve(!!g) }))
+      );
+    }
+    return requestPermissions(['android.permission.ACTIVITY_RECOGNITION']);
+  });
+
+  bridge.register('health.start', () => { if (!hcAvailable()) startSensor(); });
+  bridge.register('health.stop', () => { if (!hcAvailable()) stopSensor(); });
+
+  bridge.register('health.count', () => {
+    if (hcAvailable()) {
+      // Health Connect: today's aggregated total (dedupes across sources incl. Wear).
+      return new Promise((resolve) =>
+        HCB().readTodaySteps(ctx(), new (HCB().LongCallback)({ onResult: (v: any) => { const n = Number(v); resolve({ steps: n > 0 ? n : 0 }); } }))
+      );
+    }
+    return sensorCount();
+  });
+}

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

@@ -0,0 +1,126 @@
+import { Utils, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+
+// AVAudioSession globals (NS resolves these from the AVFoundation metadata at runtime).
+declare const AVAudioSession: any;
+declare const AVAudioSessionCategoryPlayAndRecord: string;
+declare const AVAudioSessionPortBuiltInReceiver: string;
+declare const AVAudioSessionRouteChangeNotification: string;
+declare const AVAudioSessionPortOverride: any;
+declare const NSNotificationCenter: any;
+
+let routeObserverArmed = false;
+
+/** List the current output port types (e.g. "Receiver", "Speaker", "BluetoothA2DP"). */
+function outputPortTypes(session: any): string[] {
+  const outputs = session.currentRoute?.outputs;
+  const types: string[] = [];
+  for (let i = 0; i < (outputs?.count ?? 0); i++) types.push(String(outputs.objectAtIndex(i).portType));
+  return types;
+}
+
+function isOnBuiltInReceiver(session: any): boolean {
+  return outputPortTypes(session).indexOf(AVAudioSessionPortBuiltInReceiver) !== -1;
+}
+
+/** Whether the session can record (PlayAndRecord) — i.e. we're (or about to be) in a call. */
+function isRecordCategory(session: any): boolean {
+  return String(session.category) === String(AVAudioSessionCategoryPlayAndRecord);
+}
+
+/** Push output to the loudspeaker while a call route (PlayAndRecord) is on the built-in receiver. */
+function forceSpeakerIfReceiverDuringCall(): void {
+  const session = AVAudioSession.sharedInstance();
+  if (!isRecordCategory(session) || !isOnBuiltInReceiver(session)) return; // not a call, or already speaker/headset/BT
+  try {
+    session.overrideOutputAudioPortError(AVAudioSessionPortOverride.Speaker, null);
+  } catch {
+    /* benign — route may have changed again under us */
+  }
+}
+
+/** Observe route changes once; re-assert loudspeaker whenever a call route drops to the receiver. */
+function observeAudioRouteForSpeaker(): void {
+  if (routeObserverArmed) return;
+  routeObserverArmed = true;
+  NSNotificationCenter.defaultCenter.addObserverForNameObjectQueueUsingBlock(
+    AVAudioSessionRouteChangeNotification,
+    null,
+    null,
+    () => Utils.dispatchToMainThread(() => forceSpeakerIfReceiverDuringCall())
+  );
+}
+
+/**
+ * Live-media session config. getUserMedia / playback themselves are pure WebView
+ * APIs (unlocked by the UIDelegate / onPermissionRequest grants in the custom
+ * webviews); this only tunes the native *audio session*, which iOS needs to play
+ * over the silent switch and to route mic+speaker for calls. Android routes
+ * fine on its own — honest no-op there.
+ */
+export function registerMediaHandlers(): void {
+  // DIAGNOSTIC: surface the WKWebView UIDelegate status to the page (on-screen log).
+  bridge.register('debug.webviewInfo', () => ({ diag: (global as any).__appwrapWebviewDiag ?? 'n/a (android/web)' }));
+
+  // Auto loudspeaker for in-WebView WebRTC calls. When getUserMedia is live, WebKit drives the
+  // shared AVAudioSession into PlayAndRecord and routes playback to the *earpiece/receiver* at
+  // call-gain — so remote audio sounds quiet even at max volume. We observe route changes and, while
+  // a capture (PlayAndRecord) session is active and the output fell back to the receiver, override
+  // the output port to the loudspeaker. Scoped to PlayAndRecord so non-call playback is untouched;
+  // honors a connected headset/Bluetooth route (only the built-in receiver is redirected).
+  if (isIOS) observeAudioRouteForSpeaker();
+
+  // Establish the OS-level (TCC) mic/camera grant from the *app* process. WKWebView's
+  // getUserMedia checks the same per-app TCC entry but doesn't persist a grant of its
+  // own, so without this it re-prompts on every call. AVCaptureDevice.requestAccess
+  // prompts once and the grant sticks — after which the WebView capture is silent.
+  bridge.register('media.ensurePermission', async ({ audio, video }: { audio?: boolean; video?: boolean } = {}) => {
+    if (!isIOS) return { audio: 'granted', video: 'granted' }; // Android: onPermissionRequest handles it
+
+    const ask = (mediaType: string): Promise<string> =>
+      new Promise((resolve) => {
+        const status = AVCaptureDevice.authorizationStatusForMediaType(mediaType);
+        if (status === AVAuthorizationStatus.Authorized) return resolve('granted');
+        if (status === AVAuthorizationStatus.Denied || status === AVAuthorizationStatus.Restricted) {
+          return resolve('denied');
+        }
+        AVCaptureDevice.requestAccessForMediaTypeCompletionHandler(mediaType, (granted: boolean) =>
+          resolve(granted ? 'granted' : 'denied')
+        );
+      });
+
+    const out: { audio?: string; video?: string } = {};
+    if (audio) out.audio = await ask(AVMediaTypeAudio);
+    if (video) out.video = await ask(AVMediaTypeVideo);
+    return out;
+  });
+
+  bridge.register('media.configureAudio', ({ mode }: { mode?: string }) => {
+    if (!isIOS) return; // Android: nothing to configure
+    const session = AVAudioSession.sharedInstance();
+    let category: string;
+    let options = 0;
+    // Default mode = the system's choice for the category; voiceChat swaps in the
+    // voice-processing I/O unit (hardware AEC) so TTS doesn't bleed into the mic.
+    let avMode = AVAudioSessionModeDefault;
+    if (mode === 'playAndRecord') {
+      category = AVAudioSessionCategoryPlayAndRecord;
+      // Loud speaker by default + allow Bluetooth headsets for calls.
+      options =
+        AVAudioSessionCategoryOptions.DefaultToSpeaker | AVAudioSessionCategoryOptions.AllowBluetooth;
+    } else if (mode === 'voiceChat') {
+      // Full-duplex voice agent: PlayAndRecord + VoiceChat engages iOS acoustic
+      // echo cancellation, so speaker TTS is removed from the mic feed (no STT bleed).
+      category = AVAudioSessionCategoryPlayAndRecord;
+      options =
+        AVAudioSessionCategoryOptions.DefaultToSpeaker | AVAudioSessionCategoryOptions.AllowBluetooth;
+      avMode = AVAudioSessionModeVoiceChat;
+    } else if (mode === 'default') {
+      category = AVAudioSessionCategoryAmbient;
+    } else {
+      category = AVAudioSessionCategoryPlayback; // ignores the silent switch
+    }
+    session.setCategoryModeOptionsError(category, avMode, options as any, null as any);
+    session.setActiveError(true, null as any);
+  });
+}