@tastic/hud 0.12.0 → 0.14.0

package/src/ContentGutter.tsx

@@ -1,6 +1,6 @@
-import { computeContentBounds } from '@tastic/core'
+import { computeContentBounds, useRotatedWindowDimensions } from '@tastic/core'
 import { ReactNode } from 'react'
-import { StyleProp, StyleSheet, useWindowDimensions, View, ViewStyle } from 'react-native'
+import { StyleProp, StyleSheet, View, ViewStyle } from 'react-native'
 
 interface Props {
   // Upper bound on the centered content region's width, in px. Omitted (the default) means no
@@ -25,13 +25,20 @@ interface Props {
 // any further stops being useful. Below maxContentWidth - or with it omitted entirely - this is a
 // no-op passthrough: children render at the full window width, no gutters.
 //
-// See @tastic/core's computeContentBounds for the actual clamp math this just wires up to a live
-// useWindowDimensions() read - deliberately the only geometry source this component owns itself; a
+// The width it clamps against is @tastic/core's useRotatedWindowDimensions(), not a raw
+// useWindowDimensions(): under a fake-landscape ancestor (FakeLandscapeView - the OS window stays
+// portrait-locked, the screen is only visually rotated) the raw window width never changes, so a
+// raw read would cap a rotated play area at the portrait width while everything inside laid out for
+// the swapped landscape footprint, clipping it. That hook is an exact identity with
+// useWindowDimensions() whenever no rotation applies, so nothing changes at rotation 0.
+//
+// See @tastic/core's computeContentBounds for the actual clamp math this just wires up to that live
+// read - deliberately the only geometry source this component owns itself; a
 // caller that also needs to fold in device safe-area insets or a split-screen zone boundary
 // composes those together on its own side, the same way LightCycles' useZoneClampedAlign composes
 // useAutoAlign with its own extra geometry (see that hook for the pattern this follows).
 export function ContentGutter({ maxContentWidth, leftGutter, rightGutter, style, children }: Props) {
-  const { width: windowWidth } = useWindowDimensions()
+  const { width: windowWidth } = useRotatedWindowDimensions()
   const { contentWidth, gutterWidth } = computeContentBounds(windowWidth, maxContentWidth ?? Infinity)
 
   return (

package/src/RotatedFrame.tsx

@@ -0,0 +1,71 @@
+import { FakeLandscapeView, rotateDimensions, rotateInsets, useRotation, type ViewRotation } from '@tastic/core'
+import { type ReactNode, useMemo } from 'react'
+import { StyleSheet, useWindowDimensions, View } from 'react-native'
+import { Portal } from 'react-native-paper'
+import { SafeAreaInsetsContext, useSafeAreaInsets } from 'react-native-safe-area-context'
+
+export interface RotatedFrameProps {
+  children: ReactNode
+  /** The angle to turn the frame by. Defaults to the live physical hold (@tastic/core's useRotation); pass it
+   * when the caller already has the exact angle it wants, e.g. a dialog handed its caller's rotation, or 0 for
+   * one that already sits inside a turned frame. */
+  rotation?: ViewRotation
+  /** Give everything inside the frame the safe-area insets already remapped onto the frame's own edges (see
+   * @tastic/core's rotateInsets), so a component that reads `useSafeAreaInsets()` itself (a library screen,
+   * Paper's Modal, a toaster) lands on the right edge when the frame is turned. Leave it off for content that
+   * rotates the insets itself, which would otherwise rotate them twice. */
+  rotatedSafeArea?: boolean
+  /** Mount a Paper Portal.Host INSIDE the frame, so a dialog (Paper's Portal otherwise mounts at the app root,
+   * outside the frame) is laid out against the frame's footprint and turned with it. The dialog must then be
+   * told `rotation={0}`. */
+  portalHost?: boolean
+  /** Let touches fall through the frame to whatever is beneath it, so only its children claim them. For a frame
+   * laid OVER other content (a dialog layer, a root-level overlay); a screen that owns the window leaves it off. */
+  passThrough?: boolean
+  /** Cap on the content column's width in the WIDE layout only (the rotated footprint is landscape), centred: a
+   * stats list or a roster stretched across an 874pt-wide landscape screen reads badly. Portrait is never capped,
+   * so a portrait iPad or desktop window keeps its full width. Omit for no cap. */
+  maxContentWidth?: number
+}
+
+/** A frame turned to follow the phone while the OS stays portrait-locked (see @tastic/core's FakeLandscapeView),
+ * sized to the turned footprint so its content lays out against the short edge at +/-90. The tree is IDENTICAL
+ * at every angle, so a rotation never remounts what is inside: `FakeLandscapeView > SafeArea provider >
+ * [Portal.Host] > column`. `rotation`, `rotatedSafeArea`, `passThrough` and `maxContentWidth` only change styles
+ * and values, but `portalHost` adds or removes the Portal.Host element, so it must be STATIC per call site
+ * (flipping it at runtime would remount everything inside).
+ *
+ * Safe for tap-driven content only: react-native-gesture-handler's translation deltas are untransformed, so
+ * never put a gesture-tracked game board inside it. */
+export function RotatedFrame({ children, rotation: rotationOverride, rotatedSafeArea = false, portalHost = false, passThrough = false, maxContentWidth }: RotatedFrameProps) {
+  const ambientRotation = useRotation()
+  const rotation = rotationOverride ?? ambientRotation
+  const window = useWindowDimensions()
+  const { width, height } = rotateDimensions(window.width, window.height, rotation)
+  const rawInsets = useSafeAreaInsets()
+  const insets = useMemo(() => (rotatedSafeArea ? rotateInsets(rawInsets, rotation) : rawInsets), [rotatedSafeArea, rawInsets, rotation])
+  const cappedWidth = maxContentWidth !== undefined && width > height ? maxContentWidth : undefined
+  const column = (
+    <View style={[styles.column, cappedWidth !== undefined && { maxWidth: cappedWidth }]} pointerEvents={passThrough ? 'box-none' : undefined}>
+      {children}
+    </View>
+  )
+
+  return (
+    <FakeLandscapeView rotation={rotation} passThrough={passThrough} style={styles.root}>
+      <SafeAreaInsetsContext.Provider value={insets}>{portalHost ? <Portal.Host>{column}</Portal.Host> : column}</SafeAreaInsetsContext.Provider>
+    </FakeLandscapeView>
+  )
+}
+
+const styles = StyleSheet.create({
+  // A centred column: full width up to `maxWidth`, so a capped frame sits in the middle of a wider window.
+  column: {
+    alignSelf: 'center',
+    flex: 1,
+    width: '100%'
+  },
+  root: {
+    flex: 1
+  }
+})

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

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