@tastic/shell 0.1.1 → 0.2.0

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

@@ -3,7 +3,8 @@ import { useEffect } from 'react'
 
 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 +18,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
 }
 

package/src/screens/HomeScreen.tsx

@@ -1,12 +1,12 @@
-import { defaultColors, useAutoPaperTheme } from '@rific/auto-paper'
+import { defaultColors, FadingScrollView, useAutoPaperTheme } from '@rific/auto-paper'
 import { IconButton, Pressable } from '@rific/feedback-press'
 import { FakeLandscapeView, useRotation } from '@tastic/core'
-import { PressAwayOverlay, usePopoverHost, useWellColors, WELL_SHADOW } from '@tastic/hud'
-import { type Profile, ProfilePicker } from '@tastic/profile'
+import { PressAwayOverlay, usePopoverHost, useWellColors, WELL_SHADOW } from '@tastic/hud/chrome'
+import { getProfilePickerContentSize, type Profile, ProfilePicker, type ProfilePickerColorSection } from '@tastic/profile'
 import { Redirect, router, useIsFocused } from 'expo-router'
-import { useCallback, useEffect, useState } from 'react'
-import { AppState, type AppStateStatus, ScrollView, StyleSheet, View } from 'react-native'
-import { Icon, Text } from 'react-native-paper'
+import { type ReactNode, useCallback, useEffect, useMemo, useState } from 'react'
+import { AppState, type AppStateStatus, StyleSheet, View } from 'react-native'
+import { Icon, Portal, Text } from 'react-native-paper'
 
 import { useGameGuide } from '../components/GuideHost'
 import { SettingsDialog } from '../components/SettingsDialog'
@@ -16,7 +16,8 @@ import { useOpponent } from '../hooks/useOpponent'
 import { useProfiles } from '../hooks/useProfiles'
 import { useSeatColors } from '../hooks/useSeatColors'
 import { usePack } from '../PackContext'
-import type { GameDefinition } from '../types'
+import { loadoutHref, playHref, PROFILES_HREF, STATS_HREF } from '../routes'
+import type { PackGameDefinition } from '../types'
 import { HOME_GRID_GAP, HOME_LEFT_PANE_PICKER_GAP, HOME_TILE_PADDING, HOME_TOP_BAND, HOME_WIDE_PANE_GAP, PREVIEW_ASPECT, ROW_PREVIEW_WIDTH, useHomeLayout } from './homeLayout'
 
 // Home: who's playing (seat 1, the same seat 1 every loadout starts with), then every game in the
@@ -26,10 +27,13 @@ import { HOME_GRID_GAP, HOME_LEFT_PANE_PICKER_GAP, HOME_TILE_PADDING, HOME_TOP_B
 // picked. Seat 2 is chosen in the loadout, from seat 2's own button.
 //
 // A cold launch that finds the player left the app inside a resumable game's play screen
-// (GameDefinition.resumable) goes straight back there instead, before the menu ever paints.
+// (GameDefinition.resumable) goes straight back there instead, before the menu ever paints. The
+// pack's own How to Play (PackDefinition.guide) shows by itself on a first launch, held back while
+// that launch is about to drop into a game: it must never open over a game in progress.
 export function HomeScreen() {
   const pack = usePack()
   const { consumeResumeGame } = useLastActiveGame()
+  const { autoShowPack } = useGameGuide()
   // A one-shot cold-launch decision, read exactly once at this instance's mount (see
   // hooks/useLastActiveGame.tsx), never a live value this screen re-renders from. Reading it live made
   // every Home in the stack swap its whole menu for a Redirect while a game was on top and rebuild it
@@ -39,7 +43,10 @@ export function HomeScreen() {
     const id = consumeResumeGame()
     return pack.games.find((g) => g.id === id && g.resumable) ?? null
   })
-  if (resumeGame) return <Redirect href={{ pathname: '/play/[game]', params: { game: resumeGame.id } }} />
+  useEffect(() => {
+    if (!resumeGame) autoShowPack()
+  }, [resumeGame, autoShowPack])
+  if (resumeGame) return <Redirect href={playHref(resumeGame.id)} />
   return <HomeMenu />
 }
 
@@ -48,9 +55,11 @@ function HomeMenu() {
   const rotation = useRotation()
   const layout = useHomeLayout()
   const { insets } = layout
-  const { dark } = useAutoPaperTheme()
-  const { openFirstTime, openFor } = useGameGuide()
+  const { dark, colors } = useAutoPaperTheme()
+  const { openFirstTime, openFor, openPack } = useGameGuide()
   const [settingsOpen, setSettingsOpen] = useState(false)
+  // The game whose rules sheet (GameDefinition.Rules) is open.
+  const [rulesGame, setRulesGame] = useState<PackGameDefinition | null>(null)
   const isFocused = useIsFocused()
   const [appState, setAppState] = useState<AppStateStatus>(AppState.currentState)
   useEffect(() => {
@@ -84,82 +93,135 @@ function HomeMenu() {
     const id = requestAnimationFrame(() => setPreviewsRevealed(true))
     return () => cancelAnimationFrame(id)
   }, [tiled])
-  // A popover is placed once, as it opens. Switching between the column and the two panes unmounts
-  // the very button it hangs off, which would leave the press-away overlay up with nothing to dismiss,
-  // so the switch closes it.
+  // A popover is placed once, as it opens, from measurements of the frame it opens in. Turning the
+  // phone (or any resize) moves the frame under it, and switching between the column and the two panes
+  // unmounts the very button it hangs off, which would leave the press-away overlay up with nothing to
+  // dismiss. So every layout change closes it.
   const closePicker = pickerHost.close
   useEffect(() => {
     closePicker()
-  }, [isWide, closePicker])
+  }, [isWide, rotation, layout.windowWidth, layout.windowHeight, closePicker])
 
-  const bg = dark ? '#000000' : '#FFFFFF'
-  const fg = dark ? '#FFFFFF' : '#000000'
+  // Over the pack's Backdrop Home draws nothing of its own behind the menu.
+  const bg = pack.Backdrop ? 'transparent' : dark ? '#000000' : '#FFFFFF'
+  const fg = pack.foreground ?? (dark ? '#FFFFFF' : '#000000')
+  // Seat 1's color as the pack draws profile colors (PackDefinition.previewColor), and the button on
+  // the theme's surface over a backdrop, so neither washes out on it.
+  const { previewColor } = pack
+  const p1Drawn = previewColor ? previewColor(p1Color, dark) : p1Color
+  const triggerStyle = useMemo(() => (pack.Backdrop ? [styles.pill, { backgroundColor: colors.surface }] : undefined), [pack.Backdrop, colors.surface])
 
   // A game with nothing to set up (no useLoadout) opens straight to its play screen.
-  const openGame = useCallback((game: GameDefinition) => openFirstTime(game.id, () => router.push(game.useLoadout ? { pathname: '/loadout/[game]', params: { game: game.id } } : { pathname: '/play/[game]', params: { game: game.id } })), [openFirstTime])
+  const openGame = useCallback((game: PackGameDefinition) => openFirstTime(game.id, () => router.push(game.useLoadout ? loadoutHref(game.id) : playHref(game.id))), [openFirstTime])
+
+  // A tile's rules button: the game's rules sheet where it has one, else its How to Play cards.
+  const openRules = useCallback((game: PackGameDefinition) => (game.Rules ? setRulesGame(game) : openFor(game.id)), [openFor])
+
+  const colorSection: ProfilePickerColorSection = { value: p1Color, onChange: handleP1ColorChange, swatches: defaultColors, caption: selectedProfile ? pack.colorCaption : undefined, previewValue: previewColor ? (hex: string) => previewColor(hex, dark) : undefined }
+  // The pack's own placement for the menu (PackDefinition.usePickerAlign), sized from the same rows
+  // and color page the picker draws; hud's own without one. The pack never changes while it runs.
+  const usePickerAlign = pack.usePickerAlign ?? noPickerAlign
+  const pickerSize = getProfilePickerContentSize(profiles.length, true, colorSection)
+  const pickerAlign = usePickerAlign(pickerHost.openId === `${SEAT_ONE_PICKER}-profile`, pickerSize.width, pickerSize.height)
+
+  const picker = <ProfilePicker idPrefix={SEAT_ONE_PICKER} host={pickerHost} profiles={profiles} selectedId={lastSelected[1]} color={p1Drawn} dark={dark} guestLabel={pack.guestLabel ?? 'P1'} nullLabel={pack.nullLabel} onSelect={(profile: Profile | null) => selectProfile(1, profile?.id ?? null)} onManage={() => router.push(PROFILES_HREF)} colorSection={colorSection} alignOverride={pickerAlign} triggerStyle={triggerStyle} />
 
-  const picker = <ProfilePicker idPrefix='home-p1' host={pickerHost} profiles={profiles} selectedId={lastSelected[1]} color={p1Color} dark={dark} guestLabel='P1' onSelect={(profile: Profile | null) => selectProfile(1, profile?.id ?? null)} onManage={() => router.push('/profiles')} colorSection={{ value: p1Color, onChange: handleP1ColorChange, swatches: defaultColors, caption: selectedProfile ? pack.colorCaption : undefined }} />
+  // Closes seat 1's menu on a press anywhere but the menu and its button. Where it's mounted matters on
+  // a phone, where zIndex only orders the children of one parent: the menu lives inside the scroller in
+  // the upright layout, so the overlay goes there too, under the button's wrapper (raised while the menu
+  // is open) and over the rows. As the frame's first child it sat under the whole scroller, and a press
+  // on a row played the game. In the wide layout the left pane is itself the frame's child, so the
+  // overlay stays there, under the pane and over the grid.
+  const pressAway = <PressAwayOverlay active={pickerHost.openId !== null} onPress={pickerHost.close} style={styles.pressAway} />
+  const RulesSheet = rulesGame?.Rules
 
   return (
     <View style={[styles.container, { backgroundColor: bg }]}>
       {/* Reads correctly however the phone is held: see @tastic/core's FakeLandscapeView. The
-      Settings dialog stays outside it: it renders through a Portal, turned by its own `rotation`. */}
+      Settings dialog stays outside it: it renders through a Portal, turned by its own `rotation`. A
+      game's rules sheet renders inside it instead (see RulesHost). */}
       <FakeLandscapeView style={styles.rotatable}>
-        <PressAwayOverlay active={pickerHost.openId !== null} onPress={pickerHost.close} />
-        {isWide ? (
-          <>
-            {/* Right pane: the game grid, scrolling on its own beside the left pane. The scroller runs
+        <RulesHost enabled={pack.games.some((game) => game.Rules)}>
+          {isWide ? (
+            <>
+              {pressAway}
+              {/* Right pane: the game grid, scrolling on its own beside the left pane. The scroller runs
             to the frame's right edge and the cog's gutter is its content's padding, so a web scrollbar
-            sits at the window's edge. */}
-            <ScrollView style={[styles.wideRightPane, { left: layout.paddingLeft + layout.leftPaneWidth + HOME_WIDE_PANE_GAP }]} contentContainerStyle={{ paddingTop: 16 + insets.top, paddingBottom: 16 + insets.bottom, paddingRight: layout.paddingRight }}>
-              <View style={[styles.grid, { width: layout.rightPaneWidth }]}>
-                {pack.games.map((game) => (
-                  <GameTile key={game.id} game={game} width={layout.tileWidth} previewWidth={layout.previewWidth} previewRevealed={previewsRevealed} dark={dark} p1Color={p1Color} p2Color={p2Color} onPress={() => openGame(game)} onRules={() => openFor(game.id)} />
-                ))}
-              </View>
-            </ScrollView>
-            {/* Left pane: the hero, then seat 1's button, centred as one group under the corner
+            sits at the window's edge. Both scrollers fade out at an edge while there is more past it
+            (auto-paper's FadingScrollView, a mask, so whatever is behind shows through). */}
+              <FadingScrollView style={[styles.wideRightPane, { left: layout.paddingLeft + layout.leftPaneWidth + HOME_WIDE_PANE_GAP }]} contentContainerStyle={{ paddingTop: 16 + insets.top, paddingBottom: 16 + insets.bottom, paddingRight: layout.paddingRight }}>
+                <View style={[styles.grid, { width: layout.rightPaneWidth }]}>
+                  {pack.games.map((game) => (
+                    <GameTile key={game.id} game={game} width={layout.tileWidth} previewWidth={layout.previewWidth} previewRevealed={previewsRevealed} dark={dark} p1Color={p1Color} p2Color={p2Color} onPress={() => openGame(game)} onRules={hasRules(game) ? () => openRules(game) : undefined} />
+                  ))}
+                </View>
+              </FadingScrollView>
+              {/* Left pane: the hero, then seat 1's button, centred as one group under the corner
             buttons' band. A later sibling of the grid, lifted while seat 1's menu is open so the menu
             paints over the tiles. box-none: only its controls claim taps. */}
-            <View style={[styles.wideLeftPane, { left: layout.paddingLeft, width: layout.leftPaneWidth, paddingTop: HOME_TOP_BAND + insets.top, paddingBottom: 16 + insets.bottom }, pickerHost.openId !== null && styles.pickerOpen]}>
-              <pack.HeroTitle words={pack.wordmark} color={fg} p1Color={p1Color} p2Color={p2Color} active={heroActive} fit={layout.heroFit} />
-              <View style={styles.widePicker}>{picker}</View>
-            </View>
-          </>
-        ) : (
-          <ScrollView style={styles.scroll} contentContainerStyle={[styles.content, { paddingTop: 56 + insets.top, paddingBottom: 24 + insets.bottom, paddingLeft: 16 + insets.left, paddingRight: 16 + insets.right }]}>
-            <pack.HeroTitle words={pack.wordmark} color={fg} p1Color={p1Color} p2Color={p2Color} active={heroActive} />
+              <View style={[styles.wideLeftPane, { left: layout.paddingLeft, width: layout.leftPaneWidth, paddingTop: HOME_TOP_BAND + insets.top, paddingBottom: 16 + insets.bottom }, pickerHost.openId !== null && styles.pickerOpen]}>
+                <pack.HeroTitle words={pack.wordmark} color={fg} p1Color={p1Color} p2Color={p2Color} active={heroActive} fit={layout.heroFit} />
+                <View style={styles.widePicker}>{picker}</View>
+              </View>
+            </>
+          ) : (
+            <FadingScrollView style={styles.scroll} contentContainerStyle={[styles.content, { paddingTop: 56 + insets.top, paddingBottom: 24 + insets.bottom, paddingLeft: 16 + insets.left, paddingRight: 16 + insets.right }]}>
+              {pressAway}
+              <pack.HeroTitle words={pack.wordmark} color={fg} p1Color={p1Color} p2Color={p2Color} active={heroActive} />
 
-            {/* Who's playing: seat 1's button, the same one each loadout starts with. Lifted above the
+              {/* Who's playing: seat 1's button, the same one each loadout starts with. Lifted above the
             tiles while its menu is open, so the menu paints over them. */}
-            <View style={[styles.picker, pickerHost.openId !== null && styles.pickerOpen]}>{picker}</View>
+              <View style={[styles.picker, pickerHost.openId !== null && styles.pickerOpen]}>{picker}</View>
 
-            <View style={styles.list}>
-              {pack.games.map((game) => (
-                <GameRow key={game.id} game={game} dark={dark} p1Color={p1Color} p2Color={p2Color} previewRevealed={previewsRevealed} onPress={() => openGame(game)} onRules={() => openFor(game.id)} />
-              ))}
-            </View>
-          </ScrollView>
-        )}
+              <View style={styles.list}>
+                {pack.games.map((game) => (
+                  <GameRow key={game.id} game={game} dark={dark} p1Color={p1Color} p2Color={p2Color} previewRevealed={previewsRevealed} onPress={() => openGame(game)} onRules={hasRules(game) ? () => openRules(game) : undefined} />
+                ))}
+              </View>
+            </FadingScrollView>
+          )}
 
-        <IconButton icon='trophy' iconColor={fg} size={24} style={[styles.corner, { top: 8 + insets.top, left: 8 + insets.left }]} onPress={() => router.push('/stats')} accessibilityLabel='Stats & Achievements' />
-        <IconButton icon='cog' iconColor={fg} size={24} style={[styles.corner, { top: 8 + insets.top, right: 8 + insets.right }]} onPress={() => setSettingsOpen(true)} accessibilityLabel='Settings' />
+          <IconButton icon='trophy' iconColor={fg} size={24} style={[styles.corner, { top: 8 + insets.top, left: 8 + insets.left }]} onPress={() => router.push(STATS_HREF)} accessibilityLabel='Stats & Achievements' />
+          <IconButton icon='cog' iconColor={fg} size={24} style={[styles.corner, { top: 8 + insets.top, right: 8 + insets.right }]} onPress={() => setSettingsOpen(true)} accessibilityLabel='Settings' />
+          {RulesSheet && <RulesSheet visible onDismiss={() => setRulesGame(null)} />}
+        </RulesHost>
       </FakeLandscapeView>
 
-      <SettingsDialog visible={settingsOpen} onDismiss={() => setSettingsOpen(false)} rotation={rotation} />
+      {/* Home's How to Play row replays the pack's own cards (PackDefinition.guide); without them each
+      tile's rules button shows its game's. */}
+      <SettingsDialog visible={settingsOpen} onDismiss={() => setSettingsOpen(false)} rotation={rotation} onShowHowToPlay={pack.guide ? openPack : undefined} />
     </View>
   )
 }
 
+// Seat 1's button's popover id prefix (its menu is `${SEAT_ONE_PICKER}-profile`).
+const SEAT_ONE_PICKER = 'home-p1'
+
+// No placement of the pack's own: hud places the menu itself.
+const noPickerAlign = () => undefined
+
+// Whether a tile has a rules button: a rules sheet or How to Play cards to show.
+function hasRules(game: PackGameDefinition): boolean {
+  return !!(game.Rules || game.guide)
+}
+
+// A game's rules sheet (GameDefinition.Rules) portals into a Paper host inside Home's turned frame, so
+// it's turned with the frame and laid out against it (a sheet laid out against the upright window ran
+// off a phone held sideways). Only in a pack with one: a pack without keeps the frame as it was.
+function RulesHost({ enabled, children }: { enabled: boolean; children: ReactNode }) {
+  return enabled ? <Portal.Host>{children}</Portal.Host> : <>{children}</>
+}
+
 interface GameRowProps {
-  game: GameDefinition
+  game: PackGameDefinition
   dark: boolean
   p1Color: string
   p2Color: string
   // Whether Home has painted once, so a preview may draw (see previewsRevealed).
   previewRevealed: boolean
   onPress: () => void
-  onRules: () => void
+  // Undefined for a game with no rules sheet and no How to Play cards: no rules button.
+  onRules?: () => void
 }
 
 // One game on its own well: its icon at app-icon size (the art was drawn as an app icon), or its
@@ -173,13 +235,7 @@ function GameRow({ game, dark, p1Color, p2Color, previewRevealed, onPress, onRul
     // inside a button is invalid on the web.
     <View>
       <Pressable onPress={onPress} style={[styles.row, { backgroundColor: well.bg }]} accessibilityRole='button' accessibilityLabel={game.title}>
-        {game.Preview ? (
-          <PreviewBox game={game} width={ROW_PREVIEW_WIDTH} revealed={previewRevealed} dark={dark} p1Color={p1Color} p2Color={p2Color} />
-        ) : (
-          <View style={[styles.rowIcon, { backgroundColor: dark ? ICON_DARK_BG : ICON_LIGHT_BG }]}>
-            <GameIcon size={ROW_ICON_SIZE} p1Color={p1Color} p2Color={p2Color} dark={dark} />
-          </View>
-        )}
+        {game.Preview ? <PreviewBox game={game} width={ROW_PREVIEW_WIDTH} revealed={previewRevealed} dark={dark} p1Color={p1Color} p2Color={p2Color} /> : <View style={[styles.rowIcon, { backgroundColor: dark ? ICON_DARK_BG : ICON_LIGHT_BG }]}>{GameIcon && <GameIcon size={ROW_ICON_SIZE} p1Color={p1Color} p2Color={p2Color} dark={dark} />}</View>}
         <View style={styles.rowText}>
           <Text variant='titleLarge' style={[styles.rowTitle, { color: well.fg }]} numberOfLines={1}>
             {game.title}
@@ -189,9 +245,11 @@ function GameRow({ game, dark, p1Color, p2Color, previewRevealed, onPress, onRul
           </Text>
         </View>
       </Pressable>
-      <Pressable onPress={onRules} style={styles.rulesButton} hitSlop={12} accessibilityRole='button' accessibilityLabel={`${game.title} rules`}>
-        <Icon source='information-outline' size={22} color={well.fgMuted} />
-      </Pressable>
+      {onRules && (
+        <Pressable onPress={onRules} style={styles.rulesButton} hitSlop={12} accessibilityRole='button' accessibilityLabel={`${game.title} rules`}>
+          <Icon source='information-outline' size={22} color={well.fgMuted} />
+        </Pressable>
+      )}
     </View>
   )
 }
@@ -217,15 +275,17 @@ function GameTile({ game, width, previewWidth, dark, p1Color, p2Color, previewRe
           {game.blurb}
         </Text>
       </Pressable>
-      <Pressable onPress={onRules} style={styles.tileRulesButton} hitSlop={12} accessibilityRole='button' accessibilityLabel={`${game.title} rules`}>
-        <Icon source='information-outline' size={20} color='#FFFFFF' />
-      </Pressable>
+      {onRules && (
+        <Pressable onPress={onRules} style={styles.tileRulesButton} hitSlop={12} accessibilityRole='button' accessibilityLabel={`${game.title} rules`}>
+          <Icon source='information-outline' size={20} color='#FFFFFF' />
+        </Pressable>
+      )}
     </View>
   )
 }
 
 interface PreviewBoxProps {
-  game: GameDefinition
+  game: PackGameDefinition
   width: number
   revealed: boolean
   dark: boolean
@@ -241,13 +301,13 @@ function PreviewBox({ game, width, revealed, dark, p1Color, p2Color }: PreviewBo
   const iconSize = Math.min(height, ROW_ICON_SIZE)
   return (
     <View style={[styles.preview, { width, height, backgroundColor: dark ? ICON_DARK_BG : ICON_LIGHT_BG }]}>
-      {Preview ? (
-        revealed && <Preview width={width} height={height} p1Color={p1Color} p2Color={p2Color} dark={dark} />
-      ) : (
-        <View style={[styles.previewIcon, { width: iconSize, height: iconSize, borderRadius: iconSize * 0.22 }]}>
-          <GameIcon size={iconSize} p1Color={p1Color} p2Color={p2Color} dark={dark} />
-        </View>
-      )}
+      {Preview
+        ? revealed && <Preview width={width} height={height} p1Color={p1Color} p2Color={p2Color} dark={dark} />
+        : GameIcon && (
+            <View style={[styles.previewIcon, { width: iconSize, height: iconSize, borderRadius: iconSize * 0.22 }]}>
+              <GameIcon size={iconSize} p1Color={p1Color} p2Color={p2Color} dark={dark} />
+            </View>
+          )}
     </View>
   )
 }
@@ -289,6 +349,15 @@ const styles = StyleSheet.create({
   pickerOpen: {
     zIndex: 100
   },
+  // Seat 1's button on the theme's surface (over a backdrop), the same pill as the tiles' wells.
+  pill: {
+    borderRadius: 999
+  },
+  // Over the rows (and, wide, the grid), whose own stacking is unset, so a press on them reaches it on
+  // the web too, and under the raised button and left pane, so the menu's rows stay pressable.
+  pressAway: {
+    zIndex: 5
+  },
   // The preview's own rounding, clipping whatever it draws to the box.
   preview: {
     alignItems: 'center',