@tastic/hud 0.1.6 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastic/hud",
-  "version": "0.1.6",
+  "version": "0.3.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",
@@ -68,6 +68,7 @@
     "@infinitetoken/tsconfig": "^0.3.0",
     "@rific/auto-paper": "^0.10.3",
     "@rific/feedback-press": "^0.10.8",
+    "@rific/updater": "^0.4.2",
     "@shopify/react-native-skia": "^2.6.2",
     "@tastic/core": "^0.1.5",
     "@testing-library/dom": "^10.4.1",
@@ -91,6 +92,7 @@
   "peerDependencies": {
     "@rific/auto-paper": ">=0.9.0",
     "@rific/feedback-press": ">=0.10.0",
+    "@rific/updater": ">=0.4.0",
     "@shopify/react-native-skia": ">=1.5.0",
     "@tastic/core": ">=0.1.0",
     "react": ">=19.0.0",

package/src/BaseSettingsDialog.tsx

@@ -0,0 +1,371 @@
+import { AutoAppearancePicker, Dialog, useAutoPaperTheme } from '@rific/auto-paper'
+import { Button, SoundContext, TouchableRipple, useHapticSettings, useSoundSettings, useVibration } from '@rific/feedback-press'
+import { useUpdater } from '@rific/updater'
+import { useIsTouchPrimaryDevice } from '@tastic/core'
+import { ReactNode, useContext, useState } from 'react'
+import { Platform, ScrollView, StyleSheet, View } from 'react-native'
+import { Icon, Portal, Text } from 'react-native-paper'
+
+interface SettingIconProps {
+  source: string
+  color: string
+  containerColor: string
+}
+
+// Small colored badge per row (icon tinted on its own MD3 container color) — echoes the
+// primary/secondary/tertiary triad that's already each consuming app's own identity, so the
+// settings list picks up that same palette instead of introducing new colors of its own.
+function SettingIcon({ source, color, containerColor }: SettingIconProps) {
+  return (
+    <View style={[styles.iconBadge, { backgroundColor: containerColor }]}>
+      <Icon source={source} size={18} color={color} />
+    </View>
+  )
+}
+
+export interface BaseSettingsDialogProps {
+  visible: boolean
+  onDismiss: () => void
+  // Live physical-hold rotation (see @tastic/split-screen's getViewRotation) — this is a centered,
+  // app-wide modal with no per-player zone to match (unlike an in-game round-over dialog), so it
+  // just rotates its own content in place; defaults to 0 for a caller that doesn't track one (a
+  // game with no face-to-face two-player mode has nothing to stay consistent with anyway).
+  rotation?: number
+  // Each app's own OTA version (e.g. release.otaVersion) — not something this package can read
+  // itself, since every consuming app tracks its own release.ts independently. Accepts a number too
+  // since that's what release.otaVersion actually is in most apps (a bare incrementing counter, not
+  // a formatted string) — this just interpolates it into the VERSION label same as the original
+  // inline JSX did.
+  version: string | number
+  // Optional, and always passed as a pair — omit both entirely for a game that's portrait-only (or
+  // otherwise has no orientation-based reflow at all), where there's nothing to lock against.
+  lockOrientation?: boolean
+  onLockOrientationChange?: (value: boolean) => void
+  // Optional, and always passed as a pair — omit both entirely for a game with no full-screen edge-
+  // anchored swipe controls (nothing to guard). iOS-only regardless of whether the pair is passed:
+  // @tastic/edge-guard's own swizzle is a no-op on every other platform.
+  deferBottomEdgeGestures?: boolean
+  onDeferBottomEdgeGestures?: (value: boolean) => void
+  // 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
+  // these, so hiding one takes its own explicit flag instead. All default to shown, matching every
+  // app's existing behavior before this prop existed.
+  hideSound?: boolean
+  // Haptics is already native-only (see the row's own Platform.OS check) — this hides it even
+  // there, for a game that's deliberately silent on vibration.
+  hideHaptics?: boolean
+  hideAppearance?: boolean
+  // Check for Updates is already native-only (a web build has no OTA update concept at all) — this
+  // hides it even there, for a native app that isn't wired up for EAS/OTA updates at all.
+  hideUpdateCheck?: boolean
+  // Surfaces a failed update check (e.g. via @rific/toaster's error()) — omit for an app with no
+  // toast system wired up; the check itself still runs and still reports success/no-update through
+  // the ordinary info overlay either way. Meaningless (never called) when hideUpdateCheck is set.
+  onUpdateError?: (message: string) => void
+  // App-specific extra settings sections (board options, CPU difficulty, stats backup, ...),
+  // rendered between Appearance and Check for Updates — this component only owns the settings
+  // every game shares, never anything about how a particular game plays.
+  children?: ReactNode
+}
+
+// The settings shell every @tastic game shares — orientation lock, the optional edge-guard toggle,
+// sound/haptics, appearance, and update checking — extracted after the same six rows were
+// independently copied into LightCycles, AirHockey, BoxHockey, Pong, and Snake and then needed
+// hand-editing in every one of them, twice, for what were meant to be identical fixes. `children`
+// 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 = 0, version, lockOrientation, onLockOrientationChange, deferBottomEdgeGestures, onDeferBottomEdgeGestures, hideSound = false, hideHaptics = false, hideAppearance = false, hideUpdateCheck = false, onUpdateError, children }: BaseSettingsDialogProps) {
+  const { dark, colors } = useAutoPaperTheme()
+  // Also gates the Lock Orientation row below (alongside showLockOrientation itself) — 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
+  // of actually locking anything.
+  const isTouchPrimary = useIsTouchPrimaryDevice()
+  const { settings: hapticSettings, set: setHapticSettings } = useHapticSettings()
+  const { settings: soundSettings, set: setSoundSettings } = useSoundSettings()
+  // 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).
+  // Both rows disable their own automatic channel below (soundDisabled/hapticDisabled) and fire it
+  // manually here instead, gated on the NEW value so it only plays when switching that channel on.
+  const sound = useContext(SoundContext)
+  const { forceShort: forceHapticFeedback } = useVibration()
+  // Covers check()'s three purely-informational cases (dev-mode disabled, web unsupported, no
+  // update found) via onInfo below — a retro card overlay instead of the native Alert.alert those
+  // cases fall back to by default.
+  const [infoMessage, setInfoMessage] = useState<{ title: string; message: string } | null>(null)
+  // autoCheck: false — every consuming app's own root layout already runs the background check via
+  // its own useUpdater() instance; a second instance with autoCheck's default (true) would set up a
+  // second AppState listener and double every foreground-resume update check. This instance only
+  // ever checks on an explicit tap of the button below.
+  const { check, checking, updateReady } = useUpdater({
+    autoCheck: false,
+    autoPrompt: false,
+    onError: onUpdateError,
+    onInfo: (title, message) => setInfoMessage({ title, message })
+  })
+
+  const showLockOrientation = isTouchPrimary && lockOrientation !== undefined && onLockOrientationChange !== undefined
+  const showEdgeGuard = Platform.OS === 'ios' && deferBottomEdgeGestures !== undefined && onDeferBottomEdgeGestures !== undefined
+  const showHaptics = Platform.OS !== 'web' && !hideHaptics
+  const showSound = !hideSound
+  const showAppearance = !hideAppearance
+  const showUpdateCheck = Platform.OS !== 'web' && !hideUpdateCheck
+
+  // High-contrast retro look: literal black/white by appearance, not auto-paper's own (slightly
+  // tinted) background role.
+  const fg = dark ? '#FFFFFF' : '#000000'
+  const cardBg = dark ? '#111111' : '#F2F2F2'
+  const cardBorder = dark ? 'rgba(255,255,255,0.2)' : 'rgba(0,0,0,0.2)'
+
+  return (
+    <>
+      <Dialog visible={visible} onDismiss={onDismiss} style={[styles.dialog, rotation % 360 !== 0 && { transform: [{ rotate: `${rotation}deg` }] }]}>
+        <Dialog.Title>Settings</Dialog.Title>
+        {/* react-native-paper's Dialog.ScrollArea has a fixed 24px marginBottom baked in (meant to
+          reserve room for a Dialog.Actions row below it) — overridden to 0 since this dialog has
+          no actions row, and that gap otherwise reads as unexplained empty footer space. */}
+        <Dialog.ScrollArea style={styles.scrollArea}>
+          <ScrollView contentContainerStyle={styles.content} showsVerticalScrollIndicator={false}>
+            {/* Grouped tightly together (styles.toggleGroup's small internal gap, not the 24px gap
+              between sections below) — same bare-row shape for all of them, no segmented control
+              and no section heading (each row's own label already says what it is). Haptics only
+              joins on native — there's nothing for it to control on web. */}
+            <View style={styles.toggleGroup}>
+              {/* Omitted entirely for a portrait-only game (no lockOrientation/onLockOrientationChange
+                passed at all — nothing to lock), and hidden (not just disabled) on a desktop/laptop
+                browser even when they are — see isTouchPrimary's own doc above. Still shown on
+                native and on a touch-capable mobile browser, where a rotated window really does
+                reflect a rotated device. */}
+              {showLockOrientation && (
+                <TouchableRipple onPress={() => onLockOrientationChange!(!lockOrientation)} style={styles.toggleButton} accessibilityLabel={`Lock orientation ${lockOrientation ? 'on' : 'off'}`}>
+                  <View style={styles.toggleContent}>
+                    <SettingIcon source={lockOrientation ? 'lock' : 'lock-open-variant-outline'} color={lockOrientation ? colors.secondary : colors.onSurfaceVariant} containerColor={lockOrientation ? colors.secondaryContainer : colors.surfaceVariant} />
+                    <View style={styles.flexShrink}>
+                      <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
+                        Lock Orientation
+                      </Text>
+                      <Text variant='bodySmall' numberOfLines={1} style={{ color: colors.onSurfaceVariant }}>
+                        Pins the current layout
+                      </Text>
+                    </View>
+                  </View>
+                </TouchableRipple>
+              )}
+
+              {/* iOS only — mirrors into UserDefaults for @tastic/edge-guard's own config plugin
+                swizzle to read. Guards both edges — the top (Notification Center/Control Center)
+                and the bottom (home-indicator swipe, incidentally Reachability too), per that
+                package's own doc. Off by default: a deliberate opt-in for whoever's actually hit an
+                accidental-swipe-near-an-edge problem mid-game and come looking for a fix, not a
+                surprise every player gets by default. */}
+              {showEdgeGuard && (
+                <TouchableRipple onPress={() => onDeferBottomEdgeGestures!(!deferBottomEdgeGestures)} style={styles.toggleButton} accessibilityLabel={`Edge guard ${deferBottomEdgeGestures ? 'on' : 'off'}`}>
+                  <View style={styles.toggleContent}>
+                    <SettingIcon source={deferBottomEdgeGestures ? 'shield-check-outline' : 'shield-off-outline'} color={deferBottomEdgeGestures ? colors.secondary : colors.onSurfaceVariant} containerColor={deferBottomEdgeGestures ? colors.secondaryContainer : colors.surfaceVariant} />
+                    <View style={styles.flexShrink}>
+                      <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
+                        Edge Guard
+                      </Text>
+                      <Text variant='bodySmall' numberOfLines={1} style={{ color: colors.onSurfaceVariant }}>
+                        Requires a second swipe
+                      </Text>
+                    </View>
+                  </View>
+                </TouchableRipple>
+              )}
+
+              {/* Side by side, not stacked — neither needs a full row's width (single-line label,
+                no description under it the way Lock Orientation has), so sharing one row reads
+                just as clearly and takes half the vertical space. toggleRow carries the same
+                edge-alignment negative margin toggleButton normally carries itself; the buttons
+                inside it use toggleButtonInRow (flex: 1) instead so the two don't double up on it.
+                The row itself only renders when at least one of the two will — an empty flex row
+                still eats its own gap/margin otherwise. */}
+              {(showSound || showHaptics) && (
+                <View style={styles.toggleRow}>
+                  {showSound && (
+                    <TouchableRipple
+                      soundDisabled
+                      onPress={() => {
+                        const enabled = !soundSettings.enabled
+                        setSoundSettings({ enabled })
+                        if (enabled) sound.selection?.()
+                      }}
+                      style={styles.toggleButtonInRow}
+                      accessibilityLabel={`Sound ${soundSettings.enabled ? 'on' : 'off'}`}
+                    >
+                      <View style={styles.toggleContent}>
+                        <SettingIcon source={soundSettings.enabled ? 'volume-high' : 'volume-off'} color={soundSettings.enabled ? colors.tertiary : colors.onSurfaceVariant} containerColor={soundSettings.enabled ? colors.tertiaryContainer : colors.surfaceVariant} />
+                        <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
+                          Sound
+                        </Text>
+                      </View>
+                    </TouchableRipple>
+                  )}
+
+                  {/* Already native-only (see showHaptics's own definition) — hideHaptics can hide
+                    it there too, for a game that's deliberately silent on vibration. */}
+                  {showHaptics && (
+                    <TouchableRipple
+                      hapticDisabled
+                      onPress={() => {
+                        const vibrate = !hapticSettings.vibrate
+                        setHapticSettings({ vibrate })
+                        if (vibrate) forceHapticFeedback()
+                      }}
+                      style={styles.toggleButtonInRow}
+                      accessibilityLabel={`Haptics ${hapticSettings.vibrate ? 'on' : 'off'}`}
+                    >
+                      <View style={styles.toggleContent}>
+                        <SettingIcon source={hapticSettings.vibrate ? 'vibrate' : 'vibrate-off'} color={hapticSettings.vibrate ? colors.tertiary : colors.onSurfaceVariant} containerColor={hapticSettings.vibrate ? colors.tertiaryContainer : colors.surfaceVariant} />
+                        <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
+                          Haptics
+                        </Text>
+                      </View>
+                    </TouchableRipple>
+                  )}
+                </View>
+              )}
+            </View>
+
+            {showAppearance && (
+              <View style={styles.section}>
+                <Text variant='labelMedium' style={[styles.sectionLabel, { color: colors.onSurfaceVariant }]}>
+                  APPEARANCE
+                </Text>
+                <AutoAppearancePicker showLabels={false} />
+              </View>
+            )}
+
+            {children}
+
+            {/* Native only (a web build has no OTA update concept at all, desktop or mobile browser
+              alike) — hideUpdateCheck can hide it there too, for a native app that isn't wired up
+              for EAS/OTA updates at all. */}
+            {showUpdateCheck && (
+              <View style={styles.section}>
+                <Text variant='labelSmall' style={[styles.sectionLabel, { color: colors.onSurfaceVariant }]}>
+                  VERSION {version}
+                  {updateReady ? ' · UPDATE READY' : ''}
+                </Text>
+                <Button mode='outlined' onPress={check} loading={checking} disabled={checking}>
+                  Check for Updates
+                </Button>
+              </View>
+            )}
+          </ScrollView>
+        </Dialog.ScrollArea>
+      </Dialog>
+      {infoMessage && (
+        <Portal>
+          <View style={styles.overlay}>
+            <View style={[styles.overlayCard, { backgroundColor: cardBg, borderColor: cardBorder }, rotation % 360 !== 0 && { transform: [{ rotate: `${rotation}deg` }] }]}>
+              <Icon source='information-outline' size={64} color={colors.secondary} />
+              <Text variant='headlineLarge' style={[styles.overlayTitle, { color: colors.secondary }]}>
+                {infoMessage.title}
+              </Text>
+              <Text variant='bodyLarge' style={[styles.overlayBody, { color: fg }]}>
+                {infoMessage.message}
+              </Text>
+              <Button mode='contained' onPress={() => setInfoMessage(null)} style={styles.overlayButton} buttonColor={colors.primary} textColor={colors.onPrimary}>
+                OK
+              </Button>
+            </View>
+          </View>
+        </Portal>
+      )}
+    </>
+  )
+}
+
+const styles = StyleSheet.create({
+  content: {
+    gap: 24,
+    paddingVertical: 20
+  },
+  // Caps the card so it never grows past the screen — without this the dialog just keeps
+  // growing to fit its content and the overflow gets clipped by the screen edge, which is
+  // what happened in landscape where there's less height to work with. Dialog.ScrollArea +
+  // ScrollView below then take over and let the content scroll within that bound.
+  dialog: {
+    maxHeight: '90%'
+  },
+  flexShrink: {
+    flexShrink: 1
+  },
+  iconBadge: {
+    alignItems: 'center',
+    borderRadius: 10,
+    height: 36,
+    justifyContent: 'center',
+    width: 36
+  },
+  overlay: {
+    alignItems: 'center',
+    backgroundColor: 'rgba(0,0,0,0.72)',
+    bottom: 0,
+    justifyContent: 'center',
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0
+  },
+  overlayBody: { textAlign: 'center' },
+  overlayButton: { width: 160 },
+  overlayCard: {
+    alignItems: 'center',
+    borderRadius: 20,
+    borderWidth: 1,
+    gap: 16,
+    maxWidth: 360,
+    padding: 32
+  },
+  overlayTitle: { fontWeight: 'bold' },
+  scrollArea: {
+    marginBottom: 0
+  },
+  section: {
+    gap: 12
+  },
+  sectionLabel: {
+    letterSpacing: 2
+  },
+  // Negative margin cancels the padding so the icon still lines up with APPEARANCE/SOUND &
+  // HAPTICS below, while the ripple/hover highlight itself gets room to breathe on both sides
+  // instead of a flush edge-to-edge slab. overflow: 'hidden' makes sure that highlight actually
+  // clips to borderRadius instead of drawing as a plain rectangle.
+  toggleButton: {
+    borderRadius: 12,
+    marginHorizontal: -12,
+    overflow: 'hidden',
+    paddingHorizontal: 12,
+    paddingVertical: 10
+  },
+  // Same shape as toggleButton but `flex: 1` instead of its own `marginHorizontal: -12` — two of
+  // these side by side in toggleRow would otherwise both pull inward and collide in the middle.
+  // toggleRow carries that edge-alignment margin once, for the row as a whole, instead.
+  toggleButtonInRow: {
+    borderRadius: 12,
+    flex: 1,
+    overflow: 'hidden',
+    paddingHorizontal: 12,
+    paddingVertical: 10
+  },
+  toggleContent: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    gap: 12
+  },
+  toggleGroup: {
+    gap: 4
+  },
+  toggleRow: {
+    flexDirection: 'row',
+    gap: 4,
+    marginHorizontal: -12
+  }
+})

package/src/CornerActionButtons.tsx

@@ -0,0 +1,39 @@
+import { IconButton } from '@rific/feedback-press'
+import { StyleSheet } from 'react-native'
+
+interface Props {
+  onBack: () => void
+  onSettings: () => void
+  // Full-contrast foreground — same convention as every other component keying off a `dark` prop
+  // (BaseSettingsDialog, SectionedDropdown, etc.), just resolved by the caller since this component
+  // never reads theme state itself.
+  fg: string
+  // Safe-area insets already remapped onto the screen's real visual edges (see
+  // @tastic/split-screen's rotateInsets) — this component just adds the fixed 8px margin on top,
+  // it doesn't know anything about physical device orientation itself.
+  insets: { top: number; left: number; right: number }
+}
+
+// Back (top-left) + Settings (top-right) icon buttons, fixed at the screen's rotated corners — the
+// default reachability answer for a two-player screen: correct any time both players share one
+// screen but only one of them (or neither, in vs-CPU) is on the far side of a rotated zone. Not the
+// right answer for a screen where the top corners themselves fall *inside* one player's own rotated
+// zone (two-player face-to-face) — see SharedActionBand for that case instead, which callers select
+// between based on their own game-mode/orientation state (this component has no opinion on which).
+export function CornerActionButtons({ onBack, onSettings, fg, insets }: Props) {
+  return (
+    <>
+      <IconButton icon='arrow-left' iconColor={fg} size={24} style={[styles.back, { top: 8 + insets.top, left: 8 + insets.left }]} onPress={onBack} accessibilityLabel='Back' />
+      <IconButton icon='cog' iconColor={fg} size={24} style={[styles.topRight, { top: 8 + insets.top, right: 8 + insets.right }]} onPress={onSettings} accessibilityLabel='Settings' />
+    </>
+  )
+}
+
+const styles = StyleSheet.create({
+  back: {
+    position: 'absolute'
+  },
+  topRight: {
+    position: 'absolute'
+  }
+})

package/src/LabeledDropdown.tsx

@@ -0,0 +1,175 @@
+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 { PopoverHost } from './usePopoverHost'
+
+const TRIGGER_HEIGHT = 28
+const POPOVER_WIDTH = 180
+const ROW_HEIGHT = 36
+const LIST_PADDING = 8
+
+// Exported so a caller that needs to independently compute this popover's own placement — to feed
+// alignOverride with, say, a @tastic/split-screen-zone-aware hook's result — can match its real
+// content dimensions exactly, rather than hardcoding or re-deriving this component's own internal
+// sizing (which alignOverride itself deliberately doesn't take a dependency on any particular
+// zone-awareness package to compute).
+export const LABELED_DROPDOWN_POPOVER_WIDTH = POPOVER_WIDTH
+export function getLabeledDropdownContentHeight(optionCount: number): number {
+  return LIST_PADDING * 2 + optionCount * ROW_HEIGHT
+}
+
+export interface LabeledDropdownOption<T extends string> {
+  value: T
+  label: 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
+  options: LabeledDropdownOption<T>[]
+  value: T
+  onChange: (value: T) => void
+  color: string
+  dark: boolean
+  // Forces a specific horizontal alignment instead of letting whichever placement result applies
+  // (see alignOverride below) decide. Matches PopoverBody's own align prop meaning.
+  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. a popover
+  // 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 actual zone boundary. Omit for the
+  // ordinary case (a popover with nothing but the screen edge to avoid).
+  alignOverride?: AlignResult
+}
+
+// A name-trigger + selection popover in the same visual style as @tastic/profile's own
+// ProfilePicker trigger — an uppercase text label + chevron, opening a list whose selected row
+// fills entirely with the seat's own accent color — rather than this package's own
+// SectionedDropdown, whose trigger is a fixed icon with a gauge ring around it. For a choice that
+// reads more like "who/what you're playing" than "a game setting" (a CPU seat's own difficulty,
+// occupying the same slot a human seat's ProfilePicker would), the always-visible text label
+// carries more of the meaning than an icon would on its own.
+export function LabeledDropdown<T extends string>({ id, host, options, value, onChange, color, dark, align: forcedAlign, alignOverride }: Props<T>) {
+  const menuBg = dark ? '#000000' : '#FFFFFF'
+  const fg = dark ? '#FFFFFF' : '#000000'
+
+  const open = host.openId === id
+  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.
+  const auto = useAutoAlign(open, POPOVER_WIDTH, contentHeight)
+  const placement = alignOverride ?? auto
+  const { maxHeight, measured, triggerRef, verticalAlign } = placement
+  const align = forcedAlign ?? placement.align
+
+  const handleSelect = (option: LabeledDropdownOption<T>) => {
+    onChange(option.value)
+    host.close()
+  }
+
+  return (
+    <View style={[styles.anchor, open && styles.anchorOpen]}>
+      <TouchableRipple onPress={() => host.toggle(id)} style={styles.trigger}>
+        <View ref={triggerRef} collapsable={false} style={styles.triggerInner}>
+          <Text style={[styles.triggerLabel, { color }]} numberOfLines={1}>
+            {(selected?.label ?? '').toUpperCase()}
+          </Text>
+          <Icon source='menu-down' size={16} color={color} />
+        </View>
+      </TouchableRipple>
+
+      {/* Gated on `measured`, not just `open` — see InlineColorPicker's identical fix. */}
+      <PopoverBody visible={open && measured} align={align} verticalAlign={verticalAlign} caretColor={menuBg} caretBorderColor={color} caretBorderWidth={2} triggerSize={TRIGGER_HEIGHT}>
+        <ScrollView style={[styles.menu, { backgroundColor: menuBg, borderColor: color, width: POPOVER_WIDTH, maxHeight }]} contentContainerStyle={styles.menuContent} showsVerticalScrollIndicator={false}>
+          {options.map((option) => {
+            const isSelected = option.value === value
+            const onColor = getContrastColor(color)
+            return (
+              <TouchableRipple key={option.value} onPress={() => handleSelect(option)} style={[styles.row, isSelected && { backgroundColor: color }]}>
+                <View style={styles.rowInner}>
+                  {option.icon && <Icon source={option.icon} size={18} color={isSelected ? onColor : fg} />}
+                  <Text style={[styles.rowLabel, { color: isSelected ? onColor : fg }]} numberOfLines={1}>
+                    {option.label}
+                  </Text>
+                </View>
+              </TouchableRipple>
+            )
+          })}
+        </ScrollView>
+      </PopoverBody>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  anchor: {
+    position: 'relative'
+  },
+  // React Native Web gives every position:'relative' view its own stacking context, so the
+  // elevation has to live on the anchor itself — see PopoverBody's own stacking-context notes.
+  anchorOpen: {
+    zIndex: 100
+  },
+  menu: {
+    borderRadius: 12,
+    borderWidth: 2,
+    elevation: 8,
+    shadowColor: '#000000',
+    shadowOffset: { height: 2, width: 0 },
+    shadowOpacity: 0.3,
+    shadowRadius: 8
+  },
+  menuContent: {
+    padding: LIST_PADDING
+  },
+  row: {
+    borderRadius: 8,
+    height: ROW_HEIGHT
+  },
+  rowInner: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    flex: 1,
+    gap: 8,
+    paddingHorizontal: 12
+  },
+  rowLabel: {
+    flex: 1,
+    fontSize: 14
+  },
+  trigger: {
+    alignSelf: 'flex-start'
+  },
+  triggerInner: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    gap: 2,
+    height: TRIGGER_HEIGHT
+  },
+  triggerLabel: {
+    fontSize: 13,
+    fontWeight: '700',
+    letterSpacing: 1
+  }
+})

package/src/SharedActionBand.tsx

@@ -0,0 +1,61 @@
+import { IconButton } from '@rific/feedback-press'
+import { ReactNode } from 'react'
+import { StyleSheet, View } from 'react-native'
+
+interface Props {
+  onBack: () => void
+  onSettings: () => void
+  // Optional, and expected to be passed together in practice (either a screen has both a randomize
+  // and a reset action, or neither) — kept as two independently-optional props rather than one pair
+  // flag so a caller with only one of the two isn't forced to fake the other.
+  onRandomize?: () => void
+  onReset?: () => void
+  fg: string
+  // Whether one of THIS band's own popovers (i.e. something rendered inside `children`) is
+  // currently open — the caller computes this (typically `host.openId !== null &&
+  // OWN_IDS.includes(host.openId)`), since only the caller knows which popover ids belong to its
+  // own children. Elevates the whole column above sibling panels when true — React Native Web gives
+  // every position:'relative' view its own stacking context, so a popover escaping `children` needs
+  // this wrapper itself elevated, not just the popover content, to paint above a later sibling
+  // (e.g. a player panel) rather than underneath it.
+  popoverOpen: boolean
+  // The screen's own per-round option row (grid size, arena, etc.) — rendered directly below the
+  // action row, inside the same elevating column.
+  children: ReactNode
+}
+
+// The reachability fix for a two-player screen where the plain top-left/top-right corners (see
+// CornerActionButtons) would land inside one player's own rotated zone — most concretely, two-
+// player face-to-face, where the far player's zone always covers the top half of the screen. Folds
+// back/randomize/reset/settings into one row that sits on neutral ground instead (the shared band
+// between the two players' zones), directly above the caller's own per-round option row. The
+// caller decides *when* this applies (it owns gameMode/orientationMode) — this component only
+// renders the result once that decision's already been made.
+export function SharedActionBand({ onBack, onSettings, onRandomize, onReset, fg, popoverOpen, children }: Props) {
+  return (
+    <View style={[styles.column, popoverOpen && styles.columnOpen]}>
+      <View style={styles.actionsRow}>
+        <IconButton icon='arrow-left' iconColor={fg} size={20} onPress={onBack} accessibilityLabel='Back' />
+        {onRandomize && <IconButton icon='dice-multiple' iconColor={fg} size={18} onPress={onRandomize} accessibilityLabel='Randomize match settings' />}
+        {onReset && <IconButton icon='restore' iconColor={fg} size={18} onPress={onReset} accessibilityLabel='Reset match settings to defaults' />}
+        <IconButton icon='cog' iconColor={fg} size={20} onPress={onSettings} accessibilityLabel='Settings' />
+      </View>
+      {children}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  actionsRow: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    gap: 16
+  },
+  column: {
+    alignItems: 'center',
+    gap: 8
+  },
+  columnOpen: {
+    zIndex: 100
+  }
+})