@livx.cc/appwrap 0.58.3 → 0.59.0

package/package.json

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

@@ -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/capabilities.manifest.ts

@@ -326,7 +326,7 @@ export const MODULES: ModuleManifest[] = [
     },
   },
 
-  // NOTE: billing, health, and widget are NOT part of CE — they live in host-provided module packs
+  // NOTE: billing, health, and widget are not built in — they live in host-provided module packs
   // (a consumer opts in via `modulePacks`).
 ];
 

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

@@ -4,6 +4,7 @@ import { mimeFor } from './mime';
 import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, serviceWorkerGuardJs, externalNavGuardJs } from './web-quirks';
 import { envGlobalsJs } from './env';
 import { requestPermissions } from './android-helpers';
+import { showFileChooser } from './file-chooser.android';
 import { hostOf } from './env-switcher';
 
 // `android` + `java` resolve to the real types-android namespaces (no declare needed).
@@ -80,6 +81,17 @@ function getChromeClientClass(): any {
         Utils.dispatchToMainThread(() => (ok ? request.grant(request.getResources()) : request.deny()))
       );
     },
+
+    // <input type="file"> — NOT optional here: replacing NS's WebChromeClient removed the
+    // platform's default handling, so without this the input is completely inert. All state is
+    // per-invocation closure state inside showFileChooser (the class is shared across webviews).
+    onShowFileChooser(
+      _view: android.webkit.WebView,
+      filePathCallback: android.webkit.ValueCallback<androidNative.Array<android.net.Uri>>,
+      fileChooserParams: android.webkit.WebChromeClient.FileChooserParams
+    ): boolean {
+      return showFileChooser(filePathCallback, fileChooserParams);
+    },
   });
   return chromeClientClass;
 }

package/runtime/app/shell/file-chooser.android.ts

@@ -0,0 +1,187 @@
+import { Utils } from '@nativescript/core';
+import { mimeFor } from './mime';
+import { requestPermissions, startActivityForResult } from './android-helpers';
+
+/**
+ * `<input type="file">` support for the Android WebView.
+ *
+ * WHY THIS FILE EXISTS: we replace NativeScript's WebChromeClient wholesale
+ * (custom-webview.android.ts → setWebChromeClient), so the platform's own file-chooser
+ * handling is gone with it. Without an `onShowFileChooser` override, tapping a file input
+ * does NOTHING — no picker, no callback. (iOS needs none: WKWebView implements the picker itself.)
+ *
+ * THE ONE INVARIANT: `filePathCallback.onReceiveValue` MUST be invoked EXACTLY ONCE on every
+ * path — success, cancel, back, no-activity, thrown exception. Chromium keeps the input in a
+ * "chooser open" state until the callback fires, so a missed call wedges that input PERMANENTLY
+ * for the rest of the page's life (a second tap silently does nothing). Hence the `settled`
+ * latch + the catch-all reject path below; never add an early `return` that skips `deliver`.
+ *
+ * STATE: everything is per-invocation closure state over the callback/params ARGUMENTS. The
+ * WebChromeClient Java proxy is shared across every webview (NS caches the class — see the
+ * header comment in custom-webview.android.ts), so holding per-request state on the client or
+ * in a module-level slot would cross-wire concurrent requests and separate webviews. Don't.
+ */
+export function showFileChooser(
+  filePathCallback: android.webkit.ValueCallback<androidNative.Array<android.net.Uri>>,
+  params: android.webkit.WebChromeClient.FileChooserParams
+): boolean {
+  let settled = false;
+  const deliver = (uris: androidNative.Array<android.net.Uri> | null): void => {
+    if (settled) return;
+    settled = true;
+    Utils.dispatchToMainThread(() => {
+      try {
+        filePathCallback.onReceiveValue(uris);
+      } catch (e) {
+        console.warn('[appwrap] file-chooser callback failed: ' + e);
+      }
+    });
+  };
+
+  try {
+    pick(params).then(deliver, (e) => {
+      console.warn('[appwrap] file-chooser failed: ' + e);
+      deliver(null); // cancel semantics — the input stays usable
+    });
+  } catch (e) {
+    console.warn('[appwrap] file-chooser threw: ' + e);
+    deliver(null);
+  }
+  return true; // we own the request (returning false = "no chooser", input goes inert)
+}
+
+/** accept="" tokens → intent MIME types. `.png` style extensions map through the shared MIME table. */
+function acceptMimes(params: any): string[] {
+  const raw: string[] = Array.from(params?.getAcceptTypes?.() ?? []).map(String);
+  const out = new Set<string>();
+  for (const t of raw) {
+    const token = t.trim();
+    if (!token) continue; // the platform pads getAcceptTypes() with empty strings for accept=""
+    if (token.startsWith('.')) out.add(mimeFor(token.slice(1).toLowerCase()));
+    else if (token.includes('/')) out.add(token);
+  }
+  // application/octet-stream is mimeFor's fallback for an unknown extension — it matches nothing
+  // in the picker, so an unresolvable accept must widen to "any file", not narrow to nothing.
+  if (out.has('application/octet-stream')) return [];
+  return Array.from(out);
+}
+
+async function pick(params: any): Promise<androidNative.Array<android.net.Uri> | null> {
+  const mimes = acceptMimes(params);
+  const FCP = android.webkit.WebChromeClient.FileChooserParams;
+  const multiple = params?.getMode?.() === FCP.MODE_OPEN_MULTIPLE;
+
+  if (params?.isCaptureEnabled?.()) {
+    const captured = await capture(mimes);
+    // Fall through to the normal picker ONLY when the capture path is UNAVAILABLE (no capture
+    // app, CAMERA denied): `capture` is a HINT in the HTML spec, not a hard requirement.
+    // A settled capture ends the request — including a CANCEL (`uris: null`), which must return
+    // the user to the page, not ambush them with a second picker they never asked for.
+    if (captured.settled) return captured.uris;
+  }
+
+  const I = android.content.Intent;
+  const intent = new I(I.ACTION_GET_CONTENT);
+  intent.addCategory(I.CATEGORY_OPENABLE);
+  intent.setType(mimes.length === 1 ? mimes[0] : '*/*');
+  if (mimes.length > 1) {
+    const arr = (Array as any).create(java.lang.String, mimes.length);
+    mimes.forEach((m, i) => (arr[i] = new java.lang.String(m)));
+    intent.putExtra(I.EXTRA_MIME_TYPES, arr);
+  }
+  if (multiple) intent.putExtra(I.EXTRA_ALLOW_MULTIPLE, true);
+
+  const { resultCode, intent: data } = await startActivityForResult(intent);
+  if (resultCode !== android.app.Activity.RESULT_OK || !data) return null;
+  return toUriArray(collect(data));
+}
+
+/** Multi-select arrives as ClipData; single select as the intent's data Uri. */
+function collect(data: android.content.Intent): android.net.Uri[] {
+  const uris: android.net.Uri[] = [];
+  const clip = data.getClipData?.();
+  if (clip) {
+    for (let i = 0; i < clip.getItemCount(); i++) {
+      const u = clip.getItemAt(i).getUri();
+      if (u) uris.push(u);
+    }
+  }
+  const single = data.getData?.();
+  if (!uris.length && single) uris.push(single);
+  return uris;
+}
+
+function toUriArray(uris: android.net.Uri[]): androidNative.Array<android.net.Uri> | null {
+  if (!uris.length) return null;
+  const arr = (Array as any).create(android.net.Uri, uris.length);
+  uris.forEach((u, i) => (arr[i] = u));
+  return arr;
+}
+
+/**
+ * capture="" path: MediaStore capture intents. Image capture writes to a FileProvider-backed
+ * cache file (EXTRA_OUTPUT) so the web layer gets a FULL-SIZE file rather than the ~100px
+ * thumbnail the extras-only path returns.
+ *
+ * `settled:false` means the capture path is UNAVAILABLE (no capture activity / CAMERA denied) —
+ * the ONLY case the caller may fall back to the normal picker. `settled:true` owns the request:
+ * `uris` carries the capture, or is null when the user CANCELLED (back out of the camera). The
+ * two were once both a bare null, which turned one cancel into a second, unrequested picker.
+ */
+type CaptureResult =
+  | { settled: true; uris: androidNative.Array<android.net.Uri> | null }
+  | { settled: false };
+
+async function capture(mimes: string[]): Promise<CaptureResult> {
+  const kind = mimes[0]?.split('/')[0] ?? 'image';
+  const MS = android.provider.MediaStore;
+  const ctx = Utils.android.getApplicationContext();
+  const I = android.content.Intent;
+
+  const action = kind === 'video' ? MS.ACTION_VIDEO_CAPTURE
+    : kind === 'audio' ? MS.Audio.Media.RECORD_SOUND_ACTION
+      : MS.ACTION_IMAGE_CAPTURE;
+  const intent = new I(action);
+  if (!intent.resolveActivity(ctx.getPackageManager())) return { settled: false };
+
+  // CAMERA is only REQUIRED when the app DECLARES it: Android denies a capture intent to an app
+  // that declares the permission without holding it, but asks nothing of an app that doesn't
+  // declare it at all. Requesting an undeclared permission returns denied forever → a dead
+  // capture path in apps that never opted into the camera module.
+  if (action !== MS.Audio.Media.RECORD_SOUND_ACTION && declares('android.permission.CAMERA')) {
+    if (!(await requestPermissions(['android.permission.CAMERA']))) return { settled: false };
+  }
+
+  let output: android.net.Uri | null = null;
+  if (action === MS.ACTION_IMAGE_CAPTURE) {
+    const dir = new java.io.File(ctx.getCacheDir(), 'shared'); // already exposed by file_paths.xml
+    dir.mkdirs();
+    const file = new java.io.File(dir, 'capture-' + java.lang.System.currentTimeMillis() + '.jpg');
+    output = androidx.core.content.FileProvider.getUriForFile(ctx, ctx.getPackageName() + '.fileprovider', file);
+    intent.putExtra(MS.EXTRA_OUTPUT, output);
+    intent.addFlags(I.FLAG_GRANT_WRITE_URI_PERMISSION | I.FLAG_GRANT_READ_URI_PERMISSION);
+  }
+
+  const { resultCode, intent: data } = await startActivityForResult(intent);
+  // Cancelled (BACK out of the camera) — settled, with nothing: the caller delivers null.
+  if (resultCode !== android.app.Activity.RESULT_OK) return { settled: true, uris: null };
+  // EXTRA_OUTPUT captures return no data Uri — the bytes landed in `output`.
+  const uris = data ? collect(data) : [];
+  if (!uris.length && output) uris.push(output);
+  return { settled: true, uris: toUriArray(uris) };
+}
+
+function declares(permission: string): boolean {
+  try {
+    const ctx = Utils.android.getApplicationContext();
+    const info = ctx.getPackageManager().getPackageInfo(
+      ctx.getPackageName(),
+      android.content.pm.PackageManager.GET_PERMISSIONS
+    );
+    return Array.from(info.requestedPermissions ?? []).map(String).includes(permission);
+  } catch (e) {
+    return false;
+  }
+}
+
+declare const androidx: any; // androidx.core.content.FileProvider — not in the android-32 platform typings

package/runtime/app/shell/plugin-host.ts

@@ -1,7 +1,7 @@
 /**
- * Mobile plugin host — the in-process analog of the desktop plugin host (`plugin/host.ts`).
+ * Mobile plugin host — the in-process analog of an out-of-process desktop plugin host.
  *
- * On desktop a plugin's `WindowCtx` ops marshal over a Unix socket to the Rust shell; that host does
+ * On desktop a plugin's `WindowCtx` ops marshal to the native shell over IPC; that host does
  * NOT apply on mobile — there is one WKWebView/WebView and the NS runtime IS the trusted host. So the
  * mobile "host" is trivial: at boot it takes each configured plugin's def and registers its `handlers`
  * directly onto the same {@link bridge} the built-in `handlers*.ts` groups use. A PWA then reaches a

package/scripts/stage-assets.mjs

@@ -8,8 +8,8 @@ import { fileURLToPath } from 'node:url';
 
 const pkgDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const repoRoot = resolve(pkgDir, '../..');
-// Excludes build artifacts (NativeScript: node_modules/platforms/hooks/app/www; Tauri desktop:
-// src-tauri/target — gigabytes — and src-tauri/gen — regenerated on build) and OS cruft.
+// Excludes build artifacts (NativeScript: node_modules/platforms/hooks/app/www; desktop shells:
+// native build output — gigabytes — and generated dirs) and OS cruft.
 const EXCLUDE = /(?:^|\/)(?:node_modules|platforms|hooks|app\/www|target|gen|\.DS_Store)(?:\/|$)/;
 
 for (const name of ['runtime', 'templates']) {

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
@@ -25,8 +25,7 @@ import type { AppwrapConfig } from './config';
 import { encodeShareDirectSync, unknownConfigKeys } from './config';
 import { resolveModulePacks, type ResolvedModule, type SyncContext } from './packs';
 import { createHash } from 'crypto';
-// Icon helpers re-exported so the EE desktop lane (which owns the Tauri chassis) can reuse them via
-// `@livx.cc/appwrap/cli` — the CE/EE split (Phase D) moved the desktop lane out but keeps these shared.
+// Icon helpers re-exported via `@livx.cc/appwrap/cli` so a host-provided platform lane can reuse them.
 export { APPLE_ICON_GRID_SCALE, makeDockRuntimeIcon } from './icon';
 import {
   androidScreenOrientation,
@@ -109,21 +108,19 @@ function resolveAssetRoot(rel: string): string {
 const TEMPLATE_DIR = resolveAssetRoot('runtime');
 /** Ordered runtime-template roots copied into native/ (later roots overlay earlier — file-level
  * last-wins), defaulting to the single built-in template. runCli (A5) can extend this so a consumer
- * (a host) layers extra shell files on top of CE without forking the template. A single root
+ * (a host) layers extra shell files on top of the built-in one without forking the template. A single root
  * is byte-identical to the pre-overlay behavior. */
 let TEMPLATE_ROOTS: string[] = [TEMPLATE_DIR];
 const CI_TEMPLATE_DIR = resolveAssetRoot('templates/ci');
 /** Scaffold for `appwrap create-module` — a starter module pack (see packs.ts / @livx.cc/appwrap/testing). */
 const MODULE_PACK_TEMPLATE_DIR = resolveAssetRoot('templates/module-pack');
-/** Desktop (Tauri chassis) template dir. CE ships no bundled desktop template — the desktop lane is
- * host-owned: a consumer points this at its own template via `runCli({ desktopTemplateDir })` (A5).
- * A `let` so runCli can override it; empty by default so the mobile lanes are unaffected. The desktop
- * lane itself lives in the EE package (Phase D split) and reads this value via `getDesktopTemplateDir()`
- * — CE keeps the seam (set by `runCli({ desktopTemplateDir })`) but ships no desktop code. */
+/** Desktop template dir. No desktop template ships here — the desktop lane is host-owned: a consumer
+ * points this at its own template via `runCli({ desktopTemplateDir })` (A5). A `let` so runCli can
+ * override it; empty by default so the mobile lanes are unaffected. */
 let DESKTOP_TEMPLATE_DIR = '';
 
-/** The desktop (Tauri) template dir set via `runCli({ desktopTemplateDir })`. Read by the EE desktop
- * lane (hosted on top of CE through the `platforms` seam) so the seam stays authoritative in one place. */
+/** The desktop template dir set via `runCli({ desktopTemplateDir })`. Read by the host-provided desktop
+ * lane (composed through the `platforms` seam) so the seam stays authoritative in one place. */
 export function getDesktopTemplateDir(): string {
   return DESKTOP_TEMPLATE_DIR;
 }
@@ -139,7 +136,7 @@ export interface CliOptions {
   commands?: Record<string, (cwd: string, flags: Record<string, string>, positionals: string[]) => Promise<void> | void>;
   /** Pluggable platform handlers for `dev`/`build` (keyed by the platform arg, e.g. 'desktop') —
    * consulted BEFORE the built-in platform routing, so a host can add/replace a platform lane. The
-   * 4th arg is the driving command ('dev' | 'build') so a single handler (e.g. the EE desktop lane)
+   * 4th arg is the driving command ('dev' | 'build') so a single handler (e.g. a desktop lane)
    * can branch dev-vs-build — `dev desktop` and `build desktop` route to the SAME handler key. */
   platforms?: Record<string, (cwd: string, flags: Record<string, string>, positionals: string[], command: 'dev' | 'build') => Promise<void> | void>;
   /** Module packs injected by the host, applied BEFORE the app config's own `modulePacks` (so the app
@@ -147,7 +144,7 @@ export interface CliOptions {
   modulePacks?: string[];
   /** Extra runtime-template overlay roots, appended after the built-in template (later roots win). */
   templateRoots?: string[];
-  /** Override for the desktop (Tauri) template dir. */
+  /** Override for the desktop template dir. */
   desktopTemplateDir?: string;
 }
 
@@ -342,7 +339,7 @@ const OPTIONAL_GROUP_HANDLERS: Record<string, { file: string; fn: string }> = {
   appleSignIn: { file: './handlers-apple-signin', fn: 'registerAppleSignInHandlers' },
   backgroundTask: { file: './handlers-background', fn: 'registerBackgroundTaskHandlers' },
   shareTarget: { file: './handlers-share-target', fn: 'registerShareTargetHandlers' },
-  // billing/health/widget live in host-provided module packs (not part of CE) — a consumer opts in via modulePacks.
+  // billing/health/widget live in host-provided module packs — a consumer opts in via modulePacks.
 };
 
 /** The bare specifier a pack handler uses to import a built-in shell API — rewritten to a relative
@@ -979,7 +976,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 +2008,55 @@ 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;
+  let inBlock = false; // block directives DON'T nest — fail loud rather than silently mis-render
+  for (const line of src.split('\n')) {
+    const t = line.trim();
+    if (t.startsWith('#@if:')) {
+      if (inBlock) throw new Error('renderCiWorkflow: nested #@if: block directives are unsupported');
+      inBlock = true; dropBlock = !holds(t.slice(5)); continue;
+    }
+    if (t === '#@end') { inBlock = false; 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);
+  }
+  if (inBlock) throw new Error('renderCiWorkflow: unterminated #@if: block (missing #@end)');
+  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 +2075,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.
@@ -2140,7 +2197,7 @@ function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: {
     console.warn('  ⚠ `shareTarget` is active but `urlScheme` is unset — the iOS share extension cannot forward to the app. Set `urlScheme` in the appwrap config.');
   }
   // Copy each template root in order — later roots OVERLAY earlier (file-level last-wins), so a
-  // consumer template can add or replace shell files without forking CE. Single root (default) is
+  // consumer template can add or replace shell files without forking the template. Single root (default) is
   // exactly the pre-overlay copy.
   for (const root of TEMPLATE_ROOTS) {
     if (!existsSync(root)) { console.warn(`⚠ template root not found: ${root}`); continue; }
@@ -4055,7 +4112,7 @@ async function createModule(cwd: string, flags: Record<string, string>, position
 /**
  * The CLI entry point — the bare `appwrap` bin calls `runCli()` with no options (identical to the
  * historical `main`). A host calls `runCli({ commands, platforms, modulePacks,
- * templateRoots, desktopTemplateDir })` to compose extra capability on top of CE without forking it.
+ * templateRoots, desktopTemplateDir })` to compose extra capability on top without forking it.
  */
 export async function runCli(options: CliOptions = {}): Promise<void> {
   cliOptions = { ...options };

package/src/config.ts

@@ -132,81 +132,10 @@ export interface AppwrapConfig {
    * Set 0 for no extra lift (input flush at the reported height; the strip may show). */
   iosKeyboardExtraLift?: number;
   pwaDist: string;
-  /** Desktop (Tauri chassis) shell — phase-0, macOS-only. When present, `appwrap dev|build desktop`
-   * stamps a generated Tauri wrapper (`native-desktop/`). Identity (`id`/`name`/`version`), `urlScheme`
-   * (internal deep-link loopback) and `pwaDist` (→ Tauri `frontendDist`) come from the top-level config;
-   * this only carries the desktop-window specifics. Absent → the desktop lane is inert (mobile-only app). */
-  desktop?: {
-    /** Window title (default: `name`). */
-    title?: string;
-    /** Initial window inner width in px (default 430 — a phone-ish portrait frame). */
-    width?: number;
-    /** Initial window inner height in px (default 800). */
-    height?: number;
-    /** Bundle identifier for the desktop build (default: `${id}.desktop`). Reverse-DNS. */
-    identifier?: string;
-    /** Remember the window's size + position across launches (tauri-plugin-window-state). Default
-     * `true`. When `false`, the plugin isn't registered so every launch opens at the configured
-     * `width`/`height` (no saved state applied). */
-    restoreWindowState?: boolean;
-    /** Force Google's account chooser in `signInWithPopup` OAuth. The shared WKWebView cookie store
-     * keeps the Google session, so Firebase auto-signs the remembered account; for apps that run
-     * multiple instances against different accounts (e.g. Unclaw) set `true` to append
-     * `prompt=select_account` to the popup's `accounts.google.com` OAuth URL so the user always picks.
-     * Default `false` (remember-me behavior stays). macOS-only. */
-    googleAccountPicker?: boolean;
-    /** Launch the app automatically when the user logs in (tauri-plugin-autostart, macOS LaunchAgent).
-     * Default `false`. The shell registers a login item on first launch when `true`, and explicitly
-     * REMOVES it when `false`, so flipping this off actually clears the login item on the next launch.
-     * NOTE: an adhoc-signed `.app` (the phase-0 desktop build) still autostarts via the LaunchAgent
-     * plist — no Developer ID required. macOS-only. */
-    autostart?: boolean;
-    /** Path (relative to the app root) to a TypeScript file that exports custom native handlers via
-     * `defineHandlers({...})` from `@livx.cc/appwrap/handlers`. When present the desktop shell spawns a
-     * Bun sidecar (`bun <path>`) at launch and routes any method the sidecar advertises to it — so an
-     * app ships app-custom native capabilities (called from the PWA via `kit.invoke('myapp.foo', …)`)
-     * without touching the Rust shell. Absent → the feature is fully inert (no sidecar spawned).
-     * The CLI stamps the ABSOLUTE resolved path into the shell config; handlers run with their CWD at
-     * the app dir, so `build desktop` apps must keep their repo (+ node_modules) around at runtime —
-     * embedding the handler file into the `.app` is out of scope for phase-0. macOS-only. */
-    handlers?: string;
-    /** Local-server mode: boot a command that serves the app locally, then load it LIVE in the window
-     * (instead of the bundled `pwaDist`). The shell shows a bundled splash, spawns `command` (+`args`)
-     * in a background thread, polls `http://localhost:<port><healthPath>` until it answers, then
-     * navigates the window there; on window-close it kills the child so the stack never outlives the
-     * shell. Use for a desktop app that IS a local dev/server stack (e.g. `para-chat`). Absent → the
-     * desktop lane loads the bundled `pwaDist` as usual. The CLI resolves `command` (when a bare name)
-     * and `cwd` to absolute paths at stamp time (a GUI-launched .app inherits the minimal launchd PATH,
-     * so a bare `bun`/PATH lookup would fail). `build desktop` apps must keep the server (+ its repo)
-     * present at runtime — bundling the server INTO the .app is a future phase. macOS-only. */
-    server?: {
-      /** Command to spawn (argv[0]). A bare name is PATH-resolved at stamp time; an absolute path is used as-is. */
-      command: string;
-      /** Extra arguments passed to the command. */
-      args?: string[];
-      /** Working directory to spawn in (default: the app project root). */
-      cwd?: string;
-      /** How the shell learns the URL to load. Provide EXACTLY ONE:
-       *  - `urlMarker` (preferred for servers that print their address, e.g. vite/para-chat): the shell
-       *    pipes the server's stdout and, on the first line CONTAINING this marker, extracts the first
-       *    `http(s)://…` token and loads it. This tracks whatever port the server auto-picked — no
-       *    hardcoded port, no mismatch. e.g. `"Frontend:"` matches `Frontend:  https://localhost:5050`.
-       *  - `port` (+ optional `https`) for a silent server on a KNOWN fixed port: the shell TCP-polls
-       *    `localhost:<port>` and loads `<http|https>://localhost:<port>`. */
-      urlMarker?: string;
-      /** Fixed port the server listens on (used only when `urlMarker` is absent). */
-      port?: number;
-      /** Load over https in fixed-`port` mode (default false = http). Ignored in `urlMarker` mode (the
-       * captured URL carries its own scheme). The server's TLS cert CA must be trusted by the system
-       * keychain and its SANs cover `localhost`/`127.0.0.1`, or the WebView shows a cert error. */
-      https?: boolean;
-      /** Health path polled for readiness (default `/`). Ready = any HTTP response (even 4xx/5xx). */
-      healthPath?: string;
-      /** Max ms to wait for the port before showing an error in the splash (default 120000 — a first-run
-       * production build can be slow). */
-      readyTimeoutMs?: number;
-    };
-  };
+  /** Desktop-shell block, consumed by an external desktop host (a module pack) that registers a
+   * `'desktop'` platform handler via `runCli({ platforms })`. Carried OPAQUE — nothing here reads
+   * it; the key is registered only so `unknownConfigKeys` doesn't warn on configs that declare it. */
+  desktop?: Record<string, unknown>;
   /** Custom URL scheme for deep links (e.g. "hellowrap" → hellowrap://...). */
   urlScheme?: string;
   /** Android App Links: https hosts whose `https://<host>/...` links open the app directly (the
@@ -249,6 +178,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,16 +286,19 @@ 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 external
+   * store tooling. Carried OPAQUE — nothing here 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. */
   overrides?: string;
   /** appwrap TS plugins (`@livx.cc/appwrap/plugin`). Each entry is an npm package name or a path to a
    * plugin entrypoint (that `export default definePlugin(...)`); the object form adds a config-level
-   * `attachTo` override (which windows it attaches to). `appwrap dev|build desktop` resolves + bun-builds
-   * each into a single embedded bundle and stamps it into the desktop shell (see `regeneratePlugins`),
-   * where the multiplexed plugin host loads them. A.1 skeleton: desktop-only; manifest/perms merge is
-   * stubbed (full module-manifest reuse lands later). */
+   * `attachTo` override (which windows it attaches to). On mobile the runtime registers a plugin's
+   * `handlers` in-process; a host-provided desktop lane bundles them for its own shell. Manifest/perms
+   * merge is stubbed (full module-manifest reuse lands later). */
   plugins?: (string | { name: string; attachTo?: 'main' | 'all' | string; options?: unknown })[];
   /** Opt-in capability allow-list (built-in modules — see capabilities.manifest.ts). When PRESENT,
    * only the listed capabilities (plus always-on core) are advertised, permissioned, and — for
@@ -434,10 +375,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/src/icon.ts

@@ -1,11 +1,10 @@
 /**
  * Dependency-free PNG codec + macOS app-icon corner rounding, in pure TS on `node:zlib`.
  *
- * WHY: Tauri embeds `src-tauri/icons/icon.png` via `generate_context!` and sets it as the RUNTIME
- * app icon on macOS — which OVERRIDES the bundle icns/Assets.car in cmd+tab/Dock. The template ships
- * a placeholder square, so every built app shows that square while running. We stamp the app's real
- * icon in instead: downscale (sips, in the CLI) → decode here → round the corners with the macOS
- * app-icon squircle mask → ensure RGBA (Tauri hard-requires alpha) → re-encode.
+ * WHY: a desktop shell can embed an icon PNG and set it as the RUNTIME app icon on macOS — which
+ * OVERRIDES the bundle icns/Assets.car in cmd+tab/Dock. A template placeholder would then show while
+ * the app runs, so we stamp the app's real icon in instead: downscale (sips, in the CLI) → decode here
+ * → round the corners with the macOS app-icon squircle mask → ensure RGBA (alpha is required) → re-encode.
  *
  * Supports 8-bit RGB / RGBA, non-interlaced PNG (what `sips` emits). Errors clearly on anything else.
  */

package/src/packs.ts

@@ -1,5 +1,5 @@
 /**
- * Module-pack resolver — the single public extension seam of appwrap (CE/EE seam A2).
+ * Module-pack resolver — the single public extension seam of appwrap.
  *
  * A "pack" is a directory (local, or an npm package) that contributes capabilities to a wrapper build
  * exactly like the built-in modules do: it exports `ModuleManifest[]` (the same contribution bags the
@@ -15,7 +15,7 @@
  *    own module is not an error).
  *
  * This one mechanism serves three audiences identically: a host layers its private packs, a consumer
- * app vendors its own copy of a module, and the community ships plugins — none of them patch CE.
+ * app vendors its own copy of a module, and the community ships plugins — none of them patch the core.
  *
  * PURE of CLI I/O: filesystem/npm resolution and pack import are injected ports (`resolvePack`/
  * `importPack`), so the merge logic unit-tests against in-memory fakes. The CLI wires the real ports.

package/src/plugin/index.ts

@@ -14,7 +14,7 @@
  *   });
  *
  * Types-first: `definePlugin` is an identity helper that validates + returns the def, which the plugin
- * entrypoint `export default`s. The multiplexed host (`host.ts`) `import()`s the built bundle and reads
+ * entrypoint `export default`s. The multiplexed host `import()`s the built bundle and reads
  * `.default`. Nothing runs at import time (unlike `defineHandlers`, which starts a loop) — the host
  * drives the lifecycle.
  */

package/src/plugin/types.ts

@@ -1,10 +1,10 @@
 /**
  * appwrap plugin contract — the PORT (`@livx.cc/appwrap/plugin`).
  *
- * A TS plugin consumes a CURATED, VERSIONED facade over the native `webview-control` primitives
- * ({@link WindowCtx}) — it never touches objc2 FFI. The plugin runs OUT-OF-WEBVIEW in the trusted
- * multiplexed Bun host (see `host.ts`); the host speaks a bidirectional line-JSON protocol over a
- * Unix domain socket to the Rust shell, which owns the primitives.
+ * A TS plugin consumes a CURATED, VERSIONED facade over the native window primitives
+ * ({@link WindowCtx}) — it never touches native FFI. The plugin runs OUT-OF-WEBVIEW in a trusted
+ * multiplexed Bun host, which speaks a bidirectional line-JSON protocol to the native shell that
+ * owns the primitives.
  *
  * IoC / Hollywood: the CORE calls the plugin — on window-created it fans out to each plugin whose
  * `attachTo` matches, invoking `onWindow(ctx)`. Plugins never reach into core internals.
@@ -37,7 +37,7 @@ export interface WindowIdentity {
 export type Dispose = () => void;
 
 /**
- * Curated, versioned facade over the native `webview-control` primitives, scoped to ONE window.
+ * Curated, versioned facade over the native window primitives, scoped to ONE window.
  * NOT raw FFI — a deliberately small subset (design risk #4: avoid a god-interface). Every method
  * marshals over the host↔shell socket as an `op` envelope and awaits a `result`.
  */
@@ -79,7 +79,7 @@ export interface PluginDef {
   onClose?(win: WindowIdentity): void;
 }
 
-// ── Wire protocol (host ↔ shell, one JSON object per line over a Unix domain socket) ──────────────
+// ── Wire protocol (host ↔ shell, one JSON object per line) ────────────────────────────────────────
 // Envelope: { pluginId?, windowId?, kind, method?, params?, id?, ... }. Route by pluginId × windowId.
 //   host → shell:  { kind:'ready',  plugins:[{ pluginId, methods:[…] }] }   (once, at boot)
 //   host → shell:  { kind:'op',     id, pluginId, windowId, method, params }  (a WindowCtx call)
@@ -101,7 +101,7 @@ export interface StampedPlugin {
   /** Bundle/build id derived from the config source (sanitized filename or package name). This is a
    * pre-bundle-load stamp — the plugin's real def `name` isn't known until the host `import()`s the
    * bundle. It is NOT the routing/diagnostic identifier: routing (matchScope, registry) and all
-   * diagnostics key off the loaded def `name` (see host.ts). Used only for the bundle filename. */
+   * diagnostics key off the loaded def `name`. Used only for the bundle filename. */
   bundleId: string;
   /** Config-level attachTo OVERRIDE (string forms only). Falls back to the def's own `attachTo`. */
   attachTo?: 'main' | 'all' | string;

package/src/testing.ts

@@ -1,5 +1,5 @@
 /**
- * Pack conformance validator — the public `@livx.cc/appwrap/testing` entry (CE/EE seam A8).
+ * Pack conformance validator — the public `@livx.cc/appwrap/testing` entry.
  *
  * A module pack (see packs.ts) is authored out-of-tree and staged into the shell at sync. Because a
  * malformed pack fails LATE (mid-generate, on a device build), this gives pack authors a FAST, offline
@@ -32,7 +32,7 @@ export interface ValidatePackResult {
 const NODE_BUILTIN_SET = new Set(builtinModules.flatMap((m) => [m, `node:${m}`]));
 
 /** The sanctioned shell-API specifier prefix a pack handler may deep-import (rewritten to relative on
- * staging). Any OTHER `@livx.cc/appwrap/...` deep import reaches into CE internals → rejected. */
+ * staging). Any OTHER `@livx.cc/appwrap/...` deep import reaches into internals → rejected. */
 const SANCTIONED_SHELL_PREFIX = '@livx.cc/appwrap/runtime/app/shell/';
 
 /** Map a handler file extension to the Bun.Transpiler loader for its dialect (mirrors cli.ts). */
@@ -51,7 +51,7 @@ function loaderFor(file: string): 'ts' | 'tsx' | 'js' | 'jsx' {
 function bareImportError(spec: string): string | null {
   // Sanctioned shell API — always fine.
   if (spec === SANCTIONED_SHELL_PREFIX.slice(0, -1) || spec.startsWith(SANCTIONED_SHELL_PREFIX)) return null;
-  // Any OTHER appwrap deep import escapes the sanctioned seam into CE internals.
+  // Any OTHER appwrap deep import escapes the sanctioned seam into internals.
   if (spec === '@livx.cc/appwrap' || spec.startsWith('@livx.cc/appwrap/')) {
     return `imports appwrap internals via "${spec}" — a pack may only deep-import the sanctioned ` +
       `"${SANCTIONED_SHELL_PREFIX}*" shell APIs.`;

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 }}