@spacesops/wdk-react-native-core 1.0.0-beta.53 → 1.0.0-beta.55

package/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md — @spacesops/wdk-react-native-core
+
+The single package consuming apps install. It owns provider/hook/lifecycle code and, just as importantly, **pins the versions of `@spacesops/pear-wrk-wdk` and `@spacesops/react-native-bare-kit` that are known to work together**. Consumers must not install those directly.
+
+## Release order
+
+Publish upstream first, then bump here, then the app: `wdk-wallet-btc` → `pear-wrk-wdk` → `react-native-bare-kit` → **this** → app. Both `@spacesops/*` dependencies are exact pins, so **publishing this package before an upstream version exists makes it uninstallable** (`ETARGET / notarget`) — verify each pin resolves on npm before publishing.
+
+Regenerate `package-lock.json` from scratch when bumping either pin. npm preserves existing lock entries instead of re-resolving, so an incremental install keeps an old addon version hoisted and nests the correct one beneath it — two copies, and two `.so` files in every consumer APK.
+
+## Non-obvious invariants
+
+**No Expo config plugin can live here.** This package is `"type": "module"` and Expo does a plain `require()` of `app.plugin.js`, so a CJS plugin throws `ERR_REQUIRE_ESM` at prebuild. The Android packaging plugin lives in `react-native-bare-kit`, which is CJS; consumers reference `"@spacesops/react-native-bare-kit"` in `plugins`. `bin/verify-addons.mjs` is fine as ESM.
+
+**Do not add `@expo/*` packages as dependencies.** They use Expo-SDK-aligned versions (`@expo/config-plugins` is `54.x`, not `10.x`), so a guessed range installs a second incompatible copy. Use optional peers.
+
+**Some things genuinely cannot be fixed from here.** npm `overrides` only work from the root manifest, so a bad transitive range in a dependency is the *app's* problem to override — document it in the README rather than attempting a fix. `@tetherto/wdk-react-native-secure-storage` targets Expo SDK 55 while apps on SDK 54 must override `expo-crypto` and `expo-local-authentication`.
+
+**Never add a `postinstall` that builds.** It runs in every consumer install, needs TypeScript present, and `dist` already ships.
+
+## Triage
+
+Native addon failures (`ADDON_NOT_FOUND`, release-only crashes) belong to `react-native-bare-kit` — see its `TROUBLESHOOTING.md`. Failures scoped to one chain (a wrong or `undefined` address, `MODULE_NOT_FOUND` for a wallet file) come from the versions packed inside pear's bundle and need a pear release; the copies in an app's `node_modules` never execute.

package/README.md

@@ -65,45 +65,60 @@ function WalletScreen() {
 
 ## Installation
 
-### Step 1: Install Dependencies
-
-This package is part of the **Spacesops beta.40 pipeline**. Install matching peer/runtime versions in your host app:
+### Step 1: Install
 
 ```bash
-npm install @spacesops/wdk-react-native-core@1.0.0-beta.40
-npm install @spacesops/pear-wrk-wdk@1.1.1-beta.40 @spacesops/react-native-bare-kit@0.11.0-beta.40
-npm install @tetherto/wdk-react-native-secure-storage
-npm install react@">=18.0.0" react-native@">=0.70.0"
-npm install react-native-nitro-modules@">=0.35.0"
+npm install @spacesops/wdk-react-native-core
+npm install react-native-nitro-modules   # >=0.35, required by react-native-mmkv
+```
+
+**Install this package only.** `@spacesops/pear-wrk-wdk` (the worklet bundle) and `@spacesops/react-native-bare-kit` (the native runtime) arrive as dependencies at versions known to work together. Adding them to your own `dependencies` lets your ranges drift from the set this package was tested against, which fails at runtime rather than at install.
+
+For the same reason, **never add a bare addon package** (`bare-crypto`, `@buildonspark/spark-frost-bare-addon`, anything with `"addon": true`) to your `dependencies`. The worklet bundle hardcodes the exact addon versions it links, pear pins all of them, and a direct dependency at a different version gets linked into your APK as a second unused `.so`.
+
+### Step 2: Add the Expo config plugin
+
+```json
+{ "expo": { "plugins": ["@spacesops/react-native-bare-kit"] } }
 ```
 
-`react-native-mmkv` (4.3.x) is bundled as a dependency; the host app must install **`react-native-nitro-modules` ≥ 0.35** so Android/iOS Nitro codegen (e.g. `HybridObject.CxxPart`) matches MMKV.
+This is not optional on Android. Bare addons are `dlopen`ed by filename and the loader reads their symbol tables directly, so stripping their debug symbols corrupts them — and only some builds strip, so **without the plugin your debug builds work and your release builds crash**. The plugin keeps symbols for every addon it finds in the tree, discovering them the same way the linker does rather than matching a fixed list of names.
+
+The plugin lives in `@spacesops/react-native-bare-kit` because the constraint is a property of the native runtime. It installs as a dependency of this package, so you do not need to add it to your own `dependencies` — only to `plugins` above.
+
+Non-Expo apps must do the equivalent in `android/app/build.gradle`; see the `@spacesops/react-native-bare-kit` README.
+
+### Step 3: Verify the native addons line up
 
-**Host app notes (beta.40):**
+```bash
+npx wdk-verify-addons
+```
 
-- You do **not** need `wire-worklet.js`, `relink-bare-addons.js`, or a direct `@spacesops/wdk-wallet-btc` dependency—bitcoin runs inside the pear worklet bundle.
-- On **Android**, configure **`keepDebugSymbols`** for `libbare*.so` in your Expo app or config plugin (see `@spacesops/react-native-bare-kit` README).
-- Include **`bitcoin`** in `networkConfigs` (electrum URLs, etc.) so it matches pear’s `networks: ["bitcoin"]`.
+Every addon the worklet bundle links must exist on disk at that exact version. Addon linking itself needs no setup — bare-kit's Gradle `preBuild` runs it on every Android build.
 
-### Step 2: Install from GitHub (if using source)
+If it reports a mismatch, the usual cause is a **stale lockfile**. npm preserves existing lock entries instead of re-resolving, so an incremental install can keep an older addon version hoisted and nest the correct one beneath it, putting two copies in your APK. Re-resolve from scratch:
 
 ```bash
-npm install https://github.com/spacesops/wdk-react-native-core.git
+rm -rf node_modules package-lock.json && npm install
 ```
 
-Or add to your `package.json`:
+`bare-posix` is reported as having no Android prebuild. That is expected — its `exports` map `android` to `unsupported.js`, so nothing can ever link it.
+
+### Expo SDK compatibility
+
+`@tetherto/wdk-react-native-secure-storage` targets **Expo SDK 55** (`expo-crypto@^55`, `expo-local-authentication@^55`). On **SDK 54** those ranges resolve to packages your app cannot use, and npm `overrides` are the only mechanism that can correct a transitive range — no library can do it for you. Add to your app's `package.json`:
 
 ```json
 {
-  "dependencies": {
-    "@spacesops/wdk-react-native-core": "1.0.0-beta.40",
-    "@spacesops/pear-wrk-wdk": "1.1.1-beta.40",
-    "@spacesops/react-native-bare-kit": "0.11.0-beta.40",
-    "@tetherto/wdk-react-native-secure-storage": "github:tetherto/wdk-react-native-secure-storage"
+  "overrides": {
+    "expo-crypto": "~15.0.9",
+    "expo-local-authentication": "~17.0.8"
   }
 }
 ```
 
+Drop these once you move to SDK 55 or later.
+
 ## Core Concepts
 
 ### WdkAppProvider
@@ -491,6 +506,16 @@ The `WdkAppProvider` uses a **consolidated effect** for wallet state synchroniza
 
 ## Troubleshooting
 
+### Native addons fail to load (`ADDON_NOT_FOUND`, `dlopen` failures, release-only crashes)
+
+Start with `npx wdk-verify-addons`, then see **`node_modules/@spacesops/react-native-bare-kit/TROUBLESHOOTING.md`**. A listed candidate in an `ADDON_NOT_FOUND` message means the file *was* found and `dlopen` failed, so it is a symbol problem rather than a missing or misnamed library — and bare truncates the real cause out of the log.
+
+If it only reproduces in release builds, you are almost certainly missing the Expo config plugin from Step 2.
+
+### Errors from a specific network after the worklet starts
+
+Failures scoped to one chain (a wrong or `undefined` address, `MODULE_NOT_FOUND` for a wallet file) come from the versions packed inside the worklet bundle, not from your app. The same packages in your `node_modules` are used for types and never execute, so they can look correct while the device fails. These need a `@spacesops/pear-wrk-wdk` release; report them rather than patching locally.
+
 ### Wallet Initialization Fails
 
 **Symptoms**: `status` is `ERROR`, `error` is set

package/bin/verify-addons.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * Verifies that every native addon the pear worklet bundle links is actually
+ * present on disk, at the exact version the bundle expects.
+ *
+ * Deliberately checks files rather than `addons-lock.json`: the lock records
+ * what link intended to write, so comparing against it can pass while a `.so`
+ * is missing.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+const ABIS = ['arm64-v8a', 'armeabi-v7a', 'x86', 'x86_64']
+
+const root = process.cwd()
+const req = (p) => path.join(root, 'node_modules', p)
+
+const pearDir = req('@spacesops/pear-wrk-wdk')
+const addonsDir = req('@spacesops/react-native-bare-kit/android/src/main/addons')
+
+function fail(message, hint) {
+  console.error(`[verify-addons] ${message}`)
+  if (hint) console.error(`\n${hint}`)
+  process.exit(1)
+}
+
+function expectedAddons() {
+  const manifest = path.join(pearDir, 'generated/pear-linked-addons.json')
+  if (fs.existsSync(manifest)) {
+    return JSON.parse(fs.readFileSync(manifest, 'utf8')).linkedAddons
+  }
+
+  // Older pear releases did not ship the manifest.
+  const bundle = path.join(pearDir, 'generated/bundle/wdk-worklet.mobile.bundle.js')
+  if (!fs.existsSync(bundle)) {
+    fail(
+      'could not find the pear worklet bundle',
+      'Is @spacesops/pear-wrk-wdk installed? Expected:\n  ' + bundle
+    )
+  }
+  const text = fs.readFileSync(bundle, 'utf8')
+  const names = [...text.matchAll(/linked\\?:lib[^"'\\]+/g)].map((m) =>
+    m[0].replace(/^linked\\?:/, '')
+  )
+  return [...new Set(names)].sort()
+}
+
+/**
+ * A missing `.so` is expected when the package ships no Android prebuild at
+ * all — `bare-posix` maps `android` to `unsupported.js` in its exports, so the
+ * bundle references it but nothing can ever link it.
+ */
+function shipsAndroidPrebuild(addonFile) {
+  const name = addonFile.replace(/^lib/, '').replace(/\.\d+\.\d+\.\d+\.so$/, '')
+  const pkg = name.includes('__') ? '@' + name.replace('__', '/') : name
+  const prebuilds = req(path.join(pkg, 'prebuilds'))
+  if (!fs.existsSync(prebuilds)) return false
+  return fs.readdirSync(prebuilds).some((d) => d.startsWith('android-'))
+}
+
+const expected = expectedAddons()
+if (expected.length === 0) fail('the pear bundle links no native addons, which cannot be right')
+
+if (!fs.existsSync(addonsDir)) {
+  fail(
+    'no linked addons directory',
+    'bare-kit link has not run yet. It runs automatically on Android preBuild;\n' +
+      'to run it now:\n  node node_modules/@spacesops/react-native-bare-kit/android/link.mjs'
+  )
+}
+
+let failed = false
+
+for (const abi of ABIS) {
+  const dir = path.join(addonsDir, abi)
+  if (!fs.existsSync(dir)) {
+    console.error(`[verify-addons] ${abi}: missing entirely`)
+    failed = true
+    continue
+  }
+
+  const present = new Set(fs.readdirSync(dir).filter((f) => f.endsWith('.so')))
+  const missing = expected.filter((n) => !present.has(n))
+
+  const hard = missing.filter(shipsAndroidPrebuild)
+  const expectedAbsent = missing.filter((n) => !shipsAndroidPrebuild(n))
+
+  // Two versions of one addon means a duplicate package in the tree: the
+  // bundle only ever loads one, so the other is dead weight in the APK.
+  const byName = new Map()
+  for (const f of present) {
+    const base = f.replace(/\.\d+\.\d+\.\d+\.so$/, '')
+    byName.set(base, (byName.get(base) ?? 0) + 1)
+  }
+  const duplicated = [...byName].filter(([, n]) => n > 1).map(([b]) => b)
+
+  if (hard.length) {
+    console.error(`[verify-addons] ${abi}: ${hard.length} addon(s) the bundle needs are missing:`)
+    hard.forEach((n) => console.error(`  - ${n}`))
+    failed = true
+  } else {
+    const notes = []
+    if (expectedAbsent.length) notes.push(`${expectedAbsent.length} with no Android prebuild`)
+    if (duplicated.length) notes.push(`${duplicated.length} duplicated`)
+    console.log(
+      `[verify-addons] ${abi}: ${expected.length - missing.length}/${expected.length} present` +
+        (notes.length ? ` (${notes.join(', ')})` : '')
+    )
+  }
+
+  for (const n of duplicated) {
+    console.warn(`[verify-addons] ${abi}: ${n} is linked at more than one version`)
+  }
+}
+
+if (failed) {
+  fail(
+    'the installed tree does not match the pear bundle',
+    'pear pins every addon it links as an exact dependency, so a mismatch usually\n' +
+      'means a stale lockfile kept an older resolution. Re-resolve from scratch:\n' +
+      '  rm -rf node_modules package-lock.json && npm install\n\n' +
+      'If it persists, the pear release is inconsistent — see\n' +
+      'node_modules/@spacesops/react-native-bare-kit/TROUBLESHOOTING.md'
+  )
+}
+
+console.log('[verify-addons] OK')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacesops/wdk-react-native-core",
-  "version": "1.0.0-beta.53",
+  "version": "1.0.0-beta.55",
   "description": "Core functionality for React Native wallets - wallet management, balance fetching, and worklet operations",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,7 +10,9 @@
     "dist",
     "src",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "bin",
+    "AGENTS.md"
   ],
   "exports": {
     ".": {
@@ -38,8 +40,7 @@
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
-    "prepack": "npm run build",
-    "postinstall": "npm run build"
+    "prepack": "npm run build"
   },
   "keywords": [
     "wallet",
@@ -52,11 +53,11 @@
   "author": "Spacesops",
   "license": "Apache-2.0",
   "dependencies": {
-    "@tetherto/wdk-react-native-secure-storage": "github:tetherto/wdk-react-native-secure-storage",
+    "@spacesops/pear-wrk-wdk": "1.1.1-beta.44",
+    "@spacesops/react-native-bare-kit": "0.11.0-beta.49",
     "@tanstack/react-query": "^5.0.0",
+    "@tetherto/wdk-react-native-secure-storage": "1.0.0-beta.5",
     "expo-crypto": "^15.0.8",
-    "@spacesops/pear-wrk-wdk": "1.1.1-beta.43",
-    "@spacesops/react-native-bare-kit": "0.11.0-beta.48",
     "react-native-mmkv": "^4.3.0",
     "zod": "^3.22.0",
     "zustand": "^5.0.9"
@@ -77,5 +78,8 @@
     "react": "*",
     "react-native": ">=0.70.0",
     "react-native-nitro-modules": ">=0.35.0"
+  },
+  "bin": {
+    "wdk-verify-addons": "./bin/verify-addons.mjs"
   }
 }