feat(native): add React Native viewer with Clerk auth

native-app/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+.expo
+android
+ios
+dist

native-app/App.tsx

@@ -0,0 +1,66 @@
+import "react-native-url-polyfill/auto";
+
+import { ClerkProvider, SignedIn, SignedOut, useAuth } from "@clerk/clerk-expo";
+import { tokenCache } from "@clerk/clerk-expo/token-cache";
+import { ActivityIndicator, StyleSheet, Text, View } from "react-native";
+
+import { SignInScreen } from "./src/screens/SignInScreen";
+import { ViewerScreen } from "./src/screens/ViewerScreen";
+
+const publishableKey = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY;
+
+function AuthReadyGate() {
+  const { isLoaded } = useAuth();
+
+  if (!isLoaded) {
+    return (
+      <View style={styles.loadingWrap}>
+        <ActivityIndicator color="#125dc6" size="large" />
+      </View>
+    );
+  }
+
+  return (
+    <>
+      <SignedOut>
+        <SignInScreen />
+      </SignedOut>
+      <SignedIn>
+        <ViewerScreen />
+      </SignedIn>
+    </>
+  );
+}
+
+export default function App() {
+  if (!publishableKey) {
+    return (
+      <View style={styles.loadingWrap}>
+        <Text style={styles.errorText}>
+          Missing EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY
+        </Text>
+      </View>
+    );
+  }
+
+  return (
+    <ClerkProvider publishableKey={publishableKey} tokenCache={tokenCache}>
+      <AuthReadyGate />
+    </ClerkProvider>
+  );
+}
+
+const styles = StyleSheet.create({
+  loadingWrap: {
+    alignItems: "center",
+    backgroundColor: "#eef4fa",
+    flex: 1,
+    justifyContent: "center",
+  },
+  errorText: {
+    color: "#9b1026",
+    fontSize: 16,
+    paddingHorizontal: 20,
+    textAlign: "center",
+  },
+});

native-app/README.md

@@ -0,0 +1,54 @@
+# Helium Native (Expo + React Native)
+
+Simple React Native viewer app that:
+
+- Authenticates with Clerk (`@clerk/clerk-expo`)
+- Connects to Helium signaling at `/ws/signaling`
+- Joins a 6-digit room and answers WebRTC offers
+- Renders incoming stream with `RTCView`
+
+## Auth implementation notes (from Clerk docs via Context7)
+
+This app follows Clerk Expo guidance:
+
+- Wrap app with `ClerkProvider`
+- Use secure `tokenCache` from `@clerk/clerk-expo/token-cache`
+- Configure `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`
+- Use `useSignIn()` and `setActive()` for email/password sign-in
+- Use `useAuth()` for sign-out and auth state gating
+
+## Environment variables
+
+Create `native-app/.env`:
+
+```env
+EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
+EXPO_PUBLIC_HELIUM_BASE_URL=https://helium.srizan.dev
+```
+
+## Install
+
+```bash
+pnpm -C native-app install
+```
+
+## Run on Android
+
+`react-native-webrtc` requires native modules, so use a development build:
+
+```bash
+pnpm -C native-app prebuild
+pnpm -C native-app android
+```
+
+## Signaling protocol wired
+
+Implemented in `native-app/src/hooks/useHeliumViewer.ts`:
+
+- send `join-room`
+- receive `offer`
+- create peer connection with provided `iceServers`
+- set remote description and send `answer`
+- exchange `ice-candidate`
+- handle `room-closed`
+- heartbeat with `ping` every 15s

native-app/app.json

@@ -0,0 +1,16 @@
+{
+  "expo": {
+    "name": "Helium Native",
+    "slug": "helium-native",
+    "scheme": "heliumnative",
+    "version": "0.1.0",
+    "orientation": "portrait",
+    "userInterfaceStyle": "light",
+    "android": {
+      "package": "dev.srizan.helium.native"
+    },
+    "plugins": [
+      "expo-secure-store"
+    ]
+  }
+}

native-app/babel.config.js

@@ -0,0 +1,7 @@
+module.exports = function(api) {
+  api.cache(true);
+
+  return {
+    presets: ["babel-preset-expo"],
+  };
+};

native-app/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "helium-native",
+  "version": "0.1.0",
+  "private": true,
+  "main": "expo/AppEntry",
+  "scripts": {
+    "start": "expo start",
+    "android": "expo run:android",
+    "ios": "expo run:ios",
+    "prebuild": "expo prebuild",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clerk/clerk-expo": "^2.19.22",
+    "expo": "^54.0.0",
+    "expo-secure-store": "^15.0.0",
+    "react": "19.2.0",
+    "react-native": "0.82.0",
+    "react-native-url-polyfill": "^2.0.0",
+    "react-native-webrtc": "^124.0.7"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.2",
+    "typescript": "^5.9.3"
+  }
+}

native-app/src/hooks/useHeliumViewer.ts

@@ -0,0 +1,224 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  MediaStream,
+  RTCPeerConnection,
+  RTCIceCandidate,
+  RTCSessionDescription,
+} from "react-native-webrtc";
+
+import { getSignalingUrl } from "../lib/signaling";
+import type {
+  IncomingSignalingMessage,
+  SignalingOfferEvent,
+} from "../types/signaling";
+
+interface UseHeliumViewerResult {
+  status: string;
+  streamUrl: string | null;
+  connect: (roomId: string) => void;
+  disconnect: () => void;
+  isConnected: boolean;
+}
+
+interface PeerConnectionHandlers {
+  ontrack: ((event: { streams?: MediaStream[] }) => void) | null;
+  onicecandidate:
+    | ((event: { candidate: RTCIceCandidate | null }) => void)
+    | null;
+  onconnectionstatechange: (() => void) | null;
+}
+
+export function useHeliumViewer(): UseHeliumViewerResult {
+  const wsRef = useRef<WebSocket | null>(null);
+  const pcRef = useRef<RTCPeerConnection | null>(null);
+  const targetPeerIdRef = useRef<string | null>(null);
+  const heartbeatRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const [status, setStatus] = useState<string>("idle");
+  const [streamUrl, setStreamUrl] = useState<string | null>(null);
+  const [isConnected, setIsConnected] = useState<boolean>(false);
+
+  const sendMessage = useCallback((payload: object): void => {
+    const ws = wsRef.current;
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+      return;
+    }
+
+    ws.send(JSON.stringify(payload));
+  }, []);
+
+  const cleanupPeerConnection = useCallback((): void => {
+    const pc = pcRef.current;
+    if (pc) {
+      pc.close();
+      pcRef.current = null;
+    }
+    targetPeerIdRef.current = null;
+    setIsConnected(false);
+  }, []);
+
+  const disconnect = useCallback((): void => {
+    if (heartbeatRef.current) {
+      clearInterval(heartbeatRef.current);
+      heartbeatRef.current = null;
+    }
+
+    cleanupPeerConnection();
+    setStreamUrl(null);
+
+    const ws = wsRef.current;
+    if (ws) {
+      ws.close();
+      wsRef.current = null;
+    }
+
+    setStatus("disconnected");
+  }, [cleanupPeerConnection]);
+
+  const handleOffer = useCallback(
+    async (message: SignalingOfferEvent): Promise<void> => {
+      setStatus("received offer");
+
+      cleanupPeerConnection();
+      targetPeerIdRef.current = message.senderId;
+
+      const pc = new RTCPeerConnection({
+        iceServers: message.iceServers ?? [],
+      });
+      const pcWithHandlers = pc as RTCPeerConnection & PeerConnectionHandlers;
+      pcRef.current = pc;
+
+      pcWithHandlers.ontrack = (event): void => {
+        const stream = event.streams?.[0] as MediaStream | undefined;
+        if (!stream) {
+          return;
+        }
+
+        setStreamUrl(stream.toURL());
+      };
+
+      pcWithHandlers.onicecandidate = (event): void => {
+        if (!event.candidate || !targetPeerIdRef.current) {
+          return;
+        }
+
+        sendMessage({
+          event: "ice-candidate",
+          targetId: targetPeerIdRef.current,
+          candidate: event.candidate,
+        });
+      };
+
+      pcWithHandlers.onconnectionstatechange = (): void => {
+        setStatus(`peer: ${pc.connectionState}`);
+        if (pc.connectionState === "connected") {
+          setIsConnected(true);
+        }
+        if (pc.connectionState === "failed" || pc.connectionState === "closed") {
+          setIsConnected(false);
+        }
+      };
+
+      await pc.setRemoteDescription(new RTCSessionDescription(message.sdp));
+      const answer = await pc.createAnswer();
+      await pc.setLocalDescription(answer);
+
+      sendMessage({
+        event: "answer",
+        targetId: message.senderId,
+        sdp: answer,
+      });
+
+      setStatus("sent answer");
+    },
+    [cleanupPeerConnection, sendMessage],
+  );
+
+  const handleIncomingMessage = useCallback(
+    async (event: MessageEvent<string>): Promise<void> => {
+      const message = JSON.parse(event.data) as IncomingSignalingMessage;
+
+      if (message.event === "joined") {
+        setStatus(`joined room ${message.roomId}`);
+        return;
+      }
+
+      if (message.event === "offer") {
+        await handleOffer(message);
+        return;
+      }
+
+      if (message.event === "ice-candidate") {
+        const pc = pcRef.current;
+        if (!pc || !pc.remoteDescription) {
+          return;
+        }
+
+        await pc.addIceCandidate(new RTCIceCandidate(message.candidate));
+        return;
+      }
+
+      if (message.event === "room-closed") {
+        disconnect();
+        setStatus("room closed by host");
+        return;
+      }
+
+      if (message.event === "error") {
+        setStatus(`error: ${message.message}`);
+      }
+    },
+    [disconnect, handleOffer],
+  );
+
+  const connect = useCallback(
+    (roomId: string): void => {
+      disconnect();
+
+      setStatus("connecting websocket");
+      const ws = new WebSocket(getSignalingUrl());
+      wsRef.current = ws;
+
+      ws.onopen = (): void => {
+        setStatus("websocket connected");
+        sendMessage({ event: "join-room", roomId });
+
+        heartbeatRef.current = setInterval(() => {
+          sendMessage({ event: "ping" });
+        }, 15000);
+      };
+
+      ws.onmessage = (event): void => {
+        void handleIncomingMessage(event);
+      };
+
+      ws.onerror = (): void => {
+        setStatus("websocket error");
+      };
+
+      ws.onclose = (): void => {
+        if (heartbeatRef.current) {
+          clearInterval(heartbeatRef.current);
+          heartbeatRef.current = null;
+        }
+        setStatus("websocket closed");
+        setIsConnected(false);
+      };
+    },
+    [disconnect, handleIncomingMessage, sendMessage],
+  );
+
+  useEffect(() => {
+    return () => {
+      disconnect();
+    };
+  }, [disconnect]);
+
+  return {
+    status,
+    streamUrl,
+    connect,
+    disconnect,
+    isConnected,
+  };
+}

native-app/src/lib/signaling.ts

@@ -0,0 +1,14 @@
+const DEFAULT_BASE_URL = "https://helium.srizan.dev";
+
+export function getHeliumBaseUrl(): string {
+  return process.env.EXPO_PUBLIC_HELIUM_BASE_URL ?? DEFAULT_BASE_URL;
+}
+
+export function getSignalingUrl(baseUrl: string = getHeliumBaseUrl()): string {
+  const url = new URL(baseUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.pathname = "/ws/signaling";
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}

native-app/src/screens/SignInScreen.tsx

@@ -0,0 +1,130 @@
+import { useState } from "react";
+import { useSignIn } from "@clerk/clerk-expo";
+import {
+  ActivityIndicator,
+  Pressable,
+  StyleSheet,
+  Text,
+  TextInput,
+  View,
+} from "react-native";
+
+export function SignInScreen() {
+  const { isLoaded, signIn, setActive } = useSignIn();
+  const [email, setEmail] = useState<string>("");
+  const [password, setPassword] = useState<string>("");
+  const [status, setStatus] = useState<string>("");
+
+  const onSignIn = async (): Promise<void> => {
+    if (!isLoaded) {
+      return;
+    }
+
+    setStatus("Signing in...");
+
+    try {
+      const attempt = await signIn.create({
+        identifier: email.trim(),
+        password,
+      });
+
+      if (attempt.status === "complete") {
+        await setActive({ session: attempt.createdSessionId });
+        setStatus("Signed in");
+        return;
+      }
+
+      setStatus(`Needs extra step: ${attempt.status}`);
+    } catch {
+      setStatus("Sign-in failed");
+    }
+  };
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Helium Native</Text>
+      <Text style={styles.subtitle}>Sign in with Clerk</Text>
+
+      <TextInput
+        autoCapitalize="none"
+        keyboardType="email-address"
+        onChangeText={setEmail}
+        placeholder="Email"
+        placeholderTextColor="#7e8794"
+        style={styles.input}
+        value={email}
+      />
+      <TextInput
+        onChangeText={setPassword}
+        placeholder="Password"
+        placeholderTextColor="#7e8794"
+        secureTextEntry
+        style={styles.input}
+        value={password}
+      />
+
+      <Pressable
+        disabled={!isLoaded || !email || !password}
+        onPress={() => {
+          void onSignIn();
+        }}
+        style={styles.button}
+      >
+        {isLoaded ? (
+          <Text style={styles.buttonText}>Sign in</Text>
+        ) : (
+          <ActivityIndicator color="#ffffff" />
+        )}
+      </Pressable>
+
+      <Text style={styles.status}>{status}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: "stretch",
+    backgroundColor: "#f4f8fb",
+    flex: 1,
+    gap: 12,
+    justifyContent: "center",
+    padding: 24,
+  },
+  title: {
+    color: "#0f1f33",
+    fontSize: 28,
+    fontWeight: "700",
+    textAlign: "center",
+  },
+  subtitle: {
+    color: "#4a5f79",
+    marginBottom: 12,
+    textAlign: "center",
+  },
+  input: {
+    backgroundColor: "#ffffff",
+    borderColor: "#c8d7ea",
+    borderRadius: 12,
+    borderWidth: 1,
+    color: "#11243d",
+    paddingHorizontal: 14,
+    paddingVertical: 12,
+  },
+  button: {
+    alignItems: "center",
+    backgroundColor: "#1366d6",
+    borderRadius: 12,
+    paddingVertical: 12,
+  },
+  buttonText: {
+    color: "#ffffff",
+    fontSize: 16,
+    fontWeight: "700",
+  },
+  status: {
+    color: "#405166",
+    fontSize: 13,
+    textAlign: "center",
+  },
+});

native-app/src/screens/ViewerScreen.tsx

@@ -0,0 +1,150 @@
+import { useState } from "react";
+import { useAuth } from "@clerk/clerk-expo";
+import {
+  Pressable,
+  SafeAreaView,
+  StyleSheet,
+  Text,
+  TextInput,
+  View,
+} from "react-native";
+import { RTCView } from "react-native-webrtc";
+
+import { useHeliumViewer } from "../hooks/useHeliumViewer";
+
+export function ViewerScreen() {
+  const { signOut } = useAuth();
+  const [roomCode, setRoomCode] = useState<string>("");
+  const { connect, disconnect, isConnected, status, streamUrl } = useHeliumViewer();
+
+  return (
+    <SafeAreaView style={styles.safeArea}>
+      <View style={styles.container}>
+        <Text style={styles.title}>Helium Viewer</Text>
+        <Text style={styles.status}>{status}</Text>
+
+        <TextInput
+          autoCapitalize="none"
+          keyboardType="number-pad"
+          maxLength={6}
+          onChangeText={(text: string) => {
+            setRoomCode(text.replace(/\D/g, ""));
+          }}
+          placeholder="Enter 6-digit room code"
+          placeholderTextColor="#6a7a8e"
+          style={styles.input}
+          value={roomCode}
+        />
+
+        <View style={styles.actions}>
+          <Pressable
+            disabled={roomCode.length !== 6}
+            onPress={() => {
+              connect(roomCode);
+            }}
+            style={styles.primaryButton}
+          >
+            <Text style={styles.primaryButtonText}>Connect</Text>
+          </Pressable>
+
+          <Pressable onPress={disconnect} style={styles.secondaryButton}>
+            <Text style={styles.secondaryButtonText}>Disconnect</Text>
+          </Pressable>
+
+          <Pressable
+            onPress={() => {
+              void signOut();
+            }}
+            style={styles.secondaryButton}
+          >
+            <Text style={styles.secondaryButtonText}>Sign out</Text>
+          </Pressable>
+        </View>
+
+        <View style={styles.videoWrap}>
+          {isConnected && streamUrl ? (
+            <RTCView
+              mirror={false}
+              objectFit="contain"
+              streamURL={streamUrl}
+              style={styles.video}
+            />
+          ) : (
+            <Text style={styles.placeholder}>No stream yet</Text>
+          )}
+        </View>
+      </View>
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  safeArea: {
+    backgroundColor: "#f0f6fd",
+    flex: 1,
+  },
+  container: {
+    flex: 1,
+    gap: 12,
+    padding: 18,
+  },
+  title: {
+    color: "#12263c",
+    fontSize: 22,
+    fontWeight: "700",
+  },
+  status: {
+    color: "#4f6278",
+    fontSize: 13,
+  },
+  input: {
+    backgroundColor: "#ffffff",
+    borderColor: "#d3deeb",
+    borderRadius: 12,
+    borderWidth: 1,
+    color: "#10233b",
+    fontSize: 16,
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+  },
+  actions: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    gap: 8,
+  },
+  primaryButton: {
+    backgroundColor: "#0e68de",
+    borderRadius: 10,
+    paddingHorizontal: 14,
+    paddingVertical: 10,
+  },
+  primaryButtonText: {
+    color: "#ffffff",
+    fontWeight: "700",
+  },
+  secondaryButton: {
+    backgroundColor: "#e4edf8",
+    borderRadius: 10,
+    paddingHorizontal: 14,
+    paddingVertical: 10,
+  },
+  secondaryButtonText: {
+    color: "#21354d",
+    fontWeight: "600",
+  },
+  videoWrap: {
+    alignItems: "center",
+    backgroundColor: "#0a121e",
+    borderRadius: 14,
+    flex: 1,
+    justifyContent: "center",
+    overflow: "hidden",
+  },
+  video: {
+    height: "100%",
+    width: "100%",
+  },
+  placeholder: {
+    color: "#92a3b8",
+  },
+});

native-app/src/types/signaling.ts

@@ -0,0 +1,39 @@
+export interface NativeSessionDescriptionInit {
+  type: "offer" | "answer" | "pranswer" | "rollback";
+  sdp: string;
+}
+
+export interface SignalingOfferEvent {
+  event: "offer";
+  sdp: NativeSessionDescriptionInit;
+  senderId: string;
+  iceServers?: RTCIceServer[];
+}
+
+export interface SignalingIceCandidateEvent {
+  event: "ice-candidate";
+  from: string;
+  candidate: RTCIceCandidateInit;
+}
+
+export interface SignalingJoinedEvent {
+  event: "joined";
+  roomId: string;
+}
+
+export interface SignalingErrorEvent {
+  event: "error";
+  message: string;
+}
+
+export interface SignalingRoomClosedEvent {
+  event: "room-closed";
+}
+
+export type IncomingSignalingMessage =
+  | SignalingOfferEvent
+  | SignalingIceCandidateEvent
+  | SignalingJoinedEvent
+  | SignalingErrorEvent
+  | SignalingRoomClosedEvent
+  | { event: "pong" };

native-app/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["App.tsx", "src/**/*.ts", "src/**/*.tsx"]
+}

package.json

@@ -32,7 +32,11 @@
     "mobile:build": "pnpm -C mobile-wrapper build",
     "mobile:android:add": "pnpm -C mobile-wrapper cap:android:add",
     "mobile:android:sync": "pnpm -C mobile-wrapper cap:sync",
-    "mobile:android:open": "pnpm -C mobile-wrapper cap:android:open"
+    "mobile:android:open": "pnpm -C mobile-wrapper cap:android:open",
+    "native:install": "pnpm -C native-app install",
+    "native:android": "pnpm -C native-app android",
+    "native:start": "pnpm -C native-app start",
+    "native:typecheck": "pnpm -C native-app typecheck"
   },
   "dependencies": {
     "@clerk/localizations": "^3.34.0",

pnpm-workspace.yaml

@@ -1,6 +1,7 @@
 packages:
   - .
   - mobile-wrapper
+  - native-app
 
 onlyBuiltDependencies:
   - '@vencord/venmic'