@usequark/quark-create-app 1.23.11

package/templates/mobile/README.md

@@ -0,0 +1,130 @@
+# Quark Mobile App
+
+Expo-based mobile client for Quark projects.
+
+## Quick Start
+
+```bash
+# 1. Start the backend (web + worker) from project root
+pnpm dev
+
+# 2. In a second terminal — start the mobile app
+cd apps/mobile
+echo 'EXPO_PUBLIC_API_URL=http://localhost:3000' > .env
+npx expo start
+```
+
+## Review on MacBook (Android Emulator)
+
+Requires [Android Studio](https://developer.android.com/studio) with an AVD created.
+
+```bash
+# First time only: install dependencies + generate native dirs
+npx expo prebuild --platform android
+
+# Run on Android emulator
+npx expo run:android
+
+# Subsequent runs (fast — reuses build cache)
+npx expo run:android
+```
+
+Hot reload works out of the box. Shake menu (`Cmd+M`) to open dev tools.
+
+## Review on Physical Android Phone
+
+### Option A: Expo Go (quickest, no build)
+
+1. Install **Expo Go** from the Play Store
+2. Run `npx expo start` and scan the QR code
+3. Limitation: `expo-secure-store` and `expo-notifications` behave differently in Expo Go — use for UI/layout review only
+
+### Option B: Development Build (full fidelity)
+
+```bash
+# First time: generate native dirs + install on device via USB
+npx expo prebuild --platform android
+npx expo run:android --device
+
+# Or use EAS Build for a wireless install
+npx eas build --profile development --platform android
+# Download the .apk from the EAS dashboard, install on phone
+```
+
+Development builds support all native modules (`expo-secure-store`, `expo-notifications`) identically to production.
+
+## Commands Reference
+
+### Development
+
+| Command | What it does |
+|---|---|
+| `npx expo start` | Start Metro bundler (JS only, fastest) |
+| `npx expo start --clear` | Start with cleared cache |
+| `npx expo run:android` | Build + run on Android emulator/device |
+| `npx expo run:android --device` | Build + run on connected physical device |
+| `npx expo start --tunnel` | Expose local server over the internet (for testing on phone without same WiFi) |
+
+### Production Builds
+
+| Command | What it does |
+|---|---|
+| `npx eas build --profile production --platform android` | Build release APK/AAB for Play Store |
+| `npx eas build --profile production --platform ios` | Build release IPA for App Store |
+| `npx eas build --platform all` | Build both platforms |
+
+### OTA Updates
+
+| Command | What it does |
+|---|---|
+| `npx eas update --channel staging` | Push JS changes to staging channel |
+| `npx eas update --channel production` | Push JS changes to production (live users) |
+
+OTA is instant — no app store review needed for JS-only changes. See `CHECKLIST.md` for what qualifies.
+
+### Scripts (from project root)
+
+| Command | What it does |
+|---|---|
+| `pnpm dev` | Start web + worker (API on :3000) |
+| `pnpm build:mobile` | Export mobile app for preview |
+
+## Environment
+
+| Variable | Required | Description |
+|---|---|---|
+| `EXPO_PUBLIC_API_URL` | Yes | Backend API URL (e.g. `http://localhost:3000` or `https://your-app.quark.dev`) |
+| `EXPO_PUBLIC_GOOGLE_CLIENT_ID` | Optional | Google Sign-In client ID |
+
+Set in `apps/mobile/.env`. The `EXPO_PUBLIC_` prefix is required by Expo for client-side access.
+
+## Architecture
+
+- **Expo Router v55** — File-based routing
+- **expo-secure-store** — Secure token storage (never AsyncStorage)
+- **Zod** — All validation at system boundaries
+- **fetch** — HTTP client with auth injection + automatic 401 retry
+
+## Auth Flow
+
+1. Sign in via `/api/auth/token` → receives JWT + refresh token
+2. Tokens stored in `expo-secure-store`
+3. API calls include `Authorization: Bearer <token>` header
+4. On 401, token refresh attempted via `/api/auth/refresh`
+5. On refresh failure, auth cleared and user redirected to sign-in
+
+## Push Notifications
+
+- Token registered on app launch after authentication
+- APNs (iOS) and FCM (Android) handled server-side via worker jobs
+- No Firebase SDK on client or server
+
+## Deep Linking
+
+Configure your URL scheme in `app.json` under `expo.scheme`. Expo Router handles file-based deep linking automatically.
+
+## OTA Updates
+
+Configured via `expo-updates`. Channels: `development` → `staging` → `production`.
+
+See `CHECKLIST.md` for OTA vs store build decisions.

package/templates/mobile/app/(app)/_layout.tsx

@@ -0,0 +1,83 @@
+import { Ionicons } from "@expo/vector-icons";
+import { Redirect, Tabs } from "expo-router";
+import { Platform } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { AuthGate } from "../../components/AuthGate";
+import { useTheme } from "../../components/ThemeProvider";
+import { useAuth } from "../../hooks/use-auth";
+
+export default function AppLayout() {
+	const { isAuthenticated, isLoading } = useAuth();
+	const insets = useSafeAreaInsets();
+	const theme = useTheme();
+	const isDark = theme === "dark";
+
+	if (isLoading) {
+		return null;
+	}
+
+	if (!isAuthenticated) {
+		return <Redirect href="/(auth)/sign-in" />;
+	}
+
+	return (
+		<AuthGate>
+			<Tabs
+				screenOptions={{
+					headerShown: false,
+					tabBarStyle: {
+						backgroundColor: isDark ? "#1c1c1e" : "#ffffff",
+						borderTopColor: isDark ? "#38383a" : "#e5e5ea",
+						paddingBottom: Platform.OS === "ios" ? insets.bottom : 8,
+						height: Platform.OS === "ios" ? 88 : 64,
+					},
+					tabBarActiveTintColor: isDark ? "#fff" : "#000",
+					tabBarInactiveTintColor: isDark ? "#888" : "#666",
+				}}
+			>
+				<Tabs.Screen
+					name="index"
+					options={{
+						title: "Home",
+						tabBarLabel: "Home",
+						tabBarIcon: ({ color, size }) => (
+							<Ionicons
+								name="home-outline"
+								size={size}
+								color={color as string}
+							/>
+						),
+					}}
+				/>
+				<Tabs.Screen
+					name="profile"
+					options={{
+						title: "Profile",
+						tabBarLabel: "Profile",
+						tabBarIcon: ({ color, size }) => (
+							<Ionicons
+								name="person-outline"
+								size={size}
+								color={color as string}
+							/>
+						),
+					}}
+				/>
+				<Tabs.Screen
+					name="settings"
+					options={{
+						title: "Settings",
+						tabBarLabel: "Settings",
+						tabBarIcon: ({ color, size }) => (
+							<Ionicons
+								name="settings-outline"
+								size={size}
+								color={color as string}
+							/>
+						),
+					}}
+				/>
+			</Tabs>
+		</AuthGate>
+	);
+}

package/templates/mobile/app/(app)/index.tsx

@@ -0,0 +1,147 @@
+import { useCallback, useEffect, useState } from "react";
+import {
+	ActivityIndicator,
+	RefreshControl,
+	ScrollView,
+	Text,
+	View,
+} from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useAuth } from "../../hooks/use-auth";
+import { getProfile } from "../../lib/auth";
+import { useThemeTokens } from "../../lib/theme-tokens";
+
+interface UserProfile {
+	id: string;
+	email: string;
+	name: string | null;
+	role: string;
+}
+
+export default function HomeScreen() {
+	const { isAuthenticated } = useAuth();
+	const { bgColor, textColor, mutedColor, cardBg, borderColor, isDark } =
+		useThemeTokens();
+	const insets = useSafeAreaInsets();
+	const [profile, setProfile] = useState<UserProfile | null>(null);
+	const [loading, setLoading] = useState(true);
+	const [refreshing, setRefreshing] = useState(false);
+
+	const fetchProfile = useCallback(async () => {
+		try {
+			const data = await getProfile();
+			setProfile(data);
+		} catch {
+			// Profile fetch failed - non-critical
+		} finally {
+			setLoading(false);
+			setRefreshing(false);
+		}
+	}, []);
+
+	useEffect(() => {
+		if (isAuthenticated) {
+			fetchProfile();
+		}
+	}, [isAuthenticated, fetchProfile]);
+
+	async function onRefresh() {
+		setRefreshing(true);
+		await fetchProfile();
+	}
+
+	if (loading) {
+		return (
+			<View
+				style={{
+					flex: 1,
+					justifyContent: "center",
+					alignItems: "center",
+					backgroundColor: bgColor,
+				}}
+				accessibilityLabel="Loading home screen"
+				accessibilityRole="progressbar"
+			>
+				<ActivityIndicator size="large" color={isDark ? "#fff" : "#000"} />
+			</View>
+		);
+	}
+
+	return (
+		<ScrollView
+			style={{ flex: 1, backgroundColor: bgColor }}
+			contentContainerStyle={{
+				padding: 20,
+				paddingTop: insets.top + 20,
+			}}
+			refreshControl={
+				<RefreshControl refreshing={refreshing} onRefresh={onRefresh} />
+			}
+			accessibilityLabel="Home screen content"
+		>
+			<Text
+				style={{
+					fontSize: 28,
+					fontWeight: "bold",
+					color: textColor,
+					marginBottom: 8,
+				}}
+				accessibilityRole="header"
+			>
+				Welcome{profile?.name ? `, ${profile.name}` : ""}
+			</Text>
+			<Text style={{ fontSize: 16, color: mutedColor, marginBottom: 24 }}>
+				{profile?.email || "Signed in to your account"}
+			</Text>
+
+			<View
+				style={{
+					backgroundColor: cardBg,
+					borderRadius: 12,
+					padding: 16,
+					marginBottom: 16,
+					borderWidth: 1,
+					borderColor,
+				}}
+				accessibilityLabel="Account info card"
+				accessibilityRole="summary"
+			>
+				<Text style={{ fontSize: 14, color: mutedColor, marginBottom: 4 }}>
+					Account
+				</Text>
+				<Text style={{ fontSize: 16, color: textColor, fontWeight: "500" }}>
+					{profile?.name || "No name set"}
+				</Text>
+				<Text style={{ fontSize: 14, color: mutedColor, marginTop: 4 }}>
+					{profile?.email}
+				</Text>
+			</View>
+
+			<View
+				style={{
+					backgroundColor: cardBg,
+					borderRadius: 12,
+					padding: 16,
+					borderWidth: 1,
+					borderColor,
+				}}
+				accessibilityLabel="Quick actions card"
+				accessibilityRole="summary"
+			>
+				<Text style={{ fontSize: 14, color: mutedColor, marginBottom: 4 }}>
+					Role
+				</Text>
+				<Text
+					style={{
+						fontSize: 16,
+						color: textColor,
+						fontWeight: "500",
+						textTransform: "capitalize",
+					}}
+				>
+					{profile?.role || "viewer"}
+				</Text>
+			</View>
+		</ScrollView>
+	);
+}

package/templates/mobile/app/(app)/profile.tsx

@@ -0,0 +1,204 @@
+import { useEffect, useState } from "react";
+import {
+	ActivityIndicator,
+	Alert,
+	Pressable,
+	ScrollView,
+	Text,
+	TextInput,
+	View,
+} from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useAuth } from "../../hooks/use-auth";
+import { getProfile, updateProfile } from "../../lib/auth";
+import { useThemeTokens } from "../../lib/theme-tokens";
+
+interface UserProfile {
+	id: string;
+	email: string;
+	name: string | null;
+	role: string;
+}
+
+export default function ProfileScreen() {
+	const { isAuthenticated } = useAuth();
+	const {
+		bgColor,
+		textColor,
+		mutedColor,
+		cardBg,
+		borderColor,
+		inputBg,
+		isDark,
+	} = useThemeTokens();
+	const insets = useSafeAreaInsets();
+	const [profile, setProfile] = useState<UserProfile | null>(null);
+	const [name, setName] = useState("");
+	const [loading, setLoading] = useState(true);
+	const [saving, setSaving] = useState(false);
+
+	useEffect(() => {
+		if (isAuthenticated) {
+			(async () => {
+				try {
+					const data = await getProfile();
+					setProfile(data);
+					setName(data.name || "");
+				} catch {
+					// Non-critical
+				} finally {
+					setLoading(false);
+				}
+			})();
+		}
+	}, [isAuthenticated]);
+
+	async function handleSave() {
+		if (!name.trim()) {
+			Alert.alert("Error", "Name cannot be empty");
+			return;
+		}
+		setSaving(true);
+		try {
+			const updated = await updateProfile({ name: name.trim() });
+			setProfile(updated);
+			Alert.alert("Saved", "Profile updated successfully");
+		} catch {
+			Alert.alert("Error", "Failed to update profile. Please try again.");
+		} finally {
+			setSaving(false);
+		}
+	}
+
+	if (loading) {
+		return (
+			<View
+				style={{
+					flex: 1,
+					justifyContent: "center",
+					alignItems: "center",
+					backgroundColor: bgColor,
+				}}
+				accessibilityLabel="Loading profile"
+				accessibilityRole="progressbar"
+			>
+				<ActivityIndicator size="large" color={isDark ? "#fff" : "#000"} />
+			</View>
+		);
+	}
+
+	return (
+		<ScrollView
+			style={{ flex: 1, backgroundColor: bgColor }}
+			contentContainerStyle={{
+				padding: 20,
+				paddingTop: insets.top + 20,
+			}}
+			accessibilityLabel="Profile screen"
+		>
+			<Text
+				style={{
+					fontSize: 28,
+					fontWeight: "bold",
+					color: textColor,
+					marginBottom: 24,
+				}}
+				accessibilityRole="header"
+			>
+				Profile
+			</Text>
+
+			<Text style={{ fontSize: 14, color: mutedColor, marginBottom: 8 }}>
+				Name
+			</Text>
+			<TextInput
+				value={name}
+				onChangeText={setName}
+				placeholder="Your name"
+				placeholderTextColor={mutedColor}
+				autoComplete="name"
+				style={{
+					backgroundColor: inputBg,
+					borderWidth: 1,
+					borderColor,
+					borderRadius: 8,
+					padding: 12,
+					marginBottom: 16,
+					fontSize: 16,
+					color: textColor,
+				}}
+				accessibilityLabel="Name input"
+				accessibilityHint="Enter your display name"
+			/>
+
+			<Text style={{ fontSize: 14, color: mutedColor, marginBottom: 8 }}>
+				Email
+			</Text>
+			<View
+				style={{
+					backgroundColor: cardBg,
+					borderWidth: 1,
+					borderColor,
+					borderRadius: 8,
+					padding: 12,
+					marginBottom: 16,
+				}}
+				accessibilityLabel="Email display"
+			>
+				<Text style={{ fontSize: 16, color: mutedColor }}>
+					{profile?.email}
+				</Text>
+			</View>
+
+			<Text style={{ fontSize: 14, color: mutedColor, marginBottom: 8 }}>
+				Role
+			</Text>
+			<View
+				style={{
+					backgroundColor: cardBg,
+					borderWidth: 1,
+					borderColor,
+					borderRadius: 8,
+					padding: 12,
+					marginBottom: 24,
+				}}
+				accessibilityLabel="Role display"
+			>
+				<Text
+					style={{
+						fontSize: 16,
+						color: textColor,
+						textTransform: "capitalize",
+					}}
+				>
+					{profile?.role || "viewer"}
+				</Text>
+			</View>
+
+			<Pressable
+				onPress={handleSave}
+				disabled={saving}
+				style={{
+					backgroundColor: isDark ? "#fff" : "#000",
+					padding: 14,
+					borderRadius: 8,
+					alignItems: "center",
+					opacity: saving ? 0.6 : 1,
+				}}
+				accessibilityLabel="Save profile changes"
+				accessibilityRole="button"
+				accessibilityState={{ disabled: saving }}
+			>
+				<Text
+					style={{
+						color: isDark ? "#000" : "#fff",
+						fontSize: 16,
+						fontWeight: "600",
+					}}
+				>
+					{saving ? "Saving..." : "Save Changes"}
+				</Text>
+			</Pressable>
+		</ScrollView>
+	);
+}

package/templates/mobile/app/(app)/settings.tsx

@@ -0,0 +1,80 @@
+import { useRouter } from "expo-router";
+import { Pressable, Text, View } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useAuth } from "../../hooks/use-auth";
+import { useThemeTokens } from "../../lib/theme-tokens";
+
+export default function SettingsScreen() {
+	const router = useRouter();
+	const { signOut } = useAuth();
+	const { bgColor, textColor, mutedColor, cardBg, borderColor } =
+		useThemeTokens();
+	const insets = useSafeAreaInsets();
+
+	async function handleSignOut() {
+		await signOut();
+		router.replace("/(auth)/sign-in");
+	}
+
+	return (
+		<View
+			style={{
+				flex: 1,
+				backgroundColor: bgColor,
+				padding: 20,
+				paddingTop: insets.top + 20,
+			}}
+			accessibilityLabel="Settings screen"
+		>
+			<Text
+				style={{
+					fontSize: 28,
+					fontWeight: "bold",
+					color: textColor,
+					marginBottom: 24,
+				}}
+				accessibilityRole="header"
+			>
+				Settings
+			</Text>
+
+			<View
+				style={{
+					backgroundColor: cardBg,
+					borderRadius: 12,
+					padding: 16,
+					marginBottom: 16,
+					borderWidth: 1,
+					borderColor,
+				}}
+				accessibilityLabel="App info section"
+			>
+				<Text style={{ fontSize: 14, color: mutedColor, marginBottom: 4 }}>
+					App
+				</Text>
+				<Text style={{ fontSize: 16, color: textColor }}>Quark Mobile</Text>
+				<Text style={{ fontSize: 14, color: mutedColor, marginTop: 4 }}>
+					Version 0.1.0
+				</Text>
+			</View>
+
+			<Pressable
+				onPress={handleSignOut}
+				style={{
+					backgroundColor: "#ff3b30",
+					paddingHorizontal: 24,
+					paddingVertical: 14,
+					borderRadius: 8,
+					alignItems: "center",
+				}}
+				accessibilityLabel="Sign out of your account"
+				accessibilityRole="button"
+				accessibilityHint="Signs you out and returns to the sign in screen"
+			>
+				<Text style={{ color: "#fff", fontSize: 16, fontWeight: "600" }}>
+					Sign Out
+				</Text>
+			</Pressable>
+		</View>
+	);
+}

package/templates/mobile/app/(auth)/_layout.tsx

@@ -0,0 +1,10 @@
+import { Stack } from "expo-router";
+
+export default function AuthLayout() {
+	return (
+		<Stack screenOptions={{ headerShown: false }}>
+			<Stack.Screen name="sign-in" />
+			<Stack.Screen name="sign-up" />
+		</Stack>
+	);
+}