@livx.cc/appwrap 0.28.1 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.28.1",
+  "version": "0.29.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/background-worker.android.ts

@@ -0,0 +1,47 @@
+import { Utils } from '@nativescript/core';
+import { runHeadless, finishRun } from './handlers-background';
+
+// androidx (WorkManager) isn't in @nativescript/types-android — it's an AndroidX library, not the
+// platform SDK — so it stays `any`. `java` resolves from the SDK typings; `NativeClass`/`JavaProxy`
+// are ambient NativeScript runtime globals.
+declare const androidx: any;
+declare const java: any;
+
+/**
+ * WorkManager headless Worker — created by WorkManager on a background launch. `doWork()` posts to the
+ * MAIN looper (the WebView must be built + driven on the UI thread), runs the headless WebView loop for
+ * the input task id, and blocks the worker thread on a `CountDownLatch` until `backgroundTask.finish`
+ * (or a timeout). Returns success/failure; WorkManager handles periodic rescheduling.
+ *
+ * ANDROID-ONLY (`.android.ts`): a top-level `@JavaProxy` / `extends androidx.work.Worker` class
+ * dereferences Android-only globals at module load. In a SHARED file that evaluates on iOS too, that
+ * throws during ES-module instantiation → hard launch crash. Isolating it here keeps it off iOS.
+ * ⚠ DEVICE-UNVERIFIED — compiles only (see handlers-background.ts header).
+ */
+@NativeClass()
+@JavaProxy('cc.livx.appwrap.AppwrapBackgroundWorker')
+export class AppwrapBackgroundWorker extends androidx.work.Worker {
+  constructor(context: any, params: any) {
+    super(context, params);
+  }
+
+  doWork(): any {
+    const id = this.getInputData().getString('appwrap.taskId') ?? '';
+    if (!id) return androidx.work.ListenableWorker.Result.failure();
+
+    const latch = new java.util.concurrent.CountDownLatch(1);
+    const result = { success: false };
+    Utils.dispatchToMainThread(() => {
+      runHeadless(id)
+        .then((ok: boolean) => { result.success = ok; latch.countDown(); })
+        .catch(() => { latch.countDown(); });
+    });
+    // Block the worker thread (bounded — below the WorkManager 10-min ceiling) until the JS handler
+    // finishes. A timeout returns failure so WorkManager retries on its schedule.
+    const completed = latch.await(9, java.util.concurrent.TimeUnit.MINUTES);
+    if (!completed) finishRun(id, false);
+    return completed && result.success
+      ? androidx.work.ListenableWorker.Result.success()
+      : androidx.work.ListenableWorker.Result.failure();
+  }
+}

package/runtime/app/shell/background-worker.ios.ts

@@ -0,0 +1,5 @@
+// iOS stub. The WorkManager Worker is Android-only; handlers-background.ts STATICALLY imports
+// `AppwrapBackgroundWorker`, so the name must resolve on iOS too — but it must carry NO `@JavaProxy` /
+// `androidx` references (those are undefined on iOS and would crash ES-module instantiation at launch).
+// registerAndroid() is the only consumer and never runs on iOS, so this value is never dereferenced.
+export const AppwrapBackgroundWorker: any = undefined;

package/runtime/app/shell/background-worker.ts

@@ -0,0 +1,7 @@
+// Base / iOS module for `./background-worker`. The WorkManager Worker is Android-only; the real
+// `@JavaProxy` class lives in `background-worker.android.ts` (NS resolves the `.android.ts` override on
+// Android). This base resolves for plain `tsc` (which doesn't know NS platform suffixes) AND serves as
+// the iOS runtime impl — it must carry NO `@JavaProxy` / `androidx` references (undefined on iOS, they'd
+// crash ES-module instantiation at launch). registerAndroid() — the only consumer — never runs on iOS,
+// so this value is never dereferenced there.
+export const AppwrapBackgroundWorker: any = undefined;

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

@@ -3,6 +3,11 @@ import { bridge } from './bridge';
 import { SHELL_CONFIG } from './config';
 import { setPendingBackgroundTaskId } from './background-context';
 import { CustomWebView } from './custom-webview';
+// Android-only WorkManager Worker (@JavaProxy + `extends androidx.work.Worker`). Kept in a `.android.ts`
+// file so it's NEVER evaluated on iOS — a top-level Android native class in a shared module dereferences
+// `@JavaProxy`/`androidx` at module load, which are undefined on iOS → the whole ES module graph fails to
+// instantiate → hard launch crash. iOS resolves the `.ios.ts` stub; registerAndroid() is the only user.
+import { AppwrapBackgroundWorker } from './background-worker';
 
 // BackgroundTasks (iOS), NSDate, and the `android`/`java` namespaces resolve from the full SDK
 // (@nativescript/types-ios + types-android) — no declares needed.
@@ -58,7 +63,7 @@ const pendingRuns = new Map<string, PendingRun>();
 /** Build an offscreen WebView, attach the bridge, and load the app so its handshake reports `id`. The
  * returned promise resolves when the JS handler calls `backgroundTask.finish` (or `abort()` fires).
  * REUSES `CustomWebView` (scheme handler + bridge injection) — no duplicated transport. */
-function runHeadless(id: string): Promise<boolean> {
+export function runHeadless(id: string): Promise<boolean> {
   return new Promise<boolean>((resolve) => {
     setPendingBackgroundTaskId(id); // the next handshake reports this wake id
     const webView = new CustomWebView();
@@ -109,7 +114,7 @@ function loadAppInto(webView: CustomWebView, id: string, attempt = 0): void {
 
 /** Resolve an in-flight headless run (called by `backgroundTask.finish`, the safety abort, or a load
  * failure). Tears the offscreen WebView's bridge attachment down. Idempotent. */
-function finishRun(id: string, success: boolean): void {
+export function finishRun(id: string, success: boolean): void {
   const run = pendingRuns.get(id);
   if (!run) return;
   pendingRuns.delete(id);
@@ -222,7 +227,7 @@ function registerAndroid(): void {
     // WorkManager periodic floor is 15 min; clamp a smaller hint up so enqueue doesn't reject it.
     const ms = Math.max(15 * 60_000, Number(p?.minIntervalMs ?? 15 * 60_000));
     const builder = new androidx.work.PeriodicWorkRequest.Builder(
-      AppwrapBackgroundWorker.class,
+      (AppwrapBackgroundWorker as any).class,
       ms, java.util.concurrent.TimeUnit.MILLISECONDS
     );
     // The id rides as input data → the Worker reads it to drive the matching JS handler.
@@ -249,42 +254,5 @@ function registerAndroid(): void {
   });
 }
 
-/**
- * WorkManager headless Worker — created by WorkManager on a background launch. `doWork()` posts to the
- * MAIN looper (the WebView must be built + driven on the UI thread), runs the headless WebView loop for
- * the input task id, and blocks the worker thread on a `CountDownLatch` until `backgroundTask.finish`
- * (or a timeout). Returns success/failure; WorkManager handles periodic rescheduling.
- *
- * ⚠ DEVICE-UNVERIFIED — compiles only (see the file header).
- */
-@NativeClass()
-@JavaProxy('cc.livx.appwrap.AppwrapBackgroundWorker')
-export class AppwrapBackgroundWorker extends androidx.work.Worker {
-  constructor(context: any, params: any) {
-    super(context, params);
-  }
-
-  doWork(): any {
-    const id = this.getInputData().getString('appwrap.taskId') ?? '';
-    if (!id) return androidx.work.ListenableWorker.Result.failure();
-
-    const latch = new java.util.concurrent.CountDownLatch(1);
-    const result = { success: false };
-    Utils.dispatchToMainThread(() => {
-      runHeadless(id)
-        .then((ok: boolean) => { result.success = ok; latch.countDown(); })
-        .catch(() => { latch.countDown(); });
-    });
-    // Block the worker thread (bounded — below the WorkManager 10-min ceiling) until the JS handler
-    // finishes. A timeout returns failure so WorkManager retries on its schedule.
-    const completed = latch.await(9, java.util.concurrent.TimeUnit.MINUTES);
-    if (!completed) finishRun(id, false);
-    return completed && result.success
-      ? androidx.work.ListenableWorker.Result.success()
-      : androidx.work.ListenableWorker.Result.failure();
-  }
-}
-
-// Reference the Worker class so the bundler/NS metadata retains the JavaProxy (mirrors how the FCM
-// service is kept alive via its import side-effect). Without a reference the class can be tree-shaken.
-void AppwrapBackgroundWorker;
+// The WorkManager headless Worker (@JavaProxy `AppwrapBackgroundWorker`) lives in
+// `background-worker.android.ts` — see the import at the top of this file for WHY it can't be here.

package/src/cli.ts

@@ -24,6 +24,7 @@ import {
   androidScreenOrientation,
   iosOrientations,
   mergeManifest,
+  resolveBuildNumber,
   stampAndroidOrientation,
   stampAndroidQueries,
   stampPlistBackgroundTasks,
@@ -45,31 +46,15 @@ const execErrText = (e: unknown): string => {
   return `${err.stdout ?? ''}${err.stderr ?? ''}`;
 };
 
-/** Marketing version → a monotonic integer build (0.2.1 → 201; 1.4.12 → 10412). Stable & increasing
- * across semver bumps so store re-uploads are always accepted without a manual bump. */
-function deriveBuild(version: string): number {
-  const [maj = 0, min = 0, patch = 0] = version.split('.').map((n) => parseInt(n, 10) || 0);
-  return maj * 10000 + min * 100 + patch;
-}
-
 /**
- * Resolved monotonic build number (iOS CFBundleVersion / Android versionCode).
- * Precedence: `APPWRAP_BUILD_NUMBER` env (CI run #) > explicit `cfg.buildNumber` > derived from version.
- * The env override means CI gets a monotonic, collision-free build number for free — no per-app config
- * plumbing — which is the whole point: the derived default is CONSTANT per version, so repeat uploads
- * of the same marketing version would 409 ("build already exists") without it.
+ * Resolved monotonic build number (iOS CFBundleVersion / Android versionCode). Thin env wrapper over
+ * the pure `resolveBuildNumber` (in derive.ts, where it unit-tests). Precedence: `APPWRAP_BUILD_NUMBER`
+ * env (CI run #) > explicit numeric `cfg.buildNumber` > named strategy ('timestamp'|'epoch') > derived
+ * from version. The env override gives CI a monotonic, collision-free build for free; the derived
+ * default is CONSTANT per version, so repeat uploads of one marketing version would 409 without it.
  */
 function buildNumberOf(cfg: AppwrapConfig): number {
-  const env = process.env.APPWRAP_BUILD_NUMBER;
-  if (env != null && env !== '') {
-    const n = parseInt(env, 10);
-    if (!Number.isNaN(n)) return n;
-  }
-  if (cfg.buildNumber != null) {
-    const n = parseInt(String(cfg.buildNumber), 10);
-    if (!Number.isNaN(n)) return n;
-  }
-  return deriveBuild(cfg.version);
+  return resolveBuildNumber(cfg, process.env.APPWRAP_BUILD_NUMBER);
 }
 
 const IOS_PERMISSION_KEYS: Record<string, string[]> = {

package/src/config.ts

@@ -113,8 +113,12 @@ export interface AppwrapConfig {
   >;
   /** Monotonic build identifier. Stores reject a re-upload unless this is HIGHER than the last:
    * iOS `CFBundleVersion`, Android `versionCode` (the marketing `version` stays the user-facing
-   * string). Default: an integer derived from `version` (0.2.1 → 201). Set explicitly from a CI
-   * run number for fleet builds of the same marketing version. */
+   * string). Default: an integer derived from `version` (0.2.1 → 201). Set an explicit number from a
+   * CI run for fleet builds of one marketing version, OR a named strategy string (resolved by the
+   * framework so it can't drift across branches):
+   *   - `'timestamp'` — YYMMDDHHMM UTC (e.g. 2606221405). iOS-ONLY: exceeds Android's versionCode cap.
+   *   - `'epoch'` — unix seconds. Android-safe.
+   * (`APPWRAP_BUILD_NUMBER` env always wins; an unknown string falls back to the derived default.) */
   buildNumber?: string | number;
   /** iOS export-compliance. `ITSAppUsesNonExemptEncryption` — stamped `false` by default (skips the
    * per-upload prompt). Set `true` only if the app uses non-exempt encryption. */

package/src/derive.ts

@@ -47,6 +47,56 @@ export function mergeManifest<
   return cfg;
 }
 
+/** Marketing version → a monotonic integer build (0.2.1 → 201; 1.4.12 → 10412). Stable & increasing
+ * across semver bumps so store re-uploads are always accepted without a manual bump. */
+export function deriveBuild(version: string): number {
+  const [maj = 0, min = 0, patch = 0] = version.split('.').map((n) => parseInt(n, 10) || 0);
+  return maj * 10000 + min * 100 + patch;
+}
+
+/** Named build-number strategies. Live ONCE here so apps opt into a name instead of copying the
+ * stamping logic into their config (which drifts across branches). All return a single integer.
+ *  - `timestamp`: human-readable YYMMDDHHMM (UTC), e.g. 2026-06-22 14:05 → 2606221405. ≈2.6e9, ≤ the
+ *    iOS CFBundleVersion UInt32 cap (4294967295) until ~2042 — but it EXCEEDS Android versionCode's
+ *    2.1e9 cap, so this strategy is iOS-ONLY.
+ *  - `epoch`: unix seconds (Math.floor(Date.now()/1000)), ≈1.78e9 — Android-safe. */
+const BUILD_STRATEGIES: Record<string, (now: Date) => number> = {
+  timestamp: (now) => {
+    const p = (n: number) => String(n).padStart(2, '0');
+    const yy = now.getUTCFullYear() % 100;
+    return Number(
+      `${p(yy)}${p(now.getUTCMonth() + 1)}${p(now.getUTCDate())}${p(now.getUTCHours())}${p(now.getUTCMinutes())}`
+    );
+  },
+  epoch: (now) => Math.floor(now.getTime() / 1000),
+};
+
+/**
+ * Resolve the monotonic build number (iOS CFBundleVersion / Android versionCode). Pure: the CLI
+ * passes the `APPWRAP_BUILD_NUMBER` env value in (no process.env read here, so it unit-tests).
+ * Precedence: env (CI run #) > explicit numeric `buildNumber` > named strategy > derived from version.
+ * An unrecognized strategy string falls back to `deriveBuild` (never crashes).
+ */
+export function resolveBuildNumber(
+  cfg: { version: string; buildNumber?: string | number },
+  envBuildNumber?: string,
+  now: Date = new Date()
+): number {
+  if (envBuildNumber != null && envBuildNumber !== '') {
+    const n = parseInt(envBuildNumber, 10);
+    if (!Number.isNaN(n)) return n;
+  }
+  if (cfg.buildNumber != null) {
+    // A numeric value (number or numeric string) is the literal build number.
+    const n = parseInt(String(cfg.buildNumber), 10);
+    if (!Number.isNaN(n)) return n;
+    // Non-numeric → a strategy NAME. Map it, or fall back to deriveBuild for an unknown string.
+    const strategy = BUILD_STRATEGIES[String(cfg.buildNumber).trim()];
+    if (strategy) return strategy(now);
+  }
+  return deriveBuild(cfg.version);
+}
+
 /**
  * Collapse a PWA web-manifest `orientation` value to our three states. The manifest spec allows
  * `portrait`/`landscape` plus the `-primary`/`-secondary`/`*-up`/`natural` variants — we don't model

package/templates/ci/fastlane/Fastfile

@@ -46,7 +46,13 @@ platform :ios do
 
     # Wait for App Store Connect to finish processing and FAIL if it doesn't — Apple can accept the
     # upload yet silently drop the build (e.g. an out-of-range CFBundleVersion). skip:true hides that.
-    upload_to_testflight(api_key: api_key, skip_waiting_for_build_processing: false, wait_processing_timeout_duration: 1800)
+    # APPWRAP_TF_WAIT_TIMEOUT (seconds) tunes the wait: real builds can exceed 30 min under Apple
+    # processing load and crash the lane (BuildWatcher exceeded) — default to 1h, raise it if needed.
+    # Guard BOTH unset (nil) and empty/blank env: nil.to_i and "".to_i are 0, which would crash the
+    # lane instantly (BuildWatcher exceeded '0'). Only a positive integer overrides the 3600 default.
+    tf_wait_env = ENV['APPWRAP_TF_WAIT_TIMEOUT'].to_s.strip
+    tf_wait_timeout = tf_wait_env.to_i > 0 ? tf_wait_env.to_i : 3600
+    upload_to_testflight(api_key: api_key, skip_waiting_for_build_processing: false, wait_processing_timeout_duration: tf_wait_timeout)
   end
 end
 

package/templates/ci/github/workflows/appwrap-pr.yml

@@ -7,7 +7,7 @@ jobs:
   web:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
       - run: bun install
       - run: bun test || echo "no tests"
@@ -17,9 +17,9 @@ jobs:
     runs-on: macos-15
     needs: web
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with: { node-version: 22 }
       - run: bun install && bun run build
       # Pin global tools — unpinned installs can grab a breaking release mid-flight. Bump deliberately.

package/templates/ci/github/workflows/appwrap-release-android.yml

@@ -22,9 +22,9 @@ jobs:
   play:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with: { node-version: 22 }
       - uses: actions/setup-java@v4
         with: { distribution: temurin, java-version: 17 }

package/templates/ci/github/workflows/appwrap-release-ios.yml

@@ -24,12 +24,12 @@ jobs:
   testflight:
     runs-on: macos-15
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       # Apple requires the iOS 26 SDK (Xcode 26+) for uploads — runners may default to older Xcode.
       - uses: maxim-lobanov/setup-xcode@v1
         with: { xcode-version: latest-stable }
       - uses: oven-sh/setup-bun@v2
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with: { node-version: 22 }
       - run: bun install && bun run build
       # Pin global tools — unpinned installs can grab a breaking release mid-flight. Bump deliberately.