pivot: drop Flutter scaffold, retarget for native Kotlin Android

Research showed nodejs-mobile-flutter doesn't exist as a maintained
dependency (JaneaSystems repo is 404, official org ships only RN +
Cordova plugins, pub.dev has nothing). On closer inspection the plugin
layer is dead weight for a WebView-shell architecture — every plugin
exists to bridge messages between an outer JS runtime and Node, but our
"bridge" is just HTTP between the WebView and Fastify. Decision
discussed in JSS#366.

This commit removes the Flutter scaffold (pubspec.yaml, lib/, test/, the
Flutter-shaped android/) and updates README + ARCHITECTURE to describe
the native Kotlin direction: MainActivity hosting a WebView, libnode.so
linked via JNI/CMake (~80 LOC C++ from JaneaSystems samples), foreground
service wrapping the Node thread.

scripts/bundle-jss.sh retargeted from assets/nodejs-project/ to
app/src/main/assets/jss/ to match the standard Android assets path.

Stays the same: the verified launch args, the bundle script's contract
(npm pack + prod install + sanity check, refuses native modules), the
repo's gh-pages trunk.

Author: melvincarvalho

.gitignore

@@ -1,46 +1,42 @@
-# Flutter / Dart
-.dart_tool/
-.flutter-plugins
-.flutter-plugins-dependencies
-.packages
-.pub-cache/
-.pub/
+# Gradle
+.gradle/
 build/
-.metadata
+out/
 
-# IDE
+# Android Studio / IntelliJ
 .idea/
-.vscode/
 *.iml
 *.ipr
 *.iws
-.DS_Store
+local.properties
+captures/
 
-# Android
-android/.gradle/
-android/captures/
-android/local.properties
-android/app/release/
-android/app/debug/
+# Build artifacts
+*.apk
+*.aab
+*.ap_
+*.dex
+*.class
+proguard/
+
+# Signing keys (NEVER commit)
 *.keystore
 *.jks
-android/key.properties
+key.properties
+
+# Logs
+*.log
 
-# iOS (kept in case we ever scope iOS in)
-ios/Pods/
-ios/.symlinks/
-ios/Flutter/Flutter.framework
-ios/Flutter/Flutter.podspec
+# OS / editor
+.DS_Store
+.vscode/
 
-# Bundled JSS — copied in by scripts/bundle-jss.sh, not tracked
-assets/nodejs-project/
+# Bundled JSS (produced by scripts/bundle-jss.sh, not tracked)
+app/src/main/assets/jss/
 
-# Node (only present transiently while bundling)
+# Vendored libnode binaries (produced by scripts/fetch-libnode.sh, not tracked)
+app/libnode/
+
+# Node (transient while bundling)
 node_modules/
 npm-debug.log
-yarn-debug.log
-yarn-error.log
-
-# Generated
-.flutter-version
-# Note: pubspec.lock IS committed (Flutter convention for application packages)

ARCHITECTURE.md

@@ -2,66 +2,81 @@
 
 ## Goal
 
-Ship a single-tap Android install that runs a personal Solid pod on the phone. The user opens the app and a JSS instance is running at `http://localhost:4443/` inside the app's process; closing the app stops the pod (or, with the foreground service, keeps it alive in the background).
+Ship a single-tap Android install that runs a personal Solid pod on the phone. The user opens the app and a JSS instance is running at `http://127.0.0.1:4443/` inside the app's process; closing the app stops the pod (or, with the foreground service, keeps it alive in the background).
+
+## Why native Kotlin (not Flutter, not React Native, not a plugin)
+
+> The original draft specified Flutter. Research showed there's no maintained Flutter↔nodejs-mobile plugin, and on closer inspection **the plugin layer is dead weight for our shape**: every plugin (RN, Flutter, Capacitor) exists to marshal messages between an outer JS runtime and the embedded Node. Our UI is a `WebView`, the WebView talks to JSS over HTTP, and the bridge is HTTP. Pivot rationale: [JSS#366 comment](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/366#issuecomment-4401796552). Same APK story (JS bundle + WebView), one fewer abstraction.
 
 ## Components
 
 ### 1. Bundled JSS (the asset)
 
-- Path inside APK: `assets/nodejs-project/`
+- Path inside APK: `app/src/main/assets/jss/`
 - Contents: full JSS tree as published to npm — `bin/`, `src/`, `package.json`, `node_modules/`
 - Why the full `node_modules/`: it's pure JS, so copying it once at build-time is cheaper than `npm install` on first launch (and avoids needing a network on first run)
-- Size estimate: ~1.4 MB unpacked (per `npm publish` output for `javascript-solid-server@0.0.169`) + node_modules ≈ 30–50 MB
+- Verified bundle size for `javascript-solid-server@0.0.169`: **~62 MB / 5444 files** (per `scripts/bundle-jss.sh` smoke run)
+- Not tracked in git; produced fresh from `scripts/bundle-jss.sh` for each build
 
-### 2. nodejs-mobile runtime
+### 2. nodejs-mobile runtime (`libnode.so`)
 
-- Provides a patched Node binary cross-compiled for Android (arm64-v8a, armeabi-v7a, x86_64)
-- Runs as a dedicated thread inside the Android process
-- Restrictions vs upstream Node: no `child_process`, no `cluster`, no `worker_threads` until recent versions, no native addons unless explicitly built for Android
+- Patched Node binary cross-compiled for Android (arm64-v8a, armeabi-v7a, x86_64)
+- Vendored from [`nodejs-mobile/nodejs-mobile` releases](https://github.com/nodejs-mobile/nodejs-mobile/releases) by `scripts/fetch-libnode.sh`
+- Currently ships **Node 18.20.4** (last release Oct 2024; Node 18 EOL April 2025 — see Risks)
+- Restrictions vs upstream Node: no `child_process`, no `cluster`, no native addons unless explicitly built for Android
+- Linked via JNI/CMake; loaded into a dedicated thread inside the Android process
 
-### 3. Flutter plugin (`nodejs-mobile-flutter`)
+### 3. JNI shim (`native-lib.cpp`)
 
-- Boots the Node runtime, hands it the entry script (`assets/nodejs-project/bin/jss.js`) plus startup args
-- Provides a Dart channel for bidirectional message passing (used post-MVP for native UI ↔ JSS commands; v1 doesn't need it)
+- ~80 lines of C++, lifted near-verbatim from [JaneaSystems/nodejs-mobile-samples](https://github.com/JaneaSystems/nodejs-mobile-samples/tree/master/android/native-gradle/app/src/main/cpp)
+- Two responsibilities:
+  1. `extern "C" int callintoNode(int argc, char *argv[]) { return node::Start(argc, argv); }` — exposes Node's main loop
+  2. Pipe stdout/stderr to logcat (otherwise Fastify's startup logs vanish)
+- Optional reuse from `nodejs-mobile-react-native`'s C++ layer (MIT licensed): the assetCopy routine and JNI thread setup. We're a server, not a client of `rn-bridge.cpp`'s message channel — we don't need that file.
 
-### 4. Flutter UI
+### 4. MainActivity (Kotlin)
 
-- **v1**: a single `WebView` widget pointed at `http://localhost:4443/`
-- Initial route depends on JSS config; default lands on the IDP landing or the `/{pod}/` root
-- v2: native screens for sign-in, file browse, sharing — replacing the WebView screen by screen
+- Single-screen `WebView` pointed at `http://127.0.0.1:4443/`
+- WebView config: `domStorageEnabled = true`, `javaScriptEnabled = true`, allow mixed content for loopback, override `shouldOverrideUrlLoading` so off-pod links open in the system browser (avoids in-WebView OAuth capture)
+- Boot waits for the foreground service to report Node ready before loading the URL — show a splash in the meantime
 
-### 5. Android foreground service
+### 5. JssService (Kotlin foreground service)
 
-- Standard pattern: when JSS is "running" the app posts a persistent notification ("JSS is running on port 4443")
-- Required to avoid the OS killing the Node thread when the app goes to background
-- User can stop the pod by tapping the notification's Stop action
+- Wraps the Node thread in an Android `Service` with `START_STICKY` and a persistent notification ("JSS pod running on :4443")
+- Required: without a foreground service, Android kills the Node thread when the app backgrounds
+- Notification has a "Stop" action wired to a graceful Fastify shutdown via a process-internal HTTP call (or sigterm via the JNI side)
+- Reference: `node_flutter`'s `NodeService.kt` (~133 lines, MIT) is the cleanest example to lift the lifecycle pattern from
 
 ## Boot sequence
 
-1. App `main()` → run Flutter app
-2. Flutter `initState` → call `NodejsMobile.startNodeProject()` with:
-   - script: `bin/jss.js`
-   - args: `['start', '--single-user', '--port', '4443', '--host', '127.0.0.1', '--root', '<android-files-dir>/data', '--idp']`
-   - env: `JSS_SINGLE_USER_PASSWORD=<derived-or-prompted>` (only on first launch, to seed the IDP account)
-3. Node thread starts; JSS imports its modules; Fastify binds to `127.0.0.1:4443`
-4. Flutter listens for the "ready" message on the channel (or polls `GET /` until 200) and shows the WebView
+1. App `onCreate` → start `JssService` as a foreground service
+2. `JssService` spawns a worker thread → JNI `startNode(args)`:
+   - script: `<filesDir>/jss/bin/jss.js`
+   - args: `['start', '--single-user', '--port', '4443', '--host', '127.0.0.1', '--root', '<filesDir>/data', '--idp']`
+   - env: `JSS_SINGLE_USER_PASSWORD=<derived-or-stored>` (only on first launch, to seed the IDP account)
+3. Node imports JSS modules; Fastify binds to `127.0.0.1:4443`
+4. Service polls `GET http://127.0.0.1:4443/` (100 ms backoff, max ~5 s) → broadcasts ready
+5. `MainActivity` receives ready → loads the WebView URL
 
-## Data layout on device
+## Asset layout on device
 
-- `<android-files-dir>/data/` — JSS pod data (passed via `--root <path>` or `DATA_ROOT` env)
-- `<android-files-dir>/data/.idp/` — IDP credentials, keys (verified by spike: created on first boot)
-- `<android-files-dir>/data/.well-known/` — token store, etc. (when `--idp` is on)
-- `<cache-dir>/` — JSS notification queues, ephemeral state
+| Path | Purpose |
+|---|---|
+| `<filesDir>/jss/` | JSS tree, copied from APK assets on first launch (or when build version changes) |
+| `<filesDir>/data/` | Pod data: `profile/`, `public/`, `private/`, `inbox/`, `settings/`, `.idp/` |
+| `<filesDir>/data/.idp/` | IDP credentials + signing keys (verified by spike: created on first boot) |
+| `<cacheDir>/` | Ephemeral state (notification queues, etc.) |
 
-The pod's filesystem layout is unchanged from desktop JSS — we just point `--root` at app-private storage. Verified by booting `jss start --single-user --port 4444 --root /tmp/foo --idp`: full pod tree (profile/, public/, private/, inbox/, settings/, .idp/) is created at the supplied path with nothing leaking to `~/.jss/` or the cwd.
+The pod's filesystem layout is unchanged from desktop JSS — we just point `--root` at app-private storage. Verified by booting `jss start --single-user --port 4444 --root /tmp/foo --idp`: full pod tree is created at the supplied path with nothing leaking to `~/.jss/` or the cwd.
 
-> **Spike note (2026-05-08):** the CLI flag is `-r, --root <path>`, not `--data-root` as initially drafted. The architecture docs and any future Dart launcher should use `--root`.
+> **CLI flag note (verified 2026-05-08):** the flag is `-r, --root <path>`, not `--data-root`.
 
 ## Auth model on a single-user phone pod
 
 - `--single-user` mode: one pod, one WebID, no registration UI
-- Default: pod owner is the device user; the IDP login screen still works for cross-app sign-in flows (xlogin, did:nostr signers)
-- E2EE composes cleanly: the device-local Nostr key is the pod's WebID and the encryption key (see [JSS#365](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/365))
+- Default pod owner is the device user
+- The IDP login screen still works for cross-app sign-in flows (xlogin, did:nostr signers via NIP-07 in the WebView)
+- E2EE composes cleanly: device-local Nostr key is the pod's WebID and the encryption key (see [JSS#365](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/365))
 
 ## Public exposure (optional)
 
@@ -72,23 +87,31 @@ The pod's filesystem layout is unchanged from desktop JSS — we just point `--r
 ## What we're not doing
 
 | Choice | Why |
-|--------|-----|
-| Run Node via Termux instead of nodejs-mobile | Termux requires a separate app + manual setup; defeats "one-click install" |
-| Cross-compile native deps for Android | Not needed — JSS already uses pure-JS substitutes everywhere |
-| Custom Node fork for additional capabilities | nodejs-mobile is maintained; forking is a long-term burden |
-| iOS in v1 | App Store rule 2.5.2 (no executable code download) and embedded-interpreter policy is fuzzy; needs separate research |
-| Native Flutter UI in v1 | WebView is faster to ship and reuses JSS's existing IDP / mashlib UIs |
-
-## Open questions
-
-- Does `nodejs-mobile`'s most recent release ship Node ≥ 18? (`engines.node: ">=18.0.0"` is JSS's floor; spike on dev box ran Node 24 with one `oidc-provider` warning about preferring v22 LTS — runtime is *forgiving*, but we should pin the mobile target to whatever Node `nodejs-mobile` ships)
-- Memory ceiling on cheap Android devices (1 GB RAM)? `oidc-provider` is the heaviest dep; might need `--idp` off in a "lite" mode
-- How do we surface the WebID/pod URL outside the app? (Deep link? Share sheet? A "copy URL" button?)
-- Does the foreground-service notification need a stop action wired to a graceful Fastify shutdown? (yes — need to expose this via the plugin channel)
-- First-run UX: where do we surface the IDP password? Options: (a) auto-generate, store in Android Keystore, never show; (b) prompt user; (c) skip IDP entirely on phone (signed-in via did:nostr only)
+|---|---|
+| Run Node via Termux | Termux requires a separate app + manual setup; defeats "one-click install" |
+| Cross-compile native deps | Not needed — JSS uses pure-JS substitutes throughout |
+| Custom Node fork | `nodejs-mobile` is maintained; forking is a long-term burden |
+| Flutter / React Native shell | Both pay for an outer JS runtime to talk to Node — but our UI is a WebView, talking to Node over HTTP. The plugin layer is dead weight |
+| Bare/Pear runtime | No `fs` / `http` builtins — would require rewriting JSS's transitive deps against `bare-*` modules |
+| iOS in v1 | App Store rule 2.5.2 grey zone on dynamic JS eval; OIDC client registration may trip it |
+| Native UI (Compose/Views) in v1 | WebView reuses JSS's existing IDP + mashlib UIs; faster to ship |
+
+## Risks / open questions
+
+- **Node 18 EOL.** Upstream `nodejs-mobile` last released Oct 2024 with Node 18.20.4. Node 18 stopped getting security patches April 2025. For a server running OIDC + TLS, this is real. Mitigations: 127.0.0.1-only bind cuts attack surface; track community efforts toward a Node 20/22 mobile build (watch upstream issues).
+- **APK size.** `libnode.so` is ~30 MB per ABI. Ship as AAB with ABI splits (arm64-v8a + armeabi-v7a; drop x86_64 unless emulator support is needed) so Play Store delivers per-device.
+- **Port collisions.** 4443 may be taken on the device. Plan: try 4443, then 4444, 4445, … and write the chosen port to a `SharedPreferences` the WebView reads. Or bind to port 0 and read back via a JNI return.
+- **Memory on low-end devices.** `oidc-provider` is the heaviest dep; `--no-idp` "lite" mode is the fallback for 1 GB RAM phones.
+- **First-run IDP password UX.** Options: (a) auto-generate, store in Android Keystore, never show; (b) prompt user; (c) skip IDP entirely on phone (sign in via did:nostr only). Pick before v1.
+- **Foreground service stop action.** Notification "Stop" needs to wire to a graceful Fastify shutdown — sigterm via JNI or an in-process HTTP call to a `/.shutdown` admin endpoint we'd need to add to JSS.
+- **WebID URL discovery from outside the app.** How does the user get their pod URL into another app on the phone? Options: deep link, share sheet, a "copy URL" button. Pick before v1.
 
 ## Build & release
 
-- Debug builds: `flutter run` from a dev box with a connected device
-- Release: `flutter build apk --release` produces a signed APK; `flutter build appbundle` for Play Store
-- CI (later): GitHub Actions matrix with `subosito/flutter-action`, building both `--debug` and `--release` artifacts on each tag
+- Debug: `./gradlew installDebug` from a dev box with a connected device (ADB)
+- Release: `./gradlew bundleRelease` produces a signed AAB for Play Store; `./gradlew assembleRelease` for sideload-friendly APKs
+- CI (later): GitHub Actions, JDK 17, Android SDK action, NDK action, build both `--debug` and `--release` AABs on each tag
+- Pre-build hooks (orchestrated outside gradle for clarity):
+  - `scripts/bundle-jss.sh` — populates `app/src/main/assets/jss/`
+  - `scripts/fetch-libnode.sh` — populates `app/libnode/{abi}/libnode.so`
+- Both are idempotent and check version pins; CI invokes them before `./gradlew`