Overview
ArcShell wraps Surface in a native iOS and Android shell using Capacitor (MIT license). The key architectural choice is live URL mode: the shell loads Surface from its running server URL rather than bundling a static web app. This is the only viable approach for Next.js App Router with server components and Supabase auth cookies.
iOS and Android projects are scaffolded and committed at surface/ios/ and surface/android/. Config at surface/capacitor.config.ts. See the ArcShell Feature Matrix.
Why live URL mode
Standard Capacitor bundles a static web build. That breaks for Surface because:
- Next.js App Router server components require a running Node server
- Supabase auth cookies require the real domain for SSR
- Static export loses all server-side data fetching and API routes
Live URL mode is the solution: the WebView/WKWebView loads from a URL. In development: http://10.20.10.29:3002. In production: https://surface.arc-grid.com.
Setup
# capacitor.config.ts (simplified)
const config: CapacitorConfig = {
appId: 'com.arcgrid.surface',
appName: 'ArcGrid Surface',
server: {
url: process.env.CAPACITOR_SERVER_URL ?? 'https://surface.arc-grid.com',
cleartext: process.env.NODE_ENV === 'development'
}
}
# Build and run (iOS)
npx cap sync ios
npx cap open ios # opens Xcode
# Build and run (Android)
npx cap sync android
npx cap open android # opens Android StudioNative plugins
- Camera / Gallery (ARCSHELL.3) - Capacitor Camera plugin for Castin video capture and portal uploads
- Push Notifications (ARCSHELL.2) - APNS (iOS) and FCM (Android) bridged to Supabase realtime
- Status Bar - hide/show based on Surface page state
- Safe Area - insets injected as CSS vars for Surface layout
White-label product (ARCSHELL.P0)
ArcShell.P0 is also a commercial product: a white-label Capacitor wrapper for client web apps. A client provides their web app URL; ArcShell delivers native iOS/Android builds with their branding. This is separate from the Grid's internal Surface use.