@livx.cc/appwrap 0.20.4 → 0.21.0

package/package.json

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

@@ -11,6 +11,7 @@ import { registerAndroidHandlers } from './shell/handlers-android';
 import { registerOptionalHandlers } from './shell/optional-handlers.generated';
 import './shell/fcm-bootstrap.generated'; // side-effect: registers the FCM service when push is wired
 import { startEventForwarding } from './shell/events';
+import { startDevMenu } from './shell/devmenu';
 import { SHELL_CONFIG } from './shell/config';
 import { bindStatusBarPage, setStatusBarStyle, enableAndroidEdgeToEdge, wireAndroidSafeArea } from './shell/status-bar';
 import { CustomWebView } from './shell/custom-webview';
@@ -44,6 +45,8 @@ export function onPageLoaded(args: EventData): void {
   if (isAndroid) registerAndroidHandlers();
   // Opt-in modules that own their own handler file (health, …) — generated to only the active set.
   registerOptionalHandlers();
+  // Shake-to-open developer menu (App Info / Reload). On by default, incl. prod.
+  if (SHELL_CONFIG.devMenu) startDevMenu();
 
   const webView = page.getViewById<CustomWebView>('webview');
   bridge.attach(webView);

package/runtime/app/shell/banner.ts

@@ -0,0 +1,149 @@
+import { Application, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+
+/**
+ * Persistent bottom banner (vs. the auto-dismiss `toast`). Used for the "new version available —
+ * tap to reload" update prompt. **Tap** emits `toast.action` { id } (the web side decides what to
+ * do) and dismisses; **swipe down** dismisses without acting.
+ */
+
+let currentId: string | null = null;
+let iosBanner: UIView | null = null;
+let iosTapHandler: any = null;
+let androidBanner: android.view.View | null = null;
+
+function onTap(): void {
+  const id = currentId;
+  dismissBanner();
+  if (id) bridge.emit('toast.action', { id });
+}
+
+export function showBanner(opts: { id: string; message: string }): void {
+  dismissBanner(); // only one at a time
+  currentId = opts.id;
+  if (isIOS) Utils.dispatchToMainThread(() => showIOSBanner(opts.message));
+  else if (isAndroid) runOnAndroidUi(() => showAndroidBanner(opts.message));
+}
+
+export function dismissBanner(): void {
+  currentId = null;
+  if (isIOS && iosBanner) {
+    const b = iosBanner;
+    iosBanner = null;
+    iosTapHandler = null;
+    Utils.dispatchToMainThread(() => b.removeFromSuperview());
+  }
+  if (isAndroid && androidBanner) {
+    const v = androidBanner;
+    androidBanner = null;
+    runOnAndroidUi(() => (v.getParent() as android.view.ViewGroup)?.removeView(v));
+  }
+}
+
+// ── iOS ──────────────────────────────────────────────────────────────
+// Built lazily (and only on iOS) — `NSObject`/`interop` don't exist on Android, and this file is
+// imported on both platforms via handlers.ts, so a top-level `.extend` would crash the Android shell.
+let IOSGestureHandler: any = null;
+function iosGestureHandlerClass(): any {
+  if (!IOSGestureHandler) {
+    IOSGestureHandler = (NSObject as any).extend(
+      { bannerTapped() { onTap(); }, bannerDismissed() { dismissBanner(); } },
+      {
+        exposedMethods: {
+          bannerTapped: { returns: interop.types.void },
+          bannerDismissed: { returns: interop.types.void },
+        },
+      }
+    );
+  }
+  return IOSGestureHandler;
+}
+
+function showIOSBanner(message: string): void {
+  const rootVC = Utils.ios.getRootViewController();
+  if (!rootVC?.view) return;
+  const screen = UIScreen.mainScreen.bounds;
+  const safeBottom = rootVC.view.safeAreaInsets ? rootVC.view.safeAreaInsets.bottom : 0;
+  const width = screen.size.width - 24;
+
+  const container = UIView.alloc().initWithFrame(CGRectMake(12, 0, width, 52));
+  container.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(0.08, 0.08, 0.1, 0.85);
+  container.layer.cornerRadius = 12;
+  container.clipsToBounds = true;
+  container.userInteractionEnabled = true;
+
+  const blur = UIVisualEffectView.alloc().initWithEffect(UIBlurEffect.effectWithStyle(UIBlurEffectStyle.Dark));
+  blur.frame = container.bounds;
+  blur.autoresizingMask = UIViewAutoresizing.FlexibleWidth | UIViewAutoresizing.FlexibleHeight;
+  blur.userInteractionEnabled = false;
+  container.addSubview(blur);
+
+  const label = UILabel.alloc().initWithFrame(CGRectMake(16, 0, width - 32, 52));
+  label.text = message;
+  label.textColor = UIColor.whiteColor;
+  label.textAlignment = NSTextAlignment.Center;
+  label.font = UIFont.systemFontOfSizeWeight(15, UIFontWeightSemibold);
+  blur.contentView.addSubview(label);
+
+  iosTapHandler = iosGestureHandlerClass().alloc().init();
+  container.addGestureRecognizer(UITapGestureRecognizer.alloc().initWithTargetAction(iosTapHandler, 'bannerTapped'));
+  const swipe = UISwipeGestureRecognizer.alloc().initWithTargetAction(iosTapHandler, 'bannerDismissed');
+  swipe.direction = UISwipeGestureRecognizerDirection.Down;
+  container.addGestureRecognizer(swipe);
+
+  container.center = CGPointMake(screen.size.width / 2, screen.size.height - safeBottom - 38);
+  container.alpha = 0;
+  rootVC.view.addSubview(container);
+  iosBanner = container;
+  UIView.animateWithDurationAnimations(0.3, () => (container.alpha = 1));
+}
+
+// ── Android ──────────────────────────────────────────────────────────
+function showAndroidBanner(message: string): void {
+  const activity = Application.android.foregroundActivity || Application.android.startActivity;
+  if (!activity) return;
+  const density = activity.getResources().getDisplayMetrics().density;
+  const pad = Math.round(16 * density);
+
+  const tv = new android.widget.TextView(activity);
+  tv.setText(message);
+  tv.setTextColor(android.graphics.Color.WHITE);
+  tv.setTextSize(15);
+  tv.setPadding(pad, pad, pad, pad);
+  tv.setGravity(android.view.Gravity.CENTER);
+  tv.setBackgroundColor(android.graphics.Color.argb(230, 20, 20, 26));
+
+  // Distinguish a tap (→ reload) from a downward swipe (→ dismiss) on one touch listener.
+  const SWIPE = 40 * density;
+  let downX = 0, downY = 0, downT = 0;
+  tv.setOnTouchListener(new android.view.View.OnTouchListener({
+    onTouch(_v: any, e: any) {
+      switch (e.getActionMasked()) {
+        case android.view.MotionEvent.ACTION_DOWN:
+          downX = e.getRawX(); downY = e.getRawY(); downT = e.getEventTime();
+          return true;
+        case android.view.MotionEvent.ACTION_UP: {
+          const dy = e.getRawY() - downY;
+          const dx = Math.abs(e.getRawX() - downX);
+          const dt = e.getEventTime() - downT;
+          if (dy > SWIPE) dismissBanner();                      // swipe down → dismiss
+          else if (Math.abs(dy) < SWIPE && dx < SWIPE && dt < 400) onTap(); // tap → reload
+          return true;
+        }
+        default:
+          return true;
+      }
+    },
+  }));
+
+  const lp = new android.widget.FrameLayout.LayoutParams(-1, -2); // MATCH_PARENT × WRAP_CONTENT
+  lp.gravity = android.view.Gravity.BOTTOM;
+  activity.addContentView(tv, lp);
+  androidBanner = tv;
+}
+
+function runOnAndroidUi(fn: () => void): void {
+  const activity = Application.android.foregroundActivity || Application.android.startActivity;
+  if (activity) activity.runOnUiThread(new java.lang.Runnable({ run: fn }));
+  else fn();
+}

package/runtime/app/shell/bridge.ts

@@ -39,6 +39,11 @@ export class Bridge {
     this.webView = null;
   }
 
+  /** The attached WebView (for handlers that drive it directly, e.g. app.reload). */
+  getWebView(): CustomWebView | null {
+    return this.webView;
+  }
+
   emit(event: string, payload?: unknown): void {
     this.deliver(JSON.stringify({ v: 1, kind: 'event', event, payload }));
   }
@@ -75,7 +80,8 @@ export class Bridge {
     this.evalJs(js).catch((e) => console.error('Bridge: deliver failed', e));
   }
 
-  private evalJs(script: string): Promise<any> {
+  /** Evaluate JS in the WebView and resolve its value (used by deliver + the dev-menu version probe). */
+  evalJs(script: string): Promise<any> {
     const wv = this.webView;
     return new Promise((resolve, reject) => {
       if (!wv) return reject(new Error('no webview'));

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

@@ -68,7 +68,7 @@ export const MODULES: ModuleManifest[] = [
   { name: 'haptics', core: true, group: 'core', capabilities: { haptics: 'native' } },
   { name: 'share', core: true, group: 'core', capabilities: { share: 'native', shareFiles: 'native' } },
   { name: 'storage', core: true, group: 'core', capabilities: { storage: 'native', secureStorage: 'native' } },
-  { name: 'toast', core: true, group: 'core', capabilities: { toast: 'native' } },
+  { name: 'toast', core: true, group: 'core', capabilities: { toast: 'native', banner: 'native', updates: 'native' } },
   { name: 'statusBar', core: true, group: 'core', capabilities: { statusBar: 'native', themeColor: 'native' } },
   { name: 'device', core: true, group: 'extended', capabilities: { device: 'native' } },
   { name: 'clipboard', core: true, group: 'extended', capabilities: { clipboard: 'native' } },

package/runtime/app/shell/config.ts

@@ -27,6 +27,8 @@ export const SHELL_CONFIG = {
   debug: false,
   /** Value written to `localStorage.DEBUG` in debug mode so the PWA logger goes verbose ('*' = all). */
   debugLog: '*',
+  /** Shake-to-open developer menu (App Info / Reload). On by default, including store builds. */
+  devMenu: true,
   /** Remote push configured, per platform (iOS aps-environment entitlement / Android FCM). Drives the
    * `push` capability flag at runtime by platform — off unless `appwrap.json.push` enables it, so an
    * un-provisioned build honestly reports 'none' (and a personal-team iOS build keeps `pushIos:false`). */

package/runtime/app/shell/devmenu.ts

@@ -0,0 +1,144 @@
+import { Device, Dialogs, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+import { SHELL_CONFIG } from './config';
+import { SHELL_BUILD, reloadWebView } from './handlers';
+
+/**
+ * Shake-to-open developer menu (enabled in prod too, gated by `SHELL_CONFIG.devMenu`).
+ * A shake raises a native action sheet → "App Info" shows non-sensitive diagnostics
+ * (ids, versions, loader, remote host) including the running webapp's version vs. the
+ * latest deployed — so you can tell at a glance whether the device got the update.
+ */
+
+/** Last version info the web side reported (native-kit's updates module). */
+let webInfo: { current?: string; latest?: string; build?: string | number; updateAvailable?: boolean } = {};
+
+export function startDevMenu(): void {
+  // The web side (native-kit updates) pushes its version + the latest-deployed version here.
+  bridge.register('app.reportWebVersion', (p: any) => {
+    webInfo = p || {};
+  });
+  if (isIOS) startIOSShake();
+  else if (isAndroid) startAndroidShake();
+}
+
+// ── shake detection (total acceleration magnitude in g incl. gravity, debounced) ──
+const SHAKE_G = 1.8; // spike vs. ~1g rest
+let shakeMm: any = null; // hold a ref so CoreMotion isn't GC'd
+let firstSpikeAt = 0;
+let spikes = 0;
+let lastMenuAt = 0;
+
+function onAccelMagnitude(g: number): void {
+  if (g < SHAKE_G) return;
+  const now = Date.now();
+  if (now - lastMenuAt < 1500) return; // don't re-open right after a menu
+  if (now - firstSpikeAt > 800) {
+    firstSpikeAt = now; // start a fresh window
+    spikes = 1;
+    return;
+  }
+  if (++spikes >= 2) {
+    spikes = 0;
+    firstSpikeAt = 0;
+    lastMenuAt = now;
+    void showDevMenu();
+  }
+}
+
+function startIOSShake(): void {
+  // Poll `mm.deviceMotion` on a JS timer — CoreMotion's queue-handler block is fragile under
+  // NativeScript (can silently stop firing on-device); mirrors the motion.start handler.
+  const mm = CMMotionManager.new();
+  if (!mm.deviceMotionAvailable) return; // no sensors (simulator)
+  shakeMm = mm;
+  mm.deviceMotionUpdateInterval = 0.1;
+  mm.startDeviceMotionUpdates();
+  setInterval(() => {
+    const m = mm.deviceMotion;
+    if (!m) return; // first sample not ready
+    const x = m.userAcceleration.x + m.gravity.x; // total accel in g (rest ≈ 1)
+    const y = m.userAcceleration.y + m.gravity.y;
+    const z = m.userAcceleration.z + m.gravity.z;
+    onAccelMagnitude(Math.sqrt(x * x + y * y + z * z));
+  }, 100);
+}
+
+function startAndroidShake(): void {
+  const sm = Utils.android
+    .getApplicationContext()
+    .getSystemService(android.content.Context.SENSOR_SERVICE) as android.hardware.SensorManager;
+  const accel = sm.getDefaultSensor(android.hardware.Sensor.TYPE_ACCELEROMETER);
+  if (!accel) return;
+  const G = 9.80665;
+  const listener = new android.hardware.SensorEventListener({
+    onAccuracyChanged() {},
+    onSensorChanged(e: any) {
+      const v = e.values;
+      onAccelMagnitude(Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]) / G);
+    },
+  });
+  sm.registerListener(listener, accel, android.hardware.SensorManager.SENSOR_DELAY_UI);
+}
+
+// ── menu + info ──────────────────────────────────────────────────────
+let menuOpen = false;
+async function showDevMenu(): Promise<void> {
+  if (menuOpen) return; // sensor keeps firing while the sheet is up — don't stack dialogs
+  menuOpen = true;
+  try {
+    const action = await Dialogs.action({
+      title: SHELL_CONFIG.name,
+      message: 'Developer menu',
+      cancelButtonText: 'Cancel',
+      actions: ['App Info', 'Reload'],
+    });
+    if (action === 'App Info') await showInfo();
+    else if (action === 'Reload') reloadWebView();
+  } finally {
+    menuOpen = false;
+  }
+}
+
+async function showInfo(): Promise<void> {
+  // Running web version: prefer what kit.updates reported, else read the page's embedded global
+  // directly — so the line shows for any server-loader app exposing __APP_VERSION__, even if its
+  // native-kit is too old to ship the updates module.
+  const current = webInfo.current || (await readPageVersion());
+  const lines = [
+    `App: ${SHELL_CONFIG.name}`,
+    `ID: ${SHELL_CONFIG.appId}`,
+    `Shell: ${SHELL_CONFIG.version} (${SHELL_BUILD})`,
+    `Platform: ${isIOS ? 'iOS' : 'Android'} ${Device.osVersion}`,
+    `Loader: ${SHELL_CONFIG.loader}`,
+  ];
+  if (SHELL_CONFIG.loader === 'server') lines.push(`Remote: ${safeHost(SHELL_CONFIG.serverUrl)}`);
+
+  const build = webInfo.build ? ` · build ${webInfo.build}` : '';
+  lines.push(`Web version: ${current || 'unknown'}${build}`);
+  if (webInfo.latest && current && webInfo.latest !== current) lines.push(`⚠️ Update available: ${webInfo.latest} — Reload to apply`);
+  else if (webInfo.latest) lines.push('✓ Up to date');
+
+  Dialogs.alert({ title: 'App Info', message: lines.join('\n'), okButtonText: 'Close' });
+}
+
+/** Read the running page's embedded version directly from the WebView: `window.__APP_VERSION__`,
+ * then a `<meta name="app-version">` fallback. '' if neither is present (or eval fails). */
+async function readPageVersion(): Promise<string> {
+  try {
+    const v = await bridge.evalJs(
+      'window.__APP_VERSION__ || document.querySelector(\'meta[name="app-version"]\')?.getAttribute("content") || ""'
+    );
+    return v ? String(v) : '';
+  } catch {
+    return '';
+  }
+}
+
+/** Host[:port] only — strips scheme, path, query, fragment AND any `user:pass@` userinfo, so no
+ * credentials or tokens embedded in the URL ever surface in diagnostics. */
+function safeHost(url: string): string {
+  const afterScheme = String(url || '').replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');
+  const authority = afterScheme.split(/[/?#]/)[0]; // drop path/query/fragment
+  return authority.split('@').pop() || authority; // drop userinfo
+}

package/runtime/app/shell/handlers.ts

@@ -3,12 +3,13 @@ import { bridge } from './bridge';
 import { SHELL_CONFIG } from './config';
 import { onPwaHandshake } from './events';
 import { showToast } from './toast';
+import { showBanner, dismissBanner } from './banner';
 import { setStatusBarStyle } from './status-bar';
 import { buildCapabilityMap } from './capabilities.manifest';
 import { ACTIVE_MODULE_NAMES } from './active-modules.generated';
 
 /** Build identifier for the native shell bundle — bump per deploy to spot stale bundles. */
-export const SHELL_BUILD = 'oauth-media-speaker-1';
+export const SHELL_BUILD = 'updates-devmenu-2';
 
 /** Register all protocol-v1 handlers. */
 export function registerHandlers(): void {
@@ -23,7 +24,7 @@ export function registerHandlers(): void {
     return {
       protocol: 1,
       platform: isIOS ? 'ios' : 'android',
-      app: { id: SHELL_CONFIG.appId, name: SHELL_CONFIG.name, version: SHELL_CONFIG.version, build: SHELL_BUILD },
+      app: { id: SHELL_CONFIG.appId, name: SHELL_CONFIG.name, version: SHELL_CONFIG.version, build: SHELL_BUILD, loader: SHELL_CONFIG.loader },
       debug: { lastNotifTap: safeJson(ApplicationSettings.getString('kit:__notifTap', '')) },
       capabilities,
     };
@@ -127,11 +128,36 @@ export function registerHandlers(): void {
     showToast(String(message ?? ''), duration ?? 'short')
   );
 
+  // Persistent, tappable banner (e.g. the remote-update "tap to reload" prompt). Tap emits
+  // `toast.action` { id } back to the web side.
+  bridge.register('toast.banner', ({ id, message }: { id: string; message: string }) =>
+    showBanner({ id: String(id ?? 'banner'), message: String(message ?? '') })
+  );
+  bridge.register('toast.dismissBanner', () => dismissBanner());
+
+  // Hard reload the WebView, bypassing cache — used by the update banner + dev menu.
+  bridge.register('app.reload', () => reloadWebView());
+
   bridge.register('ui.statusBar.setStyle', ({ style }: { style: 'light' | 'dark' }) =>
     setStatusBarStyle(style)
   );
 }
 
+/** Reload the attached WebView from origin, bypassing the HTTP cache (iOS `reloadFromOrigin`,
+ * Android `clearCache` + `reload`). No-op if no WebView is attached yet. */
+export function reloadWebView(): void {
+  const wv = bridge.getWebView();
+  if (!wv) return;
+  Utils.dispatchToMainThread(() => {
+    if (isIOS && wv.ios) {
+      (wv.ios as WKWebView).reloadFromOrigin();
+    } else if (isAndroid && wv.android) {
+      wv.android.clearCache(true);
+      wv.android.reload();
+    }
+  });
+}
+
 /** Parse a stored JSON breadcrumb; null if absent/unparseable (diagnostic, never throws). */
 function safeJson(s: string): unknown {
   if (!s) return null;

package/src/cli.ts

@@ -358,6 +358,7 @@ export const SHELL_CONFIG = {
   backendOrigin: ${JSON.stringify(cfg.backendOrigin ?? '')},
   debug: ${JSON.stringify(cfg.debug ?? false)},
   debugLog: ${JSON.stringify(cfg.debugLog ?? '*')},
+  devMenu: ${JSON.stringify(cfg.devMenu ?? true)},
   pushIos: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.ios !== false)},
   pushAndroid: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.android !== false)},
 };

package/src/config.ts

@@ -57,6 +57,10 @@ export interface AppwrapConfig {
   /** In debug mode, the value written to `localStorage.DEBUG` at startup so the PWA's logger goes
    * verbose (common convention — `'*'` = all, or comma-separated module names). Default `'*'`. */
   debugLog?: string;
+  /** Shake-to-open developer menu (App Info / Reload). Default `true` — ON in store builds too, since
+   * it only exposes non-sensitive diagnostics (ids, versions, loader, remote host). Set `false` to
+   * disable. Remote-update detection (native-kit `kit.updates`) is independent of this flag. */
+  devMenu?: boolean;
   /** Apple Development Team ID for device builds (Xcode → Settings → Accounts). */
   teamId?: string;
   /** Path (relative to the PWA project) to a StoreKit configuration file for LOCAL IAP

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

@@ -11,7 +11,7 @@ jobs:
       - uses: oven-sh/setup-bun@v2
       - run: bun install
       - run: bun test || echo "no tests"
-      - run: bun run build.ts # → dist/ (the PWA bundle the wrapper ships)
+      - run: bun run build # → dist/ (the PWA bundle the wrapper ships)
 
   ios-build:
     runs-on: macos-15
@@ -21,7 +21,7 @@ jobs:
       - uses: oven-sh/setup-bun@v2
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
-      - run: bun install && bun run build.ts
+      - run: bun install && bun run build
       # Pin global tools — unpinned installs can grab a breaking release mid-flight. Bump deliberately.
       - run: npm i -g nativescript@9.0.6
       - run: bunx @livx.cc/appwrap init # native/ is generated (gitignored) — regenerate it fresh in CI

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

@@ -29,7 +29,7 @@ jobs:
       - uses: actions/setup-java@v4
         with: { distribution: temurin, java-version: 17 }
       - uses: android-actions/setup-android@v3
-      - run: bun install && bun run build.ts        # → dist/ (the PWA bundle the wrapper ships)
+      - run: bun install && bun run build        # → dist/ (the PWA bundle the wrapper ships)
       # Pin global tools — unpinned installs can grab a breaking release mid-flight. Bump deliberately.
       - run: npm i -g nativescript@9.0.6
       - run: bunx @livx.cc/appwrap init                      # native/ is generated (gitignored) — regenerate fresh in CI

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

@@ -31,7 +31,7 @@ jobs:
       - uses: oven-sh/setup-bun@v2
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
-      - run: bun install && bun run build.ts
+      - run: bun install && bun run build
       # Pin global tools — unpinned installs can grab a breaking release mid-flight. Bump deliberately.
       - run: npm i -g nativescript@9.0.6
       - run: bunx @livx.cc/appwrap init # native/ is generated (gitignored) — regenerate it fresh in CI