@tastic/hud 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastic/hud",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Visual component kit for local-multiplayer React Native games: inline (non-modal) popovers, dropdowns, color pickers, gauges, ready buttons, and dialogs, built to stay scoped to one player's own zone on a shared screen",
   "keywords": [
     "react-native",
@@ -88,7 +88,7 @@
     "@infinitetoken/jest-config": "^0.5.2",
     "@infinitetoken/tsconfig": "^0.6.0",
     "@rific/auto-paper": "^0.13.3",
-    "@rific/core": "^0.3.1",
+    "@rific/core": "^0.4.0",
     "@rific/feedback-press": "^0.13.0",
     "@rific/updater": "^0.7.1",
     "@shopify/react-native-skia": "^2.14.0",
@@ -117,6 +117,7 @@
   },
   "peerDependencies": {
     "@rific/auto-paper": "^0.13.0",
+    "@rific/core": ">=0.4.0",
     "@rific/feedback-press": ">=0.10.2",
     "@rific/updater": ">=0.4.0",
     "@shopify/react-native-skia": ">=2.6.0",

package/src/AchievementCatalogSection.tsx

@@ -15,12 +15,13 @@ import { MONO_FONT } from './fonts'
 interface Props {
   rows: AchievementCatalogRow[]
   label?: string
-  // Independently optional overrides for this section's own heading/row colors - default to the
-  // same useAutoPaperTheme()-derived formula as AchievementRow/StatSection/StatRow/BaseStatsScreen
-  // (see BaseStatsScreen's own doc for why) when omitted, so every existing caller renders
-  // identically to before. Passed straight through to each <AchievementRow>.
+  // Independently optional overrides for the heading's and rows' colors. fg and sectionBg go to each
+  // <AchievementRow> (whose own defaults are the well's, see wellSurface.ts). fgMuted goes to the heading and
+  // the rows; omitted, the heading (drawn on the screen, not on a well) keeps its own screen-derived default
+  // and the rows theirs.
   fg?: string
   fgMuted?: string
+  sectionBg?: string
 }
 
 // The "ALL ACHIEVEMENTS" heading + one <AchievementRow> per row - extracted verbatim from every
@@ -42,7 +43,7 @@ interface Props {
 // about 1.4:1 and 1.8:1 against the light screen's white, so a bar or check in either barely shows;
 // mixed, they're about 5:1 and 6:1 (bronze goes from about 3:1 to 9:1). The badge keeps the true tier
 // color: its glyph is black, which reads on all three.
-export function AchievementCatalogSection({ rows, label = 'ALL ACHIEVEMENTS', fg, fgMuted: fgMutedOverride }: Props) {
+export function AchievementCatalogSection({ rows, label = 'ALL ACHIEVEMENTS', fg, fgMuted: fgMutedOverride, sectionBg }: Props) {
   const { dark } = useAutoPaperTheme()
   const fgMuted = fgMutedOverride ?? (dark ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)')
   const tierAccent = (tierColor: string) => (dark ? tierColor : getBlendedColor('#000000', tierColor, 0.5))
@@ -53,7 +54,7 @@ export function AchievementCatalogSection({ rows, label = 'ALL ACHIEVEMENTS', fg
         {label}
       </Text>
       {rows.map((row) => (
-        <AchievementRow key={row.id} icon={row.icon} title={row.title} description={row.description} badgeColor={row.unlockedAt !== undefined ? row.tierColor : LOCKED_BADGE_COLOR} checkColor={tierAccent(row.tierColor)} unlockedLabel={row.unlockedLabel} progress={row.progress} deviceMarker={row.deviceMarker} fg={fg} fgMuted={fgMutedOverride} />
+        <AchievementRow key={row.id} icon={row.icon} title={row.title} description={row.description} badgeColor={row.unlockedAt !== undefined ? row.tierColor : LOCKED_BADGE_COLOR} checkColor={tierAccent(row.tierColor)} unlockedLabel={row.unlockedLabel} progress={row.progress} deviceMarker={row.deviceMarker} fg={fg} fgMuted={fgMutedOverride} sectionBg={sectionBg} />
       ))}
     </Fragment>
   )

package/src/AchievementRow.tsx

@@ -1,7 +1,8 @@
-import { useAutoPaperTheme } from '@rific/auto-paper'
 import { StyleSheet, View } from 'react-native'
 import { Icon, ProgressBar, Text } from 'react-native-paper'
 
+import { useWellColors, WELL_SHADOW } from './wellSurface'
+
 // A neutral gray for a locked badge's own background - exported so a caller computing its own
 // badge color (unlocked ? tierColor : LOCKED_BADGE_COLOR, matching LightCycles' own achievements.tsx)
 // doesn't need to invent or duplicate this exact tone.
@@ -32,10 +33,9 @@ interface Props {
   // from a specific profile's own tab - optional since only an app with per-profile stat views has
   // this concept at all.
   deviceMarker?: boolean
-  // Independently optional overrides for this row's own text/background colors - each defaults to
-  // the same dark-mode-derived formula as StatRow/StatSection/BaseStatsScreen (see that component's
-  // own doc for why) when omitted, so every existing caller renders identically to before. A caller
-  // with its own app-wide chrome palette passes whichever of the three it needs.
+  // Independently optional overrides for this row's own text/background colors - each defaults to the well's
+  // (wellSurface.ts: the theme's surface and its onSurface/onSurfaceVariant text), like StatSection/StatRow. A
+  // caller with its own app-wide chrome palette passes whichever of the three it needs.
   fg?: string
   fgMuted?: string
   sectionBg?: string
@@ -44,16 +44,15 @@ interface Props {
 // One row per achievement - a tier-colored (or locked-gray) badge, title/description, an optional
 // progress bar while locked, and either an unlocked check-mark+label or a lock icon. Extracted
 // verbatim from LightCycles' own achievements.tsx, where this exact row shape backed its entire
-// "ALL ACHIEVEMENTS" list. fg/fgMuted/its own section background default to the same
-// useAutoPaperTheme()-derived formula as StatRow/StatSection/BaseStatsScreen (see BaseStatsScreen's
-// own doc for why), each independently overridable via the matching prop for a caller with its own
-// chrome palette. Has no opinion on what an achievement actually IS (id, unlock predicate, catalog)
+// "ALL ACHIEVEMENTS" list. Each row is its own well (wellSurface.ts: the theme's surface on MD3's level-1 shadow);
+// fg/fgMuted/its own background default to the well's colors, each independently overridable via the matching
+// prop for a caller with its own chrome palette. Has no opinion on what an achievement actually IS (id, unlock predicate, catalog)
 // - that stays entirely app-local; this is purely the presentational row.
 export function AchievementRow({ icon, title, description, badgeColor, unlockedLabel, checkColor, progress, deviceMarker, fg: fgOverride, fgMuted: fgMutedOverride, sectionBg: sectionBgOverride }: 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 sectionBg = sectionBgOverride ?? (dark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.04)')
+  const well = useWellColors()
+  const fg = fgOverride ?? well.fg
+  const fgMuted = fgMutedOverride ?? well.fgMuted
+  const sectionBg = sectionBgOverride ?? well.bg
   const unlocked = unlockedLabel !== undefined
 
   return (
@@ -116,6 +115,7 @@ const styles = StyleSheet.create({
   row: {
     alignItems: 'center',
     borderRadius: 12,
+    boxShadow: WELL_SHADOW,
     flexDirection: 'row',
     gap: 12,
     padding: 12

package/src/ActivityStatSection.tsx

@@ -9,6 +9,11 @@ interface ActivityStats {
 
 interface Props {
   stats: ActivityStats
+  // Optional overrides for the section's and its rows' colors, passed straight through to StatSection and each
+  // StatRow (whose own defaults are the well's, see wellSurface.ts) - for a caller with its own chrome palette.
+  fg?: string
+  fgMuted?: string
+  sectionBg?: string
 }
 
 // The "ACTIVITY" StatSection (Days Played / Day Streak / Best Day Streak) - extracted verbatim
@@ -18,12 +23,12 @@ interface Props {
 // currentDayStreak/bestDayStreak) rather than importing DayStreakState itself, so this component
 // has no dependency on @tastic/achievements at all: any caller's own stats/statsView object that
 // happens to carry these three fields already satisfies it structurally.
-export function ActivityStatSection({ stats }: Props) {
+export function ActivityStatSection({ stats, fg, fgMuted, sectionBg }: Props) {
   return (
-    <StatSection label='ACTIVITY'>
-      <StatRow label='Days Played' value={String(stats.distinctDaysPlayed)} />
-      <StatRow label='Day Streak' value={String(stats.currentDayStreak)} />
-      <StatRow label='Best Day Streak' value={String(stats.bestDayStreak)} />
+    <StatSection label='ACTIVITY' fg={fg} sectionBg={sectionBg}>
+      <StatRow label='Days Played' value={String(stats.distinctDaysPlayed)} fg={fg} fgMuted={fgMuted} />
+      <StatRow label='Day Streak' value={String(stats.currentDayStreak)} fg={fg} fgMuted={fgMuted} />
+      <StatRow label='Best Day Streak' value={String(stats.bestDayStreak)} fg={fg} fgMuted={fgMuted} />
     </StatSection>
   )
 }

package/src/BaseSettingsDialog.tsx

@@ -1,4 +1,5 @@
 import { AutoAppearancePicker, Dialog, FadingScrollView, useAutoPaperTheme, useBlurModule, useThemeSettings } from '@rific/auto-paper'
+import { useExpoKeepAwake, useKeepAwakeSettings } from '@rific/core'
 import { Button, SoundContext, TouchableRipple, useHapticSettings, useSoundSettings, useVibration } from '@rific/feedback-press'
 import { useUpdater } from '@rific/updater'
 import { rotateInsets, useIsTouchPrimaryDevice, useRotation, type ViewRotation } from '@tastic/core'
@@ -56,13 +57,7 @@ export interface BaseSettingsDialogProps {
   // @tastic/edge-guard's own swizzle is a no-op on every other platform.
   deferBottomEdgeGestures?: boolean
   onDeferBottomEdgeGestures?: (value: boolean) => void
-  // Optional, and always passed as a pair - omit both for an app that doesn't keep the screen awake.
-  // This dialog only shows and reports the toggle; the app itself keeps the screen on while it's set
-  // (expo-keep-awake on its match screen), so this package needs no native dependency for it. Shown
-  // on the same devices as Lock Orientation (see isTouchPrimary below): a desktop/laptop browser
-  // stays awake on its own while someone is playing with its keyboard or mouse.
-  keepAwake?: boolean
-  onKeepAwakeChange?: (value: boolean) => void
+  // No Keep Awake props: that row reads @rific/core's Keep Awake setting itself (see showKeepAwake).
   // Explicit opt-outs for the rows that pull their own state straight from @rific/feedback-press,
   // @rific/auto-paper, and @rific/updater's own shared contexts/hooks rather than from anything the
   // caller passes in - unlike Lock Orientation/Edge Guard above, there's no "value" to omit for
@@ -97,7 +92,7 @@ export interface BaseSettingsDialogProps {
 // is the seam for whatever isn't shared: a game with its own board/difficulty settings (or a stats
 // backup flow, or anything else genuinely specific to it) renders those below Appearance, not by
 // forking this component.
-export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverride, version, lockOrientation, onLockOrientationChange, deferBottomEdgeGestures, onDeferBottomEdgeGestures, keepAwake, onKeepAwakeChange, hideSound = false, hideHaptics = false, hideAppearance = false, hideUpdateCheck = false, onUpdateError, onShowHowToPlay, children }: BaseSettingsDialogProps) {
+export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverride, version, lockOrientation, onLockOrientationChange, deferBottomEdgeGestures, onDeferBottomEdgeGestures, hideSound = false, hideHaptics = false, hideAppearance = false, hideUpdateCheck = false, onUpdateError, onShowHowToPlay, children }: BaseSettingsDialogProps) {
   const { colors } = useAutoPaperTheme()
   const ambientRotation = useRotation()
   const rotation = rotationOverride ?? ambientRotation
@@ -113,7 +108,7 @@ export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverr
   // Dialog's own 32pt padding is simply overhung.
   const insets = rotateInsets(useSafeAreaInsets(), rotation)
   const sheetWidth = Math.min(overlayStyles.card.maxWidth, (turned ? window.height : window.width) - 2 * Math.max(insets.left, insets.right, SHEET_GUTTER))
-  // Also gates the Lock Orientation and Keep Awake rows below (alongside their own props) - true
+  // Also gates the Lock Orientation and Keep Awake rows below (alongside their own conditions) - true
   // unconditionally on native (see the hook's own doc), so this only actually excludes a
   // desktop/laptop browser, where a mouse-driven window has no physical orientation to lock
   // against; a resize there would just make the setting silently stop reflowing the layout instead
@@ -121,6 +116,8 @@ export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverr
   const isTouchPrimary = useIsTouchPrimaryDevice()
   const { settings: hapticSettings, set: setHapticSettings } = useHapticSettings()
   const { settings: soundSettings, set: setSoundSettings } = useSoundSettings()
+  const { settings: keepAwakeSettings, set: setKeepAwakeSettings } = useKeepAwakeSettings()
+  const expoKeepAwake = useExpoKeepAwake()
   // Sound/Haptics toggle themselves: the ripple's automatic press feedback fires on onPressIn,
   // before onPress applies the toggle, so it reflects the OLD enabled value - backwards from what
   // a settings toggle should confirm (turning off would click/buzz, turning on would go silent).
@@ -160,7 +157,10 @@ export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverr
 
   const showLockOrientation = isTouchPrimary && lockOrientation !== undefined && onLockOrientationChange !== undefined
   const showEdgeGuard = Platform.OS === 'ios' && deferBottomEdgeGestures !== undefined && onDeferBottomEdgeGestures !== undefined
-  const showKeepAwake = isTouchPrimary && keepAwake !== undefined && onKeepAwakeChange !== undefined
+  // Only in an app that opted in by handing expo-keep-awake to @rific/core's KeepAwakeProvider:
+  // without the module the setting would do nothing. On the same devices as Lock Orientation, since a
+  // desktop/laptop browser stays awake on its own while someone plays with its keyboard or mouse.
+  const showKeepAwake = isTouchPrimary && expoKeepAwake !== undefined
   const showHaptics = Platform.OS !== 'web' && !hideHaptics
   const showSound = !hideSound
   const showAppearance = !hideAppearance
@@ -243,11 +243,11 @@ export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverr
                     </TouchableRipple>
                   )}
 
-                  {/* See the keepAwake prop's own doc: the app does the keeping awake, this only toggles it. */}
+                  {/* The app's own useKeepAwake('game') does the keeping awake; this only flips the shared setting. */}
                   {showKeepAwake && (
-                    <TouchableRipple onPress={() => onKeepAwakeChange!(!keepAwake)} style={styles.toggleButton} accessibilityLabel={`Keep awake ${keepAwake ? 'on' : 'off'}`}>
+                    <TouchableRipple onPress={() => setKeepAwakeSettings({ enabled: !keepAwakeSettings.enabled })} style={styles.toggleButton} accessibilityLabel={`Keep awake ${keepAwakeSettings.enabled ? 'on' : 'off'}`}>
                       <View style={styles.toggleContent}>
-                        <SettingIcon source={keepAwake ? 'eye' : 'eye-closed'} color={keepAwake ? colors.tertiary : colors.onSurfaceVariant} containerColor={keepAwake ? colors.tertiaryContainer : colors.surfaceVariant} />
+                        <SettingIcon source={keepAwakeSettings.enabled ? 'eye' : 'eye-closed'} color={keepAwakeSettings.enabled ? colors.tertiary : colors.onSurfaceVariant} containerColor={keepAwakeSettings.enabled ? colors.tertiaryContainer : colors.surfaceVariant} />
                         <View style={styles.flexShrink}>
                           <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
                             Keep Awake

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

@@ -1,8 +1,11 @@
 // The fleet-chrome entry point (`@tastic/hud/chrome`): the shared dialogs, stats screen pieces, corner
-// buttons and style tokens, reachable without the main barrel, for an app that has none of its heavy
-// peers. Hangman is the reason it exists: it has @tastic/core, @rific/updater and the Paper stack, but
-// no Skia, no @tastic/profile and no @tastic/split-screen. Everything reachable from this file must stay
-// free of those three and of the main barrel; @tastic/achievements may appear only as `import type`.
+// buttons, popover primitives, color picker and style tokens, reachable without the main barrel, for an
+// app that has none of its heavy peers. Hangman is the reason it exists: it has @tastic/core,
+// @rific/updater and the Paper stack, but no Skia, no @tastic/profile and no @tastic/split-screen. The
+// popover pieces (PopoverBody, PressAwayOverlay, usePopoverHost, useAutoAlign) and InlineColorPicker are
+// here for @tastic/profile 0.16+, which imports them from this entry instead of the main barrel so its
+// ProfilePicker and ProfilesScreen work in Hangman. Everything reachable from this file must stay free of
+// those three and of the main barrel; @tastic/achievements may appear only as `import type`.
 // AchievementUnlockList is left out on purpose because it value-imports @tastic/profile's ProfileChip.
 // src/__tests__/chromeImports.test.ts walks the real import graph from here and enforces all of it.
 export { AchievementCatalogSection } from '../AchievementCatalogSection'
@@ -15,11 +18,17 @@ export { ContentGutter } from '../ContentGutter'
 export { CornerActionButtons } from '../CornerActionButtons'
 export { COMPACT_DIALOG_HEIGHT, DialogHeader, type DialogHeaderProps, isCompactDialogHeight } from '../DialogHeader'
 export { MONO_FONT } from '../fonts'
+export { getInlineColorPickerContentSize, InlineColorPicker } from '../InlineColorPicker'
 export { overlayActionStyles, overlayStyles } from '../overlayCard'
 export { OverlayBackdrop, type OverlayBackdropProps, OverlayCard, type OverlayCardProps, type OverlayCardThemeColors, useOverlayCardColors } from '../OverlaySurface'
+export { PopoverBody } from '../PopoverBody'
+export { PressAwayOverlay } from '../PressAwayOverlay'
 export { RotatedFrame, type RotatedFrameProps } from '../RotatedFrame'
 export { getStaggeredWordDuration, StaggeredWord, type StaggeredWordProps } from '../StaggeredWord'
 export { StatRow } from '../StatRow'
 export { StatSection } from '../StatSection'
 export { UpdateDialog, type UpdateDialogProps } from '../UpdateDialog'
+export { type AlignResult, type PopoverAlign, type PopoverRotation, type PopoverVerticalAlign, useAutoAlign } from '../useAutoAlign'
 export { useCompactDialog } from '../useCompactDialog'
+export { type PopoverHost, usePopoverHost } from '../usePopoverHost'
+export { useWellColors, WELL_SHADOW, type WellColors } from '../wellSurface'

package/src/index.ts

@@ -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 }
+}