@livx.cc/appwrap 0.58.4 → 0.60.0

package/package.json

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

@@ -86,7 +86,7 @@ function armNativeSurfaceRecovery(webView: CustomWebView): void {
 
 export function onPageLoaded(args: EventData): void {
   const page = args.object as Page;
-  page.bindingContext = { backgroundColor: SHELL_CONFIG.backgroundColor };
+  page.bindingContext = { backgroundColor: SHELL_CONFIG.backgroundColor, appName: SHELL_CONFIG.name };
   bindStatusBarPage(page);
   if (isAndroid) enableAndroidEdgeToEdge();
   applyThemeColor(SHELL_CONFIG.themeColor); // manifest/config theme_color → native chrome at boot

package/runtime/app/main-page.xml

@@ -9,7 +9,7 @@
     <!-- 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="{{ appName }}" 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" />

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/config.ts

@@ -74,4 +74,11 @@ export const SHELL_CONFIG = {
    * inert. `envs` = declared presets; `allowPattern` = anchored regex gating "Other" (default-deny
    * when ''). Stamped by `appwrap init`/`sync` — see `stampShellConfig`. */
   envSwitcher: { enabled: false, envs: [] as { label: string; url: string }[], allowPattern: '' },
+  /** TCC-gated web APIs this build DECLARED (active modules + the config's `permissions{}`) — what the
+   * document-start capability guard exposes to the page. NOT the same question as "is the Info.plist
+   * usage string present": the plist also carries the webview baseline (NSCameraUsageDescription is
+   * stamped in every build so WKWebView's `<input type="file">` "Take Photo" can't TCC-kill the
+   * process), and an app that never asked for the camera must still not be handing `getUserMedia` to
+   * whatever page it renders. Stamped by `appwrap init`/`sync` — see `stampShellConfig`. */
+  webCaps: { camera: false, microphone: false, geolocation: false },
 };

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/custom-webview.ios.ts

@@ -332,11 +332,15 @@ export class CustomWebView extends WebView {
     // (reject camera/mic/geolocation in JS before WebKit's native path — see capabilityGuardJs) +
     // native-feel suppression, all injected before the page's own scripts run. Globals first so the page
     // can read __APPWRAP__ / __APPWRAP_BACKEND_ORIGIN__.
-    const hasPlistKey = (k: string) => !!NSBundle.mainBundle.objectForInfoDictionaryKey(k);
+    // Driven by the STAMPED declaration, not by sniffing Info.plist: NSCameraUsageDescription is now
+    // present in every build (the webview baseline — so WKWebView's file-input "Take Photo" can't
+    // TCC-kill us), and reading presence would therefore open getUserMedia({video}) to every page an
+    // app renders, including ones a loader:'server' shell doesn't control. SHELL_CONFIG.webCaps is
+    // what the app actually declared (modules + `permissions{}`).
     const capabilityGuard = capabilityGuardJs({
-      camera: hasPlistKey('NSCameraUsageDescription'),
-      microphone: hasPlistKey('NSMicrophoneUsageDescription'),
-      geolocation: hasPlistKey('NSLocationWhenInUseUsageDescription'),
+      camera: SHELL_CONFIG.webCaps.camera,
+      microphone: SHELL_CONFIG.webCaps.microphone,
+      geolocation: SHELL_CONFIG.webCaps.geolocation,
     });
     const swGuard = serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker);
     const extNavGuard = externalNavGuardJs(SHELL_CONFIG.openNewWindowsInBrowser);

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

@@ -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,
@@ -87,6 +86,12 @@ const IOS_PERMISSION_KEYS: Record<string, string[]> = {
   calendar: ['NSCalendarsFullAccessUsageDescription', 'NSCalendarsUsageDescription'],
 };
 
+/** Default copy for the always-stamped NSCameraUsageDescription (see "the webview baseline" in
+ * nativeReqs). Written for an App Review reader: it describes the ONLY way a plain appwrap app reaches
+ * the camera — choosing "Take Photo" from a file upload. An app that calls the camera directly (the
+ * `camera`/`scanner` modules, or its own `permissions.camera`) replaces this with its own copy. */
+const WEBVIEW_BASELINE_CAMERA_USAGE = 'Take a photo when you choose “Take Photo” while attaching a file.';
+
 /** Runtime permissions stamped into AndroidManifest.xml per declared domain.
  * photos/faceid need none: system picker / USE_BIOMETRIC is baseline. */
 const ANDROID_PERMISSION_KEYS: Record<string, string[]> = {
@@ -109,21 +114,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 +142,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 +150,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;
 }
 
@@ -235,6 +238,11 @@ interface NativeReqs {
   activeOptIn: string[];           // opt-in capability names that are active (for the handshake map)
   activeOptionalGroups: string[];  // strippable handler groups (own file) that are active
   iosPlist: Array<{ key: string; usage: string }>;
+  /** What the app DECLARED it wants the web layer to be able to use — modules + `permissions{}`, and
+   * deliberately NOT the webview baseline. Drives the shell's document-start capability guard.
+   * Kept separate from `iosPlist` because the two answer different questions: the plist must cover
+   * everything the OS can kill us for REACHING, the guard must expose only what the app ASKED for. */
+  webCaps: { camera: boolean; microphone: boolean; geolocation: boolean };
   iosEntitlements: Record<string, boolean | string | string[]>;
   androidPerms: string[];
   androidGradleDeps: string[];
@@ -280,7 +288,11 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
       for (const p of m.ios?.permissions ?? []) {
         if (seenKeys.has(p.key)) continue;
         seenKeys.add(p.key);
-        iosPlist.push({ key: p.key, usage: cfg.permissions?.[p.domain as keyof typeof cfg.permissions] ?? p.defaultUsage });
+        // `permissions{}` overrides the module's default COPY. A `false` there is an opt-out of the
+        // webview baseline (below), never of a module's own key — the module ships native code that
+        // touches the class, so the string is mandatory; fall back to the default copy.
+        const override = cfg.permissions?.[p.domain as keyof typeof cfg.permissions];
+        iosPlist.push({ key: p.key, usage: typeof override === 'string' && override ? override : p.defaultUsage });
       }
       for (const ap of m.android?.permissions ?? []) androidPerms.add(ap);
       for (const g of m.android?.gradleDeps ?? []) gradle.add(g);
@@ -292,14 +304,52 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
       // resolves under the pack's own dir, so it must not be conflated with the built-in dir names.
       if (m.nativeSrc && !packInfo(m.name)) nativeSrc.push(m.nativeSrc);
     }
-  } else {
-    // legacy: only what `permissions{}` declares (via the key maps) — no behavior change
-    for (const [domain, text] of Object.entries(cfg.permissions ?? {})) {
-      for (const key of IOS_PERMISSION_KEYS[domain] ?? []) {
-        if (text && !seenKeys.has(key)) { seenKeys.add(key); iosPlist.push({ key, usage: text }); }
-      }
-      for (const p of ANDROID_PERMISSION_KEYS[domain] ?? []) androidPerms.add(p);
+  }
+
+  // A DECLARED permission is always stamped — in BOTH modes. Before, `permissions{}` was read only in
+  // legacy mode; with `modules` present it merely overrode a module's usage copy, so declaring a domain
+  // no module owned stamped NOTHING. That silent inertness shipped a store rejection (Copy Bin,
+  // Guideline 2.1(a): TCC killed the app for a missing NSCameraUsageDescription). Module-derived keys are
+  // collected FIRST and win the dedupe, so an app whose declared domains its modules already own stamps
+  // byte-identically. `false` = an explicit opt-out (see the webview baseline below), never a usage string.
+  for (const [domain, text] of Object.entries(cfg.permissions ?? {})) {
+    if (text === false) continue;
+    for (const key of IOS_PERMISSION_KEYS[domain] ?? []) {
+      if (text && !seenKeys.has(key)) { seenKeys.add(key); iosPlist.push({ key, usage: text }); }
     }
+    for (const p of ANDROID_PERMISSION_KEYS[domain] ?? []) androidPerms.add(p);
+  }
+
+  // Snapshot the DECLARED capabilities before the baseline widens the plist — see NativeReqs.webCaps.
+  const webCaps = {
+    camera: seenKeys.has('NSCameraUsageDescription'),
+    microphone: seenKeys.has('NSMicrophoneUsageDescription'),
+    geolocation: seenKeys.has('NSLocationWhenInUseUsageDescription'),
+  };
+
+  // ── The webview baseline ───────────────────────────────────────────────────────────────────────
+  // The shell's invariant is that every TCC-gated capability a WEB PAGE can reach is either DECLARED
+  // (usage string present) or BLOCKED before WebKit enters its native path — see mediaCaptureGuardJs /
+  // geolocationGuardJs, which reject getUserMedia + geolocation in JS at document-start.
+  //
+  // `<input type="file">` is the one reachable path with no such seam: WKWebView's own picker is native
+  // and internal, it offers "Take Photo" for an image accept, and TCC hard-kills the HOST process for a
+  // camera access with no usage string. There is no JS hook to suppress that menu item and no config in
+  // which it is absent — EVERY appwrap iOS build can reach it. When the answer is unconditional the
+  // correct mechanism is a default, not a warning the developer has no way to act on: an app author
+  // reads `modules` as "features we call", and nothing about a file input reads as "camera".
+  //
+  // So the key is stamped by default, with honest copy, overridable via `permissions.camera` and
+  // opt-out-able with `permissions: { camera: false }`. An unused iOS usage string is inert (it is only
+  // ever surfaced when the class is actually requested) — it is not an App Review flag, unlike an
+  // entitlement or a background mode.
+  //
+  // iOS only: the Android chooser's capture path already handles an UNDECLARED CAMERA permission (it
+  // checks `declares()` and falls back to the plain picker — file-chooser.android.ts), so Android needs
+  // nothing and stays opt-in; adding a runtime permission there would change the Play listing.
+  if (cfg.permissions?.camera !== false && !seenKeys.has('NSCameraUsageDescription')) {
+    seenKeys.add('NSCameraUsageDescription');
+    iosPlist.push({ key: 'NSCameraUsageDescription', usage: WEBVIEW_BASELINE_CAMERA_USAGE });
   }
 
   // Active PACK modules (from the config's modulePacks) — their native source + register handler
@@ -319,6 +369,7 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
     activeOptIn: optIn.filter((m) => active.has(m.name)).map((m) => m.name),
     activeOptionalGroups: OPTIONAL_GROUPS.filter((g) => activeMods.some((m) => m.group === g)),
     iosPlist,
+    webCaps,
     iosEntitlements,
     androidPerms: [...androidPerms],
     androidGradleDeps: [...gradle],
@@ -342,7 +393,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
@@ -862,6 +913,12 @@ export async function loadConfig(cwd: string, flags: Record<string, string>): Pr
 export function stampShellConfig(outDir: string, cfg: AppwrapConfig): void {
   // Resolve the env-switcher block. Absent block OR `enabled:false` → the whole feature is inert
   // (the shell reads `envSwitcher.enabled`). `allowPattern`/`envs` default to empty (default-deny).
+  // Which TCC-gated web APIs this build DECLARED (modules + `permissions{}`). The shell's guard used to
+  // sniff Info.plist for the usage strings, but the plist now also carries the webview baseline
+  // (an always-present NSCameraUsageDescription so the file-input picker can't kill the process) —
+  // sniffing it would silently hand getUserMedia({video}) to every app, including a loader:'server'
+  // shell showing pages the author doesn't control. Intent and plist are now stamped separately.
+  const webCaps = nativeReqs(cfg).webCaps;
   const es = cfg.envSwitcher;
   const envSwitcher = {
     enabled: !!es && es.enabled !== false,
@@ -896,6 +953,7 @@ export const SHELL_CONFIG = {
   pushRegistrationUrl: ${JSON.stringify(cfg.push?.registrationUrl ?? '')},
   iosKeyboardExtraLift: ${JSON.stringify(cfg.iosKeyboardExtraLift ?? 82)},
   envSwitcher: ${JSON.stringify(envSwitcher)} as { enabled: boolean; envs: { label: string; url: string }[]; allowPattern: string },
+  webCaps: ${JSON.stringify(webCaps)} as { camera: boolean; microphone: boolean; geolocation: boolean },
 };
 `;
   writeFileSync(join(outDir, 'app/shell/config.ts'), content);
@@ -2040,15 +2098,20 @@ export function renderCiWorkflow(src: string, ctx: CiRenderContext): string {
     : 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:')) { dropBlock = !holds(t.slice(5)); continue; }
-    if (t === '#@end') { dropBlock = false; continue; }
+    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)
@@ -2195,7 +2258,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; }
@@ -3146,7 +3209,29 @@ function buildInputStats(cwd: string, cfg: { pwaDist?: string; overrides?: strin
    }
   }
   stats.push({ sum: runtime, newest: runtimeNewest });
-  return { parts: stats.map((s) => s.sum), newest: Math.max(...stats.map((s) => s.newest)) };
+  const parts = stats.map((s) => s.sum);
+  // The STAMPED shell config (native/app/shell/config.ts) — compiled into bundle.js, and the ONLY
+  // input that carries values which never touch a fingerprinted file. `dev --url` / `deploy` stamp it
+  // from the EFFECTIVE cfg (serverUrl, loader, debug), so with `--url` every other input is byte-identical
+  // and the fingerprint matched → "inputs unchanged" → the previous .ipa (carrying the PREVIOUS
+  // serverUrl) was reinstalled while the on-disk config said the new one. Silent stale deploy.
+  // CONTENT, not mtime: sync/stamp rewrites this file unconditionally on every run, so its mtime is
+  // pure noise (it would bust the cache always). Deliberately excluded from `newest` for the same
+  // reason — an always-now mtime would make the `--resume` gate unusable, and the fingerprint is the
+  // real gate; --resume is the evidence-relaxed first-run path by construction.
+  parts.push(stringHash(readFileIfExists(join(resolve(cwd, flags.out ?? 'native'), 'app/shell/config.ts'))));
+  return { parts, newest: Math.max(...stats.map((s) => s.newest)) };
+}
+
+function readFileIfExists(p: string): string {
+  try { return readFileSync(p, 'utf8'); } catch { return ''; }
+}
+
+/** djb2 over a string — same family as the fingerprint hash; only needs to change when content does. */
+function stringHash(s: string): number {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = (((h << 5) + h) ^ s.charCodeAt(i)) >>> 0;
+  return h;
 }
 
 /** Newest mtime across every build input — the evidence the `--resume` gate needs when no build cache
@@ -3660,6 +3745,11 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
   // ungated. (A fingerprintMatch skip already has an identical cache; nothing to write.)
   if (!canSkipBuild || adoptCache) writeBuildCache(outDir, 'ios', { fingerprint: fp, artifactPath: ipaPath, builtAt: new Date().toISOString() });
 
+  // Prove the .ipa we're about to install actually carries the serverUrl we just stamped — the CLI used
+  // to print "✓ Deployed" while shipping an artifact built from a PREVIOUS URL (a build-skip whose cache
+  // key ignored the stamped shell config). Cheap, and it fails BEFORE the install rather than silently.
+  assertShippedServerUrl(ipaPath, cfg);
+
   console.log(`▶ installing ${ipa} → ${device.name} [${device.transport}]`);
   let installedViaUsbmux = false;
   let installed = false;
@@ -3753,6 +3843,31 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
     : `✓ Deployed to ${device.name}.`);
 }
 
+/** Deploy-time verification for `loader:'server'`: the .ipa's compiled bundle must contain the exact
+ * `serverUrl` we stamped. Reads the bundle straight out of the zip (no extraction). Exits on mismatch —
+ * shipping a shell pointed at the WRONG origin looks like a working deploy and is the hardest class of
+ * bug to see from the outside. Unverifiable (no unzip / bundle not found) → warn, never block. */
+function assertShippedServerUrl(ipaPath: string, cfg: AppwrapConfig): void {
+  if ((cfg.loader ?? 'app') !== 'server' || !cfg.serverUrl) return;
+  let bundle = '';
+  try {
+    bundle = execFileSync('sh', ['-c', `unzip -p ${JSON.stringify(ipaPath)} 'Payload/*.app/app/bundle.js'`], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  } catch { /* no unzip / unexpected layout → fall through to the unverifiable warning */ }
+  if (!bundle) return void console.warn(`  ⚠ could not read the bundle out of ${ipaPath.split('/').pop()} — shipped serverUrl NOT verified.`);
+  if (bundle.includes(JSON.stringify(cfg.serverUrl))) {
+    console.log(`✓ verified shipped serverUrl → ${cfg.serverUrl}`);
+    return;
+  }
+  const shipped = [...bundle.matchAll(/serverUrl:\s*("(?:[^"\\]|\\.)*")/g)].map((m) => m[1]);
+  console.error(
+    `\n✖ The .ipa does NOT carry the serverUrl that was just stamped.\n` +
+      `  stamped: ${cfg.serverUrl}\n` +
+      (shipped.length ? `  in .ipa: ${shipped.join(', ')}\n` : '') +
+      `  → a stale artifact was about to be installed. Re-run with --force to rebuild.\n`
+  );
+  process.exit(1);
+}
+
 /** Install an .ipa over usbmux via ideviceinstaller — a separate stack from devicectl/CoreDevice, so it
  * works when the CoreDevice tunnel is stuck. Returns false if ideviceinstaller is absent or the install
  * fails (the caller then prints the re-plug / brew-install remedy). */
@@ -4110,7 +4225,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
@@ -316,11 +245,17 @@ export interface AppwrapConfig {
    * testing — products resolve without App Store Connect. Only applies when launched from
    * Xcode (simulator or device-from-Xcode), not a standalone devicectl sideload. */
   storekitConfig?: string;
-  /** Permission usage strings, keyed by domain. Only listed ones are stamped
-   * (iOS: Info.plist usage string; Android: <uses-permission>). 'contacts' has no
-   * iOS key (CNContactPicker needs none) — it only stamps Android READ_CONTACTS. */
+  /** Permission usage strings, keyed by domain. A listed domain is ALWAYS stamped (iOS: Info.plist
+   * usage string; Android: <uses-permission>) — with or without `modules`; when a module already owns
+   * the same key, the string here overrides its default copy. 'contacts' has no iOS key
+   * (CNContactPicker needs none) — it only stamps Android READ_CONTACTS.
+   *
+   * `camera` is stamped by DEFAULT in every iOS build: WKWebView's `<input type="file">` picker offers
+   * "Take Photo", and iOS hard-kills the app for a camera access with no usage string. Pass
+   * `camera: false` to opt out (only for an app with no file inputs at all), or your own string to
+   * replace the default copy. */
   permissions?: Partial<
-    Record<'location' | 'photos' | 'camera' | 'microphone' | 'faceid' | 'calendar' | 'contacts' | 'motion' | 'tracking', string>
+    Record<'location' | 'photos' | 'camera' | 'microphone' | 'faceid' | 'calendar' | 'contacts' | 'motion' | 'tracking', string | false>
   >;
   /** App Tracking Transparency tracking domains (iOS, `tracking` module). When the module is active
    * the CLI sets the privacy manifest's `NSPrivacyTracking` → true and fills `NSPrivacyTrackingDomains`
@@ -357,8 +292,8 @@ 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
+  /** 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
@@ -367,10 +302,9 @@ export interface AppwrapConfig {
   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

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.`;