anchordb-lens-link 1.3.0 → 1.3.2

package/README.md

@@ -3,6 +3,8 @@
 **Open a QA build's AnchorDB database in Anchor Lens, on the same Android phone, from a file.** No
 laptop, no relay, no pairing code.
 
+**[Overview](https://www.nisalanadeera.com/projects/anchordb)** · **[Report a bug or get support](https://www.nisalanadeera.com/projects/anchordb#feedback)**
+
 ```bash
 npm install anchordb-lens-link
 ```
@@ -41,6 +43,42 @@ Lens opens the app's database live. Edits in either app show up in the other.
 The file is rewritten on every launch, because the port and the secret change. It works only while the
 app is running; if Lens says the app closed, open the app and pick the file again.
 
+## Staying alive in the background
+
+Android stops apps in the background to save power, and some phones — Xiaomi's especially — do it
+within seconds of switching away. So while the link is on, the app runs an Android **foreground
+service** with an ongoing notification (*Anchor Lens Link on*, then *Anchor Lens connected*), which is
+what Android lets an app use to keep running. Anchor Lens does the same while it is connected, so you
+can switch between the two.
+
+It starts with the link, so call `enableLensLink` while the app is on screen: Android 12 and later
+refuse to start one from the background. `keepAlive: false` turns it off, and `link.keepAliveError`
+says why it could not start.
+
+Two settings make it dependable. Put them on a QA screen:
+
+```ts
+import {
+  askBatteryUnrestricted,
+  askNotificationPermission,
+  backgroundStatus,
+  openBackgroundSettings,
+} from "anchordb-lens-link";
+
+const status = backgroundStatus(); // { notifications, batteryUnrestricted, keepingAlive, manufacturer, vendorSettings }
+await askNotificationPermission(); // Android 13+: lets the notification show
+askBatteryUnrestricted(); // Android's "let this app always run in the background?" dialog
+if (status?.vendorSettings) openBackgroundSettings(); // Xiaomi: Autostart, and Battery saver
+```
+
+On a Xiaomi phone also turn on **Autostart**, set **Battery saver** to **No restrictions**, and lock the
+app in Recents.
+
+The package adds `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_SPECIAL_USE`, `POST_NOTIFICATIONS` and
+`REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` to the app's manifest, with a `specialUse` foreground service.
+That suits a QA build; a Play Store build that shipped the package would have to justify them — one
+more reason to keep it out of production.
+
 ## Keep it out of production
 
 A link exposes the database to Anchor Lens on the phone, so:
@@ -69,9 +107,10 @@ enableLensLink(db, options?): Promise<LensLink>
 | `allowInProduction` | Required in a release build |
 | `readOnly` | Refuse every write from Lens |
 | `anchorVersion`, `platform` | Reported to Lens |
+| `keepAlive` | Keep the app running in the background while the link is on. Default `true` |
 | `onConnectionsChange(count)` | Lens connections opening and closing |
 
-`LensLink` has `port`, `fileName`, `filePath`, `connections`, `agent` and `close()`. Calling
+`LensLink` has `port`, `fileName`, `filePath`, `connections`, `keepAliveError`, `agent` and `close()`. Calling
 `enableLensLink` again for the same database replaces the running link, so it is safe in an effect and
 through Fast Refresh.
 
@@ -85,3 +124,11 @@ For a Lens client: `readLensLink(fileText)` returns `{ app, database, port, secr
   React Native app needs `expo-modules-core` installed). iOS is not supported yet.
 - `anchordb` 1.3 or later, whose inspector accepts a shared secret.
 - Anchor Lens with **Open app from file**.
+
+## Bugs, support and feedback
+
+Report a bug, ask for help or suggest a feature on the [AnchorDB project page](https://www.nisalanadeera.com/projects/anchordb#feedback) —
+choose `anchordb-lens-link` as the package, and the reply comes by email.
+
+Include the version (`npm ls anchordb`), where it runs, the smallest snippet that reproduces it, and
+the full error.

package/android/build.gradle

@@ -4,13 +4,13 @@ plugins {
 }
 
 group = 'dev.anchordb'
-version = '1.3.0'
+version = '1.3.2'
 
 android {
   namespace "dev.anchordb.lenslink"
   defaultConfig {
-    versionCode 1
-    versionName '1.3.0'
+    versionCode 3
+    versionName '1.3.2'
   }
 }
 
@@ -18,4 +18,6 @@ dependencies {
   // The WebSocket server on 127.0.0.1. Anchor Lens connects with React Native's built-in WebSocket, so
   // this is the only native networking code on either side.
   implementation "org.java-websocket:Java-WebSocket:1.6.0"
+  // NotificationCompat and ServiceCompat, for the foreground service that keeps the app running.
+  implementation "androidx.core:core-ktx:1.17.0"
 }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,28 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <!-- Keep the app running while Anchor Lens Link is on: a foreground service with a notification. -->
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
+  <!-- Android 13 and later: lets that notification show. -->
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+  <!-- The system "let this app always run in the background?" dialog. -->
+  <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
+
+  <!-- Phone makers' own background-running screens, so the app can check they exist before opening one. -->
+  <queries>
+    <package android:name="com.miui.securitycenter" />
+    <package android:name="com.coloros.safecenter" />
+    <package android:name="com.vivo.permissionmanager" />
+  </queries>
+
+  <application>
+    <service
+      android:name="dev.anchordb.lenslink.LensLinkKeepAliveService"
+      android:exported="false"
+      android:foregroundServiceType="specialUse">
+      <property
+        android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
+        android:value="Keeps a development database inspector connection (Anchor Lens Link) open while the app is in the background." />
+    </service>
+  </application>
+</manifest>

package/android/src/main/java/dev/anchordb/lenslink/AnchorLensLinkModule.kt

@@ -1,6 +1,19 @@
 package dev.anchordb.lenslink
 
+import android.Manifest
+import android.annotation.SuppressLint
+import android.app.NotificationManager
+import android.content.ComponentName
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.net.Uri
+import android.os.Build
 import android.os.Bundle
+import android.os.PowerManager
+import android.provider.Settings
+import androidx.core.content.ContextCompat
+import expo.modules.interfaces.permissions.Permissions
 import expo.modules.kotlin.Promise
 import expo.modules.kotlin.exception.CodedException
 import expo.modules.kotlin.exception.Exceptions
@@ -20,11 +33,12 @@ import java.util.concurrent.atomic.AtomicBoolean
 import java.util.concurrent.atomic.AtomicInteger
 
 /**
- * The native half of Anchor Lens Link: a WebSocket server on this phone's loopback address, and the link
- * file in Android/media/<package>/anchor-lens/.
+ * The native half of Anchor Lens Link: a WebSocket server on this phone's loopback address, the link file
+ * in Android/media/<package>/anchor-lens/, and what keeps the app running in the background.
  *
- * Only transport and files live here. Authentication, the inspector protocol and the database are all
- * JavaScript, in anchordb itself — this module never sees a secret it checks, or a document.
+ * Only transport, files and Android settings live here. Authentication, the inspector protocol and the
+ * database are all JavaScript, in anchordb itself — this module never sees a secret it checks, or a
+ * document.
  */
 class AnchorLensLinkModule : Module() {
   private var server: LinkServer? = null
@@ -68,8 +82,41 @@ class AnchorLensLinkModule : Module() {
       linkFile(name).delete()
     }
 
+    AsyncFunction("startKeepAlive") { title: String, text: String ->
+      startKeepAliveNow(title, text)
+    }
+
+    Function("updateKeepAlive") { title: String, text: String ->
+      updateKeepAliveNow(title, text)
+    }
+
+    Function("stopKeepAlive") {
+      stopKeepAliveNow()
+    }
+
+    Function("backgroundStatus") {
+      backgroundStatusNow()
+    }
+
+    AsyncFunction("askNotificationPermission") { promise: Promise ->
+      askNotificationPermissionNow(promise)
+    }
+
+    Function("askBatteryUnrestricted") {
+      askBatteryUnrestrictedNow()
+    }
+
+    Function("openBackgroundSettings") {
+      openBackgroundSettingsNow()
+    }
+
+    Function("openNotificationSettings") {
+      openNotificationSettingsNow()
+    }
+
     OnDestroy {
       stopServerNow()
+      stopKeepAliveNow()
     }
   }
 
@@ -86,7 +133,7 @@ class AnchorLensLinkModule : Module() {
     server?.closeConnection(id)
   }
 
-  private fun context() = appContext.reactContext ?: throw Exceptions.ReactContextLost()
+  private fun context(): Context = appContext.reactContext ?: throw Exceptions.ReactContextLost()
 
   @Suppress("DEPRECATION")
   private fun linkFile(name: String): File {
@@ -97,8 +144,137 @@ class AnchorLensLinkModule : Module() {
     return File(File(media, "anchor-lens"), name)
   }
 
+  // region Keeping the app running
+
+  private fun startKeepAliveNow(title: String, text: String) {
+    val context = context()
+    val intent =
+      Intent(context, LensLinkKeepAliveService::class.java)
+        .putExtra(LensLinkKeepAliveService.EXTRA_TITLE, title)
+        .putExtra(LensLinkKeepAliveService.EXTRA_TEXT, text)
+    try {
+      ContextCompat.startForegroundService(context, intent)
+    } catch (err: IllegalStateException) {
+      // Android 12 and later refuse to start one while the app is in the background.
+      throw KeepAliveNotAllowed(err)
+    }
+  }
+
+  private fun updateKeepAliveNow(title: String, text: String) {
+    if (!LensLinkKeepAliveService.running) return
+    val context = context()
+    try {
+      context
+        .getSystemService(NotificationManager::class.java)
+        ?.notify(LensLinkKeepAliveService.NOTIFICATION_ID, LensLinkKeepAliveService.notification(context, title, text))
+    } catch (_: SecurityException) {
+      // Without notification permission the service keeps running; only its text is not shown.
+    }
+  }
+
+  private fun stopKeepAliveNow() {
+    val context = appContext.reactContext ?: return
+    context.stopService(Intent(context, LensLinkKeepAliveService::class.java))
+  }
+
+  private fun backgroundStatusNow(): Map<String, Any> {
+    val context = context()
+    val notifications =
+      Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU ||
+        ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) ==
+        PackageManager.PERMISSION_GRANTED
+    val power = context.getSystemService(PowerManager::class.java)
+    return mapOf(
+      "notifications" to (if (notifications) "granted" else "denied"),
+      "batteryUnrestricted" to (power?.isIgnoringBatteryOptimizations(context.packageName) ?: true),
+      "keepingAlive" to LensLinkKeepAliveService.running,
+      "manufacturer" to Build.MANUFACTURER,
+      "vendorSettings" to (vendorScreen(context) != null),
+    )
+  }
+
+  private fun askNotificationPermissionNow(promise: Promise) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+      // Before Android 13 notifications need no permission.
+      promise.resolve(
+        Bundle().apply {
+          putBoolean("granted", true)
+          putBoolean("canAskAgain", true)
+        },
+      )
+      return
+    }
+    Permissions.askForPermissionsWithPermissionsManager(
+      appContext.permissions,
+      promise,
+      Manifest.permission.POST_NOTIFICATIONS,
+    )
+  }
+
+  @SuppressLint("BatteryLife")
+  private fun askBatteryUnrestrictedNow(): Boolean {
+    val context = context()
+    val power = context.getSystemService(PowerManager::class.java)
+    if (power?.isIgnoringBatteryOptimizations(context.packageName) == true) return true
+    return openScreen(Intent(Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS, Uri.parse("package:${context.packageName}"))) ||
+      openScreen(Intent(Settings.ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS))
+  }
+
+  private fun openBackgroundSettingsNow(): String {
+    val context = context()
+    val vendor = vendorScreen(context)
+    return when {
+      vendor != null && openScreen(vendor) -> "vendor"
+      openScreen(Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.parse("package:${context.packageName}"))) -> "app"
+      else -> "none"
+    }
+  }
+
+  private fun openNotificationSettingsNow(): Boolean {
+    val context = context()
+    val intent =
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS).putExtra(Settings.EXTRA_APP_PACKAGE, context.packageName)
+      } else {
+        Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.parse("package:${context.packageName}"))
+      }
+    return openScreen(intent)
+  }
+
+  private fun openScreen(intent: Intent): Boolean {
+    val activity = appContext.currentActivity
+    return try {
+      if (activity != null) {
+        activity.startActivity(intent)
+      } else {
+        context().startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
+      }
+      true
+    } catch (_: Exception) {
+      false
+    }
+  }
+
+  private fun vendorScreen(context: Context): Intent? {
+    val screens = VENDOR_SCREENS[Build.MANUFACTURER.lowercase()] ?: return null
+    return screens
+      .map { (pkg, activity) -> Intent().setComponent(ComponentName(pkg, activity)) }
+      .firstOrNull { it.resolveActivity(context.packageManager) != null }
+  }
+
+  // endregion
+
   companion object {
     private val FILE_NAME = Regex("^[A-Za-z0-9._-]{1,120}\\.anchorlens$")
+
+    // Makers whose phones stop background apps beyond what Android does, with the screen that lets an app
+    // keep running. Redmi and POCO phones report "Xiaomi".
+    private val VENDOR_SCREENS =
+      mapOf(
+        "xiaomi" to listOf("com.miui.securitycenter" to "com.miui.permcenter.autostart.AutoStartManagementActivity"),
+        "oppo" to listOf("com.coloros.safecenter" to "com.coloros.safecenter.permission.startup.StartupAppListActivity"),
+        "vivo" to listOf("com.vivo.permissionmanager" to "com.vivo.permissionmanager.activity.BgStartUpManagerActivity"),
+      )
   }
 }
 
@@ -108,6 +284,12 @@ private class InvalidLinkFileName(name: String) :
 private class NoMediaDirectory :
   CodedException("This device has no shared media storage to write the Anchor Lens link file to.")
 
+private class KeepAliveNotAllowed(cause: Throwable) :
+  CodedException(
+    "Android did not let the app keep running in the background, because it was not on screen. Turn the link on while the app is open.",
+    cause,
+  )
+
 /** One launch's server. A stopped WebSocketServer cannot be started again, so each start makes a new one. */
 private class LinkServer(
   private val module: AnchorLensLinkModule,

package/android/src/main/java/dev/anchordb/lenslink/LensLinkKeepAliveService.kt

@@ -0,0 +1,89 @@
+package dev.anchordb.lenslink
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.content.pm.ServiceInfo
+import android.os.Build
+import android.os.IBinder
+import androidx.core.app.NotificationCompat
+import androidx.core.app.ServiceCompat
+
+/**
+ * Keeps the app's process running while Anchor Lens Link is on — or, in Anchor Lens, while it is connected
+ * to an app.
+ *
+ * Android freezes and then stops apps in the background, and some phones (Xiaomi's especially) do it
+ * within seconds of switching away. A foreground service, with its ongoing notification, is what Android
+ * lets an app use to keep running, so the link survives switching between the two apps. Found on a phone.
+ */
+class LensLinkKeepAliveService : Service() {
+  override fun onBind(intent: Intent?): IBinder? = null
+
+  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+    val title = intent?.getStringExtra(EXTRA_TITLE) ?: "Anchor Lens Link"
+    val text = intent?.getStringExtra(EXTRA_TEXT) ?: ""
+    val type =
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_SPECIAL_USE
+      } else {
+        0
+      }
+    ServiceCompat.startForeground(this, NOTIFICATION_ID, notification(this, title, text), type)
+    running = true
+    // Not restarted after being stopped: the JavaScript that answers Lens would not be running anyway.
+    return START_NOT_STICKY
+  }
+
+  override fun onDestroy() {
+    running = false
+    ServiceCompat.stopForeground(this, ServiceCompat.STOP_FOREGROUND_REMOVE)
+    super.onDestroy()
+  }
+
+  companion object {
+    const val NOTIFICATION_ID = 0x4c4c
+    const val CHANNEL_ID = "anchor-lens-link"
+    const val EXTRA_TITLE = "title"
+    const val EXTRA_TEXT = "text"
+
+    @Volatile
+    var running = false
+
+    fun notification(context: Context, title: String, text: String): Notification {
+      ensureChannel(context)
+      val launch = context.packageManager.getLaunchIntentForPackage(context.packageName)
+      val open =
+        launch?.let {
+          PendingIntent.getActivity(context, 0, it, PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT)
+        }
+      val builder =
+        NotificationCompat.Builder(context, CHANNEL_ID)
+          .setSmallIcon(R.drawable.anchor_lens_link_notification)
+          .setContentTitle(title)
+          .setContentText(text)
+          .setStyle(NotificationCompat.BigTextStyle().bigText(text))
+          .setOngoing(true)
+          .setOnlyAlertOnce(true)
+          .setPriority(NotificationCompat.PRIORITY_LOW)
+          .setCategory(NotificationCompat.CATEGORY_SERVICE)
+          .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE)
+      if (open != null) builder.setContentIntent(open)
+      return builder.build()
+    }
+
+    private fun ensureChannel(context: Context) {
+      if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+      val manager = context.getSystemService(NotificationManager::class.java) ?: return
+      if (manager.getNotificationChannel(CHANNEL_ID) != null) return
+      val channel = NotificationChannel(CHANNEL_ID, "Anchor Lens Link", NotificationManager.IMPORTANCE_LOW)
+      channel.description = "Shown while this app keeps running for Anchor Lens."
+      channel.setShowBadge(false)
+      manager.createNotificationChannel(channel)
+    }
+  }
+}

package/android/src/main/res/drawable/anchor_lens_link_notification.xml

@@ -0,0 +1,10 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+  android:width="24dp"
+  android:height="24dp"
+  android:viewportWidth="24"
+  android:viewportHeight="24">
+  <!-- An eye: something is looking at this app's data. -->
+  <path
+    android:fillColor="#FFFFFFFF"
+    android:pathData="M12,4.5C7,4.5 2.73,7.61 1,12c1.73,4.39 6,7.5 11,7.5s9.27,-3.11 11,-7.5c-1.73,-4.39 -6,-7.5 -11,-7.5zM12,17c-2.76,0 -5,-2.24 -5,-5s2.24,-5 5,-5 5,2.24 5,5 -2.24,5 -5,5zM12,9c-1.66,0 -3,1.34 -3,3s1.34,3 3,3 3,-1.34 3,-3 -1.34,-3 -3,-3z" />
+</vector>

package/dist/cjs/app.d.ts

@@ -1,31 +1,14 @@
 import { InspectorAgent, type AnchorDB } from "anchordb";
+import { type LensLinkNative } from "./native.js";
 /**
  * The app half of Anchor Lens Link.
  *
  * `enableLensLink(db)` starts a WebSocket server on 127.0.0.1, puts an `InspectorAgent` on the database
- * behind it, and writes the link file Lens opens. Every connection is an ordinary inspector session —
- * the same protocol, capability checks and Model API writes as through the relay — authenticated with a
- * secret made for this launch, which exists only inside the sealed file.
+ * behind it, writes the link file Lens opens, and keeps the app running in the background while the link
+ * is on. Every connection is an ordinary inspector session — the same protocol, capability checks and
+ * Model API writes as through the relay — authenticated with a secret made for this launch, which exists
+ * only inside the sealed file.
  */
-/** An event from the native module. */
-export interface LensLinkNativeEvent {
-    id: number;
-    data?: string;
-    code?: number;
-}
-/** The native module's surface. Exported so a test, or another runtime, can supply its own. */
-export interface LensLinkNative {
-    startServer(): Promise<number>;
-    stopServer(): Promise<void>;
-    send(id: number, data: string): boolean;
-    closeConnection(id: number): void;
-    packageName(): string;
-    writeLinkFile(name: string, contents: string): string;
-    deleteLinkFile(name: string): boolean;
-    addListener(event: "onOpen" | "onMessage" | "onClose", listener: (event: LensLinkNativeEvent) => void): {
-        remove(): void;
-    };
-}
 export interface LensLinkOptions {
     /**
      * Required in a release build — which includes a QA APK. Lens Link exposes the database to Anchor
@@ -37,6 +20,12 @@ export interface LensLinkOptions {
     /** Reported to Lens. */
     anchorVersion?: string;
     platform?: string;
+    /**
+     * Keep the app running in the background while the link is on, with an ongoing notification — an
+     * Android foreground service. On by default: without it Android stops the app soon after you switch to
+     * Lens, and some phones within seconds. `backgroundStatus()` reports the settings that help it hold.
+     */
+    keepAlive?: boolean;
     /** Called whenever a Lens connection opens or closes, with how many are open. */
     onConnectionsChange?: (count: number) => void;
     /** The native module. Defaults to the one this package installs. */
@@ -52,14 +41,17 @@ export interface LensLink {
     readonly filePath: string;
     /** Lens connections open right now. */
     readonly connections: number;
-    /** Stop listening, close every Lens connection, and delete the link file. */
+    /** Why the app could not be kept running in the background; null when it is, or when keepAlive is off. */
+    readonly keepAliveError: string | null;
+    /** Stop listening, close every Lens connection, delete the link file, and stop keeping the app running. */
     close(): Promise<void>;
 }
 /**
  * Let Anchor Lens on this phone open `db`. For development and QA builds.
  *
- * Calling it again for the same database replaces the running link, so it is safe in an effect or
- * after a reload. Resolves once the link file is written.
+ * Call it while the app is on screen — at startup, say — since Android only lets a foreground app start
+ * keeping itself running. Calling it again for the same database replaces the running link, so it is safe
+ * in an effect or after a reload. Resolves once the link file is written.
  */
 export declare function enableLensLink(db: AnchorDB, options?: LensLinkOptions): Promise<LensLink>;
 //# sourceMappingURL=app.d.ts.map

package/dist/cjs/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EAGd,KAAK,QAAQ,EAEd,MAAM,UAAU,CAAC;AAGlB;;;;;;;GAOG;AAEH,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC7B,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,WAAW,IAAI,MAAM,CAAC;IACtB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IACtD,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,WAAW,CACT,KAAK,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,EACzC,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAC7C;QAAE,MAAM,IAAI,IAAI,CAAA;KAAE,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wBAAwB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,oEAAoE;IACpE,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAOD;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAOnG"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EAGd,KAAK,QAAQ,EAEd,MAAM,UAAU,CAAC;AAElB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE;;;;;;;;GAQG;AAEH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wBAAwB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,oEAAoE;IACpE,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0GAA0G;IAC1G,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,2GAA2G;IAC3G,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAOD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAOnG"}

package/dist/cjs/app.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enableLensLink = enableLensLink;
 const anchordb_1 = require("anchordb");
 const link_file_ts_1 = require("./link-file.js");
+const native_ts_1 = require("./native.js");
 // On globalThis, not in module scope: Fast Refresh re-runs this module, and a registry that reset with it
 // would leave the previous agent answering on the previous server's events.
 const registry = (globalThis.__anchordbLensLinks ??=
@@ -10,12 +11,13 @@ const registry = (globalThis.__anchordbLensLinks ??=
 /**
  * Let Anchor Lens on this phone open `db`. For development and QA builds.
  *
- * Calling it again for the same database replaces the running link, so it is safe in an effect or
- * after a reload. Resolves once the link file is written.
+ * Call it while the app is on screen — at startup, say — since Android only lets a foreground app start
+ * keeping itself running. Calling it again for the same database replaces the running link, so it is safe
+ * in an effect or after a reload. Resolves once the link file is written.
  */
 async function enableLensLink(db, options = {}) {
     (0, anchordb_1.assertInspectorAllowed)(db.name, options.allowInProduction);
-    const native = options.native ?? nativeModule();
+    const native = options.native ?? (0, native_ts_1.nativeModule)();
     await registry.get(db.name)?.close();
     const link = await start(db, native, options);
     registry.set(db.name, link);
@@ -26,6 +28,7 @@ async function start(db, native, options) {
     // proves the same value.
     const secret = (0, link_file_ts_1.randomHex)(32).toUpperCase();
     const platform = options.platform ?? "android";
+    const fileName = `${db.name.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 100)}.anchorlens`;
     const agent = new anchordb_1.InspectorAgent(db, {
         auth: { sharedSecret: secret },
         platform,
@@ -33,7 +36,23 @@ async function start(db, native, options) {
         ...(options.readOnly ? { readOnly: true } : {}),
     });
     const sockets = new Map();
-    const report = () => options.onConnectionsChange?.(sockets.size);
+    let keepingAlive = false;
+    let keepAliveError = null;
+    /** The notification: whether Lens is connected right now. */
+    const notice = () => sockets.size > 0
+        ? ["Anchor Lens connected", `Anchor Lens is reading ${db.name}. This app keeps running while you use Lens.`]
+        : ["Anchor Lens Link on", `Anchor Lens can open ${db.name} from ${fileName}.`];
+    const report = () => {
+        if (keepingAlive) {
+            try {
+                native.updateKeepAlive(...notice());
+            }
+            catch {
+                // The notification's wording is a courtesy; the connection does not depend on it.
+            }
+        }
+        options.onConnectionsChange?.(sockets.size);
+    };
     const subscriptions = [
         native.addListener("onOpen", ({ id }) => {
             const socket = new NativeSocket(native, id);
@@ -54,7 +73,6 @@ async function start(db, native, options) {
             report();
         }),
     ];
-    const fileName = `${db.name.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 100)}.anchorlens`;
     let port;
     let filePath;
     try {
@@ -78,6 +96,16 @@ async function start(db, native, options) {
         await agent.close();
         throw err;
     }
+    if (options.keepAlive !== false) {
+        try {
+            await native.startKeepAlive(...notice());
+            keepingAlive = true;
+        }
+        catch (err) {
+            // The link still works while the app is on screen, so this is reported, not thrown.
+            keepAliveError = err.message;
+        }
+    }
     let closed = false;
     const link = {
         agent,
@@ -87,6 +115,9 @@ async function start(db, native, options) {
         get connections() {
             return sockets.size;
         },
+        get keepAliveError() {
+            return keepAliveError;
+        },
         close: async () => {
             if (closed)
                 return;
@@ -100,6 +131,15 @@ async function start(db, native, options) {
                 socket.closed();
             }
             sockets.clear();
+            if (keepingAlive) {
+                keepingAlive = false;
+                try {
+                    native.stopKeepAlive();
+                }
+                catch {
+                    // Already stopped, or the app is shutting down.
+                }
+            }
             try {
                 native.deleteLinkFile(fileName);
             }
@@ -154,13 +194,4 @@ class NativeSocket {
             listener(event);
     }
 }
-function nativeModule() {
-    const modules = globalThis.expo?.modules;
-    const found = modules?.AnchorLensLink;
-    if (!found) {
-        throw new Error("Anchor Lens Link needs its native module, and this build does not have it. It runs on Android, in a " +
-            "development or release build (not Expo Go): install anchordb-lens-link, then rebuild the app.");
-    }
-    return found;
-}
 //# sourceMappingURL=app.js.map