@livx.cc/appwrap 0.48.0 → 0.48.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.48.0",
+  "version": "0.48.2",
   "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/capabilities.manifest.ts

@@ -98,6 +98,16 @@ export const MODULES: ModuleManifest[] = [
     ios: { permissions: [{ key: 'NSLocationWhenInUseUsageDescription', domain: 'location', defaultUsage: 'Show your location.' }] },
     android: { permissions: ['android.permission.ACCESS_FINE_LOCATION', 'android.permission.ACCESS_COARSE_LOCATION'] },
   },
+  // heading (compass) — handlers live in the always-bundled parity/android groups (registerParity/
+  // AndroidHandlers). iOS CLHeading via CLLocationManager: trueHeading needs location auth, so it rides
+  // geo's SAME NSLocationWhenInUseUsageDescription (the CLI dedups when geo is also active; declared here
+  // for self-containment so a heading-only app still stamps it). Android uses TYPE_ROTATION_VECTOR — a
+  // motion sensor that needs NO runtime permission, so no android block (avoid an unused-permission flag).
+  {
+    name: 'heading', group: 'parity',
+    capabilities: { heading: 'native' },
+    ios: { permissions: [{ key: 'NSLocationWhenInUseUsageDescription', domain: 'location', defaultUsage: 'Show your compass heading.' }] },
+  },
   {
     name: 'photos', group: 'extended',
     capabilities: { photos: 'native' },
@@ -308,39 +318,11 @@ export const MODULES: ModuleManifest[] = [
   },
 
   // ── widget — home-screen presence via a native extension (iOS WidgetKit / Android AppWidget) ──
-  // Opt-in; ships its own extension target under modules-native/widget/. The host publishes tiles into
-  // an App Group container the extension reads at render; each tile deep-links back on tap. The App
-  // Group entitlement is app-specific (group.<appId>), so consumers supply it via appwrap.config
-  // `iosEntitlements` for now (Phase-2 templates `group.$APPID` in the CLI). Phase-1 spike ships a
-  // single static tile to prove the extension builds, provisions the group, renders, and deep-links.
-  {
-    name: 'widget', group: 'widget',
-    capabilities: { widget: { ios: true, android: true } },
-    // Android launcher widget = an AppWidgetProvider receiver (icon-grid) fed by the widget.publish
-    // handler via SharedPreferences; Kotlin source + res ship as nativeSrc. iOS side = the WidgetKit
-    // extension under nativeSrc's App_Resources/iOS/extensions/.
-    android: {
-      kotlin: true,
-      manifestApplication: `<receiver
-      android:name="cc.livx.appwrap.AppwrapWidgetProvider"
-      android:exported="true">
-      <intent-filter>
-        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
-      </intent-filter>
-      <meta-data
-        android:name="android.appwidget.provider"
-        android:resource="@xml/appwrap_widget_info" />
-    </receiver>`,
-    },
-    nativeSrc: 'widget',
-  },
-
-  // ── widget — home-screen presence via a native extension (iOS WidgetKit / Android AppWidget) ──
-  // Opt-in; ships its own extension target under modules-native/widget/. The host publishes tiles into
-  // an App Group container the extension reads at render; each tile deep-links back on tap. The App
-  // Group entitlement is app-specific (group.<appId>), so consumers supply it via appwrap.config
-  // `iosEntitlements` for now (Phase-2 templates `group.$APPID` in the CLI). Phase-1 spike ships a
-  // single static tile to prove the extension builds, provisions the group, renders, and deep-links.
+  // Opt-in; ships its own native surfaces under modules-native/widget/. The app publishes tiles/stats
+  // into a shared container (App Group on iOS, SharedPreferences on Android) via the `widget.publish`
+  // handler; the extension/provider reads it at render and each tile deep-links back on tap. Two kinds:
+  // a `launcher` icon-grid (the host's pinned apps) and a `data` widget (a mini-app's live stat/list).
+  // The App Group id is derived (`group.<appId>`) and templated into both targets by the CLI.
   {
     name: 'widget', group: 'widget',
     capabilities: { widget: { ios: true, android: true } },

package/runtime/app/shell/handlers-android.ts

@@ -365,6 +365,44 @@ export function registerAndroidHandlers(): void {
     motionListener = null;
   });
 
+  // ── heading (SensorManager: rotation vector → compass azimuth) ─────
+  // TYPE_ROTATION_VECTOR fuses accelerometer+magnetometer(+gyro) into an orientation; getOrientation
+  // gives azimuth (rad, counter-clockwise from north), which we convert to a 0–360 compass heading.
+  // UNVERIFIED-ON-DEVICE.
+  let headingListener: android.hardware.SensorEventListener | null = null;
+
+  bridge.register('heading.start', (p: { hz?: number } = {}) => {
+    if (headingListener) return; // already streaming
+    const hz = Math.max(1, Math.min(60, p.hz || 10));
+    const minMs = 1000 / hz;
+    const sm = sensorManager();
+    const rot = sm.getDefaultSensor(android.hardware.Sensor.TYPE_ROTATION_VECTOR);
+    if (!rot) throw err('UNSUPPORTED', 'No rotation-vector sensor (compass) on this device');
+    const R = Array.create('float', 9);
+    const orientation = Array.create('float', 3);
+    let last = 0;
+    headingListener = new android.hardware.SensorEventListener({
+      onAccuracyChanged() {},
+      onSensorChanged(event: android.hardware.SensorEvent) {
+        const now = java.lang.System.currentTimeMillis();
+        if (now - last < minMs) return; // throttle emit to the requested Hz
+        last = now;
+        android.hardware.SensorManager.getRotationMatrixFromVector(R, event.values);
+        android.hardware.SensorManager.getOrientation(R, orientation);
+        // orientation[0] = azimuth in rad (−π..π), CCW from north. Convert to 0–360 compass degrees.
+        const deg = ((orientation[0] * 180) / Math.PI + 360) % 360;
+        bridge.emit('heading.data', { deg });
+      },
+    });
+    const periodUs = Math.max(5000, Math.round(1_000_000 / hz));
+    sm.registerListener(headingListener, rot, periodUs);
+  });
+
+  bridge.register('heading.stop', () => {
+    if (headingListener) sensorManager().unregisterListener(headingListener);
+    headingListener = null;
+  });
+
   // ── contacts (ACTION_PICK + ContactsContract query) ────────────────
   bridge.register('contacts.pick', async () => {
     if (!(await requestPermissions(['android.permission.READ_CONTACTS']))) {

package/runtime/app/shell/handlers-parity.ts

@@ -24,7 +24,7 @@ function readContact(contact: CNContact): { name: string; phones: string[]; emai
 // shared module can instantiate on Android — NSObject/CL*/CN*/UIImagePicker* are iOS globals, and a
 // top-level `extends NSObject` would evaluate at ES-module load and crash the Android shell.
 // any: module-level holders for runtime-built ObjC subclasses; each class BODY stays fully typed.
-let GeoWatchDelegate: any, ContactPickerDelegate: any, CameraCaptureDelegate: any;
+let GeoWatchDelegate: any, HeadingDelegate: any, ContactPickerDelegate: any, CameraCaptureDelegate: any;
 function ensureIosDelegates(): void {
   if (!isIOS || GeoWatchDelegate) return;
 
@@ -58,6 +58,30 @@ function ensureIosDelegates(): void {
   }
   GeoWatchDelegate = GeoWatchDelegateImpl;
 
+  // CLLocationManager delegate for the compass heading stream (heading.watch). Emits a 0–360
+  // compass heading; prefers trueHeading (needs location auth) and falls back to magneticHeading.
+  // UNVERIFIED-ON-DEVICE.
+  @NativeClass()
+  class HeadingDelegateImpl extends NSObject implements CLLocationManagerDelegate {
+    static ObjCProtocols = [CLLocationManagerDelegate];
+    static new(): HeadingDelegateImpl {
+      return <HeadingDelegateImpl>super.new();
+    }
+    locationManagerDidUpdateHeading(_m: CLLocationManager, heading: CLHeading): void {
+      // trueHeading is negative when unavailable (no location auth / no recent fix) — magneticHeading
+      // is always valid once the magnetometer is calibrated.
+      const deg = heading.trueHeading >= 0 ? heading.trueHeading : heading.magneticHeading;
+      bridge.emit('heading.data', {
+        deg: ((deg % 360) + 360) % 360,
+        accuracy: heading.headingAccuracy >= 0 ? heading.headingAccuracy : undefined,
+      });
+    }
+    locationManagerDidFailWithError(_m: CLLocationManager, error: NSError): void {
+      console.warn('AppWrap: heading.watch error', error.localizedDescription);
+    }
+  }
+  HeadingDelegate = HeadingDelegateImpl;
+
   // CNContactPickerViewController delegate. The picker resolution callbacks are set as instance fields
   // after construction (replacing the old closure-captured `resolve`).
   @NativeClass()
@@ -220,6 +244,36 @@ export function registerParityHandlers(): void {
     motionManager = null;
   });
 
+  // ── heading (CLLocationManager compass) ────────────────────────────
+  // Compass heading via CLLocationManager.startUpdatingHeading (delegate-pushed, not polled — the
+  // heading callback is reliable, unlike CoreMotion's block). UNVERIFIED-ON-DEVICE.
+  let headingManager: CLLocationManager | null = null;
+  let headingDelegate: any = null;
+
+  bridge.register('heading.start', () => {
+    if (!isIOS) throw iosOnly();
+    if (headingManager) return; // already streaming
+    Utils.dispatchToMainThread(() => {
+      const mm = CLLocationManager.new();
+      if (!CLLocationManager.headingAvailable()) throw err('UNSUPPORTED', 'No compass on this device');
+      headingManager = mm;
+      headingDelegate = HeadingDelegate.new();
+      mm.delegate = headingDelegate;
+      mm.headingFilter = 1; // emit on ≥1° change
+      // trueHeading requires location auth; request it so we can report true (not just magnetic) north.
+      if (mm.authorizationStatus === CLAuthorizationStatus.kCLAuthorizationStatusNotDetermined) {
+        mm.requestWhenInUseAuthorization();
+      }
+      mm.startUpdatingHeading();
+    });
+  });
+
+  bridge.register('heading.stop', () => {
+    headingManager?.stopUpdatingHeading();
+    headingManager = null;
+    headingDelegate = null;
+  });
+
   // ── contacts (CNContactPickerViewController — no permission needed) ──
   bridge.register('contacts.pick', () => {
     if (!isIOS) throw iosOnly();

package/runtime/app/shell/web-quirks.ts

@@ -37,6 +37,24 @@ window.__APPWRAP_DEBUG__=${SHELL_CONFIG.debug ? 'true' : 'false'};
   });
   window.addEventListener('error', function(e){ post('[uncaught] ' + (e.message || e) + ' @ ' + (e.filename || '') + ':' + (e.lineno || 0)); });
   window.addEventListener('unhandledrejection', function(e){ var r = e.reason; post('[rejection] ' + ((r && (r.stack || r.message)) || r)); });
+  // Debug builds only: a loud, non-interactive DEV strip pinned to the top edge showing the server
+  // this shell points at. A dev-pointing ipa (debug:true) must never be mistaken for a store/prod
+  // build — the host in the strip makes "which backend am I on?" answerable at a glance.
+  var srv = ${JSON.stringify(SHELL_CONFIG.serverUrl || '')};
+  var host = ''; try { host = srv ? new URL(srv).host : (location && location.host) || ''; } catch (e) { host = srv || ''; }
+  function mountDevStrip(){
+    if (document.getElementById('__appwrap_dev_strip__') || !document.body) return;
+    var el = document.createElement('div');
+    el.id = '__appwrap_dev_strip__';
+    el.textContent = 'DEV · ' + host;
+    el.style.cssText = 'position:fixed;top:0;left:0;right:0;z-index:2147483647;pointer-events:none;'
+      + 'background:#b91c1c;color:#fff;text-align:center;letter-spacing:.5px;'
+      + 'font:600 10px/1 -apple-system,system-ui,sans-serif;'
+      + 'padding:calc(env(safe-area-inset-top,0px) + 2px) 6px 2px;';
+    document.body.appendChild(el);
+  }
+  if (document.body) mountDevStrip();
+  else document.addEventListener('DOMContentLoaded', mountDevStrip);
 })();`;
 
 /**