@livx.cc/appwrap 0.61.24 → 0.61.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.61.24",
+  "version": "0.61.26",
   "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/shell/handlers-webview.ts

@@ -28,7 +28,19 @@ const KVO_KEYS = ['URL', 'title', 'canGoBack', 'canGoForward', 'loading'];
  *                                                 overlay's page; resolves {result} (the returned value, JSON round-tripped).
  *                                                 `world` = a named isolated JS world (iOS; Android has one world). The
  *                                                 hub's own (trusted) origin only — never in bridge-origin's FOREIGN_ALLOWED.
- * Events: `webview.state` {url,title,canGoBack,canGoForward,loading} on every navigation change.
+ *   webview.fab {show, bottom?, right?, size?, color?, symbol?, text?, label?}
+ *                                               — a round floating button over the app AND the overlay (an "assistant"
+ *                                                 button that stays tappable while a page is shown): `bottom`/`right` = CSS px
+ *                                                 from the app WebView's bottom-right, `size` (52), `color` #rrggbb, `symbol` an
+ *                                                 SF Symbol (iOS, default 'sparkles'), `text` its glyph on Android ('✦'),
+ *                                                 `label` = accessibility, `radius` (default round), symbol/text '' = a
+ *                                                 plain shape. show:false hides it. Taps emit `webview.fab`.
+ *   webview.float {on, hit?: [{x,y,w,h}]}      — the app's WebView draws OVER the overlay (transparent wherever its own page
+ *                                                 is), e.g. chat bubbles floating over a shown page without resizing it.
+ *                                                 Touches inside `hit` (app CSS px) go to the app; everywhere else to the
+ *                                                 overlay. Call again to move the rects; on:false restores. iOS; Android
+ *                                                 resolves {floating:false} (not supported — keep a fallback).
+ * Events: `webview.state` {url,title,canGoBack,canGoForward,loading} on every navigation change; `webview.fab` on a tap.
  *
  * Swipe back/forward on, target=_blank/window.open loads in place (shared ios-ui-delegate), keyboard +
  * safe areas handled by WKWebView's own scroll-view insets (contentInsetAdjustment automatic).
@@ -51,6 +63,17 @@ const evalJs = (p?: { js?: string } | null) => {
   if (!js) throw err('NATIVE_ERROR', 'webview.eval: empty js');
   return js;
 };
+/** webview.fab params (sizes in CSS px). */
+type Fab = { show?: boolean; bottom?: number; right?: number; size?: number; radius?: number; color?: string; symbol?: string; text?: string; label?: string };
+const fabOpts = (p?: Fab | null) => ({
+  show: !!p?.show, bottom: Math.max(0, Number(p?.bottom) || 16), right: Math.max(0, Number(p?.right) || 16),
+  size: Math.min(96, Math.max(32, Number(p?.size) || 52)), rgb: /^#?([0-9a-f]{6})$/i.exec(String(p?.color ?? '').trim())?.[1] ?? '2f6b4c',
+  symbol: p?.symbol === '' ? '' : String(p?.symbol || 'sparkles'), text: p?.text === '' ? '' : String(p?.text || '✦'),
+  radius: p?.radius === undefined ? null : Math.max(0, Number(p.radius) || 0), label: String(p?.label || 'Assistant'),
+});
+/** webview.float hit rects (app CSS px); junk entries dropped. */
+const floatRects = (l: unknown) => (Array.isArray(l) ? l : []).map((r: any) => ({ x: +r?.x, y: +r?.y, w: +r?.w, h: +r?.h }))
+  .filter((r) => [r.x, r.y, r.w, r.h].every(Number.isFinite) && r.w > 0 && r.h > 0);
 const parsed = (s: unknown) => { try { return JSON.parse(String(s)); } catch { return s ?? null; } };
 const EVAL_TIMEOUT = 30000;
 
@@ -60,6 +83,9 @@ const snapOpts = (p?: { width?: number; quality?: number } | null) => ({
   quality: Math.min(1, Math.max(0.1, Number(p?.quality) || 0.6)),
 });
 
+/** webview.float is on: the app WebView must stay see-through (keyboard.ts's backdrop paint skips it). */
+export let appFloating = false;
+
 export function registerWebViewHandlers(): void {
   if (isIOS) registerIos();
   else if (isAndroid) registerAndroid();
@@ -76,6 +102,22 @@ function registerIos(): void {
   let bottomConstraint: NSLayoutConstraint | null = null;
   let emitQueued = false;
   let ObserverClass: any; // KVO sink, built once (ObjC class names are global)
+  let fab: UIButton | null = null;
+  let fabTarget: any = null, FabTargetClass: any; // its tap target (an exposedMethods NSObject, built once)
+  let fabBottom: NSLayoutConstraint | null = null, fabRight: NSLayoutConstraint | null = null, fabW: NSLayoutConstraint | null = null, fabH: NSLayoutConstraint | null = null;
+  // webview.float: the app WebView renders above the overlay (layer zPosition — draw order only) while the overlay stays
+  // first in hit-testing (subview order): it sits in a pass-through wrapper that declines the touches inside `floatHit`
+  // (app CSS px), which fall to the app. (A wrapper, not a WKWebView subclass: its super hitTest recursed in NativeScript.)
+  let floating = false, floatHit: { x: number; y: number; w: number; h: number }[] = [], hostBg: UIColor | null = null, hostOpaque = true;
+  let wrap: UIView | null = null, WrapClass: any;
+  const appHit = (view: UIView, pt: CGPoint) => {
+    const host = bridge.getWebView()?.ios as UIView | undefined;
+    if (!floating || !host) return false;
+    const p = view.convertPointToView(pt, host);
+    return floatHit.some((r) => p.x >= r.x && p.x <= r.x + r.w && p.y >= r.y && p.y <= r.y + r.h);
+  };
+  /** The button stays above the overlay (which comes to the front on open/show). */
+  const fabFront = () => { if (fab && !fab.hidden) fab.superview?.bringSubviewToFront(fab); };
 
   const state = () => ({
     url: wv?.URL?.absoluteString ?? '',
@@ -114,7 +156,16 @@ function registerIos(): void {
     if ((view as any).inspectable !== undefined) (view as any).inspectable = true; // iOS 16.4+ Safari inspector
 
     view.translatesAutoresizingMaskIntoConstraints = false;
-    container.addSubview(view);
+    WrapClass ??= (UIView as any).extend({
+      hitTestWithEvent(pt: CGPoint, ev: _UIEvent) {
+        if (!wv || appHit(this, pt)) return null;
+        return wv.hitTestWithEvent(this.convertPointToView(pt, wv), ev);
+      },
+    }, { name: 'AppwrapOverlayWrap' });
+    wrap = WrapClass.alloc().initWithFrame(CGRectZero);
+    wrap!.translatesAutoresizingMaskIntoConstraints = false;
+    container.addSubview(wrap!);
+    wrap!.addSubview(view);
     // Anchor to the app WebView's box so `top`/`bottom` are in the page's own CSS px (== points).
     const ref: any = host ?? container;
     topConstraint = view.topAnchor.constraintEqualToAnchorConstant(ref.topAnchor, top);
@@ -124,6 +175,8 @@ function registerIos(): void {
       bottomConstraint,
       view.leadingAnchor.constraintEqualToAnchor(ref.leadingAnchor),
       view.trailingAnchor.constraintEqualToAnchor(ref.trailingAnchor),
+      wrap!.topAnchor.constraintEqualToAnchor(ref.topAnchor), wrap!.bottomAnchor.constraintEqualToAnchor(ref.bottomAnchor),
+      wrap!.leadingAnchor.constraintEqualToAnchor(ref.leadingAnchor), wrap!.trailingAnchor.constraintEqualToAnchor(ref.trailingAnchor),
     ] as any);
 
     ObserverClass ??= (NSObject as any).extend(
@@ -146,7 +199,7 @@ function registerIos(): void {
     if (!wv) return;
     for (const k of KVO_KEYS) { try { wv.removeObserverForKeyPath(observer!, k); } catch { /* not observed */ } }
     wv.stopLoading();
-    wv.removeFromSuperview();
+    wv.removeFromSuperview(); wrap?.removeFromSuperview(); wrap = null;
     wv = null; observer = null; uiDelegate = null; topConstraint = null; bottomConstraint = null;
     bridge.emit('webview.closed', {});
   };
@@ -170,7 +223,8 @@ function registerIos(): void {
       if (!wv) create(inset(top), inset(bottom));
       else setInsets(top, bottom);
       wv!.hidden = false;
-      wv!.superview?.bringSubviewToFront(wv!);
+      wrap?.superview?.bringSubviewToFront(wrap);
+      fabFront();
       load(target);
       return state();
     });
@@ -190,11 +244,66 @@ function registerIos(): void {
 
   bridge.register('webview.hide', () => onMain(() => { if (wv) wv.hidden = true; return { open: !!wv }; }));
   bridge.register('webview.show', (p?: { top?: number; bottom?: number } | null) => onMain(() => {
-    if (wv) { setInsets(p?.top, p?.bottom); wv.hidden = false; wv.superview?.bringSubviewToFront(wv); }
+    if (wv) { setInsets(p?.top, p?.bottom); wv.hidden = false; wrap?.superview?.bringSubviewToFront(wrap); fabFront(); }
     return { open: !!wv };
   }));
   bridge.register('webview.close', () => onMain(() => { destroy(); }));
 
+  bridge.register('webview.fab', (p?: Fab | null) => {
+    const o = fabOpts(p);
+    return onMain(() => {
+      if (!fab) {
+        if (!o.show) return { shown: false };
+        const host = bridge.getWebView()?.ios as WKWebView | undefined;
+        const container = host?.superview ?? Utils.ios.getRootViewController()?.view;
+        if (!container) throw err('NATIVE_ERROR', 'webview.fab: no host view');
+        FabTargetClass ??= (NSObject as any).extend({ tap() { bridge.emit('webview.fab', {}); } }, { name: 'AppwrapFabTarget', exposedMethods: { tap: { returns: interop.types.void } } });
+        fabTarget = FabTargetClass.new();
+        const b = UIButton.buttonWithType(UIButtonType.System);
+        b.translatesAutoresizingMaskIntoConstraints = false;
+        b.addTargetActionForControlEvents(fabTarget, 'tap', UIControlEvents.TouchUpInside);
+        b.layer.shadowColor = UIColor.blackColor.CGColor; b.layer.shadowOpacity = 0.28; b.layer.shadowRadius = 9; b.layer.shadowOffset = CGSizeMake(0, 5);
+        container.addSubview(b);
+        const ref: any = host ?? container;
+        fabBottom = b.bottomAnchor.constraintEqualToAnchorConstant(ref.bottomAnchor, -o.bottom);
+        fabRight = b.trailingAnchor.constraintEqualToAnchorConstant(ref.trailingAnchor, -o.right);
+        fabW = b.widthAnchor.constraintEqualToConstant(o.size); fabH = b.heightAnchor.constraintEqualToConstant(o.size);
+        NSLayoutConstraint.activateConstraints([fabBottom, fabRight, fabW, fabH] as any);
+        fab = b;
+      }
+      const n = parseInt(o.rgb, 16);
+      fab.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255, 1);
+      // the glyph in black or white, whichever reads on the colour
+      const light = (0.299 * ((n >> 16) & 255) + 0.587 * ((n >> 8) & 255) + 0.114 * (n & 255)) > 150;
+      fab.tintColor = light ? UIColor.colorWithRedGreenBlueAlpha(0.06, 0.15, 0.1, 1) : UIColor.whiteColor;
+      fab.setImageForState(o.symbol ? UIImage.systemImageNamedWithConfiguration(o.symbol, UIImageSymbolConfiguration.configurationWithPointSizeWeight(o.size * 0.42, UIImageSymbolWeight.Semibold)) : null, UIControlState.Normal);
+      fab.layer.cornerRadius = o.radius ?? o.size / 2;
+      fab.accessibilityLabel = o.label;
+      if (fabBottom) fabBottom.constant = -o.bottom;
+      if (fabRight) fabRight.constant = -o.right;
+      if (fabW) fabW.constant = o.size;
+      if (fabH) fabH.constant = o.size; // (a later call may resize it)
+      fab.hidden = !o.show;
+      fabFront();
+      return { shown: o.show };
+    });
+  });
+
+  bridge.register('webview.float', (p?: { on?: boolean; hit?: unknown } | null) => onMain(() => {
+    const host = bridge.getWebView()?.ios as WKWebView | undefined;
+    if (!host) throw err('NATIVE_ERROR', 'webview.float: no host view');
+    floatHit = floatRects(p?.hit);
+    const on = !!p?.on;
+    if (on !== floating) {
+      floating = appFloating = on;
+      if (on) { hostBg = host.backgroundColor; hostOpaque = host.opaque; host.opaque = false; host.backgroundColor = UIColor.clearColor; host.scrollView.backgroundColor = UIColor.clearColor; }
+      else { host.opaque = hostOpaque; host.backgroundColor = hostBg; host.scrollView.backgroundColor = hostBg; }
+      host.layer.zPosition = on ? 1 : 0;
+      if (fab) fab.layer.zPosition = on ? 2 : 0;
+    }
+    return { floating };
+  }));
+
   bridge.register('webview.snapshot', (p?: { width?: number; quality?: number } | null) => {
     const o = snapOpts(p);
     return onMain(() => new Promise<{ jpeg: string; width: number; height: number }>((resolve, reject) => {
@@ -355,7 +464,22 @@ function registerAndroid(): void {
     if (bottom !== undefined) insets.bottom = inset(bottom);
     layout();
   };
-  const reveal = () => { wv.setVisibility(android.view.View.VISIBLE); wv.bringToFront(); };
+  let fab: any = null, fabO = fabOpts(null);
+  /** Place the button at the app WebView's bottom-right (`bottom`/`right` CSS px inside it), above the overlay. */
+  const fabLayout = () => {
+    const frame = content();
+    if (!fab || !frame) return;
+    const d = density(), px = Math.round(fabO.size * d), fl = [0, 0], hl = [0, 0];
+    const h = host ?? bridge.getWebView()?.android;
+    let boxBottom = 0, boxRight = 0;
+    if (h) { frame.getLocationInWindow(fl); h.getLocationInWindow(hl); boxBottom = frame.getHeight() - (hl[1] - fl[1] + h.getHeight()); boxRight = frame.getWidth() - (hl[0] - fl[0] + h.getWidth()); }
+    const lp = new android.widget.FrameLayout.LayoutParams(px, px, android.view.Gravity.BOTTOM | android.view.Gravity.END);
+    lp.bottomMargin = Math.max(0, Math.round(boxBottom + fabO.bottom * d));
+    lp.rightMargin = Math.max(0, Math.round(boxRight + fabO.right * d));
+    fab.setLayoutParams(lp);
+    if (fab.getVisibility() === android.view.View.VISIBLE) fab.bringToFront();
+  };
+  const reveal = () => { wv.setVisibility(android.view.View.VISIBLE); wv.bringToFront(); if (fab?.getVisibility() === android.view.View.VISIBLE) fab.bringToFront(); };
 
   bridge.register('webview.open', ({ url, top, bottom }: { url: string; top?: number; bottom?: number }) => {
     const target = String(url ?? '');
@@ -388,6 +512,35 @@ function registerAndroid(): void {
   }));
   bridge.register('webview.close', () => onMain(() => { destroy(); }));
 
+  bridge.register('webview.fab', (p?: Fab | null) => {
+    fabO = fabOpts(p);
+    return onMain(() => {
+      const frame = content();
+      if (!fab) {
+        if (!fabO.show) return { shown: false };
+        if (!frame) throw err('NATIVE_ERROR', 'webview.fab: no host view');
+        fab = new android.widget.TextView(activity());
+        fab.setGravity(android.view.Gravity.CENTER);
+        fab.setElevation(8 * density());
+        fab.setOnClickListener(new android.view.View.OnClickListener({ onClick() { bridge.emit('webview.fab', {}); } }));
+        frame.addView(fab);
+      }
+      const n = parseInt(fabO.rgb, 16), light = (0.299 * ((n >> 16) & 255) + 0.587 * ((n >> 8) & 255) + 0.114 * (n & 255)) > 150;
+      const bg = new android.graphics.drawable.GradientDrawable();
+      if (fabO.radius === null) bg.setShape(android.graphics.drawable.GradientDrawable.OVAL);
+      else bg.setCornerRadius(fabO.radius * density());
+      bg.setColor(android.graphics.Color.rgb((n >> 16) & 255, (n >> 8) & 255, n & 255));
+      fab.setBackground(bg);
+      fab.setText(fabO.text);
+      fab.setTextSize(android.util.TypedValue.COMPLEX_UNIT_DIP, fabO.size * 0.42);
+      fab.setTextColor(light ? android.graphics.Color.rgb(16, 38, 26) : android.graphics.Color.WHITE);
+      fab.setContentDescription(fabO.label);
+      fab.setVisibility(fabO.show ? android.view.View.VISIBLE : android.view.View.GONE);
+      fabLayout();
+      return { shown: fabO.show };
+    });
+  });
+
   bridge.register('webview.snapshot', (p?: { width?: number; quality?: number } | null) => {
     const o = snapOpts(p);
     return onMain(() => {
@@ -432,6 +585,8 @@ function registerAndroid(): void {
     })();
   });
 
+  bridge.register('webview.float', () => ({ floating: false })); // (not supported here: callers keep their fallback)
+
   bridge.register('webview.cookies', (p: { cookies?: Cookie[] } | null) => {
     const list = cookieList(p);
     return onMain(() => new Promise<{ set: number }>((resolve) => {

package/runtime/app/shell/keyboard.ts

@@ -3,6 +3,7 @@ import { bridge } from './bridge';
 import { SHELL_CONFIG } from './config';
 import { createKeyboardShowCycle, type KeyboardEventTag } from './keyboard-frame';
 import { appwrapNativeLog } from './native-log';
+import { appFloating } from './handlers-webview';
 
 declare const android: any;
 // iOS keyboard-notification globals (marshalled from UIKit at runtime).
@@ -231,7 +232,8 @@ function syncBackdropColor(): void {
         const color = UIColor.colorWithRedGreenBlueAlpha(+m[1] / 255, +m[2] / 255, +m[3] / 255, 1);
         // The keyboard's rounded corners (iOS 26) show whatever native view is behind the webview — paint
         // the whole chain up to the window, not only the webview + window (a dark host view showed through).
-        for (let v: UIView | null = w; v; v = v.superview) v.backgroundColor = color;
+        // (floating over a page — webview.float — the webview itself stays clear, or it covers the page)
+        for (let v: UIView | null = appFloating ? w.superview : w; v; v = v.superview) v.backgroundColor = color;
         if (w.window) w.window.backgroundColor = color;
         if (SHELL_CONFIG.debug) appwrapNativeLog(`[native:keyboard] backdrop ← rgb(${m[1]},${m[2]},${m[3]})`);
       });