@matiks/rn-app-state 1.0.0

package/FLOW.md

@@ -0,0 +1,239 @@
+# `@matiks/rn-app-state` — How it works
+
+This document describes how the package exposes **app lifecycle state** (`active` | `background` | `killed`) to React Native via **Nitro Modules** (JSI), and how each platform derives that state.
+
+---
+
+## 1. Purpose in one paragraph
+
+The library ships a React hook, `useNitroAppState`, that returns:
+
+| Field | Meaning |
+|--------|---------|
+| `appState` | Reactive lifecycle: `'active'`, `'background'`, or briefly `'killed'` on cold start when inferring a force-killed previous session. |
+| `wasKilledLastSession` | Boolean from native storage: whether the **previous** run ended without a “clean exit” (persisted flag). |
+| `getStateOnNotification` | Synchronous snapshot of foreground vs background, intended for push/notification handlers. |
+
+On **web**, there is no Nitro bridge; the hook falls back to React Native’s `AppState` API and never reports `killed`.
+
+---
+
+## 2. High-level architecture
+
+Nitro connects JavaScript to **one native HybridObject** registered under the name `AppStateModule`. TypeScript describes the contract; **Nitrogen** generates C++/Swift/Kotlin glue; your implementations live in `ios/HybridAppState.swift` and `android/.../HybridAppState.kt`.
+
+```mermaid
+flowchart TB
+  subgraph JS["JavaScript / TypeScript"]
+    Hook["useNitroAppState"]
+    Spec["AppState.nitro.ts (interface)"]
+    Hook -->|"createHybridObject('AppStateModule')"| NitroJS["react-native-nitro-modules"]
+    Hook -.-> Spec
+  end
+
+  subgraph Nitro["Nitro runtime"]
+    JSI["JSI bridge"]
+    Cxx["Generated C++ HybridAppStateModuleSpec"]
+    NitroJS --> JSI --> Cxx
+  end
+
+  subgraph iOS["iOS"]
+    Swift["HybridAppState.swift"]
+    UIKit["UIKit: UIApplication + NotificationCenter"]
+    UD["UserDefaults (killed/clean flag)"]
+    Cxx <--> Swift
+    Swift --> UIKit
+    Swift --> UD
+  end
+
+  subgraph Android["Android"]
+    Kt["HybridAppState.kt"]
+    PLO["ProcessLifecycleOwner"]
+    Prefs["SharedPreferences"]
+    Cxx <--> Kt
+    Kt --> PLO
+    Kt --> Prefs
+  end
+
+  Cxx --> Swift
+  Cxx --> Kt
+```
+
+**Registration:** `nitro.json` maps the HybridObject name to native classes:
+
+```json
+"autolinking": {
+  "AppStateModule": {
+    "swift": "HybridAppState",
+    "kotlin": "HybridAppState"
+  }
+}
+```
+
+Generated code (e.g. `NitroAppStateAutolinking.swift`) constructs `HybridAppState()` when JS requests `AppStateModule`.
+
+---
+
+## 3. Repository layout (mental model)
+
+| Path | Role |
+|------|------|
+| `src/specs/AppState.nitro.ts` | Type-only Nitro spec: methods and event shapes consumed by TS and codegen. |
+| `src/useNitroAppState/useNitroAppState.native.ts` | Hook for iOS/Android: Nitro module + listener + `killed` UX. |
+| `src/useNitroAppState/useNitroAppState.web.ts` | Web: `AppState` from `react-native`; no `killed`. |
+| `src/useNitroAppState/types.ts` | `AppStateType`, `NitroAppStateResult`. |
+| `ios/HybridAppState.swift` | iOS implementation (UIKit + UserDefaults). |
+| `android/.../HybridAppState.kt` | Android implementation (lifecycle + SharedPreferences). |
+| `nitrogen/generated/**` | Generated bridges — **do not edit**; regenerate with `npm run specs` / `npx nitrogen`. |
+| `nitro.json` | Nitro project config + autolinking map. |
+
+Metro resolves **`.native.ts`** vs **`.web.ts`** when the bundler target is native vs web, so a single export path (`useNitroAppState`) picks the right implementation.
+
+---
+
+## 4. TypeScript contract (`AppStateModule`)
+
+The native module exposes:
+
+- **`getCurrentState(): string`** — Current cached lifecycle string (`'active'` | `'background'`). Not `'killed'`; `killed` is JS-only for UX.
+- **`wasKilledLastSession: boolean`** — Read once per process from persisted flags.
+- **`addListener(cb)`** — Subscribe to `{ state: string }` events when native state changes.
+- **`getStateOnNotification(): string`** — Snapshot at call time (see platform notes below).
+
+---
+
+## 5. Hook flow (native)
+
+### 5.1 Obtaining the module
+
+```mermaid
+sequenceDiagram
+  participant React as React component
+  participant Hook as useNitroAppState
+  participant Nitro as NitroModules
+  participant Native as HybridAppState
+
+  React->>Hook: render
+  Hook->>Nitro: createHybridObject('AppStateModule')
+  Nitro->>Native: construct / wrap singleton
+  Hook->>Native: wasKilledLastSession, getCurrentState()
+  Hook->>Native: addListener(...)
+```
+
+The module is cached in a module-level `_module` and in a `useRef` so the same instance is reused.
+
+### 5.2 Initial `appState` and the `'killed'` special case
+
+Native **never** returns the string `'killed'` from `getCurrentState()`. The hook synthesizes `'killed'` **only** when:
+
+1. `wasKilledLastSession === true`, and  
+2. It uses that as the **initial** `useState` value so the UI can show “resuming after kill” once.
+
+Immediately after mount, if the initial state was `'killed'`, a `setTimeout(0)` runs `getCurrentState()` again and sets React state to the real native value (`'active'` or `'background'`). So `'killed'` is a **transient** first paint, not a streaming lifecycle state from the OS.
+
+```mermaid
+stateDiagram-v2
+  direction LR
+  [*] --> KilledUI: wasKilledLastSession && first paint
+  KilledUI --> ActiveOrBg: setTimeout → getCurrentState()
+  ActiveOrBg --> ActiveOrBg: addListener events
+```
+
+### 5.3 Ongoing updates
+
+`addListener` receives `AppStateChangeEvent` with `state: 'active' | 'background'`. The effect unsubscribes on unmount via `listener.remove()`.
+
+### 5.4 `getStateOnNotification`
+
+Exposed as a **stable** `useCallback` (depends only on `mod`). It calls native `getStateOnNotification()` so push handlers get a fresh snapshot rather than a stale React closure.
+
+---
+
+## 6. iOS (`HybridAppState.swift`)
+
+### 6.1 Live state: UIKit
+
+- **Initial:** `readApplicationState()` reads `UIApplication.shared.applicationState` on the **main thread** and maps `.active` → `"active"`, `.background` / `.inactive` → `"background"`.
+- **Updates:** `NotificationCenter` observers call `updateState` on the main thread:
+  - `didBecomeActive` → `"active"`
+  - `willResignActive` → `"background"` (covers control center, incoming call overlay, etc.)
+  - `didEnterBackground` → `"background"` and `markCleanExit()`
+  - `willTerminate` → `markCleanExit()`
+
+`currentState` is only mutated on the main thread. `getCurrentState()` uses `Thread.isMainThread` / `DispatchQueue.main.sync` so callers from arbitrary Nitro threads still read consistent main-thread state.
+
+### 6.2 `wasKilledLastSession`: UserDefaults
+
+- Key stores whether the last run **exited cleanly** (background or terminate handler set the flag).
+- On launch: if the app had run before and the flag says **not** clean, `wasKilledLastSession` is `true`.
+- Then the flag is reset to “not clean” until the next clean exit.
+
+### 6.3 `getStateOnNotification` on iOS
+
+Calls `readApplicationState()` on the main thread — i.e. **live `UIApplication` state** at invocation time, not only the cached `currentState`.
+
+---
+
+## 7. Android (`HybridAppState.kt`)
+
+### 7.1 Live state: `ProcessLifecycleOwner`
+
+- Observer on `onStart` → `"active"`, `onStop` → `"background"` (and `markCleanExit()` on stop).
+- `currentState` is `@Volatile` for safe reads from any thread; `getCurrentState()` returns it directly.
+
+### 7.2 `wasKilledLastSession`: SharedPreferences
+
+Same **clean-exit** idea as iOS: `hasLaunchedBefore` + `didExitCleanly` in app prefs.
+
+### 7.3 `getStateOnNotification` on Android
+
+Returns the module’s **`currentState`** (updated by process lifecycle), not a separate system API.
+
+---
+
+## 8. Web (`useNitroAppState.web.ts`)
+
+- Uses `AppState` from `react-native` (e.g. visibility-based behavior under `react-native-web`).
+- Maps everything except `'active'` to `'background'`.
+- `wasKilledLastSession` is always `false`; `'killed'` is never used.
+
+---
+
+## 9. Codegen and native load
+
+- **`nitro.json`** sets namespaces and links `AppStateModule` → `HybridAppState`.
+- **`npm run specs`** runs Nitrogen (`npx nitrogen@0.33.9`) to refresh `nitrogen/generated/**` when the spec or config changes.
+- Android loads the C++ library in generated `NitroAppStateOnLoad` (`System.loadLibrary("NitroAppState")`); iOS links via CocoaPods / generated autolinking.
+
+---
+
+## 10. End-to-end: user backgrounds the app (native)
+
+```mermaid
+sequenceDiagram
+  participant OS as OS lifecycle
+  participant Native as HybridAppState
+  participant JSI as JSI / Nitro
+  participant JS as useNitroAppState
+
+  OS->>Native: e.g. willResignActive / onStop
+  Native->>Native: updateState("background")
+  Native->>JSI: listener({ state: "background" })
+  JSI->>JS: setAppState("background")
+  JS->>JS: React re-render
+```
+
+---
+
+## 11. Summary table
+
+| Layer | Responsibility |
+|--------|----------------|
+| `AppState.nitro.ts` | Contract for JS and codegen. |
+| `useNitroAppState.native.ts` | Wire Nitro + React; synthesize brief `'killed'` UX; subscribe/unsubscribe. |
+| `useNitroAppState.web.ts` | RN `AppState` only. |
+| iOS `HybridAppState` | UIKit notifications + `UIApplication` state; UserDefaults for kill inference. |
+| Android `HybridAppState` | `ProcessLifecycleOwner`; SharedPreferences for kill inference. |
+| Nitrogen output | JSI/C++ bridges and autolinking factories — keep in sync with spec via Nitrogen. |
+
+This should be enough to navigate the codebase, extend the spec safely, or debug lifecycle mismatches per platform.

package/NitroAppState.podspec

@@ -0,0 +1,31 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NitroAppState"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/matiks-com/rn-app-state.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    # Implementation (Swift)
+    "ios/**/*.{swift}",
+    # Autolinking/Registration (Objective-C++)
+    "ios/**/*.{m,mm}",
+    # Implementation (C++ objects)
+    "cpp/**/*.{hpp,cpp}",
+  ]
+
+  load 'nitrogen/generated/ios/NitroAppState+autolinking.rb'
+  add_nitrogen_files(s)
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,72 @@
+# @matiks/rn-app-state
+
+Nitro-powered native app state module for React Native. Provides a reactive hook that tracks app lifecycle state (`active`, `background`, `killed`) using native code via JSI -- zero bridge overhead.
+
+## Features
+
+- **Reactive hook** -- `useNitroAppState()` triggers re-renders on state changes
+- **Native lifecycle observation** -- iOS (NotificationCenter) + Android (ProcessLifecycleOwner)
+- **Kill detection** -- `wasKilledLastSession` flag detected on cold start via persisted clean-exit flag
+- **Notification support** -- `getStateOnNotification()` returns the app state at the moment of a push/silent notification
+- **Web fallback** -- Uses React Native's AppState API on web (no Nitro required)
+- **Thread-safe** -- Both iOS and Android implementations handle concurrent access correctly
+
+## Installation
+
+```bash
+yarn add @matiks/rn-app-state
+cd ios && pod install
+```
+
+## Usage
+
+```tsx
+import { useNitroAppState } from '@matiks/rn-app-state'
+
+function MyComponent() {
+  const { appState, wasKilledLastSession, getStateOnNotification } = useNitroAppState()
+
+  useEffect(() => {
+    if (appState === 'active') {
+      // Refresh data, resume animations, etc.
+    }
+  }, [appState])
+
+  return <Text>App State: {appState}</Text>
+}
+```
+
+## API
+
+### `useNitroAppState()`
+
+Returns:
+
+| Property | Type | Description |
+|---|---|---|
+| `appState` | `'active' \| 'background' \| 'killed'` | Current app lifecycle state. Reactive. |
+| `wasKilledLastSession` | `boolean` | Whether the app was force-killed in the previous session. |
+| `getStateOnNotification` | `() => AppStateType` | Synchronous call to get native state at notification receipt time. |
+
+### States
+
+- **`active`** -- App is in the foreground and interactive
+- **`background`** -- App is in the background (iOS `inactive` is merged into `background`)
+- **`killed`** -- Previous session was force-terminated (reported briefly on cold start, then transitions to `active`)
+
+## Requirements
+
+- React Native 0.76+
+- `react-native-nitro-modules` 0.33.x
+- iOS 16.0+
+- Android minSdk 23+
+
+## Development
+
+```bash
+# Generate nitrogen bridge code
+yarn specs
+
+# Type check
+yarn typecheck
+```

package/android/CMakeLists.txt

@@ -0,0 +1,29 @@
+project(NitroAppState)
+cmake_minimum_required(VERSION 3.9.0)
+
+set (PACKAGE_NAME NitroAppState)
+set (CMAKE_VERBOSE_MAKEFILE ON)
+set (CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED
+        src/main/cpp/cpp-adapter.cpp
+)
+
+# Add Nitrogen specs
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroAppState+autolinking.cmake)
+
+# Set up local includes
+include_directories(
+        "src/main/cpp"
+        "../cpp"
+)
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android
+)

package/android/build.gradle

@@ -0,0 +1,140 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.13.2"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: 'org.jetbrains.kotlin.android'
+apply from: '../nitrogen/generated/android/NitroAppState+autolinking.gradle'
+apply from: "./fix-prefab.gradle"
+
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroAppState_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroAppState_" + name]).toInteger()
+}
+
+android {
+  namespace "com.margelo.nitro.appstate"
+
+  ndkVersion getExtOrDefault("ndkVersion")
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+            "META-INF",
+            "META-INF/**",
+            "**/libc++_shared.so",
+            "**/libNitroModules.so",
+            "**/libfbjni.so",
+            "**/libjsi.so",
+            "**/libfolly_json.so",
+            "**/libfolly_runtime.so",
+            "**/libglog.so",
+            "**/libhermes.so",
+            "**/libhermes-executor-debug.so",
+            "**/libhermes_executor.so",
+            "**/libreactnative.so",
+            "**/libreactnativejni.so",
+            "**/libturbomodulejsijni.so",
+            "**/libreact_nativemodule_core.so",
+            "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += [
+          // React Codegen files
+          "${project.buildDir}/generated/source/codegen/java"
+        ]
+      }
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+
+dependencies {
+  //noinspection GradleDynamicVersion
+  compileOnly "com.facebook.react:react-native:+"
+
+  // Add a dependency on NitroModules
+  compileOnly project(":react-native-nitro-modules")
+
+  // ProcessLifecycleOwner for app lifecycle observation
+  implementation "androidx.lifecycle:lifecycle-process:2.8.7"
+  implementation "androidx.lifecycle:lifecycle-common:2.8.7"
+}

package/android/fix-prefab.gradle

@@ -0,0 +1,51 @@
+tasks.configureEach { task ->
+  // Make sure that we generate our prefab publication file only after having built the native library
+  // so that not a header publication file, but a full configuration publication will be generated, which
+  // will include the .so file
+
+  def prefabConfigurePattern = ~/^prefab(.+)ConfigurePackage$/
+  def matcher = task.name =~ prefabConfigurePattern
+  if (matcher.matches()) {
+    def variantName = matcher[0][1]
+    task.outputs.upToDateWhen { false }
+    task.dependsOn("externalNativeBuild${variantName}")
+  }
+}
+
+afterEvaluate {
+  def abis = reactNativeArchitectures()
+  rootProject.allprojects.each { proj ->
+    if (proj === rootProject) return
+
+    def dependsOnThisLib = proj.configurations.findAll { it.canBeResolved }.any { config ->
+      config.dependencies.any { dep ->
+        dep.group == project.group && dep.name == project.name
+      }
+    }
+    if (!dependsOnThisLib && proj != project) return
+
+    if (!proj.plugins.hasPlugin('com.android.application') && !proj.plugins.hasPlugin('com.android.library')) {
+      return
+    }
+
+    def variants = proj.android.hasProperty('applicationVariants') ? proj.android.applicationVariants : proj.android.libraryVariants
+    // Touch the prefab_config.json files to ensure that in ExternalNativeJsonGenerator.kt we will re-trigger the prefab CLI to
+    // generate a libnameConfig.cmake file that will contain our native library (.so).
+    // See this condition: https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:build-system/gradle-core/src/main/java/com/android/build/gradle/tasks/ExternalNativeJsonGenerator.kt;l=207-219?q=createPrefabBuildSystemGlue
+    variants.all { variant ->
+      def variantName = variant.name
+      abis.each { abi ->
+        def searchDir = new File(proj.projectDir, ".cxx/${variantName}")
+        if (!searchDir.exists()) return
+        def matches = []
+        searchDir.eachDir { randomDir ->
+          def prefabFile = new File(randomDir, "${abi}/prefab_config.json")
+          if (prefabFile.exists()) matches << prefabFile
+        }
+        matches.each { prefabConfig ->
+          prefabConfig.setLastModified(System.currentTimeMillis())
+        }
+      }
+    }
+  }
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+NitroAppState_kotlinVersion=2.1.20
+NitroAppState_minSdkVersion=23
+NitroAppState_targetSdkVersion=36
+NitroAppState_compileSdkVersion=36
+NitroAppState_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

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

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,6 @@
+#include <jni.h>
+#include "NitroAppStateOnLoad.hpp"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return margelo::nitro::appstate::initialize(vm);
+}