@livx.cc/native-kit 0.35.0 → 0.35.2

package/README.md

@@ -3,7 +3,7 @@
 Isomorphic native-capabilities kit for PWAs — the **same API in the browser and inside an [appwrap](https://github.com/Livshitz/appwrap) native shell**. Zero dependencies.
 
 ```bash
-bun add @livx.cc/native-kit   # or: npm i @livx.cc/native-kit
+bun add @livx.cc/native-kit
 ```
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.35.0",
+  "version": "0.35.2",
   "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

@@ -122,10 +122,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.

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';

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/motion.ts

@@ -19,11 +19,12 @@ export class MotionModule {
     return this.kit.capability('motion');
   }
 
-  /** Stream motion samples (~10Hz); resolves an unsubscribe once streaming starts. */
-  async watch(cb: (sample: MotionSample) => void): Promise<Unsubscribe> {
+  /** Stream motion samples; resolves an unsubscribe once streaming starts. `opts.hz` sets the emit
+   * rate (default 10, clamped 5–60 native-side) — bump it for crisp tilt (e.g. a game asks 60). */
+  async watch(cb: (sample: MotionSample) => void, opts?: { hz?: number }): Promise<Unsubscribe> {
     const off = this.kit.on('motion.data', (p) => cb(p as MotionSample));
     try {
-      await this.kit.invoke('motion.start');
+      await this.kit.invoke('motion.start', opts?.hz ? { hz: opts.hz } : undefined);
     } catch (e) {
       off();
       throw e;