@tastic/hud 0.8.5 → 0.13.0

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

package/src/SectionedDropdown.tsx

@@ -7,7 +7,7 @@ import { Icon, Text } from 'react-native-paper'
 import { MONO_FONT } from './fonts'
 import { PopoverBody } from './PopoverBody'
 import TriggerGaugeHost from './TriggerGaugeHost'
-import { PopoverRotation, useAutoAlign } from './useAutoAlign'
+import { AlignResult, PopoverRotation, useAutoAlign } from './useAutoAlign'
 import { PopoverHost } from './usePopoverHost'
 
 const MENU_BORDER_WIDTH = 1
@@ -96,10 +96,17 @@ interface Props {
   // background — pass a real design-system "on" color explicitly instead when you have one.
   onAccentColor?: string
   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). Only pass this to force a specific
-  // side regardless of where the trigger actually sits.
+  // Forces a specific horizontal alignment instead of letting whichever placement result applies
+  // (see alignOverride below) decide. Only pass this to force a specific side regardless of where
+  // the trigger actually sits.
   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 dropdown 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 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 any other
   // ancestor rotated the same way — a bare CSS `transform: rotate()`, not an actual OS-level
   // orientation change) is currently applying. Defaults to a live ambient read via @tastic/core's
@@ -128,7 +135,7 @@ interface Props {
 // powerups are enabled, say) is just this with one 'multi' section (optionally with allClear); a
 // combined menu (e.g. spawn frequency + which types, in one menu) is just two sections in the same
 // array.
-export function SectionedDropdown({ id, host, icon, accessibilityLabel, sections, accentColor, mutedColor, onAccentColor, dark, align: alignOverride, rotation: rotationOverride, autoDismiss = true, labelFontFamily = MONO_FONT, allClearLabels = { all: 'All', clear: 'Clear' } }: Props) {
+export function SectionedDropdown({ id, host, icon, accessibilityLabel, sections, accentColor, mutedColor, onAccentColor, dark, align: forcedAlign, alignOverride, rotation: rotationOverride, autoDismiss = true, labelFontFamily = MONO_FONT, allClearLabels = { all: 'All', clear: 'Clear' } }: Props) {
   const ambientRotation = useRotation()
   const rotation = rotationOverride ?? ambientRotation
   const menuBg = dark ? '#000000' : '#FFFFFF'
@@ -156,8 +163,12 @@ export function SectionedDropdown({ id, host, icon, accessibilityLabel, sections
       const divider = sectionIndex > 0 ? MENU_DIVIDER_HEIGHT : 0
       return sum + rows + footer + divider
     }, 0)
-  const { align: autoAlign, maxHeight, measured, triggerRef, verticalAlign } = useAutoAlign(open, MENU_MAX_WIDTH, estimatedHeight, 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, MENU_MAX_WIDTH, estimatedHeight, rotation)
+  const placement = alignOverride ?? auto
+  const { maxHeight, measured, triggerRef, verticalAlign } = placement
+  const align = forcedAlign ?? placement.align
 
   // Trigger reflects the selected option's own icon only when there's exactly one section and it's
   // single-select — any other shape (multi-select present, or more than one section) has no single

package/src/StaggeredWord.tsx

@@ -0,0 +1,114 @@
+import { useEffect } from 'react'
+import { LayoutChangeEvent, StyleProp, StyleSheet, TextStyle, View, ViewStyle } from 'react-native'
+import Animated, { Easing, useAnimatedStyle, useSharedValue, withDelay, withTiming } from 'react-native-reanimated'
+
+const STAGGER_MS = 45
+const LETTER_DURATION_MS = 320
+
+// The one formula every consumer's own follow-on animation (a paddle rally, a bouncing puck, a
+// looping trail) needs in order to time its own entrance off "once the letters have mostly
+// landed" — five apps (AirHockey, BoxHockey, Pong, LightCycles, Snake) had each independently
+// re-derived `(letterCount - 1) * STAGGER_MS + LETTER_DURATION_MS` locally as their own
+// `TOTAL_STAGGER_MS` constant. Exported as a pure function, not a component return value, so a
+// caller can compute it once, outside render, the same way every one of those apps already did.
+// `letterCount` is the TOTAL number of letters actually animated, not necessarily a single
+// StaggeredWord's own `word.length` — see `startIndex` below for a multi-word wordmark, where a
+// second word's letters continue the same overall stagger sequence.
+export function getStaggeredWordDuration(letterCount: number): number {
+  return (letterCount - 1) * STAGGER_MS + LETTER_DURATION_MS
+}
+
+interface AnimatedLetterProps {
+  char: string
+  index: number
+  color: string
+  reducedMotion: boolean
+  fontFamily: string
+  fontSize: number
+  lineHeight: number
+  fontWeight?: TextStyle['fontWeight']
+  letterSpacing?: number
+}
+
+function AnimatedLetter({ char, index, color, reducedMotion, fontFamily, fontSize, lineHeight, fontWeight, letterSpacing }: AnimatedLetterProps) {
+  const progress = useSharedValue(reducedMotion ? 1 : 0)
+
+  useEffect(() => {
+    if (reducedMotion) return
+    progress.value = withDelay(index * STAGGER_MS, withTiming(1, { duration: LETTER_DURATION_MS, easing: Easing.out(Easing.back(1.5)) }))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reducedMotion])
+
+  const style = useAnimatedStyle(() => ({
+    opacity: progress.value,
+    transform: [{ translateY: (1 - progress.value) * 12 }, { scale: 0.85 + progress.value * 0.15 }]
+  }))
+
+  return (
+    <Animated.Text allowFontScaling={false} style={[{ color, fontFamily, fontSize, lineHeight, fontWeight, letterSpacing }, style]}>
+      {char}
+    </Animated.Text>
+  )
+}
+
+export interface StaggeredWordProps {
+  word: string
+  color: string
+  fontFamily: string
+  fontSize: number
+  lineHeight: number
+  // Whether to skip the stagger entirely and render every letter already fully settled — wire
+  // straight from react-native-reanimated's own useReducedMotion() at the call site rather than
+  // this component calling it internally, so a caller composing several StaggeredWords (see
+  // `startIndex` below) only needs the one hook call, not one per word.
+  reducedMotion: boolean
+  // Continues the stagger sequence from a larger overall wordmark this word is only one line/part
+  // of — this word's own first letter animates at index `startIndex`, its second at
+  // `startIndex + 1`, and so on. Defaults to 0 for a standalone single-word wordmark (Snake's
+  // "SNAKE", Pong's "PONG"); a caller stacking multiple words (AirHockey's "AIR"/"HOCKEY",
+  // BoxHockey's "BOX"/"HOCKEY", LightCycles' "Light"/"Cycles") passes the running total of letters
+  // already animated by earlier words, so the whole wordmark reads as one continuous cascade
+  // instead of each word restarting its own stagger from zero.
+  startIndex?: number
+  // Every consumer this component was extracted from hardcoded bold letters (baked into a fixed
+  // StyleSheet entry, not a prop) — kept as the default here rather than a fixed style, so the one
+  // consumer that doesn't want it (LightCycles, whose own registered display font is already
+  // sufficiently bold on its own) can opt out with `fontWeight='normal'` instead of this component
+  // forcing it unconditionally.
+  fontWeight?: TextStyle['fontWeight']
+  // Unset by default — only AirHockey/BoxHockey/Pong's shared MONO_FONT-based letter style actually
+  // wants extra tracking; Snake's/LightCycles' own theme fonts don't.
+  letterSpacing?: number
+  // The wrapping row's own style — e.g. LightCycles' own vertical offset for its second word
+  // beneath its first.
+  style?: StyleProp<ViewStyle>
+  // Lets a caller measure this word's own rendered box (e.g. to size/position a follow-on canvas
+  // overlay the way Snake's HeroSnakeTrail or LightCycles' HeroTitleTrails do) the same way it
+  // would measure any other plain View.
+  onLayout?: (e: LayoutChangeEvent) => void
+}
+
+// One row of letters staggering in on mount (or rendered already fully settled under reduced
+// motion) — the "AnimatedLetter" building block five apps' own hero-title screens
+// (AirHockey/BoxHockey/Pong/LightCycles/Snake's own HeroTitle.tsx/AnimatedHeroTitle.tsx) had each
+// hand-rolled independently, identical down to the same 45ms stagger, 320ms per-letter duration,
+// and back-ease overshoot. A single word/line on its own, or one of several stacked/side-by-side
+// words sharing one overall stagger sequence via `startIndex` — this component only ever renders
+// one row of letters; a caller composing more than one word renders more than one StaggeredWord
+// (see `startIndex`'s own doc), the same way every one of those five apps' own `Word` helper
+// already did internally.
+export function StaggeredWord({ word, color, fontFamily, fontSize, lineHeight, reducedMotion, startIndex = 0, fontWeight = 'bold', letterSpacing, style, onLayout }: StaggeredWordProps) {
+  return (
+    <View style={[styles.row, style]} onLayout={onLayout}>
+      {word.split('').map((char, i) => (
+        <AnimatedLetter key={i} char={char} index={startIndex + i} color={color} reducedMotion={reducedMotion} fontFamily={fontFamily} fontSize={fontSize} lineHeight={lineHeight} fontWeight={fontWeight} letterSpacing={letterSpacing} />
+      ))}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: 'row'
+  }
+})

package/src/guide/DirectionKeysHint.tsx

@@ -0,0 +1,96 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { StyleSheet, View } from 'react-native'
+import { Icon, Text } from 'react-native-paper'
+
+export interface DirectionKeyLabels {
+  up: string
+  left: string
+  down: string
+  right: string
+}
+
+export type DirectionKeysAxis = 'both' | 'vertical'
+
+export interface DirectionKeysHintProps {
+  // What's printed on each cap — e.g. { up: 'W', left: 'A', down: 'S', right: 'D' }. Omit for the
+  // arrow keys themselves, drawn as arrow icons (so does any single cap left out). Pass whatever the
+  // seat's own key scheme actually is, not a guess: the fleet games let each seat pick WASD, arrows,
+  // IJKL and so on.
+  labels?: Partial<DirectionKeyLabels>
+  // 'both' (default) draws the four-key inverted T. 'vertical' draws only up above down, for a game
+  // whose controls only ever read those two (Pong's paddles).
+  axis?: DirectionKeysAxis
+  // Defaults to the theme's own primary — i.e. player 1's seat color in the fleet games.
+  color?: string
+}
+
+const CAP_SIZE = 34
+
+const ARROWS: DirectionKeyLabels = { up: 'arrow-up', left: 'arrow-left', down: 'arrow-down', right: 'arrow-right' }
+
+function KeyCap({ label, icon, color }: { label?: string; icon: string; color: string }) {
+  return (
+    <View style={[styles.cap, { borderColor: color }]}>
+      {label !== undefined ? (
+        <Text variant='titleMedium' style={[styles.capLabel, { color }]}>
+          {label}
+        </Text>
+      ) : (
+        <Icon source={icon} size={20} color={color} />
+      )}
+    </View>
+  )
+}
+
+// Key caps in the inverted-T every keyboard player already knows (or just up over down, see `axis`) —
+// the desktop counterpart to SwipeHint for the "how do I steer" card, since a desktop browser steers by
+// key, not by swipe. Plain Views, no animation, so there's nothing for reduced motion to switch off.
+export function DirectionKeysHint({ labels, axis = 'both', color }: DirectionKeysHintProps) {
+  const { colors } = useAutoPaperTheme()
+  const tint = color ?? colors.primary
+
+  if (axis === 'vertical') {
+    const accessibilityLabel = labels?.up && labels.down ? `Keys ${labels.up} and ${labels.down}` : 'Up and down arrow keys'
+    return (
+      <View accessible accessibilityLabel={accessibilityLabel} style={styles.cluster}>
+        <KeyCap label={labels?.up} icon={ARROWS.up} color={tint} />
+        <KeyCap label={labels?.down} icon={ARROWS.down} color={tint} />
+      </View>
+    )
+  }
+
+  const accessibilityLabel = labels?.up && labels.left && labels.down && labels.right ? `Keys ${labels.up}, ${labels.left}, ${labels.down}, ${labels.right}` : 'Arrow keys'
+
+  return (
+    <View accessible accessibilityLabel={accessibilityLabel} style={styles.cluster}>
+      <KeyCap label={labels?.up} icon={ARROWS.up} color={tint} />
+      <View style={styles.row}>
+        <KeyCap label={labels?.left} icon={ARROWS.left} color={tint} />
+        <KeyCap label={labels?.down} icon={ARROWS.down} color={tint} />
+        <KeyCap label={labels?.right} icon={ARROWS.right} color={tint} />
+      </View>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  cap: {
+    alignItems: 'center',
+    borderRadius: 8,
+    borderWidth: 2,
+    height: CAP_SIZE,
+    justifyContent: 'center',
+    width: CAP_SIZE
+  },
+  capLabel: {
+    fontWeight: 'bold'
+  },
+  cluster: {
+    alignItems: 'center',
+    gap: 6
+  },
+  row: {
+    flexDirection: 'row',
+    gap: 6
+  }
+})

package/src/guide/GuideProvider.tsx

@@ -0,0 +1,87 @@
+import { createContext, type ReactNode, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
+
+import { HowToPlayDialog } from './HowToPlayDialog'
+import type { GuideRotation, GuideStep } from './types'
+
+interface GuideContextValue {
+  isOpen: boolean
+  // Opens the guide unconditionally — the Settings "How to play" row's whole job. Never persists
+  // anything on its own: only finishing or skipping does, and only while the player hasn't already
+  // seen this version.
+  open: () => void
+  close: () => void
+  // Opens it once per session, and only if this player hasn't seen `currentVersion` yet — see
+  // useAutoShowGuide.
+  requestAutoShow: () => void
+}
+
+const noop = () => {}
+
+// A default that does nothing rather than throwing when there's no provider above — an app's own
+// existing tests render its Settings dialog or Home screen without one, and a "How to play" row that
+// silently does nothing in that harness is a far better failure than every such test breaking.
+const GuideContext = createContext<GuideContextValue>({ isOpen: false, open: noop, close: noop, requestAutoShow: noop })
+
+export interface GuideProviderProps {
+  steps: GuideStep[]
+  // Bumped by the app only for a genuine controls/rules change, to re-prompt everyone.
+  currentVersion: number
+  // Read from the app's own persisted store (see createGuideSlice's selectVersionSeen).
+  seenVersion: number
+  // Called with `currentVersion` when the player finishes or skips a guide they hadn't seen yet.
+  onSeen: (version: number) => void
+  // The app's live fake-landscape rotation (see GuideRotation). The card rotates and sizes itself for it.
+  rotation?: GuideRotation
+  children?: ReactNode
+}
+
+// Mounted once at the app root, next to <UpdateDialog /> — the fleet's existing "self-presenting
+// app-level dialog" seat — so any screen can open it through useGuide() without prop-drilling, and
+// the Portal it renders sits above every route. Inside PersistGate, so `seenVersion` is already the
+// rehydrated value by the time this first renders.
+export function GuideProvider({ steps, currentVersion, seenVersion, onSeen, rotation, children }: GuideProviderProps) {
+  const [isOpen, setIsOpen] = useState(false)
+  // Once per session, not once per Home mount — Home remounts every time the player backs out of a
+  // match, and skipping shouldn't be something they have to do again a minute later just because the
+  // persisted flag hadn't been written back through the store yet.
+  const autoShownRef = useRef(false)
+  const unseen = seenVersion < currentVersion
+
+  const open = useCallback(() => setIsOpen(true), [])
+
+  const close = useCallback(() => {
+    setIsOpen(false)
+    if (unseen) onSeen(currentVersion)
+  }, [unseen, onSeen, currentVersion])
+
+  const requestAutoShow = useCallback(() => {
+    if (!unseen || autoShownRef.current) return
+    autoShownRef.current = true
+    setIsOpen(true)
+  }, [unseen])
+
+  const value = useMemo(() => ({ isOpen, open, close, requestAutoShow }), [isOpen, open, close, requestAutoShow])
+
+  return (
+    <GuideContext.Provider value={value}>
+      {children}
+      <HowToPlayDialog visible={isOpen} steps={steps} onFinish={close} onSkip={close} rotation={rotation} />
+    </GuideContext.Provider>
+  )
+}
+
+export function useGuide(): GuideContextValue {
+  return useContext(GuideContext)
+}
+
+// Call this from the Home screen and nowhere else — that placement, not any route check in here, is
+// what keeps it from ever firing over a live match or a two-seat loadout. Home is the one screen
+// with a single reader, before any seating, so a face-to-face two-player phone doesn't need per-seat
+// rotated copies of the card. `enabled` lets a caller hold it back (e.g. while a shared-link import
+// is being handled) without breaking the rules of hooks by conditionally calling this.
+export function useAutoShowGuide(enabled = true) {
+  const { requestAutoShow } = useGuide()
+  useEffect(() => {
+    if (enabled) requestAutoShow()
+  }, [enabled, requestAutoShow])
+}