@tastic/shell 0.1.1 → 0.2.1

package/src/hooks/useSeatColors.ts

@@ -1,5 +1,5 @@
-import { getThirdColor, useAutoPaperTheme, useThemeSettings } from '@rific/auto-paper'
-import { avoidSeatColorClash, profileSeatColor } from '@tastic/profile'
+import { getThirdColor, type ThemeSettings, useAutoPaperTheme, useThemeSettings } from '@rific/auto-paper'
+import { avoidSeatColorClash, type Profile, profileSeatColor } from '@tastic/profile'
 import { useFocusEffect } from 'expo-router'
 import { useCallback, useEffect, useRef } from 'react'
 import { useDispatch, useSelector } from 'react-redux'
@@ -11,19 +11,34 @@ 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.
+type ThemeColors = Pick<ThemeSettings, 'color' | 'harmony'>
+
+// Whether a theme already has the colors (and harmony) a seat change would set: skipped, so a re-run
+// with nothing new writes nothing.
+function sameTheme(current: ThemeColors, next: Partial<ThemeColors>): boolean {
+  const a = current.color
+  const b = next.color
+  const sameColor = typeof a === 'string' || typeof b === 'string' ? typeof a === typeof b && String(a).toLowerCase() === String(b).toLowerCase() : !!a && !!b && a.primary.toLowerCase() === b.primary.toLowerCase() && a.secondary.toLowerCase() === b.secondary.toLowerCase()
+  return sameColor && (next.harmony === undefined || next.harmony === current.harmony)
+}
+
+// Both seats' live colors 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.
+//
+// The theme follows the seats. By default it's a triad of the two seat colors, and each seat's live
+// color is read back from it (its primary and secondary). A pack with its own seatTheme (a muted seed
+// from seat 1's color, say) gets that instead, applied again when dark mode flips, and each seat's
+// color comes from where it's remembered (the seatColors key), since the theme no longer holds the
+// raw colors: seat 2 keeps its own color rather than the harmony's.
 export function useSeatColors(p2IsHuman: boolean) {
-  const { colors: themeColors } = useAutoPaperTheme()
-  const { set: setThemeColor } = useThemeSettings()
-  const p1Color = themeColors.primary
-  const p2Color = themeColors.secondary
+  const { dark, colors: themeColors } = useAutoPaperTheme()
+  const { settings: themeSettings, set: setThemeColor } = useThemeSettings()
   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 { seatColors, seatTheme } = usePack()
   const seatDefaultColors = [seatColors[1], seatColors[2]] as const
 
   // Typed explicitly because @tastic/profile's action creators return a plain `{ payload, type }`
@@ -44,6 +59,20 @@ export function useSeatColors(p2IsHuman: boolean) {
   const p1Profile = profiles.find((p) => p.id === lastSelected[1]) ?? null
   const p2Profile = p2IsHuman ? (profiles.find((p) => p.id === lastSelected[2]) ?? null) : null
 
+  // Where each seat's color is remembered: a profile's pick in this pack (or its own color), the CPU's,
+  // or a guest's. Seat 2 steps aside when both seats land on one color.
+  const rememberedColors = (p1Prof: Profile | null, p2Prof: Profile | null, picks: typeof profileColors, guest: typeof guestColors, cpu: string) => {
+    const p1 = p1Prof ? profileSeatColor(p1Prof, picks) : guest[1]
+    const p2 = avoidSeatColorClash(p1, p2Prof ? profileSeatColor(p2Prof, picks) : p2IsHuman ? guest[2] : cpu, seatDefaultColors)
+    return { p1, p2 }
+  }
+  const remembered = rememberedColors(p1Profile, p2Profile, profileColors, guestColors, cpuColor)
+  const p1Color = seatTheme ? remembered.p1 : themeColors.primary
+  const p2Color = seatTheme ? remembered.p2 : themeColors.secondary
+
+  // The theme two seat colors make: the pack's own, or the triad.
+  const themeFor = useCallback((p1: string, p2: string): Partial<ThemeColors> => (seatTheme ? seatTheme({ 1: p1, 2: p2 }, dark) : { color: { primary: p1, secondary: p2, tertiary: getThirdColor(p1, p2) } }), [seatTheme, dark])
+
   // 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).
@@ -52,6 +81,7 @@ export function useSeatColors(p2IsHuman: boolean) {
   const guestColorsRef = useRef(guestColors)
   const cpuColorRef = useRef(cpuColor)
   const profileColorsRef = useRef(profileColors)
+  const themeForRef = useRef(themeFor)
   useEffect(() => {
     p1ProfileRef.current = p1Profile
   }, [p1Profile])
@@ -67,19 +97,22 @@ export function useSeatColors(p2IsHuman: boolean) {
   useEffect(() => {
     profileColorsRef.current = profileColors
   }, [profileColors])
+  useEffect(() => {
+    themeForRef.current = themeFor
+  }, [themeFor])
 
   // 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.
+  // With a seatTheme, dark mode flipping is a reason too: the theme it makes depends on it.
   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) } })
+    const next = themeFor(remembered.p1, remembered.p2)
+    if (sameTheme(themeSettings, next)) return
+    setThemeColor(next)
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [lastSelected[1], lastSelected[2], p2IsHuman, guestColors, cpuColor, profileColors, profiles.length])
+  }, [lastSelected[1], lastSelected[2], p2IsHuman, guestColors, cpuColor, profileColors, profiles.length, dark])
 
   // 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
@@ -89,14 +122,8 @@ export function useSeatColors(p2IsHuman: boolean) {
   // 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) } })
+      const next = rememberedColors(p1ProfileRef.current, p2ProfileRef.current, profileColorsRef.current, guestColorsRef.current, cpuColorRef.current)
+      setThemeColor(themeForRef.current(next.p1, next.p2))
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [lastSelected[1], lastSelected[2], p2IsHuman, setThemeColor])
   )
@@ -127,21 +154,21 @@ export function useSeatColors(p2IsHuman: boolean) {
     (hex: string) => {
       const swapped = hex.toLowerCase() === p2Color.toLowerCase()
       const nextP2 = swapped ? p1Color : p2Color
-      setThemeColor({ color: { primary: hex, secondary: nextP2, tertiary: getThirdColor(hex, nextP2) } })
+      setThemeColor(themeFor(hex, nextP2))
       persistSeatColor(1, hex)
       if (swapped) persistSeatColor(2, nextP2)
     },
-    [setThemeColor, p1Color, p2Color, persistSeatColor]
+    [setThemeColor, themeFor, 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) } })
+      setThemeColor(themeFor(nextP1, hex))
       persistSeatColor(2, hex)
       if (swapped) persistSeatColor(1, nextP1)
     },
-    [setThemeColor, p1Color, p2Color, persistSeatColor]
+    [setThemeColor, themeFor, p1Color, p2Color, persistSeatColor]
   )
 
   return { p1Color, p2Color, handleP1ColorChange, handleP2ColorChange }

package/src/index.ts

@@ -2,7 +2,7 @@
 // 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'
+export { type FeedbackSounds, type GameDefinition, type GameGuide, type GameIconProps, type GameLoadout, type GamePreviewProps, type GameRulesProps, GUEST_PLAYER_ID, type GuidelessGameDefinition, type HeroTitleProps, humanSeatsFor, type LoadoutOptionsProps, type PackDefinition, type PackGameDefinition, type PackGuide, type PackStatsReset, type PackStatsSectionsProps, type PackStatsTab, type PickerAlign, type RoundMode, roundModeFor, type Seat, type SeatControlLook, type SeatTwo, seatTwoFor, type StackScreenOptions } 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'

package/src/redux/createPackStore.ts

@@ -2,7 +2,7 @@ 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 type { PackDefinition, PackGameDefinition } from '../types'
 import lastActiveGame from './lastActiveGameSlice'
 import { createShellReducers } from './shellState'
 
@@ -22,16 +22,25 @@ export interface PackStoreConfig {
   keyPrefix: string
   // redux-persist's migrate, run on the saved store before it rehydrates (see pack.ts).
   migrate?: (state: PersistedState, version: number) => Promise<PersistedState>
+  // Keys left out of the root entry, beside liveplay: keys that persist themselves (a key whose reducer
+  // is its own persistReducer, saving each game's board to an entry of its own), so they aren't written
+  // into the root entry too.
+  blacklist?: readonly string[]
+  // State paths the dev serializability check skips (keys too big to walk on every action, such as
+  // saved boards).
+  serializableIgnoredPaths?: readonly string[]
+  // The pack's own middleware, after the shell's.
+  middleware?: readonly Middleware[]
 }
 
 // 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'>[] }
+export type PackStoreSource = Pick<PackDefinition, 'seatColors' | 'appearance' | 'seatTheme' | 'reducers'> & { games: readonly Pick<PackGameDefinition, '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) {
+export function createPackStore(pack: PackStoreSource, { keyPrefix, migrate, blacklist = [], serializableIgnoredPaths = [], middleware = [] }: 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.
@@ -52,7 +61,7 @@ export function createPackStore(pack: PackStoreSource, { keyPrefix, migrate }: P
       // 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'],
+      blacklist: ['liveplay', ...blacklist],
       migrate
     },
     rootReducer
@@ -63,10 +72,11 @@ export function createPackStore(pack: PackStoreSource, { keyPrefix, migrate }: P
       const defaultMiddleware = getDefaultMiddleware({
         immutableCheck: false,
         serializableCheck: {
-          ignoredActions: [FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER]
+          ignoredActions: [FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER],
+          ignoredPaths: [...serializableIgnoredPaths]
         }
       })
-      return defaultMiddleware.concat(errorMiddleware)
+      return defaultMiddleware.concat(errorMiddleware, ...middleware)
     },
     reducer: persistedReducer
   })

package/src/redux/shellState.ts

@@ -21,7 +21,7 @@ const appSoundReducer = (state: SoundSettings = initialSoundSettings, action: {
 
 // The store keys every pack has, whatever its games, built from the pack's own seat colors and
 // appearance. Each game adds its own keys beside these (see GameDefinition.reducers).
-export function createShellReducers({ seatColors, appearance = 'system' }: Pick<PackDefinition, 'seatColors' | 'appearance'>) {
+export function createShellReducers({ seatColors, appearance = 'system', seatTheme }: Pick<PackDefinition, 'seatColors' | 'appearance' | 'seatTheme'>) {
   return {
     // Explicit primary/secondary triad (rather than a single seed expanded via harmony) so the pack's
     // identity is pinned exactly instead of drifting with whatever hue math a harmony offset would
@@ -30,7 +30,9 @@ export function createShellReducers({ seatColors, appearance = 'system' }: Pick<
     // derived, not picked, via getThirdColor: the hue maximally distant from both (see
     // @rific/auto-paper's README "Explicit triad" section). The appearance is the pack's ('system',
     // createThemeReducer's own default, when it sets none).
-    theme: createThemeReducer({ appearance, color: { primary: seatColors[1], secondary: seatColors[2], tertiary: getThirdColor(seatColors[1], seatColors[2]) } }),
+    // A pack with its own seatTheme starts from what seat 1's default color makes of it instead (dark
+    // only when the pack's appearance is; hooks/useSeatColors.ts re-applies it with the live mode).
+    theme: createThemeReducer(seatTheme ? { appearance, ...seatTheme(seatColors, appearance === 'dark') } : { appearance, color: { primary: seatColors[1], secondary: seatColors[2], tertiary: getThirdColor(seatColors[1], seatColors[2]) } }),
     haptic: hapticReducer,
     sound: appSoundReducer,
     // @rific/core's Keep Awake setting (see Providers.tsx's KeepAwakeBridge), under the namespace its

package/src/routes.ts

@@ -0,0 +1,10 @@
+import type { Href } from 'expo-router'
+
+// The shell's own routes, the ones every pack's src/app/ has (play/[game], loadout/[game], stats,
+// profiles). An app with expo-router's typed routes type-checks this source against its own route tree
+// (its tsc reads the package's src/), and an app moving onto the shell (Solitaire) has these routes only
+// part of the way through. So they're handed to expo-router as plain Hrefs, not checked against it.
+export const playHref = (game: string) => ({ pathname: '/play/[game]', params: { game } }) as unknown as Href
+export const loadoutHref = (game: string) => ({ pathname: '/loadout/[game]', params: { game } }) as unknown as Href
+export const STATS_HREF = '/stats' as unknown as Href
+export const PROFILES_HREF = '/profiles' as unknown as Href

package/src/screens/GameRoute.tsx

@@ -1,9 +1,11 @@
 import { Redirect, useLocalSearchParams } from 'expo-router'
 import { useEffect } from 'react'
+import { AppState } from 'react-native'
 
 import { useLastActiveGame } from '../hooks/useLastActiveGame'
 import { usePackGame } from '../PackContext'
-import type { GameDefinition } from '../types'
+import { playHref } from '../routes'
+import type { PackGameDefinition } from '../types'
 import { type LoadoutGame, LoadoutScreen } from './LoadoutScreen'
 
 // The game routes, loadout/[game] and play/[game]: a game's loadout and its play screen, by id. An id
@@ -17,11 +19,11 @@ export function LoadoutRoute() {
   const game = usePackGame(id)
   if (!game) return <Redirect href='/' />
   // A game with nothing to set up has no loadout (GameDefinition.useLoadout): a link to one plays it.
-  if (!hasLoadout(game)) return <Redirect href={{ pathname: '/play/[game]', params: { game: game.id } }} />
+  if (!hasLoadout(game)) return <Redirect href={playHref(game.id)} />
   return <LoadoutScreen key={game.id} game={game} />
 }
 
-function hasLoadout(game: GameDefinition): game is LoadoutGame {
+function hasLoadout(game: PackGameDefinition): game is LoadoutGame {
   return !!game.useLoadout
 }
 
@@ -35,14 +37,20 @@ export function PlayRoute() {
 }
 
 // A resumable game's play screen (GameDefinition.resumable) is where a cold launch comes back to:
-// remembered as it mounts, and forgotten when it unmounts, which is the player backing out of it
-// (its own back, hardware back or a browser back). Backgrounding the app leaves the screen mounted,
-// so it stays remembered. Runs once per play screen: the context's functions never change.
+// remembered as it mounts, and forgotten when the player backs out of it (its own back, hardware back
+// or a browser back), which unmounts it while the app is in use. Backgrounding the app leaves the
+// screen mounted, so it stays remembered. An unmount with the app NOT active keeps it too: when iOS
+// terminates an app it hasn't suspended yet (swiped away from the app switcher soon after leaving
+// it), React Native's renderer stops every surface (RCTSurfacePresenter's will-terminate handler),
+// which unmounts the whole tree, and clearing then sent every such relaunch to Home. Runs once per
+// play screen: the context's functions never change.
 function useResumePoint(gameId: string | null) {
   const { setLastActiveGame, clearLastActiveGame } = useLastActiveGame()
   useEffect(() => {
     if (!gameId) return
     setLastActiveGame(gameId)
-    return clearLastActiveGame
+    return () => {
+      if (AppState.currentState === 'active') clearLastActiveGame()
+    }
   }, [gameId, setLastActiveGame, clearLastActiveGame])
 }