@tastic/shell 0.0.0-stage → 0.1.1

package/src/hooks/useProfiles.tsx

@@ -0,0 +1,134 @@
+import { type CreateProfileInput, createProfileRecord, Profile, profilesActions, resolveInitialProfiles, useSharedProfilesSync } from '@tastic/profile'
+import { createContext, ReactNode, useCallback, useContext, useEffect, useState } from 'react'
+import { useDispatch, useSelector } from 'react-redux'
+import type { Action, Dispatch } from 'redux'
+
+import { profileSelectionActions } from '../redux/profileSelectionSlice'
+import type { ShellState } from '../redux/shellState'
+import type { Seat } from '../types'
+
+// Same group id BoxHockey and LightCycles both declare in app.json's ios.entitlements (and any
+// future @tastic game that wants into the same shared roster) - see @tastic/profile's own README
+// for why only the base identity fields travel through this.
+const SHARED_GROUP_ID = 'group.com.infinitetoken.tastic'
+
+interface ProfilesContextValue {
+  profiles: Profile[]
+  lastSelected: Record<Seat, string | null>
+  // True once the one-time initial reconciliation below (redux-persist's own already-rehydrated
+  // `profiles` against the shared App Group store) has completed - see ProfilesProvider's own doc.
+  // RootLayout's GatedApp reads this to hold its children back (see splashGate.ts's
+  // 'profiles' gate) until real profile data exists, rather than the empty starting state.
+  loaded: boolean
+  createProfile: (input: CreateProfileInput) => Profile
+  updateProfile: (id: string, patch: Partial<CreateProfileInput>) => void
+  // Also clears lastSelected for any seat currently pointing at this id, so /loadout immediately
+  // reflects Player (no profile) for that seat rather than a dangling id until next reload.
+  deleteProfile: (id: string) => void
+  selectProfile: (seat: Seat, profileId: string | null) => void
+}
+
+const ProfilesContext = createContext<ProfilesContextValue | null>(null)
+
+interface Props {
+  children: ReactNode
+}
+
+// Single source of truth for saved player profiles, mounted once at the root (RootLayout): expo-router
+// keeps prior screens mounted, so a per-screen copy could go stale or clobber a concurrent update.
+//
+// `profiles` lives in Redux (the shell's `profiles` key, @tastic/profile's own profilesReducer),
+// persisted locally like every other key, with the shared App Group roster layered on top as a
+// separate, cross-app sync target (see resolveInitialProfiles/useSharedProfilesSync below).
+// `lastSelected` is profileSelectionSlice.ts: which profile seat 1/2 last picked is a per-app thing,
+// never shared cross-app. Only the base identity fields live here; a game that keeps something per
+// profile (Box Hockey's control scheme) keeps it in its own slice.
+//
+// Gating stays external (RootLayout's GatedApp holds the app behind the 'profiles' splash gate
+// until `loaded`); this provider just exposes `loaded` and always renders `children` at once.
+export function ProfilesProvider({ children }: Props) {
+  const profiles = useSelector((state: ShellState) => state.profiles)
+  const lastSelected = useSelector((state: ShellState) => state.profileSelection)
+  const dispatch = useDispatch<Dispatch<Action>>()
+  const [loaded, setLoaded] = useState(false)
+
+  useEffect(() => {
+    let cancelled = false
+    // PersistGate (an ancestor - see components/Providers.tsx) already blocks this component from
+    // mounting until redux-persist has rehydrated, so `profiles` here is already whatever this
+    // device last had locally - resolveInitialProfiles reconciles that against the shared App
+    // Group store (if available), seeding the shared store from it on a first sync, or preferring
+    // the shared roster once anything has been shared. A one-time reconciliation against the
+    // mount-time snapshot, deliberately not a resync whenever `profiles` changes afterward (the
+    // empty deps array below is intentional, not a missed dependency - resolveInitialProfiles' own
+    // setAll dispatch would otherwise re-trigger this effect).
+    resolveInitialProfiles(SHARED_GROUP_ID, profiles).then((resolved) => {
+      if (cancelled) return
+      dispatch(profilesActions.setAll(resolved))
+      // A seat can still point at a profile a sibling app deleted since this device last ran.
+      dispatch(profileSelectionActions.pruneToRoster(resolved.map((p) => p.id)))
+      setLoaded(true)
+    })
+    return () => {
+      cancelled = true
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  // Mirrors local writes out to the shared store (syncToShared, called from each CRUD function
+  // below) and picks up remote writes a sibling @tastic app made while this one was backgrounded
+  // (onRemoteChange) - see @tastic/profile's own doc for both.
+  const { syncToShared } = useSharedProfilesSync({
+    groupId: SHARED_GROUP_ID,
+    onRemoteChange: useCallback(
+      (remote: Profile[]) => {
+        dispatch(profilesActions.setAll(remote))
+        // Same job as deleteProfile's clearProfile below, for profiles a sibling app deleted while this one was backgrounded.
+        dispatch(profileSelectionActions.pruneToRoster(remote.map((p) => p.id)))
+      },
+      [dispatch]
+    )
+  })
+
+  const createProfile = useCallback(
+    (input: CreateProfileInput) => {
+      const record = createProfileRecord(input)
+      dispatch(profilesActions.add(record))
+      syncToShared([...profiles, record])
+      return record
+    },
+    [profiles, dispatch, syncToShared]
+  )
+
+  const updateProfile = useCallback(
+    (id: string, patch: Partial<CreateProfileInput>) => {
+      dispatch(profilesActions.update({ id, patch }))
+      syncToShared(profiles.map((p) => (p.id === id ? { ...p, ...patch, updatedAt: Date.now() } : p)))
+    },
+    [profiles, dispatch, syncToShared]
+  )
+
+  const deleteProfile = useCallback(
+    (id: string) => {
+      dispatch(profilesActions.remove(id))
+      syncToShared(profiles.filter((p) => p.id !== id))
+      dispatch(profileSelectionActions.clearProfile(id))
+    },
+    [profiles, dispatch, syncToShared]
+  )
+
+  const selectProfile = useCallback(
+    (seat: Seat, profileId: string | null) => {
+      dispatch(profileSelectionActions.select({ profileId, seat }))
+    },
+    [dispatch]
+  )
+
+  return <ProfilesContext.Provider value={{ profiles, lastSelected, loaded, createProfile, updateProfile, deleteProfile, selectProfile }}>{children}</ProfilesContext.Provider>
+}
+
+export function useProfiles() {
+  const ctx = useContext(ProfilesContext)
+  if (!ctx) throw new Error('useProfiles must be used within a ProfilesProvider')
+  return ctx
+}

package/src/hooks/useSeatColors.ts

@@ -0,0 +1,148 @@
+import { getThirdColor, useAutoPaperTheme, useThemeSettings } from '@rific/auto-paper'
+import { avoidSeatColorClash, profileSeatColor } from '@tastic/profile'
+import { useFocusEffect } from 'expo-router'
+import { useCallback, useEffect, useRef } from 'react'
+import { useDispatch, useSelector } from 'react-redux'
+import type { Action, Dispatch } from 'redux'
+
+import { usePack } from '../PackContext'
+import { seatColorsActions } from '../redux/seatColorsSlice'
+import type { ShellState } from '../redux/shellState'
+import type { Seat } from '../types'
+import { useProfiles } from './useProfiles'
+
+// Both seats' live colors (the theme's primary and secondary) and the handlers that change them,
+// for Home's who's-playing button and the loadout's seat buttons. `p2IsHuman` says whether seat 2
+// is a person (a guest or a profile) or the CPU, which decides where seat 2's color comes from.
+export function useSeatColors(p2IsHuman: boolean) {
+  const { colors: themeColors } = useAutoPaperTheme()
+  const { set: setThemeColor } = useThemeSettings()
+  const p1Color = themeColors.primary
+  const p2Color = themeColors.secondary
+  const { profiles, lastSelected } = useProfiles()
+  // What @tastic/profile's avoidSeatColorClash moves seat 2 to when both seats land on one color: a
+  // profile picked for one seat can be saved as the other seat's color, with no swap step behind it.
+  // The pack's own seat colors, which never change while it runs.
+  const { seatColors } = usePack()
+  const seatDefaultColors = [seatColors[1], seatColors[2]] as const
+
+  // Typed explicitly because @tastic/profile's action creators return a plain `{ payload, type }`
+  // interface with no index signature, which react-redux's default Dispatch<UnknownAction> rejects.
+  const dispatch = useDispatch<Dispatch<Action>>()
+  // A seat's live color comes from one of three independently-remembered places depending on what's
+  // in that seat - a selected profile's pick in this pack (or its own saved color without one), the
+  // CPU's own remembered color, or a guest's own remembered color - all in the `seatColors` slice
+  // (seatColorsSlice.ts). A profile's own saved color is never written back to; only the Profiles
+  // screen edits it.
+  const guestColors = useSelector((state: ShellState) => state.seatColors.lastGuestColor)
+  const cpuColor = useSelector((state: ShellState) => state.seatColors.lastCpuColor)
+  // Each profile's own color pick in this pack, by profile id, read through @tastic/profile's
+  // profileSeatColor. It follows the profile, not the seat: kept through a switch to another profile
+  // and back, a move to the other seat, and a relaunch.
+  const profileColors = useSelector((state: ShellState) => state.seatColors.profileColors)
+
+  const p1Profile = profiles.find((p) => p.id === lastSelected[1]) ?? null
+  const p2Profile = p2IsHuman ? (profiles.find((p) => p.id === lastSelected[2]) ?? null) : null
+
+  // Mirrored for the focus effect below, so it can read each seat's current profile and remembered
+  // colors without depending on them (profiles is a new array on every useProfiles() render, and
+  // useFocusEffect re-runs whenever its callback's identity changes, even while still focused).
+  const p1ProfileRef = useRef(p1Profile)
+  const p2ProfileRef = useRef(p2Profile)
+  const guestColorsRef = useRef(guestColors)
+  const cpuColorRef = useRef(cpuColor)
+  const profileColorsRef = useRef(profileColors)
+  useEffect(() => {
+    p1ProfileRef.current = p1Profile
+  }, [p1Profile])
+  useEffect(() => {
+    p2ProfileRef.current = p2Profile
+  }, [p2Profile])
+  useEffect(() => {
+    guestColorsRef.current = guestColors
+  }, [guestColors])
+  useEffect(() => {
+    cpuColorRef.current = cpuColor
+  }, [cpuColor])
+  useEffect(() => {
+    profileColorsRef.current = profileColors
+  }, [profileColors])
+
+  // Keeps each seat's live theme color matching what it's supposed to be right now: on mount, and
+  // when a seat's profile changes (a pick, the swap when a seat picks the other seat's profile, or a
+  // deletion from Manage), when seat 2 changes between the CPU and a person, when a profile's pick
+  // changes, and when the roster resolves. profiles itself is read, not depended on (a new array on
+  // every render); profiles.length stands in as a coarse "profiles finished loading" signal.
+  useEffect(() => {
+    const nextP1 = p1Profile ? profileSeatColor(p1Profile, profileColors) : guestColors[1]
+    const nextP2 = avoidSeatColorClash(nextP1, p2Profile ? profileSeatColor(p2Profile, profileColors) : p2IsHuman ? guestColors[2] : cpuColor, seatDefaultColors)
+    if (nextP1.toLowerCase() === p1Color.toLowerCase() && nextP2.toLowerCase() === p2Color.toLowerCase()) return
+    setThemeColor({ color: { primary: nextP1, secondary: nextP2, tertiary: getThirdColor(nextP1, nextP2) } })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [lastSelected[1], lastSelected[2], p2IsHuman, guestColors, cpuColor, profileColors, profiles.length])
+
+  // The loadout pushes the play screen and Profiles on top of itself and comes back via
+  // router.back()/safeBack() - a pop that reveals this same, still-mounted screen. On every focus
+  // regain, re-derive each seat's live color from its authoritative source, so editing a profile's
+  // own color on the Profiles screen is picked up the instant you're back (a new color for the
+  // profile drops its pick, see profileSeatColor). Keyed only on what is a real reason to reapply;
+  // everything else is read through the refs above.
+  useFocusEffect(
+    useCallback(() => {
+      const guest = guestColorsRef.current
+      const cpu = cpuColorRef.current
+      const p1Prof = p1ProfileRef.current
+      const p2Prof = p2ProfileRef.current
+      const picks = profileColorsRef.current
+      const nextP1 = p1Prof ? profileSeatColor(p1Prof, picks) : guest[1]
+      const nextP2 = avoidSeatColorClash(nextP1, p2Prof ? profileSeatColor(p2Prof, picks) : p2IsHuman ? guest[2] : cpu, seatDefaultColors)
+      setThemeColor({ color: { primary: nextP1, secondary: nextP2, tertiary: getThirdColor(nextP1, nextP2) } })
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [lastSelected[1], lastSelected[2], p2IsHuman, setThemeColor])
+  )
+
+  // Routes a seat's just-changed color to whichever slot owns it right now - kept as that profile's
+  // pick in this pack (the pack's caption on the seat button's Color row) when a profile's in the
+  // seat. Picking the profile's own color drops the pick.
+  const persistSeatColor = useCallback(
+    (seat: Seat, hex: string) => {
+      const profile = seat === 1 ? p1Profile : p2Profile
+      if (profile) {
+        dispatch(seatColorsActions.setProfileColor({ profile, color: hex }))
+        return
+      }
+      if (seat === 2 && !p2IsHuman) {
+        dispatch(seatColorsActions.setLastCpuColor(hex))
+        return
+      }
+      dispatch(seatColorsActions.setLastGuestColor({ seat, color: hex }))
+    },
+    [p1Profile, p2Profile, p2IsHuman, dispatch]
+  )
+
+  // Picking the other seat's exact current color swaps the two instead of no-op'ing - only reachable
+  // where that picker allows it (allowSwapTaken: against the CPU only, where the other color is the
+  // CPU's, not a second person's choice). Each side of a swap persists by its own seat's rule above.
+  const handleP1ColorChange = useCallback(
+    (hex: string) => {
+      const swapped = hex.toLowerCase() === p2Color.toLowerCase()
+      const nextP2 = swapped ? p1Color : p2Color
+      setThemeColor({ color: { primary: hex, secondary: nextP2, tertiary: getThirdColor(hex, nextP2) } })
+      persistSeatColor(1, hex)
+      if (swapped) persistSeatColor(2, nextP2)
+    },
+    [setThemeColor, p1Color, p2Color, persistSeatColor]
+  )
+  const handleP2ColorChange = useCallback(
+    (hex: string) => {
+      const swapped = hex.toLowerCase() === p1Color.toLowerCase()
+      const nextP1 = swapped ? p2Color : p1Color
+      setThemeColor({ color: { primary: nextP1, secondary: hex, tertiary: getThirdColor(nextP1, hex) } })
+      persistSeatColor(2, hex)
+      if (swapped) persistSeatColor(1, nextP1)
+    },
+    [setThemeColor, p1Color, p2Color, persistSeatColor]
+  )
+
+  return { p1Color, p2Color, handleP1ColorChange, handleP2ColorChange }
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+// The pack's root and its registry: an app's src/app/_layout.tsx renders RootLayout with its pack
+// and store, and every screen, game and shared piece reads the pack through usePack().
+export { PackProvider, usePack, usePackGame } from './PackContext'
+export { RootLayout } from './RootLayout'
+export { type GameDefinition, type GameGuide, type GameIconProps, type GameLoadout, type GamePreviewProps, type HeroTitleProps, humanSeatsFor, type LoadoutOptionsProps, type PackDefinition, type PackStatsSectionsProps, type RoundMode, roundModeFor, type Seat, type SeatControlLook, type SeatTwo, seatTwoFor } from './types'
+
+// The screens behind an app's routes (src/app/ stays in the app: expo-router only reads routes there).
+export { LoadoutRoute, PlayRoute } from './screens/GameRoute'
+export { HomeScreen } from './screens/HomeScreen'
+// The shape of the box a game's Preview draws in on Home (width / height).
+export { PREVIEW_ASPECT } from './screens/homeLayout'
+export { ProfilesRoute } from './screens/ProfilesRoute'
+export { StatsScreen } from './screens/StatsScreen'
+
+// What a game's own screens use.
+export { useGameGuide } from './components/GuideHost'
+export { imageGameIcon } from './components/imageGameIcon'
+export { SettingsDialog, type SettingsDialogProps } from './components/SettingsDialog'
+export { useActiveRound } from './hooks/useActiveRound'
+export { useAppSettings } from './hooks/useAppSettings'
+export { useOpponent } from './hooks/useOpponent'
+export { ProfilesProvider, useProfiles } from './hooks/useProfiles'
+export { useSeatColors } from './hooks/useSeatColors'
+export { safeBack } from './navigation'
+
+// The store: the pack's one store, the shell's own keys, and what a game builds its keys from.
+export { type AppSettings, appSettingsActions, default as appSettingsReducer, DEFAULT_APP_SETTINGS } from './redux/appSettingsSlice'
+export { createPackStore, type PackStore, type PackStoreConfig, type PackStoreSource } from './redux/createPackStore'
+export { createGameGuideSlice, type GameGuideState } from './redux/gameGuideSlice'
+export { type ActiveRound, liveplayActions, default as liveplayReducer, type LiveplaySliceState } from './redux/liveplaySlice'
+export { forgetProfileAchievements, onProfileRemoved } from './redux/onProfileRemoved'
+export { DEFAULT_OPPONENT, opponentActions, default as opponentReducer, type OpponentState } from './redux/opponentSlice'
+export { defaultProfileSelectionState, profileSelectionActions, default as profileSelectionReducer, type ProfileSelectionState } from './redux/profileSelectionSlice'
+export { createSeatColorsReducer, defaultSeatColorsState, seatColorsActions, type SeatColorsState } from './redux/seatColorsSlice'
+export { createShellReducers, type ShellState } from './redux/shellState'
+
+// A game's per-player settings and its stats and achievements (src/shared/ in the apps until now).
+export { createGameStats, type RecordResult } from './gameStats'
+export { createPlayerSettings, type PlayerControlsState, type PlayerSettingsState, seatPlayerKey } from './playerSettings'

package/src/navigation.ts

@@ -0,0 +1,11 @@
+import { configureNavigation, safeBack } from '@rific/core'
+import { router } from 'expo-router'
+
+// safeBack's own implementation (router.canGoBack() ? router.back() : router.replace(fallbackPath))
+// now lives in @rific/core, shared across the fleet - this just injects expo-router's `router` once
+// at module load (the fallback path defaults to '/', already correct for this app's own root route)
+// and re-exports safeBack unchanged, so every existing call site (`safeBack()`, `onBack={safeBack}`,
+// `onHome={safeBack}`, `onConfirm={safeBack}`) keeps working with zero changes.
+configureNavigation({ router })
+
+export { safeBack }

package/src/playerSettings.ts

@@ -0,0 +1,112 @@
+import { useCallback, useMemo } from 'react'
+import { useDispatch, useSelector } from 'react-redux'
+import type { UnknownAction } from 'redux'
+
+import { onProfileRemoved } from './redux/onProfileRemoved'
+import type { ShellState } from './redux/shellState'
+import type { Seat } from './types'
+
+const SEATS: readonly Seat[] = [1, 2]
+
+// Who a seat's saved settings belong to: the profile picked for it, or that seat's guest. Seat 1's
+// and seat 2's guests are different people, so each keeps its own.
+export function seatPlayerKey(selection: Record<Seat, string | null>, seat: Seat): string {
+  return selection[seat] ?? `guest:${seat}`
+}
+
+// A game's settings with each seat's controls (Box Hockey's shot style, the desktop keys elsewhere).
+type WithControls<C> = { controlScheme: Record<Seat, C> }
+
+// Saved per player: the match settings each player last set up as seat 1 (only what they changed;
+// the rest comes from the game's defaults, so a setting added later starts at its default), and
+// the controls each player last played with, in either seat.
+export type PlayerSettingsState<S> = Record<string, Partial<Omit<S, 'controlScheme'>>>
+export type PlayerControlsState<C> = Record<string, C>
+
+interface PlayerSettingsOptions<S extends WithControls<C>, C> {
+  // The game's id: its store keys are `${id}Settings` and `${id}Controls`.
+  id: string
+  defaults: S
+  // When the two seats can't share one control (a desktop key cluster), every control in menu order:
+  // if both seats would get the same one, seat 2 takes the first one seat 1 isn't using (shown and
+  // played, never saved). Leave out where both can use the same (Box Hockey's shot styles).
+  distinctControls?: readonly C[]
+}
+
+// One game's loadout, kept per player (Jay, 2026-10-24): the match settings follow seat 1's player,
+// so each person's own setup loads when they're picked; each seat's controls follow the player in
+// that seat. A seat's color pick is the shell's (seatColors, by profile). Seat 2 itself (the CPU, a
+// person or nobody) is pack-wide, and so is everything in appSettings.
+export function createPlayerSettings<S extends WithControls<C>, C>({ id, defaults, distinctControls }: PlayerSettingsOptions<S, C>) {
+  const settingsKey = `${id}Settings`
+  const controlsKey = `${id}Controls`
+  const PATCH = `${settingsKey}/patch`
+  const SET_CONTROL = `${controlsKey}/set`
+
+  const patch = (player: string, changes: Partial<Omit<S, 'controlScheme'>>) => ({ type: PATCH, payload: { player, changes } })
+  const setControl = (player: string, control: C) => ({ type: SET_CONTROL, payload: { player, control } })
+
+  function forget<T>(state: Record<string, T>, profileId: string): Record<string, T> {
+    if (!(profileId in state)) return state
+    const { [profileId]: _removed, ...rest } = state
+    return rest
+  }
+
+  const settingsReducer = onProfileRemoved((state: PlayerSettingsState<S> = {}, action: UnknownAction): PlayerSettingsState<S> => {
+    if (action.type !== PATCH) return state
+    const { player, changes } = action.payload as ReturnType<typeof patch>['payload']
+    return { ...state, [player]: { ...state[player], ...changes } }
+  }, forget)
+
+  const controlsReducer = onProfileRemoved((state: PlayerControlsState<C> = {}, action: UnknownAction): PlayerControlsState<C> => {
+    if (action.type !== SET_CONTROL) return state
+    const { player, control } = action.payload as ReturnType<typeof setControl>['payload']
+    return state[player] === control ? state : { ...state, [player]: control }
+  }, forget)
+
+  // The settings the loadout shows and a round plays with, from the saved state: seat 1's player's
+  // own setup over the defaults, and each seat's player's controls (seat 2's only for a person).
+  function compose(saved: PlayerSettingsState<S> | undefined, controls: PlayerControlsState<C> | undefined, selection: Record<Seat, string | null>, seatTwoIsPerson: boolean): S {
+    const control1 = controls?.[seatPlayerKey(selection, 1)] ?? defaults.controlScheme[1]
+    let control2 = (seatTwoIsPerson ? controls?.[seatPlayerKey(selection, 2)] : undefined) ?? defaults.controlScheme[2]
+    if (distinctControls && control2 === control1) control2 = distinctControls.find((c) => c !== control1) ?? control2
+    return { ...defaults, ...saved?.[seatPlayerKey(selection, 1)], controlScheme: { 1: control1, 2: control2 } } as S
+  }
+
+  // The same, read straight from the store (a game's How to Play reads it this way).
+  function select(state: ShellState): S {
+    const root = state as unknown as Record<string, unknown>
+    return compose(root[settingsKey] as PlayerSettingsState<S> | undefined, root[controlsKey] as PlayerControlsState<C> | undefined, state.profileSelection, state.opponent.seatTwo === 'person')
+  }
+
+  // The loadout's settings and their one write path. A patch's match settings go to seat 1's player;
+  // a changed control goes to that seat's player (seat 2's only for a person), so a swap of desktop
+  // keys between the seats saves both players' new keys.
+  function useSettings(): { settings: S; setSettings: (patch: Partial<S>) => void } {
+    const selection = useSelector((state: ShellState) => state.profileSelection)
+    const seatTwoIsPerson = useSelector((state: ShellState) => state.opponent.seatTwo === 'person')
+    const saved = useSelector((state: Record<string, unknown>) => state[settingsKey] as PlayerSettingsState<S> | undefined)
+    const controls = useSelector((state: Record<string, unknown>) => state[controlsKey] as PlayerControlsState<C> | undefined)
+    const dispatch = useDispatch()
+
+    const settings = useMemo(() => compose(saved, controls, selection, seatTwoIsPerson), [saved, controls, selection, seatTwoIsPerson])
+
+    const setSettings = useCallback(
+      (next: Partial<S>) => {
+        const { controlScheme, ...changes } = next
+        if (Object.keys(changes).length > 0) dispatch(patch(seatPlayerKey(selection, 1), changes as Partial<Omit<S, 'controlScheme'>>))
+        if (!controlScheme) return
+        for (const seat of SEATS) {
+          if (seat === 2 && !seatTwoIsPerson) continue
+          if (controlScheme[seat] !== settings.controlScheme[seat]) dispatch(setControl(seatPlayerKey(selection, seat), controlScheme[seat]))
+        }
+      },
+      [dispatch, selection, seatTwoIsPerson, settings.controlScheme]
+    )
+
+    return { settings, setSettings }
+  }
+
+  // `reducers` is what a game mounts (its GameDefinition's reducers); the two are also named for tests.
+  return { reducers: { [settingsKey]: settingsReducer, [controlsKey]: controlsReducer }, settingsReducer, controlsReducer, actions: { patch, setControl }, compose, select, useSettings }
+}

package/src/redux/appSettingsSlice.ts

@@ -0,0 +1,34 @@
+import { createSettingsSlice } from '@rific/core'
+import type { ViewRotation } from '@tastic/core'
+
+// Settings that apply to the whole pack rather than one game. A game's own rules (board, score to
+// win, controls) live in that game's own settings slice.
+export interface AppSettings {
+  // Lock Orientation: RootLayout's OrientationBridge hands it to @tastic/core's OrientationProvider
+  // (freezeWhileLocked), which freezes the one shared orientation reading for every screen, every
+  // board, dialogs and the status bar alike. Off by default: all of those just follow however the
+  // device is actually being held.
+  lockOrientation: boolean
+  // The angle the lock is holding. Written by OrientationProvider's onLockChange (recorded on lock,
+  // cleared on unlock) and handed back as lockInitialValue, so a relaunch reopens in the locked
+  // orientation instead of portrait. Never set by the UI directly; absent while unlocked.
+  lockedRotation?: ViewRotation
+  // Edge Guard's opt-in (see Providers.tsx's EdgeGuardBridge).
+  deferBottomEdgeGestures: boolean
+}
+
+export const DEFAULT_APP_SETTINGS: AppSettings = {
+  lockOrientation: false,
+  deferBottomEdgeGestures: false
+}
+
+// Merge mode, like every settings slice in the pack: REHYDRATE fills any field added since a
+// player's settings were saved from the defaults.
+const { actions, reducer } = createSettingsSlice<AppSettings, 'merge', never>('appSettings', {
+  initialState: DEFAULT_APP_SETTINGS,
+  initializeMode: 'merge',
+  fieldSetters: []
+})
+
+export const appSettingsActions = actions
+export default reducer

package/src/redux/createPackStore.ts

@@ -0,0 +1,78 @@
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import { combineReducers, configureStore, type Middleware, type Reducer } from '@reduxjs/toolkit'
+import { FLUSH, PAUSE, PERSIST, type PersistedState, persistReducer, persistStore, PURGE, REGISTER, REHYDRATE } from 'redux-persist'
+
+import type { GameDefinition, PackDefinition } from '../types'
+import lastActiveGame from './lastActiveGameSlice'
+import { createShellReducers } from './shellState'
+
+const hasError = (action: unknown): action is { error?: unknown } => typeof action === 'object' && action !== null && 'error' in action && Boolean(action.error)
+
+const errorMiddleware: Middleware = () => (next) => (action) => {
+  if (!hasError(action)) return next(action)
+  return action
+}
+
+export interface PackStoreConfig {
+  // On web every Tastic app shares one origin (games.infinitetoken.com) and so one localStorage,
+  // where AsyncStorage keeps this state under keyPrefix + 'root': the default prefix would make every
+  // app's state the same persist:root. REHYDRATE still reports key 'root'. It applies on native too.
+  // This is the only key the pack writes itself (the shared profile roster is @tastic/profile's,
+  // shared on purpose).
+  keyPrefix: string
+  // redux-persist's migrate, run on the saved store before it rehydrates (see pack.ts).
+  migrate?: (state: PersistedState, version: number) => Promise<PersistedState>
+}
+
+// What the store is built from: the pack's games (each mounts its own keys, GameDefinition.reducers,
+// and whether one is resumable decides the resume key), the pack's own keys (PackDefinition.reducers),
+// and the seat colors and appearance the shell's own keys start from.
+export type PackStoreSource = Pick<PackDefinition, 'seatColors' | 'appearance' | 'reducers'> & { games: readonly Pick<GameDefinition, 'reducers' | 'resumable'>[] }
+
+// The pack's one Redux store, persisted with redux-persist: the shell's keys (shellState.ts), the
+// pack's own, and every game's own.
+export function createPackStore(pack: PackStoreSource, { keyPrefix, migrate }: PackStoreConfig) {
+  const gameReducers: Record<string, Reducer> = Object.assign({}, ...pack.games.map((game) => game.reducers))
+  // Which play screen the player was last on, for a cold launch to resume (GameDefinition.resumable).
+  // Only in a pack with a resumable game, so a pack without one saves exactly what it did before.
+  const resumeReducers: Record<string, Reducer> = pack.games.some((game) => game.resumable) ? { lastActiveGame } : {}
+  const rootReducer = combineReducers({ ...createShellReducers(pack), ...resumeReducers, ...pack.reducers, ...gameReducers })
+
+  const persistedReducer = persistReducer(
+    {
+      key: 'root',
+      keyPrefix,
+      storage: AsyncStorage,
+      // redux-persist defaults `timeout` to 5000ms: a failsafe setTimeout scheduled on every PERSIST
+      // dispatch to force-resolve rehydrate if storage never responds. It's never cleared once
+      // rehydrate resolves normally (only guarded by an internal `_sealed` flag), so it sits as a
+      // pending timer for up to 5s after every store creation - under Jest that's a real open handle
+      // ("A worker process has failed to exit gracefully"). Disabling it (falsy timeout skips the
+      // setTimeout call entirely) is redux-persist's own documented way to opt out; AsyncStorage reads
+      // failing to ever resolve at all isn't a failure mode worth a 5s failsafe for.
+      timeout: 0,
+      // liveplay is per-round state that must never survive a relaunch (see liveplaySlice.ts).
+      blacklist: ['liveplay'],
+      migrate
+    },
+    rootReducer
+  )
+
+  const store = configureStore({
+    middleware: (getDefaultMiddleware) => {
+      const defaultMiddleware = getDefaultMiddleware({
+        immutableCheck: false,
+        serializableCheck: {
+          ignoredActions: [FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER]
+        }
+      })
+      return defaultMiddleware.concat(errorMiddleware)
+    },
+    reducer: persistedReducer
+  })
+
+  const persistor = persistStore(store)
+  return { store, persistor }
+}
+
+export type PackStore = ReturnType<typeof createPackStore>['store']

package/src/redux/gameGuideSlice.ts

@@ -0,0 +1,39 @@
+import type { Action } from 'redux'
+
+const REHYDRATE = 'persist/REHYDRATE'
+
+export interface GameGuideState {
+  versionSeen: number
+}
+
+// Which version of one game's How to Play cards this player has finished or skipped, under the
+// game's own store key. Unlike @tastic/hud's createGuideSlice, a saved store without this key reads
+// as "not seen": a game added to a pack in an update is new to everyone, so its cards show on the
+// first tap of its tile even for a player who has had the pack for months. (createGuideSlice reads
+// the missing key as a returning player and stamps it seen, which is right only for a guide that
+// ships with the app's first store.)
+export function createGameGuideSlice(mountKey: string) {
+  const MARK_SEEN = `${mountKey}/markSeen`
+  const initialState: GameGuideState = { versionSeen: 0 }
+
+  function markSeen(version: number) {
+    return { type: MARK_SEEN, payload: version }
+  }
+
+  function reducer(state: GameGuideState = initialState, action: Action & { payload?: unknown }): GameGuideState {
+    if (action.type === REHYDRATE) {
+      const persisted = (action.payload as Record<string, { versionSeen?: unknown } | undefined> | undefined)?.[mountKey]
+      return typeof persisted?.versionSeen === 'number' ? { versionSeen: persisted.versionSeen } : state
+    }
+    if (action.type === MARK_SEEN && typeof action.payload === 'number') {
+      return { versionSeen: Math.max(state.versionSeen, action.payload) }
+    }
+    return state
+  }
+
+  function selectVersionSeen(rootState: object): number {
+    return (rootState as Record<string, GameGuideState | undefined>)[mountKey]?.versionSeen ?? 0
+  }
+
+  return { actions: { markSeen }, reducer, selectVersionSeen }
+}

package/src/redux/lastActiveGameSlice.ts

@@ -0,0 +1,12 @@
+import { createSettingsSlice } from '@rific/core'
+
+// The play screen the player was last on, so a cold launch can drop them straight back onto it (see
+// GameDefinition.resumable). Read once and written only through hooks/useLastActiveGame.tsx, which
+// deliberately never subscribes to it (see that file for why). Mounted only in a pack with a
+// resumable game (createPackStore.ts). From Solitaire's own, which keeps its game ids.
+export type LastActiveGameState = { gameId: string | null }
+
+const { actions, reducer } = createSettingsSlice<LastActiveGameState>('lastActiveGame', { initialState: { gameId: null } })
+
+export const lastActiveGameActions = actions
+export default reducer

package/src/redux/liveplaySlice.ts

@@ -0,0 +1,34 @@
+import { createSettingsSlice } from '@rific/core'
+
+import type { RoundMode } from '../types'
+
+// The round a loadout committed: which game, how seat 2 was set up, and a snapshot of that game's
+// settings, so changing a setting mid-match only affects the next match. The game's play screen
+// reads its own settings back out (see useActiveRound).
+export interface ActiveRound {
+  game: string
+  mode: RoundMode
+  settings: object
+}
+
+// Transient per-round state, blacklisted from redux-persist in createPackStore.ts: none of it may
+// survive a relaunch. A crash or force-quit mid-round leaving `activelyPlaying` stuck true in
+// storage would re-enable Edge Guard (see Providers.tsx's EdgeGuardBridge) the moment the app
+// cold-launches back to Home, before any play screen could correct it. Built on @rific/core's
+// createSettingsSlice: one generated setter per field.
+export type LiveplaySliceState = {
+  // Whether a play screen has a live, unpaused round in progress right now (not merely "a play
+  // screen is mounted"). Written by the play screen as its phase changes, and reset to false on its
+  // unmount so leaving mid-round by any path can't leave it stuck true.
+  activelyPlaying: boolean
+  // null until a round has been committed (a direct link to a play screen falls back to the game's
+  // defaults and a CPU opponent).
+  activeRound: ActiveRound | null
+}
+
+const { actions, reducer } = createSettingsSlice<LiveplaySliceState>('liveplay', {
+  initialState: { activelyPlaying: false, activeRound: null }
+})
+
+export const liveplayActions = actions
+export default reducer