@tastic/hud 0.12.0 → 0.13.0

package/src/guide/HowToPlayDialog.tsx

@@ -0,0 +1,224 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { Button } from '@rific/feedback-press'
+import { useEffect, useRef, useState } from 'react'
+import { BackHandler, type NativeScrollEvent, type NativeSyntheticEvent, ScrollView, StyleSheet, useWindowDimensions, View } from 'react-native'
+import { Portal, Text } from 'react-native-paper'
+import { useReducedMotion } from 'react-native-reanimated'
+
+import { getOverlayCardColors, overlayActionStyles, overlayStyles } from '../overlayCard'
+import type { GuideRotation, GuideStep } from './types'
+
+// The overlay's own breathing room and the card's own inner padding. Together with the card's max
+// width these fix the width of one page exactly, which the paging ScrollView below needs up front (it
+// snaps to multiples of it) rather than measuring after layout.
+const OVERLAY_GUTTER = 24
+const CARD_PADDING = 24
+const MAX_CARD_WIDTH = 360
+// A quarter-turned card has the phone's long edge to spread across, so it's allowed wider: shorter
+// lines mean fewer of them, which is what actually has to fit (see sizing below).
+const MAX_CARD_WIDTH_TURNED = 520
+const ART_HEIGHT = 132
+// Below this much usable height the illustration box shrinks. Sized so the full card (padding, art,
+// title, two lines of body, dots, buttons) fits a 360pt-wide phone held sideways.
+const COMPACT_BELOW = 480
+const ART_HEIGHT_COMPACT = 88
+
+// Where the card has to fit. The fleet's rotation is FAKE: the OS window stays portrait and the card
+// is only turned with a transform, so a quarter-turned card's on-screen width is its layout HEIGHT,
+// which must fit the window's short edge, and its on-screen height is its layout width. Sizing it
+// against the unswapped window (what the first version did) let a sideways card run off a small
+// phone. Exported for tests.
+export function getGuideCardSize(windowWidth: number, windowHeight: number, rotation: GuideRotation) {
+  const turned = rotation === 90 || rotation === -90
+  const availableWidth = (turned ? windowHeight : windowWidth) - OVERLAY_GUTTER * 2
+  const availableHeight = (turned ? windowWidth : windowHeight) - OVERLAY_GUTTER * 2
+  const width = Math.min(turned ? MAX_CARD_WIDTH_TURNED : MAX_CARD_WIDTH, availableWidth)
+  return {
+    width,
+    pageWidth: width - CARD_PADDING * 2,
+    maxHeight: availableHeight,
+    artHeight: availableHeight < COMPACT_BELOW ? ART_HEIGHT_COMPACT : ART_HEIGHT
+  }
+}
+
+export interface HowToPlayDialogProps {
+  visible: boolean
+  steps: GuideStep[]
+  // Last card's primary button.
+  onFinish: () => void
+  // Skip (first card only — see the action row), and Android's hardware back button — both mean "I don't need this", so a caller persisting
+  // "seen" should treat them exactly like onFinish.
+  onSkip: () => void
+  // The app's live fake-landscape rotation (see GuideRotation). Portal content escapes any rotated
+  // ancestor, so the card rotates itself, and sizes itself for the turn (see getGuideCardSize).
+  rotation?: GuideRotation
+}
+
+type CardProps = Omit<HowToPlayDialogProps, 'visible'>
+
+function HowToPlayCard({ steps, onFinish, onSkip, rotation = 0 }: CardProps) {
+  const { dark, colors } = useAutoPaperTheme()
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions()
+  const reducedMotion = useReducedMotion()
+  const [index, setIndex] = useState(0)
+  const scrollRef = useRef<ScrollView>(null)
+
+  // Android's hardware back would otherwise fall through to the router underneath and pop a screen
+  // (or exit the app) with the guide still up. Treated as Skip, the same as the on-screen button.
+  useEffect(() => {
+    const subscription = BackHandler.addEventListener('hardwareBackPress', () => {
+      onSkip()
+      return true
+    })
+    return () => subscription.remove()
+  }, [onSkip])
+
+  const { fg, cardBg, cardBorder, fgMuted } = getOverlayCardColors(dark)
+  const { width: cardWidth, pageWidth, maxHeight, artHeight } = getGuideCardSize(windowWidth, windowHeight, rotation)
+  const rotationStyle = rotation === 0 ? undefined : { transform: [{ rotate: `${rotation}deg` }] }
+  const isFirst = index === 0
+  const isLast = index === steps.length - 1
+  const isOnly = steps.length === 1
+  const artBackground = dark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.05)'
+
+  // The page a Next/Back tap is animating to, while it's on its way. An animated scrollTo emits every
+  // offset in between through onScroll, and without this the dots and buttons would flip back to the
+  // page being left for the first half of the animation.
+  const targetRef = useRef<number | null>(null)
+
+  function goTo(next: number) {
+    targetRef.current = next
+    setIndex(next)
+    scrollRef.current?.scrollTo({ x: next * pageWidth, animated: !reducedMotion })
+  }
+
+  // Keeps the dots and buttons in step with a swipe (or a trackpad scroll on web). onScroll, not only
+  // onMomentumScrollEnd: react-native-web never fires the momentum events, so on web a swipe moved the
+  // cards while the dots and buttons stayed on the old page (Jay spotted it in Solitaire). The index
+  // follows whichever page is more than half in view, the same moment a native pager's dots change.
+  function syncToOffset(offsetX: number) {
+    const page = Math.round(offsetX / pageWidth)
+    if (page < 0 || page >= steps.length) return
+    if (targetRef.current !== null) {
+      if (page === targetRef.current) targetRef.current = null
+      return
+    }
+    setIndex(page)
+  }
+
+  function handleScroll(e: NativeSyntheticEvent<NativeScrollEvent>) {
+    syncToOffset(e.nativeEvent.contentOffset.x)
+  }
+
+  // Native's settle event: also clears a pending target, in case the animation was interrupted by a
+  // drag before it reached its page.
+  function handleMomentumEnd(e: NativeSyntheticEvent<NativeScrollEvent>) {
+    targetRef.current = null
+    syncToOffset(e.nativeEvent.contentOffset.x)
+  }
+
+  return (
+    <Portal>
+      <View style={[overlayStyles.overlay, styles.overlay]}>
+        <View accessibilityViewIsModal style={[overlayStyles.card, styles.card, { width: cardWidth, maxHeight, backgroundColor: cardBg, borderColor: cardBorder }, rotationStyle]}>
+          {/* The pager shrinks (flexShrink) when the card hits maxHeight, and each page is its own
+            vertical ScrollView, so a page that still doesn't fit (a long translation, large text)
+            scrolls instead of being clipped. In the normal case nothing scrolls. */}
+          <ScrollView ref={scrollRef} horizontal pagingEnabled showsHorizontalScrollIndicator={false} onScroll={handleScroll} scrollEventThrottle={16} onMomentumScrollEnd={handleMomentumEnd} style={[styles.pager, { width: pageWidth }]}>
+            {steps.map((step, i) => (
+              <ScrollView key={i} nestedScrollEnabled showsVerticalScrollIndicator={false} style={{ width: pageWidth }} contentContainerStyle={styles.page}>
+                {step.art !== undefined && <View style={[styles.art, { height: artHeight, backgroundColor: artBackground }]}>{step.art}</View>}
+                <Text variant='headlineSmall' style={[styles.title, { color: fg }]}>
+                  {step.title}
+                </Text>
+                <Text variant='bodyMedium' style={[styles.body, { color: fg }]}>
+                  {step.body}
+                </Text>
+              </ScrollView>
+            ))}
+          </ScrollView>
+
+          {steps.length > 1 && (
+            <View accessible accessibilityLabel={`Step ${index + 1} of ${steps.length}`} style={styles.dots}>
+              {steps.map((_, i) => (
+                <View key={i} style={[styles.dot, { backgroundColor: i === index ? colors.primary : fgMuted }]} />
+              ))}
+            </View>
+          )}
+
+          {/* ConfirmDialog's exact row (see overlayActionStyles): outlined secondary on the left,
+            contained primary on the right. Skip and Back share the one secondary slot — three
+            full-size buttons don't fit side by side at the row's 128 minimum — so Skip is only
+            offered on the first card; after that the way out is Next to the end (a short flow) or
+            Android's hardware back, which skips from anywhere. */}
+          <View style={overlayActionStyles.actions}>
+            {!isOnly && (
+              <Button mode='outlined' onPress={isFirst ? onSkip : () => goTo(index - 1)} style={overlayActionStyles.actionButton}>
+                {isFirst ? 'Skip' : 'Back'}
+              </Button>
+            )}
+            <Button mode='contained' onPress={isLast ? onFinish : () => goTo(index + 1)} style={isOnly ? overlayActionStyles.actionButtonSingle : overlayActionStyles.actionButton} buttonColor={colors.primary} textColor={colors.onPrimary}>
+              {isLast ? 'Ready' : 'Next'}
+            </Button>
+          </View>
+        </View>
+      </View>
+    </Portal>
+  )
+}
+
+// A short, skippable, paged "how to play" card — the one shared shape every fleet game's intro takes,
+// built on the same retro overlay-card look as ConfirmDialog (see overlayCard.ts) so it reads as
+// part of the same family. Controlled and presentational: whether it's visible, and what happens on
+// finish/skip (persisting "seen", mostly), is the caller's — see GuideProvider for the wiring nearly
+// every app wants. Buttons are the primary way through; the paging ScrollView underneath is what
+// makes a swipe work too, with no gesture-handler dependency.
+//
+// Split into an outer visibility gate and an inner card so the card's own page index is created
+// fresh every time it opens — a replay from Settings always starts on the first card, with no
+// effect needed to reset it.
+export function HowToPlayDialog({ visible, steps, ...rest }: HowToPlayDialogProps) {
+  if (!visible || steps.length === 0) return null
+  return <HowToPlayCard steps={steps} {...rest} />
+}
+
+const styles = StyleSheet.create({
+  art: {
+    alignItems: 'center',
+    borderRadius: 12,
+    justifyContent: 'center',
+    overflow: 'hidden',
+    width: '100%'
+  },
+  body: {
+    textAlign: 'center'
+  },
+  // Additive on top of overlayCard's own shared `card` shape — its default 32px padding is tighter
+  // here (a paged card wants more width for its art) and the shared 16px gap is right.
+  card: {
+    padding: CARD_PADDING
+  },
+  dot: {
+    borderRadius: 4,
+    height: 8,
+    width: 8
+  },
+  dots: {
+    flexDirection: 'row',
+    gap: 8
+  },
+  overlay: {
+    paddingHorizontal: OVERLAY_GUTTER
+  },
+  page: {
+    alignItems: 'center',
+    gap: 12
+  },
+  pager: {
+    flexShrink: 1
+  },
+  title: {
+    fontWeight: 'bold',
+    textAlign: 'center'
+  }
+})

package/src/guide/SeatDevicesHint.tsx

@@ -0,0 +1,52 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { StyleSheet, View } from 'react-native'
+import { Icon } from 'react-native-paper'
+
+export type SeatDevice = 'keyboard' | 'mouse'
+
+export interface SeatDevicesHintProps {
+  // What each seat plays with right now, in seat order (index 0 = player 1). Map the app's own live
+  // control scheme onto this: a key scheme is 'keyboard', a pointer scheme is 'mouse'.
+  devices: readonly SeatDevice[]
+  // Each seat's color, same order. Defaults to the theme's primary/secondary, which ARE the two seats'
+  // colors in the fleet games.
+  seatColors?: readonly string[]
+}
+
+const ICON: Record<SeatDevice, { source: string; size: number }> = {
+  keyboard: { source: 'keyboard-outline', size: 56 },
+  mouse: { source: 'mouse-outline', size: 44 }
+}
+
+const ORDER: readonly SeatDevice[] = ['keyboard', 'mouse']
+
+// "Two players, one computer": the desktop counterpart to SeatDiagram on the two-player card. One icon
+// per device the seats actually use (a keyboard if either is on keys, a mouse if either drags), each
+// tinted in the color of the one seat using it, or the neutral onSurface when both share it. So the
+// fleet's common default of P1 on the mouse and P2 on WASD reads as a P1-colored mouse beside a
+// P2-colored keyboard, and a keys-only setup as one plain keyboard. Snake, AirHockey and Pong each drew
+// their own copy of this before it existed here. Plain Icons, no animation.
+export function SeatDevicesHint({ devices, seatColors }: SeatDevicesHintProps) {
+  const { colors } = useAutoPaperTheme()
+  const tints = seatColors ?? [colors.primary, colors.secondary]
+  const accessibilityLabel = devices.map((device, i) => `Player ${i + 1} uses the ${device}`).join(', ')
+
+  return (
+    <View accessible accessibilityLabel={accessibilityLabel} style={styles.row}>
+      {ORDER.map((device) => {
+        const seats = devices.flatMap((d, i) => (d === device ? [i] : []))
+        if (seats.length === 0) return null
+        const color = seats.length === 1 ? (tints[seats[0]] ?? colors.onSurface) : colors.onSurface
+        return <Icon key={device} source={ICON[device].source} size={ICON[device].size} color={color} />
+      })}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  row: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    gap: 20
+  }
+})

package/src/guide/SeatDiagram.tsx

@@ -0,0 +1,72 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { StyleSheet, View } from 'react-native'
+import { Text } from 'react-native-paper'
+
+export interface SeatDiagramProps {
+  // Default to the theme's own secondary/primary — in the fleet games those ARE the two players'
+  // live seat colors, so the picture always matches whatever colors they've picked.
+  topColor?: string
+  bottomColor?: string
+  topLabel?: string
+  bottomLabel?: string
+}
+
+const DEVICE_WIDTH = 88
+const DEVICE_HEIGHT = 120
+
+// "Two players, one phone": a portrait phone split into a top half and a bottom half, each tinted in
+// its own seat color, with the top label upside down the way that player actually reads it. The
+// seating card every face-to-face game (LightCycles, Snake, AirHockey, BoxHockey, Pong) needs, drawn
+// once. Plain Views, no animation — nothing here needs reduced-motion handling.
+export function SeatDiagram({ topColor, bottomColor, topLabel = 'P2', bottomLabel = 'P1' }: SeatDiagramProps) {
+  const { colors } = useAutoPaperTheme()
+  const top = topColor ?? colors.secondary
+  const bottom = bottomColor ?? colors.primary
+
+  return (
+    <View accessible accessibilityLabel={`${bottomLabel} plays the bottom half, ${topLabel} plays the top half`} style={[styles.device, { borderColor: colors.onSurface }]}>
+      <View style={[styles.half, { borderColor: top }]}>
+        <View style={[StyleSheet.absoluteFill, styles.tint, { backgroundColor: top }]} />
+        <Text variant='titleMedium' style={[styles.label, styles.flipped, { color: top }]}>
+          {topLabel}
+        </Text>
+      </View>
+      <View style={[styles.half, styles.bottomHalf, { borderColor: bottom }]}>
+        <View style={[StyleSheet.absoluteFill, styles.tint, { backgroundColor: bottom }]} />
+        <Text variant='titleMedium' style={[styles.label, { color: bottom }]}>
+          {bottomLabel}
+        </Text>
+      </View>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  bottomHalf: {
+    borderTopWidth: 0
+  },
+  device: {
+    borderRadius: 16,
+    borderWidth: 2,
+    height: DEVICE_HEIGHT,
+    overflow: 'hidden',
+    width: DEVICE_WIDTH
+  },
+  flipped: {
+    transform: [{ rotate: '180deg' }]
+  },
+  half: {
+    alignItems: 'center',
+    borderWidth: 2,
+    flex: 1,
+    justifyContent: 'center'
+  },
+  label: {
+    fontWeight: 'bold'
+  },
+  // A wash of the seat color behind its own label rather than an rgba() fill — the theme's colors
+  // aren't guaranteed to be 6-digit hex, so an opacity layer is the only alpha that always works.
+  tint: {
+    opacity: 0.2
+  }
+})

package/src/guide/SwipeHint.tsx

@@ -0,0 +1,115 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { useEffect } from 'react'
+import { StyleSheet, View } from 'react-native'
+import { Icon } from 'react-native-paper'
+import Animated, { Easing, useAnimatedStyle, useReducedMotion, useSharedValue, withRepeat, withSequence, withTiming } from 'react-native-reanimated'
+
+export type SwipeDirection = 'up' | 'down' | 'left' | 'right'
+export type SwipePointer = 'finger' | 'mouse'
+
+export interface SwipeHintProps {
+  direction?: SwipeDirection
+  // What sweeps along the path: a fingertip ring (a touch screen) or a mouse (a desktop seat that
+  // plays by dragging). The mouse variant also relabels itself "Drag" for screen readers, since a
+  // desktop player should never be told to swipe.
+  pointer?: SwipePointer
+  // Defaults to the theme's own primary — i.e. the player's own seat color in the fleet games.
+  color?: string
+  // Length of the dotted path in points, arrowhead excluded.
+  length?: number
+}
+
+const DOT_COUNT = 7
+const FINGER_SIZE = 28
+const MOUSE_SIZE = 30
+const SWEEP_MS = 900
+const PAUSE_MS = 500
+
+const ARROW_ICON: Record<SwipeDirection, string> = { up: 'arrow-up', down: 'arrow-down', left: 'arrow-left', right: 'arrow-right' }
+
+// A finger-sized ring (or, with pointer='mouse', a mouse) sweeping along a dotted path toward an
+// arrowhead, on a loop — the "swipe this way" illustration the arcade games (LightCycles, Snake, Pong,
+// AirHockey, BoxHockey) each need for their first card, so it lives here once rather than being
+// redrawn per app. The mouse variant is the same card on desktop web for a seat that plays by
+// dragging; Snake and AirHockey each drew their own before it existed. Plain Views plus Reanimated:
+// no Skia, no SVG, so it renders identically in every consuming app (Hangman, which has neither,
+// included). Under reduced motion the pointer just rests at the midpoint, still visible.
+export function SwipeHint({ direction = 'right', pointer = 'finger', color, length = 96 }: SwipeHintProps) {
+  const { colors } = useAutoPaperTheme()
+  const tint = color ?? colors.primary
+  const reducedMotion = useReducedMotion()
+  const progress = useSharedValue(0.5)
+  const horizontal = direction === 'left' || direction === 'right'
+  // Which way the finger travels along its own axis — left/up run against the positive x/y axes.
+  const sign = direction === 'right' || direction === 'down' ? 1 : -1
+
+  useEffect(() => {
+    if (reducedMotion) {
+      progress.value = 0.5
+      return
+    }
+    // Sweep out, hold (the ring fades while it rests at the end), then snap back to the start.
+    progress.value = 0
+    progress.value = withRepeat(withSequence(withTiming(1, { duration: SWEEP_MS, easing: Easing.out(Easing.cubic) }), withTiming(1, { duration: PAUSE_MS }), withTiming(0, { duration: 0 })), -1)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reducedMotion])
+
+  const fingerStyle = useAnimatedStyle(() => {
+    const travel = (progress.value - 0.5) * length * sign
+    return {
+      opacity: reducedMotion ? 1 : Math.min(1, progress.value * 6, (1 - progress.value) * 6 + 0.001),
+      transform: horizontal ? [{ translateX: travel }] : [{ translateY: travel }]
+    }
+  })
+
+  const axis = horizontal ? (sign > 0 ? 'row' : 'row-reverse') : sign > 0 ? 'column' : 'column-reverse'
+
+  return (
+    <View accessibilityLabel={`${pointer === 'mouse' ? 'Drag' : 'Swipe'} ${direction}`} accessible style={[styles.path, { flexDirection: axis }]}>
+      <View style={[styles.dots, { flexDirection: axis, [horizontal ? 'width' : 'height']: length }]}>
+        {Array.from({ length: DOT_COUNT }, (_, i) => (
+          <View key={i} style={[styles.dot, { backgroundColor: tint, opacity: 0.35 + (0.65 * i) / (DOT_COUNT - 1) }]} />
+        ))}
+      </View>
+      <Icon source={ARROW_ICON[direction]} size={28} color={tint} />
+      {pointer === 'mouse' ? (
+        <Animated.View style={[styles.mouse, fingerStyle]}>
+          <Icon source='mouse' size={MOUSE_SIZE} color={tint} />
+        </Animated.View>
+      ) : (
+        <Animated.View style={[styles.finger, { borderColor: tint }, fingerStyle]} />
+      )}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  dot: {
+    borderRadius: 3,
+    height: 6,
+    width: 6
+  },
+  dots: {
+    alignItems: 'center',
+    justifyContent: 'space-between'
+  },
+  // Centered on the whole path (not on the dots row alone) by the container's own alignItems/
+  // justifyContent, then pushed along the axis by its own animated translate — absolute so it never
+  // takes space from the dots and arrowhead it's drawn over.
+  finger: {
+    borderRadius: FINGER_SIZE / 2,
+    borderWidth: 3,
+    height: FINGER_SIZE,
+    position: 'absolute',
+    width: FINGER_SIZE
+  },
+  // Positioned exactly like `finger` (absolute, centered by the container, moved by the same animated
+  // translate); only what's drawn differs.
+  mouse: {
+    position: 'absolute'
+  },
+  path: {
+    alignItems: 'center',
+    justifyContent: 'center'
+  }
+})

package/src/guide/guideSlice.ts

@@ -0,0 +1,131 @@
+// redux-persist's own REHYDRATE action-type constant, inlined as a literal rather than taking a
+// dependency on the package itself — same reasoning as @tastic/profile's createSeatColorsSlice, whose
+// factory shape this follows: this file has no opinion on whether the consuming app uses
+// redux-persist at all, and the string is a long-stable part of its public contract.
+const REHYDRATE = 'persist/REHYDRATE'
+
+export interface GuideState {
+  // The highest guide version this player has finished or skipped — 0 means "never". Compared
+  // against the app's own `currentVersion`, so bumping that later re-prompts everyone (only worth
+  // doing for a genuine controls/rules change, not a copy tweak).
+  versionSeen: number
+}
+
+// A `type` alias, not an `interface`, on purpose: redux's UnknownAction has a string index signature,
+// and only an object-literal type alias (never an interface) is implicitly assignable to one — with an
+// interface here `configureStore` rejects the reducer at the consuming app's own typecheck.
+export type GuideAction = {
+  type: string
+  payload?: unknown
+  // Present on redux-persist's own REHYDRATE action (the persistConfig `key` it belongs to).
+  key?: string
+}
+
+export interface GuideSliceOptions {
+  // What a player who has already seen (or been grandfathered past) the guide is stamped with.
+  currentVersion: number
+  // The key the reducer is mounted under in the app's own combineReducers({...}) — redux-persist's
+  // REHYDRATE payload is keyed by it, and a reducer has no way to see its own mount key.
+  mountKey?: string
+  // The persistConfig `key` of the store this reducer lives in. A REHYDRATE for any OTHER persisted
+  // reducer (a nested persistReducer) carries that reducer's own substate, which would otherwise
+  // look exactly like "an existing player with no guide key".
+  persistKey?: string
+}
+
+export interface GuideSlice {
+  actions: { markSeen: (version: number) => { type: string; payload: number } }
+  reducer: (state: GuideState | undefined, action: GuideAction) => GuideState
+  selectVersionSeen: (rootState: object) => number
+}
+
+// The persisted "has this player seen the how-to-play flow" flag, as its own slice rather than a
+// field on any app's settings blob — every fleet app already has a redux-persist root store behind a
+// PersistGate, and a dedicated key survives 'Reset stats'/'Reset match settings' (neither touches
+// Redux) without needing any of the four strict per-app settings validators to learn a new field.
+//
+// The one thing a plain settings field can't do, and the reason this is a factory instead of a
+// createSettingsSlice call: tell a FRESH install from an EXISTING player who just updated. On a
+// fresh install redux-persist's getStoredState finds nothing under the persistConfig key and
+// REHYDRATE arrives with `payload === undefined`; an existing player has a payload object that
+// simply predates this slice and so has no `[mountKey]` entry. The first shows the guide; the
+// second is grandfathered — stamped as already having seen `currentVersion` — so nobody who has been
+// playing gets a "how to play" screen after an over-the-air update. Both can still replay it from
+// Settings.
+//
+// redux-persist's default stateReconciler (autoMergeLevel1) skips any substate a reducer already
+// changed while handling REHYDRATE, so the value returned here for an existing player wins rather
+// than being overwritten.
+export function createGuideSlice({ currentVersion, mountKey = 'guide', persistKey = 'root' }: GuideSliceOptions): GuideSlice {
+  const MARK_SEEN = `${mountKey}/markSeen`
+  const initialState: GuideState = { versionSeen: 0 }
+
+  function markSeen(version: number) {
+    return { type: MARK_SEEN, payload: version }
+  }
+
+  function reducer(state: GuideState = initialState, action: GuideAction): GuideState {
+    if (action.type === REHYDRATE) {
+      if (action.key !== undefined && action.key !== persistKey) return state
+      const payload = action.payload as Record<string, Partial<GuideState> | undefined> | undefined
+      // Nothing persisted at all (fresh install) — or the read failed, which shows the guide once
+      // more rather than silently skipping it.
+      if (!payload) return state
+      const persisted = payload[mountKey]
+      if (typeof persisted?.versionSeen === 'number') return { versionSeen: persisted.versionSeen }
+      return { versionSeen: currentVersion }
+    }
+    if (action.type === MARK_SEEN && typeof action.payload === 'number') {
+      return { versionSeen: Math.max(state.versionSeen, action.payload) }
+    }
+    return state
+  }
+
+  function selectVersionSeen(rootState: object): number {
+    return (rootState as Record<string, GuideState | undefined>)[mountKey]?.versionSeen ?? 0
+  }
+
+  return { actions: { markSeen }, reducer, selectVersionSeen }
+}
+
+// The one AsyncStorage call createReturningPlayerMigrate needs, passed in (apps pass AsyncStorage
+// itself) so this entry point never imports it.
+export interface GuideStorageReader {
+  getItem: (key: string) => Promise<string | null>
+}
+
+// Structurally identical to redux-persist's own PersistedState, so the returned function drops straight
+// into a persistConfig's `migrate` without this package depending on redux-persist.
+export type GuidePersistedState = { _persist: { version: number; rehydrated: boolean } } | undefined
+
+// For a persistConfig's `migrate`. createGuideSlice grandfathers a player by finding a persisted root
+// store with no guide entry in it, which only works for a player whose last build already HAD that root
+// store. Most of the fleet (LightCycles, AirHockey, BoxHockey, Pong) only got a redux-persist root store
+// after its last shipped update, so their current players have no root store at all: on their first
+// launch of a guide build REHYDRATE would arrive with no payload, exactly like a fresh install, and the
+// guide would greet people who've been playing for weeks.
+//
+// Those earlier builds did write their own AsyncStorage keys (settings, stats, appearance, ...), which
+// are passed in as `legacyKeys`. So: no root store, but any legacy key present, means "played an earlier
+// build", and that player is rehydrated with an empty payload instead, which the guide slice reads as an
+// existing player and stamps as seen. An empty payload is a no-op for every other slice (nothing to merge,
+// and redux-persist's reconciler skips `_persist`). A root store that already exists passes through
+// untouched, so this is a no-op for every launch after the first. A failed read falls back to the
+// fresh-install behavior (the guide shows once), the same as the slice itself.
+//
+// Runs before REHYDRATE and before PersistGate lets anything render, so there's no race with Home's
+// auto-show. List the keys the shipped builds actually wrote (read them from the last shipped commit, not
+// today's source). The one thing to avoid is a key today's build writes BEFORE PersistGate opens: on a
+// fresh install that would already exist by the time this runs, and the fresh install would be taken for
+// a returning player.
+export function createReturningPlayerMigrate(storage: GuideStorageReader, legacyKeys: readonly string[]) {
+  return async (state: GuidePersistedState, version: number): Promise<GuidePersistedState> => {
+    if (state !== undefined || legacyKeys.length === 0) return state
+    try {
+      const values = await Promise.all(legacyKeys.map((key) => storage.getItem(key)))
+      return values.some((value) => value !== null) ? { _persist: { version, rehydrated: false } } : undefined
+    } catch {
+      return undefined
+    }
+  }
+}

package/src/guide/index.ts

@@ -0,0 +1,14 @@
+// The how-to-play entry point (`@tastic/hud/guide`) — a standalone build reachable without ever
+// touching the main barrel, the same reason `@tastic/hud/skia-gate` is. This file and everything it
+// imports must stay free of @tastic/core, @tastic/profile, @tastic/split-screen, @tastic/achievements,
+// @rific/updater and Skia: those are optional peers of this package (see package.json's
+// peerDependenciesMeta) precisely so an app like Hangman, which has none of them, can install
+// @tastic/hud and use only this. src/__tests__/guideImports.test.ts enforces it.
+export { type DirectionKeyLabels, type DirectionKeysAxis, DirectionKeysHint, type DirectionKeysHintProps } from './DirectionKeysHint'
+export { GuideProvider, type GuideProviderProps, useAutoShowGuide, useGuide } from './GuideProvider'
+export { createGuideSlice, createReturningPlayerMigrate, type GuideAction, type GuidePersistedState, type GuideSlice, type GuideSliceOptions, type GuideState, type GuideStorageReader } from './guideSlice'
+export { getGuideCardSize, HowToPlayDialog, type HowToPlayDialogProps } from './HowToPlayDialog'
+export { type SeatDevice, SeatDevicesHint, type SeatDevicesHintProps } from './SeatDevicesHint'
+export { SeatDiagram, type SeatDiagramProps } from './SeatDiagram'
+export { type SwipeDirection, SwipeHint, type SwipeHintProps, type SwipePointer } from './SwipeHint'
+export type { GuideRotation, GuideStep } from './types'

package/src/guide/types.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react'
+
+// One card of a game's how-to-play flow. Content is app-local data, not something this package
+// authors: only the app knows its own controls, its own key schemes on desktop web, its own win
+// condition. `art` is whatever illustrates the idea — a `SwipeHint`/`SeatDiagram` from this same
+// entry point, or anything the app draws itself (plain Views + Reanimated keeps it renderer-free).
+export interface GuideStep {
+  title: string
+  body: string
+  art?: ReactNode
+}
+
+// The fleet's fake-landscape rotation (structurally @tastic/core's ViewRotation, restated here so this
+// entry point never imports @tastic/core). Pass the app's LIVE rotation (useRotation/getViewRotation):
+// the guide renders in the app-root Portal host, outside any rotated screen, so it turns itself.
+export type GuideRotation = 0 | 90 | 180 | -90

package/src/index.ts

@@ -1,5 +1,6 @@
 export { AchievementCatalogSection } from './AchievementCatalogSection'
 export { AchievementRow, LOCKED_BADGE_COLOR } from './AchievementRow'
+export { AchievementUnlockList, type AchievementUnlockOwner, type UnlockedAchievement } from './AchievementUnlockList'
 export { ActivityStatSection } from './ActivityStatSection'
 export { BaseSettingsDialog, type BaseSettingsDialogProps } from './BaseSettingsDialog'
 export { BaseStatsScreen } from './BaseStatsScreen'
@@ -12,7 +13,7 @@ export { MONO_FONT } from './fonts'
 export { getInlineColorPickerContentSize, InlineColorPicker } from './InlineColorPicker'
 export { getLabeledDropdownContentHeight, LABELED_DROPDOWN_POPOVER_WIDTH, LabeledDropdown, type LabeledDropdownOption } from './LabeledDropdown'
 export { loadSkiaWeb } from './loadSkiaWeb'
-export { getOverlayCardColors, type OverlayCardColors, overlayStyles } from './overlayCard'
+export { getOverlayCardColors, overlayActionStyles, type OverlayCardColors, overlayStyles } from './overlayCard'
 export { getColorPopoverId, getCpuDifficultyPopoverId, PlayerSetupPanel, type PlayerSetupPanelProps } from './PlayerSetupPanel'
 export { PopoverBody } from './PopoverBody'
 export { PressAwayOverlay } from './PressAwayOverlay'