@livx.cc/appwrap 0.42.4 → 0.46.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.42.4",
+  "version": "0.46.1",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",
@@ -30,17 +30,19 @@
   "exports": {
     ".": "./src/config.ts",
     "./config": "./src/config.ts",
+    "./handlers": "./src/handlers.ts",
     "./cli": "./src/cli.ts"
   },
   "files": [
     "src",
     "runtime",
+    "runtime-desktop",
     "templates",
     "scripts/stage-assets.mjs"
   ],
   "scripts": {
     "prepack": "node scripts/stage-assets.mjs",
-    "postpack": "rm -rf runtime templates"
+    "postpack": "rm -rf runtime runtime-desktop templates"
   },
   "publishConfig": {
     "access": "public"

package/runtime/app/app.ts

@@ -48,6 +48,21 @@ if (isIOS) {
       onDeepLink(url.absoluteString);
       return true;
     }
+    // Universal links (https://<associated-domain>/...) arrive as a browsing user
+    // activity, NOT via openURL. Without this, tapping an https app link opens Safari
+    // instead of the app. Requires the associated-domains entitlement (iosEntitlements).
+    applicationContinueUserActivityRestorationHandler(
+      _app: UIApplication,
+      userActivity: NSUserActivity,
+      _restorationHandler: (restorableObjects: NSArray<any>) => void
+    ): boolean {
+      if (userActivity.activityType === NSUserActivityTypeBrowsingWeb && userActivity.webpageURL) {
+        console.log('AppWrap: universalLink', userActivity.webpageURL.absoluteString);
+        onDeepLink(userActivity.webpageURL.absoluteString);
+        return true;
+      }
+      return false;
+    }
     // Drives `kit.screen.orientation.lock` — UIKit reads this on every rotation.
     applicationSupportedInterfaceOrientationsForWindow(_app: UIApplication, _window: UIWindow): UIInterfaceOrientationMask {
       // iosOrientationMask() returns the raw bitmask as a number; the protocol types it as the enum.

package/runtime/app/main-page.ts

@@ -116,7 +116,16 @@ export function onPageLoaded(args: EventData): void {
 
   const webView = page.getViewById<CustomWebView>('webview');
   bridge.attach(webView);
-  if (isIOS) armNativeSurfaceRecovery(webView); // global freeze-recovery on any native modal dismiss
+  // NOTE: the GLOBAL UIWindowDidBecomeHidden freeze-recovery observer is intentionally NOT armed.
+  // It over-fired: the iOS edit menu / text-selection callout / AutoFill bar present in their own
+  // floating UIWindows, and their normal appear/disappear churn hides a transient window → the observer
+  // ran neutralizeStrayWindows() and DETACHED the just-shown edit-menu window (a plain UIWindow, so no
+  // class filter can distinguish it from a real orphan) → Copy/Paste + AutoFill silently dead on EVERY
+  // text field (device-verified via the [native:recover] log). Freeze recovery still runs via the
+  // explicit per-surface dismiss callbacks (billing/oauth/share/PHPicker/SafariVC → recoverAfterNativeSurface),
+  // which are the proven baseline and only fire for actual native surfaces. Re-add a scoped observer only
+  // 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)
   startEventForwarding();
   loadBundle(webView);
@@ -171,7 +180,7 @@ function loadBundle(webView: CustomWebView): void {
         const readAccessURL = NSURL.fileURLWithPathIsDirectory(wwwPath, true);
         wk.loadFileURLAllowingReadAccessToURL(entryURL, readAccessURL);
       } else {
-        const url = NSURL.URLWithString(`app://local/${SHELL_CONFIG.entry}`);
+        const url = NSURL.URLWithString(`app://localhost/${SHELL_CONFIG.entry}`);
         wk.loadRequest(NSURLRequest.requestWithURL(url));
       }
     };

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

@@ -1,7 +1,7 @@
 import { WebView, knownFolders, path as nsPath, File } from '@nativescript/core';
 import { SHELL_CONFIG } from './config';
 import { mimeFor } from './mime';
-import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, mediaCaptureGuardJs, serviceWorkerGuardJs, externalNavGuardJs } from './web-quirks';
+import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, capabilityGuardJs, serviceWorkerGuardJs, externalNavGuardJs } from './web-quirks';
 import { envGlobalsJs } from './env';
 import { createUiDelegate } from './ios-ui-delegate';
 import { appwrapNativeLog } from './native-log';
@@ -157,7 +157,7 @@ export class CustomWebView extends WebView {
       for (let j = 0; j < windows.count; j++) {
         const w = windows.objectAtIndex(j);
         if (main && w !== main && w.windowLevel > 0 && !w.hidden) {
-          if (dbg) appendWebLog(`[native:recover] stray win[${j}] lvl=${w.windowLevel} uie=${w.userInteractionEnabled} key=${w.keyWindow}`);
+          if (dbg) appendWebLog(`[native:recover] stray win[${j}] ${NSStringFromClass(w.class())} lvl=${w.windowLevel} uie=${w.userInteractionEnabled} key=${w.keyWindow}`);
           w.userInteractionEnabled = false;
           w.hidden = true;
           w.windowScene = null; // detach from the scene — strongest removal
@@ -179,21 +179,31 @@ export class CustomWebView extends WebView {
     config.allowsInlineMediaPlayback = true;
     config.allowsPictureInPictureMediaPlayback = true;
     config.mediaTypesRequiringUserActionForPlayback = 0; // WKAudiovisualMediaTypeNone
+    // Element Fullscreen API (iOS 15.4+): the JS Fullscreen API on arbitrary elements is gated behind
+    // this preference (native <video> fullscreen works without it). respondsToSelector-guarded so it's a
+    // no-op on older iOS (mirrors the setInspectable: probe below).
+    if (config.preferences.respondsToSelector('setElementFullscreenEnabled:')) {
+      (config.preferences as WKPreferences & { elementFullscreenEnabled: boolean }).elementFullscreenEnabled = true;
+    }
     config.websiteDataStore = WKWebsiteDataStore.defaultDataStore();
     // Apple's hard requirement for a service worker in a WKWebView: restrict navigation to the
     // declared app-bound domains (also stamped to Info.plist WKAppBoundDomains). Only set when
     // configured — otherwise the WebView stays unrestricted (default behavior).
     if (SHELL_CONFIG.appBoundDomains?.length) config.limitsNavigationsToAppBoundDomains = true;
 
-    // Env hints + framework globals (backend origin) + a getUserMedia guard for UNDECLARED capabilities
-    // (must reject in JS before WebKit's native capture path — see mediaCaptureGuardJs) + native-feel
-    // suppression, all injected before the page's own scripts run. Globals first so the page can read
-    // __APPWRAP__ / __APPWRAP_BACKEND_ORIGIN__.
+    // Env hints + framework globals (backend origin) + the TCC capability guard for UNDECLARED web APIs
+    // (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);
-    const mediaGuard = mediaCaptureGuardJs(hasPlistKey('NSCameraUsageDescription'), hasPlistKey('NSMicrophoneUsageDescription'));
+    const capabilityGuard = capabilityGuardJs({
+      camera: hasPlistKey('NSCameraUsageDescription'),
+      microphone: hasPlistKey('NSMicrophoneUsageDescription'),
+      geolocation: hasPlistKey('NSLocationWhenInUseUsageDescription'),
+    });
     const swGuard = serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker);
     const extNavGuard = externalNavGuardJs(SHELL_CONFIG.openNewWindowsInBrowser);
-    for (const src of [envGlobalsJs(), APPWRAP_GLOBALS_JS, mediaGuard, swGuard, extNavGuard, NATIVE_FEEL_JS]) {
+    for (const src of [envGlobalsJs(), APPWRAP_GLOBALS_JS, capabilityGuard, swGuard, extNavGuard, NATIVE_FEEL_JS]) {
       const script = WKUserScript.alloc().initWithSourceInjectionTimeForMainFrameOnly(
         src,
         WKUserScriptInjectionTime.AtDocumentStart,

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

@@ -102,7 +102,7 @@ function loadAppInto(webView: CustomWebView, id: string, attempt = 0): void {
     if (SHELL_CONFIG.loader === 'server' && SHELL_CONFIG.serverUrl) {
       wk.loadRequest(NSURLRequest.requestWithURL(NSURL.URLWithString(SHELL_CONFIG.serverUrl)));
     } else {
-      wk.loadRequest(NSURLRequest.requestWithURL(NSURL.URLWithString(`app://local/${SHELL_CONFIG.entry}`)));
+      wk.loadRequest(NSURLRequest.requestWithURL(NSURL.URLWithString(`app://localhost/${SHELL_CONFIG.entry}`)));
     }
   } else {
     if (retry(!webView.android)) return;

package/runtime/app/shell/web-quirks.ts

@@ -71,6 +71,65 @@ export function mediaCaptureGuardJs(camera: boolean, microphone: boolean): strin
 })();`;
 }
 
+/**
+ * Reject `navigator.geolocation` in JS at document-start when this build did NOT declare location
+ * (no NSLocationWhenInUseUsageDescription). Unlike camera/mic — where an undeclared request is a HARD
+ * TCC process-kill (see mediaCaptureGuardJs) — a WKWebView geolocation request with no usage string
+ * does NOT crash: WebKit's CoreLocation provider silently denies it. But the un-guarded failure mode is
+ * poor (the promise/callback can hang, and some iOS builds surface a confusing WebKit prompt for a
+ * permission the app can never grant). So when location is undeclared we fail FAST and deterministically
+ * — invoke the error callback with PERMISSION_DENIED so the page's own fallback runs immediately. When
+ * location IS declared, we no-op: WebKit + CoreLocation own the real prompt and the API works natively.
+ *
+ * `declared` = presence of NSLocationWhenInUseUsageDescription (the `geo` module). Patches BOTH
+ * getCurrentPosition and watchPosition on the live `navigator.geolocation`. Idempotent via a window guard.
+ */
+export function geolocationGuardJs(declared: boolean): string {
+  if (declared) return '';
+  return `(function(){
+  var geo = navigator.geolocation;
+  if (!geo || window.__appwrapGeoGuard) return;
+  window.__appwrapGeoGuard = true;
+  function deny(_pos, err){
+    if (typeof err === 'function') {
+      // GeolocationPositionError.PERMISSION_DENIED === 1.
+      setTimeout(function(){ try { err({ code: 1, message: 'location not available (capability not enabled for this app)', PERMISSION_DENIED: 1, POSITION_UNAVAILABLE: 2, TIMEOUT: 3 }); } catch (e) {} }, 0);
+    }
+  }
+  geo.getCurrentPosition = function(_ok, err){ deny(_ok, err); };
+  geo.watchPosition = function(_ok, err){ deny(_ok, err); return 0; };
+  geo.clearWatch = function(){};
+})();`;
+}
+
+/** A snapshot of which TCC-gated capabilities THIS build declared (Info.plist usage strings present),
+ * derived by the shell from `NSBundle.mainBundle.objectForInfoDictionaryKey`. Drives capabilityGuardJs. */
+export interface DeclaredCaps {
+  /** NSCameraUsageDescription present. */
+  camera: boolean;
+  /** NSMicrophoneUsageDescription present. */
+  microphone: boolean;
+  /** NSLocationWhenInUseUsageDescription present (the `geo` module). */
+  geolocation: boolean;
+}
+
+/**
+ * The single crash-proofing / graceful-degradation guard for ALL JS-reachable, TCC-gated web APIs in a
+ * WKWebView, injected at document-start. Takes the build's declared-capability snapshot and, for every
+ * capability the build did NOT declare, prevents the app-killing (camera/mic) or hanging (geolocation)
+ * failure while letting DECLARED capabilities pass straight through to their native prompt. Composes the
+ * individual guards so every consumer's foreign webview (shell + feedox mini-app views) is covered from
+ * one call site. Other TCC-gated surfaces (getDisplayMedia, SpeechRecognition, WebMIDI/BT/NFC/USB) are
+ * simply UNIMPLEMENTED by WKWebView — they resolve to `undefined`, so feature-detection degrades cleanly
+ * and there is nothing to guard.
+ */
+export function capabilityGuardJs(declared: DeclaredCaps): string {
+  return [
+    mediaCaptureGuardJs(declared.camera, declared.microphone),
+    geolocationGuardJs(declared.geolocation),
+  ].filter(Boolean).join('\n');
+}
+
 /**
  * Neutralize `navigator.serviceWorker.register` inside the native shell at document-start, so a
  * consumer PWA doesn't have to hand-gate its own SW. Inside the shell a service worker is at best
@@ -195,6 +254,10 @@ const NATIVE_FEEL_CSS = [
   // touch-callout:none suppresses long-press menus, but on inputs/textareas/contenteditable that also
   // kills the iOS Copy/Paste callout — so exclude editable fields (same set as the user-select rule).
   ':where(:not(input,textarea,[contenteditable],[contenteditable] *)){-webkit-touch-callout:none;-webkit-user-select:none;user-select:none}',
+  // Both -webkit-touch-callout and user-select INHERIT, so a :not(input) exclusion isn't enough — the
+  // field still inherits `none` from body/form and loses its paste callout + AutoFill selection. Must
+  // EXPLICITLY re-enable editable fields (not merely exempt them).
+  'input,textarea,[contenteditable],[contenteditable] *{-webkit-touch-callout:default;-webkit-user-select:text;user-select:text}',
 ].join('');
 
 /** Accessibility-standard reduced-motion reset — collapse animation/transition durations to ~0 and

package/runtime-desktop/autotest/index.html

@@ -0,0 +1,77 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>appwrap desktop autotest</title>
+<body style="font-family:monospace;background:#111;color:#0f0"><pre id="log">autotest</pre>
+<canvas id="cv" width="800" height="600"></canvas>
+<script>
+const logEl = document.getElementById('log');
+const say = (m) => { logEl.textContent += '\n' + m; };
+// Phase markers travel over the real bridge so they interleave with [bridge] eprintln
+// lines next to the watchdog's memory samples. UNSUPPORTED responses are irrelevant.
+const mark = (name) => window.appwrapNative?.postMessage(JSON.stringify({ v: 1, id: 'ph-' + name, kind: 'request', method: 'phase.' + name, params: null }));
+window.__appwrapDeliver = () => {}; // swallow responses
+
+const cleanups = [];
+const phases = [
+  ['idle', () => {}],
+  ['motion-listeners', () => {
+    const h1 = () => {}; const h2 = () => {};
+    window.addEventListener('devicemotion', h1);
+    window.addEventListener('deviceorientation', h2);
+    cleanups.push(() => { window.removeEventListener('devicemotion', h1); window.removeEventListener('deviceorientation', h2); });
+  }],
+  ['raf-canvas', () => {
+    const ctx = document.getElementById('cv').getContext('2d');
+    let run = true, t = 0;
+    const loop = () => { if (!run) return; t++; ctx.fillStyle = `hsl(${t % 360},80%,50%)`; ctx.fillRect(0, 0, 800, 600); ctx.getImageData(0, 0, 100, 100); requestAnimationFrame(loop); };
+    loop();
+    cleanups.push(() => { run = false; });
+  }],
+  ['speech-tts', () => {
+    let run = true;
+    const speak = () => { if (!run) return; const u = new SpeechSynthesisUtterance('test'); u.volume = 0; u.onend = speak; speechSynthesis.speak(u); };
+    speak();
+    cleanups.push(() => { run = false; speechSynthesis.cancel(); });
+  }],
+  ['geo-watch', () => {
+    if (!navigator.geolocation) return say('no geolocation');
+    const id = navigator.geolocation.watchPosition(() => {}, () => {}, { enableHighAccuracy: true });
+    cleanups.push(() => navigator.geolocation.clearWatch(id));
+  }],
+  ['bridge-storage-spam', () => {
+    let run = true, i = 0;
+    const big = 'x'.repeat(100_000);
+    const tick = () => {
+      if (!run) return;
+      for (let j = 0; j < 20; j++) window.appwrapNative.postMessage(JSON.stringify({ v: 1, id: 's' + (++i), kind: 'request', method: 'storage.set', params: { key: 'k' + (i % 50), value: big } }));
+      setTimeout(tick, 100);
+    };
+    tick();
+    cleanups.push(() => { run = false; });
+  }],
+  ['toast-spam', () => {
+    let run = true, i = 0;
+    const tick = () => { if (!run || i > 40) return; i++; window.appwrapNative.postMessage(JSON.stringify({ v: 1, id: 't' + i, kind: 'request', method: 'toast.show', params: { message: 'spam ' + i } })); setTimeout(tick, 500); };
+    tick();
+    cleanups.push(() => { run = false; });
+  }],
+  ['getusermedia', () => {
+    navigator.mediaDevices?.getUserMedia({ video: true, audio: true })
+      .then((s) => { say('gum ok'); cleanups.push(() => s.getTracks().forEach((t) => t.stop())); })
+      .catch((e) => say('gum err ' + e.name));
+  }],
+  ['idle-end', () => {}],
+];
+
+let idx = 0;
+const next = () => {
+  while (cleanups.length) { try { cleanups.pop()(); } catch {} }
+  if (idx >= phases.length) { mark('DONE'); say('DONE'); return; }
+  const [name, fn] = phases[idx++];
+  mark(name); say('phase: ' + name);
+  try { fn(); } catch (e) { say('threw: ' + e.message); }
+  setTimeout(next, 30_000);
+};
+next();
+</script>
+</body>

package/runtime-desktop/bridge-shim/build.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Build the injectable content bundle. Must run with the bod-browser repo as cwd so its
+# tsconfig `paths` (shared/*) resolve — the bundle reuses extension/src/content/* unmodified.
+set -e
+HERE="$(cd "$(dirname "$0")" && pwd)"
+BOD_BROWSER="${BOD_BROWSER:-$HERE/../../../bod-browser}"
+cd "$BOD_BROWSER"
+bun build "$HERE/content-entry.ts" --outfile "$HERE/dist/content.js"
+echo "built $HERE/dist/content.js"

package/runtime-desktop/bridge-shim/content-entry.ts

@@ -0,0 +1,87 @@
+// SPIKE: browser-bridge content layer for the appwrap desktop (Tauri/WKWebView) shell.
+// Reuses bod-browser's extension/src/content/* modules UNMODIFIED; only the transport differs:
+// instead of chrome.runtime messaging, each page dials a local WS to the shim (bridge-shim/shim.ts)
+// and answers ContentAction messages. Injected per-window via Tauri initialization_script.
+//
+// Build (from the bod-browser repo root so its tsconfig `paths` resolve shared/*):
+//   cd ../bod-browser && bun build <this file> --outfile <appwrap>/runtime-desktop/bridge-shim/dist/content.js
+import type { ContentAction } from 'shared/protocol';
+import { advanceScroll } from '../../../bod-browser/extension/src/content/advance-scroll';
+import {
+  clickElement, typeInElement, fillElement, doScroll, scrollElementIntoView, evalScript,
+  waitForElement, hoverElement, scrollElementBy, hoverNear, sendKey,
+} from '../../../bod-browser/extension/src/content/actions';
+import {
+  queryElements, getLinks, findButtons, clickText, queryByText, getElementValue, setElementAttribute,
+} from '../../../bod-browser/extension/src/content/query';
+import { getA11ySnapshot, queryA11y } from '../../../bod-browser/extension/src/content/a11y';
+import { probePage } from '../../../bod-browser/extension/src/content/probe';
+import { diagnosePage } from '../../../bod-browser/extension/src/content/diagnose';
+
+declare global {
+  interface Window { __BRIDGE_LABEL?: string; __BRIDGE_PORT?: number; __BRIDGE_LOADED?: boolean }
+}
+
+async function handleMessage(msg: ContentAction): Promise<unknown> {
+  switch (msg.action) {
+    case 'getContent':
+      return { url: location.href, title: document.title, html: document.documentElement.outerHTML, text: document.body?.innerText ?? '' };
+    case 'getTextContent':
+      return { url: location.href, title: document.title, text: document.body?.innerText?.slice(0, 20000) || '' };
+    case 'query': return queryElements(msg.selector, msg.multiple);
+    case 'click': return clickElement(msg.selector);
+    case 'type': return typeInElement(msg.selector, msg.value, msg.mode, msg.clear);
+    case 'fill': return fillElement(msg.selector, msg.value, msg.timeout, msg.mode, msg.clear);
+    case 'getValue': return getElementValue(msg.selector);
+    case 'setAttribute': return setElementAttribute(msg.selector, msg.attr, msg.value);
+    case 'scroll': return doScroll(msg.x || 0, msg.y || 0, msg.behavior);
+    case 'scrollIntoView': return scrollElementIntoView(msg.selector, msg.behavior);
+    case 'eval': return evalScript(msg.script);
+    case 'waitFor': return waitForElement(msg.selector, msg.timeout || 5000);
+    case 'hover': return hoverElement(msg.selector);
+    case 'scrollEl': return scrollElementBy(msg.selector, msg.deltaX || 0, msg.deltaY || 0, msg.behavior);
+    case 'advanceScroll':
+      return advanceScroll({ deltaY: msg.deltaY, itemSelector: msg.itemSelector, loadMoreSelector: msg.loadMoreSelector, behavior: msg.behavior });
+    case 'getA11ySnapshot': return getA11ySnapshot(msg.root || null, msg.maxDepth || 10, msg.mode || 'full');
+    case 'probe': return probePage(msg.goal || null);
+    case 'diagnose': return diagnosePage();
+    case 'queryA11y': return queryA11y(msg.role, msg.name, msg.multiple);
+    case 'getLinks': return getLinks(msg.pattern || null, msg.scope || null);
+    case 'clickText': return clickText(msg.text, msg.scope || null);
+    case 'queryByText': return queryByText(msg.text, msg.scope || null);
+    case 'findButtons': return findButtons(msg.scope || null);
+    case 'sendKey': return sendKey(msg.selector || null, msg.key, msg.modifiers);
+    case '_ping': return { pong: true };
+    default:
+      throw new Error(`Unknown action: ${(msg as ContentAction).action}`);
+  }
+}
+
+(() => {
+  // initialization_script can fire more than once per document lifecycle; guard.
+  if (window.__BRIDGE_LOADED) return;
+  window.__BRIDGE_LOADED = true;
+  const label = window.__BRIDGE_LABEL || 'unknown';
+
+  // Transport: WebKit blocks ws://127.0.0.1 (and plain-http beacons) from https pages as mixed
+  // content — no loopback exemption like Chrome. So results go out via the native
+  // WKScriptMessageHandler the shell installs (webkit.messageHandlers.bridgeShim), and commands
+  // come in via window.__bridgeDispatch(...) evaluated by the shell (evalJs op).
+  type WebkitHandlers = { webkit?: { messageHandlers?: { bridgeShim?: { postMessage: (s: string) => void } } } };
+  const post = (o: Record<string, unknown>) => {
+    try { (window as WebkitHandlers).webkit?.messageHandlers?.bridgeShim?.postMessage(JSON.stringify({ label, ...o })); } catch { /* ignore */ }
+  };
+
+  (window as unknown as { __bridgeDispatch: (m: ContentAction & { id: string }) => void }).__bridgeDispatch = (m) => {
+    Promise.resolve()
+      .then(() => handleMessage(m))
+      .then(result => post({ id: m.id, result }))
+      .catch((e: Error) => post({ id: m.id, error: e.message }));
+  };
+
+  const register = () => post({ type: 'register', url: location.href, title: document.title });
+  register();
+  addEventListener('DOMContentLoaded', register);
+  addEventListener('load', register);
+  console.log(`[BridgeDesktop:cs ${label}] loaded on ${location.href.slice(0, 80)}`);
+})();