@tastic/hud 0.20.0 → 0.22.0

package/src/PlayerSetupPanel.tsx

@@ -1,31 +1,35 @@
 import { SeedColor } from '@rific/auto-paper'
-import { Profile, ProfilePicker } from '@tastic/profile'
+import { getOptionPickerContentSize, getProfilePickerContentSize, OptionPicker, Profile, ProfilePicker, type ProfilePickerColorSection } from '@tastic/profile'
 import { ReactNode } from 'react'
 import { StyleSheet, View } from 'react-native'
 import { Text } from 'react-native-paper'
 
 import { InlineColorPicker } from './InlineColorPicker'
-import { LabeledDropdown, LabeledDropdownOption } from './LabeledDropdown'
+import { LabeledDropdownOption } from './LabeledDropdown'
 import { ReadyButton } from './ReadyButton'
 import { AlignResult, PopoverRotation } from './useAutoAlign'
 import { PopoverHost, usePopoverHost } from './usePopoverHost'
+import { useZoneClampedAlign } from './useZoneClampedAlign'
 
-// This panel's own internal color/CPU-difficulty popover ids, derived from idPrefix - exported so a
-// caller that needs to know whether one of them is currently open (e.g. to compute the `open`
-// argument useZoneClampedAlign's own first parameter needs, ahead of handing its result to
-// colorAlignOverride/cpuDifficultyAlignOverride below) doesn't have to hardcode or guess this
-// panel's own internal naming convention. Matches secondPickerId's own job for a caller's own
+// This panel's own internal popover ids, derived from idPrefix - exported so a caller that needs to
+// know whether one of them is currently open (e.g. to elevate the zone or row holding the panel)
+// doesn't have to hardcode or guess this panel's own internal naming convention. Matches secondPickerId's own job for a caller's own
 // externally-constructed picker - this is the equivalent for the two pickers this panel owns
 // itself, which have no prop of their own to name their id with.
 export function getColorPopoverId(idPrefix: string): string {
   return `${idPrefix}-color`
 }
+// The seat button's dropdown on a human seat (@tastic/profile's ProfilePicker opens under
+// `${idPrefix}-profile`). A CPU seat's opens under getCpuDifficultyPopoverId.
+export function getProfilePopoverId(idPrefix: string): string {
+  return `${idPrefix}-profile`
+}
 export function getCpuDifficultyPopoverId(idPrefix: string): string {
   return `${idPrefix}-difficulty`
 }
 
 export interface PlayerSetupPanelProps<C extends string = string> {
-  // Namespaces this panel's popover ids ('color', whatever secondPickerId names, 'difficulty') so
+  // Namespaces this panel's popover ids ('profile', 'difficulty', 'color', whatever secondPickerId names) so
   // two panels can safely share one host (see `host` below) without their ids colliding.
   idPrefix: string
   // Shared popover host, when this panel's own popovers should be mutually exclusive with another
@@ -35,7 +39,7 @@ export interface PlayerSetupPanelProps<C extends string = string> {
   // real people editing at once is the point.
   host?: PopoverHost
   label?: string
-  // Applied only to the plain `label` fallback text below (ProfilePicker/LabeledDropdown render
+  // Applied only to the plain `label` fallback text below (ProfilePicker/OptionPicker render
   // their own fixed chrome regardless of this prop) - omit to inherit whichever font the calling
   // screen's own theme resolves for a labelSmall Text, rather than this package forcing its own
   // MONO_FONT onto what's really the host app's own copy.
@@ -44,21 +48,24 @@ export interface PlayerSetupPanelProps<C extends string = string> {
   onColorChange: (hex: string) => void
   swatches: SeedColor[]
   // The other player's current color - stays visible in the swatch grid but disabled, rather than
-  // removed from it entirely. Unless allowSwapTaken is set - see InlineColorPicker's own doc.
+  // removed from it entirely. Unless allowSwapTaken is set (the other seat is the CPU), which lets
+  // it be picked so the caller can swap the two - see InlineColorPicker's own doc.
   takenColor?: string
   allowSwapTaken?: boolean
-  // Passed straight through to the internal InlineColorPicker's own `alignOverride` - this panel
-  // has no way for a caller to reach that picker directly (it's not a ReactNode slot the way
-  // secondPicker is, see that prop's own doc), so a caller inside a @tastic/split-screen zone
-  // needs this to substitute useZoneClampedAlign's result for the color picker's own popover.
+  // A short line under the seat button's Color row while a profile is selected, saying where the
+  // color applies (e.g. 'Snake only': the pick is kept in this game, not on the profile). Left out
+  // for a guest or the CPU, who have no color anywhere else.
+  colorCaption?: string
+  // False leaves the Color row out of the seat button's dropdown (e.g. a CPU seat set to "None",
+  // with no second player to color). Defaults to true.
+  showColor?: boolean
+  // The fallback color swatch's placement and rotation, passed straight through to its
+  // InlineColorPicker. That swatch is only drawn on a seat with neither a profile picker nor a CPU
+  // difficulty picker (see the header below); the seat button places its own dropdown.
   colorAlignOverride?: AlignResult
-  // Passed straight through to the internal InlineColorPicker's own `rotation` - same reasoning as
-  // colorAlignOverride above (no other way for a caller to reach that picker directly), for a
-  // caller whose own rotation reading needs to differ from InlineColorPicker's default ambient
-  // useRotation() read (see that component's own `rotation` doc for when that's worth doing).
   colorRotation?: PopoverRotation
   isHuman: boolean
-  // Whatever sits beside the color picker in pickerRow, if anything - a ControlSchemePicker, a raw
+  // Whatever sits under the seat button in pickerRow, if anything - a ControlSchemePicker, a raw
   // SectionedDropdown, or nothing at all. The five apps this component was extracted from each
   // duplicated this entire panel and differed only in what (if anything) occupied this one slot,
   // each wanting a genuinely different concept there (which physical input drives a seat, vs. a
@@ -69,7 +76,7 @@ export interface PlayerSetupPanelProps<C extends string = string> {
   secondPicker?: ReactNode
   // The popover id secondPicker opens under, if it opens one at all - lets pickerRow's own
   // "elevate above later siblings while one of my own popovers is open" logic (see pickerRowOpen)
-  // react to secondPicker's popover the same way it already does for the color picker's, without
+  // react to secondPicker's popover the same way it already does for the fallback swatch's, without
   // this component needing any opinion on what secondPicker actually renders. Omit when secondPicker
   // has no popover of its own, or isn't provided at all.
   secondPickerId?: string
@@ -82,7 +89,7 @@ export interface PlayerSetupPanelProps<C extends string = string> {
   profiles?: Profile[]
   selectedProfileId?: string | null
   takenProfileId?: string | null
-  // What the name trigger shows before any profile's selected - this seat's own 'P1'/'P2' (see
+  // What the seat button shows before any profile's selected - this seat's own 'P1'/'P2' (see
   // ProfilePicker's own doc for why it's never "Player"). Required whenever profiles is provided,
   // since the trigger always needs some idle text.
   guestLabel?: string
@@ -95,29 +102,30 @@ export interface PlayerSetupPanelProps<C extends string = string> {
   cpuDifficulty?: C
   cpuDifficultyOptions?: LabeledDropdownOption<C>[]
   onCpuDifficultyChange?: (value: C) => void
-  // Passed straight through to the internal LabeledDropdown's own `alignOverride` - same reasoning
-  // as colorAlignOverride above, for the CPU-difficulty picker instead of the color picker.
-  cpuDifficultyAlignOverride?: AlignResult
-  // InlineColorPicker's own `icon` for a human vs. a non-human seat (overridden by a selected
-  // profile's own `tag`, same precedence InlineColorPicker itself applies) - defaults match every
-  // consumer's own convention. A caller with its own extra CPU states (e.g. a "no CPU" slot) computes
-  // its own icon string and passes it through cpuIcon rather than this component needing any opinion
-  // on what those states are.
+  // The icon on a non-human seat's button chip, and on the fallback color swatch for a human vs. a
+  // non-human seat (overridden there by a selected profile's own `tag`). A human seat's button chip
+  // shows the selected profile's tag, or ProfilePicker's guest icon. A caller with its own extra CPU
+  // states (e.g. a "no CPU" slot) computes its own icon string and passes it through cpuIcon rather
+  // than this component needing any opinion on what those states are.
   humanIcon?: string
   cpuIcon?: string
 }
 
-// One panel per player slot in a local-multiplayer loadout/lobby screen: a name header (a saved
-// profile switcher for a human seat, a CPU-difficulty picker for a non-human one, or a plain label
-// when neither applies), a color picker optionally paired with a second, per-app picker (see
-// `secondPicker`'s own doc), and a Ready toggle for human seats. Ported from five apps' own
-// near-identical PlayerSetupPanel.tsx/LobbyPlayerPanel.tsx (AirHockey, BoxHockey, Pong, LightCycles,
-// Snake), which had all independently converged on this exact skeleton.
+// One panel per player slot in a local-multiplayer loadout/lobby screen: one seat button, an
+// optional second, per-app picker under it (see `secondPicker`'s own doc), and a Ready toggle for
+// human seats. A human seat's button is @tastic/profile's ProfilePicker and a CPU seat's is its
+// OptionPicker (the difficulty levels), each with the seat's color behind a Color row at the top of
+// the same dropdown: Solitaire's player button, made the fleet's seat control (Jay, 2026-10-16). It
+// used to be a profile (or difficulty) dropdown with a separate color swatch beside it, which read
+// as two unrelated things. A seat with neither picker wired keeps the plain label and the separate
+// swatch. Ported from five apps' own near-identical PlayerSetupPanel.tsx/LobbyPlayerPanel.tsx
+// (AirHockey, BoxHockey, Pong, LightCycles, Snake), which had all independently converged on this
+// exact skeleton.
 //
-// Owns its own popover host shared by its own color/profile/difficulty pickers unless a `host` is
-// passed in to share with another panel (or a shared-controls row) instead - same convention as
-// every popover-hosting component in this package.
-export function PlayerSetupPanel<C extends string = string>({ idPrefix, host, label, labelFontFamily, color, onColorChange, swatches, takenColor, allowSwapTaken, colorAlignOverride, colorRotation, isHuman, secondPicker, secondPickerId, ready, onToggleReady, dark, showReadyButton = true, profiles, selectedProfileId, takenProfileId, guestLabel, onProfileSelect, onManageProfiles, cpuDifficulty, cpuDifficultyOptions, onCpuDifficultyChange, cpuDifficultyAlignOverride, humanIcon = 'face-man', cpuIcon = 'robot' }: PlayerSetupPanelProps<C>) {
+// Owns its own popover host shared by its own pickers unless a `host` is passed in to share with
+// another panel (or a shared-controls row) instead - same convention as every popover-hosting
+// component in this package.
+export function PlayerSetupPanel<C extends string = string>({ idPrefix, host, label, labelFontFamily, color, onColorChange, swatches, takenColor, allowSwapTaken, colorCaption, showColor = true, colorAlignOverride, colorRotation, isHuman, secondPicker, secondPickerId, ready, onToggleReady, dark, showReadyButton = true, profiles, selectedProfileId, takenProfileId, guestLabel, onProfileSelect, onManageProfiles, cpuDifficulty, cpuDifficultyOptions, onCpuDifficultyChange, humanIcon = 'face-man', cpuIcon = 'robot' }: PlayerSetupPanelProps<C>) {
   const ownHost = usePopoverHost()
   const popover = host ?? ownHost
   // Checking *this panel's own* ids, not just "is anything open on the host" - when `host` is
@@ -126,22 +134,33 @@ export function PlayerSetupPanel<C extends string = string>({ idPrefix, host, la
   // letting DOM order (wrongly) decide which one paints on top.
   const ownPopoverOpen = popover.openId?.startsWith(`${idPrefix}-`) ?? false
   // Narrower than ownPopoverOpen on purpose - only true for a popover actually inside pickerRow
-  // itself (color, or secondPicker's own popover when it has one and secondPickerId names it). See
-  // pickerRowOpen's own style comment for why pickerRow needs this in addition to panelOpen above.
+  // itself (the fallback color swatch, or secondPicker's own popover when it has one and
+  // secondPickerId names it). See pickerRowOpen's own style comment for why pickerRow needs this in
+  // addition to panelOpen above.
   const pickerRowPopoverOpen = popover.openId === getColorPopoverId(idPrefix) || (secondPickerId !== undefined && popover.openId === secondPickerId)
   const showProfilePicker = isHuman && profiles !== undefined && !!onProfileSelect
   const showCpuDifficulty = !isHuman && cpuDifficulty !== undefined && cpuDifficultyOptions !== undefined && !!onCpuDifficultyChange
-  // The color button's own tag display (see InlineColorPicker) - read live from the selected
-  // profile rather than snapshotted at selection time, since a caller typically has no other
-  // editing surface for it on this same screen.
+  const seatButton = showProfilePicker || showCpuDifficulty
+  // Read live from the selected profile rather than snapshotted at selection time, since a caller
+  // typically has no other editing surface for it on this same screen.
   const selectedProfile = profiles?.find((p) => p.id === selectedProfileId) ?? null
 
+  const colorSection: ProfilePickerColorSection | undefined = showColor ? { value: color, onChange: onColorChange, swatches, takenValue: takenColor, allowSwapTaken, caption: showProfilePicker && selectedProfile ? colorCaption : undefined } : undefined
+  // The seat button's dropdown is placed here rather than by the caller: inside a
+  // @tastic/split-screen zone (2 Player) it has to stay in that player's half, which
+  // useZoneClampedAlign does, and outside one it's useAutoAlign's own placement. Sized from the same
+  // section and rows the picker draws. Rotation 0, the same as the profile, color and difficulty
+  // dropdowns this button replaced were all placed with.
+  const seatPickerId = showProfilePicker ? getProfilePopoverId(idPrefix) : getCpuDifficultyPopoverId(idPrefix)
+  const seatPickerSize = showProfilePicker ? getProfilePickerContentSize(profiles!.length, !!onManageProfiles, colorSection) : getOptionPickerContentSize(cpuDifficultyOptions?.length ?? 0, colorSection)
+  const seatPickerAlign = useZoneClampedAlign(seatButton && popover.openId === seatPickerId, seatPickerSize.width, seatPickerSize.height)
+
   return (
     <View style={[styles.panel, ownPopoverOpen && styles.panelOpen]}>
       {showProfilePicker ? (
-        <ProfilePicker idPrefix={idPrefix} host={popover} profiles={profiles!} selectedId={selectedProfileId ?? null} takenId={takenProfileId} color={color} dark={dark} guestLabel={guestLabel ?? 'GUEST'} onSelect={(profile: Profile | null) => onProfileSelect?.(profile)} onManage={onManageProfiles} />
+        <ProfilePicker idPrefix={idPrefix} host={popover} profiles={profiles!} selectedId={selectedProfileId ?? null} takenId={takenProfileId} color={color} dark={dark} guestLabel={guestLabel ?? 'GUEST'} onSelect={(profile: Profile | null) => onProfileSelect?.(profile)} onManage={onManageProfiles} colorSection={colorSection} alignOverride={seatPickerAlign} />
       ) : showCpuDifficulty ? (
-        <LabeledDropdown id={getCpuDifficultyPopoverId(idPrefix)} host={popover} options={cpuDifficultyOptions!} value={cpuDifficulty!} onChange={onCpuDifficultyChange!} color={color} dark={dark} alignOverride={cpuDifficultyAlignOverride} />
+        <OptionPicker id={getCpuDifficultyPopoverId(idPrefix)} host={popover} options={cpuDifficultyOptions!} value={cpuDifficulty!} onChange={onCpuDifficultyChange!} color={color} dark={dark} icon={cpuIcon} colorSection={colorSection} alignOverride={seatPickerAlign} />
       ) : (
         label && (
           <Text variant='labelSmall' style={{ color, fontFamily: labelFontFamily }}>
@@ -150,14 +169,16 @@ export function PlayerSetupPanel<C extends string = string>({ idPrefix, host, la
         )
       )}
 
-      <View style={[styles.pickerRow, pickerRowPopoverOpen && styles.pickerRowOpen]}>
-        {/* Human slots show the selected profile's own tag when it has one, falling back to
-        humanIcon; a non-human slot always falls back to cpuIcon - this is what actually
-        distinguishes "you" from "the CPU" now, not a fixed icon. */}
-        <InlineColorPicker id={getColorPopoverId(idPrefix)} host={popover} value={color} onChange={onColorChange} swatches={swatches} takenValue={takenColor} allowSwapTaken={allowSwapTaken} alignOverride={colorAlignOverride} rotation={colorRotation} dark={dark} tag={isHuman ? selectedProfile?.tag : undefined} icon={isHuman ? humanIcon : cpuIcon} />
+      {(!seatButton || secondPicker) && (
+        <View style={[styles.pickerRow, pickerRowPopoverOpen && styles.pickerRowOpen]}>
+          {/* The fallback swatch, for a seat with no button: a human slot shows the selected
+          profile's own tag when it has one, falling back to humanIcon; a non-human slot always
+          falls back to cpuIcon. */}
+          {!seatButton && <InlineColorPicker id={getColorPopoverId(idPrefix)} host={popover} value={color} onChange={onColorChange} swatches={swatches} takenValue={takenColor} allowSwapTaken={allowSwapTaken} alignOverride={colorAlignOverride} rotation={colorRotation} dark={dark} tag={isHuman ? selectedProfile?.tag : undefined} icon={isHuman ? humanIcon : cpuIcon} />}
 
-        {secondPicker}
-      </View>
+          {secondPicker}
+        </View>
+      )}
 
       {isHuman && showReadyButton && onToggleReady && <ReadyButton color={color} ready={ready ?? false} onToggleReady={onToggleReady} />}
     </View>
@@ -175,9 +196,9 @@ const styles = StyleSheet.create({
   panelOpen: {
     zIndex: 100
   },
-  // Same gap as `panel`'s own vertical rhythm, reused horizontally - the color picker and (when
-  // present) secondPicker sit side by side within this row instead of stacked in the panel's own
-  // column.
+  // Same gap as `panel`'s own vertical rhythm, reused horizontally - the fallback color swatch and
+  // (when present) secondPicker sit side by side within this row instead of stacked in the panel's
+  // own column.
   pickerRow: {
     alignItems: 'center',
     flexDirection: 'row',

package/src/StatRow.tsx

@@ -1,29 +1,28 @@
-import { useAutoPaperTheme } from '@rific/auto-paper'
 import { StyleSheet, View } from 'react-native'
 import { Text } from 'react-native-paper'
 
+import { useWellColors } from './wellSurface'
+
 interface Props {
   label: string
   value: string
-  // Independently optional overrides for this row's own text colors - default to the same
-  // useAutoPaperTheme()-derived formula as BaseStatsScreen (see that component's own doc for why)
-  // when omitted, so every existing caller renders identically to before.
+  // Independently optional overrides for this row's own text colors - default to the text colors of the well it
+  // sits in (wellSurface.ts: onSurface, onSurfaceVariant).
   fg?: string
   fgMuted?: string
 }
 
 // A single labeled stat - label on the left (muted), value on the right (bold, full-contrast).
 // Extracted from LightCycles' own achievements.tsx, where this exact row shape backed every
-// section (Overall/Vs CPU/Two Player/Activity). fg/fgMuted default to the same
-// useAutoPaperTheme()-derived formula as BaseStatsScreen (see that component's own doc for why),
-// each independently overridable via the matching prop for a caller with its own chrome palette.
+// section (Overall/Vs CPU/Two Player/Activity). fg/fgMuted default to the text colors of the StatSection well it
+// sits in, each independently overridable via the matching prop for a caller with its own chrome palette.
 // Deliberately just label+value text, not a color swatch or profile chip - an app needing a row
-// with a leading visual builds its own on top of this same dark-mode formula (see LightCycles' own
+// with a leading visual builds its own on top of the same useWellColors() (see LightCycles' own
 // ColorStatRow/ProfileRankingRow for an example), since what that visual even is varies per game.
 export function StatRow({ label, value, fg: fgOverride, fgMuted: fgMutedOverride }: Props) {
-  const { dark } = useAutoPaperTheme()
-  const fg = fgOverride ?? (dark ? '#FFFFFF' : '#000000')
-  const fgMuted = fgMutedOverride ?? (dark ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)')
+  const well = useWellColors()
+  const fg = fgOverride ?? well.fg
+  const fgMuted = fgMutedOverride ?? well.fgMuted
 
   return (
     <View style={styles.row}>

package/src/StatSection.tsx

@@ -1,29 +1,28 @@
-import { useAutoPaperTheme } from '@rific/auto-paper'
 import { ReactNode } from 'react'
 import { StyleSheet, View } from 'react-native'
 import { Text } from 'react-native-paper'
 
+import { useWellColors, WELL_SHADOW } from './wellSurface'
+
 interface Props {
   label: string
-  // Independently optional overrides for this section's own label color/background - default to
-  // the same useAutoPaperTheme()-derived formula as StatRow/BaseStatsScreen (see BaseStatsScreen's
-  // own doc for why) when omitted, so every existing caller renders identically to before.
+  // Independently optional overrides for this section's own label color/background - default to the well's
+  // (wellSurface.ts: the theme's surface and its onSurface text).
   fg?: string
   sectionBg?: string
   children: ReactNode
 }
 
-// A labeled, tinted-background grouping box - the "OVERALL"/"VS CPU"/"ACTIVITY"-style section
-// shape from LightCycles' own achievements.tsx, generalized to any content (typically a stack of
-// StatRow). fg/sectionBg default to the same useAutoPaperTheme()-derived formula as
-// StatRow/BaseStatsScreen (see BaseStatsScreen's own doc for why), each independently overridable
-// via the matching prop for a caller with its own chrome palette. The label itself carries the
-// section's own meaning (what it's a section OF), so this component has no opinion on that beyond
-// rendering the string it's given.
+// A labeled grouping box, a well (wellSurface.ts: the theme's surface on MD3's level-1 shadow) - the
+// "OVERALL"/"VS CPU"/"ACTIVITY"-style section shape from LightCycles' own achievements.tsx, generalized to any
+// content (typically a stack of StatRow). fg/sectionBg default to the well's colors, each independently
+// overridable via the matching prop for a caller with its own chrome palette. It was a faint tint until
+// 2026-10-17 (6% white in dark mode, 4% black in light). The label itself carries the section's own meaning
+// (what it's a section OF), so this component has no opinion on that beyond rendering the string it's given.
 export function StatSection({ label, fg: fgOverride, sectionBg: sectionBgOverride, children }: Props) {
-  const { dark } = useAutoPaperTheme()
-  const fg = fgOverride ?? (dark ? '#FFFFFF' : '#000000')
-  const sectionBg = sectionBgOverride ?? (dark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.04)')
+  const well = useWellColors()
+  const fg = fgOverride ?? well.fg
+  const sectionBg = sectionBgOverride ?? well.bg
 
   return (
     <View style={[styles.section, { backgroundColor: sectionBg }]}>
@@ -46,6 +45,7 @@ const styles = StyleSheet.create({
   },
   section: {
     borderRadius: 12,
+    boxShadow: WELL_SHADOW,
     gap: 8,
     padding: 16
   }

package/src/chrome/index.ts

@@ -23,3 +23,4 @@ export { StatRow } from '../StatRow'
 export { StatSection } from '../StatSection'
 export { UpdateDialog, type UpdateDialogProps } from '../UpdateDialog'
 export { useCompactDialog } from '../useCompactDialog'
+export { useWellColors, WELL_SHADOW, type WellColors } from '../wellSurface'

package/src/index.ts

@@ -16,7 +16,7 @@ export { getLabeledDropdownContentHeight, LABELED_DROPDOWN_POPOVER_WIDTH, Labele
 export { loadSkiaWeb } from './loadSkiaWeb'
 export { overlayActionStyles, overlayStyles } from './overlayCard'
 export { OverlayBackdrop, type OverlayBackdropProps, OverlayCard, type OverlayCardProps, type OverlayCardThemeColors, useOverlayCardColors } from './OverlaySurface'
-export { getColorPopoverId, getCpuDifficultyPopoverId, PlayerSetupPanel, type PlayerSetupPanelProps } from './PlayerSetupPanel'
+export { getColorPopoverId, getCpuDifficultyPopoverId, getProfilePopoverId, PlayerSetupPanel, type PlayerSetupPanelProps } from './PlayerSetupPanel'
 export { PopoverBody } from './PopoverBody'
 export { PressAwayOverlay } from './PressAwayOverlay'
 export { ReadyButton } from './ReadyButton'
@@ -42,3 +42,4 @@ export { useCompactDialog } from './useCompactDialog'
 export { type PopoverHost, usePopoverHost } from './usePopoverHost'
 export { type QuitConfirmation, useQuitConfirmation } from './useQuitConfirmation'
 export { useZoneClampedAlign } from './useZoneClampedAlign'
+export { useWellColors, WELL_SHADOW, type WellColors } from './wellSurface'

package/src/wellSurface.ts

@@ -0,0 +1,30 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+
+// A well is a resting card on a screen: a stats section, an achievement row, a game's menu tile. Every well in the
+// fleet is the theme's plain surface (the same surface as the dialogs, OverlayCard and auto-paper's Dialog) lifted off
+// the screen by MD3's level-1 shadow, with no elevation tint (Jay, 2026-10-17: Solitaire's Achievements wells read as
+// a different shade from its Home tiles, and he picked "shadow, no tint" over MD3's tonal elevation, which washes the
+// surface with the primary like the dialogs no longer are).
+//
+// The shadow is what makes a well show on a screen the color of the surface: MD3 (as react-native-paper implements it)
+// gives `background` and `surface` the same tone, and BaseStatsScreen's light-mode #FFFFFF is the same as the light
+// surface to the eye. In dark mode the surface is already lighter than a black screen, and the shadow barely shows.
+
+// MD3's level-1 elevation shadow (its web spec's two layers: a tight key shadow and a soft ambient one). boxShadow is
+// drawn outside the view on iOS, Android and web alike, so a well's own background is never darkened by it.
+export const WELL_SHADOW = '0px 1px 2px rgba(0, 0, 0, 0.3), 0px 1px 3px 1px rgba(0, 0, 0, 0.15)'
+
+export interface WellColors {
+  // The well's own background.
+  bg: string
+  // Text on the well: titles and values, then labels and descriptions.
+  fg: string
+  fgMuted: string
+}
+
+// The colors of a well and the text on it, from the app's own theme: the same roles the dialogs' text uses
+// (useOverlayCardColors).
+export function useWellColors(): WellColors {
+  const { colors } = useAutoPaperTheme()
+  return { bg: colors.surface, fg: colors.onSurface, fgMuted: colors.onSurfaceVariant }
+}