@stacksjs/mobile 0.74.43 → 0.74.45

package/README.md

@@ -14,6 +14,43 @@ if (isNativeMobile())
 const position = await location.getCurrentPosition()
 ```
 
+## Native bridge availability
+
+`mobile` is a typed service collection (`MobileApi`), available in both browsers
+and native apps. Its services keep Craft's existing web fallbacks. Use
+`getNativeMobileBridge()` or `mobile.nativeBridge` for native-only feature checks:
+
+```ts
+import { getNativeMobileBridge, mobile } from '@stacksjs/mobile'
+
+const bridge = getNativeMobileBridge()
+if (bridge?.capabilities.backgroundLocation === true)
+  await mobile.location.startRecording({ enableHighAccuracy: true })
+
+const unsubscribe = mobile.onReady(() => {
+  const current = mobile.nativeBridge
+  const hasHealth = current?.platform === 'ios'
+    ? current.capabilities.healthKit === true
+    : current?.capabilities.health === true
+  // Update capability-specific UI with hasHealth.
+})
+```
+
+Both accessors return `CraftMobileBridge | null`. They read the current host on
+each call, so late bridge injection is visible without reimporting the package.
+Browsers, server rendering, and desktop Craft hosts return `null`. Mobile hosts
+report their native `ios` or `android` platform, independent of the user agent.
+Call `unsubscribe()` when disposing the readiness listener.
+
+`CraftMobileBridge` exposes read-only metadata, not raw native methods. Its
+`capabilities` uses Craft's enabled-feature names, including `geolocation`,
+`biometric`, iOS `healthKit`, and Android `health` (Health Connect). A missing or
+non-boolean flag is `undefined`, never implicitly enabled. Older hosts without a
+capability map return an empty map. These flags are distinct from the hardware
+report returned asynchronously by `mobile.device.getCapabilities()` and do not
+replace permission requests or error handling. Invoke operations through the
+typed services, not through the metadata object.
+
 The `health` facade reads authorized Apple Health or Android Health Connect
 metrics and writes completed workouts using one payload. `watchConnectivity`
 keeps companion controls and recording state synchronized without exposing

package/dist/index.d.ts

@@ -24,12 +24,92 @@ export declare const pushNotifications: PushNotificationsApi;
 export declare const health: HealthApi;
 export declare const liveActivities: LiveActivitiesApi;
 export declare const watchConnectivity: WatchConnectivityApi;
+/** Reads the current host, including a bridge injected after this module loaded. */
+export declare function getNativeMobileBridge(): CraftMobileBridge | null;
 export declare function isNativeMobile(): boolean;
 export declare function onMobileReady(callback: (event: CraftReadyEvent) => void): () => void;
 export declare function withNativeFeedback<T>(action: () => T | Promise<T>): Promise<T>;
-export declare const mobile: unknown;
+export declare const mobile: MobileApi;
 
 // From: src/types.ts
+/** Enabled native features, not the hardware report from device.getCapabilities(). */
+export declare interface CraftMobileCapabilities {
+  haptics?: boolean
+  speechRecognition?: boolean
+  share?: boolean
+  camera?: boolean
+  biometric?: boolean
+  pushNotifications?: boolean
+  secureStorage?: boolean
+  geolocation?: boolean
+  backgroundLocation?: boolean
+  healthKit?: boolean
+  health?: boolean
+  liveActivities?: boolean
+  watchConnectivity?: boolean
+  clipboard?: boolean
+  contacts?: boolean
+  calendar?: boolean
+  localNotifications?: boolean
+  inAppPurchase?: boolean
+  keepAwake?: boolean
+  orientationLock?: boolean
+  deepLinks?: boolean
+  flashlight?: boolean
+  network?: boolean
+  deviceInfo?: boolean
+  badge?: boolean
+  appReview?: boolean
+  appBadge?: boolean
+  networkStatus?: boolean
+  openURL?: boolean
+  vibrationPattern?: boolean
+  appState?: boolean
+  qrScanner?: boolean
+  filePicker?: boolean
+  fileDownload?: boolean
+  googleSignIn?: boolean
+  audioRecording?: boolean
+  videoRecording?: boolean
+  motionSensors?: boolean
+  localDatabase?: boolean
+  bluetooth?: boolean
+  nfc?: boolean
+  screenCapture?: boolean
+}
+/** Browser-safe metadata from Craft's iOS or Android bridge. */
+export declare interface CraftMobileBridge {
+  readonly platform: 'ios' | 'android'
+  readonly capabilities: Readonly<CraftMobileCapabilities>
+}
+export declare interface CraftReadyEvent extends Event {
+  detail?: { platform?: string }
+}
+/** Services retain their web fallbacks; nativeBridge describes only a native host. */
+export declare interface MobileApi {
+  readonly nativeBridge: CraftMobileBridge | null
+  biometrics: BiometricsApi
+  camera: CameraApi
+  device: DeviceApi
+  haptics: HapticsApi
+  lifecycle: LifecycleApi
+  location: LocationApi
+  notifications: NotificationsApi
+  permissions: PermissionsApi
+  secureStorage: SecureStorageApi
+  share: ShareApi
+  appReview: AppReviewApi
+  deepLinks: DeepLinksApi
+  keepAwake: KeepAwakeApi
+  network: NetworkApi
+  pushNotifications: PushNotificationsApi
+  health: HealthApi
+  liveActivities: LiveActivitiesApi
+  watchConnectivity: WatchConnectivityApi
+  isNativeMobile: () => boolean
+  onReady: (callback: (event: CraftReadyEvent) => void) => () => void
+  withFeedback: <T>(action: () => T | Promise<T>) => Promise<T>
+}
 export declare interface DeviceInfo {
   platform: 'ios' | 'android' | 'macos' | 'windows' | 'linux'
   osVersion: string

package/dist/index.js

@@ -1 +1 @@
-import*as p from"craft-native/mobile";var{biometrics:f,camera:A,device:u,haptics:l,lifecycle:v,location:h,notifications:w,permissions:m,secureStorage:d,share:y,appReview:k,deepLinks:n,keepAwake:x,network:L,pushNotifications:R,health:g,liveActivities:C,watchConnectivity:N}=p,b=f,S=A,c=u,o=l,E=v,H=h,P=w,D=m,T=d,M=y,B=k;function r(t){if(typeof t==="string")return t.trim()||null;if(!t||typeof t!=="object")return null;let e=t.url;return typeof e==="string"&&e.trim()?e:null}var K={async getInitialURL(){return r(await n.getInitialURL?.())},onLink(t){return n.onLink?.((e)=>{let i=r(e);if(i)t(i)})??(()=>{})}},U=x,W=L,F=R,I=g,j=C,q=N;function a(){if(typeof globalThis>"u")return;return globalThis}function z(){let t=a();return Boolean(t?.craft)&&c.isMobile()}function G(t){let e=a();if(!e)return()=>{};if(e.craft)return queueMicrotask(()=>t(new Event("craftReady"))),()=>{};let i=(s)=>t(s);return e.addEventListener("craftReady",i,{once:!0}),()=>e.removeEventListener("craftReady",i)}async function J(t){await o.impact("light");try{let e=await t();return await o.notification("success"),e}catch(e){throw await o.notification("error"),e}}var O={biometrics:b,camera:S,device:c,haptics:o,lifecycle:E,location:H,notifications:P,permissions:D,secureStorage:T,share:M,appReview:B,deepLinks:K,keepAwake:U,network:W,pushNotifications:F,health:I,liveActivities:j,watchConnectivity:q,isNativeMobile:z,onReady:G,withFeedback:J};export{B as appReview,b as biometrics,S as camera,K as deepLinks,c as device,o as haptics,I as health,z as isNativeMobile,U as keepAwake,E as lifecycle,j as liveActivities,H as location,O as mobile,W as network,r as normalizeDeepLinkURL,P as notifications,G as onMobileReady,D as permissions,F as pushNotifications,T as secureStorage,M as share,q as watchConnectivity,J as withNativeFeedback};
+import*as p from"craft-native/mobile";var{biometrics:f,camera:l,device:u,haptics:A,lifecycle:v,location:d,notifications:m,permissions:w,secureStorage:y,share:h,appReview:k,deepLinks:a,keepAwake:x,network:L,pushNotifications:b,health:g,liveActivities:R,watchConnectivity:C}=p,N=f,E=l,S=u,o=A,H=v,M=d,P=m,B=w,D=y,j=h,T=k;function c(t){if(typeof t==="string")return t.trim()||null;if(!t||typeof t!=="object")return null;let e=t.url;return typeof e==="string"&&e.trim()?e:null}var K={async getInitialURL(){return c(await a.getInitialURL?.())},onLink(t){return a.onLink?.((e)=>{let i=c(e);if(i)t(i)})??(()=>{})}},U=x,W=L,F=b,I=g,O=R,q=C;function s(){if(typeof window>"u")return;return window}function n(){let t=s()?.craft;if(!t||typeof t!=="object")return null;if(!("platform"in t)||t.platform!=="ios"&&t.platform!=="android")return null;let e="capabilities"in t?t.capabilities:void 0,i=e&&typeof e==="object"&&!Array.isArray(e)?Object.fromEntries(Object.entries(e).filter(([,r])=>typeof r==="boolean")):{};return{platform:t.platform,capabilities:i}}function z(){return n()!==null}function G(t){let e=s();if(!e)return()=>{};if(n()){let r=!1;return queueMicrotask(()=>{if(!r)t(new Event("craftReady"))}),()=>{r=!0}}let i=(r)=>{if(!n())return;e.removeEventListener("craftReady",i),t(r)};return e.addEventListener("craftReady",i),()=>e.removeEventListener("craftReady",i)}async function J(t){await o.impact("light");try{let e=await t();return await o.notification("success"),e}catch(e){throw await o.notification("error"),e}}var Q={get nativeBridge(){return n()},biometrics:N,camera:E,device:S,haptics:o,lifecycle:H,location:M,notifications:P,permissions:B,secureStorage:D,share:j,appReview:T,deepLinks:K,keepAwake:U,network:W,pushNotifications:F,health:I,liveActivities:O,watchConnectivity:q,isNativeMobile:z,onReady:G,withFeedback:J};export{T as appReview,N as biometrics,E as camera,K as deepLinks,S as device,n as getNativeMobileBridge,o as haptics,I as health,z as isNativeMobile,U as keepAwake,H as lifecycle,O as liveActivities,M as location,Q as mobile,W as network,c as normalizeDeepLinkURL,P as notifications,G as onMobileReady,B as permissions,F as pushNotifications,D as secureStorage,j as share,q as watchConnectivity,J as withNativeFeedback};

package/dist/types.d.ts

@@ -1,3 +1,81 @@
+/** Enabled native features, not the hardware report from device.getCapabilities(). */
+export declare interface CraftMobileCapabilities {
+  haptics?: boolean
+  speechRecognition?: boolean
+  share?: boolean
+  camera?: boolean
+  biometric?: boolean
+  pushNotifications?: boolean
+  secureStorage?: boolean
+  geolocation?: boolean
+  backgroundLocation?: boolean
+  healthKit?: boolean
+  health?: boolean
+  liveActivities?: boolean
+  watchConnectivity?: boolean
+  clipboard?: boolean
+  contacts?: boolean
+  calendar?: boolean
+  localNotifications?: boolean
+  inAppPurchase?: boolean
+  keepAwake?: boolean
+  orientationLock?: boolean
+  deepLinks?: boolean
+  flashlight?: boolean
+  network?: boolean
+  deviceInfo?: boolean
+  badge?: boolean
+  appReview?: boolean
+  appBadge?: boolean
+  networkStatus?: boolean
+  openURL?: boolean
+  vibrationPattern?: boolean
+  appState?: boolean
+  qrScanner?: boolean
+  filePicker?: boolean
+  fileDownload?: boolean
+  googleSignIn?: boolean
+  audioRecording?: boolean
+  videoRecording?: boolean
+  motionSensors?: boolean
+  localDatabase?: boolean
+  bluetooth?: boolean
+  nfc?: boolean
+  screenCapture?: boolean
+}
+/** Browser-safe metadata from Craft's iOS or Android bridge. */
+export declare interface CraftMobileBridge {
+  readonly platform: 'ios' | 'android'
+  readonly capabilities: Readonly<CraftMobileCapabilities>
+}
+export declare interface CraftReadyEvent extends Event {
+  detail?: { platform?: string }
+}
+/** Services retain their web fallbacks; nativeBridge describes only a native host. */
+export declare interface MobileApi {
+  readonly nativeBridge: CraftMobileBridge | null
+  biometrics: BiometricsApi
+  camera: CameraApi
+  device: DeviceApi
+  haptics: HapticsApi
+  lifecycle: LifecycleApi
+  location: LocationApi
+  notifications: NotificationsApi
+  permissions: PermissionsApi
+  secureStorage: SecureStorageApi
+  share: ShareApi
+  appReview: AppReviewApi
+  deepLinks: DeepLinksApi
+  keepAwake: KeepAwakeApi
+  network: NetworkApi
+  pushNotifications: PushNotificationsApi
+  health: HealthApi
+  liveActivities: LiveActivitiesApi
+  watchConnectivity: WatchConnectivityApi
+  isNativeMobile: () => boolean
+  onReady: (callback: (event: CraftReadyEvent) => void) => () => void
+  withFeedback: <T>(action: () => T | Promise<T>) => Promise<T>
+}
 export declare interface DeviceInfo {
   platform: 'ios' | 'android' | 'macos' | 'windows' | 'linux'
   osVersion: string

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/mobile",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.43",
+  "version": "0.74.45",
   "description": "Craft-powered native mobile runtime for Stacks and STX applications",
   "author": "Chris Breuer",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "craft-native": ">=0.0.72"
   },
   "devDependencies": {
-    "@stacksjs/build": "0.74.43",
+    "@stacksjs/build": "0.74.45",
     "better-dx": "^0.2.24"
   }
 }