@livx.cc/appwrap 0.19.0

package/runtime/app/shell/handlers.ts

@@ -0,0 +1,149 @@
+import { ApplicationSettings, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+import { SHELL_CONFIG } from './config';
+import { onPwaHandshake } from './events';
+import { showToast } from './toast';
+import { setStatusBarStyle } from './status-bar';
+import { buildCapabilityMap } from './capabilities.manifest';
+import { ACTIVE_MODULE_NAMES } from './active-modules.generated';
+
+/** Build identifier for the native shell bundle — bump per deploy to spot stale bundles. */
+export const SHELL_BUILD = 'oauth-media-speaker-1';
+
+/** Register all protocol-v1 handlers. */
+export function registerHandlers(): void {
+  bridge.register('app.handshake', () => {
+    // The PWA's JS is now live → flush any deep link buffered during launch.
+    onPwaHandshake();
+    // Capability map is composed from the active module set (appwrap.json `modules` → the generated
+    // ACTIVE_MODULE_NAMES) + the always-on core, deduped. Opt-out capabilities report 'none' so the
+    // kit degrades gracefully. Push is special — gated by per-platform build config, not the manifest.
+    const capabilities = buildCapabilityMap(new Set(ACTIVE_MODULE_NAMES), isIOS ? 'ios' : 'android') as Record<string, 'native' | 'none'>;
+    capabilities.push = (isIOS ? SHELL_CONFIG.pushIos : SHELL_CONFIG.pushAndroid) ? 'native' : 'none';
+    return {
+      protocol: 1,
+      platform: isIOS ? 'ios' : 'android',
+      app: { id: SHELL_CONFIG.appId, name: SHELL_CONFIG.name, version: SHELL_CONFIG.version, build: SHELL_BUILD },
+      debug: { lastNotifTap: safeJson(ApplicationSettings.getString('kit:__notifTap', '')) },
+      capabilities,
+    };
+  });
+
+  bridge.register('haptics.impact', ({ style = 'medium' }: { style?: string }) => {
+    if (isIOS) {
+      const styles: Record<string, UIImpactFeedbackStyle> = {
+        light: UIImpactFeedbackStyle.Light,
+        medium: UIImpactFeedbackStyle.Medium,
+        heavy: UIImpactFeedbackStyle.Heavy,
+        soft: UIImpactFeedbackStyle.Soft,
+        rigid: UIImpactFeedbackStyle.Rigid,
+      };
+      const generator = UIImpactFeedbackGenerator.alloc().initWithStyle(
+        styles[style] ?? UIImpactFeedbackStyle.Medium
+      );
+      generator.impactOccurred();
+    } else if (isAndroid) {
+      vibrateAndroid(style === 'heavy' ? 60 : style === 'light' ? 15 : 30);
+    }
+  });
+
+  bridge.register('haptics.notify', ({ type = 'success' }: { type?: string }) => {
+    if (isIOS) {
+      const types: Record<string, UINotificationFeedbackType> = {
+        success: UINotificationFeedbackType.Success,
+        warning: UINotificationFeedbackType.Warning,
+        error: UINotificationFeedbackType.Error,
+      };
+      const gen = UINotificationFeedbackGenerator.alloc().init();
+      gen.notificationOccurred(types[type] ?? UINotificationFeedbackType.Success);
+    } else if (isAndroid) {
+      vibrateAndroid(type === 'error' ? 120 : 60);
+    }
+  });
+
+  bridge.register('share.share', async ({ title, text, url }: { title?: string; text?: string; url?: string }) => {
+    const content = [text, url].filter(Boolean).join('\n');
+    if (isIOS) {
+      const items = NSMutableArray.new();
+      if (content) items.addObject(content);
+      const controller = UIActivityViewController.alloc().initWithActivityItemsApplicationActivities(
+        items as any,
+        null
+      );
+      const rootVC = Utils.ios.getRootViewController();
+      // iPad requires a popover anchor
+      if (controller.popoverPresentationController) {
+        controller.popoverPresentationController.sourceView = rootVC.view;
+      }
+      rootVC.presentViewControllerAnimatedCompletion(controller, true, null);
+    } else if (isAndroid) {
+      const intent = new android.content.Intent(android.content.Intent.ACTION_SEND);
+      intent.setType('text/plain');
+      if (title) intent.putExtra(android.content.Intent.EXTRA_SUBJECT, title);
+      intent.putExtra(android.content.Intent.EXTRA_TEXT, content);
+      const chooser = android.content.Intent.createChooser(intent, title ?? 'Share');
+      chooser.addFlags(android.content.Intent.FLAG_ACTIVITY_NEW_TASK);
+      Utils.android.getApplicationContext().startActivity(chooser);
+    }
+  });
+
+  bridge.register(
+    'share.files',
+    ({ files, text }: { files: Array<{ name: string; mimeType: string; base64: string }>; title?: string; text?: string }) => {
+      if (!isIOS) return; // Android file share needs a FileProvider (parked)
+      const items = NSMutableArray.new();
+      if (text) items.addObject(text);
+      const tmp = NSTemporaryDirectory();
+      (files ?? []).forEach((f, i) => {
+        const data = NSData.alloc().initWithBase64EncodedStringOptions(f.base64, 0 as unknown as NSDataBase64DecodingOptions);
+        if (!data) return;
+        const filePath = tmp + i + '-' + (f.name || 'file'); // index-prefix: avoid same-name collisions in one call
+        data.writeToFileAtomically(filePath, true);
+        items.addObject(NSURL.fileURLWithPath(filePath));
+      });
+      const controller = UIActivityViewController.alloc().initWithActivityItemsApplicationActivities(
+        items as any,
+        null
+      );
+      const rootVC = Utils.ios.getRootViewController();
+      if (controller.popoverPresentationController) {
+        controller.popoverPresentationController.sourceView = rootVC.view; // iPad anchor
+      }
+      rootVC.presentViewControllerAnimatedCompletion(controller, true, null);
+    }
+  );
+
+  bridge.register('storage.get', ({ key }: { key: string }) =>
+    JSON.parse(ApplicationSettings.getString(`kit:${key}`, 'null'))
+  );
+  bridge.register('storage.set', ({ key, value }: { key: string; value?: unknown }) =>
+    ApplicationSettings.setString(`kit:${key}`, JSON.stringify(value ?? null))
+  );
+  bridge.register('storage.remove', ({ key }: { key: string }) =>
+    ApplicationSettings.remove(`kit:${key}`)
+  );
+
+  bridge.register('toast.show', ({ message, duration }: { message: string; duration?: 'short' | 'long' }) =>
+    showToast(String(message ?? ''), duration ?? 'short')
+  );
+
+  bridge.register('ui.statusBar.setStyle', ({ style }: { style: 'light' | 'dark' }) =>
+    setStatusBarStyle(style)
+  );
+}
+
+/** Parse a stored JSON breadcrumb; null if absent/unparseable (diagnostic, never throws). */
+function safeJson(s: string): unknown {
+  if (!s) return null;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}
+
+function vibrateAndroid(ms: number): void {
+  const context = Utils.android.getApplicationContext();
+  const vibrator = context.getSystemService(android.content.Context.VIBRATOR_SERVICE);
+  vibrator?.vibrate(ms);
+}

package/runtime/app/shell/ios-frameworks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Ambient declarations for iOS frameworks not covered by the default
+ * @nativescript/types-ios reference set (LocalAuthentication, CoreLocation,
+ * PhotosUI). Marshalled at runtime by the NativeScript iOS runtime regardless.
+ */
+declare const LAContext: any;
+declare const LAPolicy: any;
+declare const LABiometryType: any;
+declare const CLLocationManager: any;
+declare const CLAuthorizationStatus: any;
+declare const CLLocationManagerDelegate: any;
+declare const kCLLocationAccuracyHundredMeters: number;
+declare type CLLocation = any;
+declare type CLLocationManager = any;
+declare const PHPickerConfiguration: any;
+declare const PHPickerViewController: any;
+declare const PHPickerViewControllerDelegate: any;
+declare type PHPickerResult = any;
+declare type PHPickerViewController = any;
+// StoreKit / CoreMotion / ContactsUI / EventKit (parity handlers)
+declare const SKStoreReviewController: any;
+declare const CMMotionManager: any;
+declare const CMPedometer: any;
+// HealthKit (health/steps module)
+declare const HKHealthStore: any;
+declare const HKObjectType: any;
+declare const HKQuery: any;
+declare const HKStatisticsQuery: any;
+declare const HKStatisticsOptions: any;
+declare const HKUnit: any;
+declare const CNContactPickerViewController: any;
+declare const CNContactPickerDelegate: any;
+declare const EKEventStore: any;
+declare const EKEvent: any;
+declare const EKSpan: any;
+declare const EKEntityType: any;

package/runtime/app/shell/ios-image.ts

@@ -0,0 +1,15 @@
+/** Downscale a UIImage to `maxSize` (longest edge) and encode as a JPEG data URL. */
+export function uiImageToDataUrl(img: UIImage, maxSize: number): string {
+  const w = img.size.width;
+  const h = img.size.height;
+  const scale = Math.min(1, maxSize / Math.max(w, h));
+  const tw = Math.round(w * scale);
+  const th = Math.round(h * scale);
+  UIGraphicsBeginImageContextWithOptions({ width: tw, height: th } as CGSize, false, 1);
+  img.drawInRect({ origin: { x: 0, y: 0 }, size: { width: tw, height: th } } as CGRect);
+  const scaled = UIGraphicsGetImageFromCurrentImageContext() ?? img;
+  UIGraphicsEndImageContext();
+  const data = UIImageJPEGRepresentation(scaled, 0.85);
+  const b64 = data ? data.base64EncodedStringWithOptions(0 as unknown as NSDataBase64EncodingOptions) : '';
+  return `data:image/jpeg;base64,${b64}`;
+}

package/runtime/app/shell/ios-ui-delegate.ts

@@ -0,0 +1,131 @@
+import { Utils } from '@nativescript/core';
+
+/**
+ * WKUIDelegate for the shell WebView. Two jobs:
+ *  1. Auto-grant getUserMedia (mic/camera) for our own origin — the native app
+ *     already holds the OS-level permission (Info.plist), so re-prompting per
+ *     web-origin is friction. iOS 15+ only; older builds fall back to WebKit's
+ *     own prompt.
+ *  2. Re-implement the JS alert/confirm/prompt panels — WKWebView drops them
+ *     silently without a UIDelegate, which would break any PWA calling
+ *     window.alert/confirm/prompt.
+ *
+ * Returns a retained delegate instance (the WKWebView holds uiDelegate weakly).
+ */
+export function createUiDelegate(): any {
+  const DelegateClass = (NSObject as any).extend(
+    {
+      // iOS 15+: WKUIDelegate media capture permission.
+      webViewRequestMediaCapturePermissionForOriginInitiatedByFrameTypeDecisionHandler(
+        _webView: WKWebView,
+        _origin: any,
+        _frame: any,
+        _type: any,
+        decisionHandler: (decision: number) => void
+      ): void {
+        // WKPermissionDecision.Grant === 1 — silently grant (the app already holds the
+        // OS-level mic/camera permission; media.ensurePermission established TCC).
+        // NOTE: this only ever sees capabilities the build DECLARED — a request for an
+        // UNDECLARED capability is rejected upstream in JS (mediaCaptureGuardJs), because
+        // WebKit asks TCC to authorize the device AROUND this callback and a missing usage
+        // string is a hard process-kill a native `deny` here cannot prevent. So denying
+        // here is pointless for the crash; the real guard must be (and is) at the JS layer.
+        decisionHandler(1);
+      },
+
+      // Preserve the behavior NS's own UIDelegate gave us (we fully replace it):
+      // target=_blank / window.open has no new window in a shell → load it in place.
+      webViewCreateWebViewWithConfigurationForNavigationActionWindowFeatures(
+        webView: WKWebView,
+        _configuration: any,
+        navigationAction: WKNavigationAction,
+        _windowFeatures: any
+      ): WKWebView | null {
+        const frame = navigationAction.targetFrame;
+        if (!frame || !frame.mainFrame) webView.loadRequest(navigationAction.request);
+        return null;
+      },
+
+      webViewRunJavaScriptAlertPanelWithMessageInitiatedByFrameCompletionHandler(
+        _webView: WKWebView,
+        message: string,
+        _frame: any,
+        completionHandler: () => void
+      ): void {
+        Utils.dispatchToMainThread(() => {
+          const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
+            null as any,
+            String(message ?? ''),
+            UIAlertControllerStyle.Alert
+          );
+          alert.addAction(
+            UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () => completionHandler())
+          );
+          present(alert);
+        });
+      },
+
+      webViewRunJavaScriptConfirmPanelWithMessageInitiatedByFrameCompletionHandler(
+        _webView: WKWebView,
+        message: string,
+        _frame: any,
+        completionHandler: (ok: boolean) => void
+      ): void {
+        Utils.dispatchToMainThread(() => {
+          const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
+            null as any,
+            String(message ?? ''),
+            UIAlertControllerStyle.Alert
+          );
+          alert.addAction(
+            UIAlertAction.actionWithTitleStyleHandler('Cancel', UIAlertActionStyle.Cancel, () =>
+              completionHandler(false)
+            )
+          );
+          alert.addAction(
+            UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () => completionHandler(true))
+          );
+          present(alert);
+        });
+      },
+
+      webViewRunJavaScriptTextInputPanelWithPromptDefaultTextInitiatedByFrameCompletionHandler(
+        _webView: WKWebView,
+        prompt: string,
+        defaultText: string,
+        _frame: any,
+        completionHandler: (text: string | null) => void
+      ): void {
+        Utils.dispatchToMainThread(() => {
+          const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
+            null as any,
+            String(prompt ?? ''),
+            UIAlertControllerStyle.Alert
+          );
+          let field: UITextField | null = null;
+          alert.addTextFieldWithConfigurationHandler((tf: UITextField) => {
+            tf.text = String(defaultText ?? '');
+            field = tf;
+          });
+          alert.addAction(
+            UIAlertAction.actionWithTitleStyleHandler('Cancel', UIAlertActionStyle.Cancel, () =>
+              completionHandler(null)
+            )
+          );
+          alert.addAction(
+            UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () =>
+              completionHandler(field ? String(field.text ?? '') : '')
+            )
+          );
+          present(alert);
+        });
+      },
+    },
+    { protocols: [WKUIDelegate] }
+  );
+  return DelegateClass.new();
+}
+
+function present(alert: UIAlertController): void {
+  Utils.ios.getRootViewController().presentViewControllerAnimatedCompletion(alert, true, null);
+}

package/runtime/app/shell/mime.ts

@@ -0,0 +1,29 @@
+/** Extension → MIME map shared by the iOS app:// handler and the Android asset interceptor. */
+export const MIME: Record<string, string> = {
+  html: 'text/html',
+  js: 'text/javascript',
+  mjs: 'text/javascript',
+  css: 'text/css',
+  json: 'application/json',
+  webmanifest: 'application/manifest+json',
+  map: 'application/json',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+  webp: 'image/webp',
+  ico: 'image/x-icon',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  wasm: 'application/wasm',
+  txt: 'text/plain',
+  mp3: 'audio/mpeg',
+  mp4: 'video/mp4',
+};
+
+export function mimeFor(ext: string, fallbackPath = ''): string {
+  return MIME[ext] ?? (fallbackPath.endsWith('.html') ? 'text/html' : 'application/octet-stream');
+}

package/runtime/app/shell/native-log.ts

@@ -0,0 +1,22 @@
+import { knownFolders, path as nsPath } from '@nativescript/core';
+
+declare const NSString: any;
+
+/**
+ * Single debug log sink → Documents/appwrap-web.log. Both the forwarded WebView console
+ * (custom-webview) and native shell diagnostics (handlers) write here, because NativeScript's
+ * native `console.log`/`NSLog` do NOT surface to `devicectl --console`/`idevicesyslog` on a device
+ * build. Pull it with `appwrap logs ios`. Native lines are tagged `[native:*]`. Capped per session.
+ */
+let _log = '';
+
+export function appwrapNativeLog(line: string): void {
+  try {
+    _log += line + '\n';
+    if (_log.length > 160000) _log = _log.slice(-120000);
+    const p = nsPath.join(knownFolders.documents().path, 'appwrap-web.log');
+    NSString.stringWithString(_log).writeToFileAtomicallyEncodingError(p, true, 4 /*NSUTF8*/, null as any);
+  } catch {
+    /* best-effort */
+  }
+}

package/runtime/app/shell/optional-handlers.generated.ts

@@ -0,0 +1,10 @@
+/**
+ * Generated by `appwrap init`/`sync`. Registers opt-in modules that own their own handler file, so a
+ * build that doesn't enable them never imports (or bundles) their native code. Do not edit.
+ * Committed DEFAULT registers all optional groups (back-compat). The CLI rewrites the imports/calls
+ * to only the active OPTIONAL_GROUPS.
+ */
+// Default registers no optional modules (health & friends are strictly opt-in via appwrap.json
+// `modules`). The CLI rewrites this barrel to import only the active OPTIONAL_GROUPS.
+export function registerOptionalHandlers(): void {
+}

package/runtime/app/shell/orientation.ts

@@ -0,0 +1,43 @@
+/**
+ * iOS supported-orientation mask, shared between the AppDelegate
+ * (`application:supportedInterfaceOrientationsForWindow:`) and the
+ * `screen.orientation.*` handlers. Raw UIInterfaceOrientationMask bit values
+ * (1 << UIInterfaceOrientation) so no ambient UIKit types are needed.
+ */
+export const ORIENTATION_MASK = {
+  portrait: 1 << 1, // 2
+  portraitUpsideDown: 1 << 2, // 4
+  landscapeLeft: 1 << 3, // 8
+  landscapeRight: 1 << 4, // 16
+  landscape: (1 << 3) | (1 << 4), // 24
+  allButUpsideDown: (1 << 1) | (1 << 3) | (1 << 4), // 26 — default, free rotation sans upside-down
+};
+
+let iosMask = ORIENTATION_MASK.allButUpsideDown;
+
+/** The mask the AppDelegate reports to UIKit. */
+export function iosOrientationMask(): number {
+  return iosMask;
+}
+
+/** Map a `kit.screen.orientation` lock value to an iOS mask. */
+export function maskForLock(orientation: string): number {
+  switch (orientation) {
+    case 'portrait':
+      return ORIENTATION_MASK.portrait;
+    case 'portrait-upside-down':
+      return ORIENTATION_MASK.portraitUpsideDown;
+    case 'landscape':
+      return ORIENTATION_MASK.landscape;
+    case 'landscape-left':
+      return ORIENTATION_MASK.landscapeLeft;
+    case 'landscape-right':
+      return ORIENTATION_MASK.landscapeRight;
+    default:
+      return ORIENTATION_MASK.allButUpsideDown; // 'any' / unlock
+  }
+}
+
+export function setIosOrientationMask(mask: number): void {
+  iosMask = mask;
+}

package/runtime/app/shell/status-bar.ts

@@ -0,0 +1,129 @@
+import { Application, Color, Page, Screen, Utils, View, isAndroid, isIOS } from '@nativescript/core';
+import { SHELL_CONFIG } from './config';
+
+let currentPage: Page | null = null;
+
+/**
+ * Make the Android system bars TRANSPARENT so the page background (the NS page `backgroundColor`)
+ * spans edge-to-edge under them, instead of the default opaque black status/nav bars that box the
+ * WebView in black letterbox strips.
+ *
+ * Uses NativeScript's own helper (`org.nativescript.widgets.Utils.enableEdgeToEdge` via
+ * `Utils.android.enableEdgeToEdge`) with transparent status-bar colors — rolling our own window
+ * flags doesn't stick (NS re-applies its layout and its status-bar-style setter clears the
+ * translucent flag, giving a black bar or a dark scrim). Required on Android 15+/API 35 anyway.
+ *
+ * NOTE: NS still insets the WebView itself below the bars (its native widget layout pads the page
+ * content), so the bar regions show the PAGE background, not the web body. Consumers should set
+ * `appwrap.json.backgroundColor` to their app's theme background so the bars blend seamlessly. (iOS
+ * is genuinely edge-to-edge — the WKWebView fills the safe areas and the web paints them via
+ * env(safe-area-inset-*).)
+ */
+export function enableAndroidEdgeToEdge(): void {
+  if (!isAndroid) return;
+  const transparent = new Color(0, 0, 0, 0);
+  const apply = () => {
+    const activity = Application.android?.startActivity;
+    if (!activity) return;
+    try {
+      // Explicit transparent status-bar colors (light + dark) so the page background — not the NS
+      // page backgroundColor — shows under the status bar. Nav bar keeps NS's default subtle scrim.
+      (Utils as any).android.enableEdgeToEdge(activity, {
+        statusBarLightColor: transparent,
+        statusBarDarkColor: transparent,
+      });
+    } catch (e) {
+      console.warn('AppWrap: edge-to-edge setup failed', e);
+    }
+  };
+  apply();
+  // NS applies its own status-bar inset AFTER onPageLoaded; re-apply on the next loop so edge-to-edge
+  // wins the race (otherwise the WebView stays boxed below an opaque status-bar strip).
+  setTimeout(apply, 50);
+}
+
+/**
+ * EXPERIMENTAL (SHELL_CONFIG.edgeToEdge). Make the WebView draw genuinely edge-to-edge UNDER the
+ * transparent system bars instead of NS boxing it below them, and feed the real safe-area insets to
+ * the web layer as `--saie-{top,right,bottom,left}` CSS vars (dp). With the WebView now filling the
+ * window, native `env(safe-area-inset-*)` should also populate — so a PWA can pad with
+ * `max(env(safe-area-inset-top), var(--saie-top, 0px))` and paint the bar regions itself, matching
+ * any theme (no static page backgroundColor to match). No-op unless edgeToEdge + Android.
+ */
+export function wireAndroidSafeArea(webView: View): void {
+  if (!isAndroid || !SHELL_CONFIG.edgeToEdge) return;
+  // Un-box the layout that wraps the WebView so it (and its child WebView) fills the window UNDER the
+  // bars. 'dont-apply' = NS won't pad it with the system-bar insets.
+  const layout = (webView.parent as View) ?? webView;
+  (layout as any).androidOverflowEdge = 'dont-apply';
+
+  const density = Screen.mainScreen.scale || 1; // physical px per dp
+  const inject = (l: number, t: number, r: number, b: number) => {
+    const js =
+      `(function(s){` +
+      `s.setProperty('--saie-left','${l}px');s.setProperty('--saie-top','${t}px');` +
+      `s.setProperty('--saie-right','${r}px');s.setProperty('--saie-bottom','${b}px');` +
+      `})(document.documentElement.style);`;
+    try {
+      (webView as any).android?.evaluateJavascript(js, null);
+    } catch (e) {
+      console.warn('AppWrap: safe-area inject failed', e);
+    }
+  };
+  inject(0, 0, 0, 0); // sane defaults until the first real read
+
+  // Read the window insets DIRECTLY from the decor view. NS's androidOverflowInset event doesn't
+  // reliably reach a nested layout (its edge-to-edge machinery consumes insets higher up), so we go
+  // straight to the platform API — systemBars ∪ displayCutout, the same set a native edge-to-edge
+  // app uses. Returns true once non-zero insets are available (i.e. the window is laid out).
+  const dp = (px: number) => Math.round((px || 0) / density);
+  const readAndInject = (): boolean => {
+    try {
+      const decor = Application.android?.startActivity?.getWindow()?.getDecorView();
+      const wi = decor?.getRootWindowInsets?.();
+      if (!wi) return false;
+      const Type = (global as any).android.view.WindowInsets.Type;
+      const ins = wi.getInsets(Type.systemBars() | Type.displayCutout());
+      inject(dp(ins.left), dp(ins.top), dp(ins.right), dp(ins.bottom));
+      return ins.top + ins.bottom + ins.left + ins.right > 0;
+    } catch (e) {
+      console.warn('AppWrap: safe-area read failed', e);
+      return false;
+    }
+  };
+
+  // Insets are 0 until the window is laid out — retry a few times, then keep them fresh on
+  // resume / rotation (bar visibility + cutout side can change).
+  let tries = 0;
+  const tick = () => {
+    if (readAndInject() || ++tries > 12) return;
+    setTimeout(tick, 150);
+  };
+  setTimeout(tick, 80);
+  Application.on(Application.resumeEvent, () => setTimeout(readAndInject, 120));
+  Application.on(Application.orientationChangedEvent, () => setTimeout(readAndInject, 200));
+}
+
+export function bindStatusBarPage(page: Page): void {
+  currentPage = page;
+}
+
+/** 'light' = white icons/text (for dark backgrounds), 'dark' = black. */
+export function setStatusBarStyle(style: 'light' | 'dark'): void {
+  if (isIOS) {
+    if (currentPage) (currentPage as any).statusBarStyle = style;
+  } else if (isAndroid) {
+    const window = Application.android?.startActivity?.getWindow();
+    if (!window) return;
+    const decorView = window.getDecorView();
+    const controller = (decorView as any).getWindowInsetsController?.();
+    if (controller) {
+      const APPEARANCE_LIGHT_STATUS_BARS = 8; // WindowInsetsController.APPEARANCE_LIGHT_STATUS_BARS
+      // Android "light status bar" = dark icons; invert from our naming
+      controller.setSystemBarsAppearance(
+        style === 'dark' ? APPEARANCE_LIGHT_STATUS_BARS : 0,
+        APPEARANCE_LIGHT_STATUS_BARS
+      );
+    }
+  }
+}

package/runtime/app/shell/toast.ts

@@ -0,0 +1,67 @@
+import { Utils, isAndroid, isIOS } from '@nativescript/core';
+
+/** Native toast (trimmed to what the kit exposes). */
+export function showToast(message: string, duration: 'short' | 'long' = 'short'): void {
+  const ms = duration === 'long' ? 3500 : 2000;
+  if (isAndroid) {
+    const Toast = (android as any).widget.Toast;
+    Toast.makeText(
+      Utils.android.getApplicationContext(),
+      message,
+      duration === 'long' ? Toast.LENGTH_LONG : Toast.LENGTH_SHORT
+    ).show();
+  } else if (isIOS) {
+    showIOSToast(message, ms);
+  }
+}
+
+function showIOSToast(message: string, durationMs: number): void {
+  const rootVC = Utils.ios.getRootViewController();
+  if (!rootVC?.view) return;
+
+  const containerView = UIView.alloc().initWithFrame(CGRectMake(0, 0, 300, 60));
+  containerView.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(0.08, 0.08, 0.1, 0.6);
+  containerView.layer.cornerRadius = 12;
+  containerView.clipsToBounds = true;
+
+  const blurEffect = UIBlurEffect.effectWithStyle(UIBlurEffectStyle.Dark);
+  const blurView = UIVisualEffectView.alloc().initWithEffect(blurEffect);
+  blurView.frame = containerView.bounds;
+  blurView.autoresizingMask = UIViewAutoresizing.FlexibleWidth | UIViewAutoresizing.FlexibleHeight;
+  containerView.addSubview(blurView);
+
+  const label = UILabel.alloc().initWithFrame(CGRectMake(16, 0, 268, 60));
+  label.text = message;
+  label.textColor = UIColor.whiteColor;
+  label.textAlignment = NSTextAlignment.Center;
+  label.font = UIFont.systemFontOfSizeWeight(15, UIFontWeightMedium);
+  label.numberOfLines = 2;
+  blurView.contentView.addSubview(label);
+
+  const screenBounds = UIScreen.mainScreen.bounds;
+  containerView.center = CGPointMake(screenBounds.size.width / 2, screenBounds.size.height - 120);
+
+  rootVC.view.addSubview(containerView);
+  containerView.alpha = 0;
+  containerView.transform = CGAffineTransformMakeScale(0.8, 0.8);
+
+  UIView.animateWithDurationDelayOptionsAnimationsCompletion(
+    0.3, 0, UIViewAnimationOptions.CurveEaseOut,
+    () => {
+      containerView.alpha = 1;
+      containerView.transform = CGAffineTransformIdentity;
+    },
+    () => {
+      setTimeout(() => {
+        UIView.animateWithDurationDelayOptionsAnimationsCompletion(
+          0.3, 0, UIViewAnimationOptions.CurveEaseIn,
+          () => {
+            containerView.alpha = 0;
+            containerView.transform = CGAffineTransformMakeScale(0.8, 0.8);
+          },
+          () => containerView.removeFromSuperview()
+        );
+      }, durationMs);
+    }
+  );
+}