@livx.cc/appwrap 0.42.2 → 0.42.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.42.2",
+  "version": "0.42.4",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",

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

@@ -31,6 +31,58 @@ function buildBootstrapJs(): string {
   return `${envGlobalsJs()}\n${APPWRAP_GLOBALS_JS}\n${TRANSPORT_SHIM}\n${serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker)}\n${externalNavGuardJs(SHELL_CONFIG.openNewWindowsInBrowser)}\n${NATIVE_FEEL_JS}`;
 }
 
+/**
+ * The extended WebChromeClient MUST be generated ONCE. NativeScript caches the Java proxy
+ * class it synthesizes for `extend({...})` keyed by the methods-object shape, so calling
+ * extend() again per-webview REUSES the first invocation's class — including its captured
+ * closure. A per-instance `owner` WeakRef baked into the closure therefore cross-wires every
+ * later webview's prompt() transport to the FIRST instance (device-proven in the feedox
+ * mini-app spike: webview-2's bridge request was answered as webview-1). Route by the native
+ * view the callback is given instead, resolved against a per-view registry.
+ */
+let chromeClientClass: any;
+function getChromeClientClass(): any {
+  if (chromeClientClass) return chromeClientClass;
+  // NS runtime adds `.extend` on Java classes; it's not in the static typings, hence the cast.
+  chromeClientClass = (android.webkit.WebChromeClient as any).extend({
+    onJsPrompt(
+      view: android.webkit.WebView,
+      _url: string,
+      message: string,
+      _defaultValue: string,
+      result: android.webkit.JsPromptResult
+    ): boolean {
+      if (typeof message === 'string' && message.startsWith(PROMPT_PREFIX)) {
+        result.confirm('');
+        CustomWebView.forNative(view)?.onAppwrapMessage?.(message.slice(PROMPT_PREFIX.length));
+        return true;
+      }
+      return false; // genuine page prompt — default handling
+    },
+
+    // getUserMedia: grant the WebView's per-origin capture after ensuring the
+    // app holds the matching OS runtime permission (CAMERA / RECORD_AUDIO).
+    // No instance state — safe on the shared class.
+    onPermissionRequest(request: android.webkit.PermissionRequest): void {
+      const PR = android.webkit.PermissionRequest;
+      const resources: string[] = Array.from(request.getResources());
+      const perms = new Set<string>();
+      for (const r of resources) {
+        if (r === PR.RESOURCE_VIDEO_CAPTURE) perms.add('android.permission.CAMERA');
+        if (r === PR.RESOURCE_AUDIO_CAPTURE) perms.add('android.permission.RECORD_AUDIO');
+      }
+      if (!perms.size) {
+        Utils.dispatchToMainThread(() => request.grant(request.getResources()));
+        return;
+      }
+      requestPermissions(Array.from(perms)).then((ok) =>
+        Utils.dispatchToMainThread(() => (ok ? request.grant(request.getResources()) : request.deny()))
+      );
+    },
+  });
+  return chromeClientClass;
+}
+
 /**
  * Android CustomWebView — replaces NS's default clients after creation:
  * WebChromeClient.onJsPrompt is the appwrap transport, WebViewClient
@@ -41,6 +93,18 @@ export class CustomWebView extends WebView {
   /** Set by the bridge before load; receives raw envelope JSON. */
   onAppwrapMessage: ((json: string) => void) | null = null;
 
+  // Native-view → owning CustomWebView, keyed by the Java identity hash (stable per native
+  // object, robust to NS re-wrapping the arg passed into the ChromeClient callback). WeakRef
+  // so a destroyed view can be GC'd; entry pruned on dispose.
+  private static registry = new Map<number, WeakRef<CustomWebView>>();
+  static forNative(view: android.webkit.WebView): CustomWebView | undefined {
+    const owner = CustomWebView.registry.get(view.hashCode())?.deref();
+    // identityHashCode is not unique: on a (rare) collision the map holds the LAST writer —
+    // re-check native identity so a colliding view drops rather than cross-wires.
+    if (owner && owner.android !== view) return undefined;
+    return owner;
+  }
+
   initNativeView(): void {
     super.initNativeView();
     // NS core types the `.android` getter as `any`; narrow to the real WebView for this scope.
@@ -68,7 +132,15 @@ export class CustomWebView extends WebView {
 
     this.installDocumentStartShim(wv);
     wv.setWebViewClient(createAssetServingClient());
-    wv.setWebChromeClient(this.createTransportChromeClient());
+    // Bind THIS native view to THIS instance before wiring the (shared, extend-once) client.
+    CustomWebView.registry.set(wv.hashCode(), new WeakRef<CustomWebView>(this));
+    wv.setWebChromeClient(new (getChromeClientClass())());
+  }
+
+  disposeNativeView(): void {
+    const wv = this.android as android.webkit.WebView | undefined;
+    if (wv) CustomWebView.registry.delete(wv.hashCode());
+    super.disposeNativeView();
   }
 
   /**
@@ -115,52 +187,15 @@ export class CustomWebView extends WebView {
       console.warn('AppWrap: addDocumentStartJavaScript failed', e);
     }
   }
-
-  private createTransportChromeClient(): android.webkit.WebChromeClient {
-    const owner = new WeakRef<CustomWebView>(this);
-    // NS runtime adds `.extend` on Java classes; it's not in the static typings, hence the cast.
-    const ChromeClient = (android.webkit.WebChromeClient as any).extend({
-      onJsPrompt(
-        _view: android.webkit.WebView,
-        _url: string,
-        message: string,
-        _defaultValue: string,
-        result: android.webkit.JsPromptResult
-      ): boolean {
-        if (typeof message === 'string' && message.startsWith(PROMPT_PREFIX)) {
-          result.confirm('');
-          const view = owner.get ? owner.get() : (owner as { deref(): CustomWebView }).deref();
-          view?.onAppwrapMessage?.(message.slice(PROMPT_PREFIX.length));
-          return true;
-        }
-        return false; // genuine page prompt — default handling
-      },
-
-      // getUserMedia: grant the WebView's per-origin capture after ensuring the
-      // app holds the matching OS runtime permission (CAMERA / RECORD_AUDIO).
-      onPermissionRequest(request: android.webkit.PermissionRequest): void {
-        const PR = android.webkit.PermissionRequest;
-        const resources: string[] = Array.from(request.getResources());
-        const perms = new Set<string>();
-        for (const r of resources) {
-          if (r === PR.RESOURCE_VIDEO_CAPTURE) perms.add('android.permission.CAMERA');
-          if (r === PR.RESOURCE_AUDIO_CAPTURE) perms.add('android.permission.RECORD_AUDIO');
-        }
-        if (!perms.size) {
-          Utils.dispatchToMainThread(() => request.grant(request.getResources()));
-          return;
-        }
-        requestPermissions(Array.from(perms)).then((ok) =>
-          Utils.dispatchToMainThread(() => (ok ? request.grant(request.getResources()) : request.deny()))
-        );
-      },
-    });
-    return new ChromeClient();
-  }
 }
 
-/** https://appwrap.local/<path> → file under www/; SPA fallback to the entry for extension-less misses. */
+/** https://appwrap.local/<path> → file under www/; SPA fallback to the entry for extension-less misses.
+ * Extend-once (same NS shape-caching pitfall as the ChromeClient above): the closure here is
+ * process-constant, but generating the class per webview would silently pin the FIRST call's
+ * closure anyway — build it once and reuse. */
+let assetClientClass: any;
 function createAssetServingClient(): android.webkit.WebViewClient {
+  if (assetClientClass) return new assetClientClass();
   const wwwPath = nsPath.join(knownFolders.currentApp().path, 'www');
 
   const respond = (filePath: string, ext: string): android.webkit.WebResourceResponse => {
@@ -246,7 +281,7 @@ function createAssetServingClient(): android.webkit.WebViewClient {
   };
 
   // NS runtime adds `.extend` on Java classes; it's not in the static typings, hence the cast.
-  const Client = (android.webkit.WebViewClient as any).extend({
+  assetClientClass = (android.webkit.WebViewClient as any).extend({
     // Modern (API 21+) overload passes a WebResourceRequest; the legacy overload passed a string URL.
     // We defensively handle both, so the param is the union.
     shouldInterceptRequest(
@@ -305,5 +340,5 @@ function createAssetServingClient(): android.webkit.WebViewClient {
       }
     },
   });
-  return new Client();
+  return new assetClientClass();
 }

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

@@ -97,18 +97,36 @@ export function registerAndroidHandlers(): void {
     }
   });
 
+  // NS caches the Java proxy class synthesized by .extend({...}) by the methods-object SHAPE, so
+  // re-extending per call would permanently bake in the FIRST call's resolve/reject closure — every
+  // later authenticate would settle the first (already-settled) promise and hang its own. Extend once
+  // and route through a mutable slot (only one biometric prompt can be active at a time).
+  let biometricCallbackClass: any;
+  let biometricPending: { resolve: (v: unknown) => void; reject: (e: unknown) => void } | null = null;
+  const getBiometricCallbackClass = () => {
+    if (biometricCallbackClass) return biometricCallbackClass;
+    biometricCallbackClass = (androidx.biometric.BiometricPrompt.AuthenticationCallback as any).extend({
+      onAuthenticationSucceeded(_result: any) {
+        biometricPending?.resolve({ success: true });
+        biometricPending = null;
+      },
+      onAuthenticationError(_code: number, message: any) {
+        biometricPending?.reject(err('DENIED', String(message ?? 'authentication error')));
+        biometricPending = null;
+      },
+    });
+    return biometricCallbackClass;
+  };
+
   bridge.register('biometrics.authenticate', ({ reason }: { reason?: string }) => {
     return new Promise((resolve, reject) => {
       Utils.dispatchToMainThread(() => {
         try {
           const act = activity(); // NativeScriptActivity extends AppCompatActivity → FragmentActivity
           const executor = androidx.core.content.ContextCompat.getMainExecutor(act);
-          const Callback = (androidx.biometric.BiometricPrompt.AuthenticationCallback as any).extend({
-            onAuthenticationSucceeded(_result: any) { resolve({ success: true }); },
-            onAuthenticationError(_code: number, message: any) {
-              reject(err('DENIED', String(message ?? 'authentication error')));
-            },
-          });
+          biometricPending?.reject(err('DENIED', 'superseded by a new biometric prompt'));
+          biometricPending = { resolve, reject };
+          const Callback = getBiometricCallbackClass();
           const prompt = new androidx.biometric.BiometricPrompt(act, executor, new Callback());
           const info = new androidx.biometric.BiometricPrompt.PromptInfo.Builder()
             .setTitle(String(reason ?? 'Authenticate'))
@@ -117,6 +135,7 @@ export function registerAndroidHandlers(): void {
             .build();
           prompt.authenticate(info);
         } catch (e: any) {
+          if (biometricPending?.reject === reject) biometricPending = null;
           reject(err('UNSUPPORTED', e?.message ?? String(e)));
         }
       });

package/runtime/webpack.config.js

@@ -14,6 +14,26 @@ module.exports = (env) => {
   webpack.init(env);
 
   webpack.chainWebpack((config) => {
+    // node:-scheme imports: pure-JS deps (e.g. @noble/hashes) conditionally probe Node builtins via
+    // the `node:` scheme, which webpack cannot even READ ("UnhandledSchemeError: Reading from
+    // 'node:crypto' is not handled by plugins") — the whole NS build fails. Strip the scheme so the
+    // request becomes a bare builtin name…
+    const { NormalModuleReplacementPlugin } = require('webpack');
+    config.plugin('AppwrapStripNodeScheme').use(NormalModuleReplacementPlugin, [
+      /^node:/,
+      (resource) => {
+        resource.request = resource.request.replace(/^node:/, '');
+      },
+    ]);
+    // …then stub every Node builtin the NS runtime doesn't have to an empty module (fallback: false),
+    // so conditional probes resolve gracefully instead of "Module not found". `module` is excluded:
+    // @nativescript/webpack maps it to its own polyfill and that must keep winning.
+    config.resolve.merge({
+      fallback: Object.fromEntries(
+        require('module').builtinModules.filter((m) => m !== 'module').map((m) => [m, false])
+      ),
+    });
+
     // Ship the PWA bundle inside the app package
     config.plugin('CopyWww').use(CopyWebpackPlugin, [
       {

package/src/cli.ts

@@ -2,7 +2,7 @@
 /**
  * appwrap CLI v0 — scaffold a native wrapper around a built PWA.
  *
- *   appwrap init [--config <path>] [--out native]   # from the PWA project dir
+ *   appwrap init [--config <path>] [--out native] [--ci]   # from the PWA project dir; --ci also scaffolds GH Actions workflows
  *   appwrap sync [--config <path>] [--out native]   # re-copy PWA dist into the wrapper
  *
  * Config (TS preferred, JSON fallback) — probed in order: appwrap.config.ts → .js → appwrap.json.
@@ -592,7 +592,11 @@ function stampTeamId(outDir: string, cfg: AppwrapConfig, ctx?: { cwd: string; co
   writeFileSync(xcconfig, src);
 }
 
-interface ProvProfile { name: string; uuid: string; teamId: string; bundleId: string; exp: number }
+/** Profile kind, derived from the .mobileprovision payload: ProvisionsAllDevices → enterprise;
+ * ProvisionedDevices + get-task-allow → development; ProvisionedDevices w/o it → adhoc; else appstore. */
+type ProvKind = 'development' | 'adhoc' | 'enterprise' | 'appstore';
+
+interface ProvProfile { name: string; uuid: string; teamId: string; bundleId: string; exp: number; kind: ProvKind }
 
 /** Discover provisioning profiles installed on this machine (both the legacy MobileDevice dir and
  * the modern Xcode UserData dir). Each is decoded with `security cms` and reduced to the fields we
@@ -623,7 +627,11 @@ function findProvisioningProfiles(): ProvProfile[] {
         if (!name || !uuid || !team || !appId || byUuid.has(uuid)) continue;
         // application-identifier is `<TEAM>.<bundle.id>`; strip the team prefix to get the bundle id.
         const bundleId = appId.startsWith(team + '.') ? appId.slice(team.length + 1) : appId;
-        byUuid.set(uuid, { name, uuid, teamId: team, bundleId, exp: expStr ? Date.parse(expStr) : 0 });
+        const kind: ProvKind = /<key>ProvisionsAllDevices<\/key>\s*<true\s*\/>/.test(raw) ? 'enterprise'
+          : /<key>ProvisionedDevices<\/key>/.test(raw)
+            ? (/<key>get-task-allow<\/key>\s*<true\s*\/>/.test(raw) ? 'development' : 'adhoc')
+            : 'appstore';
+        byUuid.set(uuid, { name, uuid, teamId: team, bundleId, exp: expStr ? Date.parse(expStr) : 0, kind });
       } catch { /* skip unreadable profile */ }
     }
   }
@@ -635,10 +643,14 @@ function findProvisioningProfiles(): ProvProfile[] {
  * pinned) → newest-expiry (headless). Returns null when nothing matches (caller warns + skips). */
 function selectSigningProfile(
   profiles: ProvProfile[], teamId: string, bundleId: string, cfg: AppwrapConfig,
-  ctx?: { configPath: string },
+  ctx?: { configPath: string }, kind: ProvKind | 'device' = 'device',
 ): string | null {
   const now = Date.now();
-  const matches = profiles.filter((p) => p.teamId === teamId && p.bundleId === bundleId && p.exp > now);
+  // 'appstore' (store archive) must sign with an App Store distribution profile; 'device' (deploy)
+  // must NOT — an appstore profile can't install on a device. Filtering here is what keeps ONE
+  // signingProfiles pin map safe: a pin of the wrong kind simply doesn't match this lane.
+  const kindOk = (p: ProvProfile): boolean => (kind === 'device' ? p.kind !== 'appstore' : p.kind === kind);
+  const matches = profiles.filter((p) => p.teamId === teamId && p.bundleId === bundleId && p.exp > now && kindOk(p));
   if (matches.length === 0) return null;
   const pinned = cfg.signingProfiles?.[bundleId];
   if (pinned && matches.some((p) => p.name === pinned)) return pinned;
@@ -678,14 +690,31 @@ function stampManualSigning(outDir: string, cfg: AppwrapConfig, ctx?: { configPa
     console.warn('  ⚠ signing: manual but teamId is unset — skipping manual signing.');
     return;
   }
+  // Store archives (`appwrap build ios --release`) sign with App Store distribution profiles +
+  // "Apple Distribution"; device deploys with development/adhoc profiles + "Apple Development".
+  // A signing-DISABLED archive that's re-signed at exportArchive gets its entitlements SYNTHESIZED
+  // from the profile (dropping app.entitlements — e.g. declared-age-range); signing the archive
+  // itself is what preserves them, so the store lane rides this same manual stamp.
+  const kind: ProvKind | 'device' = process.env.APPWRAP_SIGNING_KIND === 'appstore' ? 'appstore' : 'device';
+  const identity = kind === 'appstore' ? 'Apple Distribution' : 'Apple Development';
+  // Don't pin interactive picks from the store lane — the single signingProfiles map is keyed by
+  // bundle id only, so a store pin would clobber the device pin (and vice versa).
+  const pinCtx = kind === 'device' ? ctx : undefined;
   const profiles = findProvisioningProfiles();
   let mainProvision: string | null = null;
 
   // Main app target → build.xcconfig.
   const xcconfig = join(outDir, 'App_Resources/iOS/build.xcconfig');
   if (existsSync(xcconfig)) {
-    const name = selectSigningProfile(profiles, teamId, cfg.id, cfg, ctx);
+    const name = selectSigningProfile(profiles, teamId, cfg.id, cfg, pinCtx, kind);
     if (!name) {
+      // Store lane must NOT fall through to automatic signing: an unsigned archive gets its
+      // entitlements re-synthesized from the profile at export, silently dropping any
+      // config-stamped entitlement (the declared-age-range failure this lane exists to prevent).
+      if (kind === 'appstore') {
+        console.error(`  ✗ no valid App Store distribution profile for ${cfg.id} (team ${teamId}). Install one (ASC → Profiles) or seed via Xcode, then retry.`);
+        process.exit(1);
+      }
       console.warn(`  ⚠ no valid profile for ${cfg.id} (team ${teamId}) — automatic signing will run. Install one or seed via Xcode.`);
     } else {
       mainProvision = name;
@@ -696,10 +725,10 @@ function stampManualSigning(outDir: string, cfg: AppwrapConfig, ctx?: { configPa
           ? s.replace(new RegExp(`^\\s*${key}\\s*=\\s*[^;\\n]*;?`, 'm'), `${key} = ${val};`)
           : s + `\n${key} = ${val};`;
       src = setKey(src, 'CODE_SIGN_STYLE', 'Manual');
-      src = setKey(src, 'CODE_SIGN_IDENTITY', 'Apple Development');
+      src = setKey(src, 'CODE_SIGN_IDENTITY', identity);
       src = setKey(src, 'PROVISIONING_PROFILE_SPECIFIER', name);
       writeFileSync(xcconfig, src.endsWith('\n') ? src : src + '\n');
-      console.log(`  sign ← ${cfg.id} → "${name}" (manual)`);
+      console.log(`  sign ← ${cfg.id} → "${name}" (manual, ${identity})`);
     }
   }
 
@@ -715,7 +744,7 @@ function stampManualSigning(outDir: string, cfg: AppwrapConfig, ctx?: { configPa
       if (!ext.isDirectory()) continue;
       if (!existsSync(join(extRoot, ext.name, 'extension.json'))) continue;
       const extBundle = `${cfg.id}.${ext.name}`;
-      const name = selectSigningProfile(profiles, teamId, extBundle, cfg, ctx);
+      const name = selectSigningProfile(profiles, teamId, extBundle, cfg, pinCtx, kind);
       if (!name) { console.warn(`  ⚠ no valid profile for extension ${extBundle} — it may fail to sign.`); continue; }
       extEntries.push({ bundleId: extBundle, profile: name });
       console.log(`  sign ← ${extBundle} → "${name}" (manual, via hook)`);
@@ -725,7 +754,7 @@ function stampManualSigning(outDir: string, cfg: AppwrapConfig, ctx?: { configPa
   const hookFile = join(hookDir, 'appwrap-signing.js');
   if (extEntries.length) {
     mkdirSync(hookDir, { recursive: true });
-    writeFileSync(hookFile, SIGNING_HOOK(teamId, extEntries));
+    writeFileSync(hookFile, SIGNING_HOOK(teamId, extEntries, identity));
     // NS's exportOptions reads extension profiles from this file (extensions/provisioning.json) —
     // it maps each extension bundle id → profile name so `xcodebuild -exportArchive` can build the .ipa.
     writeFileSync(join(extRoot, 'provisioning.json'),
@@ -751,11 +780,12 @@ function stampManualSigning(outDir: string, cfg: AppwrapConfig, ctx?: { configPa
  * Self-contained (no deps), zero-arg (NS DI won't choke). Per extension it upserts DEVELOPMENT_TEAM,
  * PROVISIONING_PROFILE_SPECIFIER, CODE_SIGN_STYLE=Manual, CODE_SIGN_IDENTITY in every buildSettings
  * block whose PRODUCT_BUNDLE_IDENTIFIER matches the extension's bundle id. */
-const SIGNING_HOOK = (team: string, entries: Array<{ bundleId: string; profile: string }>) => `// Generated by \`appwrap\` — stamps manual signing onto extension targets in project.pbxproj.
+const SIGNING_HOOK = (team: string, entries: Array<{ bundleId: string; profile: string }>, identity = 'Apple Development') => `// Generated by \`appwrap\` — stamps manual signing onto extension targets in project.pbxproj.
 const fs = require('fs');
 const path = require('path');
 const TEAM = ${JSON.stringify(team)};
 const ENTRIES = ${JSON.stringify(entries)};
+const IDENTITY = ${JSON.stringify(identity)};
 module.exports = function () {
   const iosDir = path.join(__dirname, '..', '..', 'platforms', 'ios');
   if (!fs.existsSync(iosDir)) return;
@@ -781,7 +811,7 @@ module.exports = function () {
       block = block.replace(/^\\s*PROVISIONING_PROFILE\\s*=\\s*[^;\\n]*;\\n?/m, '');
       block = upsert(block, 'CODE_SIGN_STYLE', 'Manual');
       block = upsert(block, 'DEVELOPMENT_TEAM', TEAM);
-      block = upsert(block, 'CODE_SIGN_IDENTITY', q('Apple Development'));
+      block = upsert(block, 'CODE_SIGN_IDENTITY', q(IDENTITY));
       block = upsert(block, 'PROVISIONING_PROFILE_SPECIFIER', q(profile));
       return block;
     });
@@ -1384,22 +1414,25 @@ export function isFrameworkRepo(root: string): boolean {
   return existsSync(join(root, 'packages/appwrap-cli/src/cli.ts'));
 }
 
-/** Emit CI scaffolding (GH Actions → git repo root, fastlane → native/).
+/** Emit CI scaffolding (GH Actions → git repo root ONLY with --ci, fastlane → native/).
+ * Writing `.github/workflows` into a consumer repo is a repo-level side effect (it can shadow or
+ * clash with the project's own CI), so it is OPT-IN via `appwrap init --ci` — never implicit.
  * GH workflows are never overwritten (users may customize them). The fastlane lane IS appwrap-managed
  * (the release recipe, not for hand-editing — see AGENTS.md), so it is RE-EMITTED on `--force` to keep
  * the recipe current after a framework upgrade; without --force it's still first-time-only. */
-function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force = false): void {
+function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force = false, withWorkflows = false): void {
   if (!existsSync(CI_TEMPLATE_DIR)) return;
   const repoRoot = gitRoot(cwd);
   // GitHub only reads `.github/workflows` at the REPO ROOT — in a monorepo, writing it under the
   // package cwd (e.g. packages/app/.github) is dead config and regenerates a stray workflow each init.
   // [from, to, overwritable]
   const targets: Array<[string, string, boolean]> = [[join(CI_TEMPLATE_DIR, 'fastlane'), join(outDir, 'fastlane'), force]];
-  // …but if the repo root IS the appwrap framework itself (in-repo example), DON'T scaffold consumer
-  // workflows into the framework's .github — that's the stray-workflow-each-init bug.
-  if (isFrameworkRepo(repoRoot)) {
+  // Even with --ci: if the repo root IS the appwrap framework itself (in-repo example), DON'T scaffold
+  // consumer workflows into the framework's .github — that's the stray-workflow-each-init bug.
+  const scaffoldWorkflows = withWorkflows && !isFrameworkRepo(repoRoot);
+  if (withWorkflows && !scaffoldWorkflows) {
     console.log('  ci   ← GH Actions scaffold skipped (inside the appwrap framework repo — manages its own CI)');
-  } else {
+  } else if (scaffoldWorkflows) {
     targets.unshift([join(CI_TEMPLATE_DIR, 'github/workflows'), join(repoRoot, '.github/workflows'), false]);
   }
   for (const [from, to, overwrite] of targets) {
@@ -1409,7 +1442,7 @@ function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force
   // Pin the emitted workflow's `bunx @livx.cc/appwrap@^x.y.z` to THIS CLI's version floor, so a CI run
   // using a freshly-emitted workflow can't silently resolve an older published build that lacks the
   // `init`/`release` commands (it would 404 loudly instead). Idempotent: re-init finds no placeholder.
-  if (!isFrameworkRepo(repoRoot)) {
+  if (scaffoldWorkflows) {
     const wf = join(repoRoot, '.github/workflows/appwrap-release-ios.yml');
     if (existsSync(wf)) writeFileSync(wf, readFileSync(wf, 'utf8').replaceAll('__APPWRAP_VERSION__', CLI_VERSION));
   }
@@ -1424,9 +1457,9 @@ function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force
       .replaceAll('__TEAM_ID__', cfg.teamId ?? '');
     writeFileSync(p, stamped);
   }
-  const ci = isFrameworkRepo(repoRoot)
-    ? '  ci   ← fastlane (native/fastlane, signing stamped) — see secrets contract in workflow headers'
-    : '  ci   ← GH Actions (.github/workflows) + fastlane (native/fastlane, signing stamped) — see secrets contract in workflow headers';
+  const ci = scaffoldWorkflows
+    ? '  ci   ← GH Actions (.github/workflows) + fastlane (native/fastlane, signing stamped) — see secrets contract in workflow headers'
+    : '  ci   ← fastlane (native/fastlane, signing stamped) — GH Actions workflows are opt-in: `appwrap init --ci`';
   console.log(ci);
 }
 
@@ -1547,7 +1580,7 @@ async function init(cwd: string, flags: Record<string, string>): Promise<void> {
   console.log(`🎁 appwrap init → ${outDir}`);
   mkdirSync(outDir, { recursive: true });
   regenerateCore(cwd, outDir, cfg, { firstRun: true, flags });
-  copyCiTemplates(cwd, outDir, cfg, 'force' in flags); // GH workflows: first-time only; fastlane lane: re-emit on --force
+  copyCiTemplates(cwd, outDir, cfg, 'force' in flags, 'ci' in flags); // GH workflows: opt-in (--ci), first-time only; fastlane lane: re-emit on --force
   writeFileSync(join(outDir, '.gitignore'), 'node_modules/\nplatforms/\nhooks/\n');
   applyOverrides(cwd, outDir, cfg); // escape hatch — last, so custom native code wins
   stampManualSigning(outDir, cfg, { configPath: resolveConfigPath(cwd, flags) }); // AFTER overrides: a consumer's extension.json / build.xcconfig would otherwise clobber the signing stamp
@@ -1918,13 +1951,29 @@ async function build(cwd: string, flags: Record<string, string>, positionals: st
     console.error(`✖ ${(e as Error).message}`);
     process.exit(1);
   }
+  const release = 'release' in flags;
+  // iOS release archive = the STORE artifact. With signing:'manual', stamp App Store distribution
+  // signing (profile kind 'appstore' + "Apple Distribution") so xcodebuild archives a SIGNED binary —
+  // an unsigned archive re-signed at exportArchive gets its entitlements SYNTHESIZED from the
+  // provisioning profile, silently dropping app.entitlements (e.g. declared-age-range).
+  if (platform === 'ios' && release) process.env.APPWRAP_SIGNING_KIND = 'appstore';
   // Make sure the wrapper reflects the latest config + PWA before compiling (also validates the config).
   await sync(cwd, flags);
 
-  const release = 'release' in flags;
   const args = ['build', platform];
   if (release) args.push('--release');
-  if (platform === 'ios' && release) args.push('--for-device');
+  if (platform === 'ios' && release) {
+    args.push('--for-device');
+    // Manual signing: pass the resolved App Store profile so NS emits a manual exportOptions.plist
+    // (app + extensions via extensions/provisioning.json) for `xcodebuild -exportArchive`. The export
+    // method comes from the archive's embedded profile (Distribution → app-store), so this yields a
+    // store .ipa whose entitlements are the archive's own (app.entitlements intact).
+    const sidecar = join(outDir, '.appwrap-signing.json');
+    if (existsSync(sidecar)) {
+      const sc = JSON.parse(readFileSync(sidecar, 'utf8')) as { provision?: string };
+      if (sc.provision) args.push('--provision', sc.provision);
+    }
+  }
   if (platform === 'android' && 'aab' in flags) args.push('--aab');
 
   if (platform === 'android' && release) {
@@ -1949,7 +1998,8 @@ async function build(cwd: string, flags: Record<string, string>, positionals: st
   console.log(`▶ ns ${args.join(' ').replace(/(--key-store-password|--key-store-alias-password) [^ ]*/g, '$1 ****')}  (cwd: ${outDir})`);
   execFileSync('ns', args, { cwd: outDir, stdio: 'inherit' });
   if (platform === 'ios' && release) {
-    console.log('ℹ App Store distribution (archive + upload) goes through the fastlane release lane (native/fastlane) — needs a paid team + ASC API key.');
+    const ipa = join(outDir, 'platforms/ios/build/Release-iphoneos');
+    console.log(`ℹ Signed store .ipa in ${ipa} — upload via \`bunx @livx.cc/mcp-appstores apple-upload\` or the fastlane release lane (native/fastlane).`);
   }
 }