@livx.cc/appwrap 0.20.4 → 0.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.20.4",
+  "version": "0.23.1",
   "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,8 +11,9 @@ 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 { bindStatusBarPage, setStatusBarStyle, applyThemeColor, enableAndroidEdgeToEdge, wireAndroidSafeArea } from './shell/status-bar';
 import { CustomWebView } from './shell/custom-webview';
 
 let initialized = false;
@@ -22,6 +23,7 @@ export function onPageLoaded(args: EventData): void {
   page.bindingContext = { backgroundColor: SHELL_CONFIG.backgroundColor };
   bindStatusBarPage(page);
   if (isAndroid) enableAndroidEdgeToEdge();
+  applyThemeColor(SHELL_CONFIG.themeColor); // manifest/config theme_color → native chrome at boot
   setStatusBarStyle(SHELL_CONFIG.statusBarStyle);
 
   if (initialized) return;
@@ -44,6 +46,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' } },
@@ -163,6 +163,9 @@ export const MODULES: ModuleManifest[] = [
       permissions: [
         { key: 'NSHealthShareUsageDescription', domain: 'health', defaultUsage: 'Read your step count from the Health app.' },
         { key: 'NSHealthUpdateUsageDescription', domain: 'health', defaultUsage: 'Read your step count from the Health app.' },
+        // Live step stream (health.liveSteps) uses CMPedometer (CoreMotion) → iOS terminates the app
+        // on access without this Motion & Fitness usage string. Required for the real-time count.
+        { key: 'NSMotionUsageDescription', domain: 'motion', defaultUsage: 'Count your steps live as you walk.' },
       ],
       entitlements: { 'com.apple.developer.healthkit': true },
     },

package/runtime/app/shell/config.ts

@@ -9,8 +9,15 @@ export const SHELL_CONFIG = {
   entry: 'index.html',
   /** Page + status bar background while the WebView boots. */
   backgroundColor: '#0b1020',
+  /** Boot-time native chrome color (status bar / safe areas), from `appwrap.json.themeColor` or the
+   * PWA manifest `theme_color`. Empty = leave the root un-tinted (page backgroundColor shows through).
+   * Applied at boot via the same root-view tint `kit.ui.syncThemeColor()` uses at runtime. */
+  themeColor: '',
   /** 'light' = white status bar icons. */
   statusBarStyle: 'light' as 'light' | 'dark',
+  /** Supported orientation (config > manifest). Drives the iOS AppDelegate orientation mask at boot
+   * (which overrides Info.plist) + is stamped to Android `screenOrientation`. '' = free rotation. */
+  orientation: '' as '' | 'portrait' | 'landscape' | 'any',
   /** Android only (experimental). true = WebView draws edge-to-edge under transparent bars +
    * safe-area insets injected as `--saie-*` CSS vars; false = bars show the page backgroundColor. */
   edgeToEdge: false,
@@ -27,6 +34,12 @@ 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,
+  /** Neutralize `navigator.serviceWorker.register` in the native shell (a SW serves stale caches and
+   * fights the app:// handler / remote-update detection). On by default; set false to opt out and keep
+   * the SW (e.g. for in-WebView web-push). See `serviceWorkerGuardJs`. */
+  neutralizeServiceWorker: 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/custom-webview.android.ts

@@ -1,7 +1,7 @@
 import { WebView, Utils, knownFolders, path as nsPath, File } from '@nativescript/core';
 import { SHELL_CONFIG } from './config';
 import { mimeFor } from './mime';
-import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS } from './web-quirks';
+import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, serviceWorkerGuardJs } from './web-quirks';
 import { envGlobalsJs } from './env';
 import { requestPermissions } from './android-helpers';
 
@@ -27,7 +27,7 @@ const PROMPT_PREFIX = '__appwrap__:';
  * native-feel. Globals first so the page can read __APPWRAP__ / __APPWRAP_BACKEND_ORIGIN__ before its
  * own scripts run. Built lazily (not a const) so envGlobalsJs() detects against a live activity context. */
 function buildBootstrapJs(): string {
-  return `${envGlobalsJs()}\n${APPWRAP_GLOBALS_JS}\n${TRANSPORT_SHIM}\n${NATIVE_FEEL_JS}`;
+  return `${envGlobalsJs()}\n${APPWRAP_GLOBALS_JS}\n${TRANSPORT_SHIM}\n${serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker)}\n${NATIVE_FEEL_JS}`;
 }
 
 /**

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

@@ -1,7 +1,7 @@
 import { WebView, knownFolders, path as nsPath, File } from '@nativescript/core';
 import { SHELL_CONFIG } from './config';
 import { mimeFor } from './mime';
-import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, mediaCaptureGuardJs } from './web-quirks';
+import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, mediaCaptureGuardJs, serviceWorkerGuardJs } from './web-quirks';
 import { envGlobalsJs } from './env';
 import { createUiDelegate } from './ios-ui-delegate';
 import { appwrapNativeLog } from './native-log';
@@ -55,7 +55,8 @@ export class CustomWebView extends WebView {
     // __APPWRAP__ / __APPWRAP_BACKEND_ORIGIN__.
     const hasPlistKey = (k: string) => !!NSBundle.mainBundle.objectForInfoDictionaryKey(k);
     const mediaGuard = mediaCaptureGuardJs(hasPlistKey('NSCameraUsageDescription'), hasPlistKey('NSMicrophoneUsageDescription'));
-    for (const src of [envGlobalsJs(), APPWRAP_GLOBALS_JS, mediaGuard, NATIVE_FEEL_JS]) {
+    const swGuard = serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker);
+    for (const src of [envGlobalsJs(), APPWRAP_GLOBALS_JS, mediaGuard, swGuard, NATIVE_FEEL_JS]) {
       const script = WKUserScript.alloc().initWithSourceInjectionTimeForMainFrameOnly(
         src,
         WKUserScriptInjectionTime.AtDocumentStart,

package/runtime/app/shell/devmenu.ts

@@ -0,0 +1,140 @@
+import { Device, Dialogs, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+import { SHELL_CONFIG } from './config';
+import { SHELL_BUILD, reloadWebView, getReportedWebVersion } 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.
+ * The web version status is reported via the always-on `app.reportWebVersion` handler
+ * (in handlers.ts) — independent of this menu — and read here when the menu is shown.
+ */
+
+export function startDevMenu(): void {
+  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 webInfo = getReportedWebVersion();
+  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-health.ts

@@ -4,6 +4,7 @@ import { requestPermissions, startActivityForResult } from './android-helpers';
 
 declare const android: any;
 declare const cc: any; // generated from the HealthConnectBridge.kt shim (overrides/)
+declare const CMPedometer: any; // CoreMotion (already linked via CMMotionManager in handlers-parity)
 
 const err = (code: string, message: string) => Object.assign(new Error(message), { code });
 
@@ -66,6 +67,41 @@ function registerIos(): void {
       store.executeQuery(q);
     })
   );
+
+  // ── Live steps (CMPedometer) — low-latency "as you walk" count, distinct from the laggy HealthKit
+  // aggregate. Caller uses HealthKit as the periodic source-of-truth and these live deltas in between.
+  // Emits `health.liveStep` { steps } (today's pedometer total since local midnight). iPhone-only
+  // (no Watch), which is fine: it's the live driver; HealthKit re-anchors the authoritative total.
+  let pedometer: any = null;
+  let anchorDay = -1; // local day-of-month the current stream is anchored to (for midnight re-anchor)
+  const localDay = () => new Date().getDate();
+  const startStream = () => {
+    anchorDay = localDay();
+    pedometer.startPedometerUpdatesFromDateWithHandler(startOfToday(), (data: any, e: any) => {
+      if (e || !data) return;
+      // Midnight self-heal: CMPedometer counts since the FIXED anchor date, so after local midnight
+      // numberOfSteps still includes yesterday. When the day rolls over, restart from the new
+      // midnight (re-anchors to 0) so the live count stays "today only".
+      if (localDay() !== anchorDay) { Utils.dispatchToMainThread(() => { pedometer.stopPedometerUpdates(); startStream(); bridge.emit('health.liveStep', { steps: 0 }); }); return; }
+      const steps = Math.round(num(data.numberOfSteps));
+      Utils.dispatchToMainThread(() => bridge.emit('health.liveStep', { steps }));
+    });
+  };
+  bridge.register('health.liveSteps.start', () => {
+    if (typeof CMPedometer === 'undefined' || !CMPedometer.isStepCountingAvailable())
+      throw err('UNSUPPORTED', 'Pedometer (live step counting) unavailable on this device');
+    // Motion & Fitness denied/restricted → surface it so the caller can fall back to HealthKit instead
+    // of silently receiving no events. (2 = denied, 1 = restricted per CMAuthorizationStatus.)
+    const auth = typeof CMPedometer.authorizationStatus === 'function' ? CMPedometer.authorizationStatus() : 0;
+    if (auth === 2 || auth === 1) throw err('DENIED', 'Motion & Fitness access is off for live step counting');
+    if (pedometer) return; // already streaming
+    pedometer = CMPedometer.new();
+    startStream();
+  });
+  bridge.register('health.liveSteps.stop', () => {
+    pedometer?.stopPedometerUpdates();
+    pedometer = null;
+  });
 }
 
 function registerAndroid(): void {

package/runtime/app/shell/handlers.ts

@@ -3,12 +3,19 @@ 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-3';
+
+/** Version status the web side (native-kit `kit.updates`) reports via `app.reportWebVersion`. */
+export interface WebVersionInfo { current?: string; latest?: string; build?: string | number; updateAvailable?: boolean; }
+let lastWebVersion: WebVersionInfo = {};
+/** Latest version status the web reported — read by the dev-menu App Info screen. */
+export function getReportedWebVersion(): WebVersionInfo { return lastWebVersion; }
 
 /** Register all protocol-v1 handlers. */
 export function registerHandlers(): void {
@@ -23,7 +30,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 +134,41 @@ 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());
+
+  // Web → native version report (native-kit `kit.updates`). Registered ALWAYS — independent of
+  // `devMenu` — so server-loader update polling never invokes an UNSUPPORTED handler (which would
+  // warn every poll) when the dev menu is off. The dev-menu App Info screen reads it when shown.
+  bridge.register('app.reportWebVersion', (p: WebVersionInfo) => { lastWebVersion = p || {}; });
+
   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/runtime/app/shell/orientation.ts

@@ -4,6 +4,8 @@
  * `screen.orientation.*` handlers. Raw UIInterfaceOrientationMask bit values
  * (1 << UIInterfaceOrientation) so no ambient UIKit types are needed.
  */
+import { SHELL_CONFIG } from './config';
+
 export const ORIENTATION_MASK = {
   portrait: 1 << 1, // 2
   portraitUpsideDown: 1 << 2, // 4
@@ -13,7 +15,11 @@ export const ORIENTATION_MASK = {
   allButUpsideDown: (1 << 1) | (1 << 3) | (1 << 4), // 26 — default, free rotation sans upside-down
 };
 
-let iosMask = ORIENTATION_MASK.allButUpsideDown;
+// Init from the configured/manifest orientation (config > manifest → stamped into SHELL_CONFIG). The
+// AppDelegate's `supportedInterfaceOrientationsForWindow` returns this mask and OVERRIDES the static
+// Info.plist `UISupportedInterfaceOrientations` at runtime — so locking orientation requires setting
+// the mask here, not just stamping the plist. `kit.screen.orientation.lock()` still overrides at runtime.
+let iosMask = maskForLock((SHELL_CONFIG as { orientation?: string }).orientation || 'any');
 
 /** The mask the AppDelegate reports to UIKit. */
 export function iosOrientationMask(): number {

package/runtime/app/shell/status-bar.ts

@@ -108,6 +108,27 @@ export function bindStatusBarPage(page: Page): void {
   currentPage = page;
 }
 
+/**
+ * Tint the native root (the chrome behind the page — status bar / safe areas) to a CSS color. This is
+ * the SAME surface the `ui.setBackgroundColor` handler / `kit.ui.syncThemeColor()` drive at runtime; we
+ * apply the manifest/config `themeColor` through it at boot so the chrome is themed before the WebView
+ * paints (no white flash, no un-themed safe areas). No-op for an empty color (leave the page bg).
+ */
+export function applyThemeColor(color: string): void {
+  if (!color) return;
+  const root = Application.getRootView();
+  if (!root) return;
+  // `color` is a PWA-manifest `theme_color` (or appwrap.json) — dev free-text, NOT validated upstream.
+  // `new Color()` THROWS on a value it can't parse, and this runs at boot (onPageLoaded), so an
+  // unsupported/malformed color (e.g. an unrecognized CSS form) would abort the rest of shell init.
+  // Degrade gracefully: log + leave the default page background rather than crash the launch.
+  try {
+    root.backgroundColor = new Color(String(color));
+  } catch (e) {
+    console.warn('[appwrap] invalid themeColor, leaving default:', color, (e as Error)?.message ?? e);
+  }
+}
+
 /** 'light' = white icons/text (for dark backgrounds), 'dark' = black. */
 export function setStatusBarStyle(style: 'light' | 'dark'): void {
   if (isIOS) {

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

@@ -71,6 +71,54 @@ export function mediaCaptureGuardJs(camera: boolean, microphone: boolean): strin
 })();`;
 }
 
+/**
+ * Neutralize `navigator.serviceWorker.register` inside the native shell at document-start, so a
+ * consumer PWA doesn't have to hand-gate its own SW. Inside the shell a service worker is at best
+ * useless and at worst HARMFUL: a cache-first SW serves a stale bundle and fights the native app://
+ * scheme handler / loader:'server' remote-update detection.
+ *
+ * SEMANTICS (and why):
+ *  - We patch ONLY `register` — leave `navigator.serviceWorker` (and its `.ready`/`.controller`/event
+ *    surface) in place. Removing `serviceWorker` entirely would lie to feature-detection: `if
+ *    ('serviceWorker' in navigator)` stays true (the SW *API* exists; this WebView genuinely supports
+ *    it), but no SW ever activates because every `register` is a no-op. Well-written PWAs treat
+ *    register() as best-effort.
+ *  - `register()` returns a PROMISE THAT NEVER RESOLVES (and never rejects). This is the gentlest of
+ *    the three options: resolving with a fake registration would hand back a lying object whose
+ *    `.update()`/`.unregister()`/`.active` consumers might call; rejecting fires `.catch()` paths that
+ *    many apps log as an error or retry in a loop. A pending promise means `.then(...)` simply never
+ *    runs (no controller, no stale cache — the desired end state) and `.catch(...)` never fires (no
+ *    uncaught error, no error spam). `navigator.serviceWorker.ready` is likewise a never-settling
+ *    promise per spec until a SW is ready, so leaving it pending matches normal "no SW yet" behavior.
+ *  - We ALSO best-effort `getRegistrations().then(rs => rs.forEach(r => r.unregister()))` to tear down
+ *    any SW a PREVIOUS web/PWA session already installed for this origin (otherwise a pre-existing
+ *    cache-first SW keeps serving stale content even though we now block new registrations).
+ *  - Touches `navigator.serviceWorker` ONLY. `Worker` / `SharedWorker` are deliberately untouched —
+ *    compute-offload workers legitimately run in a WebView.
+ *
+ * NOTE: neutralizing the SW also disables WEB push (web push needs a SW). That's expected and fine —
+ * native push is the `remote-push` lane (APNs/FCM), and the push-prompt UI already gates on
+ * `kit.is.native`. No push code needs to change.
+ *
+ * `enabled` = the resolved neutralize flag (SHELL_CONFIG.neutralizeServiceWorker, default true in
+ * native; set false via appwrap config to opt out and leave the SW fully intact). Idempotent via a
+ * window guard so double-injection (e.g. Android's onPageStarted fallback) is a no-op.
+ */
+export function serviceWorkerGuardJs(enabled: boolean): string {
+  if (!enabled) return '';
+  return `(function(){
+  var sw = navigator.serviceWorker;
+  if (!sw || !sw.register || window.__appwrapSwGuard) return;
+  window.__appwrapSwGuard = true;
+  // Tear down any SW a prior web session installed for this origin (stops it serving a stale cache).
+  try { sw.getRegistrations && sw.getRegistrations().then(function(rs){ rs.forEach(function(r){ try { r.unregister(); } catch (e) {} }); }).catch(function(){}); } catch (e) {}
+  // register() → a promise that never settles: .then() never runs (no SW activates) and .catch()
+  // never fires (no error spam / retry loops). Feature-detection ('serviceWorker' in navigator) and
+  // .ready stay truthful — the API exists, nothing ever becomes ready.
+  sw.register = function(){ return new Promise(function(){}); };
+})();`;
+}
+
 /**
  * Native-feel injection shared by both CustomWebViews. Suppresses the "it's a
  * web page" tells: pinch / double-tap zoom, long-press callout & selection,

package/src/cli.ts

@@ -20,6 +20,13 @@ import type * as CapManifest from '../../../runtime/app/shell/capabilities.manif
 // Config shape lives in its own import-safe module so a `appwrap.config.ts` file can import the
 // type + `defineConfig` helper without pulling in (and running) the CLI dispatch.
 import type { AppwrapConfig } from './config';
+import {
+  androidScreenOrientation,
+  iosOrientations,
+  mergeManifest,
+  stampAndroidOrientation,
+  stampPlistOrientations,
+} from './derive';
 
 /** 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. */
@@ -323,14 +330,8 @@ async function loadConfig(cwd: string, flags: Record<string, string>): Promise<A
   const cfg = await readConfigFile(configPath);
 
   // Manifest as source: the appwrap config wins, the PWA manifest fills the gaps, template default last.
-  // (DRY single-source — devs don't re-type identity already declared in the manifest.)
-  if (cfg.pwaDist) {
-    const mf = loadManifest(cwd, cfg);
-    if (mf) {
-      cfg.name ??= mf.name || mf.short_name;
-      cfg.backgroundColor ??= mf.background_color;
-    }
-  }
+  // (DRY single-source — devs don't re-type identity already declared in the manifest.) See mergeManifest.
+  if (cfg.pwaDist) mergeManifest(cfg, loadManifest(cwd, cfg));
 
   for (const key of ['id', 'name', 'version', 'pwaDist'] as const) {
     if (!cfg[key]) {
@@ -351,13 +352,17 @@ export const SHELL_CONFIG = {
   version: ${JSON.stringify(cfg.version)},
   entry: ${JSON.stringify(cfg.entry ?? 'index.html')},
   backgroundColor: ${JSON.stringify(cfg.backgroundColor ?? '#ffffff')},
+  themeColor: ${JSON.stringify(cfg.themeColor ?? '')},
   statusBarStyle: ${JSON.stringify(cfg.statusBarStyle ?? 'dark')} as 'light' | 'dark',
+  orientation: ${JSON.stringify(cfg.orientation ?? '')} as '' | 'portrait' | 'landscape' | 'any',
   edgeToEdge: ${JSON.stringify(cfg.edgeToEdge ?? false)},
   loader: ${JSON.stringify(cfg.loader ?? 'app')} as 'app' | 'file' | 'server',
   serverUrl: ${JSON.stringify(cfg.serverUrl ?? '')},
   backendOrigin: ${JSON.stringify(cfg.backendOrigin ?? '')},
   debug: ${JSON.stringify(cfg.debug ?? false)},
   debugLog: ${JSON.stringify(cfg.debugLog ?? '*')},
+  devMenu: ${JSON.stringify(cfg.devMenu ?? true)},
+  neutralizeServiceWorker: ${JSON.stringify(cfg.neutralizeServiceWorker ?? true)},
   pushIos: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.ios !== false)},
   pushAndroid: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.android !== false)},
 };
@@ -384,6 +389,10 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
   stamp('CFBundleShortVersionString', cfg.version); // marketing version (user-facing)
   stamp('CFBundleVersion', String(buildNumberOf(cfg))); // monotonic build — store re-uploads need it higher
 
+  // Supported orientation (config > manifest) — rewrites both UISupportedInterfaceOrientations
+  // arrays (iPhone + ~ipad). Skipped when unset → keep the template's free-rotation default.
+  if (cfg.orientation) src = stampPlistOrientations(src, iosOrientations(cfg.orientation));
+
   // Permission usage strings + URL scheme + export-compliance — idempotent: strip stamped block, re-add
   src = src.replace(/\s*<!-- appwrap:begin -->[\s\S]*?<!-- appwrap:end -->/g, '');
   const extras: string[] = [];
@@ -608,6 +617,9 @@ function stampAndroidAppName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
   if (existsSync(manifest)) {
     let src = readFileSync(manifest, 'utf8');
     if (cfg.urlScheme) src = src.replace(/android:scheme="[^"]*"/, `android:scheme="${cfg.urlScheme}"`);
+    // Supported orientation (config > manifest) on the main <activity>. Skipped when unset → keep
+    // the template default (free); 'any' removes the attribute, so re-sync stays idempotent.
+    if (cfg.orientation) src = stampAndroidOrientation(src, androidScreenOrientation(cfg.orientation));
     // Permissions — idempotent: rewrite the marker block from the active modules (deduped).
     const perms = req.androidPerms.map((p) => `\t<uses-permission android:name="${p}"/>`);
     src = src.replace(
@@ -1144,7 +1156,13 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
   console.log(`▶ installing ${ipa} → ${device.name} [${device.transport}]`);
   try {
     // Capture (not inherit) so we can recognize specific failures; echo it for visibility.
-    const out = execFileSync('xcrun', ['devicectl', 'device', 'install', 'app', '--device', device.id, ipaPath], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] });
+    // Wrapped so a LOCKED device waits-and-retries instead of hard-failing (the common annoyance).
+    // --timeout: devicectl has no first-class "wait for unlock", but its overall-timeout lets a single
+    // attempt tolerate a brief locked/unavailable window before erroring; the outer retry covers the
+    // fail-fast case + the unlock prompt. (Verified against `devicectl --help`; community wraps it too.)
+    const out = withUnlockRetry('Install', () =>
+      execFileSync('xcrun', ['devicectl', 'device', 'install', 'app', '--timeout', '25', '--device', device.id, ipaPath], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] })
+    );
     process.stdout.write(out);
   } catch (e: any) {
     const log = `${e?.stdout ?? ''}${e?.stderr ?? ''}`;
@@ -1161,7 +1179,7 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
       );
     } else {
       console.error(
-        '✖ Install failed. Usually the device is LOCKED or only on Wi-Fi.\n' +
+        '✖ Install failed (device still locked after waiting, or only on Wi-Fi).\n' +
           '  → Unlock the phone (and plug in USB for a reliable connection), then re-run.\n' +
           `  The built .ipa is ready: ${ipaPath}`
       );
@@ -1172,14 +1190,35 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
   if (!('no-launch' in flags)) {
     console.log(`▶ launching ${cfg.id}`);
     try {
-      execFileSync('xcrun', ['devicectl', 'device', 'process', 'launch', '--device', device.id, cfg.id], { stdio: 'inherit' });
+      withUnlockRetry('Launch', () =>
+        execFileSync('xcrun', ['devicectl', 'device', 'process', 'launch', '--timeout', '25', '--device', device.id, cfg.id], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] })
+      );
     } catch {
-      console.error('⚠ Launch failed (device locked?). The app is installed — unlock and tap it, or re-run.');
+      console.error('⚠ Launch failed (still locked after waiting). The app is installed — unlock and tap it, or re-run.');
     }
   }
   console.log(`✓ Deployed to ${device.name}.`);
 }
 
+/** Run a devicectl op; if it fails because the device is LOCKED (or transiently unavailable), prompt
+ * once and poll-retry until it succeeds or the budget runs out — instead of hard-failing. A free-team
+ * 3-app-limit error is NOT a lock, so it's re-thrown immediately for the caller's specific handling.
+ * (We can't auto-unlock — that needs the passcode by design — but we can wait gracefully.) */
+function withUnlockRetry<T>(label: string, run: () => T, tries = 40, delayMs = 3000): T {
+  for (let i = 0; ; i++) {
+    try {
+      return run();
+    } catch (e: any) {
+      const log = `${e?.stdout ?? ''}${e?.stderr ?? ''}`;
+      if (/maximum number of installed apps|MIInstallerErrorDomain error 13|ApplicationVerificationFailed/.test(log)) throw e;
+      if (i >= tries) throw e;
+      if (i === 0) process.stdout.write(`\n🔒 ${label}: device unavailable — unlock your iPhone. Waiting (auto-retries every ${delayMs / 1000}s, up to ${Math.round((tries * delayMs) / 1000)}s)…\n`);
+      else process.stdout.write(`  …waiting for unlock (${i}/${tries})\n`);
+      try { execFileSync('sleep', [String(delayMs / 1000)], { stdio: 'ignore' }); } catch { /* sleep interrupted */ }
+    }
+  }
+}
+
 /** First connected libimobiledevice UDID (USB, then network). Distinct from devicectl's identifier. */
 function libimobiledeviceUdid(): { udid: string; network: boolean } | null {
   for (const [args, network] of [[['-l'], false], [['-n'], true]] as const) {

package/src/config.ts

@@ -24,6 +24,16 @@ export interface AppwrapConfig {
   entry?: string;
   backgroundColor?: string;
   statusBarStyle?: 'light' | 'dark';
+  /** Boot-time native chrome color (status bar / safe areas behind the page). Falls back to the PWA
+   * manifest's `theme_color` when absent. The shell tints the native root with it at launch (the
+   * same surface `kit.ui.syncThemeColor()` keeps in sync with `<meta name="theme-color">` at runtime)
+   * — distinct from `backgroundColor`, which paints the page/splash. CSS color string (e.g. `#0b1020`). */
+  themeColor?: string;
+  /** Supported device orientation. Falls back to the PWA manifest's `orientation` when absent
+   * (`*-primary`/`*-secondary` variants normalize to the axis). `portrait` / `landscape` lock the
+   * axis; `any` (default) leaves rotation free (sans upside-down on iOS). Stamped into iOS
+   * `UISupportedInterfaceOrientations` (+ `~ipad`) and Android `android:screenOrientation`. */
+  orientation?: 'portrait' | 'landscape' | 'any';
   /** Android only (experimental). When true, the WebView draws genuinely edge-to-edge UNDER the
    * transparent system bars (NS `androidOverflowEdge='dont-apply'`) and the real safe-area insets
    * are injected as `--saie-*` CSS vars + native `env(safe-area-inset-*)`, so a multi-theme PWA
@@ -57,6 +67,18 @@ 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;
+  /** Neutralize `navigator.serviceWorker.register` in the native shell so the consumer PWA doesn't
+   * have to gate its own SW. Inside the shell a service worker is useless-to-harmful: a cache-first SW
+   * serves a stale bundle and fights the native app:// scheme handler / loader:'server' remote-update
+   * detection. Default `true` (only affects the native build — the same web build is untouched).
+   * Set `false` to opt out and leave the SW fully intact — e.g. if the PWA intentionally wants its SW
+   * for in-WebView web-push as a fallback. NOTE: keeping the SW is the only way to get web push; native
+   * push is the separate `push` lane (APNs/FCM) and does NOT need a SW. */
+  neutralizeServiceWorker?: 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/src/derive.ts

@@ -0,0 +1,99 @@
+/**
+ * Pure manifest-derivation + native-stamp transforms — kept side-effect-free (no fs, no config I/O)
+ * so they unit-test against fixture strings, same standard as the urlScheme stamper. The CLI wires
+ * these into `loadConfig` (derivation) + the iOS/Android stampers (transforms).
+ */
+
+/** Normalized appwrap orientation — the three lock states the native shells can express. */
+export type Orientation = 'portrait' | 'landscape' | 'any';
+
+/** The PWA web-manifest fields appwrap derives from (a subset; everything optional). */
+export interface WebManifest {
+  name?: string;
+  short_name?: string;
+  background_color?: string;
+  theme_color?: string;
+  orientation?: string;
+}
+
+/**
+ * "Manifest as source" merge: explicit appwrap-config values WIN, the PWA manifest fills the gaps,
+ * the template default lands last (downstream `?? default` in the stampers). Mutates + returns `cfg`
+ * — the precedence is `??` (only an `undefined` field is filled), so this is purely additive and
+ * never overrides a value the dev wrote. Pure (no fs): the CLI loads the manifest, this merges it.
+ */
+export function mergeManifest<
+  T extends {
+    name?: string;
+    backgroundColor?: string;
+    themeColor?: string;
+    orientation?: Orientation;
+  }
+>(cfg: T, mf: WebManifest | null | undefined): T {
+  if (!mf) return cfg;
+  cfg.name ??= mf.name || mf.short_name;
+  cfg.backgroundColor ??= mf.background_color;
+  cfg.themeColor ??= mf.theme_color;
+  // normalize the manifest's portrait-primary / landscape-secondary / … to our axis lock.
+  if (cfg.orientation === undefined && mf.orientation) cfg.orientation = normalizeOrientation(mf.orientation);
+  return cfg;
+}
+
+/**
+ * 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
+ * a single-edge lock at the app level (a PWA wrapper either constrains an axis or leaves it free), so
+ * any portrait* → portrait, any landscape* → landscape, everything else (incl. `any`/absent) → any.
+ */
+export function normalizeOrientation(raw: string | undefined | null): Orientation {
+  const v = (raw ?? '').trim().toLowerCase();
+  if (v.startsWith('portrait')) return 'portrait';
+  if (v.startsWith('landscape')) return 'landscape';
+  return 'any'; // 'any' | 'natural' | '' | unknown → don't over-constrain
+}
+
+/** iOS `UISupportedInterfaceOrientations` array members for a normalized orientation. */
+export function iosOrientations(o: Orientation): string[] {
+  if (o === 'portrait') return ['UIInterfaceOrientationPortrait'];
+  if (o === 'landscape')
+    return ['UIInterfaceOrientationLandscapeLeft', 'UIInterfaceOrientationLandscapeRight'];
+  // 'any' → free rotation sans upside-down (matches the orientation.ts ALL_BUT_UPSIDE_DOWN mask).
+  return [
+    'UIInterfaceOrientationPortrait',
+    'UIInterfaceOrientationLandscapeLeft',
+    'UIInterfaceOrientationLandscapeRight',
+  ];
+}
+
+/** Android `android:screenOrientation` value for a normalized orientation. */
+export function androidScreenOrientation(o: Orientation): string {
+  if (o === 'portrait') return 'portrait';
+  if (o === 'landscape') return 'landscape';
+  return 'unspecified'; // system free rotation
+}
+
+/**
+ * Rewrite EVERY `UISupportedInterfaceOrientations` (+ the `~ipad` variant the template also sets)
+ * array body in an Info.plist string to the given members. Pure string transform — operates on the
+ * source it's handed, returns the new source. Keyed by `<key>` name so it touches only those arrays.
+ */
+export function stampPlistOrientations(src: string, orientations: string[]): string {
+  const body = orientations.map((o) => `\t\t<string>${o}</string>`).join('\n');
+  return src.replace(
+    /(<key>UISupportedInterfaceOrientations(?:~ipad)?<\/key>\s*<array>)[\s\S]*?(<\/array>)/g,
+    (_m, open, close) => `${open}\n${body}\n\t${close}`
+  );
+}
+
+/**
+ * Set (or remove) `android:screenOrientation` on the FIRST (main/launcher) `<activity …>` opening tag
+ * in an AndroidManifest.xml string. `unspecified` removes the attribute (system default = free).
+ * Pure + idempotent: an existing attribute is replaced, otherwise injected after `android:name`.
+ */
+export function stampAndroidOrientation(src: string, value: string): string {
+  return src.replace(/<activity\b[^>]*>/, (tag) => {
+    const stripped = tag.replace(/\s*android:screenOrientation="[^"]*"/, '');
+    if (value === 'unspecified') return stripped;
+    return stripped.replace(/(android:name="[^"]*")/, `$1\n\t\t\tandroid:screenOrientation="${value}"`);
+  });
+}

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