Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
import { useEffect, useState } from 'react'
import { Linking, View } from 'react-native'
import { useNavigation, useNavigationContainerRef, useRouter } from 'expo-router'
import { useSafeAreaInsets } from 'react-native-safe-area-context'
import {
OrcaMobileWebShellView,
parseMobileWebShellLoadState
} from '../../modules/orca-mobile-web-shell/src'
import { HostRouteNoticeBanner } from '../components/HostRouteNoticeBanner'
import { colors } from '../theme/mobile-theme'
import { themedStyleSheet } from '../theme/themed-styles'
import { useMobileUiLocale } from '../i18n/use-mobile-translation'
import { useMobileColorScheme } from '../theme/use-mobile-color-scheme'
import type { BridgeInitRoute } from './bridge/bridge-envelope'
import type { BridgeClearableRouteParam } from './bridge/bridge-route-update'
import type { MobileWebShellUpdateNotice } from './mobile-web-shell-session-contract'
import { useMobileWebShellDroppedFrames } from './mobile-web-shell-dev-facts'
import { ShellDevFacts } from './ShellDevFacts'
import { cancelledShellNavigationTarget } from './cancelled-navigation-target'
import { playPageHaptic } from './page-haptics'
import { useMobileWebShellBridge } from './use-mobile-web-shell-bridge'
import type { MobileWebShellRuntime } from './mobile-web-shell-runtime'
import { useKeyboardOcclusion } from '../platform/keyboard-occlusion'
import { useNativeDeviceVerbs } from '../platform/use-native-device-verbs'
import { useNativePdfViewer } from '../platform/native-pdf-view'
import { useShellPageBack } from './use-shell-page-back'
import { useShellStackPop } from './use-shell-stack-pop'
import { useMobileWebShellSession } from './use-mobile-web-shell-session'
import { usePageHostSnapshot } from './use-page-host-snapshot'
import { useReportedHostAreaServing } from './host-area-serving'
import { isHostRouteOf } from './page-route-policy'
import { nativeStackReturn } from './native-stack-return'
import { usePageLocationOnFold } from './page-location-on-fold'
import { useResponsiveLayout } from '../layout/responsive-layout'
import { storageReadParamsSchema, type BridgeNativeVerb } from './bridge/bridge-native-verbs'
import { SHELL_OPENING_LABEL, ShellPageCover } from './ShellWaitingFrame'
import { useReportedShellOverlayLoad, type ShellOverlayLoad } from './shell-overlay-load'
import { pageSafeAreaInsets, usePublishedSafeAreaInsets } from './page-safe-area-insets'
import { ShellStateScreen } from './ShellStateScreen'
import { hostProfileUnreadableLine, pageFaultLine } from './shell-lifecycle-log'
import { recordShellLifecycleLine } from './shell-lifecycle-line-recorder'
// Do not promise a retry: the shell schedules no second update attempt.
function updateNoticeMessage(notice: MobileWebShellUpdateNotice): string {
switch (notice) {
case 'update-failed':
return "Couldn't download the latest app from this host. Showing the last version that worked."
}
}
export type MobileWebShellScreenProps = {
hostId: string
// Overlay callers draw waiting/exits; stay transparent until the page paints its drawer.
onOverlayLoad?: (load: ShellOverlayLoad) => void
// The served document lives at / and cannot derive the native screen’s route.
route: BridgeInitRoute
appNamesRoute?: boolean
// The caller compares the consumed one-shot value before clearing it; a newer tap may already have replaced it (ruling 34).
onRouteParamClear?: (param: BridgeClearableRouteParam, value: string) => void
runtime?: MobileWebShellRuntime
}
// Key the native view by session id so reducer-requested remounts rebuild the WebView and reinstall every fence; the view has no independent reload.
export function MobileWebShellScreen({
hostId,
route,
appNamesRoute,
onRouteParamClear,
onOverlayLoad,
runtime
}: MobileWebShellScreenProps) {
const colorScheme = useMobileColorScheme()
const uiLocale = useMobileUiLocale()
const insets = useSafeAreaInsets()
const overlay = onOverlayLoad !== undefined
const router = useRouter()
const navigation = useNavigation()
const navigationContainer = useNavigationContainerRef()
const popShellStack = useShellStackPop()
const { isWideLayout } = useResponsiveLayout()
const { droppedBinaryFrames, reportDroppedBinaryFrames } = useMobileWebShellDroppedFrames()
const {
state,
downloadProgress,
pageRoutes,
pageRouteGrants,
routeGrants,
updateNotice,
retry,
reportShellFailure,
reportDocumentStarted,
reportDocumentLoaded,
reportPageReady,
reportPagePainted,
reportPageBackClaim,
pageReady,
pageFrame,
backClaimed,
ownsHostArea
} = useMobileWebShellSession({
hostId,
routePathname: route.pathname,
wide: isWideLayout,
appNamesRoute,
runtime
})
// Full screen from the download on, as on a phone; while checking, nobody knows the page owns it.
useReportedHostAreaServing(ownsHostArea && state.kind !== 'checking')
// Key dismissal by session id so a new generation’s refusal still appears.
const [noticeDismissedFor, setNoticeDismissedFor] = useState<string | null>(null)
const noticeShown =
updateNotice !== null && state.kind === 'ready' && noticeDismissedFor !== state.sessionId
// Edge-to-edge disables adjustResize and zeroes WebView IME insets, so visualViewport never shrinks; publish native keyboard height to the page.
const keyboardInset = Math.max(0, useKeyboardOcclusion())
const pageInsets = pageSafeAreaInsets({ insets, topCovered: noticeShown })
const {
snapshot,
unreadable,
retry: retryHostSnapshot,
readStorage,
refreshStorage,
writeStorage,
readWorkspaceKey
} = usePageHostSnapshot(hostId, route.pathname, ownsHostArea)
// Create the media registry before the bridge; its staged files must belong to this page session.
const serveDeviceVerb = useNativeDeviceVerbs(state.kind === 'ready' ? state.sessionId : null)
const servePdfView = useNativePdfViewer(hostId, state.kind === 'ready' ? state.sessionId : null)
const serveNativeVerb = (verb: BridgeNativeVerb, params: unknown): Promise<unknown> =>
verb === 'native.storage.read'
? readWorkspaceKey(storageReadParamsSchema.parse(params).key).then((value) => ({ value }))
: verb === 'native.pdf.view'
? servePdfView(params)
: serveDeviceVerb(verb, params)
// Both externalLink and cancelled navigation use this filtered opener. Report device-handler failure without throwing from a native frame callback; neither path has a reply.
const openUrlForPage = (url: string) => {
void Linking.openURL(url).catch((error: unknown) => {
console.warn('[web-shell] could not open a URL for the page', { url, error })
})
}
// Push so Back reveals the mounted page without downloading or handshaking again, unless the page replaced itself.
const openPageRoute = (href: string, replace = false) => {
if (overlay) {
return void router.replace(href)
}
// Return to an existing screen rather than pushing a duplicate over the live one.
const rootState = navigationContainer.getRootState()
const onStack = rootState ? nativeStackReturn(rootState, href) : null
if (onStack === 'current') {
return
}
if (onStack) {
navigation.dispatch({
type: 'POP',
payload: { count: onStack.count },
target: onStack.target,
source: onStack.source
})
return
}
// The wide host route owns the session area; dismissTo pops to it or replaces after a cold deep link, avoiding a second copy.
if (isWideLayout && isHostRouteOf(href, hostId)) {
router.dismissTo(href)
return
}
return void (replace ? router.replace(href) : router.push(href))
}
const holdPageLocation = usePageLocationOnFold(
isWideLayout,
() => navigation.isFocused(),
openPageRoute
)
const bridge = useMobileWebShellBridge({
hostId,
route,
safeAreaInsets: pageInsets,
keyboardInset,
colorScheme,
uiLocale,
pageRoutes,
pageRouteGrants,
routeGrants,
ownsHostArea,
session: state,
sessionEstablished: pageReady,
snapshot,
readStorage,
onStorageWrite: writeStorage,
// Treat a page that never renders as document-load-failed: refetch once for replaced bytes, then fail visibly if its code still breaks.
// Never throw from the page error boundary/native frame callback.
onPageFault: (error) => {
console.warn('[web-shell] the page faulted', error)
recordShellLifecycleLine(hostId, pageFaultLine(error))
reportShellFailure('document-load-failed')
},
// init already sees app writes in the map; refresh from persisted storage afterward on every ready, including document reloads.
onPageReady: () => {
reportPageReady()
void refreshStorage()
},
// Keep the cover until the page reports its own first frame.
onPagePainted: reportPagePainted,
onPageBackClaim: reportPageBackClaim,
onPageLocation: (href) => holdPageLocation(href, ownsHostArea),
onRouteParamClear: (param, value) => {
onRouteParamClear?.(param, value)
},
// Route refusal builds no tree; use document-load-failed for bounded recovery, then a terminal failure. The host logs the specific issue.
onRouteRefused: (issue) => {
console.warn('[web-shell] refused to open this screen', issue)
reportShellFailure('document-load-failed')
},
onNavigate: openPageRoute,
serveNativeVerb,
onExternalLink: openUrlForPage,
// Reuse the app’s platform haptics mapping; device failures are already swallowed there.
onHaptic: playPageHaptic,
// The page has one history entry; only the native stack can handle Back.
onNavigateBack: popShellStack,
// The stream survives dropped frames; keep a count because diagnostics print only once per host.
onBinaryFramesDropped: reportDroppedBinaryFrames
})
// paneKey changes keep the session mounted; publish the new route without reloading. The longer-lived host deduplicates routes and preserves any in-flight frame.
const publishRoute = bridge.publishRoute
useEffect(() => {
publishRoute(route)
}, [publishRoute, route])
usePublishedSafeAreaInsets(bridge.publishSafeAreaInsets, pageInsets)
const publishKeyboardInset = bridge.publishKeyboardInset
useEffect(() => {
publishKeyboardInset(keyboardInset)
}, [publishKeyboardInset, keyboardInset])
// Use navigation screen options to disable this stack entry’s gesture; the router has no such option.
useShellPageBack({
claimed: backClaimed,
isFocused: () => navigation.isFocused(),
sendBack: bridge.sendBack,
setOptions: navigation.setOptions
})
useReportedShellOverlayLoad(onOverlayLoad, state, pageFrame, downloadProgress)
// Profile failures preserve verified bundle bytes and retry the device store.
useEffect(() => {
if (unreadable) {
console.warn('[web-shell] this host could not be read from the app store')
reportShellFailure('host-profile-unreadable')
}
}, [reportShellFailure, unreadable])
useEffect(() => {
if (unreadable) {
recordShellLifecycleLine(hostId, hostProfileUnreadableLine())
}
}, [hostId, unreadable])
if (overlay && state.kind !== 'ready') {
return null
}
if (state.kind !== 'ready') {
return (
<ShellStateScreen
hostId={hostId}
state={state}
onRetry={() => {
if (unreadable) {
retryHostSnapshot()
}
retry()
}}
downloadProgress={downloadProgress}
host={snapshot?.host ?? null}
/>
)
}
return (
<View
style={[
styles.shellRoot,
// The page pads system bars from init insets; a visible banner owns the status-bar strip.
{ paddingTop: noticeShown ? insets.top : 0 },
overlay && { backgroundColor: 'transparent' }
]}
testID="mobile-web-shell-ready"
>
{/* Keep update-failure notice above the working fallback page so dismissal leaves its document intact. */}
{updateNotice !== null && noticeShown && (
<HostRouteNoticeBanner
message={updateNoticeMessage(updateNotice)}
tone="failure"
onDismiss={() => setNoticeDismissedFor(state.sessionId)}
/>
)}
<OrcaMobileWebShellView
key={state.sessionId}
ref={bridge.viewRef}
// Overlays cannot cover the screen beneath; hide their opaque WebView until first paint.
style={[styles.shellView, overlay && pageFrame !== 'painted' && styles.unpaintedOverlay]}
generationDirectory={state.generationDirectory}
sessionId={state.sessionId}
bridgeEnabled={bridge.bridgeEnabled}
onBridgeMessage={bridge.onBridgeMessage}
onExternalNavigation={(event) => {
const target = cancelledShellNavigationTarget(event.nativeEvent.url)
if (target === null) {
// Drop schemes outside the three allowed ones; shell-document URLs are already refused before this callback.
return
}
openUrlForPage(target)
}}
onLoadState={(event) => {
const parsed = parseMobileWebShellLoadState(event.nativeEvent)
if (parsed?.state === 'failed') {
reportShellFailure(parsed.reason)
return
}
// Load completion proves only response commit; start waiting for the page’s own first paint here.
if (parsed?.state === 'ready') {
reportDocumentLoaded()
return
}
// Cover on load start: the old document remains visible until the new one paints, before ready arrives.
if (parsed?.state === 'loading') {
reportDocumentStarted()
}
}}
/>
{overlay ? null : (
<ShellPageCover label={SHELL_OPENING_LABEL} visible={pageFrame === 'unpainted'} />
)}
<ShellDevFacts state={state} droppedBinaryFrames={droppedBinaryFrames} />
</View>
)
}
const styles = themedStyleSheet(() => ({
shellRoot: {
flex: 1,
backgroundColor: colors.bgBase
},
shellView: {
flex: 1
},
unpaintedOverlay: {
opacity: 0
}
}))