@livx.cc/appwrap 0.61.11 → 0.61.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.61.11",
+  "version": "0.61.13",
   "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_Resources/iOS/Podfile

@@ -1,13 +1,16 @@
 # Silence CocoaPods' "no platform specified" warning; matches the post_install target below.
-platform :ios, '13.0'
+platform :ios, '15.0'
 
 # Bump every pod's deployment target. Xcode 15+ removed `libarclite`, so pods that
 # declare an old IPHONEOS_DEPLOYMENT_TARGET (e.g. SAMKeychain via @nativescript/
 # secure-storage) fail device builds with "SDK does not contain 'libarclite'".
+# 15.0 is the FLOOR, not a preference: Xcode 27 rejects any IPHONEOS_DEPLOYMENT_TARGET under 15.0
+# as a hard error ("supported deployment target versions is 15.0 to 27.0.x"), so 13.0 failed every
+# device build there while older Xcodes still accepted it. An app's own target may sit higher.
 post_install do |installer|
   installer.pods_project.targets.each do |target|
     target.build_configurations.each do |config|
-      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '13.0'
+      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
     end
   end
 end

package/runtime/app/main-page.ts

@@ -1,4 +1,4 @@
-import { Application, AndroidApplication, Button, EventData, LoadEventData, Page, StackLayout, WebView, isAndroid, isIOS, knownFolders, path } from '@nativescript/core';
+import { Application, AndroidApplication, Button, EventData, GridLayout, Image, LoadEventData, Page, StackLayout, WebView, isAndroid, isIOS, knownFolders, path } from '@nativescript/core';
 import { bridge } from './shell/bridge';
 import { effectiveServerUrl } from './shell/server-url';
 import { registerHandlers } from './shell/handlers';
@@ -94,6 +94,7 @@ export function onPageLoaded(args: EventData): void {
 
   if (initialized) return;
   initialized = true;
+  const hideSplash = wireSplashHold(page); // first: the overlay must be up before the first frame
 
   registerHandlers();
   registerExtendedHandlers();
@@ -126,7 +127,7 @@ export function onPageLoaded(args: EventData): void {
   // if a future surface orphans a window with no dismiss callback — gate it on a "surface presented" flag.
   void armNativeSurfaceRecovery; // referenced to keep the helper (still callable if a scoped need arises)
   if (isAndroid) wireAndroidSafeArea(webView); // experimental edge-to-edge (no-op unless config on)
-  wireLoadFallback(page, webView); // loader:'server' failure → branded retry view (no white screen)
+  wireLoadFallback(page, webView, hideSplash); // loader:'server' failure → branded retry view (no white screen)
   startEventForwarding();
   loadBundle(webView);
   // Env indicator banner: shown in the bottom safe area on relaunch when a non-default env override is
@@ -179,7 +180,49 @@ export function onPageLoaded(args: EventData): void {
  * NOTE: web-process termination has no NS seam in a prod build (the didTerminate forwarder lives on
  * the debug-only DevCertNavDelegate) — out of scope here.
  */
-function wireLoadFallback(page: Page, webView: CustomWebView): void {
+/** iOS LaunchScreen.Center is stamped at 220pt; Android's splash canvas is 288dp (cli.ts
+ * ANDROID_SPLASH_DP). The overlay draws the SAME image at the SAME size so the hand-off from the OS
+ * launch screen is invisible. */
+const SPLASH_LOGO_SIZE = isIOS ? 220 : 288;
+
+/**
+ * `splashHold`: keep the launch splash up until the PAGE has painted. Without it the OS splash drops
+ * the moment this native page draws, and a loader:'server' WebView shows its blank canvas for the
+ * whole index.html + bundle download. The page ends the hold with `kit.invoke('ui.splash.hide')`;
+ * a safety timeout and the load-failure view end it too, so a page that never calls it (or an old
+ * web build behind a new shell) costs at most `timeoutMs`. Returns the idempotent hide.
+ */
+function wireSplashHold(page: Page): (why: string) => void {
+  const noop = () => {};
+  const overlay = SHELL_CONFIG.splash?.hold ? page.getViewById<GridLayout>('splashOverlay') : null;
+  if (!overlay) {
+    bridge.register('ui.splash.hide', noop); // a page may always call it; nothing is held here
+    return noop;
+  }
+  const logo = page.getViewById<Image>('splashLogo');
+  if (SHELL_CONFIG.splash.logo && logo) {
+    logo.src = isIOS ? 'res://LaunchScreen.Center' : 'res://splash_logo';
+    logo.width = SPLASH_LOGO_SIZE;
+    logo.height = SPLASH_LOGO_SIZE;
+  }
+  overlay.visibility = 'visible';
+  const shownAt = Date.now();
+  let done = false;
+  const hide = (why: string): void => {
+    if (done) return;
+    done = true;
+    clearTimeout(timer);
+    appwrapNativeLog(`[native:splash] hide (${why}) after ${Date.now() - shownAt}ms`);
+    overlay.animate({ opacity: 0, duration: 180 })
+      .catch(() => { /* view torn down mid-fade — collapsing below is all that matters */ })
+      .then(() => { overlay.visibility = 'collapse'; });
+  };
+  const timer = setTimeout(() => hide('timeout'), SHELL_CONFIG.splash.timeoutMs);
+  bridge.register('ui.splash.hide', () => { hide('page'); });
+  return hide;
+}
+
+function wireLoadFallback(page: Page, webView: CustomWebView, hideSplash: (why: string) => void = () => {}): void {
   if (SHELL_CONFIG.loader !== 'server') return; // bundled loaders can't fail on network
   const fallback = page.getViewById<StackLayout>('loadFallback');
   const retryBtn = page.getViewById<Button>('loadRetryBtn');
@@ -212,6 +255,7 @@ function wireLoadFallback(page: Page, webView: CustomWebView): void {
     }
     if (/cancel/i.test(err)) return; // NSURLErrorCancelled: navigation superseded, not a failure
     appwrapNativeLog(`[native:fallback] load failed: ${err}`);
+    hideSplash('load-failed');
     fallback.visibility = 'visible';
     if (!retryTimer) {
       retryTimer = setTimeout(() => { backoffMs = Math.min(backoffMs * 2, 30_000); retry(); }, backoffMs);

package/runtime/app/main-page.xml

@@ -6,6 +6,11 @@
   backgroundColor="{{ backgroundColor }}">
   <GridLayout rows="*">
     <shell:CustomWebView id="webview" row="0" />
+    <!-- splashHold: the launch splash (bg + splashIcon) held over the WebView until the page reports
+         its first paint (`ui.splash.hide`) — see wireSplashHold in main-page.ts. -->
+    <GridLayout id="splashOverlay" row="0" visibility="collapse" backgroundColor="{{ backgroundColor }}" iosOverflowSafeArea="true">
+      <Image id="splashLogo" stretch="aspectFit" horizontalAlignment="center" verticalAlignment="center" />
+    </GridLayout>
     <!-- loader:'server' load-failure fallback (App Review 2.1a): shown by main-page.ts when the
          server navigation fails (offline / server down) so the reviewer never sees a white screen. -->
     <StackLayout id="loadFallback" row="0" visibility="collapse" backgroundColor="#ffffff" verticalAlignment="center" padding="32">

package/runtime/app/shell/config.ts

@@ -73,6 +73,10 @@ export const SHELL_CONFIG = {
    * Lifting extra makes the page cover that strip (the keyboard hides the thin bottom row of content).
    * Default 82. Set 0 for NO extra lift (input sits flush at the reported height; the strip may show). */
   iosKeyboardExtraLift: 82,
+  /** `splashHold` config: hold the launch splash over the WebView until the page calls
+   * `ui.splash.hide` (or `timeoutMs` passes / the load fails). `logo` = a `splashIcon` was stamped
+   * (iOS `LaunchScreen.Center` imageset, Android `splash_logo` drawable). See wireSplashHold. */
+  splash: { hold: false, timeoutMs: 4000, logo: false } as { hold: boolean; timeoutMs: number; logo: boolean },
   /** Runtime env-switcher (loader:'server'). `enabled` is the resolved kill-switch (config block
    * present AND not `enabled:false`); when false the menu action, banner, and boot override are all
    * inert. `envs` = declared presets; `allowPattern` = anchored regex gating "Other" (default-deny

package/src/cli.ts

@@ -974,6 +974,12 @@ export function stampShellConfig(outDir: string, cfg: AppwrapConfig): void {
     envs: (es?.envs ?? []).map((e) => ({ label: String(e.label), url: String(e.url) })),
     allowPattern: es?.allowPattern ?? '',
   };
+  const hold = cfg.splashHold;
+  const splash = {
+    hold: !!hold,
+    timeoutMs: (typeof hold === 'object' && hold.timeoutMs) || 4000,
+    logo: !!cfg.splashIcon,
+  };
   const content = `/**
  * Shell config — stamped by \`appwrap init\`/\`sync\` from the appwrap config. Do not edit.
  */
@@ -1002,6 +1008,7 @@ export const SHELL_CONFIG = {
   pushAndroid: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.android !== false)},
   pushRegistrationUrl: ${JSON.stringify(cfg.push?.registrationUrl ?? '')},
   iosKeyboardExtraLift: ${JSON.stringify(cfg.iosKeyboardExtraLift ?? 82)},
+  splash: ${JSON.stringify(splash)} as { hold: boolean; timeoutMs: number; logo: boolean },
   envSwitcher: ${JSON.stringify(envSwitcher)} as { enabled: boolean; envs: { label: string; url: string }[]; allowPattern: string },
   webCaps: ${JSON.stringify(webCaps)} as { camera: boolean; microphone: boolean; geolocation: boolean },
 };
@@ -1895,6 +1902,14 @@ function generateIcons(cwd: string, outDir: string, cfg: AppwrapConfig): void {
         ras.resize(splashSrc, Math.round(220 * parseFloat(img.scale)), join(centerSet, img.filename));
       }
     }
+    // Android: the same logo on the 288dp splash canvas (xxxhdpi-sharp; nodpi so the layer-list's
+    // explicit dp size does the scaling), then re-stamp the splash XML + Android 12+ theme to use it.
+    const droidRes = join(outDir, 'App_Resources/Android/src/main/res');
+    const hex = (cfg.backgroundColor ?? '#ffffff').replace('#', '');
+    if (existsSync(splashSrc) && existsSync(droidRes) && /^[0-9a-fA-F]{6}$/.test(hex)) {
+      ras.resize(splashSrc, ANDROID_SPLASH_DP * 4, join(droidRes, 'drawable-nodpi/splash_logo.png'));
+      writeAndroidSplash(outDir, hex, true);
+    }
   }
 
   const ANDROID_DENSITIES: Record<string, number> = { mdpi: 48, hdpi: 72, xhdpi: 96, xxhdpi: 144, xxxhdpi: 192 };
@@ -1967,19 +1982,47 @@ function stampLaunchScreen(outDir: string, cfg: AppwrapConfig): void {
 
   // 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`
-    );
-  }
+  writeAndroidSplash(outDir, hex, false);
+}
+
+/** Android launch splash, both phases, on one `ANDROID_SPLASH_DP` canvas so the logo never jumps:
+ * the activity window background (`splash_screen.xml`, every API level) and — with a logo — the
+ * Android 12+ system SplashScreen (`values-v31` LaunchScreenTheme), whose icon is drawn at 288dp when
+ * it has no icon background. The shell's splash-hold overlay (main-page.ts) uses the same size. */
+const ANDROID_SPLASH_DP = 288;
+function writeAndroidSplash(outDir: string, hex: string, logo: boolean): void {
+  const res = join(outDir, 'App_Resources/Android/src/main/res');
+  const splash = join(res, 'drawable-nodpi/splash_screen.xml');
+  if (!existsSync(splash)) return;
+  const color = `#${hex.toUpperCase()}`;
+  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="${color}" />\n` +
+    `        </shape>\n` +
+    `    </item>\n` +
+    (logo
+      ? `    <item android:width="${ANDROID_SPLASH_DP}dp" android:height="${ANDROID_SPLASH_DP}dp" android:gravity="center">\n` +
+        `        <bitmap android:src="@drawable/splash_logo" android:gravity="fill" />\n` +
+        `    </item>\n`
+      : '') +
+    `</layer-list>\n`
+  );
+  const v31 = join(res, 'values-v31/styles.xml');
+  if (!logo) { if (existsSync(v31) && readFileSync(v31, 'utf8').includes('appwrap:splash')) rmSync(v31); return; }
+  mkdirSync(dirname(v31), { recursive: true });
+  writeFileSync(v31,
+    `<?xml version="1.0" encoding="utf-8"?>\n` +
+    `<!-- appwrap:splash — generated from splashIcon/backgroundColor; regenerated every sync. -->\n` +
+    `<resources xmlns:android="http://schemas.android.com/apk/res/android">\n` +
+    `    <style name="LaunchScreenTheme" parent="LaunchScreenThemeBase">\n` +
+    `        <item name="android:windowSplashScreenBackground">${color}</item>\n` +
+    `        <item name="android:windowSplashScreenAnimatedIcon">@drawable/splash_logo</item>\n` +
+    `    </style>\n` +
+    `</resources>\n`
+  );
 }
 
 const VERSION_FILE = '.appwrap-version';

package/src/config.ts

@@ -169,10 +169,18 @@ export interface AppwrapConfig {
   oauthRedirectSchemes?: string[];
   /** App icon source (≥512px square png). Defaults to the largest icon in the PWA manifest. */
   icon?: string;
-  /** Optional centered logo for the iOS launch splash — a TRANSPARENT-background png (a wordmark or
-   * glyph, NOT the app icon, whose opaque background would show as a box on the splash). When absent
-   * the splash is a clean solid `backgroundColor` fill with no logo. */
+  /** Optional centered logo for the launch splash (iOS LaunchScreen + Android splash, incl. the
+   * Android 12+ system splash) — a TRANSPARENT-background square png (a wordmark or glyph, NOT the
+   * app icon, whose opaque background would show as a box). Rendered on a 220pt (iOS) / 288dp
+   * (Android) canvas, so bake the glyph's padding into the png (~45% of the canvas keeps a square
+   * inside Android 12's 192dp circle mask). When absent the splash is a solid `backgroundColor`. */
   splashIcon?: string;
+  /** Hold the launch splash (backgroundColor + `splashIcon`) OVER the WebView until the page says it
+   * has painted — `kit.invoke('ui.splash.hide')` — instead of dropping it the moment the native page
+   * draws (which shows the WebView's blank canvas while a loader:'server' page downloads). Safety
+   * net: it hides anyway after `timeoutMs` (default 4000) or when the load-failure view shows.
+   * `true` = defaults. Off by default: a page that never calls hide would sit behind the splash. */
+  splashHold?: boolean | { timeoutMs?: number };
   /** Loader: 'app' (default — app:// scheme, ES modules OK), 'file' (debug fallback), or 'server'
    * (load `serverUrl` live — dev HMR over LAN or a deployed URL). `appwrap dev` sets this. */
   loader?: 'app' | 'file' | 'server';
@@ -401,7 +409,7 @@ export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
   'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'modulePacks', 'name',
   'androidLockTextZoom', 'envSwitcher', 'iosEntitlements', 'iosInfoPlist', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
   'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'shareTarget', 'signing', 'signingProfiles', 'statusBarStyle', 'store',
-  'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',
+  'splashHold', 'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',
   'usesNonExemptEncryption', 'vendorPaths', 'version',
 ]);