@livx.cc/native-kit 0.16.0

package/src/modules/billing/http.ts

@@ -0,0 +1,28 @@
+/** Shared HTTP helper for the backend-driven billing strategies (validator + web provider). */
+
+export type HeaderProvider =
+  | Record<string, string>
+  | (() => Record<string, string> | Promise<Record<string, string>>);
+
+export interface HttpJsonOptions {
+  url: string;
+  method: 'GET' | 'POST';
+  body?: unknown;
+  headers?: HeaderProvider;
+  /** Injected for tests / non-DOM runtimes. Defaults to global `fetch`. */
+  fetch?: typeof fetch;
+}
+
+/** POST/GET JSON, throwing on non-2xx. Keeps validators + providers DRY. */
+export async function httpJson(opts: HttpJsonOptions): Promise<any> {
+  const f = opts.fetch ?? (globalThis as any).fetch;
+  if (!f) throw new Error('billing: no fetch available — pass one via options.fetch');
+  const h = typeof opts.headers === 'function' ? await opts.headers() : opts.headers;
+  const res = await f(opts.url, {
+    method: opts.method,
+    headers: { 'content-type': 'application/json', ...(h ?? {}) },
+    body: opts.method === 'POST' ? JSON.stringify(opts.body ?? {}) : undefined,
+  });
+  if (!res.ok) throw new Error(`billing: ${opts.method} ${opts.url} → ${res.status}`);
+  return res.json();
+}

package/src/modules/billing/providers.ts

@@ -0,0 +1,68 @@
+import { httpJson, type HeaderProvider } from './http';
+import type { BillingProvider, Entitlement, Product } from './types';
+
+export class HttpBillingProviderOptions {
+  /** Backend base URL exposing /products, /checkout, /entitlements, /portal. */
+  baseUrl = '';
+  /** Static headers or a thunk (e.g. a fresh session/bearer token). */
+  headers?: HeaderProvider;
+  /** Injected for tests / non-DOM runtimes. Defaults to global `fetch`. */
+  fetch?: typeof fetch;
+  /** How to send the user to a hosted checkout / portal URL. Defaults to a same-tab
+   *  navigation — override to open a tab, an in-app browser, etc. */
+  redirect: (url: string) => void = (url) => {
+    if (typeof window !== 'undefined') window.location.assign(url);
+  };
+  mapProducts: (json: any) => Product[] = (j) => (j?.products ?? j ?? []) as Product[];
+  mapEntitlements: (json: any) => Entitlement[] = (j) => (j?.entitlements ?? j ?? []) as Entitlement[];
+}
+
+/**
+ * Web checkout via your backend — the symmetric counterpart to the native store.
+ * `purchase()` POSTs to `/checkout`; if the backend returns a hosted-checkout `url`
+ * (Stripe Checkout Session, Paddle, LemonSqueezy…), it redirects and entitlements
+ * surface on the redirect back; if the backend returns `entitlements` inline, it
+ * resolves immediately. One config covers any "backend mints a checkout URL" provider.
+ * HTTP over SDK by design — no Stripe.js / vendor packages in the kit.
+ */
+export class HttpBillingProvider implements BillingProvider {
+  public options: HttpBillingProviderOptions;
+  constructor(options?: Partial<HttpBillingProviderOptions>) {
+    this.options = { ...new HttpBillingProviderOptions(), ...options };
+    if (!this.options.baseUrl) throw new Error('HttpBillingProvider: baseUrl is required');
+  }
+
+  async products(ids: string[]): Promise<Product[]> {
+    const url = `${this.base()}/products?ids=${encodeURIComponent(ids.join(','))}`;
+    return this.options.mapProducts(await httpJson({ ...this.req(), url, method: 'GET' }));
+  }
+
+  async purchase(productId: string): Promise<Entitlement[]> {
+    const json = await httpJson({ ...this.req(), url: `${this.base()}/checkout`, method: 'POST', body: { productId } });
+    if (json?.url) {
+      this.options.redirect(String(json.url)); // hosted checkout — page navigates away
+      return []; // entitlements arrive via entitlements() after redirect-back
+    }
+    return this.options.mapEntitlements(json); // backend completed inline
+  }
+
+  async entitlements(): Promise<Entitlement[]> {
+    return this.options.mapEntitlements(await httpJson({ ...this.req(), url: `${this.base()}/entitlements`, method: 'GET' }));
+  }
+
+  restore(): Promise<Entitlement[]> {
+    return this.entitlements(); // web has no store "restore" — re-read the server-of-record
+  }
+
+  async manageSubscriptions(): Promise<void> {
+    const json = await httpJson({ ...this.req(), url: `${this.base()}/portal`, method: 'POST', body: {} });
+    if (json?.url) this.options.redirect(String(json.url)); // Stripe Billing Portal, etc.
+  }
+
+  private base() {
+    return this.options.baseUrl.replace(/\/$/, '');
+  }
+  private req() {
+    return { headers: this.options.headers, fetch: this.options.fetch };
+  }
+}

package/src/modules/billing/types.ts

@@ -0,0 +1,93 @@
+/** Billing / IAP contract — platform-neutral shapes shared by the module,
+ *  the native handlers, and any pluggable validator (Bodify / RevenueCat / IAPHUB / custom). */
+
+export type ProductType =
+  | 'consumable'
+  | 'nonConsumable'
+  | 'autoRenewable'
+  | 'nonRenewable'
+  | 'unknown';
+
+/** A purchasable product as the store describes it (localized). */
+export interface Product {
+  id: string;
+  title: string;
+  description: string;
+  /** Numeric price in `currency`, for math/sorting. */
+  price: number;
+  /** Localized formatted price, e.g. "$4.99" — show this to users. */
+  displayPrice: string;
+  currency: string;
+  type: ProductType;
+  /** ISO-8601 duration for auto-renewables, e.g. "P1M", "P1Y". */
+  subscriptionPeriod?: string;
+}
+
+/** A normalized entitlement — "this user owns/subscribes to X". */
+export interface Entitlement {
+  productId: string;
+  active: boolean;
+  /** Epoch ms; subscriptions only. */
+  expiresAt?: number;
+  /** Whether an auto-renewable will renew at period end. */
+  willRenew?: boolean;
+  /** Epoch ms of the original purchase. */
+  purchasedAt?: number;
+}
+
+/** The raw proof of a purchase, handed to the validator. Platform-specific fields
+ *  are optional so one shape serves both stores AND a web checkout. */
+export interface PurchaseReceipt {
+  platform: 'ios' | 'android' | 'web';
+  productId: string;
+  transactionId?: string;
+  /** StoreKit 2 signed transaction (JWS) — verify against Apple's root certs. */
+  jws?: string;
+  /** Base64 StoreKit 1 app receipt — verify via App Store Server API / verifyReceipt. */
+  appReceipt?: string;
+  /** Google Play Billing purchase token — verify via Play Developer API. */
+  purchaseToken?: string;
+  /** Web checkout reference (e.g. Stripe Checkout Session / subscription id). */
+  providerRef?: string;
+  /** The untouched native/provider payload, for validators that want everything. */
+  raw: unknown;
+}
+
+export interface PurchaseResult {
+  receipt: PurchaseReceipt;
+  entitlements: Entitlement[];
+}
+
+/**
+ * The swappable seam. The kit owns the on-device purchase flow; *who decides the
+ * user is actually entitled* is up to the app. Implement this (or configure the
+ * bundled `HttpValidator`) to point at Bodify, RevenueCat, IAPHUB, or your own backend.
+ */
+export interface BillingValidator {
+  /** Validate a fresh purchase/restore receipt → the entitlements it grants. */
+  validate(receipt: PurchaseReceipt): Promise<Entitlement[]>;
+  /** Current entitlements from the server-of-record (or the device, for client-trusted). */
+  entitlements(): Promise<Entitlement[]>;
+}
+
+/**
+ * The *purchase mechanism* on web — the symmetric counterpart to the native store.
+ * On mobile the kit drives StoreKit/Play directly; on web there is no native store,
+ * so the app plugs in a provider (Stripe / Paddle / LemonSqueezy / custom backend).
+ * The same `kit.billing.*` calls dispatch here when running on the web. Implement this,
+ * or configure the bundled `HttpBillingProvider` (backend-driven hosted checkout).
+ */
+export interface BillingProvider {
+  /** Catalog with localized prices (typically from your backend / Stripe prices). */
+  products(ids: string[]): Promise<Product[]>;
+  /** Start checkout for a product. Resolves to the granted entitlements when known
+   *  synchronously; for redirect-based checkout (Stripe hosted page) it navigates away
+   *  and the entitlements surface via `entitlements()` after the redirect back. */
+  purchase(productId: string): Promise<Entitlement[]>;
+  /** Current entitlements from the server-of-record (Stripe webhooks → your backend). */
+  entitlements(): Promise<Entitlement[]>;
+  /** Re-sync entitlements (web has no "restore" — defaults to `entitlements()`). */
+  restore?(): Promise<Entitlement[]>;
+  /** Open the billing/subscription-management surface (e.g. Stripe Billing Portal). */
+  manageSubscriptions?(): Promise<void>;
+}

package/src/modules/billing/validators.ts

@@ -0,0 +1,66 @@
+import { httpJson, type HeaderProvider } from './http';
+import type { BillingValidator, Entitlement, PurchaseReceipt } from './types';
+
+export type { HeaderProvider } from './http';
+
+/**
+ * Trusts the device. `validate` marks the purchased product active; `entitlements`
+ * reads whatever the native layer reports (StoreKit `currentEntitlements` /
+ * Play `queryPurchases`). Zero backend — spoofable on a compromised device, so
+ * fine for demos/dev or low-stakes unlocks, NOT for real revenue. The default.
+ */
+export class ClientTrustedValidator implements BillingValidator {
+  constructor(private readNative: () => Promise<Entitlement[]>) {}
+
+  async validate(receipt: PurchaseReceipt): Promise<Entitlement[]> {
+    // The native purchase already succeeded — grant that product directly. Do NOT
+    // read native entitlements here: on StoreKit 1 that means a restore, which pops
+    // an Apple ID prompt right after a buy. Call entitlements() explicitly for that.
+    return [{ productId: receipt.productId, active: true, purchasedAt: Date.now() }];
+  }
+
+  entitlements(): Promise<Entitlement[]> {
+    return this.readNative();
+  }
+}
+
+export class HttpValidatorOptions {
+  /** POST endpoint that receives a `PurchaseReceipt` and returns entitlements. */
+  validateUrl = '';
+  /** GET/POST endpoint for the current entitlements. Defaults to `validateUrl`. */
+  entitlementsUrl?: string;
+  /** Static headers or a thunk (e.g. to inject a fresh bearer token). */
+  headers?: HeaderProvider;
+  /** Map the provider's response JSON → `Entitlement[]`. Default expects `{ entitlements: [...] }`. */
+  mapResponse: (json: any) => Entitlement[] = (j) => (j?.entitlements ?? []) as Entitlement[];
+  /** Injected for tests / non-DOM runtimes. Defaults to global `fetch`. */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Generic server-validated strategy. One implementation covers Bodify, RevenueCat,
+ * IAPHUB, or any custom backend — they differ only by URL, auth header, and a small
+ * response mapper. HTTP over SDK by design (no vendor packages).
+ */
+export class HttpValidator implements BillingValidator {
+  public options: HttpValidatorOptions;
+  constructor(options?: Partial<HttpValidatorOptions>) {
+    this.options = { ...new HttpValidatorOptions(), ...options };
+    if (!this.options.validateUrl) throw new Error('HttpValidator: validateUrl is required');
+  }
+
+  async validate(receipt: PurchaseReceipt): Promise<Entitlement[]> {
+    const json = await httpJson({ ...this.req(), url: this.options.validateUrl, method: 'POST', body: receipt });
+    return this.options.mapResponse(json);
+  }
+
+  async entitlements(): Promise<Entitlement[]> {
+    const url = this.options.entitlementsUrl ?? this.options.validateUrl;
+    const method = this.options.entitlementsUrl ? 'GET' : 'POST';
+    return this.options.mapResponse(await httpJson({ ...this.req(), url, method }));
+  }
+
+  private req() {
+    return { headers: this.options.headers, fetch: this.options.fetch };
+  }
+}

package/src/modules/biometrics.ts

@@ -0,0 +1,19 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export class BiometricsModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('biometrics');
+  }
+
+  /** { available, type: 'face' | 'touch' | 'none' } */
+  available(): Promise<{ available: boolean; type: string }> {
+    return this.kit.invoke('biometrics.available');
+  }
+
+  /** Resolves { success } — rejects with DENIED on user cancel/failure. */
+  authenticate(reason: string): Promise<{ success: boolean }> {
+    return this.kit.invoke('biometrics.authenticate', { reason }, { timeoutMs: 60_000 });
+  }
+}

package/src/modules/browser.ts

@@ -0,0 +1,22 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export interface BrowserOptions {
+  /** Tint for the in-app browser chrome (hex, e.g. "#4b0082").
+   * iOS → SFSafariViewController.preferredControlTintColor; Android → toolbar color. */
+  toolbarColor?: string;
+}
+
+/** In-app browser: iOS SFSafariViewController, Android Chrome Custom Tabs, web new tab.
+ * Keeps the user inside the app (vs `app.openUrl`, which leaves for the OS handler). */
+export class BrowserModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('browser');
+  }
+
+  /** Present an in-app browser for the URL. Resolves once it has been presented. */
+  open(url: string, opts: BrowserOptions = {}): Promise<void> {
+    return this.kit.invoke('browser.open', { url, ...opts });
+  }
+}

package/src/modules/calendar.ts

@@ -0,0 +1,23 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export interface CalendarEventOptions {
+  title: string;
+  /** ISO datetime; defaults to now + 1h. */
+  start?: string;
+  durationMin?: number;
+  notes?: string;
+}
+
+/** Calendar write — native: EventKit (requires `calendar` permission in appwrap.json). Web: 'none'. */
+export class CalendarModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('calendar');
+  }
+
+  /** Create an event in the default calendar; resolves its identifier. */
+  createEvent(opts: CalendarEventOptions): Promise<{ id: string }> {
+    return this.kit.invoke('calendar.createEvent', opts, { timeoutMs: 120_000 });
+  }
+}

package/src/modules/clipboard.ts

@@ -0,0 +1,17 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export class ClipboardModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('clipboard');
+  }
+
+  copy(text: string): Promise<void> {
+    return this.kit.invoke('clipboard.copy', { text });
+  }
+
+  read(): Promise<string | null> {
+    return this.kit.invoke('clipboard.read');
+  }
+}

package/src/modules/contacts.ts

@@ -0,0 +1,22 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export interface PickedContact {
+  picked: boolean;
+  name?: string;
+  phones?: string[];
+  emails?: string[];
+}
+
+/** Contact picker — native: CNContactPicker (no permission needed); web: Contact Picker API where present. */
+export class ContactsModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('contacts');
+  }
+
+  /** Open the system contact picker; resolves { picked: false } when dismissed. */
+  pick(): Promise<PickedContact> {
+    return this.kit.invoke('contacts.pick', undefined, { timeoutMs: 120_000 });
+  }
+}

package/src/modules/device.ts

@@ -0,0 +1,23 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export interface DeviceInfo {
+  model: string;
+  os: string;
+  osVersion: string;
+  language: string;
+  region?: string;
+  manufacturer?: string;
+  battery?: { level: number; charging: boolean };
+}
+
+export class DeviceModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('device');
+  }
+
+  info(): Promise<DeviceInfo> {
+    return this.kit.invoke('device.info');
+  }
+}

package/src/modules/geo.ts

@@ -0,0 +1,41 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+export interface GeoPosition {
+  lat: number;
+  lng: number;
+  accuracy?: number;
+}
+
+export class GeoModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('geo');
+  }
+
+  /** Requests permission on first use. */
+  current(): Promise<GeoPosition> {
+    return this.kit.invoke('geo.current', undefined, { timeoutMs: 60_000 });
+  }
+
+  /** Stream position updates; resolves an unsubscribe once the watch is running. */
+  async watch(cb: (pos: GeoPosition) => void): Promise<Unsubscribe> {
+    const off = this.kit.on('geo.position', (p) => cb(p as GeoPosition));
+    try {
+      await this.kit.invoke('geo.watch.start', undefined, { timeoutMs: 60_000 });
+    } catch (e) {
+      off();
+      throw e;
+    }
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      off();
+      this.kit
+        .invoke('geo.watch.stop')
+        .catch((e) => console.warn('[native-kit] geo.watch.stop failed', e));
+    };
+  }
+}

package/src/modules/haptics.ts

@@ -0,0 +1,20 @@
+import type { NativeKit } from '../core/NativeKit';
+
+export type ImpactStyle = 'light' | 'medium' | 'heavy' | 'soft' | 'rigid';
+export type NotifyType = 'success' | 'warning' | 'error';
+
+export class HapticsModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('haptics');
+  }
+
+  impact(style: ImpactStyle = 'medium'): Promise<void> {
+    return this.kit.invoke('haptics.impact', { style });
+  }
+
+  notify(type: NotifyType): Promise<void> {
+    return this.kit.invoke('haptics.notify', { type });
+  }
+}

package/src/modules/health.ts

@@ -0,0 +1,70 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+/**
+ * Step counting. `count()` returns the day's step total; foreground updates come from polling it,
+ * and background/while-killed steps are included automatically (the OS records them — no live JS
+ * runs while suspended). Opt-in module — enable with `"modules": ["health"]` in appwrap.json.
+ *
+ * Platform reach:
+ *  - **iOS** (HealthKit): today's total from the Health app — aggregates iPhone + Apple Watch + other
+ *    sources, recorded by the OS regardless of the app, so it's global and survives an app kill. No
+ *    `start()` needed. Requires the `com.apple.developer.healthkit` entitlement + `requestAccess()`.
+ *  - **Android** (Health Connect): today's total from the system store — Wear-inclusive, survives a
+ *    kill, mirrors iOS. Needs the `READ_STEPS` permission (granted via `requestAccess()`). Falls back
+ *    to the `TYPE_STEP_COUNTER` sensor (since `start()`, no kill-survival) when Health Connect isn't
+ *    installed.
+ */
+export class HealthModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('health');
+  }
+
+  /** Trigger the OS permission prompt (iOS motion usage · Android ACTIVITY_RECOGNITION).
+   * Interactive — generous timeout so it waits for the user to respond to the prompt. */
+  requestAccess(): Promise<boolean> {
+    return this.kit.invoke<boolean>('health.requestAccess', undefined, { timeoutMs: 60_000 });
+  }
+
+  /** Begin counting. Required on Android (registers the sensor listener); a no-op availability
+   * check on iOS (which reads history and needs no session). */
+  start(): Promise<void> {
+    return this.kit.invoke<void>('health.start');
+  }
+
+  /** End the counting session (Android: unregisters the listener). */
+  stop(): Promise<void> {
+    return this.kit.invoke<void>('health.stop');
+  }
+
+  /** The day's step count from the platform health store — iOS HealthKit / Android Health Connect
+   * (both Wear-inclusive, survive a kill). Android falls back to the step sensor (since `start()`). */
+  async count(): Promise<number> {
+    const r = await this.kit.invoke<{ steps: number }>('health.count');
+    return r?.steps ?? 0;
+  }
+
+  /** Start a session and stream the live count (foreground) by polling every `intervalMs`.
+   * Resolves an unsubscribe that stops both the poll and the session. */
+  async watch(cb: (steps: number) => void, intervalMs = 2000): Promise<Unsubscribe> {
+    await this.start();
+    const tick = async () => {
+      try {
+        cb(await this.count());
+      } catch (e) {
+        console.warn('[native-kit] health.count failed', e);
+      }
+    };
+    await tick();
+    const id = setInterval(tick, intervalMs);
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(id);
+      this.stop().catch((e) => console.warn('[native-kit] health.stop failed', e));
+    };
+  }
+}

package/src/modules/lifecycle.ts

@@ -0,0 +1,23 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+/**
+ * App lifecycle + deep links — pure event surface.
+ * Native: shell emits on suspend/resume and on URL-scheme opens.
+ * Web: visibilitychange maps to pause/resume; deep links never fire.
+ */
+export class LifecycleModule {
+  constructor(private kit: NativeKit) {}
+
+  onPause(cb: () => void): Unsubscribe {
+    return this.kit.on('app.pause', () => cb());
+  }
+
+  onResume(cb: () => void): Unsubscribe {
+    return this.kit.on('app.resume', () => cb());
+  }
+
+  onDeepLink(cb: (url: string) => void): Unsubscribe {
+    return this.kit.on('deeplink.open', (p) => cb((p as { url: string }).url));
+  }
+}

package/src/modules/media.ts

@@ -0,0 +1,75 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/**
+ * Live media bridge — mic / camera / speaker. The streams themselves are plain
+ * web APIs (getUserMedia / MediaRecorder / WebAudio); the native shell's job is
+ * to *unlock* them: grant the WebView's per-origin capture permission and route
+ * audio sensibly. This module is the single import surface + capability gate,
+ * plus `configureAudio()` which tunes the native audio session (iOS).
+ */
+export type AudioMode = 'playback' | 'playAndRecord' | 'voiceChat' | 'default';
+
+export interface MediaDeviceLite {
+  kind: MediaDeviceKind;
+  label: string;
+  deviceId: string;
+}
+
+export class MediaModule {
+  constructor(private kit: NativeKit) {}
+
+  /** 'native' (shell grants capture) | 'web' (browser handles it) | 'none'. */
+  get capability() {
+    return this.kit.capability('media');
+  }
+
+  /** True only in a secure context with a usable mediaDevices implementation. */
+  get available(): boolean {
+    return typeof navigator !== 'undefined' && !!navigator.mediaDevices?.getUserMedia;
+  }
+
+  /**
+   * Pre-establish the OS mic/camera permission so the WebView's getUserMedia
+   * doesn't re-prompt on every call (a WKWebView artifact). Native shells prompt
+   * once via the OS and cache it; no-op on web. Called automatically by
+   * {@link getUserMedia}, but exposed for warming the grant up front.
+   */
+  ensurePermission(opts: { audio?: boolean; video?: boolean }): Promise<{ audio?: string; video?: string }> {
+    if (this.capability !== 'native') return Promise.resolve({});
+    return this.kit.invoke('media.ensurePermission', opts);
+  }
+
+  /** Thin wrapper over getUserMedia — same constraints, with an availability guard. */
+  async getUserMedia(constraints: MediaStreamConstraints): Promise<MediaStream> {
+    if (!this.available) {
+      throw Object.assign(new Error('getUserMedia unavailable (insecure context?)'), { code: 'UNSUPPORTED' });
+    }
+    // Native: secure the persistent OS grant first so the WebView prompts once, like native.
+    await this.ensurePermission({ audio: !!constraints.audio, video: !!constraints.video }).catch(() => {});
+    return navigator.mediaDevices.getUserMedia(constraints);
+  }
+
+  /** Enumerate input/output devices (labels populate only after a grant). */
+  async devices(): Promise<MediaDeviceLite[]> {
+    if (!navigator.mediaDevices?.enumerateDevices) return [];
+    const list = await navigator.mediaDevices.enumerateDevices();
+    return list.map((d) => ({ kind: d.kind, label: d.label, deviceId: d.deviceId }));
+  }
+
+  /**
+   * Tune the native audio session. 'playback' = loud, ignores the iOS silent
+   * switch (media apps); 'playAndRecord' = mic + speaker for calls; 'voiceChat'
+   * = full-duplex voice with hardware acoustic echo cancellation (AEC) — use
+   * this for live voice agents so TTS playback doesn't bleed into the mic / STT.
+   * No-op where the platform needs no session config (Android, web).
+   */
+  configureAudio(mode: AudioMode = 'playback'): Promise<void> {
+    if (this.capability !== 'native') return Promise.resolve();
+    return this.kit.invoke('media.configureAudio', { mode });
+  }
+
+  /** 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

@@ -0,0 +1,41 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+export interface MotionSample {
+  /** Acceleration incl. gravity, m/s². */
+  ax: number;
+  ay: number;
+  az: number;
+  /** Rotation rate, rad/s (absent when no gyro). */
+  rx?: number;
+  ry?: number;
+  rz?: number;
+}
+
+export class MotionModule {
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('motion');
+  }
+
+  /** Stream motion samples (~10Hz); resolves an unsubscribe once streaming starts. */
+  async watch(cb: (sample: MotionSample) => void): Promise<Unsubscribe> {
+    const off = this.kit.on('motion.data', (p) => cb(p as MotionSample));
+    try {
+      await this.kit.invoke('motion.start');
+    } catch (e) {
+      off();
+      throw e;
+    }
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      off();
+      this.kit
+        .invoke('motion.stop')
+        .catch((e) => console.warn('[native-kit] motion.stop failed', e));
+    };
+  }
+}