@livx.cc/appwrap 0.54.0 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",
@@ -32,7 +32,9 @@
     "./config": "./src/config.ts",
     "./handlers": "./src/handlers.ts",
     "./plugin": "./src/plugin/index.ts",
-    "./cli": "./src/cli.ts"
+    "./cli": "./src/cli.ts",
+    "./testing": "./src/testing.ts",
+    "./runtime/*": "./runtime/*.ts"
   },
   "files": [
     "src",

package/runtime/app/main-page.ts

@@ -5,7 +5,6 @@ import { registerHandlers } from './shell/handlers';
 import { registerExtendedHandlers } from './shell/handlers-extended';
 import { registerParityHandlers } from './shell/handlers-parity';
 import { registerSystemHandlers } from './shell/handlers-system';
-import { registerBillingHandlers } from './shell/handlers-billing';
 import { registerMediaHandlers } from './shell/handlers-media';
 import { registerKeyboardHandlers } from './shell/keyboard';
 import { registerFsHandlers } from './shell/handlers-fs';
@@ -100,7 +99,6 @@ export function onPageLoaded(args: EventData): void {
   registerExtendedHandlers();
   registerParityHandlers();
   registerSystemHandlers();
-  registerBillingHandlers();
   registerMediaHandlers();
   registerKeyboardHandlers();
   registerFsHandlers();

package/runtime/app/shell/capabilities.manifest.ts

@@ -61,8 +61,19 @@ export interface ModuleManifest {
    * App_Resources layout, copied into `native/` ONLY when the module is active (stays strippable).
    * Defaults to the module `name` when the convention dir exists. */
   nativeSrc?: string;
+  /** Build-time registration wiring for a module contributed by an OUT-OF-REPO pack (see packs.ts).
+   * Built-in modules leave this undefined — their handler barrel wiring comes from cli.ts's
+   * OPTIONAL_GROUP_HANDLERS (keyed by `group`). A pack module is self-describing: `file` is the
+   * handler module relative to the pack dir, `fn` the exported register function the shell barrel
+   * calls at page load. Runtime ignores this field (pure build-time metadata). */
+  handler?: { file: string; fn: string };
 }
 
+/** Manifest schema version the built-in modules speak. A module pack (packs.ts) declares the version
+ * it targets; a mismatch is rejected at resolve time (loud) rather than silently mis-derived. Bump
+ * this only on a breaking change to the `ModuleManifest` shape the CLI's derivation depends on. */
+export const MANIFEST_SCHEMA_VERSION = 1;
+
 export const MODULES: ModuleManifest[] = [
   // ── core (always on, no permissions) ───────────────────────────────────
   { name: 'haptics', core: true, group: 'core', capabilities: { haptics: 'native' } },
@@ -148,19 +159,6 @@ export const MODULES: ModuleManifest[] = [
     ] },
     android: { permissions: ['android.permission.READ_CALENDAR', 'android.permission.WRITE_CALENDAR'] },
   },
-  {
-    name: 'billing', group: 'billing',
-    capabilities: { billing: { ios: true, android: true } },
-    // iOS: Swift shim (AppwrapManageSubscriptions.swift) bridging StoreKit 2's Swift-async
-    // showManageSubscriptions(in:) to an @objc completion the ObjC bridge can call. Compiled into
-    // the app target only when `billing` is active (NS auto-compiles App_Resources/iOS/src/*.swift).
-    // Android: Play Billing Library v7 (handlers-billing.ts registerAndroidBilling). The BILLING
-    // permission is auto-merged by the library's own manifest, so no android.permissions entry —
-    // only the gradle dep is needed, and it lands ONLY when `billing` is active (strippable weight).
-    android: { gradleDeps: ['com.android.billingclient:billing:7.1.1'] },
-    nativeSrc: 'billing',
-  },
-
   // ── reviews — in-app store review prompt — opt-in, STRIPPABLE (own handler + group) ──
   // Moved out of the always-bundled parity/system handlers: the Android Play In-App Review path
   // references `com.google.android.play:review` classes — a gradle dep that must NOT land in builds
@@ -221,53 +219,6 @@ export const MODULES: ModuleManifest[] = [
     android: { permissions: ['android.permission.RECORD_AUDIO'] },
   },
 
-  // ── health (steps) — opt-in heavy module; FG live + BG via OS step store ──
-  {
-    name: 'health', group: 'health',
-    capabilities: { health: 'native' },
-    // iOS reads HealthKit (the Health app's aggregated total incl. Apple Watch): health-share usage
-    // string + the healthkit entitlement, both module-owned. No background execution — HealthKit
-    // already has the steps the OS recorded while the app was killed.
-    ios: {
-      // App Store validation REQUIRES both Share AND Update purpose strings whenever the HealthKit
-      // entitlement is present — even for a read-only app (else upload fails 409 "Missing purpose
-      // string … NSHealthUpdateUsageDescription"). Device debug builds don't validate this; only the
-      // App Store upload does.
-      permissions: [
-        { key: 'NSHealthShareUsageDescription', domain: 'health', defaultUsage: 'Read your step count from the Health app.' },
-        { key: 'NSHealthUpdateUsageDescription', domain: 'health', defaultUsage: 'Read your step count from the Health app.' },
-        // Live step stream (health.liveSteps) uses CMPedometer (CoreMotion) → iOS terminates the app
-        // on access without this Motion & Fitness usage string. Required for the real-time count.
-        { key: 'NSMotionUsageDescription', domain: 'motion', defaultUsage: 'Count your steps live as you walk.' },
-      ],
-      entitlements: { 'com.apple.developer.healthkit': true },
-    },
-    // Android primary = Health Connect (system store, Wear-inclusive, survives kill — matches iOS).
-    // Its client is Kotlin-coroutine-only, so the module ships HealthConnectBridge.kt (nativeSrc) and
-    // flags kotlin:true. Falls back to SensorManager TYPE_STEP_COUNTER (ACTIVITY_RECOGNITION) when HC absent.
-    android: {
-      permissions: ['android.permission.health.READ_STEPS', 'android.permission.ACTIVITY_RECOGNITION'],
-      gradleDeps: [
-        'androidx.health.connect:connect-client:1.1.0-rc01',
-        'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0',
-      ],
-      kotlin: true,
-      // Health Connect refuses to honor permissions unless the app declares a rationale activity
-      // handling VIEW_PERMISSION_USAGE / HEALTH_PERMISSIONS (alias onto the NS main activity).
-      manifestApplication: `<activity-alias
-      android:name="ViewPermissionUsageActivity"
-      android:exported="true"
-      android:targetActivity="com.tns.NativeScriptActivity"
-      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
-      <intent-filter>
-        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
-        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
-      </intent-filter>
-    </activity-alias>`,
-    },
-    nativeSrc: 'health',
-  },
-
   // ── tracking — App Tracking Transparency (iOS) — opt-in, STRIPPABLE (own handler + group) ──
   // The native-only store-compliance seam for cross-company tracking (IDFA / cross-app identity):
   // Apple REQUIRES the ATT prompt + NSUserTrackingUsageDescription and forbids tracking before
@@ -321,46 +272,30 @@ export const MODULES: ModuleManifest[] = [
     android: { gradleDeps: ['androidx.work:work-runtime:2.9.1', 'com.google.guava:guava:33.3.1-android'] },
   },
 
-  // ── widget — home-screen presence via a native extension (iOS WidgetKit / Android AppWidget) ──
-  // 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 } },
-    // 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',
-  },
+  // NOTE: billing, health, and widget were EXTRACTED into appwrap-ee module packs
+  // (packages/ee/packs/{billing,health,widget}); a consumer opts in via `modulePacks`.
 ];
 
 /** Opt-in registration groups that own their own NS handler file (strippable when inactive). Core
- * groups (core/extended/parity/system/media/billing) are always bundled; only these are CLI-gated. */
-export const OPTIONAL_GROUPS = ['health', 'oauth', 'reviews', 'scanner', 'speech', 'tracking', 'appleSignIn', 'backgroundTask', 'widget'] as const;
+ * groups (core/extended/parity/system/media) are always bundled; only these are CLI-gated. */
+export const OPTIONAL_GROUPS = ['oauth', 'reviews', 'scanner', 'speech', 'tracking', 'appleSignIn', 'backgroundTask'] as const;
+
+/** CLI-gated groups (strippable in explicit mode) that legacy mode (no `modules` key) STILL auto-bundles
+ * for back-compat. Empty now that billing (its only member) moved to an appwrap-ee pack — kept as the
+ * seam so the carve-out can be reinstated without touching cli.ts if a future built-in needs it. */
+export const LEGACY_BUNDLED_GROUPS = [] as const;
 
-/** Resolve the active capability map for the handshake from a set of active capability names. */
+/** Resolve the active capability map for the handshake from a set of active capability names. Pack
+ * modules (from the config's `modulePacks`) aren't in the static MODULES, so their handshake-relevant
+ * subset is passed in via `extraModules` (generated into active-modules.generated.ts) and merged — a
+ * pack capability is advertised exactly like a built-in one. Empty for a pack-less build. */
 export function buildCapabilityMap(
   activeNames: Set<string>,
-  platform: 'ios' | 'android'
+  platform: 'ios' | 'android',
+  extraModules: ReadonlyArray<Pick<ModuleManifest, 'name' | 'core' | 'capabilities' | 'group'>> = []
 ): Record<string, 'native' | 'none'> {
   const map: Record<string, 'native' | 'none'> = {};
-  for (const m of MODULES) {
+  for (const m of [...MODULES, ...extraModules]) {
     if (!m.core && !activeNames.has(m.name)) continue;
     for (const [cap, val] of Object.entries(m.capabilities)) {
       if (val === 'native') map[cap] = 'native';

package/runtime/app/shell/config.ts

@@ -29,6 +29,10 @@ export const SHELL_CONFIG = {
   /** Absolute backend origin for an offline (app://) PWA whose API/WS calls were originally same-origin.
    * Injected to the page as `window.__APPWRAP_BACKEND_ORIGIN__`; empty = same-origin (browser default). */
   backendOrigin: '',
+  /** The app's own custom URL scheme (`appwrap.json.urlScheme`), the one registered for deep links.
+   * Surfaced to the page as `window.__APPWRAP__.scheme` so a webapp can build its own deep-link URLs;
+   * empty = no scheme configured, and the `scheme` key is OMITTED from `__APPWRAP__` (see `detectEnv`). */
+  urlScheme: '' as string,
   /** Debug/dev mode: keep the screen awake (no auto-lock while foreground) + WebView inspectable
    * (Safari Web Inspector / chrome://inspect). Set true by `appwrap deploy`; never in store builds. */
   debug: false,

package/runtime/app/shell/env.ts

@@ -1,4 +1,5 @@
 import { Application, isAndroid } from '@nativescript/core';
+import { SHELL_CONFIG } from './config';
 
 /**
  * Runtime environment hints the page can't reliably detect itself, surfaced natively so a PWA can
@@ -10,18 +11,24 @@ import { Application, isAndroid } from '@nativescript/core';
  *                  cap DPR / disable heavy backgrounds when set.
  *  • reduceMotion— the OS "reduce motion" accessibility setting is on. Apps should disable non-essential
  *                  animation (mirrors the `prefers-reduced-motion` media query, but works pre-paint).
+ *  • scheme      — the app's own custom URL scheme (from `SHELL_CONFIG.urlScheme`), so a webapp inside the
+ *                  shell can build its own deep-link URLs. OMITTED when no urlScheme is configured.
  */
 export interface AppwrapEnv {
   native: boolean;
   platform: 'android' | 'ios';
   isEmulator: boolean;
   reduceMotion: boolean;
+  scheme?: string;
 }
 
 export function detectEnv(): AppwrapEnv {
-  return isAndroid
+  const base: AppwrapEnv = isAndroid
     ? { native: true, platform: 'android', isEmulator: androidIsEmulator(), reduceMotion: androidReduceMotion() }
     : { native: true, platform: 'ios', isEmulator: iosIsSimulator(), reduceMotion: iosReduceMotion() };
+  // Only surface `scheme` when configured — contract requires the key ABSENT for an empty urlScheme.
+  if (SHELL_CONFIG.urlScheme) base.scheme = SHELL_CONFIG.urlScheme;
+  return base;
 }
 
 /** Document-start snippet: merge the detected hints onto `window.__APPWRAP__` (idempotent). */

package/runtime/app/shell/handlers.ts

@@ -6,7 +6,7 @@ import { showToast } from './toast';
 import { showBanner, dismissBanner } from './banner';
 import { setStatusBarStyle } from './status-bar';
 import { buildCapabilityMap } from './capabilities.manifest';
-import { ACTIVE_MODULE_NAMES } from './active-modules.generated';
+import { ACTIVE_MODULE_NAMES, PACK_MODULES } from './active-modules.generated';
 import { consumePendingBackgroundTaskId } from './background-context';
 
 /** Build identifier for the native shell bundle — bump per deploy to spot stale bundles. */
@@ -26,7 +26,7 @@ export function registerHandlers(): void {
     // Capability map is composed from the active module set (appwrap.json `modules` → the generated
     // ACTIVE_MODULE_NAMES) + the always-on core, deduped. Opt-out capabilities report 'none' so the
     // kit degrades gracefully. Push is special — gated by per-platform build config, not the manifest.
-    const capabilities = buildCapabilityMap(new Set(ACTIVE_MODULE_NAMES), isIOS ? 'ios' : 'android') as Record<string, 'native' | 'none'>;
+    const capabilities = buildCapabilityMap(new Set(ACTIVE_MODULE_NAMES), isIOS ? 'ios' : 'android', PACK_MODULES) as Record<string, 'native' | 'none'>;
     capabilities.push = (isIOS ? SHELL_CONFIG.pushIos : SHELL_CONFIG.pushAndroid) ? 'native' : 'none';
     // Background launch: the headless runner (handlers-background) set the wake id before loading this
     // (offscreen) WebView. Report it so `kit.backgroundTask` dispatches the registered handler. Consumed

package/runtime/tests/env-scheme.test.ts

@@ -0,0 +1,44 @@
+/**
+ * `detectEnv()` / `envGlobalsJs()` surface the app's own custom URL scheme to the page as
+ * `window.__APPWRAP__.scheme`. Contract: the key is present ONLY when `SHELL_CONFIG.urlScheme` is set,
+ * and OMITTED (not `scheme:""`/undefined) when empty — for BOTH android and ios.
+ */
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+
+// isAndroid is a getter over a mutable flag so both platform branches are exercised. Superset the
+// named exports env.ts reaches (Application is only touched on the android branch's reduce-motion path,
+// which throws-and-falls-back off-device — safe to stub minimally).
+let androidFlag = false;
+mock.module('@nativescript/core', () => ({
+  Application: { android: {} },
+  get isAndroid() { return androidFlag; },
+  isIOS: false,
+  WebView: class {},
+}));
+
+// Dynamic import AFTER mock.module so the stub is registered before env.ts pulls @nativescript/core
+// (static imports hoist above mock.module and would load the real native module).
+const { SHELL_CONFIG } = await import('../app/shell/config');
+const { detectEnv, envGlobalsJs } = await import('../app/shell/env');
+
+afterEach(() => { SHELL_CONFIG.urlScheme = ''; });
+
+for (const platform of ['android', 'ios'] as const) {
+  describe(`scheme surfacing — ${platform}`, () => {
+    test('INCLUDES scheme when urlScheme is set', () => {
+      androidFlag = platform === 'android';
+      SHELL_CONFIG.urlScheme = 'demoapp';
+      expect(detectEnv().scheme).toBe('demoapp');
+      expect(envGlobalsJs()).toContain('"scheme":"demoapp"');
+    });
+
+    test('OMITS the scheme key when urlScheme is empty', () => {
+      androidFlag = platform === 'android';
+      SHELL_CONFIG.urlScheme = '';
+      const env = detectEnv();
+      expect('scheme' in env).toBe(false);
+      // The injected snippet must carry no `scheme` key at all (not scheme:"" / scheme:undefined).
+      expect(envGlobalsJs()).not.toContain('scheme');
+    });
+  });
+}