@livx.cc/appwrap 0.21.0 → 0.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.21.0",
+  "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

@@ -13,7 +13,7 @@ import './shell/fcm-bootstrap.generated'; // side-effect: registers the FCM serv
 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;
@@ -23,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;

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

@@ -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,
@@ -29,6 +36,10 @@ export const SHELL_CONFIG = {
   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

@@ -1,23 +1,18 @@
 import { Device, Dialogs, Utils, isAndroid, isIOS } from '@nativescript/core';
 import { bridge } from './bridge';
 import { SHELL_CONFIG } from './config';
-import { SHELL_BUILD, reloadWebView } from './handlers';
+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.
  */
 
-/** 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();
 }
@@ -104,6 +99,7 @@ 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}`,

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

@@ -9,7 +9,13 @@ 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 = 'updates-devmenu-2';
+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 {
@@ -138,6 +144,11 @@ export function registerHandlers(): void {
   // 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)
   );

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,7 +352,9 @@ 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 ?? '')},
@@ -359,6 +362,7 @@ export const SHELL_CONFIG = {
   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)},
 };
@@ -385,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[] = [];
@@ -609,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(
@@ -1145,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 ?? ''}`;
@@ -1162,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}`
       );
@@ -1173,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
@@ -61,6 +71,14 @@ export interface AppwrapConfig {
    * 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}"`);
+  });
+}