@livx.cc/native-kit 0.37.0 → 0.38.0

package/package.json

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

package/src/core/NativeKit.ts

@@ -13,6 +13,7 @@ import { ContactsModule } from '../modules/contacts';
 import { DeviceModule } from '../modules/device';
 import { FsModule } from '../modules/fs';
 import { GeoModule } from '../modules/geo';
+import { HeadingModule } from '../modules/heading';
 import { HapticsModule } from '../modules/haptics';
 import { HealthModule } from '../modules/health';
 import { KeyboardModule } from '../modules/keyboard';
@@ -89,6 +90,7 @@ export class NativeKit {
   public readonly push = new PushModule(this);
   public readonly biometrics = new BiometricsModule(this);
   public readonly geo = new GeoModule(this);
+  public readonly heading = new HeadingModule(this);
   public readonly photos = new PhotosModule(this);
   public readonly network = new NetworkModule(this);
   public readonly lifecycle = new LifecycleModule(this);

package/src/core/web-adapter.ts

@@ -53,6 +53,10 @@ export class WebAdapter implements NativeKitAdapter {
   private listeners = new Map<string, Set<(payload: unknown) => void>>();
   private geoWatchId: number | null = null;
   private motionHandler: ((e: DeviceMotionEvent) => void) | null = null;
+  private headingHandler: ((e: DeviceOrientationEvent) => void) | null = null;
+  /** the orientation event actually feeding headingHandler ('deviceorientationabsolute' on Android,
+   * 'deviceorientation' on iOS via webkitCompassHeading) — remembered so stop removes the right one. */
+  private headingEvent: 'deviceorientation' | 'deviceorientationabsolute' | null = null;
   /** Tear-down for an in-progress scanner.scan loop (stops the camera, removes the overlay). */
   private scanCancel: (() => void) | null = null;
   /** Stop an in-progress speech.listen session (resolves it with the best transcript so far). */
@@ -90,6 +94,7 @@ export class WebAdapter implements NativeKitAdapter {
       reviews: 'none',
       themeColor: 'web', // the browser honors <meta name="theme-color"> itself
       motion: typeof DeviceMotionEvent !== 'undefined' ? 'web' : 'none',
+      heading: typeof DeviceOrientationEvent !== 'undefined' ? 'web' : 'none',
       contacts: n.contacts?.select ? 'web' : 'none',
       calendar: 'none',
       camera: 'web', // <input capture> — mobile browsers open the camera
@@ -343,6 +348,52 @@ export class WebAdapter implements NativeKitAdapter {
         }
         return undefined as T;
 
+      case 'heading.start': {
+        if (typeof DeviceOrientationEvent === 'undefined') throw new KitError('UNSUPPORTED', 'No orientation sensor on this browser');
+        // iOS Safari gates DeviceOrientation behind the same explicit permission prompt as motion.
+        const req = (DeviceOrientationEvent as unknown as DeviceOrientationEventWithPermission).requestPermission;
+        if (req) {
+          const state = await req().catch((e: Error) => { throw new KitError('DENIED', e.message); });
+          if (state !== 'granted') throw new KitError('DENIED', 'Orientation permission not granted');
+        }
+        if (!this.headingHandler) {
+          const hz = Math.min(60, Math.max(1, Number(p.hz) || 10));
+          const minMs = 1000 / hz;
+          let last = 0;
+          this.headingHandler = (e) => {
+            const now = performance.now();
+            if (now - last < minMs) return;
+            // iOS: webkitCompassHeading is already a TRUE 0–360 compass heading (clockwise from north).
+            // Android/standard: `deviceorientationabsolute`'s alpha is 0–360 counter-clockwise from
+            // north, so the compass heading is (360 − alpha). `e.absolute` guards against a relative
+            // reading that isn't north-referenced (useless as a compass).
+            let deg: number | null = null;
+            let accuracy: number | undefined;
+            if (typeof e.webkitCompassHeading === 'number') {
+              deg = e.webkitCompassHeading;
+              accuracy = e.webkitCompassAccuracy != null ? Math.abs(e.webkitCompassAccuracy) : undefined;
+            } else if (e.absolute && typeof e.alpha === 'number') {
+              deg = 360 - e.alpha; // normalized to [0,360) once at emit below
+            }
+            if (deg == null) return; // non-absolute reading — not a usable compass heading
+            last = now;
+            this.emit('heading.data', { deg: ((deg % 360) + 360) % 360, accuracy });
+          };
+          // Prefer the north-referenced 'deviceorientationabsolute' (Android/Chrome); fall back to
+          // 'deviceorientation' (iOS delivers webkitCompassHeading there — no absolute event).
+          this.headingEvent = 'ondeviceorientationabsolute' in window ? 'deviceorientationabsolute' : 'deviceorientation';
+          window.addEventListener(this.headingEvent, this.headingHandler as EventListener);
+        }
+        return undefined as T;
+      }
+      case 'heading.stop':
+        if (this.headingHandler && this.headingEvent) {
+          window.removeEventListener(this.headingEvent, this.headingHandler as EventListener);
+          this.headingHandler = null;
+          this.headingEvent = null;
+        }
+        return undefined as T;
+
       case 'contacts.pick': {
         const select = navigator.contacts?.select;
         if (!select) throw new KitError('UNSUPPORTED', 'Contact Picker API unavailable');

package/src/index.ts

@@ -28,6 +28,7 @@ export type { DeviceInfo } from './modules/device';
 export type { ScheduleOptions } from './modules/notifications';
 export type { PushMessage, PushPlatform, PushToken } from './modules/push';
 export type { GeoPosition } from './modules/geo';
+export type { HeadingSample } from './modules/heading';
 export type { PickedPhoto, PickPhotoOptions } from './modules/photos';
 export type { AudioMode, MediaDeviceLite, AudioState } from './modules/media';
 export type { NetworkStatus } from './modules/network';

package/src/modules/heading.ts

@@ -0,0 +1,38 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+export interface HeadingSample {
+  /** Compass heading in degrees, 0–360 (0 = north, 90 = east). */
+  deg: number;
+  /** Heading accuracy in degrees (± this many deg), when the platform reports it. */
+  accuracy?: number;
+}
+
+export class HeadingModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('heading');
+  }
+
+  /** Stream compass heading updates; resolves an unsubscribe once streaming starts. Requests
+   * sensor permission (iOS gesture gate) on first use. Mirrors {@link MotionModule.watch}. */
+  async watch(cb: (sample: HeadingSample) => void, opts?: { hz?: number }): Promise<Unsubscribe> {
+    const off = this.kit.on('heading.data', (p) => cb(p as HeadingSample));
+    try {
+      await this.kit.invoke('heading.start', opts?.hz ? { hz: opts.hz } : undefined);
+    } catch (e) {
+      off();
+      throw e;
+    }
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      off();
+      this.kit
+        .invoke('heading.stop')
+        .catch((e) => console.warn('[native-kit] heading.stop failed', e));
+    };
+  }
+}

package/src/web-experimental.d.ts

@@ -84,4 +84,16 @@ declare global {
   interface DeviceMotionEventWithPermission {
     requestPermission?(): Promise<'granted' | 'denied' | 'prompt'>;
   }
+
+  /** iOS Safari gates DeviceOrientation behind the same static permission prompt as DeviceMotion. */
+  interface DeviceOrientationEventWithPermission {
+    requestPermission?(): Promise<'granted' | 'denied' | 'prompt'>;
+  }
+
+  /** iOS exposes a true compass heading (0–360, magnetic north) on the orientation event — a
+   * non-standard field the lib doesn't declare. Merge it on (plus its accuracy). */
+  interface DeviceOrientationEvent {
+    webkitCompassHeading?: number;
+    webkitCompassAccuracy?: number;
+  }
 }