@fressh/react-native-terminal 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# @fressh/react-native-terminal
+
+[![npm](https://img.shields.io/npm/v/@fressh/react-native-terminal)](https://www.npmjs.com/package/@fressh/react-native-terminal)
+[![npm canary](https://img.shields.io/npm/v/@fressh/react-native-terminal/canary?label=canary&color=orange)](https://www.npmjs.com/package/@fressh/react-native-terminal?activeTab=versions)
+
+Native SSH terminal for React Native, in **one package / one `.so`**:
+
+- **SSH** via russh (`fressh-ssh`)
+- **VT engine** via `alacritty_terminal` — durable, parsed `Term` state
+- **Native renderer** via Alacritty's GLES2 renderer (`fressh-render`) — no xterm.js WebView
+- **Registry-owned sessions** (`fressh-core`) → tmux-style reattach, full scrollback on
+  re-entry, no byte replay
+
+It renders natively on **Android (EGL/GLES2) and iOS (GLES2 via ANGLE → Metal)** and is
+used in production by the [fressh](https://github.com/EthanShoeDev/fressh) app. It replaces
+the earlier `@fressh/react-native-uniffi-russh` + `@fressh/react-native-xtermjs-webview`.
+
+> **`0.1.0` — experimental.** Functionality is solid on both platforms; the **public API
+> may still change** before `1.0`.
+
+## Requirements
+
+- **React Native ≥ 0.85** with the **New Architecture enabled** — this is a
+  [Nitro](https://nitro.margelo.com) module.
+- Peer deps: `react`, `react-native`, `react-native-nitro-modules`.
+- **Android:** `minSdkVersion ≥ 26`. Ships prebuilt `arm64-v8a` + `x86_64` (no
+  `armeabi-v7a` / `x86`).
+- **iOS:** deployment target **≥ 16.4**; `arm64` device + simulator.
+- **Expo:** works with **CNG / `expo prebuild` + a
+  [dev client](https://docs.expo.dev/develop/development-builds/introduction/)** — it has
+  native code, so **not** Expo Go. No config plugin is needed; autolinking handles linking.
+
+## Install
+
+```sh
+bun add @fressh/react-native-terminal
+bun add react-native-nitro-modules   # peer dep, if not already present
+```
+
+**Bare React Native** — `cd ios && pod install` (autolinking discovers the podspec); Android
+autolinks via Gradle. No manual native wiring.
+
+**Expo** — add a dev client and prebuild:
+
+```sh
+bun add expo-dev-client
+bunx expo prebuild
+```
+
+Enforce the build floors with `expo-build-properties` in `app.config.ts` / `app.json`:
+
+```ts
+plugins: [
+	[
+		'expo-build-properties',
+		{ android: { minSdkVersion: 26 }, ios: { deploymentTarget: '16.4' } },
+	],
+];
+```
+
+### Prerelease channels
+
+```sh
+bun add @fressh/react-native-terminal@canary   # latest CI canary (0.0.0-canary-<commit>)
+bun add @fressh/react-native-terminal@rc        # release-candidate line, when active
+```
+
+## Usage
+
+Connect, answer the host-key prompt, open a shell, and render it. **Bytes never cross JS** —
+the native `<Terminal>` view owns rendering and input.
+
+```tsx
+import { useEffect, useState } from 'react';
+import {
+	Terminal,
+	addFresshEventListener,
+	connect,
+	respondToHostKey,
+	startShell,
+	FresshEvent_Tags,
+	Security,
+	TerminalType,
+	type ShellId,
+} from '@fressh/react-native-terminal';
+
+export function TerminalScreen() {
+	const [shellId, setShellId] = useState<ShellId | null>(null);
+
+	useEffect(() => {
+		// One event stream carries connect progress, host-key prompts, and close events.
+		const unsubscribe = addFresshEventListener((event) => {
+			if (event.tag === FresshEvent_Tags.HostKeyPending) {
+				// event.inner.info has the server key fingerprint — show it, then accept/reject.
+				respondToHostKey(event.inner.connectionId, true);
+			}
+		});
+
+		void (async () => {
+			const connectionId = await connect({
+				host: 'example.com',
+				port: 22,
+				username: 'me',
+				security: new Security.Password({ password: '…' }),
+				// …or key auth: new Security.Key({ privateKeyContent: pem })
+			});
+			const id = await startShell(connectionId, {
+				term: TerminalType.Xterm256,
+				cols: 80,
+				rows: 24,
+				scrollbackLines: 10_000,
+			});
+			setShellId(id);
+		})();
+
+		return unsubscribe;
+	}, []);
+
+	return shellId ? <Terminal shellId={shellId} style={{ flex: 1 }} /> : null;
+}
+```
+
+`<Terminal shellId>` reattaches to the durable `Term` that `fressh-core` keeps for that
+`shellId`, so re-mounting restores full scrollback with no replay. Font size / colors are
+driven by the `config` prop (`TerminalRenderConfig`). For a one-off command without a PTY,
+use `runCommand(connectionId, cmd)`; generate keys with `generateKeyPair(KeyType.Ed25519)`.
+
+The full surface is in the exported TypeScript types: `connect`, `startShell`, `runCommand`,
+`sendData`, `resize`, `scroll`, the selection helpers, `generateKeyPair`,
+`validatePrivateKey`, and the `FresshEvent` stream.
+
+---
+
+## Architecture — the four planes
+
+| Plane   | Path                                            | Crosses JS?           |
+| ------- | ----------------------------------------------- | --------------------- |
+| Control | JS `src/ssh.ts` → shim (uniffi) → `fressh-core` | yes (rare, async)     |
+| Event   | `fressh-core` → shim → JS (one-way sink)        | yes (rare)            |
+| Render  | Nitro view ↔ `fressh-core` C-ABI                | **never**             |
+| Data    | SSH bytes → reader loop → `Term`                | **never (pure Rust)** |
+
+SSH bytes feed a durable `alacritty_terminal` `Term` entirely in Rust; the Nitro view draws
+that `Term` over a C-ABI without round-tripping through JS. iOS renders the same GLES2 path
+through **ANGLE** (→ Metal); ANGLE's `libEGL` / `libGLESv2` xcframeworks are vendored in the
+podspec.
+
+## Layout
+
+```
+react-native-terminal/
+├── rust/                     # ONE cargo workspace
+│   ├── fressh-ssh/           # russh wrapper
+│   ├── fressh-render/        # Alacritty GLES2 renderer over Term
+│   ├── fressh-core/          # runtime + registry + sessions + C-ABI
+│   └── shim-uniffi/          # thin binding shim (control plane + render C-ABI)
+├── nitro/Terminal.nitro.ts   # native view spec (render plane)
+├── src/                      # TS public API (Terminal, ssh control plane)
+├── cpp/ android/ ios/        # hand-authored umbrella native glue
+└── ReactNativeTerminal.podspec · ubrn.config.yaml · package.json
+```
+
+## Design & internals
+
+Full design rationale, the renderer-extraction decisions, and the rejected alternatives live
+in the design doc:
+[`native-rendering-refactor.md`](https://github.com/EthanShoeDev/fressh/blob/main/docs/projects/complete/native-rendering-refactor.md).
+
+### Contributing (Rust toolchain)
+
+The npm tarball ships **prebuilt** native binaries, so consumers need no Rust toolchain.
+Contributors build from the repo (the Alacritty / crossfont forks are git submodules under
+`rust/vendor/`):
+
+```sh
+bun run cargo:fmt:fix     # cargo fmt --all
+bun run cargo:lint:fix    # cargo clippy --workspace --fix -D warnings
+bun run cargo:test        # cargo test --workspace
+```
+
+Lint levels are defined once in `rust/Cargo.toml` `[workspace.lints]` and inherited per-crate
+via `[lints] workspace = true`.

package/ReactNativeTerminal.podspec

@@ -0,0 +1,82 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+# The iOS analogue of the umbrella android/CMakeLists (§8): one pod that compiles
+# BOTH planes into the app and links ONE Rust staticlib so there is a single copy
+# of fressh-core's registry statics.
+#
+#   - Control plane: the ubrn-generated JSI bindings C++ (cpp/generated/*.cpp →
+#     NativeShimUniffi::registerModule) + our hand-authored ios/*.mm installer
+#     (mirrors Android's nativeInstallRustCrate; calls registerModule directly —
+#     we run `ubrn generate`, NOT `ubrn build`, so ubrn does not own this build).
+#   - Render plane: the Nitro HybridView (nitrogen sources via add_nitrogen_files +
+#     our ios/HybridTerminal.swift). On iOS this is a STUB for now — GLES via
+#     ANGLE→Metal lands later (§5); the view compiles and draws nothing.
+#   - Rust: shim_uniffi.xcframework (built by `bun run build:ios` → rust/build-ios.sh),
+#     carrying the uniffi scaffolding + render C-ABI + the shared registry statics.
+
+Pod::Spec.new do |s|
+  s.name         = "ReactNativeTerminal"
+  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/EthanShoeDev/fressh.git", :tag => "#{s.version}" }
+
+  # Hand-authored iOS sources (the .mm installer + the Nitro Swift view) and the
+  # ubrn-generated JSI bindings C++. add_nitrogen_files (below) APPENDS the
+  # nitrogen-generated specs/bridges to this list.
+  s.source_files = [
+    "ios/**/*.{h,m,mm,swift}",
+    "cpp/generated/**/*.{h,hpp,c,cpp}",
+  ]
+
+  # The single Rust staticlib (control plane + render C-ABI + fressh-core registry
+  # statics — ONE copy, §8), plus ANGLE's libEGL/libGLESv2 (dynamic, Metal backend
+  # — the GLES2 driver the renderer runs over on iOS, §2/§5). The ANGLE frameworks
+  # must be EMBEDDED: dyld loads them at launch and egl.rs resolves their symbols
+  # from the process image (Library::this()). Fetch them with `bun run angle:fetch`.
+  s.vendored_frameworks = [
+    "shim_uniffi.xcframework",
+    "libEGL.xcframework",
+    "libGLESv2.xcframework",
+  ]
+
+  # Expose the render C-ABI header in the module umbrella so HybridTerminal.swift can
+  # call fressh_terminal_* (Swift imports the module's PUBLIC headers). Setting
+  # public_header_files restricts the public set, so this must be additive with
+  # nitrogen's — which appends to it in add_nitrogen_files below.
+  s.public_header_files = "ios/FresshTerminalRenderABI.h"
+
+  # Bundled monospace font for the renderer — FreeType rasterizes it by file path
+  # (no fontconfig on mobile, §6/§8). HybridTerminal.swift resolves it from this
+  # bundle. The Android side ships the same DejaVuSansMono.ttf as an asset.
+  s.resource_bundles = {
+    "FresshTerminalFonts" => ["ios/fonts/*.ttf"],
+  }
+
+  # Brings ubrn's header-only C++ runtime (UniffiCallInvoker.h, RustArcPtr.h, …)
+  # onto the header path — the generated bindings #include these. Android resolves
+  # the same dir by walking node_modules in CMake; on iOS the pod dependency does it.
+  s.dependency "uniffi-bindgen-react-native"
+
+  s.pod_target_xcconfig = {
+    # The generated bindings + Nitro require C++20.
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++20",
+    # `#include "shim_uniffi.hpp"` from our .mm + the generated .cpp.
+    "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/cpp/generated\"",
+  }
+
+  # React-Core / ReactCommon (turbomodule/core for ObjCTurboModule), Folly, etc.
+  install_modules_dependencies(s)
+
+  # Nitro HybridView (render plane): appends nitrogen's generated specs + bridges
+  # to source_files, adds the NitroModules dependency, and merges the C++ <-> Swift
+  # interop xcconfig. Loaded last so it extends (not overwrites) the above.
+  load File.join(__dir__, "nitrogen", "generated", "ios", "ReactNativeTerminal+autolinking.rb")
+  add_nitrogen_files(s)
+end

package/android/CMakeLists.txt

@@ -0,0 +1,76 @@
+project(ReactNativeTerminal)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME ReactNativeTerminal)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+# The single package .so (§8). It contains:
+#   - the Nitro render JNI bridge (cpp-adapter.cpp) -> the Rust render C-ABI
+#   - the ubrn-generated uniffi JSI bindings (cpp/generated/shim_uniffi.cpp) +
+#     the install glue (cpp-adapter.cpp's nativeInstallRustCrate -> registerModule)
+# ...and it LINKS the Rust cdylib `libshim_uniffi.so`, which holds the uniffi
+# scaffolding + the render C-ABI + fressh-core's registry statics (ONE copy — so
+# the control plane and the render plane see the same sessions).
+add_library(${PACKAGE_NAME} SHARED
+  src/main/cpp/cpp-adapter.cpp
+  ../cpp/generated/shim_uniffi.cpp
+)
+
+# CRITICAL: hide all symbols by default; only the JNIEXPORT entry points (which carry
+# explicit default visibility) stay exported. Without this, the React/Nitro template
+# instantiations we compile in (ShadowNode, State, ConcreteState, StateWrapperImpl,
+# RawPropsParser, …) are exported with default visibility and INTERPOSE over
+# libreactnative.so's copies at load time. RN core then manipulates Fabric State
+# objects through OUR differently-built copies, corrupting the view-state round-trip:
+# props parse correctly in cloneProps but come back freed/garbage in updateViewProps,
+# so NewStringUTF aborts (and ~HybridTerminalState segfaults). Other Nitro libs
+# (e.g. NitroMmkv) export 0 such symbols; this hand-written umbrella must match.
+target_compile_options(${PACKAGE_NAME} PRIVATE -fvisibility=hidden -fvisibility-inlines-hidden)
+target_link_options(${PACKAGE_NAME} PRIVATE -Wl,--exclude-libs,ALL)
+
+# Nitrogen-generated sources + nitro/fbjni/ReactAndroid (jsi, ReactCommon) linkage
+# + their include dirs (the generated uniffi cpp uses <jsi/jsi.h> and
+# <ReactCommon/CallInvoker.h>, both provided here).
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/ReactNativeTerminal+autolinking.cmake)
+
+# Resolve uniffi-bindgen-react-native's header-only C++ runtime (UniffiCallInvoker.h
+# etc.) by walking up node_modules from this dir (works from the consuming app).
+execute_process(
+  COMMAND node -e "const fs=require('fs'),p=require('path');let d=process.cwd();while(d.length>1){const c=p.join(d,'node_modules/uniffi-bindgen-react-native/cpp/includes');if(fs.existsSync(c)){process.stdout.write(c);break;}d=p.dirname(d);}"
+  WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+  OUTPUT_VARIABLE UNIFFI_INCLUDES
+  OUTPUT_STRIP_TRAILING_WHITESPACE)
+
+target_include_directories(${PACKAGE_NAME} PRIVATE
+  ${CMAKE_SOURCE_DIR}/../cpp/generated
+  ${UNIFFI_INCLUDES}
+)
+
+# Required for 16KB page sizes (Android 15+).
+set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,max-page-size=16384")
+
+# Import the Rust cdylib (built per-ABI by cargo-ndk into jniLibs). It carries BOTH
+# the uniffi scaffolding (the ffi_* symbols the generated cpp calls) AND the render
+# C-ABI (the fressh_terminal_* symbols the JNI bridge calls), so there is one shared
+# registry. Linked SHARED (not a static .a) so neither plane gets its own copy.
+cmake_path(SET RUST_LIB
+  ${CMAKE_SOURCE_DIR}/src/main/jniLibs/${ANDROID_ABI}/libshim_uniffi.so
+  NORMALIZE)
+add_library(shim_uniffi SHARED IMPORTED)
+# The cargo-ndk cdylib has no SONAME → IMPORTED_NO_SONAME so the NEEDED entry is the
+# basename (resolved by the loader from the APK), not the build-time path.
+set_target_properties(shim_uniffi PROPERTIES
+  IMPORTED_LOCATION ${RUST_LIB}
+  IMPORTED_NO_SONAME TRUE)
+
+find_library(LOG_LIB log)
+
+# `android` provides ANativeWindow_fromSurface/_release used by cpp-adapter.
+# react/jsi/fbjni/nitro come from the nitrogen autolinking include above.
+target_link_libraries(
+  ${PACKAGE_NAME}
+  shim_uniffi
+  android
+  ${LOG_LIB}
+)

package/android/build.gradle

@@ -0,0 +1,121 @@
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["x86", "x86_64", "armeabi-v7a", "arm64-v8a"]
+}
+
+// Build only ABIs the app is building (so the nitro prefab has a matching
+// libNitroModules.so) AND that we ship a prebuilt rust libfressh_render.so for
+// (see jniLibs). Building an ABI the app skips → header-only nitro prefab →
+// `undefined symbol: margelo::nitro::...` at link time.
+def supportedRustAbis = ["arm64-v8a", "x86_64"]
+def buildAbis = reactNativeArchitectures().findAll { supportedRustAbis.contains(it) }
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+// Nitrogen-generated: adds the generated kotlin srcDir.
+apply from: "../nitrogen/generated/android/ReactNativeTerminal+autolinking.gradle"
+// Nitro prefab workaround: makes the react-native-nitro-modules prefab link the
+// actual libNitroModules.so (not headers-only), else the native link fails with
+// `undefined symbol: margelo::nitro::HybridObject::...`. Every nitro module ships
+// this (react-native-nitro-modules + react-native-mmkv both apply it).
+apply from: "./fix-prefab.gradle"
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["ReactNativeTerminal_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["ReactNativeTerminal_" + name]).toInteger()
+}
+
+android {
+  namespace "com.margelo.nitro.fressh"
+
+  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 -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared"
+        abiFilters.addAll(buildAbis)
+      }
+    }
+    ndk {
+      abiFilters.addAll(buildAbis)
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  // These .so's are provided by react-native / nitro-modules at runtime; don't
+  // re-package them from our prefab inputs (avoids duplicate .so conflicts).
+  packagingOptions {
+    excludes = [
+      "META-INF",
+      "META-INF/**",
+      "**/libNitroModules.so",
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libreactnative.so",
+    ]
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  //noinspection GradleDynamicVersion
+  implementation "com.facebook.react:react-native:+"
+  // NitroModules core (prefab consumed by the generated autolinking CMake).
+  implementation project(":react-native-nitro-modules")
+}
+
+if (isNewArchitectureEnabled()) {
+  react {
+    jsRootDir = file("../src/")
+    libraryName = "ReactNativeTerminal"
+    codegenJavaPackageName = "com.margelo.nitro.fressh"
+  }
+}

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())
+        }
+      }
+    }
+  }
+}