@livx.cc/appwrap 0.40.0 → 0.40.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.40.0",
+  "version": "0.40.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_Resources/iOS/Info.plist

@@ -50,11 +50,9 @@
 		<key>NSAllowsLocalNetworking</key>
 		<true/>
 	</dict>
-	<!-- Background audio so music-player PWAs keep playing when backgrounded /
-	     screen-locked. Remove for apps that never play audio in the background. -->
-	<key>UIBackgroundModes</key>
-	<array>
-		<string>audio</string>
-	</array>
+	<!-- No UIBackgroundModes by default. Declaring a mode with no matching feature is an App Store
+	     2.5.4 rejection, so modules stamp only what they need: push → `remote-notification`,
+	     backgroundTask → `fetch`+`processing`, config `backgroundAudio:true` → `audio` (each creates
+	     the key if absent). Keep the default clean; apps opt into capabilities in appwrap.config. -->
 </dict>
 </plist>

package/src/cli.ts

@@ -33,6 +33,7 @@ import {
   stampPlistBackgroundTasks,
   stampPlistOrientations,
   stampPrivacyTracking,
+  stripEmptyBackgroundModes,
 } from './derive';
 import type { WebManifest } from './derive';
 
@@ -510,19 +511,25 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
     );
   }
 
-  // Remote push needs the `remote-notification` background mode. The template already ships a
-  // UIBackgroundModes array (for `audio`), so MERGE in-place — a second <key> would be a duplicate
-  // (invalid plist). Idempotent both ways: add when enabled+missing, strip when disabled.
-  const iosPush = !!cfg.push?.enabled && cfg.push?.ios !== false;
+  // UIBackgroundModes is opt-in per module/config (the template ships none). Toggle each mode in the
+  // shared array — a second <key> would be a duplicate (invalid plist). Idempotent both ways: MERGE
+  // in-place (creating the key when absent) if wanted, strip when not.
   const bgArray = /(<key>UIBackgroundModes<\/key>\s*<array>)([\s\S]*?)(<\/array>)/;
-  const hasRN = /<string>remote-notification<\/string>/.test(src);
-  if (iosPush && !hasRN) {
-    src = bgArray.test(src)
-      ? src.replace(bgArray, (_m, open, inner, close) => `${open}${inner}\t<string>remote-notification</string>\n\t${close}`)
-      : src.replace(/<\/dict>\s*<\/plist>\s*$/, `  <key>UIBackgroundModes</key>\n  <array>\n    <string>remote-notification</string>\n  </array>\n</dict>\n</plist>\n`);
-  } else if (!iosPush && hasRN) {
-    src = src.replace(/\s*<string>remote-notification<\/string>/, '');
-  }
+  const toggleBgMode = (s: string, mode: string, want: boolean): string => {
+    const has = new RegExp(`<string>${mode}</string>`).test(s);
+    if (want && !has) {
+      return bgArray.test(s)
+        ? s.replace(bgArray, (_m, open, inner, close) => `${open}${inner}\t<string>${mode}</string>\n\t${close}`)
+        : s.replace(/<\/dict>\s*<\/plist>\s*$/, `  <key>UIBackgroundModes</key>\n  <array>\n    <string>${mode}</string>\n  </array>\n</dict>\n</plist>\n`);
+    }
+    if (!want && has) return s.replace(new RegExp(`\\s*<string>${mode}</string>`), '');
+    return s;
+  };
+  // Remote push needs `remote-notification`; apps that genuinely play audio in the background opt in
+  // via `backgroundAudio: true` (Apple 2.5.4 rejects `audio` without a real background-audio feature).
+  src = toggleBgMode(src, 'remote-notification', !!cfg.push?.enabled && cfg.push?.ios !== false);
+  src = toggleBgMode(src, 'audio', !!cfg.backgroundAudio);
+  src = stripEmptyBackgroundModes(src);
 
   writeFileSync(plist, src);
 }

package/src/config.ts

@@ -164,6 +164,11 @@ export interface AppwrapConfig {
    * same ids are what `kit.backgroundTask.register(id, …)` / `.schedule({id})` use. No-op when absent
    * or the module is inactive. */
   backgroundTasks?: string[];
+  /** Opt in to the `audio` UIBackgroundMode — ONLY for apps that genuinely keep playing audio while
+   * backgrounded/screen-locked (music/streaming/podcast players). Off by default: declaring `audio`
+   * without a real background-audio feature is an App Store 2.5.4 rejection. Stamps `audio` into
+   * Info.plist UIBackgroundModes when true; no-op/stripped when absent. */
+  backgroundAudio?: boolean;
   /** Remote push (APNs/FCM). Off unless set — gating matters: an `aps-environment` entitlement on a
    * team that can't hold the Push capability (e.g. a personal team) BREAKS code signing, and the
    * handshake should honestly report `push: 'none'` on an un-provisioned build. The kit returns a raw

package/src/derive.ts

@@ -195,20 +195,15 @@ export function stampAndroidOrientation(src: string, value: string): string {
  * `remote-notification`). `ids` empty/undefined → strips the block + removes the two modes it added.
  */
 export function stampPlistBackgroundTasks(src: string, ids: string[] | undefined): string {
-  // 1) Always rewrite the marker block (permitted identifiers). Strip first → idempotent.
+  // 1) Strip the marker block first (idempotent). It is re-added LAST (step 3) so its position is
+  //    stable regardless of whether the UIBackgroundModes array below was pre-existing or freshly
+  //    created — otherwise the marker and a created array flip order between runs (non-idempotent).
   src = src.replace(/\s*<!-- appwrap:bgtask -->[\s\S]*?<!-- \/appwrap:bgtask -->/g, '');
   const list = (ids ?? []).filter(Boolean);
-  if (list.length) {
-    const items = list.map((s) => `    <string>${s}</string>`).join('\n');
-    const block =
-      `  <!-- appwrap:bgtask -->\n` +
-      `  <key>BGTaskSchedulerPermittedIdentifiers</key>\n  <array>\n${items}\n  </array>\n` +
-      `  <!-- /appwrap:bgtask -->`;
-    src = src.replace(/<\/dict>\s*<\/plist>\s*$/, `${block}\n</dict>\n</plist>\n`);
-  }
 
-  // 2) Merge/remove the fetch + processing background modes (separate from the marker — they live in
-  //    the shared UIBackgroundModes array, which may also hold audio/remote-notification).
+  // 2) Merge/remove the fetch + processing background modes — they live in the shared
+  //    UIBackgroundModes array (which may also hold audio/remote-notification). Create the key when
+  //    absent; strip the two modes (and, via stripEmptyBackgroundModes, the emptied key) when off.
   const modes = ['fetch', 'processing'];
   const bgArray = /(<key>UIBackgroundModes<\/key>\s*<array>)([\s\S]*?)(<\/array>)/;
   if (list.length) {
@@ -225,9 +220,26 @@ export function stampPlistBackgroundTasks(src: string, ids: string[] | undefined
   } else {
     for (const m of modes) src = src.replace(new RegExp(`\\s*<string>${m}</string>`), '');
   }
+  src = stripEmptyBackgroundModes(src);
+
+  // 3) Re-add the permitted-identifiers marker block LAST, right before </dict> (stable position).
+  if (list.length) {
+    const items = list.map((s) => `    <string>${s}</string>`).join('\n');
+    const block =
+      `  <!-- appwrap:bgtask -->\n` +
+      `  <key>BGTaskSchedulerPermittedIdentifiers</key>\n  <array>\n${items}\n  </array>\n` +
+      `  <!-- /appwrap:bgtask -->`;
+    src = src.replace(/<\/dict>\s*<\/plist>\s*$/, `${block}\n</dict>\n</plist>\n`);
+  }
   return src;
 }
 
+/** Remove a now-empty `UIBackgroundModes` key+array so a plist that opts into no modes carries no
+ * dangling empty key (keeps the default tidy). Pure + idempotent; no-op when the array has members. */
+export function stripEmptyBackgroundModes(src: string): string {
+  return src.replace(/\s*<key>UIBackgroundModes<\/key>\s*<array>\s*<\/array>/g, '');
+}
+
 /**
  * Stamp (or strip) `WKAppBoundDomains` in an Info.plist string — Apple's gate for running a service
  * worker inside a WKWebView (paired with `limitsNavigationsToAppBoundDomains` on the config). Pure +