@koderlabs/tasks-sdk-rn-native 0.1.0

package/LICENSE

@@ -0,0 +1,179 @@
+PROPRIETARY SOFTWARE LICENSE — ALL RIGHTS RESERVED
+
+Copyright (c) 2026 KoderLabs. All rights reserved.
+Author: Jawaid Gadiwala <jawaidgadiwala@gmail.com>
+
+================================================================================
+1. NO LICENSE GRANTED BY DEFAULT
+================================================================================
+
+This software, including all source code, object code, documentation,
+configuration files, build artifacts, test fixtures, and any associated
+materials (collectively, the "Software"), is the proprietary and confidential
+property of KoderLabs.
+
+NO license, right, title, interest, or permission of any kind — express,
+implied, statutory, by estoppel, by exhaustion, by patent exhaustion, or by
+any other legal theory — is granted to any person or entity by:
+
+  (a) viewing the Software on any registry, repository, mirror, CDN,
+      cache, or other distribution channel (including but not limited to
+      npmjs.com, GitHub, GitLab, or any private registry);
+  (b) downloading, cloning, or otherwise obtaining a copy of the Software;
+  (c) the act of the Software being technically accessible due to a registry
+      requirement, mirror, or third-party distribution;
+  (d) any prior course of dealing, custom, or industry practice.
+
+The ability to access the Software does NOT imply any permission to use it.
+A separate, signed, written license agreement executed by an authorised
+representative of KoderLabs is the ONLY mechanism by which any rights may be
+granted.
+
+================================================================================
+2. PROHIBITED ACTIVITIES (NON-EXHAUSTIVE)
+================================================================================
+
+Without prior signed written permission from KoderLabs, the following are
+expressly PROHIBITED and constitute infringement, breach of contract, and
+unauthorised use:
+
+  (a) Copying the Software in whole or in part, in any medium;
+  (b) Modifying, adapting, translating, porting, or creating derivative works
+      of the Software;
+  (c) Distributing, republishing, mirroring, hosting, transmitting,
+      sublicensing, leasing, lending, renting, selling, offering for sale,
+      bartering, gifting, or otherwise transferring the Software or any
+      portion of it;
+  (d) Forking the Software's repository, whether on GitHub, GitLab, Bitbucket,
+      Codeberg, Sourcehut, or any other version-control hosting service;
+  (e) Reverse engineering, decompiling, disassembling, deobfuscating,
+      extracting source from compiled or minified artifacts, or attempting to
+      derive the source code, algorithms, or trade secrets;
+  (f) Removing, altering, or obscuring any copyright, trademark, license,
+      attribution, or proprietary notice;
+  (g) Using the Software, in whole or in part, to train, fine-tune,
+      evaluate, or benchmark any machine-learning model, embedding model, or
+      AI system;
+  (h) Using the Software to provide a hosted service, SaaS offering,
+      managed offering, or any form of public or commercial offering;
+  (i) Using the Software in any production, staging, development, evaluation,
+      or testing capacity, whether commercial or non-commercial;
+  (j) Bypassing, disabling, or attempting to circumvent any technical
+      protection measure (license check, telemetry, signature verification,
+      etc.) embedded in the Software;
+  (k) Combining or integrating the Software with any work licensed under a
+      copyleft licence (including but not limited to GPL, AGPL, LGPL, MPL,
+      EPL) in a manner that would purport to relicense the Software;
+  (l) Filing, prosecuting, or threatening patent litigation against KoderLabs
+      or its customers based on any feature, design, or behaviour of the
+      Software ("defensive termination" — any such action automatically and
+      immediately terminates any rights granted to the litigant elsewhere).
+
+================================================================================
+3. NO IMPLIED RIGHT TO INTERNAL USE
+================================================================================
+
+The Software is NOT licensed for internal evaluation, internal production,
+internal testing, or any other internal use unless and until a separate
+written commercial licence is executed. Possession of a copy of the Software,
+by whatever means, confers no right to execute, run, deploy, or use it.
+
+================================================================================
+4. NO PATENT, TRADEMARK, OR OTHER IP GRANT
+================================================================================
+
+No patent licence, trademark licence, trade-secret disclosure, design-right
+licence, or any other intellectual-property licence is granted under this
+notice. KoderLabs retains all such rights.
+
+================================================================================
+5. CONFIDENTIALITY
+================================================================================
+
+The Software contains trade secrets and confidential information of
+KoderLabs. Any party in possession of the Software shall (a) treat it as
+confidential, (b) take reasonable measures to prevent unauthorised access or
+disclosure, and (c) not disclose, publish, or make available the Software or
+any portion thereof to any third party.
+
+================================================================================
+6. AUTOMATIC TERMINATION
+================================================================================
+
+Any rights that may exist under a separate written agreement terminate
+AUTOMATICALLY AND IMMEDIATELY upon any breach of this notice, without notice
+and without judicial action. Upon termination, the breaching party shall
+immediately destroy all copies of the Software in its possession or control
+and certify destruction in writing to KoderLabs.
+
+================================================================================
+7. NO WARRANTY
+================================================================================
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, ACCURACY, RELIABILITY,
+TITLE, AVAILABILITY, OR THAT THE SOFTWARE WILL OPERATE UNINTERRUPTED OR
+ERROR-FREE.
+
+================================================================================
+8. NO LIABILITY
+================================================================================
+
+IN NO EVENT SHALL KODERLABS OR ITS AFFILIATES, OFFICERS, EMPLOYEES, AGENTS,
+LICENSORS, OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY (INCLUDING DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+CONSEQUENTIAL, PUNITIVE, LOST PROFITS, LOST DATA, OR BUSINESS INTERRUPTION),
+WHETHER IN AN ACTION OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT
+LIABILITY, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OF OR INABILITY TO USE THE SOFTWARE, EVEN IF ADVISED OF
+THE POSSIBILITY OF SUCH DAMAGE. IN NO EVENT SHALL KODERLABS' TOTAL CUMULATIVE
+LIABILITY EXCEED ONE U.S. DOLLAR (USD 1.00).
+
+================================================================================
+9. EQUITABLE RELIEF
+================================================================================
+
+The parties acknowledge that any breach of this notice would cause
+irreparable harm to KoderLabs for which monetary damages would be inadequate.
+KoderLabs is therefore entitled, in addition to all other remedies available
+at law, to specific performance and injunctive relief without the need to
+post bond.
+
+================================================================================
+10. GOVERNING LAW AND VENUE
+================================================================================
+
+This notice shall be governed by and construed in accordance with the laws
+of the Islamic Republic of Pakistan, without regard to its conflict-of-laws
+principles. Any dispute arising out of or in connection with this notice
+shall be subject to the exclusive jurisdiction of the courts of Karachi,
+Pakistan.
+
+The United Nations Convention on Contracts for the International Sale of
+Goods shall not apply.
+
+================================================================================
+11. SEVERABILITY AND ENTIRE NOTICE
+================================================================================
+
+If any provision of this notice is held invalid or unenforceable, the
+remaining provisions shall continue in full force and effect. This notice,
+together with any separate signed written licence executed between KoderLabs
+and a licensee, constitutes the entire agreement concerning the Software and
+supersedes all prior or contemporaneous understandings.
+
+================================================================================
+12. CONTACT
+================================================================================
+
+For licensing inquiries, audit requests, or notice of suspected
+infringement, contact:
+
+    KoderLabs
+    Attn: Jawaid Gadiwala
+    Email: jawaidgadiwala@gmail.com
+
+================================================================================
+END OF LICENCE
+================================================================================

package/README.md

@@ -0,0 +1,9 @@
+# Proprietary Software
+
+KoderLabs proprietary. All rights reserved.
+
+See the bundled `LICENSE` for terms. No grant of any rights, express or
+implied, is conferred by access to or possession of this package. A
+separate signed written licence from KoderLabs is required for any use.
+
+Licensing inquiries: jawaidgadiwala@gmail.com

package/TasksSdkRnNative.podspec

@@ -0,0 +1,32 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'TasksSdkRnNative'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.description    = package['description']
+  s.license        = 'MIT'
+  s.author         = 'KoderLabs'
+  s.homepage       = 'https://tasks.koderlabs.net'
+  s.platforms      = { :ios => '13.4' }
+  s.swift_version  = '5.4'
+  s.source         = { :git => '' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+  # PLCrashReporter — BSD-licensed open-source library. Captures Mach
+  # exceptions, signals (SIGSEGV/SIGBUS/SIGABRT/SIGFPE), and ObjC NSExceptions
+  # and writes a binary crash report to disk that survives process death.
+  s.dependency 'PLCrashReporter', '~> 1.11'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    # Force C++17 for ExpoModulesCore compatibility.
+    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule',
+  }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+end

package/android/build.gradle

@@ -0,0 +1,43 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+group = 'expo.modules.tasksnative'
+version = '0.0.0'
+
+def expoModulesCorePlugin = new File(
+  project(":expo-modules-core").projectDir.absolutePath,
+  "ExpoModulesCorePlugin.gradle"
+)
+apply from: expoModulesCorePlugin
+applyKotlinExpoModulesCorePlugin()
+useCoreDependencies()
+useExpoPublishing()
+
+android {
+  namespace "expo.modules.tasksnative"
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 24)
+    compileSdkVersion safeExtGet("compileSdkVersion", 34)
+    targetSdkVersion safeExtGet("targetSdkVersion", 34)
+    versionCode 1
+    versionName "0.0.0"
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-std=c++17"
+        // Build for the architectures EAS / standard Android targets.
+        abiFilters "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "src/main/cpp/CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    pickFirst "**/libc++_shared.so"
+  }
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/cpp/CMakeLists.txt

@@ -0,0 +1,22 @@
+cmake_minimum_required(VERSION 3.18)
+project(tasksNative)
+
+# Build a tiny native lib that installs SIGSEGV/SIGBUS/SIGABRT/SIGFPE
+# handlers. On crash it serialises minimal context (signal, fault address,
+# backtrace) to a file in the app's filesDir.
+#
+# We deliberately avoid linking Crashpad/Breakpad here — that's a 50MB+
+# dependency and 1 week of integration work. The simple sigaction + raw
+# backtrace covers the most common native crash modes (null deref, abort).
+# Apps with heavy native code should add Crashpad as a follow-up.
+
+add_library(tasks_native_crash SHARED
+  tasks_native_crash.cpp
+)
+
+target_link_libraries(tasks_native_crash
+  android
+  log
+)
+
+target_compile_features(tasks_native_crash PRIVATE cxx_std_17)

package/android/src/main/cpp/tasks_native_crash.cpp

@@ -0,0 +1,174 @@
+/**
+ * Minimal native crash capture for Android.
+ *
+ * Installs a `sigaction` handler on a dedicated alternate signal stack for
+ * SIGSEGV / SIGBUS / SIGABRT / SIGFPE / SIGILL. When triggered, the handler:
+ *
+ *   1. Captures backtrace addresses via `unwind` (no symbolisation — we'd
+ *      need libunwind or Breakpad/Crashpad for full names). Address-only
+ *      output requires post-process symbolisation via the CLI source-map
+ *      upload (planned to extend for .so files).
+ *   2. Writes a JSON file to the path configured at install time.
+ *   3. Chains to the previous handler so RN's redbox / Play Store ANR
+ *      detection still works.
+ *
+ * Important constraints inside a signal handler:
+ *   - Only async-signal-safe functions (no malloc, no printf, no Java calls)
+ *   - Stack space is limited (use the alternate sigaltstack)
+ *   - Avoid touching shared mutable state — read configured `crash_file_path`
+ *     once at install time and treat it as immutable.
+ *
+ * Production hardening (out of scope for this commit, tracked in
+ * TasksSdkRnNative.java's TODO):
+ *   - Use libunwind for unwinding past async-signal-safety boundary
+ *   - Capture register dump
+ *   - Resolve symbols on next launch (offline path, can use malloc safely)
+ *   - Detect re-entrant crashes (handler crashing inside the handler)
+ */
+#include <jni.h>
+#include <signal.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <unwind.h>
+#include <string.h>
+#include <android/log.h>
+
+#define LOG_TAG "TasksNative"
+#define MAX_FRAMES 64
+#define MAX_PATH 1024
+
+static char g_crash_file_path[MAX_PATH] = {0};
+static struct sigaction g_prev_handlers[NSIG];
+static int g_handled_signals[] = {SIGSEGV, SIGBUS, SIGABRT, SIGFPE, SIGILL};
+static const size_t g_handled_count = sizeof(g_handled_signals) / sizeof(g_handled_signals[0]);
+
+struct UnwindContext {
+  void** frames;
+  size_t cap;
+  size_t count;
+};
+
+static _Unwind_Reason_Code unwind_callback(struct _Unwind_Context* ctx, void* arg) {
+  UnwindContext* uc = (UnwindContext*)arg;
+  if (uc->count >= uc->cap) return _URC_END_OF_STACK;
+  uintptr_t pc = _Unwind_GetIP(ctx);
+  if (pc) {
+    uc->frames[uc->count++] = (void*)pc;
+  }
+  return _URC_NO_REASON;
+}
+
+/**
+ * Write `len` bytes from `buf` to a file descriptor. Loops on partial writes.
+ * Async-signal-safe.
+ */
+static void safe_write(int fd, const char* buf, size_t len) {
+  while (len > 0) {
+    ssize_t n = write(fd, buf, len);
+    if (n <= 0) break;
+    buf += n;
+    len -= (size_t)n;
+  }
+}
+
+/** Itoa for unsigned long long. Async-signal-safe. */
+static int u64_to_hex(unsigned long long v, char* out) {
+  static const char digits[] = "0123456789abcdef";
+  char buf[20];
+  int i = 0;
+  if (v == 0) { out[0] = '0'; return 1; }
+  while (v && i < (int)sizeof(buf)) { buf[i++] = digits[v & 0xf]; v >>= 4; }
+  for (int j = 0; j < i; j++) out[j] = buf[i - 1 - j];
+  return i;
+}
+
+static const char* signal_name(int signo) {
+  switch (signo) {
+    case SIGSEGV: return "SIGSEGV";
+    case SIGBUS:  return "SIGBUS";
+    case SIGABRT: return "SIGABRT";
+    case SIGFPE:  return "SIGFPE";
+    case SIGILL:  return "SIGILL";
+    default:      return "SIGNAL";
+  }
+}
+
+static void crash_handler(int signo, siginfo_t* info, void* /*ctx*/) {
+  // 1. Open the crash file (O_CREAT|O_TRUNC — overwrite any stale report).
+  int fd = open(g_crash_file_path, O_WRONLY | O_CREAT | O_TRUNC, 0600);
+  if (fd < 0) goto chain;
+
+  // 2. Emit JSON manually — we can't use snprintf here (not async-signal-safe).
+  safe_write(fd, "{\"platform\":\"android\",\"signal\":\"", 32);
+  const char* sname = signal_name(signo);
+  safe_write(fd, sname, strlen(sname));
+  safe_write(fd, "\",\"faultAddr\":\"0x", 17);
+  {
+    char hex[20];
+    int hn = u64_to_hex((unsigned long long)(uintptr_t)info->si_addr, hex);
+    safe_write(fd, hex, (size_t)hn);
+  }
+  safe_write(fd, "\",\"frames\":[", 12);
+
+  void* frames[MAX_FRAMES];
+  UnwindContext uc = { frames, MAX_FRAMES, 0 };
+  _Unwind_Backtrace(unwind_callback, &uc);
+
+  for (size_t i = 0; i < uc.count; i++) {
+    if (i > 0) safe_write(fd, ",", 1);
+    safe_write(fd, "\"0x", 3);
+    char hex[20];
+    int hn = u64_to_hex((unsigned long long)(uintptr_t)frames[i], hex);
+    safe_write(fd, hex, (size_t)hn);
+    safe_write(fd, "\"", 1);
+  }
+
+  safe_write(fd, "]}", 2);
+  close(fd);
+
+chain:
+  // 3. Chain into previous handler so RN / Play Store can also see it.
+  if (g_prev_handlers[signo].sa_flags & SA_SIGINFO) {
+    if (g_prev_handlers[signo].sa_sigaction) {
+      g_prev_handlers[signo].sa_sigaction(signo, info, nullptr);
+    }
+  } else if (g_prev_handlers[signo].sa_handler != SIG_DFL &&
+             g_prev_handlers[signo].sa_handler != SIG_IGN) {
+    g_prev_handlers[signo].sa_handler(signo);
+  }
+  // 4. Re-raise so the OS sees the death and writes its own tombstone.
+  signal(signo, SIG_DFL);
+  raise(signo);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_expo_modules_tasksnative_TasksSdkRnNativeModule_nativeInstall(
+    JNIEnv* env, jobject /*thiz*/, jstring crashFilePath) {
+  const char* path = env->GetStringUTFChars(crashFilePath, nullptr);
+  if (!path) return;
+  size_t len = strnlen(path, MAX_PATH - 1);
+  memcpy(g_crash_file_path, path, len);
+  g_crash_file_path[len] = '\0';
+  env->ReleaseStringUTFChars(crashFilePath, path);
+
+  // Allocate a 64KB alternate stack so the handler can run when the main
+  // stack is corrupted (a real risk on SIGSEGV from stack overflow).
+  stack_t altstack;
+  altstack.ss_sp = malloc(SIGSTKSZ * 8);  // pre-allocated, not signal-time
+  altstack.ss_size = SIGSTKSZ * 8;
+  altstack.ss_flags = 0;
+  sigaltstack(&altstack, nullptr);
+
+  struct sigaction sa;
+  memset(&sa, 0, sizeof(sa));
+  sa.sa_sigaction = crash_handler;
+  sa.sa_flags = SA_SIGINFO | SA_ONSTACK;
+  sigemptyset(&sa.sa_mask);
+
+  for (size_t i = 0; i < g_handled_count; i++) {
+    sigaction(g_handled_signals[i], &sa, &g_prev_handlers[g_handled_signals[i]]);
+  }
+
+  __android_log_print(ANDROID_LOG_INFO, LOG_TAG,
+      "Native signal handlers installed (path=%s)", g_crash_file_path);
+}

package/android/src/main/java/expo/modules/tasksnative/TasksSdkRnNativeModule.kt

@@ -0,0 +1,188 @@
+package expo.modules.tasksnative
+
+import android.os.Handler
+import android.os.Looper
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.File
+
+/**
+ * Expo module that wires up Android native crash + ANR capture.
+ *
+ * Two layers:
+ *   1. JNI signal handler in `libtasks_native_crash.so` (built by CMake).
+ *      Catches SIGSEGV/SIGBUS/SIGABRT/SIGFPE/SIGILL and writes a JSON
+ *      crash file. See `cpp/tasks_native_crash.cpp` for the full
+ *      async-signal-safe constraints.
+ *   2. ANR watchdog — a background thread that posts a heartbeat to the
+ *      main looper every second. If the heartbeat doesn't fire within
+ *      `anrThresholdMs` (default 5000ms), we synthesise an ANR event with
+ *      the main thread's stack trace.
+ *
+ * The JS layer (`@koderlabs/tasks-sdk-rn-native`) calls:
+ *   enableCrashReporter() — install signal handler
+ *   enableAnrWatchdog(thresholdMs) — start watchdog thread
+ *   getPendingCrashReport() — read JSON file, return as object
+ *   purgePendingCrashReport() — delete file
+ *
+ * The native side never tries to POST events; that's the JS SDK's job.
+ */
+class TasksSdkRnNativeModule : Module() {
+  private companion object {
+    init {
+      System.loadLibrary("tasks_native_crash")
+    }
+    const val CRASH_FILE_NAME = "tasks-native-crash.json"
+  }
+
+  private external fun nativeInstall(crashFilePath: String)
+
+  private var watchdog: AnrWatchdog? = null
+
+  override fun definition() = ModuleDefinition {
+    Name("TasksSdkRnNative")
+
+    AsyncFunction("enableCrashReporter") {
+      val ctx = appContext.reactContext
+        ?: throw IllegalStateException("React context unavailable")
+      val path = File(ctx.filesDir, CRASH_FILE_NAME).absolutePath
+      nativeInstall(path)
+      return@AsyncFunction true
+    }
+
+    AsyncFunction("enableAnrWatchdog") { thresholdMs: Int ->
+      val ctx = appContext.reactContext
+        ?: throw IllegalStateException("React context unavailable")
+      watchdog?.stop()
+      val path = File(ctx.filesDir, "tasks-native-anr.json").absolutePath
+      watchdog = AnrWatchdog(thresholdMs.coerceAtLeast(1000), path).also { it.start() }
+      return@AsyncFunction true
+    }
+
+    AsyncFunction("getPendingCrashReport") {
+      val ctx = appContext.reactContext ?: return@AsyncFunction null
+      val crashFile = File(ctx.filesDir, CRASH_FILE_NAME)
+      val anrFile = File(ctx.filesDir, "tasks-native-anr.json")
+
+      // Native crash takes priority — it killed the app. ANRs are recovered
+      // separately when the watchdog wrote one before the process resumed.
+      val source = when {
+        crashFile.exists() -> crashFile
+        anrFile.exists() -> anrFile
+        else -> return@AsyncFunction null
+      }
+
+      return@AsyncFunction try {
+        val raw = source.readText()
+        val json = JSONObject(raw)
+        json.put("kind", if (source == crashFile) "native_signal" else "anr")
+        jsonToMap(json)
+      } catch (e: Exception) {
+        // Drop corrupted file so we don't keep retrying.
+        source.delete()
+        null
+      }
+    }
+
+    AsyncFunction("purgePendingCrashReport") {
+      val ctx = appContext.reactContext ?: return@AsyncFunction false
+      File(ctx.filesDir, CRASH_FILE_NAME).delete()
+      File(ctx.filesDir, "tasks-native-anr.json").delete()
+      return@AsyncFunction true
+    }
+  }
+
+  /** Convert JSONObject to Map<String, Any> for the Expo bridge. */
+  private fun jsonToMap(o: JSONObject): Map<String, Any?> {
+    val out = mutableMapOf<String, Any?>()
+    for (key in o.keys()) {
+      val v = o.get(key)
+      out[key] = when (v) {
+        is JSONObject -> jsonToMap(v)
+        is JSONArray -> jsonArrayToList(v)
+        JSONObject.NULL -> null
+        else -> v
+      }
+    }
+    return out
+  }
+
+  private fun jsonArrayToList(a: JSONArray): List<Any?> {
+    val out = mutableListOf<Any?>()
+    for (i in 0 until a.length()) {
+      val v = a.get(i)
+      out.add(when (v) {
+        is JSONObject -> jsonToMap(v)
+        is JSONArray -> jsonArrayToList(v)
+        JSONObject.NULL -> null
+        else -> v
+      })
+    }
+    return out
+  }
+}
+
+/**
+ * ANR watchdog — runs on a background thread and posts a heartbeat to the
+ * main looper every second. If `thresholdMs` passes without the heartbeat
+ * being acknowledged, we capture the main thread's stack trace.
+ *
+ * NOT a true Android ANR detector (the OS does that internally and shows
+ * the "App not responding" dialog at 5s for activities). This is a soft
+ * watchdog — useful for instrumentation, less so for production-grade
+ * detection. Real apps should use the Play Store's vitals API for ANR
+ * data when available; this gives signal during development.
+ */
+private class AnrWatchdog(
+  private val thresholdMs: Int,
+  private val outputPath: String,
+) : Thread("tasks-anr-watchdog") {
+  private val mainHandler = Handler(Looper.getMainLooper())
+  @Volatile private var running = true
+  @Volatile private var lastAck = System.currentTimeMillis()
+
+  fun stopWatchdog() { running = false }
+
+  // Avoid clashing with Thread.stop() which is deprecated.
+  fun stop() { stopWatchdog() }
+
+  override fun run() {
+    while (running) {
+      val sent = System.currentTimeMillis()
+      mainHandler.post { lastAck = System.currentTimeMillis() }
+      Thread.sleep(thresholdMs.toLong())
+      if (!running) return
+      // If lastAck hasn't moved since we posted, the main thread is stuck.
+      if (lastAck < sent) {
+        captureAnr()
+        // Wait for main thread to recover before re-arming, otherwise we'd
+        // generate one ANR per cycle.
+        while (running && lastAck < sent) {
+          Thread.sleep(500)
+        }
+      }
+    }
+  }
+
+  private fun captureAnr() {
+    try {
+      val stack = Looper.getMainLooper().thread.stackTrace
+      val sb = StringBuilder()
+      sb.append("{")
+      sb.append("\"platform\":\"android\",")
+      sb.append("\"thresholdMs\":").append(thresholdMs).append(",")
+      sb.append("\"capturedAt\":\"").append(java.util.Date().toString()).append("\",")
+      sb.append("\"stack\":[")
+      for ((i, frame) in stack.withIndex()) {
+        if (i > 0) sb.append(",")
+        sb.append("\"").append(frame.toString().replace("\"", "\\\"")).append("\"")
+      }
+      sb.append("]}")
+      File(outputPath).writeText(sb.toString())
+    } catch (e: Throwable) {
+      // Watchdog must never raise.
+    }
+  }
+}