@livx.cc/appwrap 0.50.1 → 0.51.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.50.1",
+  "version": "0.51.1",
   "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/custom-webview.android.ts

@@ -107,6 +107,14 @@ export class CustomWebView extends WebView {
   // object, robust to NS re-wrapping the arg passed into the ChromeClient callback). WeakRef
   // so a destroyed view can be GC'd; entry pruned on dispose.
   private static registry = new Map<number, WeakRef<CustomWebView>>();
+  // Retired asset-serving WebViewClients (app/file loader ONLY — see disposeNativeView), kept
+  // process-alive so a shouldInterceptRequest already in flight on a background thread when the view is
+  // disposed can't fire against a GC'd JS peer → "Cannot find runtime for instance". Holding the (JS-peer)
+  // object here keeps NS's per-object runtime mapping resolvable. Server mode installs no interceptor, so
+  // its clients are NOT parked (all their callbacks are main-thread → safe to GC). Growth is bounded by
+  // the number of interceptor-bearing WebViews that dispose — note handlers-background can spin up an
+  // offscreen WebView per background task, so this is per-disposed-interceptor-view, not strictly one.
+  private static retiredClients = new Set<android.webkit.WebViewClient>();
   static forNative(view: android.webkit.WebView): CustomWebView | undefined {
     const owner = CustomWebView.registry.get(view.hashCode())?.deref();
     // identityHashCode is not unique: on a (rare) collision the map holds the LAST writer —
@@ -155,9 +163,20 @@ export class CustomWebView extends WebView {
   disposeNativeView(): void {
     const wv = this.android as android.webkit.WebView | undefined;
     if (wv) CustomWebView.registry.delete(wv.hashCode());
-    // Drop the retained clients now that the native view is going away, so their peers can be GC'd.
-    this.webViewClient = null;
+    // WebChromeClient (onJsPrompt) only fires on the main thread → safe to release for GC now.
     this.webChromeClient = null;
+    // WebViewClient is different: shouldInterceptRequest can be dispatched on a BACKGROUND thread, so a
+    // request already in flight when the view tears down would fire AFTER dispose. Releasing the client's
+    // JS peer here would let that late off-thread call crash with "Cannot find runtime for instance".
+    // Park it in a process-lived set so the peer stays registered for any straggler callback — but ONLY
+    // when the interceptor is actually installed (app/file loader). Server mode installs no
+    // shouldInterceptRequest (see createAssetServingClient), so its client has no off-thread callback to
+    // outlive dispose: parking it would be pure dead retention (an accumulating leak across background-
+    // task WebViews), so just release it for GC.
+    if (this.webViewClient) {
+      if (SHELL_CONFIG.loader !== 'server') CustomWebView.retiredClients.add(this.webViewClient);
+      this.webViewClient = null;
+    }
     super.disposeNativeView();
   }
 
@@ -307,11 +326,27 @@ function createAssetServingClient(): android.webkit.WebViewClient {
     return new android.webkit.WebResourceResponse(mimeFor(ext, rel), 'utf-8', 200, 'OK', outHeaders, pin);
   };
 
+  // WebViewClient callbacks. All are dispatched on the UI/main thread EXCEPT shouldInterceptRequest,
+  // which Android runs on a BACKGROUND thread (ShouldInterceptRequestMediator). NativeScript resolves
+  // the JS peer for a callback's instance via a per-object runtime lookup (Runtime.getObjectRuntime);
+  // if that peer is momentarily unregistered — freshly created and not yet mapped on boot, or disposed
+  // and GC'd on relaunch / RESTART-from-crash — the off-thread call throws
+  // `NativeScriptException: Cannot find runtime for instance` (the red NS crash screen). NS marshals a
+  // background-thread call to the main thread fine ONCE the peer is mapped, so this is a registration/
+  // lifetime race, not a plain GC one — which is why the earlier strong-JS-ref fix didn't cover the boot path.
+  //
+  // In server mode (loader:'server') the page loads from a real https `serverUrl`: there are NO
+  // https://appwrap.local requests and `backendOrigin` is same-origin, so the asset interceptor does
+  // ZERO work — yet it is the ONLY off-main-thread callback, i.e. the only one exposed to that race.
+  // So OMIT it in server mode (the conditional spread expands to nothing): Android's default pure-Java
+  // interception runs, NS is never crossed into JS off-thread, and the crash is structurally impossible.
+  // app/file loaders MUST serve bundled www/ assets, so they keep it (and retain the client for the
+  // process lifetime — see CustomWebView.disposeNativeView — so a late in-flight call can't hit a dead peer).
   // NS runtime adds `.extend` on Java classes; it's not in the static typings, hence the cast.
   assetClientClass = (android.webkit.WebViewClient as any).extend({
     // Modern (API 21+) overload passes a WebResourceRequest; the legacy overload passed a string URL.
     // We defensively handle both, so the param is the union.
-    shouldInterceptRequest(
+    ...(SHELL_CONFIG.loader === 'server' ? {} : { shouldInterceptRequest(
       _view: android.webkit.WebView,
       request: android.webkit.WebResourceRequest | string
     ): android.webkit.WebResourceResponse | null {
@@ -343,7 +378,7 @@ function createAssetServingClient(): android.webkit.WebViewClient {
       return new android.webkit.WebResourceResponse(
         'text/plain', 'utf-8', 404, 'Not Found', new java.util.HashMap<string, string>(), emptyStream()
       );
-    },
+    } }),
 
     // External URL schemes (mailto:/tel:/sms:/geo:/intent:/webcal:/market:/…) can't be rendered by the
     // WebView — without this override it tries to LOAD them and dumps a full-page net::ERR_UNKNOWN_URL_SCHEME

package/runtime/app/shell/env-banner.ts

@@ -194,10 +194,32 @@ function hideIOSBanner(): void {
 }
 
 // ── Android ──────────────────────────────────────────────────────────
+/**
+ * Cold-relaunch safe entry: on a relaunch (main-page onPageLoaded) the Activity's window is not yet
+ * attached, so `foregroundActivity` can be null AND `getRootWindowInsets()` returns null — mounting
+ * inline then lands the pill INSIDE the nav-bar zone (bottomMargin computed off a 0 inset) where it's
+ * occluded by the home affordance and reads as "the banner disappeared". So: wait for an activity, then
+ * defer the actual mount to `decorView.post` (runs after attach + first layout on the UI thread), when
+ * insets are real. In-session callers (refreshEnvBanner) hit the same path — a one-frame post is harmless.
+ */
+let androidMountRetries = 0; // bounds the boot "activity not ready" retry so it can't spin forever
+
 function showAndroidBanner(): void {
   if (androidView) return;
   const activity = Application.android.foregroundActivity || Application.android.startActivity;
-  if (!activity) return;
+  if (!activity) {
+    if (androidMountRetries++ < 20) setTimeout(() => runOnAndroidUi(showAndroidBanner), 100); // boot: activity not ready — retry, bounded (~2s)
+    return;
+  }
+  androidMountRetries = 0;
+  activity.getWindow().getDecorView().post(new java.lang.Runnable({ run() { mountAndroidBanner(activity); } }));
+}
+
+function mountAndroidBanner(activity: android.app.Activity): void {
+  if (androidView) return; // a second deferred mount raced in — keep the first
+  // Re-gate at the final step: the override may have been cleared (reset / switch to default / hideEnvBanner)
+  // during the deferred post or the boot retry window — don't mount a stale banner the caller no longer wants.
+  if (!isEnvSwitcherEnabled() || !isNonDefaultOverride()) return;
   const density = activity.getResources().getDisplayMetrics().density;
   const padH = Math.round(14 * density), padV = Math.round(6 * density);
 
@@ -254,13 +276,15 @@ function showAndroidBanner(): void {
   armShrink();
 }
 
-/** Bottom system-inset (gesture/nav bar) in px; 0 best-effort if unavailable. */
+/** Bottom system-inset (gesture/nav bar) in px. Falls back to ~48dp (a typical nav-bar height) rather
+ * than 0 if the read fails, so the pill never lands INSIDE the nav bar on a device/timing where insets
+ * are unavailable — being a touch too high is harmless; being occluded reads as "missing". */
 function androidBottomInsetPx(activity: android.app.Activity): number {
   try {
     const wi = activity.getWindow().getDecorView().getRootWindowInsets();
     if (wi) return wi.getSystemWindowInsetBottom();
-  } catch (e) { /* pre-attach / older API — fall back to the base margin */ }
-  return 0;
+  } catch (e) { /* pre-attach / older API — fall back below */ }
+  return Math.round(48 * activity.getResources().getDisplayMetrics().density);
 }
 
 function renderAndroid(): void {

package/runtime/app/shell/env-switcher.ts

@@ -143,24 +143,26 @@ export async function showEnvSwitcher(): Promise<void> {
   }
 }
 
-// ── Deep-link entry (`<scheme>://env?url=<encoded-url>`) ──────────────────────────────────────────
-// A PR-preview link can be SHARED and auto-open the app on that env. Same security model as "Other":
-// the decoded target must pass `isUrlAllowed` (anchored allowPattern, default-deny) and a confirm
-// prompt, then applies via the EXACT SAME `applySwitch` path as a manual switch. events.ts owns the
-// WebView-ready timing (warm: now; cold launch: buffered, replayed after the PWA handshake).
+// ── Deep-link entry (`<scheme>://env?to=<name>` | `?url=<encoded-url>`) ────────────────────────────
+// A shared link can auto-open the app on a given env. Two additive forms: `?to=<name>` switches to a
+// CONFIGURED preset by label (TRUSTED — bypasses the allowlist, like the manual switcher's presets);
+// `?url=<encoded>` is a free-form target still gated by `isUrlAllowed` (anchored allowPattern, default-
+// deny). Both go through a confirm prompt and apply via the EXACT SAME `applySwitch` path as a manual
+// switch. events.ts owns the WebView-ready timing (warm: now; cold launch: buffered, replayed after
+// the PWA handshake).
 
 export type EnvDeepLinkDecision =
   | { action: 'switch'; url: string }
   | { action: 'rejected'; url: string }
   | { action: 'ignored' };
 
-/** Decode the `url` query param from a `<scheme>://env?url=<encoded>` link. Null if absent/undecodable. */
-function parseEnvTargetUrl(link: string): string | null {
+/** Decode a query param by name from a `<scheme>://env?…` link. Null if absent/empty/undecodable. */
+function parseQueryParam(link: string, name: string): string | null {
   const q = String(link || '').indexOf('?');
   if (q < 0) return null;
   for (const part of link.slice(q + 1).split('&')) {
     const eq = part.indexOf('=');
-    if ((eq < 0 ? part : part.slice(0, eq)) !== 'url') continue;
+    if ((eq < 0 ? part : part.slice(0, eq)) !== name) continue;
     try {
       const decoded = decodeURIComponent((eq < 0 ? '' : part.slice(eq + 1)).replace(/\+/g, '%20')).trim();
       return decoded || null;
@@ -171,6 +173,19 @@ function parseEnvTargetUrl(link: string): string | null {
   return null;
 }
 
+/** Decode the `url` query param from a `<scheme>://env?url=<encoded>` link. Null if absent/undecodable. */
+function parseEnvTargetUrl(link: string): string | null {
+  return parseQueryParam(link, 'url');
+}
+
+/** Resolve a `?to=`/`?env=` preset NAME against `envs` by label (case-insensitive). Null if no name given. */
+function resolvePresetByName(link: string): { name: string; preset: { label: string; url: string } | undefined } | null {
+  const name = parseQueryParam(link, 'to') ?? parseQueryParam(link, 'env');
+  if (name === null) return null;
+  const preset = (SHELL_CONFIG.envSwitcher?.envs ?? []).find((e) => e.label.toLowerCase() === name.toLowerCase());
+  return { name, preset };
+}
+
 /** Structurally an env-switch deep link (`<scheme>://env…`) AND the switcher is enabled — the signal
  * events.ts uses to CONSUME the link (never forward an env link to the PWA). Inert (false) when the
  * feature is disabled/absent, so such a link simply falls through to the normal PWA deep-link path. */
@@ -179,14 +194,26 @@ export function isEnvDeepLink(link: string): boolean {
 }
 
 /**
- * PURE decision for an inbound `<scheme>://env?url=…` deep link — no dialogs, no side effects (unit-
- * testable, mirrors env-switcher-security.test.ts). SECURITY: the decoded target MUST pass the SAME
- * `isUrlAllowed` gate as the "Other" custom URL (anchored allowPattern, default-deny). Disabled feature
- * / non-env link / malformed (no decodable `url`) → `ignored` (silently dropped); target present but not
- * allowlisted → `rejected` (NEVER switch); allowlisted → `switch`.
+ * PURE decision for an inbound `<scheme>://env?…` deep link — no dialogs, no side effects (unit-testable,
+ * mirrors env-deeplink-security.test.ts). Two additive forms:
+ *
+ *  • `?to=<name>` (alias `?env=<name>`) — switch to a CONFIGURED preset by label, case-insensitive. A
+ *    resolved preset is TRUSTED and BYPASSES the allowlist (it's a declared env, exactly like the manual
+ *    switcher trusts its presets and only allowlists free-form "Other"). A name matching NO preset →
+ *    `rejected` (NEVER switch, NEVER fall through to `?url=`). `to` WINS when both `to`/`env` present, and
+ *    takes PRECEDENCE over `?url=` when both are present.
+ *  • `?url=<encoded>` — free-form target, allowlist-GATED: MUST pass the SAME `isUrlAllowed` gate as the
+ *    "Other" custom URL (anchored allowPattern, default-deny). Allowlisted → `switch`; else → `rejected`.
+ *
+ * Disabled feature / non-env link / neither param present (or malformed/undecodable) → `ignored`.
  */
 export function decideEnvDeepLink(link: string): EnvDeepLinkDecision {
   if (!isEnvSwitcherEnabled() || hostOf(link) !== 'env') return { action: 'ignored' };
+  // Preset-by-name takes precedence and bypasses the allowlist (trusted, configured env).
+  const named = resolvePresetByName(link);
+  if (named) {
+    return named.preset ? { action: 'switch', url: named.preset.url } : { action: 'rejected', url: named.name };
+  }
   const target = parseEnvTargetUrl(link);
   if (!target) return { action: 'ignored' };
   if (!isUrlAllowed(target)) return { action: 'rejected', url: target };

package/runtime/modules-native/widget/App_Resources/Android/src/main/java/cc/livx/appwrap/AppwrapWidgetProvider.kt

@@ -5,7 +5,13 @@ import android.appwidget.AppWidgetManager
 import android.appwidget.AppWidgetProvider
 import android.content.Context
 import android.content.Intent
+import android.graphics.Bitmap
 import android.graphics.BitmapFactory
+import android.graphics.BitmapShader
+import android.graphics.Canvas
+import android.graphics.Paint
+import android.graphics.RectF
+import android.graphics.Shader
 import android.net.Uri
 import android.view.View
 import android.widget.RemoteViews
@@ -15,12 +21,14 @@ import java.io.File
 /**
  * Home-screen launcher widget (Android parity of the iOS WidgetKit launcher). Reads the payload the
  * `widget.publish` handler wrote into SharedPreferences ("appwrap.widget" / key "appwrap.widget") and
- * renders up to 4 icon-grid tiles; each tile deep-links back into the app via its entry's URL. Icons
- * are PNGs the handler saved into the app files dir. Resource ids are looked up by name so the module
- * needs no compile-time reference to the host app's R class.
+ * renders up to 12 icon-grid tiles across 4 columns; each tile deep-links back into the app via its
+ * entry's URL. Icons are PNGs the handler saved into the app files dir. Resource ids are looked up by
+ * name so the module needs no compile-time reference to the host app's R class.
  */
 class AppwrapWidgetProvider : AppWidgetProvider() {
-    private val tiles = listOf("tile0", "tile1", "tile2", "tile3")
+    private val columns = 4
+    private val tiles = (0 until 12).map { "tile$it" }
+    private val rows = (0 until 3).map { "row$it" }
 
     override fun onUpdate(ctx: Context, mgr: AppWidgetManager, ids: IntArray) {
         for (id in ids) render(ctx, mgr, id)
@@ -29,6 +37,27 @@ class AppwrapWidgetProvider : AppWidgetProvider() {
     private fun res(ctx: Context, type: String, name: String) =
         ctx.resources.getIdentifier(name, type, ctx.packageName)
 
+    /**
+     * Round an app icon to look native on the home screen (iOS-parity: iOS clips to a
+     * RoundedRectangle ~24% of the icon size). RemoteViews ImageViews can't clip via an outline, so we
+     * center-crop the source to a square and redraw it into a rounded bitmap at full source resolution
+     * — the widget host then downscales a crisp, antialiased image rather than a hard-edged square.
+     */
+    private fun rounded(src: Bitmap): Bitmap {
+        val size = minOf(src.width, src.height)
+        val sq = if (src.width != src.height)
+            Bitmap.createBitmap(src, (src.width - size) / 2, (src.height - size) / 2, size, size)
+        else src
+        val out = Bitmap.createBitmap(size, size, Bitmap.Config.ARGB_8888)
+        val canvas = Canvas(out)
+        val paint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            shader = BitmapShader(sq, Shader.TileMode.CLAMP, Shader.TileMode.CLAMP)
+        }
+        val r = size * 0.22f
+        canvas.drawRoundRect(RectF(0f, 0f, size.toFloat(), size.toFloat()), r, r, paint)
+        return out
+    }
+
     private fun render(ctx: Context, mgr: AppWidgetManager, id: Int) {
         val rv = RemoteViews(ctx.packageName, res(ctx, "layout", "appwrap_widget"))
         val raw = ctx.getSharedPreferences("appwrap.widget", Context.MODE_PRIVATE)
@@ -39,10 +68,20 @@ class AppwrapWidgetProvider : AppWidgetProvider() {
         rv.setViewVisibility(res(ctx, "id", "appwrap_widget_title"),
             if (title.isEmpty()) View.GONE else View.VISIBLE)
         val entries = payload?.optJSONArray("entries")
+        val count = entries?.length() ?: 0
+
+        // A row with no entries at all is GONE so it contributes no height (the grid stays top-packed
+        // and leftover widget height falls to the bottom). A row that is only PARTLY filled stays
+        // VISIBLE and hides its trailing tiles as INVISIBLE, so a short final row keeps its tiles in
+        // the leading columns rather than centring them (iOS Grid's short-final-row behaviour).
+        for (r in rows.indices) {
+            rv.setViewVisibility(res(ctx, "id", rows[r]),
+                if (r * columns < count) View.VISIBLE else View.GONE)
+        }
 
         for (i in tiles.indices) {
             val tileId = res(ctx, "id", tiles[i])
-            val e = if (entries != null && i < entries.length()) entries.optJSONObject(i) else null
+            val e = if (entries != null && i < count) entries.optJSONObject(i) else null
             if (e == null) { rv.setViewVisibility(tileId, View.INVISIBLE); continue }
             rv.setViewVisibility(tileId, View.VISIBLE)
             rv.setTextViewText(res(ctx, "id", "${tiles[i]}_label"), e.optString("label"))
@@ -57,7 +96,7 @@ class AppwrapWidgetProvider : AppWidgetProvider() {
             if (icon.isNotEmpty()) {
                 val f = File(ctx.filesDir, icon)
                 if (f.exists()) BitmapFactory.decodeFile(f.absolutePath)
-                    ?.let { rv.setImageViewBitmap(res(ctx, "id", "${tiles[i]}_icon"), it) }
+                    ?.let { rv.setImageViewBitmap(res(ctx, "id", "${tiles[i]}_icon"), rounded(it)) }
             }
             val link = e.optString("deepLink", "")
             if (link.isNotEmpty()) {

package/runtime/modules-native/widget/App_Resources/Android/src/main/res/layout/appwrap_widget.xml

@@ -1,32 +1,36 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- AppWrap launcher widget: title + a 2×2 icon-grid of deep-linked tiles. Populated by
-     AppwrapWidgetProvider from the published payload; empty tiles are set INVISIBLE. Each icon can
-     carry an unread-count badge (tileN_badge) overlaid on its top-right corner. -->
+<!-- AppWrap launcher widget: title + a 4-column icon grid of deep-linked tiles (up to 3 rows / 12
+     tiles), populated by AppwrapWidgetProvider from the published payload.
+
+     LAYOUT CONTRACT (iOS parity — see AppwrapWidget.swift `gridView`):
+       * Rows are CONTENT-HEIGHT (wrap_content, NO layout_weight). The root is a vertical
+         LinearLayout at match_parent, so rows stack from the TOP and any leftover widget height
+         falls to the BOTTOM — the "app folder" feel. Giving rows `0dp + weight=1` (as this layout
+         once did) makes them greedily split the full height and float each icon to the centre of
+         its band, which strands the last row at the bottom behind a large dead gap on a
+         vertically-resized widget. Don't reintroduce weights here.
+       * A partially-filled row keeps its trailing tiles INVISIBLE (not GONE) so the short final row
+         stays aligned to the LEADING columns instead of centring. A fully-empty row is set GONE by
+         the provider so it consumes no height. -->
 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     android:orientation="vertical"
-    android:background="#F2FFFFFF"
+    android:background="@color/appwrap_widget_bg"
     android:padding="10dp">
 
     <TextView
         android:id="@+id/appwrap_widget_title"
         android:layout_width="wrap_content"
         android:layout_height="wrap_content"
-        android:textColor="#222222"
+        android:textColor="@color/appwrap_widget_title"
         android:textStyle="bold"
         android:textSize="12sp"
-        android:layout_marginBottom="6dp"
+        android:layout_marginBottom="8dp"
         android:maxLines="1"
         android:ellipsize="end" />
 
-    <LinearLayout
-        android:layout_width="match_parent"
-        android:layout_height="0dp"
-        android:layout_weight="1"
-        android:orientation="horizontal"
-        android:weightSum="2">
-
+    <LinearLayout android:id="@+id/row0" style="@style/AppwrapWidgetRow">
         <LinearLayout android:id="@+id/tile0" style="@style/AppwrapWidgetTile">
             <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
                 <ImageView android:id="@+id/tile0_icon" style="@style/AppwrapWidgetIcon" />
@@ -34,7 +38,6 @@
             </FrameLayout>
             <TextView android:id="@+id/tile0_label" style="@style/AppwrapWidgetLabel" />
         </LinearLayout>
-
         <LinearLayout android:id="@+id/tile1" style="@style/AppwrapWidgetTile">
             <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
                 <ImageView android:id="@+id/tile1_icon" style="@style/AppwrapWidgetIcon" />
@@ -42,15 +45,6 @@
             </FrameLayout>
             <TextView android:id="@+id/tile1_label" style="@style/AppwrapWidgetLabel" />
         </LinearLayout>
-    </LinearLayout>
-
-    <LinearLayout
-        android:layout_width="match_parent"
-        android:layout_height="0dp"
-        android:layout_weight="1"
-        android:orientation="horizontal"
-        android:weightSum="2">
-
         <LinearLayout android:id="@+id/tile2" style="@style/AppwrapWidgetTile">
             <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
                 <ImageView android:id="@+id/tile2_icon" style="@style/AppwrapWidgetIcon" />
@@ -58,7 +52,6 @@
             </FrameLayout>
             <TextView android:id="@+id/tile2_label" style="@style/AppwrapWidgetLabel" />
         </LinearLayout>
-
         <LinearLayout android:id="@+id/tile3" style="@style/AppwrapWidgetTile">
             <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
                 <ImageView android:id="@+id/tile3_icon" style="@style/AppwrapWidgetIcon" />
@@ -67,4 +60,64 @@
             <TextView android:id="@+id/tile3_label" style="@style/AppwrapWidgetLabel" />
         </LinearLayout>
     </LinearLayout>
+    <LinearLayout android:id="@+id/row1" style="@style/AppwrapWidgetRow">
+        <LinearLayout android:id="@+id/tile4" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile4_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile4_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile4_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile5" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile5_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile5_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile5_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile6" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile6_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile6_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile6_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile7" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile7_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile7_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile7_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+    </LinearLayout>
+    <LinearLayout android:id="@+id/row2" style="@style/AppwrapWidgetRow">
+        <LinearLayout android:id="@+id/tile8" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile8_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile8_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile8_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile9" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile9_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile9_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile9_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile10" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile10_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile10_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile10_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile11" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile11_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile11_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile11_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+    </LinearLayout>
 </LinearLayout>

package/runtime/modules-native/widget/App_Resources/Android/src/main/res/values/appwrap_widget_colors.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Widget chrome colors. Split into values/ + values-night/ so the tile follows the host's theme
+     (iOS parity: containerBackground(.fill.tertiary) + .primary label adapt automatically; a
+     hardcoded white slab with #333 text stayed stark-white on a dark home screen). The widget host
+     inflates RemoteViews with its own configuration, so -night resolves without any provider code. -->
+<resources>
+    <color name="appwrap_widget_bg">#F2FFFFFF</color>
+    <color name="appwrap_widget_title">#222222</color>
+    <color name="appwrap_widget_label">#333333</color>
+</resources>

package/runtime/modules-native/widget/App_Resources/Android/src/main/res/values/appwrap_widget_styles.xml

@@ -1,27 +1,54 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <!-- One icon-grid tile: a centered icon over a single-line label, equal-weight in its row. -->
+    <!-- One grid row: 4 equal columns, CONTENT-HEIGHT. The absence of a layout_weight is load-bearing
+         (see the layout's contract comment) — a weighted row splits the widget height and floats its
+         icons mid-band, leaving a dead gap on a tall widget. -->
+    <style name="AppwrapWidgetRow">
+        <item name="android:layout_width">match_parent</item>
+        <item name="android:layout_height">wrap_content</item>
+        <item name="android:orientation">horizontal</item>
+        <item name="android:weightSum">4</item>
+        <item name="android:layout_marginBottom">10dp</item>
+    </style>
+    <!-- One icon-grid tile: a centered icon over a single-line label, equal-weight in its row.
+         Height is wrap_content so the row measures to content, not to the widget's full height. -->
     <style name="AppwrapWidgetTile">
         <item name="android:layout_width">0dp</item>
-        <item name="android:layout_height">match_parent</item>
+        <item name="android:layout_height">wrap_content</item>
         <item name="android:layout_weight">1</item>
         <item name="android:orientation">vertical</item>
-        <item name="android:gravity">center</item>
+        <item name="android:gravity">center_horizontal</item>
         <item name="android:padding">4dp</item>
     </style>
+    <!-- The provider rounds the bitmap itself (RemoteViews ImageView can't clip via outline), so the
+         source is drawn crisp at full res and just scaled to fit here — no fitCenter squashing. -->
+    <!-- The icon carries a top margin + SYMMETRIC start/end margins so the wrap_content badge-container
+         FrameLayout measures LARGER than the 44dp icon. The badge (pinned top|end of that padded
+         container) lands in the end-margin region — visually BEYOND the icon's top-right corner (iOS
+         offset(x:6,y:-6) parity) — yet stays WITHIN the container bounds, so RemoteViews' default
+         child-clipping never cuts it. marginStart mirrors marginEnd so the icon stays HORIZONTALLY
+         CENTERED within the FrameLayout (and thus under its label) — an end-only margin shifts the
+         icon left, leaving an asymmetric right gap.
+         SIZE: 44dp + 14dp of margins = 58dp, + 8dp tile padding = 66dp per column. At 4 columns that
+         needs ~284dp of widget width, which is why appwrap_widget_info declares minResizeWidth 280dp
+         — shrinking below that would start clipping the icons. -->
     <style name="AppwrapWidgetIcon">
-        <item name="android:layout_width">36dp</item>
-        <item name="android:layout_height">36dp</item>
-        <item name="android:scaleType">fitCenter</item>
+        <item name="android:layout_width">44dp</item>
+        <item name="android:layout_height">44dp</item>
+        <item name="android:layout_marginTop">7dp</item>
+        <item name="android:layout_marginStart">7dp</item>
+        <item name="android:layout_marginEnd">7dp</item>
+        <item name="android:scaleType">fitXY</item>
     </style>
-    <!-- Unread-count bubble overlaid on the icon's top-right corner. -->
+    <!-- Unread-count bubble overlapping the icon's top-right corner (iOS-parity: small, circular for
+         single digits, red fill, white ring, bold white number). ~40% of the 44dp icon. -->
     <style name="AppwrapWidgetBadge">
         <item name="android:layout_width">wrap_content</item>
-        <item name="android:layout_height">18dp</item>
+        <item name="android:layout_height">17dp</item>
         <item name="android:layout_gravity">top|end</item>
-        <item name="android:minWidth">18dp</item>
-        <item name="android:paddingLeft">5dp</item>
-        <item name="android:paddingRight">5dp</item>
+        <item name="android:minWidth">17dp</item>
+        <item name="android:paddingLeft">4dp</item>
+        <item name="android:paddingRight">4dp</item>
         <item name="android:background">@drawable/appwrap_badge_bg</item>
         <item name="android:gravity">center</item>
         <item name="android:textColor">#FFFFFF</item>
@@ -32,7 +59,7 @@
     <style name="AppwrapWidgetLabel">
         <item name="android:layout_width">wrap_content</item>
         <item name="android:layout_height">wrap_content</item>
-        <item name="android:textColor">#333333</item>
+        <item name="android:textColor">@color/appwrap_widget_label</item>
         <item name="android:textSize">11sp</item>
         <item name="android:maxLines">1</item>
         <item name="android:ellipsize">end</item>

package/runtime/modules-native/widget/App_Resources/Android/src/main/res/values-night/appwrap_widget_colors.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Dark-theme counterpart of values/appwrap_widget_colors.xml (same names, resolved by the host's
+     night configuration). Translucent near-black slab + light text, mirroring the light variant's
+     alpha so the tile reads as the same material on either theme. -->
+<resources>
+    <color name="appwrap_widget_bg">#E61C1C1E</color>
+    <color name="appwrap_widget_title">#FFFFFF</color>
+    <color name="appwrap_widget_label">#E6FFFFFF</color>
+</resources>

package/runtime/modules-native/widget/App_Resources/Android/src/main/res/xml/appwrap_widget_info.xml

@@ -1,9 +1,13 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- Launcher widget: ~4×2 cells (medium), resizable, initial layout = the icon-grid. updatePeriodMillis
-     0 → the app drives refreshes itself via widget.publish (AppWidgetManager broadcast). -->
+     0 → the app drives refreshes itself via widget.publish (AppWidgetManager broadcast).
+     minResizeWidth 280dp: the grid is 4 fixed-width columns (~66dp each — see AppwrapWidgetIcon),
+     so ~284dp is the narrowest width that renders without clipping the icons. minWidth stays 250dp
+     (it only gates where the widget may be PLACED); minResizeWidth is what bounds a user drag. -->
 <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
     android:minWidth="250dp"
     android:minHeight="110dp"
+    android:minResizeWidth="280dp"
     android:targetCellWidth="4"
     android:targetCellHeight="2"
     android:updatePeriodMillis="0"