Migrate from .NET MAUI to Expo + Convex

Complete rewrite of Scry using TypeScript stack:

- Expo/React Native with Expo Router (file-based routing)
- Convex backend (serverless functions + real-time database)
- Adaptive camera system (expo-camera in Expo Go, Vision Camera in production)
- React Native Skia + fast-opencv for image processing
- GDPR-compliant auth setup with Zitadel OIDC (pending configuration)

Key features:
- Card recognition pipeline ported to TypeScript
- Perceptual hashing (192-bit color pHash)
- CLAHE preprocessing for lighting normalization
- Local SQLite cache with Convex sync
- Collection management with offline support

Removes all .NET/MAUI code (src/, test/, tools/).

💘 Generated with Crush

Assisted-by: Claude Opus 4.5 via Crush <crush@charm.land>

lib/hooks/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Hooks module exports.
+ */
+
+export { useCameraPermission } from "./useCamera";
+export { useCardHashes, useCardCount, useSearchCards, useCollection, useCurrentUser } from "./useConvex";
+export { useSync, SyncInitializer } from "./useSync";
+export { useAuth } from "./useAuth";
+export { useUserProfile, storeAccessToken, clearAccessToken } from "./useUserProfile";

lib/hooks/useAuth.ts

@@ -0,0 +1,112 @@
+/**
+ * Authentication hook and utilities.
+ * 
+ * NOTE: Auth is currently disabled (using ConvexProvider instead of ConvexAuthProvider).
+ * This hook provides a stub implementation until Zitadel is configured.
+ */
+
+import { useState, useCallback } from "react";
+
+/**
+ * Hook for authentication state and actions.
+ * Currently returns unauthenticated state - enable ConvexAuthProvider when Zitadel is ready.
+ */
+export function useAuth() {
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSignIn = useCallback(async () => {
+    setError("Authentication not configured. Set up Zitadel environment variables.");
+  }, []);
+
+  const handleSignOut = useCallback(async () => {
+    // No-op when not authenticated
+  }, []);
+
+  return {
+    isAuthenticated: false,
+    isLoading: false,
+    error,
+    signIn: handleSignIn,
+    signOut: handleSignOut,
+    clearError: () => setError(null),
+  };
+}
+
+// Full implementation for when ConvexAuthProvider is enabled:
+/*
+import { useConvexAuth } from "convex/react";
+import { useAuthActions } from "@convex-dev/auth/react";
+import { makeRedirectUri } from "expo-auth-session";
+import { openAuthSessionAsync } from "expo-web-browser";
+import { Platform } from "react-native";
+
+const redirectUri = makeRedirectUri({
+  scheme: "scry",
+  path: "auth",
+});
+
+export function useAuth() {
+  const { isAuthenticated, isLoading } = useConvexAuth();
+  const { signIn, signOut } = useAuthActions();
+  const [isSigningIn, setIsSigningIn] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSignIn = useCallback(async () => {
+    setIsSigningIn(true);
+    setError(null);
+
+    try {
+      const result = await signIn("zitadel", { redirectTo: redirectUri });
+
+      if (Platform.OS === "web") {
+        return;
+      }
+
+      if (result?.redirect) {
+        const authResult = await openAuthSessionAsync(
+          result.redirect.toString(),
+          redirectUri,
+          {
+            showInRecents: true,
+            preferEphemeralSession: false,
+          }
+        );
+
+        if (authResult.type === "success") {
+          const url = new URL(authResult.url);
+          const code = url.searchParams.get("code");
+
+          if (code) {
+            await signIn("zitadel", { code });
+          }
+        } else if (authResult.type === "cancel") {
+          setError("Sign-in was cancelled");
+        }
+      }
+    } catch (err) {
+      console.error("Sign-in error:", err);
+      setError(err instanceof Error ? err.message : "Sign-in failed");
+    } finally {
+      setIsSigningIn(false);
+    }
+  }, [signIn]);
+
+  const handleSignOut = useCallback(async () => {
+    try {
+      await signOut();
+    } catch (err) {
+      console.error("Sign-out error:", err);
+      setError(err instanceof Error ? err.message : "Sign-out failed");
+    }
+  }, [signOut]);
+
+  return {
+    isAuthenticated,
+    isLoading: isLoading || isSigningIn,
+    error,
+    signIn: handleSignIn,
+    signOut: handleSignOut,
+    clearError: () => setError(null),
+  };
+}
+*/

lib/hooks/useCamera.ts

@@ -0,0 +1,116 @@
+/**
+ * Hook for camera permissions.
+ * Supports both expo-camera (Expo Go) and react-native-vision-camera (production).
+ */
+
+import { useState, useEffect, useRef } from "react";
+import { Platform, Linking, Alert } from "react-native";
+import Constants from "expo-constants";
+
+// Detect if running in Expo Go
+const isExpoGo = Constants.appOwnership === "expo";
+
+export interface CameraPermissionState {
+  hasPermission: boolean;
+  isLoading: boolean;
+  error: string | null;
+}
+
+/**
+ * Hook for camera permissions that works in both Expo Go and production builds.
+ */
+export function useCameraPermission(): CameraPermissionState & { requestPermission: () => Promise<void> } {
+  const [hasPermission, setHasPermission] = useState(false);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    checkPermission();
+  }, []);
+
+  const checkPermission = async () => {
+    try {
+      if (isExpoGo) {
+        // Use expo-camera
+        const { Camera } = await import("expo-camera");
+        const { status } = await Camera.getCameraPermissionsAsync();
+        setHasPermission(status === "granted");
+      } else {
+        // Use react-native-vision-camera
+        const { Camera } = await import("react-native-vision-camera");
+        const status = await Camera.getCameraPermissionStatus();
+        setHasPermission(status === "granted");
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to check camera permission");
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  const requestPermission = async () => {
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      if (isExpoGo) {
+        // Use expo-camera
+        const { Camera } = await import("expo-camera");
+        const { status, canAskAgain } = await Camera.requestCameraPermissionsAsync();
+        
+        if (status === "granted") {
+          setHasPermission(true);
+        } else {
+          if (!canAskAgain) {
+            showSettingsAlert();
+          }
+          setError("Camera permission denied");
+        }
+      } else {
+        // Use react-native-vision-camera
+        const { Camera } = await import("react-native-vision-camera");
+        const status = await Camera.requestCameraPermission();
+        
+        if (status === "granted") {
+          setHasPermission(true);
+        } else if (status === "denied") {
+          showSettingsAlert();
+          setError("Camera permission denied");
+        }
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to request camera permission");
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return { hasPermission, isLoading, error, requestPermission };
+}
+
+function showSettingsAlert() {
+  Alert.alert(
+    "Camera Permission Required",
+    "Scry needs camera access to scan cards. Please enable it in Settings.",
+    [
+      { text: "Cancel", style: "cancel" },
+      {
+        text: "Open Settings",
+        onPress: () => {
+          if (Platform.OS === "ios") {
+            Linking.openURL("app-settings:");
+          } else {
+            Linking.openSettings();
+          }
+        },
+      },
+    ]
+  );
+}
+
+/**
+ * Returns true if using expo-camera (Expo Go), false for Vision Camera (production).
+ */
+export function useIsExpoGo(): boolean {
+  return isExpoGo;
+}

lib/hooks/useConvex.ts

@@ -0,0 +1,101 @@
+/**
+ * Hooks for Convex data access.
+ */
+
+import { useQuery, useMutation } from "convex/react";
+import { api } from "../../convex/_generated/api";
+import { useHashCache } from "../context";
+import { useEffect } from "react";
+import type { CardHashEntry } from "../recognition";
+import type { Id } from "../../convex/_generated/dataModel";
+
+type User = { _id: Id<"users"> } | null | undefined;
+
+/**
+ * Hook to get the current authenticated user.
+ * Returns unauthenticated state when auth is not configured.
+ */
+export function useCurrentUser(): { user: User; isLoading: boolean; isAuthenticated: boolean } {
+  // When using ConvexProvider (no auth), just return unauthenticated state
+  // Switch to ConvexAuthProvider + useConvexAuth when Zitadel is configured
+  return {
+    user: null,
+    isLoading: false,
+    isAuthenticated: false,
+  };
+}
+
+/**
+ * Hook to fetch and cache card hashes from Convex.
+ */
+export function useCardHashes() {
+  const { setCardHashes, hashesLoaded, lastHashSync, cardHashes } = useHashCache();
+  
+  // Fetch all cards from Convex
+  const cards = useQuery(api.cards.list);
+  
+  useEffect(() => {
+    if (cards) {
+      // Convert Convex cards to CardHashEntry format
+      const entries: CardHashEntry[] = cards.map((card) => ({
+        id: card.scryfallId,
+        name: card.name,
+        setCode: card.setCode,
+        collectorNumber: card.collectorNumber,
+        imageUri: card.imageUri,
+        hash: new Uint8Array(card.hash),
+      }));
+      
+      setCardHashes(entries);
+    }
+  }, [cards, setCardHashes]);
+  
+  return {
+    loading: cards === undefined && !hashesLoaded,
+    loaded: hashesLoaded,
+    count: cardHashes.length,
+    lastSync: lastHashSync,
+    hashes: cardHashes,
+  };
+}
+
+/**
+ * Hook to get card count.
+ */
+export function useCardCount() {
+  const count = useQuery(api.cards.count);
+  return count ?? 0;
+}
+
+/**
+ * Hook to search cards by name.
+ */
+export function useSearchCards(query: string) {
+  const results = useQuery(
+    api.cards.searchByName,
+    query.length >= 2 ? { name: query } : "skip"
+  );
+  return results ?? [];
+}
+
+/**
+ * Hook to manage collection.
+ */
+export function useCollection(userId?: string) {
+  const collection = useQuery(
+    api.collections.getByUser,
+    userId ? { userId: userId as any } : "skip"
+  );
+  
+  const addCard = useMutation(api.collections.add);
+  const removeCard = useMutation(api.collections.remove);
+  const updateQuantity = useMutation(api.collections.updateQuantity);
+  
+  return {
+    collection: collection ?? [],
+    addCard,
+    removeCard,
+    updateQuantity,
+    loading: collection === undefined,
+  };
+}

lib/hooks/useSync.ts

@@ -0,0 +1,102 @@
+/**
+ * Hook for managing offline sync with local SQLite cache.
+ */
+
+import { useEffect, useState, useCallback, useRef } from "react";
+import { useConvex } from "convex/react";
+import { createSyncService, type SyncService, type SyncStatus } from "../db/syncService";
+import { useHashCache } from "../context";
+
+/**
+ * Hook to manage sync service lifecycle and status.
+ * Initializes local database, syncs with Convex, and provides hashes for recognition.
+ */
+export function useSync() {
+  const convex = useConvex();
+  const syncServiceRef = useRef<SyncService | null>(null);
+  const [status, setStatus] = useState<SyncStatus>({
+    isInitialized: false,
+    isSyncing: false,
+    lastSync: 0,
+    localCardCount: 0,
+  });
+  
+  const { setCardHashes } = useHashCache();
+
+  // Initialize sync service
+  useEffect(() => {
+    if (!convex || syncServiceRef.current) return;
+
+    const service = createSyncService(convex);
+    syncServiceRef.current = service;
+
+    // Subscribe to status changes
+    const unsubscribe = service.onStatusChange(setStatus);
+
+    // Initialize and load cached hashes
+    const init = async () => {
+      await service.initialize();
+      
+      // Load cached hashes into app store
+      const hashes = await service.getHashes();
+      if (hashes.length > 0) {
+        setCardHashes(hashes);
+        console.log(`[useSync] Loaded ${hashes.length} cached hashes`);
+      }
+      
+      // Start background sync
+      service.sync().then(async () => {
+        // Reload hashes after sync
+        const updatedHashes = await service.getHashes();
+        setCardHashes(updatedHashes);
+      });
+    };
+
+    init();
+
+    return () => {
+      unsubscribe();
+    };
+  }, [convex, setCardHashes]);
+
+  // Manual sync trigger
+  const sync = useCallback(async () => {
+    if (!syncServiceRef.current) return;
+    
+    await syncServiceRef.current.sync();
+    
+    // Reload hashes after sync
+    const hashes = await syncServiceRef.current.getHashes();
+    setCardHashes(hashes);
+  }, [setCardHashes]);
+
+  // Clear local cache
+  const clearCache = useCallback(async () => {
+    if (!syncServiceRef.current) return;
+    
+    await syncServiceRef.current.clearLocalCache();
+    setCardHashes([]);
+  }, [setCardHashes]);
+
+  // Get current hashes from cache
+  const getHashes = useCallback(async () => {
+    if (!syncServiceRef.current) return [];
+    return syncServiceRef.current.getHashes();
+  }, []);
+
+  return {
+    ...status,
+    sync,
+    clearCache,
+    getHashes,
+  };
+}
+
+/**
+ * Context-free sync initialization for use in _layout.tsx
+ * Returns a component that initializes sync when mounted.
+ */
+export function SyncInitializer() {
+  useSync();
+  return null;
+}

lib/hooks/useUserProfile.ts

@@ -0,0 +1,115 @@
+/**
+ * Hook for fetching user profile from Zitadel OIDC userinfo endpoint.
+ * 
+ * GDPR Compliance: User profile data is never stored in our database.
+ * This hook fetches it directly from Zitadel when needed for display.
+ */
+
+import { useState, useEffect, useCallback } from "react";
+import * as SecureStore from "expo-secure-store";
+
+interface UserProfile {
+  sub: string;
+  name?: string;
+  preferredUsername?: string;
+  email?: string;
+  emailVerified?: boolean;
+  picture?: string;
+}
+
+const ACCESS_TOKEN_KEY = "zitadel_access_token";
+
+/**
+ * Hook to fetch and cache user profile from Zitadel userinfo endpoint.
+ * Profile is held in memory only - never persisted to our database.
+ */
+export function useUserProfile() {
+  const [profile, setProfile] = useState<UserProfile | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchProfile = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      // Get stored access token
+      const accessToken = await SecureStore.getItemAsync(ACCESS_TOKEN_KEY);
+      
+      if (!accessToken) {
+        setProfile(null);
+        return null;
+      }
+
+      const issuer = process.env.EXPO_PUBLIC_ZITADEL_ISSUER;
+      if (!issuer) {
+        throw new Error("ZITADEL_ISSUER not configured");
+      }
+
+      // Fetch from OIDC userinfo endpoint
+      const response = await fetch(`${issuer}/oidc/v1/userinfo`, {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+        },
+      });
+
+      if (!response.ok) {
+        if (response.status === 401) {
+          // Token expired - clear it
+          await SecureStore.deleteItemAsync(ACCESS_TOKEN_KEY);
+          setProfile(null);
+          return null;
+        }
+        throw new Error(`Failed to fetch user profile: ${response.status}`);
+      }
+
+      const data = await response.json();
+      
+      const userProfile: UserProfile = {
+        sub: data.sub,
+        name: data.name,
+        preferredUsername: data.preferred_username,
+        email: data.email,
+        emailVerified: data.email_verified,
+        picture: data.picture,
+      };
+
+      setProfile(userProfile);
+      return userProfile;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Failed to fetch profile";
+      setError(message);
+      console.error("[useUserProfile]", message);
+      return null;
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  const clearProfile = useCallback(() => {
+    setProfile(null);
+    setError(null);
+  }, []);
+
+  return {
+    profile,
+    isLoading,
+    error,
+    fetchProfile,
+    clearProfile,
+  };
+}
+
+/**
+ * Store access token after successful auth (called from useAuth).
+ */
+export async function storeAccessToken(token: string): Promise<void> {
+  await SecureStore.setItemAsync(ACCESS_TOKEN_KEY, token);
+}
+
+/**
+ * Clear access token on sign out.
+ */
+export async function clearAccessToken(): Promise<void> {
+  await SecureStore.deleteItemAsync(ACCESS_TOKEN_KEY);
+}