@tastic/shell 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,165 @@
 {
   "name": "@tastic/shell",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The app around a pack of React Native games, two-seat or for one player: Home, the loadout, the stats screen, Profiles and Settings, the pack's Redux store and its root providers, driven by one PackDefinition",
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-router",
+    "local-multiplayer",
+    "couch-multiplayer",
+    "game-pack",
+    "redux"
+  ],
+  "homepage": "https://github.com/jayrdeaton/react-native-game-shell#readme",
+  "bugs": {
+    "url": "https://github.com/jayrdeaton/react-native-game-shell/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jayrdeaton/react-native-game-shell.git"
+  },
+  "license": "MIT",
+  "author": "Jay Deaton",
+  "sideEffects": [
+    "./src/navigation.ts",
+    "./src/components/Theme.tsx",
+    "./dist/*"
+  ],
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "react-native": "./src/index.ts",
+      "browser": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "react-native": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "files": [
+    "assets",
+    "dist",
+    "src",
+    "!src/__tests__",
+    "!src/__mocks__",
+    "!src/testUtils"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "fix": "eslint --fix",
+    "lint": "eslint",
+    "prepublishOnly": "npm run build",
+    "release": "git push --follow-tags",
+    "release:major": "npm version major && npm run release",
+    "release:minor": "npm version minor && npm run release",
+    "release:patch": "npm version patch && npm run release",
+    "test": "jest",
+    "test:watch": "jest --watchAll",
+    "typecheck": "tsc --noEmit",
+    "verify": "npm run lint && npm test && npm run typecheck && npm run build",
+    "preversion": "npm run verify"
+  },
+  "prettier": "@infinitetoken/eslint-config/prettier",
+  "devDependencies": {
+    "@babel/core": "^7.29.7",
+    "@expo/vector-icons": "^15.1.1",
+    "@infinitetoken/eslint-config": "^0.2.1",
+    "@infinitetoken/jest-config": "^0.5.2",
+    "@infinitetoken/tsconfig": "^0.6.0",
+    "@react-native-async-storage/async-storage": "2.2.0",
+    "@react-native-masked-view/masked-view": "0.3.2",
+    "@react-native/jest-preset": "^0.88.0",
+    "@reduxjs/toolkit": "^2.13.0",
+    "@rific/auto-paper": "^0.13.4",
+    "@rific/core": "^0.5.0",
+    "@rific/feedback-press": "^0.13.1",
+    "@rific/focus-chain": "^0.4.8",
+    "@rific/gestures": "^0.1.3",
+    "@rific/splash-gate": "^0.2.3",
+    "@rific/toaster": "^0.12.0",
+    "@rific/updater": "^0.8.0",
+    "@tastic/achievements": "^0.6.0",
+    "@tastic/core": "^0.14.0",
+    "@tastic/edge-guard": "^0.1.5",
+    "@tastic/hud": "^0.25.1",
+    "@tastic/profile": "^0.17.0",
+    "@tastic/split-screen": "^0.5.5",
+    "@testing-library/react-native": "^14.1.0",
+    "@types/jest": "30.0.0",
+    "@types/react": "~19.3.0",
+    "eslint": "^9.39.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-native": "^5.0.0",
+    "expo": "~58.0.19",
+    "expo-audio": "~58.0.10",
+    "expo-blur": "~58.0.5",
+    "expo-constants": "~58.0.13",
+    "expo-font": "~58.0.10",
+    "expo-haptics": "~58.0.7",
+    "expo-keep-awake": "~58.0.3",
+    "expo-router": "~58.0.26",
+    "expo-sensors": "~58.0.4",
+    "expo-splash-screen": "~58.0.11",
+    "expo-system-ui": "~58.0.6",
+    "expo-updates": "~58.0.18",
+    "jest": "~30.5.2",
+    "jest-expo": "~58.0.12",
+    "prettier": "^3.8.3",
+    "react": "19.3.0",
+    "react-native": "0.88.0",
+    "react-native-gesture-handler": "~3.3.0",
+    "react-native-paper": "^5.15.3",
+    "react-native-reanimated": "4.7.1",
+    "react-native-safe-area-context": "~5.10.1",
+    "react-native-screens": "~4.30.0",
+    "react-native-worklets": "0.13.0",
+    "react-redux": "^9.3.0",
+    "redux": "^5.0.1",
+    "redux-persist": "^6.0.0",
+    "test-renderer": "^1.3.1",
+    "tsup": "^8.0.0",
+    "typescript": "~6.0.3"
+  },
+  "peerDependencies": {
+    "@expo/vector-icons": ">=15.1.1",
+    "@react-native-async-storage/async-storage": ">=2.2.0",
+    "@react-native-masked-view/masked-view": ">=0.3.2",
+    "@reduxjs/toolkit": ">=2.13.0",
+    "@rific/auto-paper": ">=0.13.4",
+    "@rific/core": ">=0.5.0",
+    "@rific/feedback-press": ">=0.13.1",
+    "@rific/splash-gate": ">=0.2.3",
+    "@rific/toaster": ">=0.10.1",
+    "@tastic/achievements": ">=0.6.0",
+    "@tastic/core": ">=0.14.0",
+    "@tastic/edge-guard": ">=0.1.5",
+    "@tastic/hud": ">=0.25.1",
+    "@tastic/profile": ">=0.17.0",
+    "@tastic/split-screen": ">=0.5.5",
+    "expo-blur": ">=58.0.5",
+    "expo-constants": ">=58.0.13",
+    "expo-font": ">=58.0.10",
+    "expo-haptics": ">=58.0.7",
+    "expo-keep-awake": ">=58.0.3",
+    "expo-router": ">=58.0.26",
+    "expo-sensors": ">=58.0.4",
+    "expo-splash-screen": ">=58.0.11",
+    "react": ">=19.3.0",
+    "react-native": ">=0.88.0",
+    "react-native-gesture-handler": ">=3.3.0",
+    "react-native-paper": ">=5.15.3",
+    "react-native-reanimated": ">=4.7.1",
+    "react-native-safe-area-context": ">=5.10.1",
+    "react-redux": ">=9.3.0",
+    "redux": ">=5.0.1",
+    "redux-persist": ">=6.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/PackContext.tsx

@@ -0,0 +1,22 @@
+import { createContext, ReactNode, useContext } from 'react'
+
+import type { GameDefinition, PackDefinition } from './types'
+
+// The pack the shell is running: handed in once at the root (see RootLayout), so nothing in shell/
+// ever imports pack.ts or a game. Games reach the shell only through this registry.
+const PackContext = createContext<PackDefinition | null>(null)
+
+export function PackProvider({ pack, children }: { pack: PackDefinition; children: ReactNode }) {
+  return <PackContext.Provider value={pack}>{children}</PackContext.Provider>
+}
+
+export function usePack(): PackDefinition {
+  const pack = useContext(PackContext)
+  if (!pack) throw new Error('usePack must be used within a PackProvider')
+  return pack
+}
+
+// A game by id, or undefined for an id the pack doesn't have (a stale link).
+export function usePackGame(id: string | undefined): GameDefinition | undefined {
+  return usePack().games.find((g) => g.id === id)
+}

package/src/RootLayout.tsx

@@ -0,0 +1,186 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { useHapticSettings } from '@rific/feedback-press'
+import { Toaster, ToastProvider } from '@rific/toaster'
+import { OrientationProvider, useRotationAwareStatusBar, useThemedRootBackground } from '@tastic/core'
+import { RotatedFrame } from '@tastic/hud'
+import * as Haptics from 'expo-haptics'
+import { Stack } from 'expo-router'
+import { DeviceMotion } from 'expo-sensors'
+import { ReactNode, useCallback } from 'react'
+import { StyleSheet } from 'react-native'
+import { GestureHandlerRootView } from 'react-native-gesture-handler'
+import * as RNPaper from 'react-native-paper'
+import { SafeAreaProvider } from 'react-native-safe-area-context'
+import type { Persistor } from 'redux-persist'
+
+import { Fonts } from './components/Fonts'
+import { GuideHost } from './components/GuideHost'
+import { Providers } from './components/Providers'
+import { Theme } from './components/Theme'
+import { UpdateDialog } from './components/UpdateDialog'
+import { useAppSettings } from './hooks/useAppSettings'
+import { LastActiveGameProvider } from './hooks/useLastActiveGame'
+import { ProfilesProvider, useProfiles } from './hooks/useProfiles'
+import { PackProvider } from './PackContext'
+import type { PackStore } from './redux/createPackStore'
+import { SplashGate } from './splashGate'
+import type { GameDefinition, PackDefinition } from './types'
+
+// The pack's root: every provider the shell needs, the pack's games' own providers, and the stack.
+// src/app/_layout.tsx hands it the pack (pack.ts) and its store, so nothing in shell/ imports a
+// game or the pack itself.
+
+// Sits below Theme so it can read the live theme. useThemedRootBackground (@tastic/core) keeps both
+// the screens' contentStyle and the OS root window's own background on the live theme, which is what
+// stops white flashing through the display's rounded corners during a push/pop transition. Passing
+// false disables iOS's swipe-back gesture: otherwise it competes with the game's own pan gestures on
+// a play screen and wins (confirmed on-device in LightCycles, where it kicked the player back to the title
+// screen mid-round instead of turning their cycle). Web has no such OS-level gesture.
+//
+// useRotationAwareStatusBar (@tastic/core) hides the OS status bar whenever the content is rotated
+// off portrait. It does it through screen options because that is the only way left: an app linked
+// against the iOS 27 SDK can't set the status bar app-wide, which is all React Native's StatusBar
+// (and expo-status-bar) does on iOS, and with @tastic/core's config plugin on, every mounted
+// StatusBar logs an error. So nothing in the app mounts one (Theme passes auto-paper's Provider
+// statusBar={false}). No `locked` argument: OrientationBridge already freezes the reading it
+// follows. A play screen hides the bar for the whole round, whatever the angle (a screen's own
+// options win over screenOptions); index is listed first so it stays the stack's first route.
+const PLAY_OPTIONS = { statusBarHidden: true }
+
+function AppStack() {
+  const { dark } = useAutoPaperTheme()
+  const rootBackground = useThemedRootBackground(dark, false)
+  const statusBar = useRotationAwareStatusBar()
+  return (
+    <Stack screenOptions={{ ...rootBackground, ...statusBar }}>
+      <Stack.Screen name='index' />
+      <Stack.Screen name='play/[game]' options={PLAY_OPTIONS} />
+    </Stack>
+  )
+}
+
+// Wires the persisted Lock Orientation setting into @tastic/core's OrientationProvider. Its own
+// component because RootLayout renders the Redux store (inside Providers) and so can't call
+// useAppSettings() itself. Providers' PersistGate holds rendering until the store has rehydrated, so
+// lockInitialValue carries the saved lock from the very first render.
+//
+// freezeWhileLocked makes the lock app-wide: while appSettings.lockOrientation is on, the ONE shared
+// orientation reading freezes for every consumer (every screen, every board, hud dialogs, the
+// status bar), including anything that mounts after the lock, so no call site ever takes a `locked`
+// argument of its own (one would freeze on the pre-sensor default at mount). The Settings dialog
+// toggle only writes appSettings.lockOrientation, which reaches the provider as a changed
+// lockInitialValue; the provider reports the angle it froze on through onLockChange (`rotation`,
+// cleared on unlock), persisted as appSettings.lockedRotation and handed back here so a relaunch reopens
+// in the locked orientation instead of portrait.
+//
+// Mounted once, here, rather than per screen: one app-lifetime sensor subscription is what lets the
+// committed orientation survive navigation. deviceMotion is the app's own expo-sensors import, handed
+// in because @tastic/core never imports expo-sensors itself (apps without tilt tracking would
+// otherwise need it installed just to bundle).
+function OrientationBridge({ children }: { children: ReactNode }) {
+  const { settings, setSettings } = useAppSettings()
+  return (
+    <OrientationProvider deviceMotion={DeviceMotion} freezeWhileLocked lockInitialValue={{ locked: settings.lockOrientation, rotation: settings.lockedRotation }} onLockChange={(next) => setSettings({ lockOrientation: next.locked, lockedRotation: next.rotation })}>
+      {children}
+    </OrientationProvider>
+  )
+}
+
+// ProfilesProvider reconciles the local roster with the shared App Group one before `loaded` flips,
+// so a screen mounting earlier would read (and could persist) the wrong profiles. This holds
+// everything nested inside it, and the splash screen, until that's done, while ProfilesProvider sits
+// above it and starts reconciling immediately. Settings and stats need no gate: they live in the
+// Redux store, which Providers' PersistGate already holds until rehydrated.
+function GatedApp({ children }: { children: ReactNode }) {
+  const { loaded } = useProfiles()
+  return (
+    <SplashGate gate='profiles' ready={loaded}>
+      {children}
+    </SplashGate>
+  )
+}
+
+// The toaster only gets expo-haptics while the player's Vibrate setting is on, so its haptic ticks
+// follow the same setting as every other haptic in the app. Today they can't fire anyway (the only
+// controls that tick, the history and clear buttons, are off below), but this keeps it that way if
+// either is ever shown. Must render inside Providers, whose FeedbackBridge provides the setting.
+function HapticGatedToastProvider({ children }: { children: ReactNode }) {
+  const { settings } = useHapticSettings()
+  return (
+    <ToastProvider haptics={settings.vibrate ? Haptics : undefined} paper={RNPaper}>
+      {children}
+    </ToastProvider>
+  )
+}
+
+function RotatingToaster() {
+  const renderFrame = useCallback(
+    (toasts: ReactNode) => (
+      <RotatedFrame rotatedSafeArea passThrough>
+        {toasts}
+      </RotatedFrame>
+    ),
+    []
+  )
+  return <Toaster historyButton={null} clearButton={null} limit={3} renderFrame={renderFrame} />
+}
+
+// Every game's own root provider (its stats and achievements context), nested in pack order.
+function GameProviders({ games, children }: { games: readonly GameDefinition[]; children: ReactNode }) {
+  return games.reduceRight<ReactNode>((inner, game) => <game.Provider key={game.id}>{inner}</game.Provider>, children)
+}
+
+interface RootLayoutProps {
+  pack: PackDefinition
+  store: PackStore
+  persistor: Persistor
+}
+
+export function RootLayout({ pack, store, persistor }: RootLayoutProps) {
+  return (
+    <GestureHandlerRootView style={styles.root}>
+      <SafeAreaProvider>
+        <PackProvider pack={pack}>
+          <Fonts>
+            <Providers store={store} persistor={persistor}>
+              <Theme>
+                <ProfilesProvider>
+                  {/* Inside Providers' PersistGate, so the game a cold launch resumes (read once, as
+                  it mounts) is the saved one. */}
+                  <LastActiveGameProvider>
+                    <GameProviders games={pack.games}>
+                      <GatedApp>
+                        <OrientationBridge>
+                          <HapticGatedToastProvider>
+                            {/* Wraps the stack (rather than sitting beside it like UpdateDialog)
+                            because Home's tiles and the loadout's How to Play row reach it through
+                            context (see GuideHost). Inside the toast provider and OrientationBridge
+                            because the card renders through a Portal and rotates with the shared
+                            reading, and inside the gate so it mounts together with Home rather than
+                            before it. */}
+                            <GuideHost>
+                              <AppStack />
+                            </GuideHost>
+                            {/* historyButton/clearButton off: there's no toast history to open, and a
+                            control row for it above the toast stack would go nowhere. limit pins the
+                            package's current default (3) so a future toaster release can't change it. */}
+                            <RotatingToaster />
+                            <UpdateDialog />
+                          </HapticGatedToastProvider>
+                        </OrientationBridge>
+                      </GatedApp>
+                    </GameProviders>
+                  </LastActiveGameProvider>
+                </ProfilesProvider>
+              </Theme>
+            </Providers>
+          </Fonts>
+        </PackProvider>
+      </SafeAreaProvider>
+    </GestureHandlerRootView>
+  )
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1 }
+})

package/src/components/Fonts.tsx

@@ -0,0 +1,41 @@
+import { MaterialCommunityIcons } from '@expo/vector-icons'
+import Constants from 'expo-constants'
+import { useFonts } from 'expo-font'
+import Head from 'expo-router/head'
+import { ReactNode } from 'react'
+import { Platform } from 'react-native'
+
+import { usePack } from '../PackContext'
+import { SplashGate } from '../splashGate'
+
+interface Props {
+  children: ReactNode
+}
+
+// Holds the splash screen up (see splashGate.ts's 'fonts' gate) until the MaterialCommunityIcons
+// glyph font and the pack's own fonts (PackDefinition.fonts, its hero's display face) have actually
+// loaded - otherwise every react-native-paper Icon/IconButton (and @rific/feedback-press's
+// IconButton, which wraps paper's under the hood) would render blank, and a hero would render in
+// its fallback font, for one visible frame before snapping in once the async load resolves.
+// Gated via the Gate component (SplashGate, per splashGate.ts's own alias) rather than a
+// hand-rolled `if (!loaded) return null` - marking the splash gate ready and holding `children`
+// back until then happen in one place this way, same as RootLayout's 'profiles' gate.
+export function Fonts({ children }: Props) {
+  const pack = usePack()
+  // A failed load counts as ready too: `loaded` stays false forever after an error, which would hold
+  // the splash up for good, so the app opens on the system fallback font instead.
+  const [loaded, error] = useFonts({ ...pack.fonts, ...MaterialCommunityIcons.font })
+  return (
+    <>
+      {/* The web tab title, outside the fonts gate. Since SDK 58 Head only sets it after hydration; the static export's HTML no longer carries it (see TODO.md). Web only: on iOS, expo-router's Head is Handoff/Spotlight metadata that needs the plugin's `origin` set, and without it every route change throws (a dev build) or shows a system alert (a production build) */}
+      {Platform.OS === 'web' && (
+        <Head>
+          <title>{Constants.expoConfig?.name}</title>
+        </Head>
+      )}
+      <SplashGate gate='fonts' ready={loaded || !!error}>
+        {children}
+      </SplashGate>
+    </>
+  )
+}

package/src/components/GuideHost.tsx

@@ -0,0 +1,104 @@
+import { useIsTouchPrimaryDevice, useRotation } from '@tastic/core'
+import { GuideProvider, useGuide } from '@tastic/hud/guide'
+import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
+import { shallowEqual, useDispatch, useSelector, useStore } from 'react-redux'
+
+import { usePack } from '../PackContext'
+import type { ShellState } from '../redux/shellState'
+import { roundModeFor, seatTwoFor } from '../types'
+
+interface GameGuideContextValue {
+  // Shows a game's How to Play cards if this player hasn't finished or skipped this version yet,
+  // then runs `next` once they close; runs `next` at once otherwise. Home calls it on a tile tap, so
+  // a game's cards show the first time it's picked, before its loadout opens.
+  openFirstTime: (gameId: string, next: () => void) => void
+  // Shows a game's cards now, seen or not (a tile's rules button, a loadout's How to Play row).
+  openFor: (gameId: string) => void
+}
+
+const GameGuideContext = createContext<GameGuideContextValue | null>(null)
+
+interface Props {
+  children: ReactNode
+}
+
+// One @tastic/hud GuideProvider for the whole pack, showing whichever game's cards were asked for
+// last. Each game's cards come from its own registry entry (GameDefinition.guide), built from the
+// live settings and seat 2 so a replay after any loadout change describes the next match. Mounted
+// around the stack in RootLayout, inside the toast provider and OrientationBridge because the card
+// renders through a Portal and turns with the shared reading (`rotation`, the same one Home hands
+// its Settings dialog), and inside the profiles gate so it mounts together with Home.
+export function GuideHost({ children }: Props) {
+  const pack = usePack()
+  const [gameId, setGameId] = useState(pack.games[0].id)
+  const game = pack.games.find((g) => g.id === gameId) ?? pack.games[0]
+
+  const rotation = useRotation()
+  const touch = useIsTouchPrimaryDevice()
+  const seatTwo = useSelector((state: ShellState) => state.opponent.seatTwo)
+  const input = useSelector((state: ShellState) => game.guide.selectInput(state), shallowEqual)
+  const seenVersion = useSelector((state: ShellState) => game.guide.selectVersionSeen(state))
+  const dispatch = useDispatch()
+
+  // The seat-2 choice the cards describe: the one the player last picked, the CPU in a game that has
+  // no room for it (a saved 'nobody' in a game without a solo mode), or nobody in a game for one.
+  const mode = roundModeFor(seatTwoFor(seatTwo, game.seatTwo))
+  const steps = useMemo(() => game.guide.getSteps(input, { touch, mode }), [game, input, touch, mode])
+  const onSeen = useCallback((version: number) => dispatch(game.guide.markSeen(version)), [dispatch, game])
+
+  return (
+    <GuideProvider steps={steps} currentVersion={game.guide.version} seenVersion={seenVersion} onSeen={onSeen} rotation={rotation}>
+      <GameGuideBridge onPick={setGameId}>{children}</GameGuideBridge>
+    </GuideProvider>
+  )
+}
+
+// Inside GuideProvider, so it can open the dialog and watch it close.
+function GameGuideBridge({ onPick, children }: { onPick: (gameId: string) => void; children: ReactNode }) {
+  const pack = usePack()
+  const store = useStore<ShellState>()
+  const { isOpen, open } = useGuide()
+  const pendingNext = useRef<(() => void) | null>(null)
+  const wasOpen = useRef(false)
+
+  // When cards opened by openFirstTime close (finished, skipped or dismissed), carry on to where the
+  // tap was going.
+  useEffect(() => {
+    if (wasOpen.current && !isOpen && pendingNext.current) {
+      const next = pendingNext.current
+      pendingNext.current = null
+      next()
+    }
+    wasOpen.current = isOpen
+  }, [isOpen])
+
+  const openFor = useCallback(
+    (gameId: string) => {
+      onPick(gameId)
+      open()
+    },
+    [onPick, open]
+  )
+
+  const openFirstTime = useCallback(
+    (gameId: string, next: () => void) => {
+      const game = pack.games.find((g) => g.id === gameId)
+      if (!game || game.guide.selectVersionSeen(store.getState()) >= game.guide.version) {
+        next()
+        return
+      }
+      pendingNext.current = next
+      openFor(gameId)
+    },
+    [pack, store, openFor]
+  )
+
+  const value = useMemo(() => ({ openFirstTime, openFor }), [openFirstTime, openFor])
+  return <GameGuideContext.Provider value={value}>{children}</GameGuideContext.Provider>
+}
+
+export function useGameGuide(): GameGuideContextValue {
+  const ctx = useContext(GameGuideContext)
+  if (!ctx) throw new Error('useGameGuide must be used within a GuideHost')
+  return ctx
+}

package/src/components/Providers.tsx

@@ -0,0 +1,86 @@
+import { keepAwakeActions, KeepAwakeProvider, type KeepAwakeSettings } from '@rific/core'
+import { FeedbackPressProvider, hapticActions, type HapticSettings, soundActions, type SoundSettings, useFeedbackBridgeProps } from '@rific/feedback-press'
+import { useAudioPool } from '@rific/feedback-press/audio'
+import { useEdgeGestureGuard } from '@tastic/edge-guard'
+import * as ExpoKeepAwake from 'expo-keep-awake'
+import { ReactNode, useCallback } from 'react'
+import * as RNPaper from 'react-native-paper'
+import { Provider as ReduxProvider, useDispatch, useSelector } from 'react-redux'
+import type { Persistor } from 'redux-persist'
+import { PersistGate } from 'redux-persist/integration/react'
+
+import type { PackStore } from '../redux/createPackStore'
+import type { ShellState } from '../redux/shellState'
+
+interface Props {
+  children: ReactNode
+}
+
+// Redux-backed haptic/sound settings, dispatching through @rific/feedback-press's own
+// hapticActions/soundActions - same shape as Expo-Starter/Snake's FeedbackBridge, converged onto
+// fleet-wide rather than this app's old direct-AsyncStorage version.
+const FeedbackBridge = ({ children }: Props) => {
+  const haptic = useSelector((state: ShellState) => state.haptic)
+  const sound = useSelector((state: ShellState) => state.sound)
+  const dispatch = useDispatch()
+  const onChange = useCallback((next: HapticSettings) => dispatch(hapticActions.initialize(next)), [dispatch])
+  const onSoundChange = useCallback((next: SoundSettings) => dispatch(soundActions.initialize(next)), [dispatch])
+
+  // Generic UI feedback sounds, wired into every Button/IconButton/etc. in the package (see
+  // useFeedbackHandlers' `fire`, which already gates these on the sound-enabled setting itself -
+  // no need to re-check it here).
+  const playSelection = useAudioPool(require('../../assets/sounds/select.wav'))
+  const playNotification = useAudioPool(require('../../assets/sounds/notification.wav'))
+
+  const bridgeProps = useFeedbackBridgeProps({ initialValue: haptic, onChange, soundInitialValue: sound, onSoundChange, sound: { selection: playSelection, notification: playNotification } })
+
+  return (
+    <FeedbackPressProvider {...bridgeProps} paper={RNPaper}>
+      {children}
+    </FeedbackPressProvider>
+  )
+}
+
+// The one place @tastic/edge-guard's hook is called, mounted once for the app's lifetime rather than
+// per screen. appSettings.deferBottomEdgeGestures is the player's opt-in; liveplay.activelyPlaying is
+// a play screen's report that a live round is in progress right now (see liveplaySlice.ts). Combining them
+// here keeps Edge Guard both opt-in and scoped to actual play.
+const EdgeGuardBridge = ({ children }: Props) => {
+  const deferBottomEdgeGestures = useSelector((state: ShellState) => state.appSettings.deferBottomEdgeGestures)
+  const activelyPlaying = useSelector((state: ShellState) => state.liveplay.activelyPlaying)
+  useEdgeGestureGuard(deferBottomEdgeGestures && activelyPlaying)
+  return <>{children}</>
+}
+
+// @rific/core's Keep Awake setting (Settings dialog), persisted as the store's `keepAwake` slice.
+// Handing it expo-keep-awake is what turns the feature on: each play screen's useKeepAwake('game') and hud's
+// Keep Awake row both read the module from here.
+const KeepAwakeBridge = ({ children }: Props) => {
+  const keepAwake = useSelector((state: ShellState) => state.keepAwake)
+  const dispatch = useDispatch()
+  const onChange = useCallback((settings: KeepAwakeSettings) => dispatch(keepAwakeActions.initialize(settings)), [dispatch])
+  return (
+    <KeepAwakeProvider expoKeepAwake={ExpoKeepAwake} initialValue={keepAwake} onChange={onChange}>
+      {children}
+    </KeepAwakeProvider>
+  )
+}
+
+interface ProvidersProps extends Props {
+  store: PackStore
+  persistor: Persistor
+}
+
+export function Providers({ store, persistor, children }: ProvidersProps) {
+  return (
+    <ReduxProvider store={store}>
+      <PersistGate persistor={persistor}>
+        <EdgeGuardBridge>
+          <FeedbackBridge>
+            <KeepAwakeBridge>{children}</KeepAwakeBridge>
+          </FeedbackBridge>
+        </EdgeGuardBridge>
+      </PersistGate>
+    </ReduxProvider>
+  )
+}