@tastic/shell 0.1.1 → 0.2.1

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