@tastic/shell 0.1.1 → 0.2.0

package/src/screens/LoadoutScreen.tsx

@@ -1,11 +1,12 @@
 import { defaultColors, useAutoPaperTheme } from '@rific/auto-paper'
 import { FakeLandscapeView, getViewRotation, rotateInsets, useOrientationState } from '@tastic/core'
-import { CornerActionButtons, PlayerSetupPanel, PressAwayOverlay, ReadyButton, SharedActionBand, usePopoverHost } from '@tastic/hud'
+import { CornerActionButtons, PressAwayOverlay, usePopoverHost } from '@tastic/hud/chrome'
+import { PlayerSetupPanel, ReadyButton, SharedActionBand } from '@tastic/hud/lobby'
 import type { Profile } from '@tastic/profile'
 import { DualZoneLayout, needsSharedNeutralZone, useDualZoneLayout } from '@tastic/split-screen'
 import { router, useFocusEffect } from 'expo-router'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { Platform, StyleSheet, View } from 'react-native'
+import { Platform, type StyleProp, StyleSheet, View, type ViewStyle } from 'react-native'
 import Animated from 'react-native-reanimated'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
 import { useDispatch } from 'react-redux'
@@ -20,7 +21,8 @@ import { useSeatColors } from '../hooks/useSeatColors'
 import { safeBack } from '../navigation'
 import { usePack } from '../PackContext'
 import { liveplayActions } from '../redux/liveplaySlice'
-import { type GameDefinition, humanSeatsFor, roundModeFor, type Seat, type SeatTwo, seatTwoFor } from '../types'
+import { playHref, PROFILES_HREF } from '../routes'
+import { humanSeatsFor, type PackGameDefinition, roundModeFor, type Seat, type SeatTwo, seatTwoFor } from '../types'
 
 // The player-panel area: whenever a real device rotation changes orientationMode or which physical
 // side P1 lands on, the panels fade out, the layout underneath swaps while invisible, then they fade
@@ -31,7 +33,7 @@ const PANEL_SWAP_FADE_MS = 180
 
 // A game that has a loadout (GameDefinition.useLoadout): the loadout route sends any other straight
 // to its play screen.
-export type LoadoutGame = GameDefinition & Required<Pick<GameDefinition, 'useLoadout'>>
+export type LoadoutGame = PackGameDefinition & Required<Pick<PackGameDefinition, 'useLoadout'>>
 
 // Every game's loadout: seat 1 (the player picked on Home), seat 2 (the CPU, a second person, or
 // nobody, from seat 2's own button, or no button in a game for one player), the game's own match
@@ -66,6 +68,10 @@ export function LoadoutScreen({ game }: { game: LoadoutGame }) {
   const fixedSeats = p2IsHuman && (!!game.twoPlayerSeats?.faceToFaceOnWeb || Platform.OS !== 'web')
   const fixedUpsideDown = !!game.twoPlayerSeats?.followUpsideDown && orientationMode === 'faceToFace' && upsideDown
   const { panelLayout, panelFadeStyle } = useDualZoneLayout(fixedSeats ? 'faceToFace' : orientationMode, fixedSeats ? true : p1OnRight, fixedSeats || p1OnRightResolved, fixedSeats ? fixedUpsideDown : upsideDown, PANEL_SWAP_FADE_MS)
+  // split-screen types the fade as a style for any component (useAnimatedStyle's DefaultStyle). An app
+  // whose types widen Text's style (Expo's react-native-web types, which a generated expo-env.d.ts pulls
+  // in, make its cursor any string) can't hand that to Animated.View. It only ever sets opacity.
+  const playersRowFade = panelFadeStyle as unknown as StyleProp<ViewStyle>
 
   const [settingsOpen, setSettingsOpen] = useState(false)
   // Safe-area insets are relative to the device's fixed portrait frame; rotateInsets remaps them
@@ -113,7 +119,7 @@ export function LoadoutScreen({ game }: { game: LoadoutGame }) {
   useEffect(() => {
     if (!humanSeats.every((s) => ready[s])) return
     dispatch(liveplayActions.setActiveRound({ game: game.id, mode, settings: roundSettingsRef.current }))
-    router.push({ pathname: '/play/[game]', params: { game: game.id } })
+    router.push(playHref(game.id))
   }, [ready, humanSeats, game.id, mode, dispatch])
 
   const bg = dark ? '#000000' : '#FFFFFF'
@@ -166,7 +172,7 @@ export function LoadoutScreen({ game }: { game: LoadoutGame }) {
 
   const controlLook = { accentColor: themeColors.tertiary, mutedColor: fgMuted, dark, rotation }
   const p1Control = loadout.seatControl(1, controlsHost, { ...controlLook, seatColor: p1Color })
-  const p1Panel = <PlayerSetupPanel idPrefix='p1' host={controlsHost} color={p1Color} onColorChange={handleP1ColorChange} swatches={defaultColors} takenColor={p2Exists ? p2Color : undefined} allowSwapTaken={mode === 'vsCpu'} colorCaption={pack.colorCaption} isHuman ready={ready[1]} onToggleReady={() => setReady((r) => ({ ...r, 1: !r[1] }))} dark={dark} showReadyButton={showReadyButton} secondPicker={p1Control} secondPickerId={p1Control ? 'p1-control' : undefined} profiles={profiles} selectedProfileId={lastSelected[1]} takenProfileId={p2IsHuman ? lastSelected[2] : null} guestLabel='P1' onProfileSelect={handleP1ProfileSelect} onManageProfiles={() => router.push('/profiles')} />
+  const p1Panel = <PlayerSetupPanel idPrefix='p1' host={controlsHost} color={p1Color} onColorChange={handleP1ColorChange} swatches={defaultColors} takenColor={p2Exists ? p2Color : undefined} allowSwapTaken={mode === 'vsCpu'} colorCaption={pack.colorCaption} isHuman ready={ready[1]} onToggleReady={() => setReady((r) => ({ ...r, 1: !r[1] }))} dark={dark} showReadyButton={showReadyButton} secondPicker={p1Control} secondPickerId={p1Control ? 'p1-control' : undefined} profiles={profiles} selectedProfileId={lastSelected[1]} takenProfileId={p2IsHuman ? lastSelected[2] : null} guestLabel='P1' onProfileSelect={handleP1ProfileSelect} onManageProfiles={() => router.push(PROFILES_HREF)} />
   const p2Control = p2IsHuman ? loadout.seatControl(2, p2Host, { ...controlLook, seatColor: p2Color }) : undefined
   // A game for one player (no seatTwo) has no seat 2 button: seat 1's panel stands alone.
   const p2Panel = game.seatTwo && <SeatTwoPanel idPrefix='p2' host={p2Host} choices={game.seatTwo} seatTwo={seatTwo} onSeatTwoChange={changeSeatTwo} cpuDifficulty={loadout.cpuDifficulty} profiles={profiles} selectedProfileId={lastSelected[2]} onProfileSelect={handleP2ProfileSelect} color={p2Color} onColorChange={handleP2ColorChange} swatches={defaultColors} takenColor={p1Color} allowSwapTaken={mode === 'vsCpu'} colorCaption={pack.colorCaption} dark={dark} secondPicker={p2Control} secondPickerId={p2Control ? 'p2-control' : undefined} ready={ready[2]} onToggleReady={() => setReady((r) => ({ ...r, 2: !r[2] }))} showReadyButton={showReadyButton} />
@@ -202,7 +208,7 @@ export function LoadoutScreen({ game }: { game: LoadoutGame }) {
         ) : (
           <View style={styles.stackedZone}>
             {sharedControls}
-            <Animated.View style={[styles.playersRow, anyPlayerPickerOpen && styles.playersRowOpen, panelFadeStyle]}>
+            <Animated.View style={[styles.playersRow, anyPlayerPickerOpen && styles.playersRowOpen, playersRowFade]}>
               {!isPortrait && panelLayout.p1OnRight ? p2Panel : p1Panel}
               {!isPortrait && panelLayout.p1OnRight ? p1Panel : p2Panel}
             </Animated.View>

package/src/screens/ProfilesRoute.tsx

@@ -1,14 +1,39 @@
 import { defaultColors } from '@rific/auto-paper'
+import { type AlignResult, RotatedFrame } from '@tastic/hud/chrome'
 import { ProfilesScreen } from '@tastic/profile'
 
 import { useProfiles } from '../hooks/useProfiles'
 import { safeBack } from '../navigation'
+import { usePack } from '../PackContext'
+
+// Widest the roster gets in the wide layout (a phone held sideways, a desktop window). Upright it's
+// never capped.
+const ROSTER_MAX_WIDTH = 640
 
 // The Profiles screen (Manage, from either seat 1 button). Deleting a profile also removes its
 // stats and achievements in every game: each game's reducers listen for the removal (see
 // onProfileRemoved.ts).
+//
+// Turned with the phone like every other screen, in hud's RotatedFrame: ProfilesManager reads the
+// safe-area insets itself (the header's padding), so they're handed over remapped onto the frame's
+// edges (rotatedSafeArea); its delete confirm is a Paper Portal, which lands in a host inside the frame
+// and is turned with it (portalHost); and the roster's column is capped in the wide layout. Over a
+// pack's Backdrop the screen is transparent, drawn in the pack's foreground.
+// The pack's own placement for a profile's color swatch (PackDefinition.usePickerAlign), kept inside the
+// roster's capped column: the roster scrolls in it, which clips the menu at its edges. Handed to
+// ProfilesScreen only where the pack has one.
+function useRosterAlign(open: boolean, contentWidth: number, contentHeight: number): AlignResult {
+  const { usePickerAlign } = usePack()
+  return usePickerAlign!(open, contentWidth, contentHeight, { maxContentWidth: ROSTER_MAX_WIDTH })
+}
+
 export function ProfilesRoute() {
   const { profiles, createProfile, updateProfile, deleteProfile } = useProfiles()
+  const { Backdrop, foreground, newProfileColor, usePickerAlign } = usePack()
 
-  return <ProfilesScreen profiles={profiles} defaultColor={defaultColors[0].value} onCreate={(patch) => createProfile(patch)} onSave={(id, patch) => updateProfile(id, patch)} onDelete={deleteProfile} onBack={safeBack} />
+  return (
+    <RotatedFrame rotatedSafeArea portalHost maxContentWidth={ROSTER_MAX_WIDTH}>
+      <ProfilesScreen profiles={profiles} defaultColor={newProfileColor ?? defaultColors[0].value} onCreate={(patch) => createProfile(patch)} onSave={(id, patch) => updateProfile(id, patch)} onDelete={deleteProfile} onBack={safeBack} fg={foreground} bg={Backdrop ? 'transparent' : undefined} useColorPickerAlign={usePickerAlign ? useRosterAlign : undefined} />
+    </RotatedFrame>
+  )
 }

package/src/screens/StatsScreen.tsx

@@ -1,8 +1,7 @@
 import { useAutoPaperTheme } from '@rific/auto-paper'
-import { FakeLandscapeView, rotateInsets, useRotation } from '@tastic/core'
-import { BaseStatsScreen, PressAwayOverlay, usePopoverHost } from '@tastic/hud'
-import { OptionPicker, type OptionPickerOption } from '@tastic/profile'
-import { useMemo, useState } from 'react'
+import { BaseStatsScreen, type PopoverHost, PressAwayOverlay, RotatedFrame, usePopoverHost } from '@tastic/hud/chrome'
+import { getOptionPickerContentSize, OptionPicker, type OptionPickerOption } from '@tastic/profile'
+import { type ReactNode, useMemo, useState } from 'react'
 import { StyleSheet, View } from 'react-native'
 import { SegmentedButtons, Text } from 'react-native-paper'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
@@ -11,15 +10,22 @@ import { useDispatch } from 'react-redux'
 import { useProfiles } from '../hooks/useProfiles'
 import { safeBack } from '../navigation'
 import { usePack } from '../PackContext'
-import type { GameDefinition } from '../types'
+import { GUEST_PLAYER_ID, type PackDefinition, type PackGameDefinition, type PackStatsTab } from '../types'
 
 // Two tabs, as on Solitaire's stats screen: a page with every game's stats above the achievements
-// would leave the achievements out of sight at the bottom.
-type StatsTab = 'stats' | 'achievements'
+// would leave the achievements out of sight at the bottom. A pack's own tabs (PackDefinition.statsTabs)
+// go between them.
+const STATS = 'stats'
+const ACHIEVEMENTS = 'achievements'
 const TABS = [
-  { value: 'stats', label: 'Stats', icon: 'chart-box-outline' },
-  { value: 'achievements', label: 'Achievements', icon: 'trophy-outline' }
+  { value: STATS, label: 'Stats', icon: 'chart-box-outline' },
+  { value: ACHIEVEMENTS, label: 'Achievements', icon: 'trophy-outline' }
 ]
+// With a pack's own tabs, three or more don't fit a phone as equal segments with icons (Paper pads each
+// label 16pt a side, and "Achievements" alone is ~109pt in Solitaire's font), so each segment is as wide
+// as its label and the icons go: Solitaire's three take 309pt of a 375pt phone's 335pt row.
+const LABEL_WIDE_TAB = { flexBasis: 'auto', flexGrow: 1, flexShrink: 1 } as const
+const NO_PACK_TABS: readonly PackStatsTab[] = []
 
 // The pickers' values for Everyone and All Games (neither is ever a profile or game id).
 const EVERYONE = '__everyone__'
@@ -28,76 +34,149 @@ const ALL_GAMES = '__all__'
 const PLAYER_PICKER_ID = 'stats-player'
 const GAME_PICKER_ID = 'stats-game'
 
+// Widest the column gets in the wide layout (a phone held sideways, a desktop window): a list of stat
+// rows stretched across an 874pt-wide screen reads badly. Upright it's never capped.
+const STATS_MAX_WIDTH = 640
+
 // Every game's stats and achievements on one screen, filtered by player (Everyone, or one profile)
 // and by game (All Games, or one), like Solitaire's. Each game keeps its own stats and its own
 // achievements; this screen only shows them side by side. With two seats there's no one player to
-// open on, so it opens on Everyone. Guests count only toward Everyone: two guests in one match can't
-// be told apart.
+// open on, so it opens on Everyone, and guests count only toward Everyone: two guests in one match
+// can't be told apart. A pack for one player at a time (PackDefinition.guestStats) keeps a guest's
+// stats under GUEST_PLAYER_ID, offers Guest in the picker and opens on whoever is in seat 1.
+//
+// Turned with the phone in hud's RotatedFrame: its insets remapped onto the frame's edges, the reset
+// confirm portaled into a host inside the frame (so it's turned with it, at rotation 0), and the column
+// capped in the wide layout.
 export function StatsScreen() {
+  const pickerHost = usePopoverHost()
+  return (
+    <StatsPressAway host={pickerHost}>
+      <RotatedFrame rotatedSafeArea portalHost maxContentWidth={STATS_MAX_WIDTH}>
+        <StatsContent pickerHost={pickerHost} />
+      </RotatedFrame>
+    </StatsPressAway>
+  )
+}
+
+// Closes the pickers' open menu on a press anywhere on the screen that nothing else takes: the header
+// (its title and blank space) and, in the wide layout, the frame either side of the capped column. The
+// page's own press-away overlay only covers the scrolling content, which neither is part of. A press
+// only reaches this when no control under the finger claims it, so the back button, the menu's rows and
+// everything else still work.
+function StatsPressAway({ host, children }: { host: PopoverHost; children: ReactNode }) {
+  return (
+    <View testID='stats-press-away' style={styles.screen} onStartShouldSetResponder={() => host.openId !== null} onResponderRelease={host.close}>
+      {children}
+    </View>
+  )
+}
+
+// A pack whose Reset follows the game picker resets each game's own (GameDefinition.resetStats).
+const useNoPackReset = () => null
+
+// No placement of the pack's own: hud places the pickers' menus itself.
+const noPickerAlign = () => undefined
+
+function StatsContent({ pickerHost }: { pickerHost: PopoverHost }) {
   const pack = usePack()
   const { dark, colors } = useAutoPaperTheme()
-  // Turned with the phone like every other screen: rotateInsets remaps the device's raw safe-area
-  // reading onto the edges they land on once FakeLandscapeView turns the content.
-  const rotation = useRotation()
-  const insets = rotateInsets(useSafeAreaInsets(), rotation)
-  const { profiles } = useProfiles()
+  // Already remapped onto the turned frame's edges by RotatedFrame's rotatedSafeArea.
+  const insets = useSafeAreaInsets()
+  const { profiles, lastSelected } = useProfiles()
   const dispatch = useDispatch()
-  const pickerHost = usePopoverHost()
+  const fg = pack.foreground ?? colors.onBackground
 
-  const [tab, setTab] = useState<StatsTab>('stats')
+  const [tab, setTab] = useState<string>(STATS)
   const [gameId, setGameId] = useState<string>(ALL_GAMES)
-  // Self-heals to Everyone if the selected profile is deleted while this screen is mounted.
-  const [selectedProfileId, setSelectedProfileId] = useState<string | null>(null)
-  const profileId = selectedProfileId && profiles.some((p) => p.id === selectedProfileId) ? selectedProfileId : null
+  // Opens on whoever is in seat 1 (Guest for a guest) where the pack keeps a guest's stats, else on
+  // Everyone. Self-heals to Everyone if the selected profile is deleted while this screen is mounted, and
+  // from Guest once there is no profile (Everyone is then just the guest).
+  const [selectedProfileId, setSelectedProfileId] = useState<string | null>(() => (pack.guestStats ? (lastSelected[1] ?? GUEST_PLAYER_ID) : null))
+  const profileId = selectedProfileId && profiles.length > 0 && ((pack.guestStats && selectedProfileId === GUEST_PLAYER_ID) || profiles.some((p) => p.id === selectedProfileId)) ? selectedProfileId : null
 
   const games = gameId === ALL_GAMES ? pack.games : pack.games.filter((g) => g.id === gameId)
+  const packTabs = pack.statsTabs ?? NO_PACK_TABS
+  const packTab = packTabs.find((t) => t.value === tab)
+  // One achievement list across the pack's games doesn't narrow to a game, so the game picker goes.
+  const showGamePicker = !(tab === ACHIEVEMENTS && pack.AchievementList)
 
-  const playerOptions = useMemo<OptionPickerOption<string>[]>(() => [{ value: EVERYONE, label: 'Everyone', icon: 'account-group' }, ...profiles.map((p) => ({ value: p.id, label: p.name, icon: 'account', color: p.color }))], [profiles])
+  const playerOptions = useMemo<OptionPickerOption<string>[]>(() => [{ value: EVERYONE, label: 'Everyone', icon: 'account-group' }, ...(pack.guestStats ? [{ value: GUEST_PLAYER_ID, label: 'Guest', icon: 'account-outline' }] : []), ...profiles.map((p) => ({ value: p.id, label: p.name, icon: 'account', color: pack.previewColor ? pack.previewColor(p.color, dark) : p.color }))], [profiles, pack, dark])
   const gameOptions = useMemo<OptionPickerOption<string>[]>(() => [{ value: ALL_GAMES, label: 'All Games', icon: 'view-grid-outline' }, ...pack.games.map((g) => ({ value: g.id, label: g.title }))], [pack.games])
+  const tabButtons = useMemo(() => (packTabs.length > 0 ? [{ value: STATS, label: 'Stats' }, ...packTabs.map(({ value, label }) => ({ value, label })), { value: ACHIEVEMENTS, label: 'Achievements' }].map((button) => ({ ...button, style: LABEL_WIDE_TAB })) : TABS), [packTabs])
+  const title = tab === STATS ? 'Stats' : tab === ACHIEVEMENTS ? 'Achievements' : (packTab?.label ?? '')
+
+  // Reset: the pack's own (PackDefinition.resetStats) follows the player picker, one player's or
+  // everyone's; otherwise it clears every player's stats and achievements in the games shown (one game,
+  // or all of them). The pack never changes while it runs, so the same hook is called on every render.
+  const usePackReset = pack.resetStats?.useReset ?? useNoPackReset
+  const packReset = usePackReset()
+  const reset = resetFor(pack, packReset, profileId, profiles, games, () => games.forEach((g) => g.resetStats && dispatch(g.resetStats())))
 
-  // Reset clears every player's stats and achievements in the games shown (one game, or all of them).
-  const resetScope = games.length === 1 ? games[0].title : 'every game'
-  const onReset = () => games.forEach((g) => dispatch(g.resetStats()))
+  // The pack's own placement for the pickers' menus (PackDefinition.usePickerAlign), sized from their rows.
+  const usePickerAlign = pack.usePickerAlign ?? noPickerAlign
+  const playerSize = getOptionPickerContentSize(playerOptions.length)
+  const gameSize = getOptionPickerContentSize(gameOptions.length)
+  const playerAlign = usePickerAlign(pickerHost.openId === PLAYER_PICKER_ID, playerSize.width, playerSize.height)
+  const gameAlign = usePickerAlign(pickerHost.openId === GAME_PICKER_ID, gameSize.width, gameSize.height)
+
+  // Over the pack's Backdrop the page is transparent, with its tabs and pickers on the theme's surface.
+  const surface = pack.Backdrop ? { backgroundColor: colors.surface } : undefined
+  const triggerStyle = pack.Backdrop ? [styles.pill, surface] : undefined
+  const PackTabContent = packTab?.Content
 
   return (
-    <FakeLandscapeView style={styles.rotatable}>
-      <BaseStatsScreen title={tab === 'stats' ? 'Stats' : 'Achievements'} onBack={safeBack} insets={insets} onReset={onReset} resetLabel={games.length === 1 ? `Reset ${resetScope} Stats` : 'Reset All Stats'} resetConfirmTitle='Reset Stats?' resetConfirmBody={`Erases every player's stats and achievements in ${resetScope}. This cannot be undone.`} rotation={rotation}>
-        {/* Inside the page, not before it: BaseStatsScreen paints an opaque full-screen container that
-        would hide a tap catcher placed underneath it. Over the stat sections and under the open
-        filters (pressAway's zIndex sits below filtersOpen's), so a tap anywhere on the page but a
-        menu closes it. */}
-        <PressAwayOverlay active={pickerHost.openId !== null} onPress={pickerHost.close} style={styles.pressAway} />
-        <SegmentedButtons value={tab} onValueChange={(value) => setTab(value as StatsTab)} buttons={TABS} style={styles.tabs} />
-
-        <View style={[styles.filters, pickerHost.openId !== null && styles.filtersOpen]}>
-          {profiles.length > 0 && <OptionPicker id={PLAYER_PICKER_ID} host={pickerHost} options={playerOptions} value={profileId ?? EVERYONE} onChange={(value) => setSelectedProfileId(value === EVERYONE ? null : value)} color={colors.primary} dark={dark} icon={profileId ? 'account' : 'account-group'} />}
-          <OptionPicker id={GAME_PICKER_ID} host={pickerHost} options={gameOptions} value={gameId} onChange={setGameId} color={colors.primary} dark={dark} icon='view-grid-outline' />
-        </View>
-
-        {/* The pack's own section across its games (a calendar of play), first on the Stats tab: it
-        follows both filters, so narrowed to one game it shows that game's part. */}
-        {tab === 'stats' && pack.StatsSections && <pack.StatsSections profileId={profileId} gameId={gameId === ALL_GAMES ? null : gameId} />}
-
-        {games.map((game) => (
-          <GameStats key={game.id} game={game} tab={tab} profileId={profileId} showTitle={games.length > 1} />
-        ))}
-      </BaseStatsScreen>
-    </FakeLandscapeView>
+    <BaseStatsScreen title={title} onBack={safeBack} insets={insets} onReset={reset.onReset} resetLabel={reset.label} resetConfirmTitle={reset.title} resetConfirmBody={reset.body} fg={pack.foreground} bg={pack.Backdrop ? 'transparent' : undefined} rotation={0}>
+      {/* Inside the page, not before it: BaseStatsScreen paints an opaque full-screen container that
+      would hide a tap catcher placed underneath it. Over the stat sections and under the open
+      filters (pressAway's zIndex sits below filtersOpen's), so a tap anywhere on the page but a
+      menu closes it. Off the page (the header, the margins) StatsPressAway closes it. */}
+      <PressAwayOverlay active={pickerHost.openId !== null} onPress={pickerHost.close} style={styles.pressAway} />
+      <SegmentedButtons value={tab} onValueChange={setTab} buttons={tabButtons} style={[styles.tabs, surface]} />
+
+      {/* Takes a press on its own blank parts (the gap, an open menu's padding) while a menu is open, so
+      it never reaches StatsPressAway. */}
+      <View style={[styles.filters, pickerHost.openId !== null && styles.filtersOpen]} onStartShouldSetResponder={() => pickerHost.openId !== null}>
+        {profiles.length > 0 && <OptionPicker id={PLAYER_PICKER_ID} host={pickerHost} options={playerOptions} value={profileId ?? EVERYONE} onChange={(value) => setSelectedProfileId(value === EVERYONE ? null : value)} color={colors.primary} dark={dark} icon={profileId ? 'account' : 'account-group'} alignOverride={playerAlign} triggerStyle={triggerStyle} />}
+        {showGamePicker && <OptionPicker id={GAME_PICKER_ID} host={pickerHost} options={gameOptions} value={gameId} onChange={setGameId} color={colors.primary} dark={dark} icon='view-grid-outline' alignOverride={gameAlign} triggerStyle={triggerStyle} />}
+      </View>
+
+      {/* The pack's own section across its games (a calendar of play), first on the Stats tab: it
+      follows both filters, so narrowed to one game it shows that game's part. */}
+      {tab === STATS && pack.StatsSections && <pack.StatsSections profileId={profileId} gameId={gameId === ALL_GAMES ? null : gameId} />}
+
+      {PackTabContent && <PackTabContent profileId={profileId} gameId={gameId === ALL_GAMES ? null : gameId} />}
+
+      {tab === ACHIEVEMENTS && pack.AchievementList ? <pack.AchievementList profileId={profileId} /> : (tab === STATS || tab === ACHIEVEMENTS) && games.map((game) => <GameStats key={game.id} game={game} tab={tab} profileId={profileId} showTitle={games.length > 1 && pack.statsGameTitles !== false} titleColor={fg} />)}
+    </BaseStatsScreen>
   )
 }
 
-// One game's part of the page: its own sections, under its name when more than one game is shown.
-function GameStats({ game, tab, profileId, showTitle }: { game: GameDefinition; tab: StatsTab; profileId: string | null; showTitle: boolean }) {
-  const { colors } = useAutoPaperTheme()
+// What the screen's Reset does and says: the pack's own, for the player picked (by name; Guest for a
+// guest) or everyone, or each shown game's own.
+function resetFor(pack: PackDefinition, packReset: ((profileId: string | null) => void) | null, profileId: string | null, profiles: readonly { id: string; name: string }[], games: readonly PackGameDefinition[], resetGames: () => void) {
+  if (pack.resetStats && packReset) {
+    const name = profileId === GUEST_PLAYER_ID ? 'Guest' : profileId ? (profiles.find((p) => p.id === profileId)?.name ?? null) : null
+    return { onReset: () => packReset(profileId), ...pack.resetStats.labels(name) }
+  }
+  const scope = games.length === 1 ? games[0].title : 'every game'
+  return { onReset: resetGames, label: games.length === 1 ? `Reset ${scope} Stats` : 'Reset All Stats', title: 'Reset Stats?', body: `Erases every player's stats and achievements in ${scope}. This cannot be undone.` }
+}
+
+// One game's part of the page: its own sections, under its name when more than one game is shown. A
+// game with no achievement list of its own shows nothing on Achievements.
+function GameStats({ game, tab, profileId, showTitle, titleColor }: { game: PackGameDefinition; tab: string; profileId: string | null; showTitle: boolean; titleColor: string }) {
   const { StatsSections, AchievementList } = game
+  const Sections = tab === STATS ? StatsSections : AchievementList
+  if (!Sections) return null
   return (
     <View style={styles.game}>
       {showTitle && (
-        <Text variant='titleLarge' style={[styles.gameTitle, { color: colors.onBackground }]}>
+        <Text variant='titleLarge' style={[styles.gameTitle, { color: titleColor }]}>
           {game.title}
         </Text>
       )}
-      {tab === 'stats' ? <StatsSections profileId={profileId} /> : <AchievementList profileId={profileId} />}
+      <Sections profileId={profileId} />
     </View>
   )
 }
@@ -119,14 +198,17 @@ const styles = StyleSheet.create({
     fontWeight: 'bold',
     marginTop: 8
   },
+  // A picker's button on the theme's surface (over a backdrop), the same pill as Home's.
+  pill: {
+    borderRadius: 999
+  },
   pressAway: {
     zIndex: 50
   },
-  // A real full-bleed box for FakeLandscapeView to size its turned content against.
-  rotatable: {
+  screen: {
     flex: 1
   },
-  // SegmentedButtons' own rounding.
+  // SegmentedButtons' own rounding, so a surface behind it is the same pill.
   tabs: {
     borderRadius: 20
   }

package/src/types.ts

@@ -1,9 +1,11 @@
-import type { ThemeAppearance } from '@rific/auto-paper'
+import type { ThemeAppearance, ThemeSettings } from '@rific/auto-paper'
 import type { ViewRotation } from '@tastic/core'
-import type { MenuOption, PopoverHost } from '@tastic/hud'
+import type { AlignResult, PopoverHost } from '@tastic/hud/chrome'
 import type { GuideStep } from '@tastic/hud/guide'
+import type { MenuOption } from '@tastic/hud/lobby'
 import type { FontSource } from 'expo-font'
-import type { ComponentType, ReactNode } from 'react'
+import type { Stack } from 'expo-router'
+import type { ComponentProps, ComponentType, ReactNode } from 'react'
 import type { Action, Reducer } from 'redux'
 
 import type { ShellState } from './redux/shellState'
@@ -79,6 +81,11 @@ export interface GameLoadout {
   cpuDifficulty?: { value: string; options: MenuOption<string>[]; onChange: (value: string) => void }
 }
 
+// The id a guest's stats are kept under where a pack keeps them (PackDefinition.guestStats): the one
+// player who isn't a profile, in a pack for one player at a time. Not seatPlayerKey's `guest:1`, which
+// tells two guests at one table apart.
+export const GUEST_PLAYER_ID = 'guest'
+
 // What a game's How to Play cards are built from: the live settings (through the game's own
 // selector, so the guide host never has to know their shape), how seat 2 is set up, and whether
 // the device is touch-first.
@@ -113,12 +120,30 @@ export interface GamePreviewProps {
   dark: boolean
 }
 
+// The pack's own How to Play (PackDefinition.guide): cards that teach every game in the pack at once,
+// shown on Home's first launch and replayed from Home's Settings. Its seen version is a key of the
+// pack's own (hud's createGuideSlice), so a pack keeps whatever it already saved.
+export interface PackGuide {
+  version: number
+  selectVersionSeen: (state: ShellState) => number
+  markSeen: (version: number) => Action
+  getSteps: (context: { touch: boolean }) => GuideStep[]
+}
+
+// A game's rules sheet (GameDefinition.Rules), opened from its tile's rules button on Home. It renders
+// through a Paper Portal into a host Home mounts inside its turned frame, so it's already turned with it.
+export interface GameRulesProps {
+  visible: boolean
+  onDismiss: () => void
+}
+
 export interface GameDefinition {
   id: string
   title: string
   // One line under the tile's name on Home.
   blurb: string
-  icon: ComponentType<GameIconProps>
+  // Left out only by a game with a Preview, which Home draws in its place.
+  icon?: ComponentType<GameIconProps>
   // Drawn on Home in place of the icon, a frame after Home first paints (a preview is far more to
   // draw than an icon). While any game in the pack has one, Home lays its games out as tiles: rows
   // with the preview at their start, and a grid beside the hero on a wide screen. A game without one
@@ -134,8 +159,9 @@ export interface GameDefinition {
   twoPlayerSeats?: { faceToFaceOnWeb: boolean; followUpsideDown: boolean }
   // The store keys this game mounts (settings, achievements, guide), merged into the pack's store.
   reducers: Record<string, Reducer>
-  // Mounted at the app root for the game's lifetime (its stats and achievements context).
-  Provider: ComponentType<{ children: ReactNode }>
+  // Mounted at the app root for the game's lifetime (its stats and achievements context). Left out by
+  // a game whose stats live in the pack's own (PackDefinition.Provider).
+  Provider?: ComponentType<{ children: ReactNode }>
   // Left out by a game with nothing to set up before it starts: Home opens its play screen
   // straight away (after its How to Play the first time), and its rule variants are rows in its
   // play screen's own Settings (SettingsDialog's children).
@@ -146,15 +172,34 @@ export interface GameDefinition {
   // board: the shell only remembers which game it was (redux/lastActiveGameSlice.ts). A match that
   // isn't saved (liveplay) shouldn't opt in, or a relaunch would open a fresh one.
   resumable?: boolean
+  // The play screen keeps the status bar while the phone is held upright. Unset, the bar is hidden on
+  // every play screen for the whole round, whatever the angle; set, it's hidden only while the
+  // content is turned, as on every other screen.
+  keepStatusBar?: boolean
   // The game's stats sections and its achievement list for the stats screen, for one profile
   // (null is Everyone).
   StatsSections: ComponentType<{ profileId: string | null }>
-  AchievementList: ComponentType<{ profileId: string | null }>
-  // Clears the game's stats and achievements (the stats screen's Reset).
-  resetStats: () => Action
+  // Left out by a game whose achievements are in the pack's one list (PackDefinition.AchievementList).
+  AchievementList?: ComponentType<{ profileId: string | null }>
+  // Clears the game's stats and achievements (the stats screen's Reset). Left out by a game whose stats
+  // the pack resets itself (PackDefinition.resetStats).
+  resetStats?: () => Action
+  // The game's own How to Play cards: shown the first time its tile is picked, and from its rules
+  // button and its loadout's Settings.
   guide: GameGuide
+  // The rules sheet its tile's rules button opens, in place of its How to Play cards.
+  Rules?: ComponentType<GameRulesProps>
 }
 
+// A game with no How to Play cards of its own, taught by the pack's own (PackDefinition.guide): its
+// tile opens without cards the first time, and its rules button shows its Rules or nothing. Its own type
+// rather than an optional `guide` on GameDefinition, so a pack's code that reads its own games' cards
+// (DuelTastic's packGuides test) keeps compiling.
+export type GuidelessGameDefinition = Omit<GameDefinition, 'guide'> & { guide?: undefined }
+
+// Any game a pack holds: one with How to Play cards of its own, or one without.
+export type PackGameDefinition = GameDefinition | GuidelessGameDefinition
+
 // What Home hands the pack's hero (PackDefinition.HeroTitle).
 export interface HeroTitleProps {
   // The pack's wordmark (see PackDefinition.wordmark).
@@ -180,13 +225,41 @@ export interface PackStatsSectionsProps {
   gameId: string | null
 }
 
+// The stack's screen options (expo-router's Stack), as an object: what PackDefinition.useScreenOptions
+// returns.
+export type StackScreenOptions = Exclude<NonNullable<ComponentProps<typeof Stack>['screenOptions']>, (...args: never[]) => unknown>
+
+// The two sounds feedback-press plays on every button press (PackDefinition.useFeedbackSounds): a tap,
+// and a refused or notifying press.
+export interface FeedbackSounds {
+  selection: () => void
+  notification: () => void
+}
+
+// A tab of the pack's own on the stats screen (PackDefinition.statsTabs), between Stats and
+// Achievements, handed the screen's two filters.
+export interface PackStatsTab {
+  value: string
+  label: string
+  Content: ComponentType<PackStatsSectionsProps>
+}
+
+// The stats screen's Reset, where the pack resets stats itself (PackDefinition.resetStats). It follows
+// the player picker: one player's (a profile id, or GUEST_PLAYER_ID), or everyone's (null).
+export interface PackStatsReset {
+  useReset: () => (profileId: string | null) => void
+  // The button, the confirm's title and its body, for a player's name (Guest for a guest) or null for
+  // Everyone.
+  labels: (name: string | null) => { label: string; title: string; body: string }
+}
+
 export interface PackDefinition {
   name: string
   // The Home wordmark's two lines.
   wordmark: readonly [string, string]
   // A seat's color pick for a profile is kept for this pack only; the seat button says so.
   colorCaption: string
-  games: readonly GameDefinition[]
+  games: readonly PackGameDefinition[]
   // Player 1's and player 2's own default colors. They seed the theme's primary and secondary (the
   // tertiary is derived from them, see shellState.ts) and the guest and CPU colors a fresh install
   // starts with (seatColorsSlice.ts), so a fresh install's live theme and its remembered colors agree.
@@ -213,4 +286,64 @@ export interface PackDefinition {
   // A section of the pack's own at the top of the stats screen's Stats tab, across its games (a
   // calendar of play), above each game's own StatsSections. It follows the screen's two filters.
   StatsSections?: ComponentType<PackStatsSectionsProps>
+
+  // A table drawn once behind the whole stack (a felt), seen through every screen: the stack's own
+  // layers go transparent, and Home, the stats screen and Profiles draw on it in `foreground`.
+  Backdrop?: ComponentType
+  // The text and icon color of what Home, the stats screen and Profiles draw straight on the screen's
+  // background (the hero, the corner buttons, headers). Unset is black or white with the theme.
+  foreground?: string
+  // Mounted once around How to Play and the stack, inside the store, Theme, ProfilesProvider and every
+  // game's Provider: a context of the pack's own (one stats context across its games).
+  Provider?: ComponentType<{ children: ReactNode }>
+  // Merged into the stack's screen options after the shell's own (a status bar style, a crossfade).
+  useScreenOptions?: () => StackScreenOptions
+  // The two sounds every button plays, in place of the shell's own.
+  useFeedbackSounds?: () => FeedbackSounds
+  // The pack's own toaster, drawn in a frame turned with the phone (with the safe-area insets turned
+  // onto the frame's edges) in place of the shell's. It renders inline: the toast provider is given no
+  // Paper, so nothing portals it out of the frame.
+  Toaster?: ComponentType
+  // Every screen reads upright while the software keyboard is up (@tastic/core's OrientationProvider),
+  // for typing a profile's name with the phone sideways.
+  portraitWhileKeyboard?: boolean
+  // false leaves Edge Guard out of Settings (a pack with no edge controls and no Edge Guard plugin).
+  edgeGuard?: boolean
+  // The theme seat 1's color makes (a muted seed with a harmony), applied whenever the seats' colors or
+  // dark mode change and as a fresh install's theme, in place of a triad of the raw seat colors. With it,
+  // each seat's color is read from the seat colors rather than from the theme.
+  seatTheme?: (colors: Record<Seat, string>, dark: boolean) => Pick<ThemeSettings, 'color' | 'harmony'>
+  // How every profile color is drawn (the button's chip, the swatches, each ProfileChip): mounted as
+  // @tastic/profile's ProfileColorProvider. The saved colors stay as picked.
+  previewColor?: (hex: string, dark: boolean) => string
+  // The pack's own How to Play: shown on Home's first launch (held back while a cold launch resumes a
+  // game) and from Home's Settings, never in a play screen.
+  guide?: PackGuide
+  // Seat 1's button: the chip's label for a guest (default 'P1') and the guest row's in its menu
+  // (default @tastic/profile's).
+  guestLabel?: string
+  nullLabel?: string
+  // The stats screen keeps a guest's stats under GUEST_PLAYER_ID: a Guest entry in the player picker
+  // once a profile exists, and the screen opens on whoever is in seat 1.
+  guestStats?: boolean
+  // One achievement list across the pack's games, on the Achievements tab (the game picker hidden there).
+  AchievementList?: ComponentType<{ profileId: string | null }>
+  // Tabs of the pack's own between Stats and Achievements.
+  statsTabs?: readonly PackStatsTab[]
+  // The stats screen's Reset, following the player picker rather than the game picker.
+  resetStats?: PackStatsReset
+  // false leaves out each game's name over its sections on All Games, where its sections name it.
+  statsGameTitles?: boolean
+  // A new profile's starting color on Profiles. Unset is auto-paper's first swatch.
+  newProfileColor?: string
+  // Where a picker's menu opens (its alignOverride) on Home (seat 1's button), the stats screen (its two
+  // pickers) and Profiles (a profile's color swatch). hud's own placement measures a turned button
+  // against the upright window, so with the phone held sideways it can pick the side with no room and
+  // run the menu off the screen (Solitaire's useFrameAutoAlign places it in the turned frame instead).
+  // `open` is whether this picker's menu is open, the size is its content's, and `maxContentWidth` is a
+  // capped column's width the menu stays inside (Profiles' roster). Unset is hud's own placement.
+  usePickerAlign?: PickerAlign
 }
+
+// What PackDefinition.usePickerAlign is: a hook, called on every render of the screen it serves.
+export type PickerAlign = (open: boolean, contentWidth: number, contentHeight: number, options?: { maxContentWidth?: number }) => AlignResult