@tastic/hud 0.8.4 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastic/hud",
-  "version": "0.8.4",
+  "version": "0.12.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",
@@ -71,14 +71,17 @@
   "prettier": "@infinitetoken/eslint-config/prettier",
   "devDependencies": {
     "@infinitetoken/eslint-config": "^0.2.0",
-    "@infinitetoken/jest-config": "^0.3.0",
-    "@infinitetoken/tsconfig": "^0.4.1",
-    "@rific/auto-paper": "^0.11.0",
-    "@rific/core": "^0.1.1",
-    "@rific/feedback-press": "^0.11.1",
+    "@infinitetoken/jest-config": "^0.4.0",
+    "@infinitetoken/tsconfig": "^0.5.0",
+    "@rific/auto-paper": "^0.12.0",
+    "@rific/core": "^0.2.0",
+    "@rific/feedback-press": "^0.12.0",
     "@rific/updater": "^0.6.0",
     "@shopify/react-native-skia": "^2.6.2",
-    "@tastic/core": "^0.4.1",
+    "@tastic/achievements": "^0.2.0",
+    "@tastic/core": "^0.8.0",
+    "@tastic/profile": "^0.7.0",
+    "@tastic/split-screen": "^0.5.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^30.0.0",
@@ -94,6 +97,7 @@
     "react-native": "^0.85.3",
     "react-native-paper": "^5.15.2",
     "react-native-reanimated": "^4.5.1",
+    "react-native-safe-area-context": "^5.10.0",
     "tsup": "^8.0.0",
     "typescript": "^6.0.3"
   },
@@ -102,11 +106,15 @@
     "@rific/feedback-press": ">=0.10.0",
     "@rific/updater": ">=0.4.0",
     "@shopify/react-native-skia": ">=1.5.0",
+    "@tastic/achievements": ">=0.1.2",
     "@tastic/core": ">=0.3.0",
+    "@tastic/profile": ">=0.4.0",
+    "@tastic/split-screen": ">=0.5.0",
     "react": ">=19.0.0",
     "react-native": ">=0.76.0",
     "react-native-paper": ">=5.0.0",
-    "react-native-reanimated": ">=3.0.0"
+    "react-native-reanimated": ">=3.0.0",
+    "react-native-safe-area-context": ">=5.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/AchievementCatalogSection.tsx

@@ -0,0 +1,60 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import type { AchievementCatalogRow } from '@tastic/achievements'
+import { Fragment } from 'react'
+import { StyleSheet } from 'react-native'
+import { Text } from 'react-native-paper'
+
+import { AchievementRow, LOCKED_BADGE_COLOR } from './AchievementRow'
+import { MONO_FONT } from './fonts'
+
+// AchievementCatalogRow now comes straight from @tastic/achievements' own getAchievementCatalogRows
+// (added in the same 2026-09-18 achievements-scaffolding pass this component belongs to) — no
+// longer duplicated locally now that package has actually published the export (confirmed the two
+// shapes match exactly before wiring this real, type-only peer dependency).
+
+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>.
+  fg?: string
+  fgMuted?: string
+}
+
+// The "ALL ACHIEVEMENTS" heading + one <AchievementRow> per row - extracted verbatim from every
+// fleet app's own achievements.tsx (Snake, AirHockey, BoxHockey, Pong, LightCycles), where this
+// exact heading/list pair backed the bottom of the stats screen. Returns a Fragment, not a View:
+// every existing call site rendered the heading and each row as flat siblings inside
+// BaseStatsScreen's own gap-spaced ScrollView content, and wrapping them in a container here would
+// change that spacing (BaseStatsScreen's own `content` style already supplies the gap between
+// every child, this component included).
+//
+// Resolves each row's own locked-vs-unlocked badgeColor (tierColor when unlocked,
+// LOCKED_BADGE_COLOR when not) here rather than upstream in row computation, matching
+// AchievementRow's own "badge color is a rendering decision" doc comment - @tastic/achievements'
+// (pending) getAchievementCatalogRows deliberately leaves tierColor unresolved-to-badgeColor for
+// the same reason.
+export function AchievementCatalogSection({ rows, label = 'ALL ACHIEVEMENTS', fg, fgMuted: fgMutedOverride }: Props) {
+  const { dark } = useAutoPaperTheme()
+  const fgMuted = fgMutedOverride ?? (dark ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)')
+
+  return (
+    <Fragment>
+      <Text variant='labelMedium' style={[styles.label, { color: fgMuted, fontFamily: MONO_FONT }]}>
+        {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={row.tierColor} unlockedLabel={row.unlockedLabel} progress={row.progress} deviceMarker={row.deviceMarker} fg={fg} fgMuted={fgMutedOverride} />
+      ))}
+    </Fragment>
+  )
+}
+
+const styles = StyleSheet.create({
+  label: {
+    letterSpacing: 2,
+    marginTop: 8
+  }
+})

package/src/ActivityStatSection.tsx

@@ -0,0 +1,29 @@
+import { StatRow } from './StatRow'
+import { StatSection } from './StatSection'
+
+interface ActivityStats {
+  distinctDaysPlayed: number
+  currentDayStreak: number
+  bestDayStreak: number
+}
+
+interface Props {
+  stats: ActivityStats
+}
+
+// The "ACTIVITY" StatSection (Days Played / Day Streak / Best Day Streak) - extracted verbatim
+// from every fleet app's own achievements.tsx (Snake, AirHockey, BoxHockey, Pong, LightCycles),
+// where this exact three-row block was byte-for-byte identical. ActivityStats is a plain
+// structural type (matching @tastic/achievements' own DayStreakState shape - distinctDaysPlayed/
+// 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) {
+  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>
+  )
+}

package/src/ConfirmDialog.tsx

@@ -42,6 +42,7 @@ export function ConfirmDialog({ visible, title, message, confirmLabel, cancelLab
   const { fg, cardBg, cardBorder } = getOverlayCardColors(dark)
   const accent = destructive ? colors.danger : colors.primary
   const onAccent = destructive ? colors.onDanger : colors.onPrimary
+  const showCancel = cancelLabel !== undefined && onCancel !== undefined
 
   return (
     <Portal>
@@ -55,12 +56,12 @@ export function ConfirmDialog({ visible, title, message, confirmLabel, cancelLab
             {message}
           </Text>
           <View style={styles.actions}>
-            {cancelLabel !== undefined && onCancel !== undefined && (
+            {showCancel && (
               <Button mode='outlined' onPress={onCancel} style={styles.actionButton}>
                 {cancelLabel}
               </Button>
             )}
-            <Button mode='contained' onPress={onConfirm} style={styles.actionButton} buttonColor={accent} textColor={onAccent}>
+            <Button mode='contained' onPress={onConfirm} style={showCancel ? styles.actionButton : styles.actionButtonSingle} buttonColor={accent} textColor={onAccent}>
               {confirmLabel}
             </Button>
           </View>
@@ -71,25 +72,43 @@ export function ConfirmDialog({ visible, title, message, confirmLabel, cancelLab
 }
 
 const styles = StyleSheet.create({
-  // flexBasis (not flex: 1's own 0%) is each button's real floor: whenever both fit side by side,
-  // flexGrow still splits any leftover width evenly beyond that floor, same visual result as the
-  // old flex: 1 on a roomy screen - but a button can never be squeezed narrower than 128, only
-  // wrap to its own row instead (see actions' flexWrap below). react-native-paper's Button
+  // minWidth (not flexBasis) is each button's real floor - whenever both fit side by side, flexGrow
+  // still splits any leftover width evenly beyond that floor, same visual result as a plain flex: 1
+  // on a roomy screen, but a button can never be squeezed narrower than 128, only wrap to its own
+  // row instead (see actions' flexWrap below). This used to be flexBasis: 128, which measured
+  // correctly on web but rendered every button roughly SQUARE on iOS - confirmed live (see the
+  // "Quit Match?" Cancel/Quit buttons and the single-button "OK" dialogs both coming out ~128pt
+  // tall instead of wide). Root cause: react-native-paper's Button renders its Surface as two
+  // nested views on iOS only (Surface.tsx's SurfaceIOS, for shadow rendering) - only a curated
+  // allowlist of style keys (flex/flexGrow/flexShrink/width/height/position/... - notably NOT
+  // flexBasis) reaches the outer view, which is the real flex item inside this row; every other
+  // key, flexBasis included, falls through to an inner view whose own unspecified flexDirection
+  // defaults to column. flexGrow: 1 landed on the (row-context) outer view and grew width
+  // correctly; flexBasis: 128 landed on the (column-context) inner view instead, where a flexBasis
+  // sets HEIGHT, not width. minWidth isn't axis-relative like flexBasis, so it constrains width
+  // correctly regardless of which of the two views it ends up on. react-native-paper's Button also
   // hardcodes numberOfLines={1} on its label with no override, so a button squeezed under its
   // label's natural width silently ellipsizes ("Cancel" -> "Can...") instead of wrapping - assumed
   // fixable by just giving the row more width, until confirmed live that these two-word labels
   // (Cancel/Reset/New Game) can still lose the truncation fight even with the extra room card's own
-  // width fix below provides, on a narrow enough screen. flexBasis is the real fix: past a certain
-  // width there's no side-by-side arrangement that fits both buttons at their natural label size,
-  // so the layout has to give (stack) rather than the label (truncate).
+  // width fix below provides, on a narrow enough screen.
   actionButton: {
-    flexBasis: 128,
-    flexGrow: 1
+    flexGrow: 1,
+    minWidth: 128
+  },
+  // A lone confirm button (no cancel - BaseSettingsDialog's info-only "OK" dialogs, e.g. the
+  // update-check "no update found" message) has nothing left to share actions' width with, so
+  // actionButton's own flexGrow: 1 would stretch it across the entire row instead of reading as a
+  // normal button. Same 128 floor, no flexGrow, so it stays at that natural size instead of filling
+  // the card - centered by actions' own justifyContent below.
+  actionButtonSingle: {
+    minWidth: 128
   },
   actions: {
     flexDirection: 'row',
     flexWrap: 'wrap',
     gap: 12,
+    justifyContent: 'center',
     width: '100%'
   },
   body: {

package/src/ControlSchemePicker.tsx

@@ -2,6 +2,7 @@ import { useIsTouchPrimaryDevice } from '@tastic/core'
 import { Platform } from 'react-native'
 
 import { MenuOption, SectionedDropdown } from './SectionedDropdown'
+import { AlignResult, PopoverRotation } from './useAutoAlign'
 import { PopoverHost } from './usePopoverHost'
 
 export interface ControlSchemePickerProps<T extends string | number> {
@@ -21,6 +22,14 @@ export interface ControlSchemePickerProps<T extends string | number> {
   onAccentColor?: string
   dark: boolean
   align?: 'left' | 'right' | 'center'
+  // Passed straight through to the underlying SectionedDropdown — see that component's own
+  // `alignOverride` doc. Lets a caller inside a @tastic/split-screen zone substitute
+  // useZoneClampedAlign's result for this picker's own popover placement.
+  alignOverride?: AlignResult
+  // Passed straight through to the underlying SectionedDropdown — see that component's own
+  // `rotation` doc. Defaults to a live ambient useRotation() read when omitted, same as
+  // SectionedDropdown itself.
+  rotation?: PopoverRotation
   labelFontFamily?: string
 }
 
@@ -45,9 +54,9 @@ export interface ControlSchemePickerProps<T extends string | number> {
 // no keys of their own (a "keep using pointer input" option, say) are purely a per-app label — so a
 // caller always supplies its own `options` (and typically its own `T`) rather than this component
 // importing `@tastic/input` and choosing a set for every consumer.
-export function ControlSchemePicker<T extends string | number>({ id, host, value, onChange, options, takenValue, accentColor, mutedColor, onAccentColor, dark, align, labelFontFamily }: ControlSchemePickerProps<T>) {
+export function ControlSchemePicker<T extends string | number>({ id, host, value, onChange, options, takenValue, accentColor, mutedColor, onAccentColor, dark, align, alignOverride, rotation, labelFontFamily }: ControlSchemePickerProps<T>) {
   const isTouchPrimary = useIsTouchPrimaryDevice()
   if (Platform.OS !== 'web' || isTouchPrimary) return null
 
-  return <SectionedDropdown id={id} host={host} icon='keyboard-outline' accessibilityLabel='Control scheme' sections={[{ kind: 'single', id: 'controls', options, value, onChange, takenValue }]} accentColor={accentColor} mutedColor={mutedColor} onAccentColor={onAccentColor} dark={dark} align={align} labelFontFamily={labelFontFamily} />
+  return <SectionedDropdown id={id} host={host} icon='keyboard-outline' accessibilityLabel='Control scheme' sections={[{ kind: 'single', id: 'controls', options, value, onChange, takenValue }]} accentColor={accentColor} mutedColor={mutedColor} onAccentColor={onAccentColor} dark={dark} align={align} alignOverride={alignOverride} rotation={rotation} labelFontFamily={labelFontFamily} />
 }

package/src/InlineColorPicker.tsx

@@ -6,7 +6,7 @@ import { Icon, Text } from 'react-native-paper'
 
 import { MONO_FONT } from './fonts'
 import { PopoverBody } from './PopoverBody'
-import { PopoverRotation, useAutoAlign } from './useAutoAlign'
+import { AlignResult, PopoverRotation, useAutoAlign } from './useAutoAlign'
 import { PopoverHost } from './usePopoverHost'
 
 // Presence check, not a full-string "is this exactly one emoji" validation — this only decides a
@@ -35,6 +35,26 @@ function widthForColumns(columns: number) {
   return SWATCHES_BORDER_WIDTH * 2 + SWATCHES_PADDING * 2 + SWATCH_SIZE * columns + SWATCHES_GAP * (columns - 1)
 }
 
+// Exported so a caller that needs to independently compute this popover's own content size — to
+// feed useZoneClampedAlign's contentWidth/contentHeight params with, ahead of producing a
+// colorAlignOverride for a picker living inside a @tastic/split-screen zone — can match this
+// component's real rendered size exactly, rather than re-deriving or hardcoding its internal
+// column/row math. Same job as LabeledDropdown's own getLabeledDropdownContentHeight, but this
+// picker's size also depends on window width (via the auto-column clamp below), so windowWidth is
+// a required parameter here rather than an ambient useWindowDimensions() read — a caller computing
+// this ahead of render (to decide alignment before the picker itself has even mounted) has no
+// component instance to read that hook from, so it has to pass the value in instead. The component
+// below calls this same function with its own live useWindowDimensions() read, so there is exactly
+// one place this formula lives.
+export function getInlineColorPickerContentSize(swatchCount: number, windowWidth: number, columns?: number): { width: number; height: number } {
+  const autoColumns = clamp(Math.floor((windowWidth - 2 * SCREEN_MARGIN + SWATCHES_GAP) / (SWATCH_SIZE + SWATCHES_GAP)), MIN_COLUMNS, MAX_COLUMNS)
+  const resolvedColumns = columns ?? autoColumns
+  const width = widthForColumns(resolvedColumns)
+  const rows = Math.ceil(swatchCount / resolvedColumns)
+  const height = SWATCHES_BORDER_WIDTH * 2 + SWATCHES_PADDING * 2 + SWATCH_SIZE * rows + SWATCHES_GAP * (rows - 1)
+  return { width, height }
+}
+
 interface Props {
   id: string
   host: PopoverHost
@@ -59,9 +79,16 @@ interface Props {
   // tradeoff.
   allowSwapTaken?: boolean
   dark: boolean
-  // Manual override — omit to let the popover measure its own trigger and pick whichever alignment
-  // keeps it from overflowing the screen edge (see useAutoAlign).
+  // Forces a specific horizontal alignment instead of letting whichever placement result applies
+  // (see alignOverride below) decide.
   align?: 'left' | 'right' | 'center'
+  // Substitutes this package's own plain useAutoAlign-based placement wholesale (align,
+  // verticalAlign, maxHeight, measured, triggerRef) with a caller-supplied one — e.g.
+  // useZoneClampedAlign's result, for a picker living inside a @tastic/split-screen zone, where the
+  // plain window-relative decision can pick a direction that overflows into the shared row instead
+  // of the zone's own boundary. Same shape LabeledDropdown's/SectionedDropdown's own alignOverride
+  // takes; omit for the ordinary case (a popover with nothing but the screen edge to avoid).
+  alignOverride?: AlignResult
   // Explicit override for the rotation a @tastic/split-screen-style FakeLandscapeView (or
   // equivalent) ancestor is currently applying — see SectionedDropdown's identical prop for the
   // full reasoning. Defaults to a live ambient read via @tastic/core's useRotation() when omitted.
@@ -93,20 +120,20 @@ interface Props {
 // Renders inline rather than as a full-screen modal, scoped to its own panel — a modal color
 // picker would block the whole screen for one player while another can't touch their own panel at
 // the same time, which defeats the point of a split-screen lobby.
-export function InlineColorPicker({ id, host, value, onChange, previewValue, swatches = defaultColors, takenValue, allowSwapTaken, dark, align: alignOverride, rotation: rotationOverride, icon = 'palette', tag, labelFontFamily = MONO_FONT, autoDismiss = true, columns, size = DEFAULT_SIZE }: Props) {
+export function InlineColorPicker({ id, host, value, onChange, previewValue, swatches = defaultColors, takenValue, allowSwapTaken, dark, align: forcedAlign, alignOverride, rotation: rotationOverride, icon = 'palette', tag, labelFontFamily = MONO_FONT, autoDismiss = true, columns, size = DEFAULT_SIZE }: Props) {
   const ambientRotation = useRotation()
   const rotation = rotationOverride ?? ambientRotation
   const menuBg = dark ? '#000000' : '#FFFFFF'
   const { width: windowWidth } = useWindowDimensions()
-  const autoColumns = clamp(Math.floor((windowWidth - 2 * SCREEN_MARGIN + SWATCHES_GAP) / (SWATCH_SIZE + SWATCHES_GAP)), MIN_COLUMNS, MAX_COLUMNS)
-  const resolvedColumns = columns ?? autoColumns
-  const swatchesWidth = widthForColumns(resolvedColumns)
-  const swatchRows = Math.ceil(swatches.length / resolvedColumns)
-  const swatchesHeight = SWATCHES_BORDER_WIDTH * 2 + SWATCHES_PADDING * 2 + SWATCH_SIZE * swatchRows + SWATCHES_GAP * (swatchRows - 1)
+  const { width: swatchesWidth, height: swatchesHeight } = getInlineColorPickerContentSize(swatches.length, windowWidth, columns)
 
   const open = host.openId === id
-  const { align: autoAlign, maxHeight, measured, triggerRef, verticalAlign } = useAutoAlign(open, swatchesWidth, swatchesHeight, rotation)
-  const align = alignOverride ?? autoAlign
+  // Always called, even when alignOverride is supplied and this result goes unused — hooks can't be
+  // called conditionally. See LabeledDropdown's identical comment for the same tradeoff.
+  const auto = useAutoAlign(open, swatchesWidth, swatchesHeight, rotation)
+  const placement = alignOverride ?? auto
+  const { maxHeight, measured, triggerRef, verticalAlign } = placement
+  const align = forcedAlign ?? placement.align
   const displayFor = previewValue ?? ((hex: string) => hex)
   const displayValue = displayFor(value)
   const contrastColor = getContrastColor(displayValue)

package/src/LabeledDropdown.tsx

@@ -1,11 +1,10 @@
 import { getContrastColor } from '@rific/auto-paper'
 import { TouchableRipple } from '@rific/feedback-press'
-import { RefObject } from 'react'
 import { ScrollView, StyleSheet, View } from 'react-native'
 import { Icon, Text } from 'react-native-paper'
 
 import { PopoverBody } from './PopoverBody'
-import { PopoverAlign, PopoverVerticalAlign, useAutoAlign } from './useAutoAlign'
+import { AlignResult, useAutoAlign } from './useAutoAlign'
 import { PopoverHost } from './usePopoverHost'
 
 const TRIGGER_HEIGHT = 28
@@ -29,17 +28,6 @@ export interface LabeledDropdownOption<T extends string> {
   icon?: string
 }
 
-// Same shape useAutoAlign itself returns — lets a caller inside a @tastic/split-screen zone (or
-// any other layout this package doesn't know about) substitute its own alignment decision via
-// `alignOverride` below, without this package taking a dependency on that caller's own hook.
-interface AlignResult {
-  align: PopoverAlign
-  verticalAlign: PopoverVerticalAlign
-  maxHeight: number
-  measured: boolean
-  triggerRef: RefObject<View | null>
-}
-
 interface Props<T extends string> {
   id: string
   host: PopoverHost
@@ -74,10 +62,10 @@ export function LabeledDropdown<T extends string>({ id, host, options, value, on
   const selected = options.find((o) => o.value === value) ?? null
   const contentHeight = LIST_PADDING * 2 + options.length * ROW_HEIGHT
   // Always called, even when alignOverride is supplied and this result goes unused — hooks can't be
-  // called conditionally. A caller passing alignOverride (e.g. LightCycles' own useZoneClampedAlign,
-  // which already wraps this same hook) does end up measuring the trigger twice; an acceptable
-  // tradeoff for keeping this component's own hook usage unconditional and override-shaped rather
-  // than needing a second, hook-free code path.
+  // called conditionally. A caller passing alignOverride (e.g. this package's own
+  // useZoneClampedAlign, which already wraps this same hook) does end up measuring the trigger
+  // twice; an acceptable tradeoff for keeping this component's own hook usage unconditional and
+  // override-shaped rather than needing a second, hook-free code path.
   const auto = useAutoAlign(open, POPOVER_WIDTH, contentHeight)
   const placement = alignOverride ?? auto
   const { maxHeight, measured, triggerRef, verticalAlign } = placement

package/src/PlayerSetupPanel.tsx

@@ -0,0 +1,196 @@
+import { SeedColor } from '@rific/auto-paper'
+import { Profile, ProfilePicker } 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 { ReadyButton } from './ReadyButton'
+import { AlignResult, PopoverRotation } from './useAutoAlign'
+import { PopoverHost, usePopoverHost } from './usePopoverHost'
+
+// 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
+// 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`
+}
+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
+  // 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
+  // panel's or a shared-controls row's (e.g. vs-CPU: only one human is ever driving both slots, so
+  // having both YOU's and CPU's pickers open at once is just clutter, not a useful simultaneous-edit
+  // case). Omit to fall back to this panel's own independent host — the two-player case, where two
+  // real people editing at once is the point.
+  host?: PopoverHost
+  label?: string
+  // Applied only to the plain `label` fallback text below (ProfilePicker/LabeledDropdown 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.
+  labelFontFamily?: string
+  color: 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.
+  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.
+  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
+  // 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
+  // pull/push "feel" preference, vs. no such concept at all for a game with no per-seat setting to
+  // pick) — a ReactNode slot the caller renders its own picker into is what actually generalizes
+  // across all of them, rather than this component baking in one shape (e.g. ControlSchemePicker's
+  // own prop set) that most of its consumers don't need at all.
+  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
+  // 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
+  ready?: boolean
+  onToggleReady?: () => void
+  dark: boolean
+  // vs-CPU only has one human player, so some loadout screens render their Ready toggle standalone,
+  // centered below both slots, instead of embedded in this panel.
+  showReadyButton?: boolean
+  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
+  // 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
+  onProfileSelect?: (profile: Profile | null) => void
+  // Navigates to a profile-management screen — typically only ever wired up for one seat (a rotated
+  // second zone often can't host a working text keyboard).
+  onManageProfiles?: () => void
+  // Generic over the calling app's own CPU-difficulty union, matching LabeledDropdownOption<T>'s own
+  // genericness — this package has no opinion on what difficulties exist.
+  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.
+  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.
+//
+// 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>) {
+  const ownHost = usePopoverHost()
+  const popover = host ?? ownHost
+  // Checking *this panel's own* ids, not just "is anything open on the host" — when `host` is
+  // shared, another panel's (or a shared-controls row's) popovers also live on it, and elevating
+  // this panel for those too would tie it with whichever of them actually has the open popover,
+  // 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.
+  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 selectedProfile = profiles?.find((p) => p.id === selectedProfileId) ?? null
+
+  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} />
+      ) : showCpuDifficulty ? (
+        <LabeledDropdown id={getCpuDifficultyPopoverId(idPrefix)} host={popover} options={cpuDifficultyOptions!} value={cpuDifficulty!} onChange={onCpuDifficultyChange!} color={color} dark={dark} alignOverride={cpuDifficultyAlignOverride} />
+      ) : (
+        label && (
+          <Text variant='labelSmall' style={{ color, fontFamily: labelFontFamily }}>
+            {label}
+          </Text>
+        )
+      )}
+
+      <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} />
+
+        {secondPicker}
+      </View>
+
+      {isHuman && showReadyButton && onToggleReady && <ReadyButton color={color} ready={ready ?? false} onToggleReady={onToggleReady} />}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  panel: {
+    alignItems: 'center',
+    gap: 12
+  },
+  // See SectionedDropdown's anchorOpen comment — this panel is typically a sibling of another
+  // panel (and/or a shared-controls row), so a popover escaping this panel's bounds needs the panel
+  // itself elevated, not just the popover content, to paint above a later sibling.
+  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.
+  pickerRow: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    gap: 12
+  },
+  // A popover is an absolutely-positioned sibling of its own trigger — so a tall one (the color
+  // swatch grid) can extend down far enough to overlap the ReadyButton below, which paints on top of
+  // it by default DOM order since it's a later sibling within `panel`. `panel`'s own panelOpen
+  // elevation only helps this panel paint above OTHER panels (see its own comment) — it does nothing
+  // for stacking *within* this panel, since React Native Web gives each View its own stacking
+  // context. This is what actually fixes that: elevate pickerRow itself above its own later sibling
+  // whenever one of its own popovers is open.
+  pickerRowOpen: {
+    zIndex: 100
+  }
+})