@livx.cc/appwrap 0.52.0 → 0.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "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/shell/billing-offer.ts

@@ -0,0 +1,54 @@
+// Pure Play-Billing offer selection — NO NativeScript/native deps, so it is unit-testable in
+// isolation from com.android.billingclient.* objects. handlers-billing.ts adapts native
+// SubscriptionOfferDetails into these plain shapes and delegates the CHOICE here.
+//
+// WHY this exists (money/product-critical): getSubscriptionOfferDetails() returns EVERY offer the
+// user is eligible for, in NO guaranteed order. A trial-eligible (first-time) user's list carries
+// BOTH the base-plan offer (offerId==null, a single paid phase) AND a separate free-trial offer
+// (tag "freetrial", two phases: first priceAmountMicros==0, then the base price). A lapsed /
+// ineligible user gets ONLY the base-plan offer. Blindly taking offers.get(0) can drop the
+// MANDATORY free trial. We must pick the trial offer WHEN PRESENT, else the base plan.
+
+/** One pricing phase of an offer (only the fields the selection/pricing logic needs). */
+export interface OfferPhase {
+  /** Micros of `currency`; 0 marks a free-trial phase. */
+  priceAmountMicros: number;
+  /** ISO-8601 billing period, e.g. "P1W", "P1M". */
+  billingPeriod?: string;
+}
+
+/** A single subscription offer, flattened from Play's SubscriptionOfferDetails. */
+export interface OfferCandidate {
+  /** null/"" for the base-plan offer; a non-empty id for a promotional offer (trial). */
+  offerId: string | null;
+  phases: OfferPhase[];
+}
+
+/** True when the offer contains a zero-price (free-trial) phase. */
+export function hasFreeTrialPhase(offer: OfferCandidate): boolean {
+  return offer.phases.some((p) => p.priceAmountMicros === 0);
+}
+
+/**
+ * Select the offer to purchase / price from. Prefers the free-trial offer (a zero-price phase) when
+ * present, so a trial-eligible user actually gets the trial; otherwise falls back to the base-plan
+ * offer (offerId==null), else the first offer. Returns null for an empty list.
+ */
+export function selectSubscriptionOffer<T extends OfferCandidate>(offers: readonly T[]): T | null {
+  if (!offers || offers.length === 0) return null;
+  const trial = offers.find(hasFreeTrialPhase);
+  if (trial) return trial;
+  const base = offers.find((o) => o.offerId == null || o.offerId === '');
+  return base ?? offers[0];
+}
+
+/** The recurring paid phase to display (first phase with a price > 0), or the last phase as fallback. */
+export function recurringPhase(offer: OfferCandidate): OfferPhase | undefined {
+  const paid = offer.phases.find((p) => p.priceAmountMicros > 0);
+  return paid ?? offer.phases[offer.phases.length - 1];
+}
+
+/** The intro/free-trial phase (first zero-price phase), if any. */
+export function introPhase(offer: OfferCandidate): OfferPhase | undefined {
+  return offer.phases.find((p) => p.priceAmountMicros === 0);
+}

package/runtime/app/shell/capabilities.manifest.ts

@@ -150,10 +150,14 @@ export const MODULES: ModuleManifest[] = [
   },
   {
     name: 'billing', group: 'billing',
-    capabilities: { billing: { ios: true, android: false } },
-    // iOS-only Swift shim (AppwrapManageSubscriptions.swift) bridging StoreKit 2's Swift-async
+    capabilities: { billing: { ios: true, android: true } },
+    // iOS: Swift shim (AppwrapManageSubscriptions.swift) bridging StoreKit 2's Swift-async
     // showManageSubscriptions(in:) to an @objc completion the ObjC bridge can call. Compiled into
     // the app target only when `billing` is active (NS auto-compiles App_Resources/iOS/src/*.swift).
+    // Android: Play Billing Library v7 (handlers-billing.ts registerAndroidBilling). The BILLING
+    // permission is auto-merged by the library's own manifest, so no android.permissions entry —
+    // only the gradle dep is needed, and it lands ONLY when `billing` is active (strippable weight).
+    android: { gradleDeps: ['com.android.billingclient:billing:7.1.1'] },
     nativeSrc: 'billing',
   },
 

package/runtime/app/shell/custom-webview.android.ts

@@ -94,6 +94,17 @@ export class CustomWebView extends WebView {
   /** Set by the bridge before load; receives raw envelope JSON. */
   onAppwrapMessage: ((json: string) => void) | null = null;
 
+  /**
+   * A TLS handshake this view REFUSED (onReceivedSslError → handler.cancel()), pending attribution to the
+   * navigation it killed. Cancelling an SSL error does NOT route through onReceivedError — Chromium instead
+   * swaps in its own error page and reports it via onPageFinished with the ORIGINAL url, which would read as
+   * a SUCCESSFUL load (see `pageFinished`). Recorded here so that onPageFinished can tell the two apart.
+   * Host-scoped (a cert is per-host, so a same-host sub-resource can't fail while the main frame succeeds),
+   * and cleared on any COMMITTED navigation (`pageStarted`) — a refused one never commits, so the record
+   * always outlives the failure it describes and never leaks onto the next page.
+   */
+  pendingSslError: { host: string; reason: string } | null = null;
+
   // STRONG JS references to the native clients. Chromium holds the Java WebViewClient /
   // WebChromeClient, but NativeScript's mark-and-sweep does NOT treat that native hold as a
   // GC root — so without a JS-side reference the JS peer gets collected under memory pressure
@@ -416,6 +427,18 @@ function createAssetServingClient(): android.webkit.WebViewClient {
   };
 
   const pageStarted = (view: android.webkit.WebView): void => {
+      // A navigation COMMITTED, so any earlier TLS refusal is answered for — drop it (see pendingSslError).
+      // A refused nav never reaches here (device-verified on WebView 138: no onPageStarted on an SSL cancel),
+      // so this cannot clear the record before `pageFinished` reads it.
+      //
+      // ⚠️ That is UNDOCUMENTED Chromium behaviour, not a contract. If a future WebView fires onPageStarted
+      // for its own error-page commit (i.e. AFTER onReceivedSslError), this clears the record and the
+      // swallowed-as-success bug returns SILENTLY. If that regresses, look here first.
+      // Redirects are safe for a stronger reason than the above: on http://x → 302 → https://y(bad),
+      // onPageStarted(x) fires BEFORE the handshake, so it clears an OLDER record and the refusal is
+      // recorded after — clear-before-write ordering holds regardless.
+      const owner = CustomWebView.forNative(view);
+      if (owner) owner.pendingSslError = null;
       // Fallback injection — no-op when the document-start scripts already ran
       view.evaluateJavascript(buildBootstrapJs(), null as unknown as android.webkit.ValueCallback<string>);
   };
@@ -449,9 +472,33 @@ function createAssetServingClient(): android.webkit.WebViewClient {
   // firing on a SUCCESSFUL load. A one-shot `loadFinished` listener (env-switcher's reloadToEffective)
   // would then never unhook on success and would leak onto the NEXT navigation, blaming a later error on
   // an earlier switch (and naming the earlier switch's host). Both halves or neither.
+  //
+  // …EXCEPT this callback is ALSO how Chromium reports its OWN error page after a REFUSED TLS handshake
+  // (device-verified sequence: onReceivedSslError → handler.cancel() → onPageFinished with the original
+  // url, and NO onReceivedError). Forwarding that as a success is what silently swallowed a cert failure
+  // into a blank page — and it unhooked the env-switcher's one-shot listener too, so the failure could
+  // never be reported at all. Attribute it via the recorded refusal instead (see pendingSslError).
   const pageFinished = (view: android.webkit.WebView, url: string): void => {
+      const owner = CustomWebView.forNative(view);
+      const finishedUrl = String(url ?? '');
+      const ssl = owner?.pendingSslError;
+      if (ssl && ssl.host === hostOf(finishedUrl)) {
+        owner!.pendingSslError = null;
+        (owner as any)?._onLoadFinished(finishedUrl, ssl.reason);
+        return;
+      }
       // Mirrors NS's own `owner._onLoadFinished(url, undefined)` — absent `error` is what marks success.
-      (CustomWebView.forNative(view) as any)?._onLoadFinished(String(url ?? ''));
+      (owner as any)?._onLoadFinished(finishedUrl);
+  };
+
+  /** Android SslError primary codes → why the cert was rejected (SslError.SSL_* ordinals). */
+  const SSL_REASONS: Record<number, string> = {
+    0: 'the certificate is not valid yet',
+    1: 'the certificate has expired',
+    2: "the certificate's hostname does not match",
+    3: 'the certificate issuer is not trusted',
+    4: 'the certificate date is invalid',
+    5: 'the certificate is invalid',
   };
 
   // DEBUG-ONLY dev-server cert trust (Android parity with the iOS WKNavigationDelegate). `appwrap dev`
@@ -460,7 +507,13 @@ function createAssetServingClient(): android.webkit.WebViewClient {
   // Proceed past it ONLY in a debug build, only in server-loader mode, AND only for the ONE host the
   // build-time host (`SHELL_CONFIG.serverUrl`, NOT the switchable override) — never blanket-trust every host. Production app:// builds
   // never reach this (local assets, no TLS). NEVER active in a store build (SHELL_CONFIG.debug false).
+  //
+  // NOT trusting it is a LOAD FAILURE, and Chromium reports it through no other callback — so the cancel
+  // path RECORDS the refusal on the owning view for `pageFinished` to raise as `loadFinished(error)`.
+  // Without that the whole cert class is invisible to JS (blank page, no feedback) — the exact incident the
+  // env-switcher's reload feedback exists to name.
   const receivedSslError = (
+    view: android.webkit.WebView,
     handler: android.webkit.SslErrorHandler,
     error: android.net.http.SslError
   ): void => {
@@ -469,14 +522,20 @@ function createAssetServingClient(): android.webkit.WebViewClient {
       // Host WITHOUT port, mirroring the iOS DevCertNavDelegate (a dev server on :3000 and its HMR sub-
       // resources on an alt port share one self-signed cert) — same `hostOf` normalization + port strip.
       const stripPort = (h: string) => h.replace(/:\d+$/, '');
+      const errUrl = String(error?.getUrl?.() ?? '');
       const allowedHost = stripPort(hostOf(SHELL_CONFIG.serverUrl));
-      const errHost = stripPort(hostOf(String(error?.getUrl?.() ?? '')));
+      const errHost = stripPort(hostOf(errUrl));
       if (SHELL_CONFIG.debug && SHELL_CONFIG.loader === 'server' && !!allowedHost && errHost === allowedHost) {
         console.warn('AppWrap: trusting self-signed dev-server cert (debug + host-scoped):', errHost);
         handler.proceed();
-      } else {
-        handler.cancel();
+        return;
       }
+      const why = SSL_REASONS[error?.getPrimaryError?.()] ?? 'the certificate was rejected';
+      const owner = CustomWebView.forNative(view);
+      // Host WITH port here (unlike the trust match above) — this record is matched against the finished
+      // url via the same `hostOf`, so both sides must normalize identically.
+      if (owner) owner.pendingSslError = { host: hostOf(errUrl), reason: `TLS certificate rejected — ${why}.` };
+      handler.cancel();
   };
 
   // TWO literals, selected by loader — NOT one literal with a conditional spread. Both the omission and
@@ -492,8 +551,12 @@ function createAssetServingClient(): android.webkit.WebViewClient {
   //     declared later in the bundle (this cost us a FATAL `LookedUpClassNotFound:
   //     cc.livx.appwrap.AppwrapMessagingService` boot crash that built green). For the same reason don't
   //     hoist the object into a variable and pass `.extend(methods)`: SBG requires an ObjectExpression at
-  //     the call site and silently skips anything else. `appwrap doctor:bindings` (run by the android
-  //     build) now fails the build if a @JavaProxy ever loses its binding again.
+  //     the call site and silently skips anything else.
+  //     ⚠️ NOTHING VERIFIES THIS. An earlier version of this comment claimed `appwrap doctor:bindings`
+  //     (run by the android build) fails the build on a lost @JavaProxy binding — that command does not
+  //     exist and no test asserts the shape. The requirement is hand-maintained. A lost binding means the
+  //     callback silently never fires, which reads as "no TLS errors ever" — a green from something that
+  //     never ran. Either implement the check or keep this warning honest; do not restore the false claim.
   assetClientClass = SHELL_CONFIG.loader === 'server'
     ? (android.webkit.WebViewClient as any).extend({
       shouldOverrideUrlLoading(view: android.webkit.WebView, request: android.webkit.WebResourceRequest | string): boolean {
@@ -505,8 +568,8 @@ function createAssetServingClient(): android.webkit.WebViewClient {
       onPageFinished(view: android.webkit.WebView, url: string): void {
         pageFinished(view, url);
       },
-      onReceivedSslError(_view: android.webkit.WebView, handler: android.webkit.SslErrorHandler, error: android.net.http.SslError): void {
-        receivedSslError(handler, error);
+      onReceivedSslError(view: android.webkit.WebView, handler: android.webkit.SslErrorHandler, error: android.net.http.SslError): void {
+        receivedSslError(view, handler, error);
       },
       onReceivedError(view: android.webkit.WebView, request: android.webkit.WebResourceRequest, error: android.webkit.WebResourceError): void {
         receivedError(view, request, error);
@@ -525,8 +588,8 @@ function createAssetServingClient(): android.webkit.WebViewClient {
       onPageFinished(view: android.webkit.WebView, url: string): void {
         pageFinished(view, url);
       },
-      onReceivedSslError(_view: android.webkit.WebView, handler: android.webkit.SslErrorHandler, error: android.net.http.SslError): void {
-        receivedSslError(handler, error);
+      onReceivedSslError(view: android.webkit.WebView, handler: android.webkit.SslErrorHandler, error: android.net.http.SslError): void {
+        receivedSslError(view, handler, error);
       },
       onReceivedError(view: android.webkit.WebView, request: android.webkit.WebResourceRequest, error: android.webkit.WebResourceError): void {
         receivedError(view, request, error);

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

@@ -1,21 +1,33 @@
-import { Utils, isIOS } from '@nativescript/core';
+import { Application, Utils, isAndroid, isIOS } from '@nativescript/core';
 import { bridge } from './bridge';
 import { appwrapNativeLog } from './native-log';
 import { SHELL_CONFIG } from './config';
+import { selectSubscriptionOffer, type OfferCandidate } from './billing-offer';
 
 // @objc Swift shim (AppwrapManageSubscriptions.swift, billing nativeSrc) — no NS types; bridges
 // StoreKit 2's Swift-async showManageSubscriptions(in:) to a completion the ObjC bridge can call.
 declare const AppwrapManageSubscriptions: { present(completion: (message: string | null) => void): void };
 
+// no NS types for the Play Billing Library (com.android.billingclient.*) — referenced via FFI,
+// lazily, so a non-billing Android build never touches the class (mirrors handlers-reviews.ts).
+declare const com: any;
+
 /**
- * In-app purchases — iOS StoreKit 1 (SKPaymentQueue). StoreKit 2 (Product/Transaction)
- * is Swift-only and unreachable via the ObjC bridge, so we use the delegate-based
- * SK1 API every NativeScript/Cordova IAP plugin uses. The web layer's validator turns
- * the returned app receipt into entitlements (server-of-record). Android billing is a
- * separate handler (Play Billing) and is currently unimplemented (capability 'none').
+ * In-app purchases — ONE bridge contract, two native stores.
+ *
+ * - iOS: StoreKit 1 (SKPaymentQueue). StoreKit 2 (Product/Transaction) is Swift-only and unreachable
+ *   via the ObjC bridge, so we use the delegate-based SK1 API every NativeScript/Cordova IAP plugin
+ *   uses. Returns a base64 app receipt.
+ * - Android: Play Billing Library v7 (BillingClient / queryProductDetailsAsync / launchBillingFlow /
+ *   queryPurchasesAsync). Returns a PurchaseReceipt carrying the Play `purchaseToken` (+ productId +
+ *   packageName) — the exact shape AGF's server-side PlayStoreTokenValidator consumes.
+ *
+ * The web layer's validator (server-of-record) turns the returned receipt into entitlements; both
+ * platforms register the SAME `billing.*` methods with the SAME return shapes.
  */
 
 const PERIOD_UNIT = ['D', 'W', 'M', 'Y']; // SKProductPeriodUnit: Day/Week/Month/Year
+const DISCOUNT_FREE_TRIAL = 2; // SKProductDiscountPaymentMode.freeTrial (0=PayAsYouGo, 1=PayUpFront, 2=FreeTrial)
 const STATE = { Purchasing: 0, Purchased: 1, Failed: 2, Restored: 3, Deferred: 4 };
 const SK_ERR_CANCELLED = 2; // SKErrorPaymentCancelled
 
@@ -35,12 +47,40 @@ function appReceipt(): string {
   return data ? data.base64EncodedStringWithOptions(0 as unknown as NSDataBase64EncodingOptions) : '';
 }
 
+/**
+ * SKProductDiscount → the platform-neutral IntroOffer (parity with the Android mapper's zero-price
+ * phase, same `{ price, displayPrice, period, isFreeTrial }` shape native-kit's `IntroOffer` types).
+ *
+ * ⚠️ ELIGIBILITY CAVEAT: StoreKit 1 exposes `introductoryPrice` on the SKProduct REGARDLESS of whether
+ * this user is eligible — SK1 has no eligibility API (SK2's `isEligibleForIntroOffer` is Swift-async,
+ * unreachable via the ObjC bridge this handler uses). So a user who already consumed a trial in this
+ * group MAY see trial copy they won't actually get; StoreKit's own purchase sheet shows the truth at
+ * checkout. Gating on real eligibility is a follow-up if/when this handler moves to StoreKit 2.
+ */
+function mapIntroOffer(d: SKProductDiscount, locale: NSLocale): {
+  price: number; displayPrice: string; period: string | undefined; isFreeTrial: boolean;
+} {
+  const f = NSNumberFormatter.new();
+  f.numberStyle = 2; // CurrencyStyle
+  f.locale = locale;
+  const sp = d.subscriptionPeriod;
+  // The discount period is ONE cycle; numberOfPeriods is how many cycles it repeats. Total trial
+  // length = numberOfUnits × numberOfPeriods (e.g. 1 week × 1 = P1W).
+  const totalUnits = (sp ? sp.numberOfUnits : 0) * (d.numberOfPeriods || 1);
+  return {
+    price: d.price ? d.price.doubleValue : 0,
+    displayPrice: String(f.stringFromNumber(d.price as unknown as number) ?? ''),
+    period: sp ? `P${totalUnits}${PERIOD_UNIT[sp.unit] ?? 'D'}` : undefined,
+    isFreeTrial: d.paymentMode === DISCOUNT_FREE_TRIAL || (d.price ? d.price.doubleValue : 0) === 0,
+  };
+}
+
 function mapProduct(p: SKProduct) {
   const f = NSNumberFormatter.new();
   f.numberStyle = 2; // CurrencyStyle
   f.locale = p.priceLocale;
   const sp = p.subscriptionPeriod;
-  return {
+  const product: any = {
     id: String(p.productIdentifier),
     title: String(p.localizedTitle ?? ''),
     description: String(p.localizedDescription ?? ''),
@@ -51,6 +91,10 @@ function mapProduct(p: SKProduct) {
     type: sp ? 'autoRenewable' : 'unknown',
     subscriptionPeriod: sp ? `P${sp.numberOfUnits}${PERIOD_UNIT[sp.unit] ?? 'D'}` : undefined,
   };
+  // Surface the intro / free-trial phase so the paywall can show trial terms (see eligibility caveat
+  // on mapIntroOffer). Populated only when StoreKit reports an introductory price for this product.
+  if (p.introductoryPrice) product.introOffer = mapIntroOffer(p.introductoryPrice, p.priceLocale);
+  return product;
 }
 
 function receiptFor(productId: string, transactionId?: string) {
@@ -102,6 +146,8 @@ function ensureIosDelegates(): void {
           }
           case STATE.Failed: {
             queue.finishTransaction(t);
+            // 'DENIED' here means exactly ONE thing: the user dismissed the sheet. Anything the
+            // device refuses outright (payments restricted) is 'UNSUPPORTED' — see billing.purchase.
             const cancelled = t.error && t.error.code === SK_ERR_CANCELLED;
             const e = err(cancelled ? 'DENIED' : 'NATIVE_ERROR', t.error?.localizedDescription ?? 'Purchase failed');
             purchaseWaiters.get(pid)?.reject(e);
@@ -170,8 +216,11 @@ function requestSKProducts(ids: string[]): Promise<SKProduct[]> {
 }
 
 export function registerBillingHandlers(): void {
-  if (!isIOS) return; // Android billing is a separate, not-yet-wired handler
+  if (isIOS) registerIosBilling();
+  else if (isAndroid) registerAndroidBilling();
+}
 
+function registerIosBilling(): void {
   ensureIosDelegates();
   observer = buildObserver();
   SKPaymentQueue.defaultQueue().addTransactionObserver(observer);
@@ -182,7 +231,11 @@ export function registerBillingHandlers(): void {
   });
 
   bridge.register('billing.purchase', async ({ productId }: { productId: string }) => {
-    if (!SKPaymentQueue.canMakePayments()) throw err('DENIED', 'Purchases disabled on this device');
+    // 'UNSUPPORTED', not 'DENIED': this device CANNOT pay at all (Screen Time / parental controls
+    // / MDM restriction) — a standing condition retrying will never clear. 'DENIED' is reserved for
+    // the user dismissing the StoreKit sheet (SKErrorPaymentCancelled, below), which is a per-attempt
+    // choice. Conflating them made consumers silently swallow this as a cancel and strand the user.
+    if (!SKPaymentQueue.canMakePayments()) throw err('UNSUPPORTED', 'Purchases are disabled on this device');
     const sk = (await requestSKProducts([productId]))[0];
     if (!sk) throw err('NATIVE_ERROR', `Unknown product: ${productId}`);
     return new Promise((resolve, reject) => {
@@ -251,3 +304,359 @@ function restoreTransactions(): Promise<any[]> {
     SKPaymentQueue.defaultQueue().restoreCompletedTransactions();
   });
 }
+
+// ─────────────────────────── Android — Google Play Billing ───────────────────────────
+// Play Billing Library v7. All com.android.billingclient.* access is lazy (inside handler bodies)
+// so the shared module loads on iOS and a non-billing Android build never links the class.
+//
+// ACKNOWLEDGEMENT DECISION (money-critical): Play auto-refunds any purchase not acknowledged within
+// 3 days. We acknowledge CLIENT-SIDE here (BillingClient.acknowledgePurchase) immediately after a
+// PURCHASED update and on restore — the simplest correct choice, since this handler owns the
+// BillingClient. The AGF server validator (PlayStoreTokenValidator) MAY also acknowledge via the
+// Play Developer API; a second acknowledge is a harmless no-op on Google's side (idempotent), so
+// the two can coexist. Tradeoff: we ack before the server confirms the grant, so a failed server
+// validation still consumes the purchase (no auto-refund) — acceptable because the server is the
+// source-of-record and re-validates the token on demand. If the server takes over acknowledgement
+// exclusively, delete acknowledgeAndroidPurchase() calls here.
+
+// BillingResponseCode (com.android.billingclient.api.BillingClient.BillingResponseCode).
+const PLAY_RESP = {
+  OK: 0, USER_CANCELED: 1, SERVICE_UNAVAILABLE: 2, BILLING_UNAVAILABLE: 3, ITEM_UNAVAILABLE: 4,
+  DEVELOPER_ERROR: 5, ERROR: 6, ITEM_ALREADY_OWNED: 7, FEATURE_NOT_SUPPORTED: -2, SERVICE_DISCONNECTED: -1,
+};
+const PURCHASE_STATE_PURCHASED = 1; // com.android.billingclient.api.Purchase.PurchaseState.PURCHASED
+
+let billingClient: any = null; // com.android.billingclient.api.BillingClient
+let clientConnecting: Promise<any> | null = null;
+// Purchases arrive asynchronously via the single PurchasesUpdatedListener; route them to the
+// in-flight purchase() caller by product id (module scope, like the iOS purchaseWaiters).
+const androidPurchaseWaiters = new Map<string, { resolve: (r: any) => void; reject: (e: any) => void }>();
+// Single-purchase gate: with only one in-flight purchase, "reject all on error" (which lacks product
+// context) can never reject a DIFFERENT caller's promise. Set synchronously in billing.purchase.
+let androidPurchaseInFlight = false;
+
+function billingApi(): any {
+  return com.android.billingclient.api;
+}
+
+function packageName(): string {
+  return String(Utils.android.getApplicationContext().getPackageName());
+}
+
+/** Java List<T> from a JS array (Play Billing builders take java.util.List, not a marshaled JS array). */
+function toJavaList(items: any[]): any {
+  const list = new java.util.ArrayList();
+  for (const it of items) list.add(it);
+  return list;
+}
+
+/** Map a Play BillingResult to a bridge error, mirroring the iOS cancel/unsupported semantics. */
+function mapBillingErr(result: any): Error {
+  const code = result?.getResponseCode?.();
+  const msg = String(result?.getDebugMessage?.() ?? 'Play Billing error');
+  if (code === PLAY_RESP.USER_CANCELED) return err('DENIED', 'Purchase cancelled');
+  if (code === PLAY_RESP.BILLING_UNAVAILABLE || code === PLAY_RESP.FEATURE_NOT_SUPPORTED)
+    return err('UNSUPPORTED', msg || 'Billing unavailable on this device');
+  return err('NATIVE_ERROR', `${msg} (code ${code})`);
+}
+
+/** Lazily build + connect the BillingClient. Resolves when the service is READY. */
+function ensureAndroidClient(): Promise<any> {
+  if (billingClient && billingClient.isReady()) return Promise.resolve(billingClient);
+  if (clientConnecting) return clientConnecting;
+
+  clientConnecting = new Promise((resolve, reject) => {
+    const api = billingApi();
+    const ctx = Utils.android.getApplicationContext();
+    // v7 requires PendingPurchasesParams; enableOneTimeProducts() is harmless for a subs-only app
+    // (pending purchases are always enabled for subscriptions).
+    const pending = api.PendingPurchasesParams.newBuilder().enableOneTimeProducts().build();
+    const listener = new api.PurchasesUpdatedListener({
+      onPurchasesUpdated(result: any, purchases: any) {
+        onAndroidPurchasesUpdated(result, purchases);
+      },
+    });
+    billingClient = api.BillingClient.newBuilder(ctx)
+      .setListener(listener)
+      .enablePendingPurchases(pending)
+      .build();
+    billingClient.startConnection(new api.BillingClientStateListener({
+      onBillingSetupFinished(result: any) {
+        if (result.getResponseCode() === PLAY_RESP.OK) resolve(billingClient);
+        else reject(mapBillingErr(result));
+      },
+      onBillingServiceDisconnected() {
+        // Force a fresh connection on the next call (Google recommends reconnect-on-demand).
+        clientConnecting = null;
+      },
+    }));
+  }).catch((e) => {
+    clientConnecting = null;
+    throw e;
+  });
+  return clientConnecting;
+}
+
+/** Query one product's ProductDetails (SUBS). */
+function queryAndroidProductDetails(ids: string[]): Promise<any[]> {
+  return ensureAndroidClient().then((client) => new Promise<any[]>((resolve, reject) => {
+    const api = billingApi();
+    const products = ids.map((id) =>
+      api.QueryProductDetailsParams.Product.newBuilder()
+        .setProductId(id)
+        .setProductType(api.BillingClient.ProductType.SUBS)
+        .build());
+    const params = api.QueryProductDetailsParams.newBuilder().setProductList(toJavaList(products)).build();
+    client.queryProductDetailsAsync(params, new api.ProductDetailsResponseListener({
+      onProductDetailsResponse(result: any, list: any) {
+        if (result.getResponseCode() !== PLAY_RESP.OK) return reject(mapBillingErr(result));
+        const out: any[] = [];
+        const n = list ? list.size() : 0;
+        for (let i = 0; i < n; i++) out.push(list.get(i));
+        resolve(out);
+      },
+    }));
+  }));
+}
+
+/** Flatten a ProductDetails' SubscriptionOfferDetails into pure {offerId, phases} + a ref to the
+ *  native offer (so the caller can read its token / native phases after selection). */
+function androidOfferCandidates(pd: any): Array<OfferCandidate & { native: any }> {
+  const offers = pd.getSubscriptionOfferDetails();
+  const out: Array<OfferCandidate & { native: any }> = [];
+  const n = offers ? offers.size() : 0;
+  for (let i = 0; i < n; i++) {
+    const o = offers.get(i);
+    const list = o.getPricingPhases().getPricingPhaseList();
+    const phases = [];
+    for (let j = 0; j < list.size(); j++) {
+      const ph = list.get(j);
+      phases.push({
+        priceAmountMicros: Number(ph.getPriceAmountMicros()),
+        billingPeriod: String(ph.getBillingPeriod() ?? ''),
+      });
+    }
+    const id = o.getOfferId ? o.getOfferId() : null;
+    out.push({ offerId: id != null ? String(id) : null, phases, native: o });
+  }
+  return out;
+}
+
+/** First native pricing phase whose micros satisfy `pred`. */
+function pickNativePhase(list: any, pred: (micros: number) => boolean): any {
+  for (let i = 0; i < list.size(); i++) {
+    const p = list.get(i);
+    if (pred(Number(p.getPriceAmountMicros()))) return p;
+  }
+  return null;
+}
+
+/** ProductDetails → the platform-neutral Product shape, from the SELECTED offer (trial-aware). */
+function mapAndroidProduct(pd: any): any {
+  const selected = selectSubscriptionOffer(androidOfferCandidates(pd));
+  if (!selected) return null; // not a subscription / no offer
+  const list = selected.native.getPricingPhases().getPricingPhaseList();
+  // Recurring (paid) phase for the display price; fall back to the last phase.
+  const phase = pickNativePhase(list, (m) => m > 0) ?? list.get(list.size() - 1);
+  const period = String(phase.getBillingPeriod() ?? '');
+  const product: any = {
+    id: String(pd.getProductId()),
+    title: String(pd.getTitle() ?? pd.getName() ?? ''),
+    description: String(pd.getDescription() ?? ''),
+    price: Number(phase.getPriceAmountMicros()) / 1_000_000,
+    displayPrice: String(phase.getFormattedPrice() ?? ''),
+    currency: String(phase.getPriceCurrencyCode() ?? ''),
+    type: 'autoRenewable',
+    subscriptionPeriod: period || undefined,
+  };
+  // Surface the free-trial / intro phase so the UI can show trial terms (Play also shows them in its
+  // own sheet). Populated only when the selected offer carries a zero-price phase (trial-eligible).
+  const intro = pickNativePhase(list, (m) => m === 0);
+  if (intro) {
+    const introPeriod = String(intro.getBillingPeriod() ?? '');
+    product.introOffer = {
+      price: Number(intro.getPriceAmountMicros()) / 1_000_000,
+      displayPrice: String(intro.getFormattedPrice() ?? ''),
+      period: introPeriod || undefined,
+      isFreeTrial: Number(intro.getPriceAmountMicros()) === 0,
+    };
+  }
+  return product;
+}
+
+/** Play Purchase → PurchaseReceipt (the token is the critical field the server validator consumes). */
+function androidReceiptFor(purchase: any, productId: string): any {
+  return {
+    platform: 'android',
+    productId,
+    transactionId: String(purchase.getOrderId?.() ?? ''),
+    purchaseToken: String(purchase.getPurchaseToken()),
+    packageName: String(purchase.getPackageName?.() ?? packageName()),
+    raw: {
+      originalJson: String(purchase.getOriginalJson?.() ?? ''),
+      signature: String(purchase.getSignature?.() ?? ''),
+    },
+  };
+}
+
+/** Client-side acknowledge (see ACKNOWLEDGEMENT DECISION above). Fire-and-forget; logs on failure. */
+function acknowledgeAndroidPurchase(purchase: any): void {
+  try {
+    if (purchase.isAcknowledged()) return;
+    const api = billingApi();
+    const params = api.AcknowledgePurchaseParams.newBuilder()
+      .setPurchaseToken(purchase.getPurchaseToken())
+      .build();
+    billingClient.acknowledgePurchase(params, new api.AcknowledgePurchaseResponseListener({
+      onAcknowledgePurchaseResponse(result: any) {
+        if (result.getResponseCode() !== PLAY_RESP.OK) {
+          console.warn('AppWrap: billing acknowledge failed', result.getResponseCode(), String(result.getDebugMessage?.() ?? ''));
+        }
+      },
+    }));
+  } catch (e) {
+    console.warn('AppWrap: billing acknowledge threw', e);
+  }
+}
+
+/** The single PurchasesUpdatedListener callback — routes results to the purchase() waiter(s). */
+function onAndroidPurchasesUpdated(result: any, purchases: any): void {
+  const code = result.getResponseCode();
+  if (code !== PLAY_RESP.OK || !purchases) {
+    // No product context here (Play doesn't say which flow) → reject all in-flight purchases with the
+    // mapped error (USER_CANCELED → DENIED, mirroring iOS' cancel semantics).
+    const e = mapBillingErr(result);
+    for (const w of androidPurchaseWaiters.values()) w.reject(e);
+    androidPurchaseWaiters.clear();
+    return;
+  }
+  const n = purchases.size();
+  for (let i = 0; i < n; i++) {
+    const purchase = purchases.get(i);
+    // PENDING (cash/bank/parental-approval) → don't resolve/ack/grant now. This NATIVE waiter has NO
+    // timeout; the JS `invoke` rejects at 120s, so by the time Play flips PENDING→PURCHASED (hours/
+    // days later) the purchase() promise is long gone. The completion is recoverable ONLY via the
+    // billing.transaction event emitted below when this listener fires again with PURCHASED — NOT via
+    // the original purchase() promise. Do NOT ack or grant a PENDING purchase.
+    if (purchase.getPurchaseState() !== PURCHASE_STATE_PURCHASED) continue;
+    acknowledgeAndroidPurchase(purchase);
+    const prods = purchase.getProducts();
+    const pid = prods && prods.size() > 0 ? String(prods.get(0)) : '';
+    const receipt = androidReceiptFor(purchase, pid);
+    bridge.emit('billing.transaction', receipt);
+    const w = androidPurchaseWaiters.get(pid);
+    if (w) { w.resolve(receipt); androidPurchaseWaiters.delete(pid); }
+  }
+}
+
+/** queryPurchasesAsync(SUBS) → active PurchaseReceipts (used by restore / appReceipt / entitlements). */
+function androidActivePurchases(): Promise<any[]> {
+  return ensureAndroidClient().then((client) => new Promise<any[]>((resolve, reject) => {
+    const api = billingApi();
+    const params = api.QueryPurchasesParams.newBuilder().setProductType(api.BillingClient.ProductType.SUBS).build();
+    client.queryPurchasesAsync(params, new api.PurchasesResponseListener({
+      onQueryPurchasesResponse(result: any, list: any) {
+        if (result.getResponseCode() !== PLAY_RESP.OK) return reject(mapBillingErr(result));
+        const receipts: any[] = [];
+        const n = list ? list.size() : 0;
+        for (let i = 0; i < n; i++) {
+          const p = list.get(i);
+          if (p.getPurchaseState() !== PURCHASE_STATE_PURCHASED) continue;
+          acknowledgeAndroidPurchase(p); // ack any not-yet-acked active sub (in-place migration safety)
+          const prods = p.getProducts();
+          const pid = prods && prods.size() > 0 ? String(prods.get(0)) : '';
+          receipts.push(androidReceiptFor(p, pid));
+        }
+        resolve(receipts);
+      },
+    }));
+  }));
+}
+
+function registerAndroidBilling(): void {
+  bridge.register('billing.products', async ({ ids = [] }: { ids: string[] }) => {
+    if (!ids.length) return [];
+    return (await queryAndroidProductDetails(ids)).map(mapAndroidProduct).filter(Boolean);
+  });
+
+  bridge.register('billing.purchase', async ({ productId }: { productId: string }) => {
+    // SERIALIZE: Play's PurchasesUpdatedListener gives NO product context on error, so a single
+    // in-flight purchase is the only way "reject all on error" can't cross-talk between callers.
+    // The app is single-product; a concurrent second purchase() is rejected outright, guaranteeing
+    // there is only ever ONE entry in androidPurchaseWaiters. Guard is set SYNCHRONOUSLY (before any
+    // await) so two near-simultaneous calls can't both pass it.
+    if (androidPurchaseInFlight) throw err('NATIVE_ERROR', 'A purchase is already in progress');
+    androidPurchaseInFlight = true;
+    try {
+      const client = await ensureAndroidClient();
+      const pd = (await queryAndroidProductDetails([productId]))[0];
+      if (!pd) throw err('NATIVE_ERROR', `Unknown product: ${productId}`);
+      const selected = selectSubscriptionOffer(androidOfferCandidates(pd));
+      if (!selected) throw err('NATIVE_ERROR', `No subscription offer for ${productId}`);
+      // Trial-aware: the SELECTED offer's token carries the free trial when the user is eligible.
+      const offerToken = selected.native.getOfferToken();
+      const api = billingApi();
+      const pdParams = api.BillingFlowParams.ProductDetailsParams.newBuilder()
+        .setProductDetails(pd)
+        .setOfferToken(offerToken)
+        .build();
+      const flowParams = api.BillingFlowParams.newBuilder()
+        .setProductDetailsParamsList(toJavaList([pdParams]))
+        .build();
+      return await new Promise((resolve, reject) => {
+        androidPurchaseWaiters.set(productId, { resolve, reject });
+        Utils.dispatchToMainThread(() => {
+          const activity = Application.android.foregroundActivity ?? Application.android.startActivity;
+          if (!activity) {
+            androidPurchaseWaiters.delete(productId);
+            reject(err('NOT_READY', 'no foreground activity'));
+            return;
+          }
+          // launchBillingFlow's synchronous result reports only launch failures; the purchase itself
+          // resolves later via onAndroidPurchasesUpdated → the waiter above.
+          const launch = client.launchBillingFlow(activity, flowParams);
+          if (launch.getResponseCode() !== PLAY_RESP.OK) {
+            androidPurchaseWaiters.delete(productId);
+            reject(mapBillingErr(launch));
+          }
+        });
+      });
+    } finally {
+      // Runs when the purchase settles (resolve/reject) or on any setup throw — re-opening the gate.
+      androidPurchaseInFlight = false;
+    }
+  });
+
+  bridge.register('billing.restore', () => androidActivePurchases());
+
+  // Android has no StoreKit-1-style on-disk app receipt; the analog is the most recent active sub's
+  // purchaseToken (empty when none). Mirrors iOS' { platform:'ios', appReceipt }.
+  bridge.register('billing.appReceipt', async () => {
+    const receipts = await androidActivePurchases();
+    return { platform: 'android', purchaseToken: receipts[0]?.purchaseToken };
+  });
+
+  // Thin, device-derived entitlements (server is the source-of-record — same posture as iOS).
+  bridge.register('billing.entitlements', async () => {
+    const receipts = await androidActivePurchases();
+    const seen = new Set<string>();
+    const ents: any[] = [];
+    for (const r of receipts) {
+      if (!r.productId || seen.has(r.productId)) continue;
+      seen.add(r.productId);
+      ents.push({ productId: r.productId, active: true });
+    }
+    return ents;
+  });
+
+  // Android has no in-app management sheet; the Play subscriptions deep link is the analog for BOTH
+  // manageSubscriptions() and showManageSubscriptionsSheet() (the JS layer dispatches the sheet call
+  // here now that the capability is 'native' on Android).
+  const openManage = ({ productId }: { productId?: string } = {}) => {
+    const base = 'https://play.google.com/store/account/subscriptions';
+    const url = productId ? `${base}?sku=${encodeURIComponent(productId)}&package=${packageName()}` : base;
+    Utils.openUrl(url);
+  };
+  bridge.register('billing.manageSubscriptions', (p: { productId?: string } = {}) => openManage(p));
+  bridge.register('billing.manageSubscriptionsSheet', (p: { productId?: string } = {}) => openManage(p));
+}

package/runtime/app/shell/web-quirks.ts

@@ -37,29 +37,30 @@ window.__APPWRAP_DEBUG__=${SHELL_CONFIG.debug ? 'true' : 'false'};
   });
   window.addEventListener('error', function(e){ post('[uncaught] ' + (e.message || e) + ' @ ' + (e.filename || '') + ':' + (e.lineno || 0)); });
   window.addEventListener('unhandledrejection', function(e){ var r = e.reason; post('[rejection] ' + ((r && (r.stack || r.message)) || r)); });
-  // Debug builds only: a loud, non-interactive DEV strip pinned to the top edge showing the server
-  // this shell points at. A dev-pointing ipa (debug:true) must never be mistaken for a store/prod
-  // build — the host in the strip makes "which backend am I on?" answerable at a glance.
+  // Debug builds only: a small, non-interactive RED DOT parked just under the top safe area. A
+  // dev-pointing/dev-signed ipa (debug:true) must never be mistaken for a store/prod build — the dot is
+  // the minimum always-on "this is not a store build" tell. It deliberately carries NO text (it replaced
+  // a full-width 'DEV · <host>' strip that was too heavy): WHICH backend is answerable on demand via
+  // shake → dev menu → App Info (remote host). Sits BELOW safe-area-inset-top so it never overlaps the
+  // notch/Dynamic Island, is position:fixed (no layout shift) and pointer-events:none (never steals a tap).
   // SUPPRESSED when the env-switcher is enabled: its bottom env-banner (shown only on a NON-default
-  // env) is the better, less-intrusive "which env am I on" indicator and supersedes this strip. Apps
-  // without envSwitcher keep the strip. (Store builds never reach here — debug is false.)
-  var __appwrapDevStrip = ${SHELL_CONFIG.envSwitcher?.enabled ? 'false' : 'true'};
-  var srv = ${JSON.stringify(SHELL_CONFIG.serverUrl || '')};
-  var host = ''; try { host = srv ? new URL(srv).host : (location && location.host) || ''; } catch (e) { host = srv || ''; }
-  function mountDevStrip(){
-    if (document.getElementById('__appwrap_dev_strip__') || !document.body) return;
+  // env) is the better, less-intrusive "which env am I on" indicator and supersedes this. Apps
+  // without envSwitcher keep the dot. (Store builds never reach here — debug is false.)
+  var __appwrapDevDot = ${SHELL_CONFIG.envSwitcher?.enabled ? 'false' : 'true'};
+  function mountDevDot(){
+    if (document.getElementById('__appwrap_dev_dot__') || !document.body) return;
     var el = document.createElement('div');
-    el.id = '__appwrap_dev_strip__';
-    el.textContent = 'DEV · ' + host;
-    el.style.cssText = 'position:fixed;top:0;left:0;right:0;z-index:2147483647;pointer-events:none;'
-      + 'background:#b91c1c;color:#fff;text-align:center;letter-spacing:.5px;'
-      + 'font:600 10px/1 -apple-system,system-ui,sans-serif;'
-      + 'padding:calc(env(safe-area-inset-top,0px) + 2px) 6px 2px;';
+    el.id = '__appwrap_dev_dot__';
+    // White ring + drop shadow so a 9px dot stays legible over BOTH light and dark app backgrounds.
+    el.style.cssText = 'position:fixed;z-index:2147483647;pointer-events:none;'
+      + 'top:calc(env(safe-area-inset-top,0px) + 6px);right:calc(env(safe-area-inset-right,0px) + 8px);'
+      + 'width:9px;height:9px;border-radius:50%;background:#ef4444;'
+      + 'box-shadow:0 0 0 1.5px rgba(255,255,255,.9),0 1px 3px rgba(0,0,0,.45);';
     document.body.appendChild(el);
   }
-  if (__appwrapDevStrip) {
-    if (document.body) mountDevStrip();
-    else document.addEventListener('DOMContentLoaded', mountDevStrip);
+  if (__appwrapDevDot) {
+    if (document.body) mountDevDot();
+    else document.addEventListener('DOMContentLoaded', mountDevDot);
   }
 })();`;
 

package/runtime/tests/billing-offer.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  hasFreeTrialPhase,
+  introPhase,
+  recurringPhase,
+  selectSubscriptionOffer,
+  type OfferCandidate,
+} from '../app/shell/billing-offer';
+
+// The two offers a trial-ELIGIBLE user sees. Order is deliberately trial-LAST to prove index-0 is
+// unsafe by contract (the old offers.get(0) bug picked the base plan and dropped the trial).
+const basePlan: OfferCandidate = {
+  offerId: null,
+  phases: [{ priceAmountMicros: 4_990_000, billingPeriod: 'P1M' }],
+};
+const trialOffer: OfferCandidate = {
+  offerId: 'freetrial',
+  phases: [
+    { priceAmountMicros: 0, billingPeriod: 'P1W' },
+    { priceAmountMicros: 4_990_000, billingPeriod: 'P1M' },
+  ],
+};
+
+describe('selectSubscriptionOffer', () => {
+  test('trial present (base first) → picks the trial offer', () => {
+    expect(selectSubscriptionOffer([basePlan, trialOffer])).toBe(trialOffer);
+  });
+
+  test('trial present (trial first) → still picks the trial offer regardless of order', () => {
+    expect(selectSubscriptionOffer([trialOffer, basePlan])).toBe(trialOffer);
+  });
+
+  test('trial absent (ineligible user) → falls back to the base-plan offer', () => {
+    expect(selectSubscriptionOffer([basePlan])).toBe(basePlan);
+  });
+
+  test('trial absent, offerId not null → returns the first offer as last resort', () => {
+    const promoNoTrial: OfferCandidate = { offerId: 'promo', phases: [{ priceAmountMicros: 2_990_000 }] };
+    expect(selectSubscriptionOffer([promoNoTrial])).toBe(promoNoTrial);
+  });
+
+  test('empty list → null', () => {
+    expect(selectSubscriptionOffer([])).toBeNull();
+  });
+
+  // Falsifiability guard: the trial offer's FIRST phase is free — if the code silently used
+  // offers.get(0) again, this would fail because base-first order would pick basePlan.
+  test('the selected trial offer exposes a zero-price intro phase and the recurring price', () => {
+    const chosen = selectSubscriptionOffer([basePlan, trialOffer])!;
+    expect(hasFreeTrialPhase(chosen)).toBe(true);
+    expect(introPhase(chosen)?.priceAmountMicros).toBe(0);
+    expect(introPhase(chosen)?.billingPeriod).toBe('P1W');
+    expect(recurringPhase(chosen)?.priceAmountMicros).toBe(4_990_000);
+  });
+
+  test('base plan has no intro phase; recurring == its only paid phase', () => {
+    expect(hasFreeTrialPhase(basePlan)).toBe(false);
+    expect(introPhase(basePlan)).toBeUndefined();
+    expect(recurringPhase(basePlan)?.priceAmountMicros).toBe(4_990_000);
+  });
+});

package/src/cli.ts

@@ -644,6 +644,24 @@ export const SHELL_CONFIG = {
   writeFileSync(join(outDir, 'app/shell/config.ts'), content);
 }
 
+/** `deploy` (ios + android) stamps the shell with **`debug: true` FORCED, overriding your config**.
+ *
+ * This is INTENTIONAL and load-bearing: `deploy` is the local dev-install loop, and debug mode is what
+ * enables keep-awake + the WebView inspector for continuous troubleshooting. `sync`, `release` and
+ * `submit` all honour `cfg.debug` verbatim — `deploy` is the deliberate exception, not an oversight.
+ *
+ * ⚠️ THE TRAP: any feature gated on `SHELL_CONFIG.debug` is **unfalsifiable on a deployed build** — the
+ * gate is always open, so "it worked when I deployed it" proves nothing about a real (`debug:false`)
+ * build, and a debug-gated regression cannot reproduce here. To verify debug-gated behaviour, build via
+ * `appwrap release` (which honours the config) — do NOT conclude from a `deploy` build.
+ * Hence the printed line: the forcing must never be silent. */
+function stampDeployShellConfig(outDir: string, cfg: AppwrapConfig): void {
+  stampShellConfig(outDir, { ...cfg, debug: true });
+  console.log(cfg.debug === false
+    ? '  ⚠ deploy forces debug:true (keep-awake + WebView inspector) — OVERRIDING debug:false from your config.\n    debug-gated behaviour cannot be verified on this build; use `appwrap release` for that.'
+    : '  ℹ debug:true — forced by deploy (keep-awake + WebView inspector); debug-gated code is always ON here.');
+}
+
 function stampNativeScriptConfig(outDir: string, cfg: AppwrapConfig): void {
   const file = join(outDir, 'nativescript.config.ts');
   const src = readFileSync(file, 'utf8').replace(/id: '[^']*'/, `id: '${cfg.id}'`);
@@ -3253,40 +3271,122 @@ function pinTeamIdToConfig(configPath: string, teamId: string): void {
 
 // ── Build fingerprint for smart resume ───────────────────────────────────────────────────────────
 
-/** Cheap fingerprint of SOURCE build inputs: mtime sum of the PWA dist/ + appwrap config.
- * App_Resources/ is intentionally excluded — sync() rewrites it every run, so its mtime always
- * changes and would make the fingerprint permanently stale.
+/** Files under TEMPLATE_DIR that are NOT build inputs, for fingerprinting. Deliberately a superset-keeper
+ * vs `templateCopyFilter`: `modules-native/` IS excluded there (copied selectively per active module) but
+ * IS compiled into bundle.js, so editing it MUST invalidate the cache — it stays in the fingerprint here.
+ * `app/www` (PWA staging) is build OUTPUT and `node_modules`/`platforms`/`hooks` are generated, so all four
+ * would make the hash unstable across runs. Matched RELATIVE to TEMPLATE_DIR: when installed from npm
+ * TEMPLATE_DIR itself lives under node_modules/, and testing the absolute path would exclude everything. */
+const templateFingerprintFilter = (src: string): boolean =>
+  !/(?:^|\/)(node_modules|platforms|hooks|app\/www)(\/|$)/.test(src.slice(TEMPLATE_DIR.length));
+
+/** Cheap fingerprint of SOURCE build inputs: mtime sum of the PWA dist/ + appwrap config + the appwrap
+ * `runtime/` template tree + this CLI's version.
+ * App_Resources/ (under the app's native/ outDir) is intentionally excluded — sync() rewrites it every
+ * run, so its mtime always changes and would make the fingerprint permanently stale.
+ * runtime/ IS included: it is compiled straight into bundle.js, so omitting it made a runtime edit print
+ * "Skipping build — inputs unchanged" and then install an artifact carrying the PREVIOUS runtime — a
+ * silent stale build that reads as a pass. CLI_VERSION covers codegen changes that touch no source file.
+ * Cost: ~150 stat() calls on a 1MB tree, sub-millisecond — no need for content hashing.
  * Collision risk is acceptable — a false "match" just skips a redundant build, not a correctness bug. */
-export function buildFingerprint(cwd: string, cfg: { pwaDist?: string; overrides?: string }, flags: Record<string, string> = {}): string {
-  const mtime = (p: string): number => {
-    if (!existsSync(p)) return 0;
-    try {
-      const s = statSync(p);
-      if (s.isDirectory()) {
-        let sum = 0;
-        for (const e of readdirSync(p, { withFileTypes: true }))
-          sum += mtime(join(p, e.name));
-        return sum;
+function mtimeStats(p: string): { sum: number; newest: number } {
+  if (!existsSync(p)) return { sum: 0, newest: 0 };
+  try {
+    const s = statSync(p);
+    if (s.isDirectory()) {
+      let sum = 0, newest = 0;
+      for (const e of readdirSync(p, { withFileTypes: true })) {
+        const c = mtimeStats(join(p, e.name));
+        sum += c.sum;
+        if (c.newest > newest) newest = c.newest;
       }
-      return s.mtimeMs;
-    } catch { return 0; }
-  };
+      return { sum, newest };
+    }
+    return { sum: s.mtimeMs, newest: s.mtimeMs };
+  } catch { return { sum: 0, newest: 0 }; }
+}
+
+/** THE build-input set, walked once — the single source of truth for both consumers below:
+ * `parts` (per-input mtime SUMS) feed the fingerprint hash; `newest` (max mtime across every input)
+ * feeds the `--resume` staleness gate. Keeping them on one walk means an input can never be in the
+ * hash but out of the gate (or vice versa) — that divergence is exactly how stale builds ship. */
+function buildInputStats(cwd: string, cfg: { pwaDist?: string; overrides?: string }, flags: Record<string, string>): { parts: number[]; newest: number } {
   // Fingerprint EVERY app source the build actually consumes — not just dist. Missing the overrides dir
   // (native escape hatch) or a `.js`/`.json`/`--config` config file made edits there produce a stale
   // "inputs unchanged" skip. Resolve the real config path (ts→js→json / --config) instead of hardcoding.
   const distDir = cfg.pwaDist ? resolve(cwd, cfg.pwaDist) : join(cwd, 'dist');
   const overridesDir = resolve(cwd, cfg.overrides ?? 'appwrap.overrides');
-  const parts = [mtime(distDir), mtime(overridesDir), mtime(resolveConfigPath(cwd, flags))];
+  const stats = [mtimeStats(distDir), mtimeStats(overridesDir), mtimeStats(resolveConfigPath(cwd, flags))];
+  // The appwrap runtime template — bundled into bundle.js, so it is a first-class build input.
+  let runtime = 0, runtimeNewest = 0;
+  for (const rel of collectRelFiles(TEMPLATE_DIR, templateFingerprintFilter)) {
+    const s = mtimeStats(join(TEMPLATE_DIR, rel));
+    runtime += s.sum;
+    if (s.newest > runtimeNewest) runtimeNewest = s.newest;
+  }
+  stats.push({ sum: runtime, newest: runtimeNewest });
+  return { parts: stats.map((s) => s.sum), newest: Math.max(...stats.map((s) => s.newest)) };
+}
+
+/** Newest mtime across every build input — the evidence the `--resume` gate needs when no build cache
+ * exists to compare a fingerprint against. Same input set as `buildFingerprint` by construction. */
+export function newestBuildInputMtime(cwd: string, cfg: { pwaDist?: string; overrides?: string }, flags: Record<string, string> = {}): number {
+  return buildInputStats(cwd, cfg, flags).newest;
+}
+
+export function buildFingerprint(cwd: string, cfg: { pwaDist?: string; overrides?: string }, flags: Record<string, string> = {}): string {
+  const { parts } = buildInputStats(cwd, cfg, flags);
   // Simple djb2-style hash — good enough for a build-skip check (not cryptographic).
   let h = 5381;
   for (const n of parts) h = (((h << 5) + h) ^ (n | 0)) >>> 0;
+  // Mix in the CLI version — a `bunx appwrap` upgrade changes codegen without touching any app source.
+  for (const c of CLI_VERSION) h = (((h << 5) + h) ^ c.charCodeAt(0)) >>> 0;
   return h.toString(36);
 }
 
+/** The iOS build-skip decision — pure, so it is testable without a device, an Xcode toolchain, or an .ipa.
+ *
+ * INVARIANT (the whole point of this function): a skip REQUIRES positive evidence that the existing .ipa
+ * already contains the current inputs. Two forms of evidence are accepted:
+ *   1. fingerprintMatch — the recorded cache fingerprint equals the current one. Strongest; the default.
+ *   2. --resume with NO cache (manual Xcode build / first run) — nothing recorded a fingerprint, so we
+ *      fall back to the .ipa being at least as new as every build input. An input touched after the .ipa
+ *      was written provably postdates it, so the .ipa cannot contain it → rebuild.
+ * `--resume` relaxes WHICH evidence is required; it never removes the requirement. Before this, form 2
+ * was `resume && !cache` with NO comparison at all — `--resume` silently shipped stale .ipas, the exact
+ * failure the fingerprint exists to kill. Android has no equivalent branch (strictly form 1).
+ *
+ * Honest limit: mtime proves the artifact POSTDATES its inputs, not that it was BUILT from them (a
+ * hand-`touch`ed .ipa still fools it). That is the trust `--resume` explicitly asks for, and it is
+ * strictly stronger than the unconditional skip it replaces. `--force` overrides everything.
+ *
+ * `adoptCache` → record the fingerprint for a form-2 skip, so every LATER run is gated by form 1. */
+export function decideIosBuildSkip(o: {
+  force: boolean;
+  resume: boolean;
+  fp: string;
+  ipaPath?: string;
+  ipaMtime: number;
+  cache: BuildCache | null;
+  newestInputMtime: () => number;
+}): { skip: boolean; reason: string; adoptCache: boolean } {
+  if (o.force) return { skip: false, reason: '', adoptCache: false };
+  if (!o.ipaPath) return { skip: false, reason: '', adoptCache: false };
+  if (o.cache) {
+    return o.cache.fingerprint === o.fp && o.cache.artifactPath === o.ipaPath
+      ? { skip: true, reason: 'inputs unchanged since last build', adoptCache: false }
+      : { skip: false, reason: '', adoptCache: false };
+  }
+  if (!o.resume) return { skip: false, reason: '', adoptCache: false };
+  return o.ipaMtime >= o.newestInputMtime()
+    ? { skip: true, reason: '--resume (no cache; .ipa is newer than every build input)', adoptCache: true }
+    : { skip: false, adoptCache: false, reason: '--resume ignored — the existing .ipa is older than a build input (it cannot contain your latest change); rebuilding.' };
+}
+
 // Per-platform build cache (iOS .ipa / Android .apk) — separate files so the two don't clobber each
 // other's fingerprint (that's what enables the build-skip on BOTH platforms).
 const buildCacheFile = (platform: string) => `.appwrap-build-cache-${platform}.json`;
-interface BuildCache { fingerprint: string; artifactPath: string; builtAt: string }
+export interface BuildCache { fingerprint: string; artifactPath: string; builtAt: string }
 
 function readBuildCache(outDir: string, platform: string): BuildCache | null {
   try { return JSON.parse(readFileSync(join(outDir, buildCacheFile(platform)), 'utf8')); } catch { return null; }
@@ -3577,11 +3677,11 @@ async function deployAndroid(cwd: string, flags: Record<string, string>, cfgOver
 
   buildWebIfBundled(cwd, cfg, flags);                  // bundled → fresh web bundle; server → skip (both printed)
   await sync(cwd, flags, cfgOverride);                 // re-stamp config + copy latest PWA dist
-  stampShellConfig(outDir, { ...cfg, debug: true });   // debug: keep-awake + WebView inspector (parity with deploy ios)
+  stampDeployShellConfig(outDir, cfg);                 // forces debug:true — see the helper's doc for why + the trap
 
   const apk = join(outDir, 'platforms/android/app/build/outputs/apk/debug/app-debug.apk');
-  // Fingerprint build-skip (parity with deploy ios): skip the gradle build when dist + config are
-  // unchanged since the last build. --force/-f always rebuilds. (Rebuilding the web above usually
+  // Fingerprint build-skip (parity with deploy ios): skip the gradle build when dist + config + the
+  // appwrap runtime/ are unchanged since the last build. --force/-f always rebuilds. (Rebuilding the web above usually
   // bumps the fingerprint; pair with --no-web-build to actually hit this fast-path.)
   const force = 'force' in flags || 'f' in flags;
   const fp = buildFingerprint(cwd, cfg, flags);
@@ -3651,8 +3751,8 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
 
   buildWebIfBundled(cwd, cfg, flags); // bundled → fresh web bundle (no stale dist); server → skip (printed)
   await sync(cwd, flags, cfgOverride); // re-stamp config + copy latest PWA dist (+ vendor backend assets)
-  // Dev deploy → debug mode: keep-awake + WebView inspector for continuous troubleshooting.
-  stampShellConfig(outDir, { ...cfg, debug: true });
+  // Dev deploy → debug mode forced: keep-awake + WebView inspector. See the helper's doc for the trap.
+  stampDeployShellConfig(outDir, cfg);
   // Self-heal: drop platforms/ios if a prior `release`/`publish` left App-Store/manual signing there
   // (NS preserves it across prepares + it overrides build.xcconfig) → clean automatic dev signing.
   resetStaleSigningForAutoLane(outDir, cfg);
@@ -3660,24 +3760,29 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
   const ipaDir = join(outDir, 'platforms/ios/build/Debug-iphoneos');
 
   // Smart resume: skip ns build (pod install + xcodebuild) when inputs haven't changed.
-  // --resume (-r): opt in to fingerprint-based skip (same logic as auto, but explicit — useful when
-  //   the auto check has no prior cache yet and you want to force a skip on first run after a manual build).
+  // --resume (-r): additionally allow a skip when there is NO build cache yet (e.g. the .ipa came from a
+  //   manual Xcode build, or this is the first run) — gated on the .ipa being newer than every build
+  //   input. It relaxes WHICH evidence is required, never whether evidence is required.
   // Auto: always checks fingerprint; never skips if sources/deps changed.
   const resume = 'resume' in flags || 'r' in flags;
   const force = 'force' in flags || 'f' in flags;
   const fp = buildFingerprint(cwd, cfg, flags);
   const cache = readBuildCache(outDir, 'ios');
   const existingIpa = newestIpa(ipaDir);
-  const fingerprintMatch = !force && existingIpa && cache?.fingerprint === fp && cache?.artifactPath === join(ipaDir, existingIpa);
-  // --resume also accepts a missing cache file (e.g. after a manual Xcode build or first run),
-  // but ONLY when the fingerprint matches what's currently on disk — never skips a needed build.
-  const noCache = existingIpa && !cache;
-  const canSkipBuild = !force && (fingerprintMatch || (resume && noCache));
+  const decision = decideIosBuildSkip({
+    force, resume, fp,
+    ipaPath: existingIpa ? join(ipaDir, existingIpa) : undefined,
+    ipaMtime: existingIpa ? statSync(join(ipaDir, existingIpa)).mtimeMs : 0,
+    cache,
+    newestInputMtime: () => newestBuildInputMtime(cwd, cfg, flags),
+  });
+  const { skip: canSkipBuild, adoptCache } = decision;
 
   if (canSkipBuild) {
-    const reason = fingerprintMatch ? 'inputs unchanged since last build' : '--resume (first run, .ipa present)';
-    console.log(`⚡ Skipping build — ${reason} (${existingIpa})`);
+    console.log(`⚡ Skipping build — ${decision.reason} (${existingIpa})`);
   } else {
+    // Asked to resume but the .ipa predates a build input → say so instead of quietly rebuilding.
+    if (decision.reason) console.log(`↻ ${decision.reason}`);
     // Manual signing (signing:'manual') → pass the main-app profile as --provision so NS emits a
     // manual exportOptions.plist covering the app + its extensions (see stampManualSigning sidecar).
     const nsArgs = ['build', 'ios', '--for-device'];
@@ -3728,7 +3833,11 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
   const ipa = builtIpa;
   if (!ipa) { console.error(`✖ No .ipa produced in ${ipaDir}`); process.exit(1); }
   const ipaPath = join(ipaDir, ipa);
-  if (!canSkipBuild) writeBuildCache(outDir, 'ios', { fingerprint: fp, artifactPath: ipaPath, builtAt: new Date().toISOString() });
+  // Write the cache after a real build, AND after a --resume skip: adopting the fingerprint converts
+  // that one-time mtime-based trust into a recorded baseline, so EVERY later run is strictly
+  // fingerprint-gated. Without this, --resume stayed in the no-cache branch forever — permanently
+  // ungated. (A fingerprintMatch skip already has an identical cache; nothing to write.)
+  if (!canSkipBuild || adoptCache) writeBuildCache(outDir, 'ios', { fingerprint: fp, artifactPath: ipaPath, builtAt: new Date().toISOString() });
 
   console.log(`▶ installing ${ipa} → ${device.name} [${device.transport}]`);
   let installedViaUsbmux = false;