@fressh/react-native-terminal 0.1.0

package/src/index.ts

@@ -0,0 +1,52 @@
+// Public API for @fressh/react-native-terminal.
+// Replaces @fressh/react-native-uniffi-russh + @fressh/react-native-xtermjs-webview.
+
+export {
+	Terminal,
+	type CursorBlink,
+	type CursorStyle,
+	type TerminalComponentProps,
+	type TerminalRef,
+	type TerminalRenderConfig,
+} from './Terminal';
+export type { TerminalMethods, TerminalProps } from '../nitro/Terminal.nitro';
+
+// Control plane (§10): connect/shell lifecycle + key helpers + the event stream.
+export {
+	addFresshEventListener,
+	closePreviewTerm,
+	closeShell,
+	connect,
+	createPreviewTerm,
+	disconnect,
+	FresshEvent_Tags,
+	generateKeyPair,
+	KeyType,
+	resize,
+	respondToHostKey,
+	runCommand,
+	scroll,
+	Security,
+	selectionClear,
+	SelectionKind,
+	selectionStart,
+	selectionText,
+	selectionUpdate,
+	sendData,
+	SshConnectionProgressEvent,
+	SshError_Tags,
+	startShell,
+	TerminalType,
+	validatePrivateKey,
+} from './ssh';
+export type {
+	CommandResult,
+	ConnectionDetails,
+	ConnectionId,
+	FresshEvent,
+	FresshEventCallback,
+	FresshEventListener,
+	ServerPublicKeyInfo,
+	ShellId,
+	ShellOptions,
+} from './ssh';

package/src/ssh.ts

@@ -0,0 +1,239 @@
+/**
+ * Control plane (§10): the JS-facing SSH API. Thin, typed wrappers over the
+ * generated uniffi shim (`./generated/shim_uniffi`), which forwards to
+ * `fressh-core`. Async + rare — the byte stream NEVER crosses here (it stays
+ * native, feeding the durable `Term`; the view reads it by `shellId`).
+ *
+ * Lifetime is the registry's (§7/§9): these calls pass string ids, never native
+ * handles, so a session survives JS GC / view unmount until an explicit
+ * `disconnect`/`closeShell`.
+ */
+
+import { NativeModules, TurboModuleRegistry } from 'react-native';
+import generatedModule, {
+	closePreview as _closePreview,
+	closeShell as _closeShell,
+	connect as _connect,
+	createPreview as _createPreview,
+	disconnect as _disconnect,
+	generateKeyPair as _generateKeyPair,
+	resize as _resize,
+	respondToHostKey as _respondToHostKey,
+	scroll as _scroll,
+	selectionClear as _selectionClear,
+	selectionStart as _selectionStart,
+	runCommand as _runCommand,
+	selectionText as _selectionText,
+	selectionUpdate as _selectionUpdate,
+	sendData as _sendData,
+	setEventListener as _setEventListener,
+	startShell as _startShell,
+	validatePrivateKey as _validatePrivateKey,
+	type CommandResult,
+	type ConnectionDetails,
+	type FresshEvent,
+	FresshEvent_Tags,
+	type FresshEventListener,
+	KeyType,
+	SelectionKind,
+	type ServerPublicKeyInfo,
+	Security,
+	type ShellOptions,
+	SshConnectionProgressEvent,
+	SshError_Tags,
+	TerminalType,
+} from './generated/shim_uniffi';
+
+// Re-export the generated enums/factories (values) the app needs to construct
+// inputs and match events.
+export {
+	FresshEvent_Tags,
+	KeyType,
+	Security,
+	SelectionKind,
+	SshConnectionProgressEvent,
+	SshError_Tags,
+	TerminalType,
+};
+// Records + the event union are plain object types — re-export as types.
+export type {
+	CommandResult,
+	ConnectionDetails,
+	FresshEvent,
+	FresshEventListener,
+	ServerPublicKeyInfo,
+	ShellOptions,
+};
+
+export type ConnectionId = string;
+export type ShellId = string;
+
+// ─────────────────────────── native install ───────────────────────────
+
+// The ubrn-generated bindings call `globalThis.NativeShimUniffi`, which only
+// exists after the native installer runs. We trigger it once (idempotent) on
+// first import — before any binding call. Without this, the first uniffi call
+// throws "Cannot read property 'ubrn_uniffi_shim_uniffi_fn_func_*' of undefined".
+//
+// Platform note: the two installers are registered differently, so we look the
+// module up both ways. Android's is a legacy bridge module (ReactPackage) → it
+// surfaces on `NativeModules`. iOS's is a C++ TurboModule (ReactNativeTerminalUniffi.mm,
+// method in `methodMap_`) → it surfaces on `TurboModuleRegistry`, NOT the legacy
+// `NativeModules` proxy (which only sees ObjC-exported methods). Try the
+// TurboModule path first, then fall back to NativeModules.
+type Installer = { installRustCrate?: () => boolean };
+let nativeInstalled = false;
+function ensureNativeInstalled() {
+	if (nativeInstalled) return;
+	const mod =
+		(TurboModuleRegistry.get?.(
+			'ReactNativeTerminalUniffi',
+		) as Installer | null) ??
+		(NativeModules as { ReactNativeTerminalUniffi?: Installer })
+			.ReactNativeTerminalUniffi;
+	if (mod?.installRustCrate) {
+		mod.installRustCrate();
+		// installRustCrate sets up `globalThis.NativeShimUniffi`; only now can the
+		// generated binding talk to the dylib. `initialize()` validates the
+		// scaffolding contract/checksums AND registers the callback-interface
+		// vtable (`ubrn_..._init_callback_vtable_fressheventlistener`). Skipping it
+		// leaves the vtable cell null, so the first time Rust invokes
+		// `FresshEventListener.on_event` it panics with "Foreign pointer not set."
+		generatedModule.initialize();
+		nativeInstalled = true;
+	}
+}
+
+ensureNativeInstalled();
+
+// ─────────────────────────── control plane ───────────────────────────
+
+/** Connect + authenticate. Resolves to a `connectionId`. A `HostKeyPending`
+ *  event fires mid-handshake — answer it with {@link respondToHostKey}. */
+export const connect = (details: ConnectionDetails): Promise<ConnectionId> =>
+	_connect(details);
+
+export const disconnect = (connectionId: ConnectionId): Promise<void> =>
+	_disconnect(connectionId);
+
+export const respondToHostKey = (
+	connectionId: ConnectionId,
+	accept: boolean,
+): void => _respondToHostKey(connectionId, accept);
+
+/** Open a PTY + shell. Resolves to a `shellId` — render it with
+ *  `<Terminal shellId={shellId} />`. */
+export const startShell = (
+	connectionId: ConnectionId,
+	options: ShellOptions,
+): Promise<ShellId> => _startShell(connectionId, options);
+
+/** Run a one-off command on an existing connection without opening a PTY/shell.
+ *  Resolves to `{ stdout, stderr, exitCode }`. Runs in the login/home dir — an
+ *  `exec` channel does NOT inherit a live shell's cwd (use `cd … && …` if needed). */
+export const runCommand = (
+	connectionId: ConnectionId,
+	command: string,
+): Promise<CommandResult> => _runCommand(connectionId, command);
+
+/** Send user input (stdin). Also reachable on the render plane (the view forwards
+ *  key/IME input straight to native), so most apps won't call this directly. */
+export const sendData = (shellId: ShellId, data: ArrayBuffer): Promise<void> =>
+	_sendData(shellId, data);
+
+export const resize = (
+	shellId: ShellId,
+	cols: number,
+	rows: number,
+): Promise<void> => _resize(shellId, cols, rows);
+
+export const closeShell = (shellId: ShellId): Promise<void> =>
+	_closeShell(shellId);
+
+// ─────────────────────────── preview (non-SSH `Term`) ─────────────────────────
+// A `Term` driven by a canned byte snippet instead of an SSH channel — the
+// foundation for the Terminal-settings live preview (and, later, an on-device
+// local shell). It rides the SAME render plane as a real shell: render it with
+// `<Terminal shellId={previewId} />` and the live `config` prop still reflows it.
+
+/** Create a preview shell bound to `previewId`, fed `demo` bytes once. Synchronous
+ *  (no network). Tear down with {@link closePreviewTerm} on unmount. */
+export const createPreviewTerm = (
+	previewId: ShellId,
+	demo: ArrayBuffer,
+): void => _createPreview(previewId, demo);
+
+/** Tear down a preview shell. Emits no `ShellClosed` event (its lifetime is owned
+ *  by the screen that created it, not the app's session list). */
+export const closePreviewTerm = (previewId: ShellId): Promise<void> =>
+	_closePreview(previewId);
+
+export const generateKeyPair = (keyType: KeyType): string =>
+	_generateKeyPair(keyType);
+
+export const validatePrivateKey = (pem: string): string =>
+	_validatePrivateKey(pem);
+
+// ─────────────────────── touch interaction (scroll + selection) ──────────────
+// Touch gestures live in JS (cross-platform), but the terminal logic lives in
+// Rust keyed by `shellId` — these wrappers call it. Coordinates are PHYSICAL px
+// (surface-relative); the caller scales logical pt by the device pixel ratio,
+// matching how `<Terminal config>` already scales font/padding.
+
+/** Scroll by `deltaPx` physical px (positive = finger dragged down = older
+ *  content). Honors the app's mouse/alt-screen mode; else moves scrollback. */
+export const scroll = (shellId: ShellId, deltaPx: number): Promise<void> =>
+	_scroll(shellId, deltaPx);
+
+/** Begin a selection at a touch point (physical px). */
+export const selectionStart = (
+	shellId: ShellId,
+	x: number,
+	y: number,
+	kind: SelectionKind = SelectionKind.Word,
+): void => _selectionStart(shellId, x, y, kind);
+
+/** Extend the active selection to a touch point (physical px). */
+export const selectionUpdate = (shellId: ShellId, x: number, y: number): void =>
+	_selectionUpdate(shellId, x, y);
+
+/** Clear any active selection. */
+export const selectionClear = (shellId: ShellId): void =>
+	_selectionClear(shellId);
+
+/** The currently selected text, if any. */
+export const selectionText = (shellId: ShellId): string | undefined =>
+	_selectionText(shellId);
+
+// ─────────────────────────── event plane (one-way) ───────────────────────────
+
+export type FresshEventCallback = (event: FresshEvent) => void;
+
+// uniffi accepts ONE listener; register a single fan-out and dispatch to many JS
+// subscribers so the app can have independent listeners (connect flow, per-shell
+// close handlers, host-key prompts) without clobbering one another.
+const subscribers = new Set<FresshEventCallback>();
+let installed = false;
+
+function ensureInstalled() {
+	if (installed) return;
+	ensureNativeInstalled();
+	installed = true;
+	const listener: FresshEventListener = {
+		onEvent(event) {
+			// Snapshot so a callback that (un)subscribes mid-dispatch is safe.
+			for (const cb of Array.from(subscribers)) cb(event);
+		},
+	};
+	_setEventListener(listener);
+}
+
+/** Subscribe to the low-frequency event stream (progress, host-key, closed).
+ *  Returns an unsubscribe fn. */
+export function addFresshEventListener(cb: FresshEventCallback): () => void {
+	ensureInstalled();
+	subscribers.add(cb);
+	return () => {
+		subscribers.delete(cb);
+	};
+}

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"types": ["node"],
+		"rootDir": ".",
+		"paths": {
+			"@fressh/react-native-terminal": ["./src/index"]
+		},
+		"allowUnreachableCode": false,
+		"allowUnusedLabels": false,
+		"customConditions": ["react-native-strict-api"],
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"jsx": "react-jsx",
+		"lib": ["ESNext"],
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"noEmit": true,
+		"noFallthroughCasesInSwitch": true,
+		"noImplicitReturns": true,
+		"noUncheckedIndexedAccess": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"strict": true,
+		"target": "ESNext",
+		"verbatimModuleSyntax": true,
+		"noUnusedLocals": false,
+		"noUnusedParameters": false
+	},
+	"include": ["src/**/*.ts", "src/**/*.tsx", "nitro/**/*.ts"]
+}

package/ubrn.config.yaml

@@ -0,0 +1,24 @@
+# uniffi-bindgen-react-native config for the SSH control-plane shim.
+#
+# This package is unusual: it hosts BOTH a Nitro HybridView (the render plane)
+# AND the uniffi control plane in ONE `.so` (§8), so we do NOT let ubrn own the
+# android build files (Nitro's CMakeLists/build.gradle are hand-authored). The
+# `ubrn:generate` script runs `generate jsi bindings --library` against the
+# cargo-built `libshim_uniffi.a` to emit only the TS + C++ bindings; the umbrella
+# CMakeLists includes that C++ and links the staticlib (shared registry, §8).
+rust:
+  directory: rust
+  manifestPath: shim-uniffi/Cargo.toml
+
+bindings:
+  cpp: cpp/generated
+  ts: src/generated
+
+android:
+  jniLibs: android/src/main/jniLibs
+  # Linked as a static archive into the single package `.so` (shared registry
+  # statics, §8) — NOT a standalone shared lib.
+  useSharedLibrary: false
+  targets:
+    - arm64-v8a
+    - x86_64