@livx.cc/native-kit 0.35.2 → 0.37.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.35.2",
-  "description": "Isomorphic native-capabilities kit for PWAs \u2014 same API in browser and in an appwrap native shell. Zero dependencies.",
+  "version": "0.37.0",
+  "description": "Isomorphic native-capabilities kit for PWAs — same API in browser and in an appwrap native shell. Zero dependencies.",
   "license": "MIT",
   "author": "Elya Livshitz",
   "homepage": "https://github.com/Livshitz/appwrap#readme",

package/src/core/NativeKit.ts

@@ -34,6 +34,7 @@ import { ToastModule } from '../modules/toast';
 import { TrackingModule } from '../modules/tracking';
 import { UiModule } from '../modules/ui';
 import { UpdatesModule } from '../modules/updates';
+import { WidgetModule } from '../modules/widget';
 
 export class NativeKitOptions {
   /** Priority order; first adapter whose detect() passes wins. */
@@ -107,10 +108,17 @@ export class NativeKit {
   public readonly backgroundTask = new BackgroundTaskModule(this);
   public readonly tracking = new TrackingModule(this);
   public readonly appleSignIn = new AppleSignInModule(this);
+  public readonly widget = new WidgetModule(this);
 
   public handshakeInfo: Handshake | null = null;
   public options: NativeKitOptions;
   private adapter: NativeKitAdapter | null = null;
+  /** Web-platform fallback behind a native shell: methods the shell rejects as UNSUPPORTED
+   * are retried against the WebAdapter, so a capability the webview itself can satisfy
+   * (geolocation, speech, navigator.share, …) works even when the shell ships no handler
+   * for it. Capability keys the shell reports as 'none'/absent surface as 'web' when the
+   * fallback can fulfil them. */
+  private webFallback: NativeKitAdapter | null = null;
   private readyPromise: Promise<Handshake> | null = null;
   private contextPromise: Promise<KitContext> | null = null;
 
@@ -153,6 +161,29 @@ export class NativeKit {
           );
         }
         this.handshakeInfo = handshake;
+        // Hybrid degrade: pair a native shell with the web adapter for anything the shell
+        // doesn't implement. WebAdapter.handshake() is pure feature detection (no side
+        // effects), so probing it here is safe.
+        if (this.adapter!.kind !== 'web') {
+          const web = this.options.adapters.find((a) => a.kind === 'web');
+          if (web?.detect()) {
+            try {
+              const webHs = await web.handshake(this.options.handshakeTimeoutMs);
+              this.webFallback = web;
+              for (const [key, value] of Object.entries(webHs.capabilities)) {
+                // Only ABSENT keys are upgraded. An explicit 'none' from the shell is a
+                // veto — it means "this platform genuinely can't", not "no handler" (e.g.
+                // desktop reports motion:'none': DeviceMotionEvent exists in the webview
+                // but never fires without an accelerometer, so 'web' would be a lie).
+                if (handshake.capabilities[key] === undefined && value !== 'none') {
+                  handshake.capabilities[key] = 'web';
+                }
+              }
+            } catch (e) {
+              console.warn('[native-kit] web fallback probe failed', e);
+            }
+          }
+        }
         // Zero-config: a native server-loader app begins polling for remote updates.
         this.updates.__autostart();
         // A background launch carries the wake id in the handshake → dispatch the registered handler
@@ -229,7 +260,14 @@ export class NativeKit {
 
   async invoke<T = unknown>(method: string, params?: unknown, opts?: InvokeOptions): Promise<T> {
     if (!this.adapter) await this.ready();
-    return this.adapter!.invoke<T>(method, params, opts);
+    try {
+      return await this.adapter!.invoke<T>(method, params, opts);
+    } catch (e) {
+      if (this.webFallback && e instanceof KitError && e.code === 'UNSUPPORTED') {
+        return this.webFallback.invoke<T>(method, params, opts);
+      }
+      throw e;
+    }
   }
 
   on(event: string, cb: (payload: unknown) => void): Unsubscribe {
@@ -239,12 +277,20 @@ export class NativeKit {
       let cancelled = false;
       this.ready()
         .then(() => {
-          if (!cancelled) unsub = this.adapter!.on(event, cb);
+          if (!cancelled) unsub = this.subscribe(event, cb);
         })
         .catch(() => {}); // ready() failure already surfaces to the ready() caller
       return () => { cancelled = true; unsub?.(); };
     }
-    return this.adapter.on(event, cb);
+    return this.subscribe(event, cb);
+  }
+
+  /** Listen on the active adapter AND the web fallback — a watch that fell back to the
+   * WebAdapter (geo.position, motion.data) emits its events there, not on the shell. */
+  private subscribe(event: string, cb: (payload: unknown) => void): Unsubscribe {
+    const unsubs = [this.adapter!.on(event, cb)];
+    if (this.webFallback) unsubs.push(this.webFallback.on(event, cb));
+    return () => unsubs.forEach((u) => u());
   }
 }
 

package/src/core/types.ts

@@ -1,4 +1,4 @@
-export type Platform = 'ios' | 'android' | 'web';
+export type Platform = 'ios' | 'android' | 'desktop' | 'web';
 export type AdapterKind = 'appwrap' | 'web';
 
 /** Bridge protocol version this kit speaks. The native shell reports its own in the handshake;

package/src/index.ts

@@ -42,6 +42,7 @@ export type { CalendarEventOptions } from './modules/calendar';
 export type { BrowserOptions } from './modules/browser';
 export type { OAuthAuthorizeParams, OAuthResult } from './modules/oauth';
 export type { TrackingStatus } from './modules/tracking';
+export type { WidgetEntry, WidgetPayload, WidgetStat, WidgetPublishResult } from './modules/widget';
 export type {
   AppleSignInName,
   AppleSignInParams,

package/src/modules/app.ts

@@ -9,6 +9,26 @@ export interface AppShortcut {
   subtitle?: string;
 }
 
+/** A standalone home-screen icon to pin via {@link AppModule.pinShortcut}. Unlike {@link AppShortcut}
+ *  it carries its own `url` (the deep link the icon opens) and an optional `iconUrl` tile image. */
+export interface PinShortcut {
+  /** Stable id — dedups repeat pins of the same target. */
+  id: string;
+  title: string;
+  /** Full deep link the pinned icon opens (e.g. `myapp://a/123`). */
+  url: string;
+  /** Tile image URL; fetched to a bitmap. Falls back to the app launcher icon on failure/omission. */
+  iconUrl?: string;
+  subtitle?: string;
+}
+
+export interface PinShortcutResult {
+  /** True once the OS accepted the pin request (the user still confirms the system prompt). */
+  pinned: boolean;
+  /** Present when not pinned: `'unsupported'` (iOS/web/old Android/incapable launcher). */
+  reason?: 'unsupported';
+}
+
 /** Where this build was installed from. Drives beta-vs-prod analytics cohorts.
  *  - `appstore` / `playstore` — public store install
  *  - `testflight` — iOS beta
@@ -111,4 +131,21 @@ export class AppModule {
   onShortcut(cb: (id: string) => void): Unsubscribe {
     return this.kit.on('app.shortcut', (p) => cb((p as { id: string }).id));
   }
+
+  /** 'native' where the OS can pin a STANDALONE launcher icon on request (Android 8+); iOS has no such
+   *  API (`{ios:false}`), so on iOS this reads 'none' — surface a widget there instead. Branch on this. */
+  get pinShortcutCapability() {
+    return this.kit.capability('pinShortcut');
+  }
+
+  /**
+   * Ask the OS to add a standalone home-screen icon for a deep target (distinct from {@link setShortcuts},
+   * which is the app-icon long-press menu). Android 8+ shows the system add-to-home prompt; unsupported
+   * launchers / iOS / web resolve `{pinned:false}`. `url` is the full deep link the icon opens (e.g.
+   * `myapp://a/123`) — routed through the app's normal deep-link handling. `iconUrl` is fetched to a tile
+   * (falls back to the launcher icon). Returns whether the pin request was accepted by the system.
+   */
+  pinShortcut(shortcut: PinShortcut): Promise<PinShortcutResult> {
+    return this.kit.invoke('app.pinShortcut', shortcut);
+  }
 }

package/src/modules/notifications.ts

@@ -12,6 +12,24 @@ export interface ScheduleOptions {
    * `kit.lifecycle.onDeepLink` routes it with no extra wiring.
    */
   deepLink?: string;
+  /**
+   * Display name of the notification's SENDER (e.g. a mini-app's name). When set,
+   * iOS renders a communication-style notification (iOS 15+) and Android posts on a
+   * per-sender channel, both showing this name as the "from" identity — the original
+   * `title` is demoted to the subtitle. Falls back to a plain notification otherwise.
+   */
+  sender?: string;
+  /**
+   * Sender avatar — an image URL or data-URI. Rendered as the circular avatar on
+   * iOS (INImage) and the large icon on Android. Ignored if it can't be loaded.
+   */
+  icon?: string;
+  /**
+   * App-icon badge count to apply when this notification is DELIVERED (iOS sets the
+   * springboard badge on delivery, even while the app is closed). Absent = leave the
+   * badge unchanged. Set 0 to clear on delivery.
+   */
+  badge?: number;
 }
 
 export class NotificationsModule {

package/src/modules/widget.ts

@@ -0,0 +1,65 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/** One tile/row in an icon-grid or list widget. `deepLink` is the full URL the tile opens (routed by
+ *  the app's deep-link handling); `iconUrl` is fetched to a tile image on the device. */
+export interface WidgetEntry {
+  label: string;
+  sublabel?: string;
+  deepLink?: string;
+  iconUrl?: string;
+  /** unread/attention count drawn as a bubble on the tile (icon-grid); absent/0 = no badge. */
+  badge?: number;
+}
+
+/** A single big number for the `stat` template. */
+export interface WidgetStat {
+  value: string;
+  label?: string;
+  sublabel?: string;
+}
+
+/** Payload published to the home-screen widget. `template` picks the layout:
+ *  - `icon-grid` — grid of {@link WidgetEntry} tiles (the app-launcher use)
+ *  - `list`      — rows of {@link WidgetEntry}
+ *  - `stat`      — one {@link WidgetStat} (optional whole-widget `deepLink`) */
+export interface WidgetPayload {
+  template: 'icon-grid' | 'list' | 'stat';
+  title?: string;
+  entries?: WidgetEntry[];
+  stat?: WidgetStat;
+  /** Whole-widget deep link (stat template, or the empty-state fallback). */
+  deepLink?: string;
+  /** Which home-screen widget kind this targets. `launcher` (default) = the app-launcher/icon-grid
+   *  widget; `data` = the separate data widget an in-app view can drive. Two kinds so a data publish
+   *  never clobbers the launcher (each renders from its own shared-store key). */
+  slot?: 'launcher' | 'data';
+}
+
+export interface WidgetPublishResult {
+  published: boolean;
+  reason?: 'unsupported';
+}
+
+/**
+ * Publish content to the app's home-screen widget (iOS WidgetKit / Android AppWidget). The shell writes
+ * the payload into a shared container the widget reads at render, fetching any `iconUrl` to a local
+ * tile image, then reloads the widget. Web/unsupported builds resolve `{published:false}`. Branch on
+ * {@link WidgetModule.capability}.
+ */
+export class WidgetModule {
+  constructor(private kit: NativeKit) {}
+
+  /** 'native' where a home-screen widget surface exists (iOS 14+ / Android AppWidget) · else 'none'. */
+  get capability() {
+    return this.kit.capability('widget');
+  }
+
+  publish(payload: WidgetPayload): Promise<WidgetPublishResult> {
+    return this.kit.invoke('widget.publish', payload);
+  }
+
+  /** Clear the widget (renders its empty state). */
+  clear(): Promise<WidgetPublishResult> {
+    return this.kit.invoke('widget.publish', { template: 'icon-grid', entries: [] });
+  }
+}