@livx.cc/appwrap 0.58.2 → 0.58.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.58.2",
+  "version": "0.58.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_Resources/Android/app.gradle

@@ -14,7 +14,7 @@ android {
 
   defaultConfig {
     minSdkVersion 26 // Android 8.0 — Health Connect's floor (~99% of devices); was 24
-    targetSdkVersion 35
+    targetSdkVersion 36 // Play requires target API 36 (Android 16) from 31 Aug 2026
 
     // Version Information
     versionCode 2

package/runtime/app/main-page.ts

@@ -1,4 +1,4 @@
-import { Application, AndroidApplication, EventData, Page, isAndroid, isIOS, knownFolders, path } from '@nativescript/core';
+import { Application, AndroidApplication, Button, EventData, LoadEventData, Page, StackLayout, WebView, isAndroid, isIOS, knownFolders, path } from '@nativescript/core';
 import { bridge } from './shell/bridge';
 import { effectiveServerUrl } from './shell/server-url';
 import { registerHandlers } from './shell/handlers';
@@ -126,6 +126,7 @@ export function onPageLoaded(args: EventData): void {
   // if a future surface orphans a window with no dismiss callback — gate it on a "surface presented" flag.
   void armNativeSurfaceRecovery; // referenced to keep the helper (still callable if a scoped need arises)
   if (isAndroid) wireAndroidSafeArea(webView); // experimental edge-to-edge (no-op unless config on)
+  wireLoadFallback(page, webView); // loader:'server' failure → branded retry view (no white screen)
   startEventForwarding();
   loadBundle(webView);
   // Env indicator banner: shown in the bottom safe area on relaunch when a non-default env override is
@@ -167,6 +168,58 @@ export function onPageLoaded(args: EventData): void {
   }
 }
 
+/**
+ * loader:'server' load-failure fallback (App Review 2.1a). A server-loader shell has NO local UI —
+ * if the serverUrl is unreachable (offline, server down, DNS) the reviewer sees a bare white screen.
+ * NS core forwards BOTH webView:didFailNavigation: and didFailProvisionalNavigation: (iOS) and the
+ * main-frame onReceivedError (Android) into `loadFinishedEvent` with `args.error` — so one listener
+ * covers initial-load and in-app navigation failures on both platforms. On failure: show a simple
+ * branded "can't connect — retry" view + auto-retry with capped backoff; any successful load hides
+ * it and resets. iOS NSURLErrorCancelled ("cancelled", a superseded navigation) is NOT a failure.
+ * NOTE: web-process termination has no NS seam in a prod build (the didTerminate forwarder lives on
+ * the debug-only DevCertNavDelegate) — out of scope here.
+ */
+function wireLoadFallback(page: Page, webView: CustomWebView): void {
+  if (SHELL_CONFIG.loader !== 'server') return; // bundled loaders can't fail on network
+  const fallback = page.getViewById<StackLayout>('loadFallback');
+  const retryBtn = page.getViewById<Button>('loadRetryBtn');
+  if (!fallback || !retryBtn) return;
+
+  let retryTimer: ReturnType<typeof setTimeout> | null = null;
+  let backoffMs = 3000;
+  const clearTimer = () => { if (retryTimer) { clearTimeout(retryTimer); retryTimer = null; } };
+  const retry = () => {
+    clearTimer();
+    appwrapNativeLog('[native:fallback] retrying server load');
+    // Android: loadBundle sets `src`, but re-setting the SAME value is a NS property no-op — drive
+    // the native reload directly. iOS's loadBundle path issues a fresh loadRequest, so reuse it.
+    const droid = isAndroid ? (webView.android as android.webkit.WebView | null) : null;
+    if (droid) droid.loadUrl(effectiveServerUrl());
+    else loadBundle(webView);
+  };
+
+  webView.on(WebView.loadFinishedEvent, (args: LoadEventData) => {
+    const err = String(args.error ?? '');
+    if (!err) {
+      // successful load → hide + reset (idempotent; covers the auto-retry that finally lands)
+      clearTimer();
+      backoffMs = 3000;
+      if (fallback.visibility !== 'collapse') {
+        appwrapNativeLog('[native:fallback] load recovered — hiding fallback');
+        fallback.visibility = 'collapse';
+      }
+      return;
+    }
+    if (/cancel/i.test(err)) return; // NSURLErrorCancelled: navigation superseded, not a failure
+    appwrapNativeLog(`[native:fallback] load failed: ${err}`);
+    fallback.visibility = 'visible';
+    if (!retryTimer) {
+      retryTimer = setTimeout(() => { backoffMs = Math.min(backoffMs * 2, 30_000); retry(); }, backoffMs);
+    }
+  });
+  retryBtn.on(Button.tapEvent, retry);
+}
+
 function loadBundle(webView: CustomWebView): void {
   const wwwPath = path.join(knownFolders.currentApp().path, 'www');
   const entryPath = path.join(wwwPath, SHELL_CONFIG.entry);

package/runtime/app/main-page.xml

@@ -6,5 +6,13 @@
   backgroundColor="{{ backgroundColor }}">
   <GridLayout rows="*">
     <shell:CustomWebView id="webview" row="0" />
+    <!-- loader:'server' load-failure fallback (App Review 2.1a): shown by main-page.ts when the
+         server navigation fails (offline / server down) so the reviewer never sees a white screen. -->
+    <StackLayout id="loadFallback" row="0" visibility="collapse" backgroundColor="#ffffff" verticalAlignment="center" padding="32">
+      <Label text="Blank" fontSize="34" fontWeight="700" color="#000000" textAlignment="center" />
+      <Label text="Can't connect" fontSize="17" fontWeight="600" color="#333333" textAlignment="center" marginTop="18" />
+      <Label text="Check your internet connection — we'll keep trying." fontSize="14" color="#777777" textAlignment="center" textWrap="true" marginTop="6" />
+      <Button id="loadRetryBtn" text="Retry" fontSize="16" fontWeight="600" color="#ffffff" backgroundColor="#000000" borderRadius="22" height="44" width="160" marginTop="24" />
+    </StackLayout>
   </GridLayout>
 </Page>

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

@@ -127,6 +127,22 @@ class DevCertNavDelegate extends NSObject implements WKNavigationDelegate {
   // EXPLICITLY — ObjC message forwarding (forwardingTargetForSelector) is unreliable for a @NativeClass,
   // and a decision method (below) whose `decisionHandler` is never called STALLS the navigation → blank.
   webViewDecidePolicyForNavigationActionDecisionHandler(webView: WKWebView, navigationAction: any, decisionHandler: (p: number) => void): void {
+    // External URL schemes (mailto:/tel:/app deeplinks/…) can't be rendered by the WKWebView —
+    // navigating to one in-place silently fails ("unsupported URL"). Mirror the Android shell's
+    // shouldOverrideUrlLoading: hand every non-web scheme to the OS and cancel the navigation.
+    // http/https/file/about/blob/data (+ empty) stay in-WebView.
+    try {
+      const url: NSURL | null = navigationAction?.request?.URL ?? null;
+      const scheme = url?.scheme?.toLowerCase?.() ?? '';
+      // 'app' is the shell's own WKURLSchemeHandler serving the bundled PWA (loader:'app') — in-WebView.
+      if (scheme && !['http', 'https', 'file', 'about', 'blob', 'data', 'javascript', 'app'].includes(scheme)) {
+        UIApplication.sharedApplication.openURLOptionsCompletionHandler(url!, NSDictionary.new() as any, null);
+        decisionHandler(0 /* WKNavigationActionPolicy.Cancel */);
+        return;
+      }
+    } catch (e) {
+      console.warn('AppWrap: external-scheme nav check failed', e);
+    }
     if (this.fbResponds('webView:decidePolicyForNavigationAction:decisionHandler:')) {
       (this.fallback as any).webViewDecidePolicyForNavigationActionDecisionHandler(webView, navigationAction, decisionHandler);
     } else {

package/src/cli.ts

@@ -13,7 +13,7 @@ import { createHash } from 'crypto';
 import { cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
 import { builtinModules } from 'module';
 import { networkInterfaces, tmpdir } from 'os';
-import { basename, dirname, extname, join, resolve } from 'path';
+import { basename, dirname, extname, join, relative, resolve } from 'path';
 import { pathToFileURL } from 'url';
 // PURE-DATA capability manifest (no NativeScript globals) — type-only import (erased at runtime);
 // the VALUES are loaded dynamically below from the resolved runtime so the CLI works both in the
@@ -979,7 +979,9 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
   // and notifications fall back to a plain banner with the host app icon. native-kit's notification
   // identity path (INSendMessageIntent → communication notification) needs this to render the sender.
   if (cfg.iosEntitlements?.['com.apple.developer.usernotifications.communication']) {
-    extras.push(`  <key>NSUserActivityTypes</key>\n  <array>\n    <string>INSendMessageIntent</string>\n    <string>INStartCallIntent</string>\n  </array>`);
+    // ONLY the intents the shell actually donates: INSendMessageIntent (communication-notification
+    // styling). Declaring INStartCallIntent in an app with no calling feature is an App Review flag.
+    extras.push(`  <key>NSUserActivityTypes</key>\n  <array>\n    <string>INSendMessageIntent</string>\n  </array>`);
   }
   if (extras.length) {
     src = src.replace(
@@ -2009,6 +2011,50 @@ export function isFrameworkRepo(root: string): boolean {
   return existsSync(join(root, 'packages/appwrap-cli/src/cli.ts'));
 }
 
+/** Context the CI workflow templates are rendered against — derived from the repo shape + config.
+ *  - `subdir`: app dir relative to the git root ('' = app at repo root). Auto-detected from where the
+ *    appwrap config lives, so a monorepo gets path-scoped jobs + a PR paths filter for free.
+ *  - `tagPrefix`: release-trigger tag prefix. Monorepo default `<subdir>-v` (NOT `v`) so an unrelated
+ *    repo `v*` tag can never cut a store release; overridable via config `ci.tagPrefix`.
+ *  - `webBuild`: false for loader:'server' wraps (no local PWA bundle) — web build steps drop out. */
+export interface CiRenderContext { subdir: string; tagPrefix: string; webBuild: boolean; }
+
+/** Derive the render context for `cwd` (the app dir holding the appwrap config) inside `repoRoot`. */
+export function ciRenderContext(cwd: string, repoRoot: string, cfg: AppwrapConfig): CiRenderContext {
+  const rel = relative(repoRoot, cwd);
+  const subdir = rel === '' || rel === '.' ? '' : rel;
+  // Default tag prefix uses the LAST path segment (apps/foo → foo-v): tags are flat names, not paths.
+  const tagPrefix = cfg.ci?.tagPrefix ?? (subdir ? `${basename(subdir)}-v` : 'v');
+  return { subdir, tagPrefix, webBuild: cfg.loader !== 'server' };
+}
+
+/** Render a CI workflow template: substitute tokens and resolve `#@if:` directives.
+ * Directives (never survive into output): a trailing ` #@if:<cond>` keeps that line only when the
+ * condition holds; standalone `#@if:<cond>` … `#@end` lines gate a block (non-nesting). Conds:
+ * `monorepo` (subdir set) / `root` / `web` (local PWA build) / `server`. Tokens: `__DIR__` →
+ * `<subdir>/` or '' (path prefix), `__APP_DIR__` → subdir (working-directory), `__TAG_PREFIX__`. */
+export function renderCiWorkflow(src: string, ctx: CiRenderContext): string {
+  const holds = (c: string): boolean =>
+    c === 'monorepo' ? !!ctx.subdir : c === 'root' ? !ctx.subdir : c === 'web' ? ctx.webBuild : c === 'server' ? !ctx.webBuild
+    : c === 'doc' ? false // template-authoring notes — never emitted
+    : true;
+  const out: string[] = [];
+  let dropBlock = false;
+  for (const line of src.split('\n')) {
+    const t = line.trim();
+    if (t.startsWith('#@if:')) { dropBlock = !holds(t.slice(5)); continue; }
+    if (t === '#@end') { dropBlock = false; continue; }
+    if (dropBlock) continue;
+    const m = line.match(/^(.*?)\s*#@if:([a-z]+)$/);
+    if (m) { if (holds(m[2])) out.push(m[1]); }
+    else out.push(line);
+  }
+  return out.join('\n')
+    .replaceAll('__DIR__', ctx.subdir ? `${ctx.subdir}/` : '')
+    .replaceAll('__APP_DIR__', ctx.subdir)
+    .replaceAll('__TAG_PREFIX__', ctx.tagPrefix);
+}
+
 /** 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.
@@ -2027,19 +2073,28 @@ function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force
   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 if (scaffoldWorkflows) {
-    targets.unshift([join(CI_TEMPLATE_DIR, 'github/workflows'), join(repoRoot, '.github/workflows'), false]);
   }
   for (const [from, to, overwrite] of targets) {
     mkdirSync(to, { recursive: true });
     cpSync(from, to, { recursive: true, force: overwrite, errorOnExist: false });
   }
-  // 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.
+  // Workflows are RENDERED per-repo-shape (not raw-copied): monorepo path scoping + tag prefix +
+  // loader-aware web steps (see renderCiWorkflow), and the `bunx @livx.cc/appwrap@^x.y.z` pin is
+  // stamped to THIS CLI's version floor so a CI run can't silently resolve an older published build
+  // that lacks the `init`/`release` commands (it fails loudly instead). Never overwritten (users may
+  // customize); re-init on an existing file is a no-op.
   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));
+    const ctx = ciRenderContext(cwd, repoRoot, cfg);
+    const wfSrcDir = join(CI_TEMPLATE_DIR, 'github/workflows');
+    const wfDir = join(repoRoot, '.github/workflows');
+    mkdirSync(wfDir, { recursive: true });
+    for (const file of readdirSync(wfSrcDir)) {
+      const dest = join(wfDir, file);
+      if (existsSync(dest)) continue;
+      const rendered = renderCiWorkflow(readFileSync(join(wfSrcDir, file), 'utf8'), ctx)
+        .replaceAll('__APPWRAP_VERSION__', CLI_VERSION);
+      writeFileSync(dest, rendered);
+    }
   }
   // Stamp the app id + team into the emitted fastlane (signing needs them; the templates ship
   // `__APP_ID__`/`__TEAM_ID__` placeholders). Idempotent: re-init finds no placeholders → no-op.

package/src/config.ts

@@ -249,6 +249,15 @@ export interface AppwrapConfig {
   loader?: 'app' | 'file' | 'server';
   /** Live URL loaded when loader === 'server'. Set via config or `appwrap dev --url <url>`. */
   serverUrl?: string;
+  /** CI scaffolding options (`appwrap init --ci`). The emitted GH Actions workflows auto-adapt to the
+   * repo shape (job paths + PR path filter scoped to the app subdir when the config sits below the git
+   * root; web-build steps dropped for loader:'server'); this block only overrides the derived defaults. */
+  ci?: {
+    /** Release tag prefix the release workflows trigger on (`tags: ['<prefix>*']`). Default: `v` at
+     * the repo root, `<subdir>-v` in a monorepo — so a monorepo's generic `v*` tags can never cut a
+     * store release by accident. */
+    tagPrefix?: string;
+  };
   /** Runtime env-switcher (loader:'server' apps). Lets a build re-point the WebView between declared
    * environments (prod / lab / a preview URL) at runtime — via the native dev-menu "Switch Environment"
    * action + a bottom env-indicator banner — surviving a cold start, with NO separate native build.
@@ -348,6 +357,10 @@ export interface AppwrapConfig {
    * build finds MULTIPLE candidate profiles for an id and you pick one interactively — so you're not
    * re-prompted. Usually unset: a single matching profile is selected automatically. */
   signingProfiles?: Record<string, string>;
+  /** Store-lane block (listing metadata, screenshot dirs, submission answers) consumed by an EE host
+   * (`appwrap-ee store bootstrap|push|assets`). CE carries it OPAQUE — nothing in CE reads it; the
+   * key is registered only so `unknownConfigKeys` doesn't warn on configs that declare it. */
+  store?: Record<string, unknown>;
   /** Pure-native escape hatch: a directory (relative to the PWA project) whose contents are copied
    * OVER the generated wrapper after stamping — for legacy/custom native code the declarative config
    * can't express. Default `'appwrap.overrides'`; applied only if it exists. */
@@ -434,10 +447,10 @@ export function defineConfig(config: AppwrapConfig): AppwrapConfig {
  * with no error, then an App Store rejection). A loud warning turns that silent no-op into a signal.
  */
 export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
-  'androidAppLinks', 'appBoundDomains', 'backendOrigin', 'backgroundAudio', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'debug',
+  'androidAppLinks', 'appBoundDomains', 'backendOrigin', 'backgroundAudio', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'ci', 'debug',
   'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'modulePacks', 'name',
   'envSwitcher', 'iosEntitlements', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
-  'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'shareTarget', 'signing', 'signingProfiles', 'statusBarStyle',
+  'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'shareTarget', 'signing', 'signingProfiles', 'statusBarStyle', 'store',
   'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',
   'usesNonExemptEncryption', 'vendorPaths', 'version',
 ]);

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

@@ -1,29 +1,49 @@
-# appwrap PR checks — emitted by `appwrap init`. Adjust build commands to your project.
+# appwrap PR checks — emitted by `appwrap init --ci`. Adjust build commands to your project.
+#@if:doc
+# Template directives (processed at emit by renderCiWorkflow; none survive into the scaffolded file):
+#   `#@if:<cond>` trailing a line keeps it only when the condition holds; a standalone `#@if:<cond>`
+#   … `#@end` pair gates a block (non-nesting). Conds: monorepo/root (app dir vs repo root),
+#   web/server (loader), doc (never emitted — this note).
+#   Tokens: __DIR__ → `<subdir>/` or ``; __APP_DIR__ → subdir; __TAG_PREFIX__ → release tag prefix.
+#@end
 name: PR
 on:
   pull_request:
+    paths: #@if:monorepo
+      - '__DIR__**' #@if:monorepo
+      - '.github/workflows/appwrap-pr.yml' #@if:monorepo
+  workflow_dispatch: #@if:monorepo
 
 jobs:
+#@if:web
   web:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
       - run: bun install
+        working-directory: __APP_DIR__ #@if:monorepo
       - run: bun test || echo "no tests"
+        working-directory: __APP_DIR__ #@if:monorepo
       - run: bun run build # → dist/ (the PWA bundle the wrapper ships)
+        working-directory: __APP_DIR__ #@if:monorepo
+#@end
 
   ios-build:
     runs-on: macos-15
-    needs: web
+    needs: web #@if:web
     steps:
       - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
       - uses: actions/setup-node@v5
         with: { node-version: 22 }
-      - run: bun install && bun run build
+      - run: bun install && bun run build #@if:web
+      - run: bun install # server-loader wrap — no local web build (the app loads the live URL) #@if:server
+        working-directory: __APP_DIR__ #@if:monorepo
       # 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
-      - working-directory: native
+      # Pinned to the appwrap version that emitted this workflow (see release workflow header for why).
+      - run: bunx @livx.cc/appwrap@^__APPWRAP_VERSION__ init # native/ is generated (gitignored) — regenerate it fresh in CI
+        working-directory: __APP_DIR__ #@if:monorepo
+      - working-directory: __DIR__native
         run: npm install && ns build ios --emulator

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

@@ -1,4 +1,5 @@
-# appwrap Android release — tag push (v*) → Play internal track.
+# appwrap Android release — tag push (__TAG_PREFIX__*) → Play internal track.
+# Template directives (`#@if:` / `#@end` / `__TOKENS__`) are processed at emit — see appwrap-pr.yml header. #@if:doc
 # Build is the appwrap CLI (`appwrap build android --release --aab` → signed AAB);
 # upload is fastlane supply. Secrets contract (repo settings → Actions secrets):
 #   ANDROID_KEYSTORE_BASE64        upload keystore, base64-encoded
@@ -6,12 +7,14 @@
 #   ANDROID_KEY_ALIAS              key alias
 #   ANDROID_KEY_ALIAS_PASSWORD     key (alias) password
 #   PLAY_SERVICE_ACCOUNT_JSON      Play Developer API service-account JSON (the app must already
-#                                  exist on Play with one prior manual upload before supply works)
+#                                  exist on Play with one prior manual upload before supply works).
+#                                  OPTIONAL — when unset the job stays green and ships the AAB
+#                                  artifact only (graceful degradation until the SA exists).
 name: Release Android
 on:
   workflow_dispatch:
   push:
-    tags: ['v*']
+    tags: ['__TAG_PREFIX__*']
 
 # Monotonic store build number (Android versionCode): computed in the shell below — GitHub Actions
 # expressions have NO arithmetic operators, so `${{ github.run_number + 100 }}` is an INVALID workflow
@@ -37,35 +40,53 @@ jobs:
           path: |
             ~/.gradle/caches
             ~/.gradle/wrapper
-          key: gradle-${{ runner.os }}-${{ hashFiles('bun.lock', 'package.json') }}
+          key: gradle-${{ runner.os }}-${{ hashFiles('__DIR__bun.lock', '__DIR__package.json') }}
           restore-keys: gradle-${{ runner.os }}-
       - uses: android-actions/setup-android@v3
       - run: sudo apt-get update -qq && sudo apt-get install -y -qq imagemagick   # appwrap icon-gen needs an image tool (no sips on Linux) — else the default NS icon ships
-      - run: bun install && bun run build        # → dist/ (the PWA bundle the wrapper ships)
+      - run: bun install && bun run build # → dist/ (the PWA bundle the wrapper ships) #@if:web
+      - run: bun install # server-loader wrap — no local web build (the app loads the live URL) #@if:server
+        working-directory: __APP_DIR__ #@if:monorepo
       # Pin global tools — unpinned installs can grab a breaking release mid-flight. Bump deliberately.
       - run: bun add -g nativescript@9.0.6
-      - run: bunx @livx.cc/appwrap init                      # native/ is generated (gitignored) — regenerate fresh in CI
-      - working-directory: native
+      # Pinned to the appwrap version that emitted this workflow (see the iOS release workflow for why).
+      - run: bunx @livx.cc/appwrap@^__APPWRAP_VERSION__ init  # native/ is generated (gitignored) — regenerate fresh in CI
+        working-directory: __APP_DIR__ #@if:monorepo
+      - working-directory: __DIR__native
         run: bun install
       - name: Decode upload keystore
         run: echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | base64 -d > "$RUNNER_TEMP/upload.keystore"
       - name: Build signed AAB
+        working-directory: __APP_DIR__ #@if:monorepo
         env:
           GRADLE_OPTS: "-Dorg.gradle.caching=true -Dorg.gradle.parallel=true -Dorg.gradle.daemon=false"
           APPWRAP_ANDROID_KEYSTORE: ${{ runner.temp }}/upload.keystore
           APPWRAP_ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
           APPWRAP_ANDROID_KEYSTORE_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
           APPWRAP_ANDROID_KEYSTORE_ALIAS_PASSWORD: ${{ secrets.ANDROID_KEY_ALIAS_PASSWORD }}
-        run: bunx @livx.cc/appwrap build android --release --aab
+        run: bunx @livx.cc/appwrap@^__APPWRAP_VERSION__ build android --release --aab
       - uses: actions/upload-artifact@v4            # keep the AAB even if Play upload is skipped
         with:
           name: app-release-aab
-          path: native/platforms/android/app/build/outputs/bundle/release/app-release.aab
+          path: __DIR__native/platforms/android/app/build/outputs/bundle/release/app-release.aab
+      # ---- Play upload, gracefully gated on the service account ----
+      # Without PLAY_SERVICE_ACCOUNT_JSON (e.g. the SA isn't provisioned yet) the job stays GREEN and
+      # ships the AAB artifact only. secrets.* can't appear in a step `if:` — indirect through env.
+      - name: Check Play service account
+        id: play-sa
+        env:
+          PLAY_SERVICE_ACCOUNT_JSON: ${{ secrets.PLAY_SERVICE_ACCOUNT_JSON }}
+        run: |
+          if [ -n "$PLAY_SERVICE_ACCOUNT_JSON" ]; then echo "present=true" >> "$GITHUB_OUTPUT";
+          else echo "present=false" >> "$GITHUB_OUTPUT"; echo "::notice::PLAY_SERVICE_ACCOUNT_JSON not set — skipping Play upload, AAB artifact only"; fi
       - uses: ruby/setup-ruby@v1
+        if: steps.play-sa.outputs.present == 'true'
         with: { ruby-version: '3.3', bundler-cache: false }
       - run: gem install fastlane -v 2.236.1
+        if: steps.play-sa.outputs.present == 'true'
       - name: Upload to Play (internal)
-        working-directory: native
+        if: steps.play-sa.outputs.present == 'true'
+        working-directory: __DIR__native
         env:
           PLAY_SERVICE_ACCOUNT_JSON: ${{ secrets.PLAY_SERVICE_ACCOUNT_JSON }}
         run: fastlane android beta

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

@@ -1,4 +1,5 @@
-# appwrap iOS → TestFlight via fastlane. On-demand (workflow_dispatch) or tag push (v*).
+# appwrap iOS → TestFlight via fastlane. On-demand (workflow_dispatch) or tag push (__TAG_PREFIX__*).
+# Template directives (`#@if:` / `#@end` / `__TOKENS__`) are processed at emit — see appwrap-pr.yml header. #@if:doc
 # Secrets contract (repo settings → Actions secrets):
 #   MATCH_GIT_URL        private repo holding signing certs (fastlane match) — SSH form for the deploy key
 #   MATCH_DEPLOY_KEY     read-only SSH deploy key on that certs repo (so CI can clone it)
@@ -12,7 +13,7 @@ name: Release iOS
 on:
   workflow_dispatch:
   push:
-    tags: ['v*']
+    tags: ['__TAG_PREFIX__*']
 
 # Monotonic store build number (CFBundleVersion): computed in the shell below — GitHub Actions
 # expressions have NO arithmetic operators, so `${{ github.run_number + 100 }}` is an INVALID workflow
@@ -33,7 +34,9 @@ jobs:
       - uses: oven-sh/setup-bun@v2
       - uses: actions/setup-node@v5
         with: { node-version: 22 }
-      - run: bun install && bun run build
+      - run: bun install && bun run build #@if:web
+      - run: bun install # server-loader wrap — no local web build (the app loads the live URL) #@if:server
+        working-directory: __APP_DIR__ #@if:monorepo
       # Pin global tools — unpinned installs can grab a breaking release mid-flight. Bump deliberately.
       - run: npm i -g nativescript@9.0.6
       # bunx is PINNED to the appwrap version that emitted this workflow (stamped at `init`). Pinning is
@@ -43,7 +46,8 @@ jobs:
       # published to the @livx.cc registry. PUBLISH-ORDERING: publish the appwrap CLI BEFORE the first CI
       # run that uses a freshly-emitted workflow.
       - run: bunx @livx.cc/appwrap@^__APPWRAP_VERSION__ init # native/ is generated (gitignored) — regenerate it fresh in CI
-      - working-directory: native
+        working-directory: __APP_DIR__ #@if:monorepo
+      - working-directory: __DIR__native
         run: npm install
       - uses: ruby/setup-ruby@v1
         with: { ruby-version: '3.3', bundler-cache: false }
@@ -58,6 +62,7 @@ jobs:
       # Single source of truth: the SAME command a developer runs locally. It re-stamps native/ and
       # delegates the full archive/sign/upload to the emitted fastlane lane — no fastlane logic here.
       - name: Build & upload to TestFlight
+        working-directory: __APP_DIR__ #@if:monorepo
         env:
           MATCH_GIT_URL: ${{ secrets.MATCH_GIT_URL }}
           MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}