@livx.cc/appwrap 0.19.0

package/runtime/app/shell/capabilities.manifest.ts

@@ -0,0 +1,207 @@
+/**
+ * Capability manifest — the SINGLE, self-contained declaration of every appwrap capability.
+ *
+ * PURE DATA — no NativeScript globals — so the build-time CLI (bun) imports it to compose the shell,
+ * and the runtime imports it to build the handshake capability map. Each entry fully describes one
+ * capability's needs (permissions, background modes, native deps); the shell COLLECTS the union
+ * across the active set and dedups (two modules needing camera → one perm stamped once).
+ *
+ * Tiers:
+ *  - `core: true`  → always compiled in; cheap, no permissions (haptics, storage, toast, …).
+ *  - opt-in (default) → only active when listed in `appwrap.json.modules` (explicit mode). These
+ *    carry permissions / native deps / weight, so they're stripped from a build that doesn't ask
+ *    for them — no bundled handler advertisement, no permission prompt, no native dependency.
+ *
+ * Back-compat: when `appwrap.json` has NO `modules` key, the CLI treats EVERY capability as active
+ * (today's behavior) and permissions still come solely from `appwrap.json.permissions{}`.
+ */
+
+/** A native permission + a default human usage string (Apple requires app-facing copy).
+ * `appwrap.json.permissions{<domain>}` overrides the copy per-app; the key here is the iOS Info.plist
+ * key. Android perms need no usage string. */
+export interface IosPermission {
+  /** Info.plist key, e.g. 'NSCameraUsageDescription'. */
+  key: string;
+  /** Override-key into `appwrap.json.permissions{}` (the legacy domain name). */
+  domain: string;
+  /** Default usage string if the app doesn't override it. */
+  defaultUsage: string;
+}
+
+export interface ModuleManifest {
+  /** Capability name (also the handshake key + `kit.<name>` where 1:1). */
+  name: string;
+  /** Always-on, cheap, permission-free. Omitted/false = opt-in (gated by appwrap.json.modules). */
+  core?: boolean;
+  /** Handshake capability keys this module provides. Value 'native', or per-platform gating. */
+  capabilities: Record<string, 'native' | { ios?: boolean; android?: boolean }>;
+  /** The registration group this capability belongs to. Core caps share legacy groups (bundled
+   * together); opt-in NEW modules name their own group → the CLI imports it only when active, so it
+   * tree-shakes out of a build that doesn't use it. */
+  group: string;
+  ios?: {
+    permissions?: IosPermission[];
+    /** app.entitlements key/values (e.g. `{ 'com.apple.developer.healthkit': true }`). The CLI merges
+     * these (across active modules + push) into one App_Resources/iOS/app.entitlements. Values may be
+     * boolean, string, or string[]. */
+    entitlements?: Record<string, boolean | string | string[]>;
+  };
+  android?: {
+    /** AndroidManifest <uses-permission> names. */
+    permissions?: string[];
+    /** app.gradle dependency coordinates, e.g. 'androidx.health.connect:connect-client:1.1.0-rc01'. */
+    gradleDeps?: string[];
+    /** Module ships Kotlin native source → the CLI enables Kotlin in the NS Android build. */
+    kotlin?: boolean;
+    /** Raw XML injected inside the AndroidManifest `<application>` (activities, providers,
+     * intent-filters a capability needs — e.g. Health Connect's permission-rationale activity). */
+    manifestApplication?: string;
+  };
+  /** Module-owned native source: a dir under `runtime/modules-native/<nativeSrc>/` mirroring the
+   * App_Resources layout, copied into `native/` ONLY when the module is active (stays strippable).
+   * Defaults to the module `name` when the convention dir exists. */
+  nativeSrc?: string;
+}
+
+export const MODULES: ModuleManifest[] = [
+  // ── core (always on, no permissions) ───────────────────────────────────
+  { name: 'haptics', core: true, group: 'core', capabilities: { haptics: 'native' } },
+  { name: 'share', core: true, group: 'core', capabilities: { share: 'native', shareFiles: 'native' } },
+  { name: 'storage', core: true, group: 'core', capabilities: { storage: 'native', secureStorage: 'native' } },
+  { name: 'toast', core: true, group: 'core', capabilities: { toast: 'native' } },
+  { name: 'statusBar', core: true, group: 'core', capabilities: { statusBar: 'native', themeColor: 'native' } },
+  { name: 'device', core: true, group: 'extended', capabilities: { device: 'native' } },
+  { name: 'clipboard', core: true, group: 'extended', capabilities: { clipboard: 'native' } },
+  { name: 'network', core: true, group: 'extended', capabilities: { network: 'native' } },
+  { name: 'screen', core: true, group: 'extended', capabilities: { screen: 'native', dialogs: 'native', orientation: 'native' } },
+  { name: 'app', core: true, group: 'system', capabilities: { app: 'native', browser: 'native' } },
+
+  // ── opt-in: permission / dependency / weight-bearing ───────────────────
+  // POST_NOTIFICATIONS / VIBRATE / USE_BIOMETRIC etc. are in the template's baseline manifest already.
+  { name: 'notifications', group: 'extended', capabilities: { notifications: 'native' } },
+  {
+    name: 'biometrics', group: 'extended',
+    capabilities: { biometrics: 'native' },
+    ios: { permissions: [{ key: 'NSFaceIDUsageDescription', domain: 'faceid', defaultUsage: 'Authenticate with Face ID.' }] },
+  },
+  {
+    name: 'geo', group: 'extended',
+    capabilities: { geo: 'native' },
+    ios: { permissions: [{ key: 'NSLocationWhenInUseUsageDescription', domain: 'location', defaultUsage: 'Show your location.' }] },
+    android: { permissions: ['android.permission.ACCESS_FINE_LOCATION', 'android.permission.ACCESS_COARSE_LOCATION'] },
+  },
+  {
+    name: 'photos', group: 'extended',
+    capabilities: { photos: 'native' },
+    ios: { permissions: [{ key: 'NSPhotoLibraryUsageDescription', domain: 'photos', defaultUsage: 'Pick a photo from your library.' }] },
+  },
+  {
+    name: 'camera', group: 'media',
+    capabilities: { camera: 'native' },
+    ios: { permissions: [{ key: 'NSCameraUsageDescription', domain: 'camera', defaultUsage: 'Capture a photo.' }] },
+    android: { permissions: ['android.permission.CAMERA'] },
+  },
+  {
+    name: 'media', group: 'media',
+    capabilities: { media: 'native' },
+    ios: { permissions: [
+      { key: 'NSCameraUsageDescription', domain: 'camera', defaultUsage: 'Use the camera.' },
+      { key: 'NSMicrophoneUsageDescription', domain: 'microphone', defaultUsage: 'Use the microphone.' },
+    ] },
+    android: { permissions: ['android.permission.CAMERA', 'android.permission.RECORD_AUDIO'] },
+  },
+  {
+    name: 'motion', group: 'parity',
+    capabilities: { motion: 'native' },
+    ios: { permissions: [{ key: 'NSMotionUsageDescription', domain: 'motion', defaultUsage: 'Read device motion sensors.' }] },
+  },
+  {
+    name: 'contacts', group: 'parity',
+    capabilities: { contacts: 'native' },
+    android: { permissions: ['android.permission.READ_CONTACTS'] },
+  },
+  {
+    name: 'calendar', group: 'parity',
+    capabilities: { calendar: 'native' },
+    ios: { permissions: [
+      { key: 'NSCalendarsFullAccessUsageDescription', domain: 'calendar', defaultUsage: 'Add events to your calendar.' },
+      { key: 'NSCalendarsUsageDescription', domain: 'calendar', defaultUsage: 'Add events to your calendar.' },
+    ] },
+    android: { permissions: ['android.permission.READ_CALENDAR', 'android.permission.WRITE_CALENDAR'] },
+  },
+  {
+    name: 'reviews', group: 'system',
+    capabilities: { reviews: { ios: true, android: false } },
+  },
+  {
+    name: 'billing', group: 'billing',
+    capabilities: { billing: { ios: true, android: false } },
+  },
+
+  // ── oauth — system-browser OAuth (iOS ASWebAuthenticationSession) ──
+  // Opt-in, strippable (own handler file). No permissions/entitlements — ASWebAuthenticationSession
+  // needs none; it only relies on the app's urlScheme so the provider redirect returns to the app.
+  // Lets Google et al. complete sign-in they reject inside an embedded WebView (disallowed_useragent).
+  // Android (Custom Tabs + intent callback) is a future addition.
+  {
+    name: 'oauth', group: 'oauth',
+    capabilities: { oauth: { ios: true, android: false } },
+  },
+
+  // ── health (steps) — opt-in heavy module; FG live + BG via OS step store ──
+  {
+    name: 'health', group: 'health',
+    capabilities: { health: 'native' },
+    // iOS reads HealthKit (the Health app's aggregated total incl. Apple Watch): health-share usage
+    // string + the healthkit entitlement, both module-owned. No background execution — HealthKit
+    // already has the steps the OS recorded while the app was killed.
+    ios: {
+      permissions: [{ key: 'NSHealthShareUsageDescription', domain: 'health', defaultUsage: 'Read your step count from the Health app.' }],
+      entitlements: { 'com.apple.developer.healthkit': true },
+    },
+    // Android primary = Health Connect (system store, Wear-inclusive, survives kill — matches iOS).
+    // Its client is Kotlin-coroutine-only, so the module ships HealthConnectBridge.kt (nativeSrc) and
+    // flags kotlin:true. Falls back to SensorManager TYPE_STEP_COUNTER (ACTIVITY_RECOGNITION) when HC absent.
+    android: {
+      permissions: ['android.permission.health.READ_STEPS', 'android.permission.ACTIVITY_RECOGNITION'],
+      gradleDeps: [
+        'androidx.health.connect:connect-client:1.1.0-rc01',
+        'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0',
+      ],
+      kotlin: true,
+      // Health Connect refuses to honor permissions unless the app declares a rationale activity
+      // handling VIEW_PERMISSION_USAGE / HEALTH_PERMISSIONS (alias onto the NS main activity).
+      manifestApplication: `<activity-alias
+      android:name="ViewPermissionUsageActivity"
+      android:exported="true"
+      android:targetActivity="com.tns.NativeScriptActivity"
+      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
+      <intent-filter>
+        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
+        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
+      </intent-filter>
+    </activity-alias>`,
+    },
+    nativeSrc: 'health',
+  },
+];
+
+/** Opt-in registration groups that own their own NS handler file (strippable when inactive). Core
+ * groups (core/extended/parity/system/media/billing) are always bundled; only these are CLI-gated. */
+export const OPTIONAL_GROUPS = ['health', 'oauth'] as const;
+
+/** Resolve the active capability map for the handshake from a set of active capability names. */
+export function buildCapabilityMap(
+  activeNames: Set<string>,
+  platform: 'ios' | 'android'
+): Record<string, 'native' | 'none'> {
+  const map: Record<string, 'native' | 'none'> = {};
+  for (const m of MODULES) {
+    if (!m.core && !activeNames.has(m.name)) continue;
+    for (const [cap, val] of Object.entries(m.capabilities)) {
+      if (val === 'native') map[cap] = 'native';
+      else map[cap] = val[platform] ? 'native' : 'none';
+    }
+  }
+  return map;
+}

package/runtime/app/shell/config.ts

@@ -0,0 +1,35 @@
+/**
+ * Shell config — stamped by `appwrap init` from appwrap.json.
+ */
+export const SHELL_CONFIG = {
+  appId: 'cc.livx.hellowrap',
+  name: 'Hello AppWrap',
+  version: '0.1.0',
+  /** Entry file inside the bundled www/ folder. */
+  entry: 'index.html',
+  /** Page + status bar background while the WebView boots. */
+  backgroundColor: '#0b1020',
+  /** 'light' = white status bar icons. */
+  statusBarStyle: 'light' as 'light' | 'dark',
+  /** Android only (experimental). true = WebView draws edge-to-edge under transparent bars +
+   * safe-area insets injected as `--saie-*` CSS vars; false = bars show the page backgroundColor. */
+  edgeToEdge: false,
+  /** Loader: 'app' = app:// scheme handler (stable origin, ES modules, bundled www); 'file' = debug
+   * fallback; 'server' = load `serverUrl` live (dev HMR over LAN, or pointing at a deployed URL). */
+  loader: 'app' as 'app' | 'file' | 'server',
+  /** Live URL loaded when loader === 'server' (e.g. http://192.168.x.x:5173 dev, or a deployed https URL). */
+  serverUrl: '',
+  /** Absolute backend origin for an offline (app://) PWA whose API/WS calls were originally same-origin.
+   * Injected to the page as `window.__APPWRAP_BACKEND_ORIGIN__`; empty = same-origin (browser default). */
+  backendOrigin: '',
+  /** Debug/dev mode: keep the screen awake (no auto-lock while foreground) + WebView inspectable
+   * (Safari Web Inspector / chrome://inspect). Set true by `appwrap deploy`; never in store builds. */
+  debug: false,
+  /** Value written to `localStorage.DEBUG` in debug mode so the PWA logger goes verbose ('*' = all). */
+  debugLog: '*',
+  /** Remote push configured, per platform (iOS aps-environment entitlement / Android FCM). Drives the
+   * `push` capability flag at runtime by platform — off unless `appwrap.json.push` enables it, so an
+   * un-provisioned build honestly reports 'none' (and a personal-team iOS build keeps `pushIos:false`). */
+  pushIos: false,
+  pushAndroid: false,
+};

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

@@ -0,0 +1,270 @@
+import { WebView, Utils, knownFolders, path as nsPath, File } from '@nativescript/core';
+import { SHELL_CONFIG } from './config';
+import { mimeFor } from './mime';
+import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS } from './web-quirks';
+import { envGlobalsJs } from './env';
+import { requestPermissions } from './android-helpers';
+
+declare const android: any, java: any, androidx: any;
+
+/** Stable in-app origin — secure context, ES modules work (file:// blocks them). */
+export const APP_ORIGIN = 'https://appwrap.local';
+
+/**
+ * Web→native transport shim. postMessage tunnels through window.prompt(), which
+ * the shell intercepts synchronously in WebChromeClient.onJsPrompt — no compiled
+ * @JavascriptInterface class, no polling. Injected at document start (androidx.webkit)
+ * with an onPageStarted fallback; the guard makes double-injection a no-op.
+ */
+const TRANSPORT_SHIM = `(function(){
+  if (window.appwrapNative) return;
+  window.appwrapNative = { postMessage: function(json){ window.prompt('__appwrap__:' + json); } };
+})();`;
+
+const PROMPT_PREFIX = '__appwrap__:';
+
+/** Document-start scripts: env hints + framework globals (backend origin) + bridge transport +
+ * native-feel. Globals first so the page can read __APPWRAP__ / __APPWRAP_BACKEND_ORIGIN__ before its
+ * own scripts run. Built lazily (not a const) so envGlobalsJs() detects against a live activity context. */
+function buildBootstrapJs(): string {
+  return `${envGlobalsJs()}\n${APPWRAP_GLOBALS_JS}\n${TRANSPORT_SHIM}\n${NATIVE_FEEL_JS}`;
+}
+
+/**
+ * Android CustomWebView — replaces NS's default clients after creation:
+ * WebChromeClient.onJsPrompt is the appwrap transport, WebViewClient
+ * intercepts https://appwrap.local/* and serves the bundled PWA from www/
+ * (mirror of the iOS app:// WKURLSchemeHandler).
+ */
+export class CustomWebView extends WebView {
+  /** Set by the bridge before load; receives raw envelope JSON. */
+  onAppwrapMessage: ((json: string) => void) | null = null;
+
+  initNativeView(): void {
+    super.initNativeView();
+    const wv = this.android;
+    if (!wv) return;
+
+    // Debug mode only: debuggable via chrome://inspect (full console + network) + keep the screen
+    // awake while foreground for continuous troubleshooting. Off in store builds.
+    if (SHELL_CONFIG.debug) {
+      try { android.webkit.WebView.setWebContentsDebuggingEnabled(true); } catch (e) { /* older API */ }
+      try { wv.setKeepScreenOn(true); } catch (e) { /* no-op */ }
+    }
+
+    const settings = wv.getSettings();
+    settings.setJavaScriptEnabled(true);
+    settings.setDomStorageEnabled(true);
+    settings.setAllowFileAccess(true);
+    settings.setMediaPlaybackRequiresUserGesture(false); // speaker: autoplay allowed
+    // Native feel: no pinch-zoom controls.
+    settings.setSupportZoom(false);
+    settings.setBuiltInZoomControls(false);
+    settings.setDisplayZoomControls(false);
+    // No rubber-band overscroll glow.
+    wv.setOverScrollMode(android.view.View.OVER_SCROLL_NEVER);
+
+    this.installDocumentStartShim(wv);
+    wv.setWebViewClient(createAssetServingClient());
+    wv.setWebChromeClient(this.createTransportChromeClient());
+  }
+
+  /**
+   * Stop/restart the WebView's render + JS-timer pipeline when the app is backgrounded/foregrounded
+   * (wired to Application suspend/resume in main-page). Android does NOT reliably halt rAF/CSS
+   * animations when the activity isn't visible, so a page running a continuous animation keeps the
+   * compositor — and the CPU — busy in the background. onPause()/pauseTimers() stops that; the latter
+   * is process-wide but harmless with our single WebView. iOS suspends rAF on its own (no-op there).
+   */
+  setRenderingActive(active: boolean): void {
+    const wv = this.android;
+    if (!wv) return;
+    try {
+      if (active) { wv.onResume(); wv.resumeTimers(); }
+      else { wv.onPause(); wv.pauseTimers(); }
+    } catch (e) {
+      console.warn('AppWrap: setRenderingActive failed', e);
+    }
+  }
+
+  private installDocumentStartShim(wv: any): void {
+    try {
+      const wkt = androidx.webkit;
+      if (wkt.WebViewFeature.isFeatureSupported(wkt.WebViewFeature.DOCUMENT_START_SCRIPT)) {
+        const rules = new java.util.HashSet();
+        rules.add(APP_ORIGIN);
+        wkt.WebViewCompat.addDocumentStartJavaScript(wv, buildBootstrapJs(), rules);
+        return;
+      }
+      console.warn('AppWrap: DOCUMENT_START_SCRIPT unsupported — relying on onPageStarted shim');
+    } catch (e) {
+      console.warn('AppWrap: addDocumentStartJavaScript failed', e);
+    }
+  }
+
+  private createTransportChromeClient(): any {
+    const owner = new WeakRef<CustomWebView>(this);
+    const ChromeClient = (android.webkit.WebChromeClient as any).extend({
+      onJsPrompt(_view: any, _url: string, message: string, _defaultValue: string, result: any): boolean {
+        if (typeof message === 'string' && message.startsWith(PROMPT_PREFIX)) {
+          result.confirm('');
+          const view = owner.get ? owner.get() : (owner as any).deref();
+          view?.onAppwrapMessage?.(message.slice(PROMPT_PREFIX.length));
+          return true;
+        }
+        return false; // genuine page prompt — default handling
+      },
+
+      // getUserMedia: grant the WebView's per-origin capture after ensuring the
+      // app holds the matching OS runtime permission (CAMERA / RECORD_AUDIO).
+      onPermissionRequest(request: any): void {
+        const PR = android.webkit.PermissionRequest;
+        const resources: string[] = Array.from(request.getResources());
+        const perms = new Set<string>();
+        for (const r of resources) {
+          if (r === PR.RESOURCE_VIDEO_CAPTURE) perms.add('android.permission.CAMERA');
+          if (r === PR.RESOURCE_AUDIO_CAPTURE) perms.add('android.permission.RECORD_AUDIO');
+        }
+        if (!perms.size) {
+          Utils.dispatchToMainThread(() => request.grant(request.getResources()));
+          return;
+        }
+        requestPermissions(Array.from(perms)).then((ok) =>
+          Utils.dispatchToMainThread(() => (ok ? request.grant(request.getResources()) : request.deny()))
+        );
+      },
+    });
+    return new ChromeClient();
+  }
+}
+
+/** https://appwrap.local/<path> → file under www/; SPA fallback to the entry for extension-less misses. */
+function createAssetServingClient(): any {
+  const wwwPath = nsPath.join(knownFolders.currentApp().path, 'www');
+
+  const respond = (filePath: string, ext: string) => {
+    const stream = new java.io.FileInputStream(filePath);
+    return new android.webkit.WebResourceResponse(mimeFor(ext, filePath), 'utf-8', stream);
+  };
+
+  const emptyStream = () => new java.io.ByteArrayInputStream((Array as any).create('byte', 0));
+
+  /**
+   * PROXY a non-local path to the backend (mirror of the iOS scheme-handler proxy) so a
+   * same-origin PWA's relative /api, /functions and vendor (/_vendor/sdk.js) requests resolve
+   * under app://appwrap.local — no CORS, same-origin.
+   *
+   * THREADING: NativeScript marshals the shouldInterceptRequest JS callback onto the JS/main thread,
+   * so a synchronous HttpURLConnection here throws NetworkOnMainThreadException. Instead we return
+   * immediately with a PipedInputStream and do the network read on a background java.lang.Thread that
+   * pumps the body into the pipe — the WebView drains it lazily. mime/charset are best-effort from the
+   * path extension (we can't read upstream headers without first blocking).
+   *
+   * LIMITATION: Android's shouldInterceptRequest exposes no request body, so only body-less methods
+   * (GET/HEAD) are proxied — POST/PUT/PATCH return 501 rather than silently sending an empty body.
+   * (BodDB writes ride the WS, not HTTP POST, so this is rarely hit.)
+   */
+  const proxyToBackend = (rel: string, query: string, ext: string, method: string, headers: any): any => {
+    if (method !== 'GET' && method !== 'HEAD') {
+      return new android.webkit.WebResourceResponse(
+        'text/plain', 'utf-8', 501, 'Not Implemented', new java.util.HashMap(),
+        new java.io.ByteArrayInputStream(new java.lang.String(
+          'appwrap Android shell cannot proxy request bodies (shouldInterceptRequest limitation)'
+        ).getBytes('UTF-8'))
+      );
+    }
+    const pin = new java.io.PipedInputStream(1 << 16);
+    const pout = new java.io.PipedOutputStream(pin);
+    const target = `${SHELL_CONFIG.backendOrigin.replace(/\/+$/, '')}/${rel}${query}`;
+    const pump = new java.lang.Runnable({
+      run() {
+        let is: any = null;
+        try {
+          const conn = new java.net.URL(target).openConnection();
+          conn.setRequestMethod(method);
+          conn.setInstanceFollowRedirects(true);
+          conn.setConnectTimeout(15000);
+          conn.setReadTimeout(20000);
+          if (headers) {
+            const it = headers.entrySet().iterator();
+            while (it.hasNext()) {
+              const e = it.next();
+              const k = String(e.getKey());
+              if (k.toLowerCase() === 'host') continue; // let URLConnection set Host from the target
+              conn.setRequestProperty(k, String(e.getValue()));
+            }
+          }
+          conn.connect();
+          const status = conn.getResponseCode();
+          is = status >= 400 ? conn.getErrorStream() : conn.getInputStream();
+          const buf = (Array as any).create('byte', 16384);
+          let n: number;
+          while (is && (n = is.read(buf)) !== -1) pout.write(buf, 0, n);
+        } catch (e) {
+          console.log('[appwrap] proxy failed for /' + rel + ': ' + e);
+        } finally {
+          try { if (is) is.close(); } catch (e) { /* no-op */ }
+          try { pout.close(); } catch (e) { /* no-op */ }
+        }
+      },
+    });
+    new java.lang.Thread(pump).start();
+    const outHeaders = new java.util.HashMap();
+    outHeaders.put('Access-Control-Allow-Origin', '*');
+    outHeaders.put('Cache-Control', 'no-cache');
+    // mime/charset best-effort from the path; status 200 (real status is unknown until the bg read).
+    return new android.webkit.WebResourceResponse(mimeFor(ext, rel), 'utf-8', 200, 'OK', outHeaders, pin);
+  };
+
+  const Client = (android.webkit.WebViewClient as any).extend({
+    shouldInterceptRequest(_view: any, request: any): any {
+      const isObj = typeof request !== 'string';
+      const url: string = isObj ? String(request.getUrl().toString()) : request;
+      if (!url.startsWith(APP_ORIGIN)) return null; // external — let WebView handle it
+
+      const tail = url.slice(APP_ORIGIN.length);
+      const qIdx = tail.search(/[?#]/);
+      const query = qIdx >= 0 && tail[qIdx] === '?' ? tail.slice(qIdx).split('#')[0] : '';
+      let rel = decodeURIComponent(tail.split(/[?#]/)[0]).replace(/^\/+/, '');
+      if (!rel) rel = SHELL_CONFIG.entry;
+      let filePath = nsPath.join(wwwPath, rel);
+      const ext = rel.includes('.') ? rel.split('.').pop()!.toLowerCase() : '';
+
+      if (File.exists(filePath)) return respond(filePath, ext);
+
+      if (!ext) {
+        // extension-less navigation → SPA fallback
+        return respond(nsPath.join(wwwPath, SHELL_CONFIG.entry), 'html');
+      }
+      // Not a local asset → proxy to the backend (mirror of iOS), making relative
+      // backend/vendor requests same-origin under app://appwrap.local.
+      if (SHELL_CONFIG.backendOrigin) {
+        const method = (isObj && request.getMethod && String(request.getMethod())) || 'GET';
+        const headers = isObj && request.getRequestHeaders ? request.getRequestHeaders() : null;
+        return proxyToBackend(rel, query, ext, method.toUpperCase(), headers);
+      }
+      return new android.webkit.WebResourceResponse(
+        'text/plain', 'utf-8', 404, 'Not Found', new java.util.HashMap(), emptyStream()
+      );
+    },
+
+    onPageStarted(view: any, _url: string, _favicon: any): void {
+      // Fallback injection — no-op when the document-start scripts already ran
+      view.evaluateJavascript(buildBootstrapJs(), null);
+    },
+
+    // `appwrap dev` points at a LAN dev server that almost always uses a self-signed / mkcert TLS
+    // cert the device's trust store doesn't know — the WebView would otherwise hard-fail with
+    // ERR_CERT_AUTHORITY_INVALID. Proceed past it ONLY in a debug build AND only when actually in
+    // server-loader (dev) mode. Production app:// builds never reach this (local assets, no TLS).
+    onReceivedSslError(_view: any, handler: any, error: any): void {
+      if (SHELL_CONFIG.debug && SHELL_CONFIG.loader === 'server') {
+        console.warn('AppWrap: proceeding past dev-server SSL error (debug+server only):', String(error));
+        handler.proceed();
+      } else {
+        handler.cancel();
+      }
+    },
+  });
+  return new Client();
+}