@livx.cc/native-kit 0.35.1 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.35.1",
+  "version": "0.36.0",
   "description": "Isomorphic native-capabilities kit for PWAs \u2014 same API in browser and in an appwrap native shell. Zero dependencies.",
   "license": "MIT",
   "author": "Elya Livshitz",

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;
 
@@ -122,10 +130,26 @@ export class NativeKit {
   ready(): Promise<Handshake> {
     if (!this.readyPromise) {
       this.readyPromise = (async () => {
-        const adapter = this.options.adapters.find((a) => a.detect());
-        if (!adapter) throw new KitError('NOT_READY', 'No adapter detected this environment');
-        this.adapter = adapter;
-        const handshake = await adapter.handshake(this.options.handshakeTimeoutMs);
+        const candidates = this.options.adapters.filter((a) => a.detect());
+        if (!candidates.length) throw new KitError('NOT_READY', 'No adapter detected this environment');
+        // Try each detected adapter in priority order. A transport can LOOK native yet refuse
+        // the handshake — e.g. a host shell exposing a capability-GATED `appwrap` message
+        // handler to an embedded/mini-app page (CAP_DENIED, or no handshake handler at all).
+        // Falling through to the next adapter (web) lets the app degrade to standard web
+        // APIs instead of dying with no transport at all.
+        let handshake: Handshake | null = null;
+        let lastError: unknown = null;
+        for (const adapter of candidates) {
+          try {
+            handshake = await adapter.handshake(this.options.handshakeTimeoutMs);
+            this.adapter = adapter;
+            break;
+          } catch (e) {
+            lastError = e;
+            console.warn(`[native-kit] ${adapter.kind} adapter handshake failed (${(e as Error)?.message ?? e}) — trying next adapter`);
+          }
+        }
+        if (!handshake) throw lastError ?? new KitError('NOT_READY', 'All adapters failed the handshake');
         // Version-skew safety net: a native shell from an older `appwrap init` may speak a
         // different protocol. Fail loud rather than silently mis-degrade. The web adapter
         // always reports the kit's own protocol, so this only ever fires against a stale shell.
@@ -137,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
@@ -213,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 {
@@ -223,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/core/web-adapter.ts

@@ -316,10 +316,14 @@ export class WebAdapter implements NativeKitAdapter {
           if (state !== 'granted') throw new KitError('DENIED', 'Motion permission not granted');
         }
         if (!this.motionHandler) {
+          // Honor the requested rate (default 10 Hz, clamped 5–60 — mirrors the native cap);
+          // a tilt game asks 60 and 10 Hz steering is unplayably laggy.
+          const hz = Math.min(60, Math.max(5, Number(p.hz) || 10));
+          const minMs = 1000 / hz;
           let last = 0;
           this.motionHandler = (e) => {
             const now = performance.now();
-            if (now - last < 100) return; // ~10Hz
+            if (now - last < minMs) return;
             last = now;
             const a = e.accelerationIncludingGravity;
             const r = e.rotationRate;

package/src/index.ts

@@ -29,7 +29,7 @@ export type { ScheduleOptions } from './modules/notifications';
 export type { PushMessage, PushPlatform, PushToken } from './modules/push';
 export type { GeoPosition } from './modules/geo';
 export type { PickedPhoto, PickPhotoOptions } from './modules/photos';
-export type { AudioMode, MediaDeviceLite } from './modules/media';
+export type { AudioMode, MediaDeviceLite, AudioState } from './modules/media';
 export type { NetworkStatus } from './modules/network';
 export type { ActionOptions, AlertOptions, ConfirmOptions, SafeAreaInsets } from './modules/ui';
 export type { MotionSample } from './modules/motion';
@@ -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/media.ts

@@ -1,4 +1,5 @@
 import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
 
 /**
  * Live media bridge — mic / camera / speaker. The streams themselves are plain
@@ -9,6 +10,14 @@ import type { NativeKit } from '../core/NativeKit';
  */
 export type AudioMode = 'playback' | 'playAndRecord' | 'voiceChat' | 'default';
 
+/** Whether the device would actually play game/media sound right now, plus the media volume (0–1). */
+export interface AudioState {
+  /** True when output is effectively silenced — iOS mute switch OR zero media volume; Android: zero media volume. */
+  silent: boolean;
+  /** Media output volume, 0–1 (iOS AVAudioSession.outputVolume / Android STREAM_MUSIC). */
+  volume: number;
+}
+
 export interface MediaDeviceLite {
   kind: MediaDeviceKind;
   label: string;
@@ -68,6 +77,36 @@ export class MediaModule {
     return this.kit.invoke('media.configureAudio', { mode });
   }
 
+  /**
+   * Watch whether sound would actually be heard — for reflecting the OS mute/volume state in UI
+   * (e.g. disabling an in-app speaker toggle while the device is silenced). Fires `cb` with the
+   * current {@link AudioState} immediately and again whenever it changes (~1s granularity). Native
+   * only — on web (no OS silent concept) this is a no-op returning a noop unsubscribe.
+   */
+  async watchAudio(cb: (state: AudioState) => void): Promise<Unsubscribe> {
+    // Wait for the handshake so `platform` is resolved (it defaults to 'web' until ready — callers
+    // often subscribe during early app setup, before the bridge handshake lands).
+    await this.kit.ready().catch(() => {});
+    // Gate on PLATFORM, not the 'media' capability: the audio-state handler is always registered in
+    // the native shell, so this works even for apps that don't opt into the full media module. Only
+    // the browser (no OS silent/volume concept) is a genuine no-op.
+    if (this.kit.platform === 'web') return () => {};
+    const off = this.kit.on('media.audioState', (p) => cb(p as AudioState));
+    try {
+      await this.kit.invoke('media.audioWatch.start');
+    } catch (e) {
+      off();
+      throw e;
+    }
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      off();
+      this.kit.invoke('media.audioWatch.stop').catch((e) => console.warn('[native-kit] audioWatch.stop failed', e));
+    };
+  }
+
   /** Stop every track on a stream — convenience to release the camera/mic LED. */
   stop(stream: MediaStream | null | undefined): void {
     stream?.getTracks().forEach((t) => t.stop());

package/src/modules/notifications.ts

@@ -12,6 +12,18 @@ 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;
 }
 
 export class NotificationsModule {

package/src/modules/widget.ts

@@ -0,0 +1,63 @@
+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;
+}
+
+/** 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: [] });
+  }
+}