@g9tm/lynxcontrols-native 0.0.0-stage → 1.4.0

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @g9tm/lynxcontrols-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Android and iOS platform layer for G9: two Lynx native modules and one element (`<g9-video>`), linked into a host by
+**Lynx Autolink** from `node_modules`, plus their JS adapters.
+
+| Module | JS adapter | Android (Kotlin) | iOS (Objective-C) |
+| --- | --- | --- | --- |
+| `G9SqliteModule` | `createNativeSqliteDriver()` | androidx.sqlite `BundledSQLiteDriver` 2.7.1 | system `sqlite3` (iOS 15+, serial queue per session, `sqlite3_interrupt`) |
+| `G9HostModule` | `createNativeHostServices()` | `SharedPreferences`, `moveTaskToBack`, `InputMethodManager`, haptics, insets, `appDataDirectory()` = `filesDir` | `NSUserDefaults` suite, `resignFirstResponder`, `UIImpactFeedbackGenerator`, safe-area insets, `appDataDirectory()` = `Library` |
+| `<g9-video>` element | `createNativeMediaProvider()` (`@g9tm/lynxcontrols-native/media`) | `G9VideoUI`: Media3 ExoPlayer 1.8.0 into a `TextureView` (opacity fades work); register `G9VideoBehaviors.create()` | `G9VideoUI`: `AVQueuePlayer` + `AVPlayerLooper` in an `AVPlayerLayer`; self-registers (`LYNX_REGISTER_UI`) |
+
+```ts
+import { createG9Sqlite, singleFileDatabaseLocator } from '@g9tm/lynxcontrols-sqlite';
+import { createNativeHostServices, createNativeSqliteDriver } from '@g9tm/lynxcontrols-native';
+
+const { host, preferences, appDataDirectory } = createNativeHostServices();
+const root = await appDataDirectory(); // MAUI FileSystem.AppDataDirectory: the MAUI app's database stays found
+const db = createG9Sqlite({ driver: createNativeSqliteDriver(), locator: singleFileDatabaseLocator(`${root}/g9.db`), /* … */ });
+// <G9Provider services={{ clock, host, preferences }}>
+```
+
+## How it works
+
+- **Video** (the intro carousel's `services.media`). `<g9-video>` props: `src`, `paused`, `loop`, `muted`,
+  `start-seconds`, `near-end-seconds`, `object-fit`; events `ready`, `nearend`, `looped`, `error`. The provider's
+  player renders it with reactive props (no UI-method calls) and unmounts it on `dispose()`, which releases the native
+  player. `resolve()` maps bundled assets with `G9HostModule.assetUri` (`not-found` when the app does not ship the
+  file). The near-end/loop and start-seek rules are the platform-free cores `video/core/G9VideoCore.kt` and
+  `ios/src/core/G9VideoCore.m`, tested on the JVM and on Linux.
+
+- **Contract.** The driver passes the shared contract `@g9tm/lynxcontrols-sqlite/contract/cases.json` (27 cases): on the JVM through
+  the Kotlin core (`npm run test:android-jvm`), and in JS through the module protocol (`src/native.test.ts`).
+- **Threads.** One single-thread executor per open database with a bounded queue (256; overflow → `busy`). Replies
+  are envelopes `{ ok, value | error }`, so `G9SqliteError` fields (`code`, `sqliteCode`, `sql`,
+  `completedStatements`) survive the bridge.
+- **Cancellation.** A batch aborted while queued in JS never reaches native code.
+  - Aborting a running batch calls `interrupt(session)`.
+  - iOS: `sqlite3_interrupt` stops the statement, and the batch fails with `interrupted`.
+  - Android: androidx connections have no interrupt, so the statement finishes (`capabilities().interrupt === false`).
+- **Transport** (`plan/specs/06` §6). `columnar` (default): cell tags, float64 numbers and blob bytes as ArrayBuffers,
+  text as strings. `rows`: tagged cells. Choose with `createNativeSqliteDriver({ transport })`.
+  `contract/transport-golden.json` pins the bytes: the Kotlin encoder writes it, and the JS decoder test reads it.
+- **Values.** Safe integers cross as numbers, others as `{ int64 }`, BLOBs as ArrayBuffer. NUL in text, `NaN` and
+  `undefined` are rejected with `misuse`, as on every driver.
+
+## Layout
+
+```text
+types/platform-native-module.d.ts   codegen input (`npm run codegen` → generated/, android/…/generated, ios/src/generated;
+                                    then scripts/android-bridge-types.mjs --fix gives the Android specs the parameter
+                                    types Lynx's bridge accepts — never run the bare generator)
+scripts/android-bridge-types.mjs    `--fix` after codegen; without it, the check (`npm run check:android-types`)
+android/src/main/java/com/g9lynx/g9native/
+  sqlite/core/      pure Kotlin: G9SqliteCore, G9SqliteService (executors), G9SqliteTransport, values/errors
+  sqlite/androidx/  AndroidxSqlEngine (BundledSQLiteDriver)
+  host/core/        G9PreferencesCore
+  G9SqliteModule.kt, G9HostModule.kt, G9Bridge.kt   Lynx modules (kapt + lynx-processor → LynxLibraryProviderImpl)
+android/src/test/   JVM tests: contract runner, core, service, transport golden, preferences
+ios/src/core/       portable Objective-C (Foundation + sqlite3): G9SqliteCore, G9SqliteTransport, G9PreferencesCore
+ios/src/            G9SqliteModule.m, G9HostModule.m (dispatch queues, UIKit); register them on the host's LynxConfig
+ios/Tests/          G9NativeTestSuite (XCTest on a simulator; Linux harness in Tests/linux)
+jvm/                JVM-only Gradle build of the core + tests (no Android SDK needed)
+android-check/      cloud compile check of module + reference host against the published Lynx 4.1.0 classes, and
+                    LynxBridgeSignatureTest: every @LynxMethod through Lynx's own LynxMethodWrapper
+```
+
+The Android package is `com.g9lynx.g9native`, not `com.g9lynx.native`: `native` is a reserved word in Java, so the
+generated Java specs could not compile under that name.
+
+The native identifiers are internal and did not follow the npm rename to `@g9tm/lynxcontrols-native` (decision D12):
+the Android package `com.g9lynx.g9native`, the iOS pod `g9lynx-native`, the module classes `G9SqliteModule` and
+`G9HostModule`, and the preference store `g9lynx.preferences` keep their names, so hosts and stored data are not
+affected. The pod's version follows the package version (= the pinned G9MAUIControls version).
+
+## Commands
+
+| Command | What it proves |
+| --- | --- |
+| `npm run test:android-jvm` | Kotlin core: contract 27/27 over both transports (JDBC engine), unit tests, JaCoCo gate (lines ≥ 95 %, branches ≥ 85 %) |
+| `gradle -p packages/native/jvm check -Pg9.bundled=true` | The same on androidx `BundledSQLiteDriver` (needs Google Maven) |
+| `npm run check:android-module` | Module and host compile against Lynx 4.1.0, and the Autolink provider is generated |
+| `npm run test:ios-core` | iOS core on Linux (clang + GNUstep): contract 27/27 × 2, golden byte-identical with Kotlin, interrupt, ARC syntax |
+| `npm run bench:transport` | JS decode cost of `columnar` vs `rows` |
+
+Host integration: [`docs/integration/android.md`](../../docs/integration/android.md) and
+[`docs/integration/ios.md`](../../docs/integration/ios.md) (reference hosts: `apps/android-host`, `apps/ios-host`).

package/android/build.gradle.kts

@@ -0,0 +1,45 @@
+// @g9tm/lynxcontrols-native for Android (plan/specs/06 §4, specs/08 §3). Linked into a host by Lynx Autolink from
+// node_modules; the host's settings supply the plugin versions (AGP 8.13.0, Kotlin 2.3.20).
+plugins {
+  id("com.android.library")
+  id("org.jetbrains.kotlin.android")
+  id("org.jetbrains.kotlin.kapt")
+}
+
+android {
+  namespace = "com.g9lynx.g9native"
+  compileSdk = 36
+
+  defaultConfig {
+    minSdk = 26
+    consumerProguardFiles("consumer-rules.pro")
+  }
+
+  compileOptions {
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+  }
+
+  testOptions { unitTests.isReturnDefaultValues = true }
+}
+
+kotlin { jvmToolchain(17) }
+
+val lynx = "4.1.0"
+
+dependencies {
+  compileOnly("org.lynxsdk.lynx:lynx:$lynx")
+  compileOnly("org.lynxsdk.lynx:service-api:$lynx")
+  kapt("org.lynxsdk.lynx:lynx-processor:$lynx")
+  // The generated specs import androidx.annotation and lynx-processor's output uses @Keep, but Lynx's POMs declare it
+  // at runtime scope only: without this line kapt depends on androidx.sqlite / media3 bringing it in transitively.
+  compileOnly("androidx.annotation:annotation:1.9.1")
+  implementation("androidx.sqlite:sqlite-bundled:2.7.1")
+  // <g9-video> (video/G9VideoUI.kt): ExoPlayer drawing into a TextureView. Google Maven only.
+  implementation("androidx.media3:media3-exoplayer:1.8.0")
+
+  // The JVM contract suite also runs as Android local unit tests (same sources as ../jvm).
+  testImplementation("junit:junit:4.13.2")
+  testImplementation("org.json:json:20250517")
+  testImplementation("org.xerial:sqlite-jdbc:3.50.3.0")
+}

package/android/consumer-rules.pro

@@ -0,0 +1,3 @@
+# Lynx looks modules up by annotation name; keep them and their methods.
+-keep @com.lynx.jsbridge.LynxNativeModule class * { *; }
+-keepclassmembers class * { @com.lynx.jsbridge.LynxMethod *; }

package/android/src/main/AndroidManifest.xml

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

package/android/src/main/java/com/g9lynx/g9native/G9Bridge.kt

@@ -0,0 +1,67 @@
+package com.g9lynx.g9native
+
+import com.lynx.react.bridge.Callback
+import com.lynx.react.bridge.JavaOnlyArray
+import com.lynx.react.bridge.JavaOnlyMap
+import com.lynx.react.bridge.ReadableArray
+import com.lynx.react.bridge.ReadableMap
+
+/**
+ * Copies between Lynx bridge containers and the plain Kotlin data the cores speak (`Map`, `List`, `String`, `Double`,
+ * `Boolean`, `ByteArray` ⇄ ArrayBuffer, `null`). Everything else of the modules is plain JVM code.
+ */
+internal object G9Bridge {
+  fun map(value: Any?): Map<*, *> =
+    when (value) {
+      is ReadableMap -> value.toHashMap()
+      is Map<*, *> -> value
+      else -> emptyMap<String, Any?>()
+    }
+
+  fun list(value: Any?): List<*> =
+    when (value) {
+      is ReadableArray -> value.toArrayList()
+      is List<*> -> value
+      else -> emptyList<Any?>()
+    }
+
+  fun toMap(value: Map<*, *>): JavaOnlyMap {
+    val out = JavaOnlyMap()
+    for ((k, v) in value) {
+      val key = k as String
+      when (v) {
+        null -> out.putNull(key)
+        is Boolean -> out.putBoolean(key, v)
+        is Number -> out.putDouble(key, v.toDouble())
+        is String -> out.putString(key, v)
+        is ByteArray -> out.putByteArray(key, v)
+        is Map<*, *> -> out.putMap(key, toMap(v))
+        is List<*> -> out.putArray(key, toArray(v))
+        else -> out.putString(key, v.toString())
+      }
+    }
+    return out
+  }
+
+  fun toArray(value: List<*>): JavaOnlyArray {
+    val out = JavaOnlyArray()
+    for (v in value) {
+      when (v) {
+        null -> out.pushNull()
+        is Boolean -> out.pushBoolean(v)
+        is Number -> out.pushDouble(v.toDouble())
+        is String -> out.pushString(v)
+        is ByteArray -> out.pushByteArray(v)
+        is Map<*, *> -> out.pushMap(toMap(v))
+        is List<*> -> out.pushArray(toArray(v))
+        else -> out.pushString(v.toString())
+      }
+    }
+    return out
+  }
+
+  /** Invokes a JS callback with one envelope (Lynx marshals the call to the JS thread). */
+  fun reply(callback: Callback?, envelope: Map<String, Any?>) {
+    callback?.invoke(toMap(envelope))
+  }
+}

package/android/src/main/java/com/g9lynx/g9native/G9HostModule.kt

@@ -0,0 +1,159 @@
+package com.g9lynx.g9native
+
+import android.app.Activity
+import android.content.Context
+import android.content.ContextWrapper
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.view.HapticFeedbackConstants
+import android.view.View
+import android.view.WindowManager
+import android.view.inputmethod.InputMethodManager
+import com.g9lynx.g9native.generated.G9HostModuleSpec
+import com.g9lynx.g9native.host.core.G9PreferenceBackend
+import com.g9lynx.g9native.host.core.G9PreferencesCore
+import com.lynx.jsbridge.LynxMethod
+import com.lynx.jsbridge.LynxNativeModule
+import com.lynx.react.bridge.Callback
+import com.lynx.tasm.behavior.LynxContext
+
+/**
+ * `NativeModules.G9HostModule` (plan/specs/06 §7): preferences in `SharedPreferences` (typed int/string, like MAUI's
+ * `Preferences`), move-to-back when back is unhandled, hide keyboard, haptic tick, soft-input mode, safe-area insets.
+ * UI calls run on the main thread.
+ */
+@LynxNativeModule(name = "G9HostModule")
+class G9HostModule(private val lynxContext: LynxContext) : G9HostModuleSpec(lynxContext) {
+  private val main = Handler(Looper.getMainLooper())
+
+  private val preferences: G9PreferencesCore by lazy {
+    val prefs = lynxContext.applicationContext.getSharedPreferences("g9lynx.preferences", Context.MODE_PRIVATE)
+    G9PreferencesCore(
+      object : G9PreferenceBackend {
+        override fun all(): Map<String, *> = prefs.all
+
+        override fun putInt(key: String, value: Int) = prefs.edit().putInt(key, value).apply()
+
+        override fun putString(key: String, value: String) = prefs.edit().putString(key, value).apply()
+
+        override fun remove(key: String) = prefs.edit().remove(key).apply()
+      },
+    )
+  }
+
+  private fun activity(): Activity? {
+    var context: Context? = lynxContext
+    while (context is ContextWrapper) {
+      if (context is Activity) return context
+      context = context.baseContext
+    }
+    return null
+  }
+
+  private fun onMain(block: (Activity) -> Unit) {
+    val activity = activity() ?: return
+    main.post { if (!activity.isFinishing) block(activity) }
+  }
+
+  @LynxMethod
+  override fun capabilities(callback: Callback?) =
+    G9Bridge.reply(
+      callback,
+      G9PreferencesCore.ok(mapOf("haptics" to true, "softInputMode" to true, "video" to true, "platform" to "android")),
+    )
+
+  @LynxMethod
+  override fun getPreference(key: String, callback: Callback?) =
+    G9Bridge.reply(callback, G9PreferencesCore.envelope { preferences.get(key) })
+
+  @LynxMethod
+  override fun setPreference(key: String, kind: String, value: String?, callback: Callback?) =
+    G9Bridge.reply(callback, G9PreferencesCore.envelope { preferences.set(key, kind, value) })
+
+  @LynxMethod
+  override fun preferenceEntries(prefix: String, callback: Callback?) =
+    G9Bridge.reply(callback, G9PreferencesCore.envelope { preferences.entries(prefix) })
+
+  @LynxMethod
+  override fun safeInsets(callback: Callback?) {
+    val activity = activity()
+    if (activity == null) {
+      G9Bridge.reply(callback, G9PreferencesCore.ok(mapOf("top" to 0, "end" to 0, "bottom" to 0, "start" to 0)))
+      return
+    }
+    main.post {
+      val density = activity.resources.displayMetrics.density
+      val insets = activity.window.decorView.rootWindowInsets
+      val rtl = activity.window.decorView.layoutDirection == View.LAYOUT_DIRECTION_RTL
+      @Suppress("DEPRECATION")
+      val left = (insets?.systemWindowInsetLeft ?: 0) / density
+      @Suppress("DEPRECATION")
+      val right = (insets?.systemWindowInsetRight ?: 0) / density
+      @Suppress("DEPRECATION")
+      val value =
+        mapOf(
+          "top" to (insets?.systemWindowInsetTop ?: 0) / density,
+          "bottom" to (insets?.systemWindowInsetBottom ?: 0) / density,
+          "start" to if (rtl) right else left,
+          "end" to if (rtl) left else right,
+        )
+      G9Bridge.reply(callback, G9PreferencesCore.ok(value))
+    }
+  }
+
+  @LynxMethod
+  override fun moveToBack() = onMain { it.moveTaskToBack(true) }
+
+  @LynxMethod
+  override fun hideKeyboard() =
+    onMain { activity ->
+      val focus = activity.currentFocus ?: activity.window.decorView
+      val imm = activity.getSystemService(Context.INPUT_METHOD_SERVICE) as InputMethodManager
+      imm.hideSoftInputFromWindow(focus.windowToken, 0)
+      focus.clearFocus()
+    }
+
+  @LynxMethod
+  override fun setSoftInputMode(mode: String) =
+    onMain { activity ->
+      @Suppress("DEPRECATION")
+      activity.window.setSoftInputMode(
+        if (mode == "pan") WindowManager.LayoutParams.SOFT_INPUT_ADJUST_PAN else WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE,
+      )
+    }
+
+  /** `Context.filesDir`: the directory MAUI `FileSystem.AppDataDirectory` returns on Android, so a MAUI app's files stay put. */
+  @LynxMethod
+  override fun appDataDirectory(callback: Callback?) =
+    G9Bridge.reply(callback, G9PreferencesCore.ok(lynxContext.applicationContext.filesDir.absolutePath))
+
+  /** `asset:///<path>` for a file under the APK's `assets/` (Fresco and Media3 open that scheme); `not-found` otherwise. */
+  @LynxMethod
+  override fun assetUri(path: String, callback: Callback?) {
+    val clean = path.trimStart('/')
+    val exists =
+      clean.isNotEmpty() &&
+        try {
+          lynxContext.applicationContext.assets.open(clean).close()
+          true
+        } catch (_: java.io.IOException) {
+          false
+        }
+    G9Bridge.reply(
+      callback,
+      if (exists) {
+        G9PreferencesCore.ok("asset:///$clean")
+      } else {
+        mapOf("ok" to false, "error" to mapOf("code" to "not-found", "message" to "The app ships no asset \"$path\"."))
+      },
+    )
+  }
+
+  @LynxMethod
+  override fun hapticTick() =
+    onMain { activity ->
+      val constant = if (Build.VERSION.SDK_INT >= 27) HapticFeedbackConstants.KEYBOARD_RELEASE else HapticFeedbackConstants.KEYBOARD_TAP
+      activity.window.decorView.performHapticFeedback(constant)
+    }
+}

package/android/src/main/java/com/g9lynx/g9native/G9SqliteModule.kt

@@ -0,0 +1,49 @@
+package com.g9lynx.g9native
+
+import com.g9lynx.g9native.generated.G9SqliteModuleSpec
+import com.g9lynx.g9native.sqlite.androidx.AndroidxSqlEngine
+import com.g9lynx.g9native.sqlite.core.G9SqliteCore
+import com.g9lynx.g9native.sqlite.core.G9SqliteService
+import com.lynx.jsbridge.LynxMethod
+import com.lynx.jsbridge.LynxNativeModule
+import com.lynx.react.bridge.Callback
+import com.lynx.react.bridge.ReadableArray
+import com.lynx.react.bridge.ReadableMap
+import com.lynx.tasm.behavior.LynxContext
+
+/**
+ * `NativeModules.G9SqliteModule` (plan/specs/06 §4): the Lynx face of [G9SqliteService] over androidx.sqlite
+ * `BundledSQLiteDriver`. One process-wide service, so every LynxView of the app shares the open databases.
+ */
+@LynxNativeModule(name = "G9SqliteModule")
+class G9SqliteModule(context: LynxContext) : G9SqliteModuleSpec(context) {
+  companion object {
+    val service: G9SqliteService by lazy { G9SqliteService(G9SqliteCore(AndroidxSqlEngine())) }
+  }
+
+  @LynxMethod
+  override fun capabilities(callback: Callback?) = service.capabilities { G9Bridge.reply(callback, it) }
+
+  @LynxMethod
+  override fun open(options: ReadableMap?, callback: Callback?) = service.open(G9Bridge.map(options)) { G9Bridge.reply(callback, it) }
+
+  @LynxMethod
+  override fun run(session: String, statements: ReadableArray?, options: ReadableMap?, callback: Callback?) =
+    service.run(session, G9Bridge.list(statements), G9Bridge.map(options)) { G9Bridge.reply(callback, it) }
+
+  @LynxMethod
+  override fun begin(session: String, mode: String, callback: Callback?) = service.begin(session, mode) { G9Bridge.reply(callback, it) }
+
+  @LynxMethod
+  override fun commit(tx: String, callback: Callback?) = service.commit(tx) { G9Bridge.reply(callback, it) }
+
+  @LynxMethod
+  override fun rollback(tx: String, callback: Callback?) = service.rollback(tx) { G9Bridge.reply(callback, it) }
+
+  @LynxMethod
+  override fun close(session: String, callback: Callback?) = service.close(session) { G9Bridge.reply(callback, it) }
+
+  /** androidx connections expose no `sqlite3_interrupt`: a running statement finishes (capabilities say so). */
+  @LynxMethod
+  override fun interrupt(session: String) = Unit
+}

package/android/src/main/java/com/g9lynx/g9native/generated/G9HostModuleSpec.java

@@ -0,0 +1,48 @@
+// Generated by @lynx-js/autolink-codegen. Do not edit.
+// Parameter types: scripts/android-bridge-types.mjs --fix (Lynx's bridge rejects the generator's Object).
+package com.g9lynx.g9native.generated;
+
+import androidx.annotation.Nullable;
+import com.lynx.jsbridge.LynxContextModule;
+import com.lynx.jsbridge.LynxMethod;
+import com.lynx.react.bridge.Callback;
+import com.lynx.tasm.behavior.LynxContext;
+
+public abstract class G9HostModuleSpec extends LynxContextModule {
+  public G9HostModuleSpec(LynxContext context) {
+    super(context);
+  }
+
+  @LynxMethod
+  public abstract void capabilities(Callback callback);
+
+  @LynxMethod
+  public abstract void getPreference(String key, Callback callback);
+
+  @LynxMethod
+  public abstract void setPreference(String key, String kind, @Nullable String value, Callback callback);
+
+  @LynxMethod
+  public abstract void preferenceEntries(String prefix, Callback callback);
+
+  @LynxMethod
+  public abstract void safeInsets(Callback callback);
+
+  @LynxMethod
+  public abstract void moveToBack();
+
+  @LynxMethod
+  public abstract void hideKeyboard();
+
+  @LynxMethod
+  public abstract void setSoftInputMode(String mode);
+
+  @LynxMethod
+  public abstract void hapticTick();
+
+  @LynxMethod
+  public abstract void appDataDirectory(Callback callback);
+
+  @LynxMethod
+  public abstract void assetUri(String path, Callback callback);
+}

package/android/src/main/java/com/g9lynx/g9native/generated/G9SqliteModuleSpec.java

@@ -0,0 +1,41 @@
+// Generated by @lynx-js/autolink-codegen. Do not edit.
+// Parameter types: scripts/android-bridge-types.mjs --fix (Lynx's bridge rejects the generator's Object).
+package com.g9lynx.g9native.generated;
+
+import androidx.annotation.Nullable;
+import com.lynx.jsbridge.LynxContextModule;
+import com.lynx.jsbridge.LynxMethod;
+import com.lynx.react.bridge.Callback;
+import com.lynx.react.bridge.ReadableArray;
+import com.lynx.react.bridge.ReadableMap;
+import com.lynx.tasm.behavior.LynxContext;
+
+public abstract class G9SqliteModuleSpec extends LynxContextModule {
+  public G9SqliteModuleSpec(LynxContext context) {
+    super(context);
+  }
+
+  @LynxMethod
+  public abstract void capabilities(Callback callback);
+
+  @LynxMethod
+  public abstract void open(ReadableMap options, Callback callback);
+
+  @LynxMethod
+  public abstract void run(String session, ReadableArray statements, ReadableMap options, Callback callback);
+
+  @LynxMethod
+  public abstract void begin(String session, String mode, Callback callback);
+
+  @LynxMethod
+  public abstract void commit(String tx, Callback callback);
+
+  @LynxMethod
+  public abstract void rollback(String tx, Callback callback);
+
+  @LynxMethod
+  public abstract void close(String session, Callback callback);
+
+  @LynxMethod
+  public abstract void interrupt(String session);
+}

package/android/src/main/java/com/g9lynx/g9native/host/core/G9PreferencesCore.kt

@@ -0,0 +1,100 @@
+package com.g9lynx.g9native.host.core
+
+/** Where preferences live: Android `SharedPreferences` in the host module, a map in tests. Values are `Int` or `String`. */
+interface G9PreferenceBackend {
+  fun all(): Map<String, *>
+
+  fun putInt(key: String, value: Int)
+
+  fun putString(key: String, value: String)
+
+  fun remove(key: String)
+}
+
+/** A preference-store failure with the G9 error code the JS side raises (`preference-key`, `preference-value`). */
+class G9PreferenceException(val code: String, message: String) : RuntimeException(message)
+
+/**
+ * The `G9PreferenceStore` operations of `G9HostModule` (plan/specs/06 §7) as bridge data: typed values (a 32-bit
+ * integer is not readable as a string and vice versa, as in MAUI), `null` string removes, prefix enumeration for
+ * hydration. Keys arrive already prefixed by `createPreferences`.
+ */
+class G9PreferencesCore(private val backend: G9PreferenceBackend) {
+  private fun checkKey(key: String) {
+    if (key.isEmpty()) throw G9PreferenceException("preference-key", "A preference key must be a non-empty string.")
+  }
+
+  /** `{ type: 'int' | 'string', value }`, or `null` when absent. */
+  fun get(key: String): Map<String, Any>? =
+    when (val value = backend.all()[key]) {
+      is Int -> mapOf("type" to "int", "value" to value.toDouble())
+      is String -> mapOf("type" to "string", "value" to value)
+      else -> null
+    }
+
+  /** `kind`: `int` (value = decimal text of a 32-bit integer), `string` (`null` removes) or `remove`. */
+  fun set(key: String, kind: String, value: String?) {
+    checkKey(key)
+    when (kind) {
+      "int" -> {
+        val number =
+          value?.toIntOrNull()
+            ?: throw G9PreferenceException("preference-value", "Preference '$key' needs a 32-bit integer, got $value.")
+        backend.putInt(key, number)
+      }
+      "string" -> if (value == null) backend.remove(key) else backend.putString(key, value)
+      "remove" -> backend.remove(key)
+      else -> throw G9PreferenceException("preference-value", "Unknown preference kind '$kind'.")
+    }
+  }
+
+  /** Every `[key, value]` whose key starts with `prefix`, sorted by key (stable hydration order). */
+  fun entries(prefix: String): List<List<Any>> =
+    backend
+      .all()
+      .entries
+      .filter { it.key.startsWith(prefix) && (it.value is Int || it.value is String) }
+      .sortedBy { it.key }
+      .map { (key, value) -> listOf(key, if (value is Int) value.toDouble() else value as Any) }
+
+  companion object {
+    fun ok(value: Any?): Map<String, Any?> = mapOf("ok" to true, "value" to value)
+
+    fun failure(error: Throwable): Map<String, Any?> =
+      mapOf(
+        "ok" to false,
+        "error" to
+          mapOf(
+            "code" to ((error as? G9PreferenceException)?.code ?: "preference-store"),
+            "message" to (error.message ?: error.toString()),
+          ),
+      )
+
+    /** Runs one request and wraps its outcome in an envelope. */
+    inline fun envelope(block: () -> Any?): Map<String, Any?> =
+      try {
+        ok(block())
+      } catch (error: Throwable) {
+        failure(error)
+      }
+  }
+}
+
+/** An in-memory backend (tests, previews). */
+class G9MemoryPreferenceBackend : G9PreferenceBackend {
+  private val values = java.util.concurrent.ConcurrentHashMap<String, Any>()
+
+  override fun all(): Map<String, *> = HashMap(values)
+
+  override fun putInt(key: String, value: Int) {
+    values[key] = value
+  }
+
+  override fun putString(key: String, value: String) {
+    values[key] = value
+  }
+
+  override fun remove(key: String) {
+    values.remove(key)
+  }
+}