@livx.cc/appwrap 0.61.12 → 0.61.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.61.12",
+  "version": "0.61.14",
   "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/main-page.ts

@@ -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,70 @@ 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 {
+/**
+ * `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.
+ *
+ * PIXEL-IDENTICAL BY CONSTRUCTION: the overlay IS the OS launch splash, re-instantiated natively and
+ * pinned full-bleed over the whole window — iOS instantiates LaunchScreen.storyboard itself, Android
+ * paints the window-background drawable (splash_screen.xml). An NS-layout copy sat inside the safe
+ * area, so its logo landed lower than the storyboard's and visibly jumped at the hand-off.
+ */
+function wireSplashHold(page: Page): (why: string) => void {
+  const noop = () => {};
+  const remove = SHELL_CONFIG.splash?.hold ? mountNativeSplash(page) : null;
+  if (!remove) {
+    bridge.register('ui.splash.hide', noop); // a page may always call it; nothing is held here
+    return noop;
+  }
+  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`);
+    remove();
+  };
+  const timer = setTimeout(() => hide('timeout'), SHELL_CONFIG.splash.timeoutMs);
+  bridge.register('ui.splash.hide', () => { hide('page'); });
+  return hide;
+}
+
+/** Put the OS launch splash back on screen as a native full-window view; returns its fade-out+remove. */
+function mountNativeSplash(page: Page): (() => void) | null {
+  const FADE_MS = 180;
+  try {
+    if (isIOS) {
+      const host = (page.viewController as UIViewController | undefined)?.view;
+      const vc = UIStoryboard.storyboardWithNameBundle('LaunchScreen', null).instantiateInitialViewController();
+      if (!host || !vc) return null;
+      const v = vc.view;
+      v.frame = UIScreen.mainScreen.bounds;
+      v.autoresizingMask = UIViewAutoresizing.FlexibleWidth | UIViewAutoresizing.FlexibleHeight;
+      host.addSubview(v);
+      return () => UIView.animateWithDurationAnimationsCompletion(FADE_MS / 1000, () => { v.alpha = 0; }, () => v.removeFromSuperview());
+    }
+    const act = (Application.android.foregroundActivity || Application.android.startActivity) as android.app.Activity | null;
+    const decor = act?.getWindow()?.getDecorView() as android.view.ViewGroup | undefined;
+    if (!act || !decor) return null;
+    const v = new android.view.View(act);
+    const resId = act.getResources().getIdentifier('splash_screen', 'drawable', act.getPackageName());
+    if (resId) v.setBackground(act.getResources().getDrawable(resId, act.getTheme()));
+    else v.setBackgroundColor(android.graphics.Color.parseColor(SHELL_CONFIG.backgroundColor));
+    v.setClickable(true); // swallow touches while the page boots, like the OS splash
+    decor.addView(v, new android.view.ViewGroup.LayoutParams(-1, -1));
+    return () => v.animate().alpha(0).setDuration(FADE_MS).withEndAction(new java.lang.Runnable({ run: () => decor.removeView(v) })).start();
+  } catch (e) {
+    appwrapNativeLog(`[native:splash] overlay unavailable: ${e}`);
+    return null;
+  }
+}
+
+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');
@@ -187,6 +251,7 @@ function wireLoadFallback(page: Page, webView: CustomWebView): void {
 
   let retryTimer: ReturnType<typeof setTimeout> | null = null;
   let backoffMs = 3000;
+  let triedCache = false; // iOS: one cache-only replay per failure run (see below)
   const clearTimer = () => { if (retryTimer) { clearTimeout(retryTimer); retryTimer = null; } };
   const retry = () => {
     clearTimer();
@@ -202,6 +267,7 @@ function wireLoadFallback(page: Page, webView: CustomWebView): void {
     const err = String(args.error ?? '');
     if (!err) {
       // successful load → hide + reset (idempotent; covers the auto-retry that finally lands)
+      triedCache = false;
       clearTimer();
       backoffMs = 3000;
       if (fallback.visibility !== 'collapse') {
@@ -211,7 +277,22 @@ function wireLoadFallback(page: Page, webView: CustomWebView): void {
       return;
     }
     if (/cancel/i.test(err)) return; // NSURLErrorCancelled: navigation superseded, not a failure
+    // iOS OFFLINE LAUNCH: WKWebView gets no service worker without app-bound domains, but its HTTP
+    // cache already holds the last index.html (no-cache = revalidate, still stored) and the immutable
+    // hashed assets. Before showing the error, replay the launch URL cache-only; online launches never
+    // take this path, so they still revalidate and get the newest deploy (OTA).
+    if (isIOS && !triedCache) {
+      triedCache = true;
+      const wk = webView.ios as WKWebView | null;
+      if (wk) {
+        appwrapNativeLog(`[native:fallback] load failed (${err}) — replaying from the HTTP cache`);
+        wk.loadRequest(NSURLRequest.requestWithURLCachePolicyTimeoutInterval(
+          NSURL.URLWithString(effectiveServerUrl()), NSURLRequestCachePolicy.ReturnCacheDataDontLoad, 10));
+        return;
+      }
+    }
     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/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',
 ]);