@livx.cc/appwrap 0.39.4 → 0.39.8

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

@@ -15,21 +15,31 @@ const err = (code: string, message: string) => Object.assign(new Error(message),
 // empty protocols list it registers under the wrong selector and AVFoundation never calls it — the
 // scanner opens but never decodes. The first decoded object is forwarded via the `onResult` instance
 // field (assigned after `new()`), replacing the original closure capture.
-@NativeClass()
-class MetadataDelegate extends NSObject implements AVCaptureMetadataOutputObjectsDelegate {
-  static ObjCProtocols = [AVCaptureMetadataOutputObjectsDelegate];
-  onResult?: (obj: AVMetadataObject) => void;
-  static new(): MetadataDelegate {
-    return <MetadataDelegate>super.new();
-  }
-  captureOutputDidOutputMetadataObjectsFromConnection(
-    _output: AVCaptureOutput,
-    metadataObjects: NSArray<AVMetadataObject> | AVMetadataObject[],
-    _connection: AVCaptureConnection
-  ): void {
-    const obj = (metadataObjects as NSArray<AVMetadataObject>)?.firstObject;
-    if (obj) this.onResult?.(obj);
+// Built lazily INSIDE the iOS-only path (mirrors banner.ts): NSObject/AV* are iOS globals and this file
+// is imported on Android too, so a top-level `@NativeClass extends NSObject` would crash at module load.
+// any: runtime-built ObjC subclass holder; the class BODY stays fully typed.
+let MetadataDelegate: any;
+function metadataDelegateClass(): any {
+  if (!MetadataDelegate) {
+    @NativeClass()
+    class MetadataDelegateImpl extends NSObject implements AVCaptureMetadataOutputObjectsDelegate {
+      static ObjCProtocols = [AVCaptureMetadataOutputObjectsDelegate];
+      onResult?: (obj: AVMetadataObject) => void;
+      static new(): MetadataDelegateImpl {
+        return <MetadataDelegateImpl>super.new();
+      }
+      captureOutputDidOutputMetadataObjectsFromConnection(
+        _output: AVCaptureOutput,
+        metadataObjects: NSArray<AVMetadataObject> | AVMetadataObject[],
+        _connection: AVCaptureConnection
+      ): void {
+        const obj = (metadataObjects as NSArray<AVMetadataObject>)?.firstObject;
+        if (obj) this.onResult?.(obj);
+      }
+    }
+    MetadataDelegate = MetadataDelegateImpl;
   }
+  return MetadataDelegate;
 }
 
 /**
@@ -124,8 +134,8 @@ function registerIos(): void {
 
           // 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 delegate = MetadataDelegate.new();
-          delegate.onResult = (obj) => {
+          const delegate = metadataDelegateClass().new();
+          delegate.onResult = (obj: AVMetadataObject) => {
             if (!pending) return;
             const value = (obj as AVMetadataMachineReadableCodeObject).stringValue;
             if (value == null) return;

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

@@ -4,23 +4,6 @@ import { requestPermissions } from './android-helpers';
 
 const err = (code: string, message: string) => Object.assign(new Error(message), { code });
 
-// iOS speech-synthesizer delegate — both finish & cancel settle the pending speak (the JS
-// `speakPending` is captured via the `onSettle` instance field, assigned after `new()`).
-@NativeClass()
-class SpeakDelegate extends NSObject implements AVSpeechSynthesizerDelegate {
-  static ObjCProtocols = [AVSpeechSynthesizerDelegate];
-  onSettle?: () => void;
-  static new(): SpeakDelegate {
-    return <SpeakDelegate>super.new();
-  }
-  speechSynthesizerDidFinishSpeechUtterance(_s: AVSpeechSynthesizer, _u: AVSpeechUtterance): void {
-    this.onSettle?.();
-  }
-  speechSynthesizerDidCancelSpeechUtterance(_s: AVSpeechSynthesizer, _u: AVSpeechUtterance): void {
-    this.onSettle?.();
-  }
-}
-
 /**
  * Voice I/O. TTS: iOS AVSpeechSynthesizer / Android TextToSpeech — speak resolves on finish.
  * STT: iOS SFSpeechRecognizer + AVAudioEngine mic tap / Android SpeechRecognizer — listen resolves
@@ -37,6 +20,26 @@ export function registerSpeechHandlers(): void {
 }
 
 function registerIos(): void {
+  // iOS speech-synthesizer delegate — both finish & cancel settle the pending speak (the JS
+  // `speakPending` is captured via the `onSettle` instance field, assigned after `new()`). Declared
+  // INSIDE this iOS-only registrar (mirrors app.ts): NSObject/AV* are iOS globals and this shared
+  // module is imported on Android too, so a top-level `@NativeClass extends NSObject` would crash at
+  // module load.
+  @NativeClass()
+  class SpeakDelegate extends NSObject implements AVSpeechSynthesizerDelegate {
+    static ObjCProtocols = [AVSpeechSynthesizerDelegate];
+    onSettle?: () => void;
+    static new(): SpeakDelegate {
+      return <SpeakDelegate>super.new();
+    }
+    speechSynthesizerDidFinishSpeechUtterance(_s: AVSpeechSynthesizer, _u: AVSpeechUtterance): void {
+      this.onSettle?.();
+    }
+    speechSynthesizerDidCancelSpeechUtterance(_s: AVSpeechSynthesizer, _u: AVSpeechUtterance): void {
+      this.onSettle?.();
+    }
+  }
+
   // 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: AVSpeechSynthesizer | null = null;

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

@@ -9,14 +9,24 @@ const err = (code: string, message: string) => Object.assign(new Error(message),
 // (orphaned tracking window / throttled renderer), so recover from its didFinish. Strong-ref the
 // delegate while the browser is up (ARC would otherwise free it). Mirrors the OAuth delegate pattern.
 let activeSafariDelegate: NSObject | null = null;
-@NativeClass()
-class SafariDelegate extends NSObject implements SFSafariViewControllerDelegate {
-  static ObjCProtocols = [SFSafariViewControllerDelegate];
-  static new(): SafariDelegate { return <SafariDelegate>super.new(); }
-  safariViewControllerDidFinish(_controller: SFSafariViewController): void {
-    activeSafariDelegate = null;
-    bridge.getWebView()?.recoverAfterNativeSurface();
+// Built lazily INSIDE an iOS-only path (mirrors banner.ts): NSObject/SF* are iOS globals and this file
+// is imported on Android too, so a top-level `@NativeClass extends NSObject` would crash at module load.
+// any: runtime-built ObjC subclass holder; the class BODY stays fully typed.
+let SafariDelegate: any;
+function safariDelegateClass(): any {
+  if (!SafariDelegate) {
+    @NativeClass()
+    class SafariDelegateImpl extends NSObject implements SFSafariViewControllerDelegate {
+      static ObjCProtocols = [SFSafariViewControllerDelegate];
+      static new(): SafariDelegateImpl { return <SafariDelegateImpl>super.new(); }
+      safariViewControllerDidFinish(_controller: SFSafariViewController): void {
+        activeSafariDelegate = null;
+        bridge.getWebView()?.recoverAfterNativeSurface();
+      }
+    }
+    SafariDelegate = SafariDelegateImpl;
   }
+  return SafariDelegate;
 }
 
 /** Running on a simulator/emulator? (mirrors env.ts detection; kept local to avoid a cross-import). */
@@ -204,7 +214,7 @@ export function registerSystemHandlers(): void {
       Utils.dispatchToMainThread(() => {
         const vc = SFSafariViewController.alloc().initWithURL(NSURL.URLWithString(target));
         if (toolbarColor) vc.preferredControlTintColor = new Color(String(toolbarColor)).ios;
-        activeSafariDelegate = SafariDelegate.new();
+        activeSafariDelegate = safariDelegateClass().new();
         vc.delegate = activeSafariDelegate as SFSafariViewControllerDelegate;
         Utils.ios.getRootViewController().presentViewControllerAnimatedCompletion(vc, true, null);
       });

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

@@ -11,123 +11,134 @@ import { Utils } from '@nativescript/core';
  *     window.alert/confirm/prompt.
  *
  * Returns a retained delegate instance (the WKWebView holds uiDelegate weakly).
+ *
+ * Built lazily INSIDE createUiDelegate (mirrors banner.ts): NSObject/WK* are iOS globals, and although
+ * this module is reached only from the iOS WebView path today, defining the class at top level would
+ * still evaluate those globals at ES-module instantiation — keep it inside the factory to stay safe.
  */
-@NativeClass()
-class AppwrapUiDelegate extends NSObject implements WKUIDelegate {
-  static ObjCProtocols = [WKUIDelegate];
-  static new(): AppwrapUiDelegate {
-    return <AppwrapUiDelegate>super.new();
-  }
+// any: runtime-built ObjC subclass holder; the class BODY stays fully typed.
+let AppwrapUiDelegate: any;
+function appwrapUiDelegateClass(): any {
+  if (AppwrapUiDelegate) return AppwrapUiDelegate;
+  @NativeClass()
+  class AppwrapUiDelegateImpl extends NSObject implements WKUIDelegate {
+    static ObjCProtocols = [WKUIDelegate];
+    static new(): AppwrapUiDelegateImpl {
+      return <AppwrapUiDelegateImpl>super.new();
+    }
 
-  // iOS 15+: WKUIDelegate media capture permission.
-  webViewRequestMediaCapturePermissionForOriginInitiatedByFrameTypeDecisionHandler(
-    _webView: WKWebView,
-    _origin: WKSecurityOrigin,
-    _frame: WKFrameInfo,
-    _type: WKMediaCaptureType,
-    decisionHandler: (decision: WKPermissionDecision) => 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(WKPermissionDecision.Grant);
-  }
+    // iOS 15+: WKUIDelegate media capture permission.
+    webViewRequestMediaCapturePermissionForOriginInitiatedByFrameTypeDecisionHandler(
+      _webView: WKWebView,
+      _origin: WKSecurityOrigin,
+      _frame: WKFrameInfo,
+      _type: WKMediaCaptureType,
+      decisionHandler: (decision: WKPermissionDecision) => 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(WKPermissionDecision.Grant);
+    }
 
-  // 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: WKWebViewConfiguration,
-    navigationAction: WKNavigationAction,
-    _windowFeatures: WKWindowFeatures
-  ): WKWebView {
-    const frame = navigationAction.targetFrame;
-    if (!frame || !frame.mainFrame) webView.loadRequest(navigationAction.request);
-    return null as unknown as WKWebView;
-  }
+    // 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: WKWebViewConfiguration,
+      navigationAction: WKNavigationAction,
+      _windowFeatures: WKWindowFeatures
+    ): WKWebView {
+      const frame = navigationAction.targetFrame;
+      if (!frame || !frame.mainFrame) webView.loadRequest(navigationAction.request);
+      return null as unknown as WKWebView;
+    }
 
-  webViewRunJavaScriptAlertPanelWithMessageInitiatedByFrameCompletionHandler(
-    _webView: WKWebView,
-    message: string,
-    _frame: WKFrameInfo,
-    completionHandler: () => void
-  ): void {
-    Utils.dispatchToMainThread(() => {
-      const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
-        null as unknown as string,
-        String(message ?? ''),
-        UIAlertControllerStyle.Alert
-      );
-      alert.addAction(
-        UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () => completionHandler())
-      );
-      present(alert);
-    });
-  }
+    webViewRunJavaScriptAlertPanelWithMessageInitiatedByFrameCompletionHandler(
+      _webView: WKWebView,
+      message: string,
+      _frame: WKFrameInfo,
+      completionHandler: () => void
+    ): void {
+      Utils.dispatchToMainThread(() => {
+        const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
+          null as unknown as string,
+          String(message ?? ''),
+          UIAlertControllerStyle.Alert
+        );
+        alert.addAction(
+          UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () => completionHandler())
+        );
+        present(alert);
+      });
+    }
 
-  webViewRunJavaScriptConfirmPanelWithMessageInitiatedByFrameCompletionHandler(
-    _webView: WKWebView,
-    message: string,
-    _frame: WKFrameInfo,
-    completionHandler: (ok: boolean) => void
-  ): void {
-    Utils.dispatchToMainThread(() => {
-      const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
-        null as unknown as string,
-        String(message ?? ''),
-        UIAlertControllerStyle.Alert
-      );
-      alert.addAction(
-        UIAlertAction.actionWithTitleStyleHandler('Cancel', UIAlertActionStyle.Cancel, () =>
-          completionHandler(false)
-        )
-      );
-      alert.addAction(
-        UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () => completionHandler(true))
-      );
-      present(alert);
-    });
-  }
+    webViewRunJavaScriptConfirmPanelWithMessageInitiatedByFrameCompletionHandler(
+      _webView: WKWebView,
+      message: string,
+      _frame: WKFrameInfo,
+      completionHandler: (ok: boolean) => void
+    ): void {
+      Utils.dispatchToMainThread(() => {
+        const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
+          null as unknown as string,
+          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: WKFrameInfo,
-    completionHandler: (text: string) => void
-  ): void {
-    Utils.dispatchToMainThread(() => {
-      const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
-        null as unknown as string,
-        String(prompt ?? ''),
-        UIAlertControllerStyle.Alert
-      );
-      let field: UITextField | null = null;
-      alert.addTextFieldWithConfigurationHandler((tf: UITextField) => {
-        tf.text = String(defaultText ?? '');
-        field = tf;
+    webViewRunJavaScriptTextInputPanelWithPromptDefaultTextInitiatedByFrameCompletionHandler(
+      _webView: WKWebView,
+      prompt: string,
+      defaultText: string,
+      _frame: WKFrameInfo,
+      completionHandler: (text: string) => void
+    ): void {
+      Utils.dispatchToMainThread(() => {
+        const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
+          null as unknown as string,
+          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 as unknown as string)
+          )
+        );
+        alert.addAction(
+          UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () =>
+            completionHandler(field ? String(field.text ?? '') : '')
+          )
+        );
+        present(alert);
       });
-      alert.addAction(
-        UIAlertAction.actionWithTitleStyleHandler('Cancel', UIAlertActionStyle.Cancel, () =>
-          completionHandler(null as unknown as string)
-        )
-      );
-      alert.addAction(
-        UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () =>
-          completionHandler(field ? String(field.text ?? '') : '')
-        )
-      );
-      present(alert);
-    });
+    }
   }
+  AppwrapUiDelegate = AppwrapUiDelegateImpl;
+  return AppwrapUiDelegate;
 }
 
 export function createUiDelegate(): WKUIDelegate {
-  return AppwrapUiDelegate.new();
+  return appwrapUiDelegateClass().new();
 }
 
 function present(alert: UIAlertController): void {

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

@@ -27,10 +27,14 @@ export function enableAndroidEdgeToEdge(): void {
     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.
+      // page backgroundColor — shows under the status bar. In FULL edge-to-edge mode (the edgeToEdge
+      // config + wireAndroidSafeArea un-boxing) also make the NAV bar transparent so the web content
+      // draws under it too; otherwise keep NS's default nav-bar scrim (so the buttons stay legible on
+      // apps that aren't drawing their own content down there).
       Utils.android.enableEdgeToEdge(activity, {
         statusBarLightColor: transparent,
         statusBarDarkColor: transparent,
+        ...(SHELL_CONFIG.edgeToEdge ? { navigationBarLightColor: transparent, navigationBarDarkColor: transparent } : {}),
       });
     } catch (e) {
       console.warn('AppWrap: edge-to-edge setup failed', e);
@@ -52,11 +56,39 @@ export function enableAndroidEdgeToEdge(): void {
  */
 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;
-  // androidOverflowEdge: not in the public View typings — an NS edge-to-edge layout hint set dynamically.
-  (layout as any).androidOverflowEdge = 'dont-apply';
+  // Un-box the WebView so it fills the window UNDER the system bars. 'dont-apply' = NS won't pad the
+  // view with the system-bar insets. The insets are consumed/applied by the root FRAME (NS sets its
+  // androidOverflowEdge to 'ignore' by default — ui/frame/index.android.ts), NOT by the WebView's
+  // immediate parent, so overriding only webView.parent left the content boxed. Set it up the whole
+  // chain — root view (the Frame), the Page, and the WebView's parent — so whichever applies the
+  // insets stops padding. (androidOverflowEdge isn't in the public View typings — an NS layout hint.)
+  const targets: Array<View | null> = [
+    Application.getRootView() as View | null,
+    currentPage,
+    (webView.parent as View) ?? null,
+    webView,
+  ];
+  for (const t of targets) if (t) (t as any).androidOverflowEdge = 'dont-apply';
+
+  // HIDE the navigation bar (immersive) so the game is genuinely full-bleed at the bottom — drawing
+  // under a nav bar you can still see is moot. Status bar stays visible (clock/battery over the page).
+  // BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE: a swipe from the bottom edge reveals it briefly, then it
+  // re-hides — the standard game pattern. Immersive resets on resume / when transiently shown, so it's
+  // re-applied below. API 30+ (WindowInsetsController); the device floor for edge-to-edge is well above.
+  const hideNav = () => {
+    try {
+      const controller = Application.android?.startActivity?.getWindow()?.getInsetsController?.();
+      if (!controller) return;
+      controller.hide(android.view.WindowInsets.Type.navigationBars());
+      controller.setSystemBarsBehavior(
+        android.view.WindowInsetsController.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
+      );
+    } catch (e) {
+      console.warn('AppWrap: hide nav bar failed', e);
+    }
+  };
+  hideNav();
+  setTimeout(hideNav, 60); // win the race against NS's own post-load bar setup
 
   const density = Screen.mainScreen.scale || 1; // physical px per dp
   const inject = (l: number, t: number, r: number, b: number) => {
@@ -102,8 +134,8 @@ export function wireAndroidSafeArea(webView: View): void {
     setTimeout(tick, 150);
   };
   setTimeout(tick, 80);
-  Application.on(Application.resumeEvent, () => setTimeout(readAndInject, 120));
-  Application.on(Application.orientationChangedEvent, () => setTimeout(readAndInject, 200));
+  Application.on(Application.resumeEvent, () => { setTimeout(readAndInject, 120); setTimeout(hideNav, 120); });
+  Application.on(Application.orientationChangedEvent, () => { setTimeout(readAndInject, 200); setTimeout(hideNav, 200); });
 }
 
 export function bindStatusBarPage(page: Page): void {

package/src/cli.ts

@@ -20,6 +20,7 @@ import type * as CapManifest from '../../../runtime/app/shell/capabilities.manif
 // Config shape lives in its own import-safe module so a `appwrap.config.ts` file can import the
 // type + `defineConfig` helper without pulling in (and running) the CLI dispatch.
 import type { AppwrapConfig } from './config';
+import { unknownConfigKeys } from './config';
 import {
   androidScreenOrientation,
   applyBuildNumberFlag,
@@ -377,6 +378,15 @@ async function loadConfig(cwd: string, flags: Record<string, string>): Promise<A
   }
   const cfg = await readConfigFile(configPath);
 
+  // Warn (never fail) on keys this appwrap doesn't recognize. A config authored for a NEWER appwrap
+  // silently no-ops its unknown keys on an older install (e.g. `targetedDevices` before 0.39 → wrong
+  // device family, no error). Turn that silent no-op into a signal.
+  const stray = unknownConfigKeys(cfg as unknown as Record<string, unknown>);
+  if (stray.length) {
+    const ver = pkgVersion(resolve(import.meta.dir, '../package.json'));
+    for (const k of stray) console.warn(`⚠ appwrap: unrecognized config key '${k}' — ignored. If you expect it to apply, your installed @livx.cc/appwrap (${ver}) may predate it — upgrade.`);
+  }
+
   // Manifest as source: the appwrap config wins, the PWA manifest fills the gaps, template default last.
   // (DRY single-source — devs don't re-type identity already declared in the manifest.) See mergeManifest.
   if (cfg.pwaDist) mergeManifest(cfg, loadManifest(cwd, cfg));
@@ -819,6 +829,15 @@ function generateIcons(cwd: string, outDir: string, cfg: AppwrapConfig): void {
     console.warn('⚠ No app icon source found (manifest icons or config `icon`) — keeping template icons');
     return;
   }
+  // Icon rasterization uses `sips`, which is macOS-only. On Linux/CI (e.g. a GitHub Actions Android
+  // build) it's absent — skip gracefully and keep the template icons rather than throwing and failing
+  // the whole init/build. Regenerate real icons on macOS for store builds.
+  try {
+    execFileSync('which', ['sips'], { stdio: 'ignore' });
+  } catch {
+    console.warn('⚠ `sips` unavailable (non-macOS host) — keeping template icons; regenerate on macOS for store builds');
+    return;
+  }
   const probe = (prop: string) =>
     parseInt(execFileSync('sips', ['-g', prop, source]).toString().match(/(\d+)\s*$/)?.[1] ?? '0', 10);
   const w = probe('pixelWidth');
@@ -868,16 +887,36 @@ function generateIcons(cwd: string, outDir: string, cfg: AppwrapConfig): void {
 
 /** Tint the iOS launch screen to the configured background color. */
 function stampLaunchScreen(outDir: string, cfg: AppwrapConfig): void {
-  const storyboard = join(outDir, 'App_Resources/iOS/LaunchScreen.storyboard');
-  if (!existsSync(storyboard) || !cfg.backgroundColor) return;
+  if (!cfg.backgroundColor) return;
   const hex = cfg.backgroundColor.replace('#', '');
   if (!/^[0-9a-fA-F]{6}$/.test(hex)) return;
-  const ch = (i: number) => (parseInt(hex.slice(i, i + 2), 16) / 255).toFixed(4);
-  const src = readFileSync(storyboard, 'utf8').replace(
-    /<color key="backgroundColor"[^/]*\/>/g,
-    `<color key="backgroundColor" red="${ch(0)}" green="${ch(2)}" blue="${ch(4)}" alpha="1" colorSpace="custom" customColorSpace="sRGB"/>`
-  );
-  writeFileSync(storyboard, src);
+
+  // iOS: tint the storyboard launch background.
+  const storyboard = join(outDir, 'App_Resources/iOS/LaunchScreen.storyboard');
+  if (existsSync(storyboard)) {
+    const ch = (i: number) => (parseInt(hex.slice(i, i + 2), 16) / 255).toFixed(4);
+    const src = readFileSync(storyboard, 'utf8').replace(
+      /<color key="backgroundColor"[^/]*\/>/g,
+      `<color key="backgroundColor" red="${ch(0)}" green="${ch(2)}" blue="${ch(4)}" alpha="1" colorSpace="custom" customColorSpace="sRGB"/>`
+    );
+    writeFileSync(storyboard, src);
+  }
+
+  // Android: replace the default NativeScript splash (background bitmap + NS logo) with a solid fill
+  // of the app's backgroundColor — parity with the iOS solid launch screen, and no NS branding flash.
+  const splash = join(outDir, 'App_Resources/Android/src/main/res/drawable-nodpi/splash_screen.xml');
+  if (existsSync(splash)) {
+    writeFileSync(splash,
+      `<?xml version="1.0" encoding="utf-8"?>\n` +
+      `<layer-list xmlns:android="http://schemas.android.com/apk/res/android" android:gravity="fill">\n` +
+      `    <item>\n` +
+      `        <shape android:shape="rectangle">\n` +
+      `            <solid android:color="#${hex.toUpperCase()}" />\n` +
+      `        </shape>\n` +
+      `    </item>\n` +
+      `</layer-list>\n`
+    );
+  }
 }
 
 const VERSION_FILE = '.appwrap-version';
@@ -1201,11 +1240,33 @@ function runNs(outDir: string, args: string[]): void {
   execFileSync('ns', args, { cwd: outDir, stdio: 'inherit' });
 }
 
+/** Read the loader currently stamped into the generated shell (app/shell/config.ts). Used to
+ * preserve an ACTIVE `dev` loader across `run` (see run()'s footgun note). Returns null if the
+ * generated config is absent/unreadable — the caller then falls back to the appwrap config. */
+function readStampedLoader(outDir: string): { loader: string; serverUrl: string; debug: boolean } | null {
+  try {
+    const src = readFileSync(join(outDir, 'app/shell/config.ts'), 'utf8');
+    const loader = src.match(/loader:\s*"([^"]*)"/)?.[1];
+    if (!loader) return null;
+    return {
+      loader,
+      serverUrl: src.match(/serverUrl:\s*"([^"]*)"/)?.[1] ?? '',
+      debug: /debug:\s*true/.test(src),
+    };
+  } catch {
+    return null;
+  }
+}
+
 /** `appwrap run <ios|android> [--device <id|name>]` — compile + boot the wrapper in a
  * simulator/emulator (or named device) with live reload: the appwrap-managed replacement for raw
- * `ns run`, driven from the PWA project root with deps auto-installed. Like `ns run`, it reflects
- * whatever loader is currently stamped (`init`/`sync`/`dev`/`build` own stamping) and does NOT
- * re-stamp — so it won't clobber a `dev` loader. */
+ * `ns run`, driven from the PWA project root with deps auto-installed.
+ *
+ * Refreshes the generated wrapper from the source template + PWA first (same regenerateCore as
+ * `sync`/`build`) so framework `runtime/` edits and PWA rebuilds actually reach the device — `run`
+ * used to skip this and silently ship the STALE generated shell (the run-without-sync footgun). An
+ * ACTIVE `dev` loader (loader:'server', stamped by `appwrap dev`) is preserved so dev→run
+ * live-reload isn't clobbered back to the bundled loader. */
 async function run(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
   const platform = positionals[0];
   if (platform !== 'ios' && platform !== 'android') {
@@ -1217,6 +1278,17 @@ async function run(cwd: string, flags: Record<string, string>, positionals: stri
     console.error(`✖ Wrapper not found at ${outDir} — run \`appwrap init\` first`);
     process.exit(1);
   }
+  const cfg = await loadConfig(cwd, flags);
+  const stamped = readStampedLoader(outDir);
+  const devActive = stamped?.loader === 'server';
+  // Preserve a live dev loader; otherwise regenerate from the appwrap config (bundled loader).
+  const effectiveCfg = devActive
+    ? { ...cfg, loader: 'server' as const, serverUrl: stamped!.serverUrl, debug: stamped!.debug }
+    : cfg;
+  regenerateCore(cwd, outDir, effectiveCfg, { flags });
+  applyOverrides(cwd, outDir, effectiveCfg); // overrides win last — same order as sync (else run wipes them)
+  stampVersionManifest(outDir, effectiveCfg); // keep the managed-marker / provenance current
+  console.log(devActive ? `✓ Refreshed wrapper (preserved dev loader → ${stamped!.serverUrl})` : '✓ Refreshed wrapper from template + PWA');
   runNs(outDir, ['run', platform, ...(flags.device ? ['--device', flags.device] : [])]);
 }
 

package/src/config.ts

@@ -200,3 +200,24 @@ export interface AppwrapConfig {
 export function defineConfig(config: AppwrapConfig): AppwrapConfig {
   return config;
 }
+
+/**
+ * Top-level keys appwrap recognizes — KEEP IN SYNC with `AppwrapConfig` above (top-level only; nested
+ * keys like `push.ios` are not listed). Drives `unknownConfigKeys`, which warns (never fails) on stray
+ * keys at load time. The motivating bug: a config written for a NEWER appwrap silently no-ops its
+ * unknown keys on an OLDER installed version (e.g. `targetedDevices` before 0.39 → a universal build
+ * with no error, then an App Store rejection). A loud warning turns that silent no-op into a signal.
+ */
+export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
+  'appBoundDomains', 'backendOrigin', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'debug',
+  'debugLog', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'loader', 'modules', 'name',
+  'neutralizeServiceWorker', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
+  'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'statusBarStyle',
+  'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',
+  'usesNonExemptEncryption', 'vendorPaths', 'version',
+]);
+
+/** Config keys appwrap doesn't recognize (pure — the caller decides how to surface them). */
+export function unknownConfigKeys(cfg: Record<string, unknown>): string[] {
+  return Object.keys(cfg).filter((k) => !KNOWN_CONFIG_KEYS.has(k));
+}