@tastic/hud 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastic/hud",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Visual component kit for local-multiplayer React Native games: inline (non-modal) popovers, dropdowns, color pickers, gauges, ready buttons, and dialogs, built to stay scoped to one player's own zone on a shared screen",
   "keywords": [
     "react-native",
@@ -34,6 +34,13 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
     },
+    "./guide": {
+      "react-native": "./src/guide/index.ts",
+      "browser": "./src/guide/index.ts",
+      "types": "./dist/guide/index.d.ts",
+      "import": "./dist/guide/index.mjs",
+      "require": "./dist/guide/index.js"
+    },
     "./skia-gate": {
       "react-native": "./src/SkiaGate.tsx",
       "browser": "./src/SkiaGate.web.tsx",
@@ -73,13 +80,13 @@
     "@infinitetoken/eslint-config": "^0.2.0",
     "@infinitetoken/jest-config": "^0.4.0",
     "@infinitetoken/tsconfig": "^0.5.0",
-    "@rific/auto-paper": "^0.12.0",
+    "@rific/auto-paper": "^0.12.3",
     "@rific/core": "^0.2.0",
     "@rific/feedback-press": "^0.12.0",
     "@rific/updater": "^0.6.0",
     "@shopify/react-native-skia": "^2.6.2",
     "@tastic/achievements": "^0.2.0",
-    "@tastic/core": "^0.8.0",
+    "@tastic/core": "^0.12.0",
     "@tastic/profile": "^0.7.0",
     "@tastic/split-screen": "^0.5.0",
     "@testing-library/dom": "^10.4.1",
@@ -102,12 +109,12 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@rific/auto-paper": ">=0.9.0",
-    "@rific/feedback-press": ">=0.10.0",
+    "@rific/auto-paper": ">=0.12.2",
+    "@rific/feedback-press": ">=0.10.2",
     "@rific/updater": ">=0.4.0",
     "@shopify/react-native-skia": ">=1.5.0",
-    "@tastic/achievements": ">=0.1.2",
-    "@tastic/core": ">=0.3.0",
+    "@tastic/achievements": ">=0.2.0",
+    "@tastic/core": ">=0.12.0",
     "@tastic/profile": ">=0.4.0",
     "@tastic/split-screen": ">=0.5.0",
     "react": ">=19.0.0",
@@ -116,6 +123,26 @@
     "react-native-reanimated": ">=3.0.0",
     "react-native-safe-area-context": ">=5.0.0"
   },
+  "peerDependenciesMeta": {
+    "@rific/updater": {
+      "optional": true
+    },
+    "@shopify/react-native-skia": {
+      "optional": true
+    },
+    "@tastic/achievements": {
+      "optional": true
+    },
+    "@tastic/core": {
+      "optional": true
+    },
+    "@tastic/profile": {
+      "optional": true
+    },
+    "@tastic/split-screen": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   }

package/src/AchievementUnlockList.tsx

@@ -0,0 +1,98 @@
+import { getContrastColor, useAutoPaperTheme } from '@rific/auto-paper'
+import type { AchievementTier } from '@tastic/achievements'
+import { type Profile, ProfileChip } from '@tastic/profile'
+import { StyleSheet, View, type ViewStyle } from 'react-native'
+import { Icon, Text } from 'react-native-paper'
+
+// The only fields a row reads - structural, so any app's own AchievementDefinition<Stats> fits
+// without this package caring about its stats type parameter.
+export interface UnlockedAchievement {
+  id: string
+  icon: string
+  title: string
+  tier: AchievementTier
+}
+
+// Who a seat's rows belong to: their ProfileChip when a profile is selected, otherwise a plain
+// avatar in the seat's own color (a guest seat has no tag to show). An app that draws profile colors
+// muted wraps its tree in @tastic/profile's ProfileColorProvider (ProfileChip reads it) and passes
+// an already-muted `color` here.
+export interface AchievementUnlockOwner {
+  profile?: Profile | null
+  color: string
+}
+
+interface Props<Seat extends number> {
+  unlocks: Partial<Record<Seat, UnlockedAchievement[]>>
+  // Row order: every unlock of the first seat, then the next.
+  seats: readonly Seat[]
+  owners: Record<Seat, AchievementUnlockOwner>
+  // Taken as a prop rather than imported: @tastic/achievements stays a type-only dependency of
+  // this package. Callers pass its ACHIEVEMENT_TIER_COLORS (or their own palette).
+  tierColors: Record<AchievementTier, string>
+  fg?: string
+  style?: ViewStyle
+}
+
+const AVATAR_SIZE = 18
+
+// The newly-unlocked achievements on a game-over / round-over card, one row per achievement:
+// owner avatar, tier-colored icon badge, title. Extracted from the per-app copies in Snake,
+// LightCycles, Pong, BoxHockey and AirHockey, which had drifted to three different owner markers;
+// this is the ProfileChip-or-color-avatar one most of them used. One row per achievement rather
+// than a per-seat summary, so the list stays aligned when only one seat unlocked anything.
+// Renders nothing when there are no unlocks at all.
+export function AchievementUnlockList<Seat extends number>({ unlocks, seats, owners, tierColors, fg: fgOverride, style }: Props<Seat>) {
+  const { dark } = useAutoPaperTheme()
+  const fg = fgOverride ?? (dark ? '#FFFFFF' : '#000000')
+  const rows = seats.flatMap((seat) => (unlocks[seat] ?? []).map((achievement) => ({ seat, achievement })))
+  if (rows.length === 0) return null
+
+  return (
+    <View style={[styles.list, style]}>
+      {rows.map(({ seat, achievement }) => {
+        const owner = owners[seat]
+        return (
+          <View key={`${seat}-${achievement.id}`} style={styles.row}>
+            {owner.profile ? (
+              <ProfileChip profile={owner.profile} size={AVATAR_SIZE} />
+            ) : (
+              <View style={[styles.circle, { backgroundColor: owner.color }]}>
+                <Icon source='account' size={10} color={getContrastColor(owner.color)} />
+              </View>
+            )}
+            <View style={[styles.circle, { backgroundColor: tierColors[achievement.tier] }]}>
+              <Icon source={achievement.icon} size={12} color='#000000' />
+            </View>
+            <Text style={[styles.label, { color: fg }]} numberOfLines={1}>
+              {achievement.title}
+            </Text>
+          </View>
+        )
+      })}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  circle: {
+    alignItems: 'center',
+    borderRadius: AVATAR_SIZE / 2,
+    height: AVATAR_SIZE,
+    justifyContent: 'center',
+    width: AVATAR_SIZE
+  },
+  label: {
+    flexShrink: 1,
+    fontSize: 12,
+    fontWeight: '700'
+  },
+  list: {
+    gap: 6
+  },
+  row: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    gap: 6
+  }
+})

package/src/BaseSettingsDialog.tsx

@@ -1,12 +1,13 @@
 import { AutoAppearancePicker, Dialog, useAutoPaperTheme } from '@rific/auto-paper'
 import { Button, SoundContext, TouchableRipple, useHapticSettings, useSoundSettings, useVibration } from '@rific/feedback-press'
 import { useUpdater } from '@rific/updater'
-import { toRotationStyle, useIsTouchPrimaryDevice, useRotation, type ViewRotation } from '@tastic/core'
+import { useIsTouchPrimaryDevice, useRotation, type ViewRotation } from '@tastic/core'
 import { ReactNode, useContext, useState } from 'react'
 import { Platform, ScrollView, StyleSheet, View } from 'react-native'
-import { Icon, Text } from 'react-native-paper'
+import { Icon, Portal, Text } from 'react-native-paper'
 
 import { ConfirmDialog } from './ConfirmDialog'
+import { RotatedFrame } from './RotatedFrame'
 import { useUpdateConfirmBridge } from './useUpdateConfirmBridge'
 
 interface SettingIconProps {
@@ -29,11 +30,11 @@ function SettingIcon({ source, color, containerColor }: SettingIconProps) {
 export interface BaseSettingsDialogProps {
   visible: boolean
   onDismiss: () => void
-  // Explicit override for the live physical-hold rotation (see @tastic/core's useRotation) — this is
+  // Explicit override for the live physical-hold rotation (see @tastic/core's useRotation). This is
   // a centered, app-wide modal with no per-player zone to match (unlike an in-game round-over
-  // dialog), so it just rotates its own content in place. Defaults to a live ambient read via
-  // useRotation() when omitted; pass this only when a caller's own reading needs to differ from the
-  // ambient one (rare — most callers should simply omit it).
+  // dialog), so it lays itself out in its own frame turned by this angle (see the return below).
+  // Defaults to a live ambient read via useRotation() when omitted. Pass 0 when the dialog already
+  // renders under a Portal.Host inside a turned frame of the caller's own (Solitaire's screens).
   rotation?: ViewRotation
   // Each app's own OTA version (e.g. release.otaVersion) — not something this package can read
   // itself, since every consuming app tracks its own release.ts independently. Accepts a number too
@@ -67,6 +68,10 @@ export interface BaseSettingsDialogProps {
   // toast system wired up; the check itself still runs and still reports success/no-update through
   // the ordinary info overlay either way. Meaningless (never called) when hideUpdateCheck is set.
   onUpdateError?: (message: string) => void
+  // Omit to hide the row entirely (a game with no how-to-play flow, or a screen where replaying one
+  // would be disruptive — e.g. over a live match). Called AFTER this dialog's own onDismiss, so the
+  // two overlays never stack: wire it straight to @tastic/hud/guide's `useGuide().open`.
+  onShowHowToPlay?: () => void
   // App-specific extra settings sections (board options, CPU difficulty, stats backup, ...),
   // rendered between Appearance and Check for Updates — this component only owns the settings
   // every game shares, never anything about how a particular game plays.
@@ -80,7 +85,7 @@ export interface BaseSettingsDialogProps {
 // is the seam for whatever isn't shared: a game with its own board/difficulty settings (or a stats
 // backup flow, or anything else genuinely specific to it) renders those below Appearance, not by
 // forking this component.
-export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverride, version, lockOrientation, onLockOrientationChange, deferBottomEdgeGestures, onDeferBottomEdgeGestures, hideSound = false, hideHaptics = false, hideAppearance = false, hideUpdateCheck = false, onUpdateError, children }: BaseSettingsDialogProps) {
+export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverride, version, lockOrientation, onLockOrientationChange, deferBottomEdgeGestures, onDeferBottomEdgeGestures, hideSound = false, hideHaptics = false, hideAppearance = false, hideUpdateCheck = false, onUpdateError, onShowHowToPlay, children }: BaseSettingsDialogProps) {
   const { colors } = useAutoPaperTheme()
   const ambientRotation = useRotation()
   const rotation = rotationOverride ?? ambientRotation
@@ -126,148 +131,187 @@ export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverr
   const showAppearance = !hideAppearance
   const showUpdateCheck = Platform.OS !== 'web' && !hideUpdateCheck
 
+  // Laid out in its own turned frame rather than rotated in place. Paper's Portal mounts at the app
+  // root, full screen and portrait-shaped, so a sheet that only rotated its card kept resolving its
+  // maxHeight against the PORTRAIT height: turned 90deg it ran past the ~402pt short edge, and the top
+  // row (Lock Orientation, the one you need to get back out of landscape) was clipped with no way to
+  // scroll to it. So the whole output goes through one Portal to the root, into a RotatedFrame sized
+  // to the turned footprint, with rotated safe-area insets and its own Portal.Host. The Dialog and the
+  // two ConfirmDialogs below portal into THAT host, so they lay out against the turned window with no
+  // transform of their own (hence rotation={0} on the ConfirmDialogs). The frame is pass-through at
+  // every level and stays mounted with this component, which keeps the Dialog's close fade; at
+  // rotation 0 it is an identity frame.
   return (
-    <>
-      <Dialog visible={visible} onDismiss={onDismiss} style={[styles.dialog, toRotationStyle(rotation)]}>
-        <Dialog.Title>Settings</Dialog.Title>
-        {/* react-native-paper's Dialog.ScrollArea has a fixed 24px marginBottom baked in (meant to
-          reserve room for a Dialog.Actions row below it) — overridden to 0 since this dialog has
-          no actions row, and that gap otherwise reads as unexplained empty footer space. */}
-        <Dialog.ScrollArea style={styles.scrollArea}>
-          <ScrollView contentContainerStyle={styles.content} showsVerticalScrollIndicator={false}>
-            {/* Grouped tightly together (styles.toggleGroup's small internal gap, not the 24px gap
-              between sections below) — same bare-row shape for all of them, no segmented control
-              and no section heading (each row's own label already says what it is). Haptics only
-              joins on native — there's nothing for it to control on web. */}
-            <View style={styles.toggleGroup}>
-              {/* Omitted entirely for a portrait-only game (no lockOrientation/onLockOrientationChange
-                passed at all — nothing to lock), and hidden (not just disabled) on a desktop/laptop
-                browser even when they are — see isTouchPrimary's own doc above. Still shown on
-                native and on a touch-capable mobile browser, where a rotated window really does
-                reflect a rotated device. */}
-              {showLockOrientation && (
-                <TouchableRipple onPress={() => onLockOrientationChange!(!lockOrientation)} style={styles.toggleButton} accessibilityLabel={`Lock orientation ${lockOrientation ? 'on' : 'off'}`}>
-                  <View style={styles.toggleContent}>
-                    <SettingIcon source={lockOrientation ? 'lock' : 'lock-open-variant-outline'} color={lockOrientation ? colors.secondary : colors.onSurfaceVariant} containerColor={lockOrientation ? colors.secondaryContainer : colors.surfaceVariant} />
-                    <View style={styles.flexShrink}>
-                      <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
-                        Lock Orientation
-                      </Text>
-                      <Text variant='bodySmall' numberOfLines={1} style={{ color: colors.onSurfaceVariant }}>
-                        Pins the current layout
-                      </Text>
-                    </View>
-                  </View>
-                </TouchableRipple>
-              )}
-
-              {/* iOS only — mirrors into UserDefaults for @tastic/edge-guard's own config plugin
-                swizzle to read. Guards both edges — the top (Notification Center/Control Center)
-                and the bottom (home-indicator swipe, incidentally Reachability too), per that
-                package's own doc. Off by default: a deliberate opt-in for whoever's actually hit an
-                accidental-swipe-near-an-edge problem mid-game and come looking for a fix, not a
-                surprise every player gets by default. */}
-              {showEdgeGuard && (
-                <TouchableRipple onPress={() => onDeferBottomEdgeGestures!(!deferBottomEdgeGestures)} style={styles.toggleButton} accessibilityLabel={`Edge guard ${deferBottomEdgeGestures ? 'on' : 'off'}`}>
-                  <View style={styles.toggleContent}>
-                    <SettingIcon source={deferBottomEdgeGestures ? 'shield-check-outline' : 'shield-off-outline'} color={deferBottomEdgeGestures ? colors.secondary : colors.onSurfaceVariant} containerColor={deferBottomEdgeGestures ? colors.secondaryContainer : colors.surfaceVariant} />
-                    <View style={styles.flexShrink}>
-                      <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
-                        Edge Guard
-                      </Text>
-                      <Text variant='bodySmall' numberOfLines={1} style={{ color: colors.onSurfaceVariant }}>
-                        Requires a second swipe
-                      </Text>
+    <Portal>
+      <RotatedFrame rotation={rotation} rotatedSafeArea portalHost passThrough>
+        <Dialog visible={visible} onDismiss={onDismiss} style={styles.dialog}>
+          <Dialog.Title>Settings</Dialog.Title>
+          {/* react-native-paper's Dialog.ScrollArea has a fixed 24px marginBottom baked in (meant to
+            reserve room for a Dialog.Actions row below it) — overridden to 0 since this dialog has
+            no actions row, and that gap otherwise reads as unexplained empty footer space. */}
+          <Dialog.ScrollArea style={styles.scrollArea}>
+            <ScrollView contentContainerStyle={styles.content} showsVerticalScrollIndicator={false}>
+              {/* Grouped tightly together (styles.toggleGroup's small internal gap, not the 24px gap
+                between sections below) — same bare-row shape for all of them, no segmented control
+                and no section heading (each row's own label already says what it is). Haptics only
+                joins on native — there's nothing for it to control on web. */}
+              <View style={styles.toggleGroup}>
+                {/* Omitted entirely for a portrait-only game (no lockOrientation/onLockOrientationChange
+                  passed at all — nothing to lock), and hidden (not just disabled) on a desktop/laptop
+                  browser even when they are — see isTouchPrimary's own doc above. Still shown on
+                  native and on a touch-capable mobile browser, where a rotated window really does
+                  reflect a rotated device. */}
+                {showLockOrientation && (
+                  <TouchableRipple onPress={() => onLockOrientationChange!(!lockOrientation)} style={styles.toggleButton} accessibilityLabel={`Lock orientation ${lockOrientation ? 'on' : 'off'}`}>
+                    <View style={styles.toggleContent}>
+                      <SettingIcon source={lockOrientation ? 'lock' : 'lock-open-variant-outline'} color={lockOrientation ? colors.secondary : colors.onSurfaceVariant} containerColor={lockOrientation ? colors.secondaryContainer : colors.surfaceVariant} />
+                      <View style={styles.flexShrink}>
+                        <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
+                          Lock Orientation
+                        </Text>
+                        <Text variant='bodySmall' numberOfLines={1} style={{ color: colors.onSurfaceVariant }}>
+                          Pins the current layout
+                        </Text>
+                      </View>
                     </View>
-                  </View>
-                </TouchableRipple>
-              )}
+                  </TouchableRipple>
+                )}
 
-              {/* Side by side, not stacked — neither needs a full row's width (single-line label,
-                no description under it the way Lock Orientation has), so sharing one row reads
-                just as clearly and takes half the vertical space. toggleRow carries the same
-                edge-alignment negative margin toggleButton normally carries itself; the buttons
-                inside it use toggleButtonInRow (flex: 1) instead so the two don't double up on it.
-                The row itself only renders when at least one of the two will — an empty flex row
-                still eats its own gap/margin otherwise. */}
-              {(showSound || showHaptics) && (
-                <View style={styles.toggleRow}>
-                  {showSound && (
-                    <TouchableRipple
-                      soundDisabled
-                      onPress={() => {
-                        const enabled = !soundSettings.enabled
-                        setSoundSettings({ enabled })
-                        if (enabled) sound.selection?.()
-                      }}
-                      style={styles.toggleButtonInRow}
-                      accessibilityLabel={`Sound ${soundSettings.enabled ? 'on' : 'off'}`}
-                    >
-                      <View style={styles.toggleContent}>
-                        <SettingIcon source={soundSettings.enabled ? 'volume-high' : 'volume-off'} color={soundSettings.enabled ? colors.tertiary : colors.onSurfaceVariant} containerColor={soundSettings.enabled ? colors.tertiaryContainer : colors.surfaceVariant} />
+                {/* iOS only — mirrors into UserDefaults for @tastic/edge-guard's own config plugin
+                  swizzle to read. Guards both edges — the top (Notification Center/Control Center)
+                  and the bottom (home-indicator swipe, incidentally Reachability too), per that
+                  package's own doc. Off by default: a deliberate opt-in for whoever's actually hit an
+                  accidental-swipe-near-an-edge problem mid-game and come looking for a fix, not a
+                  surprise every player gets by default. */}
+                {showEdgeGuard && (
+                  <TouchableRipple onPress={() => onDeferBottomEdgeGestures!(!deferBottomEdgeGestures)} style={styles.toggleButton} accessibilityLabel={`Edge guard ${deferBottomEdgeGestures ? 'on' : 'off'}`}>
+                    <View style={styles.toggleContent}>
+                      <SettingIcon source={deferBottomEdgeGestures ? 'shield-check-outline' : 'shield-off-outline'} color={deferBottomEdgeGestures ? colors.secondary : colors.onSurfaceVariant} containerColor={deferBottomEdgeGestures ? colors.secondaryContainer : colors.surfaceVariant} />
+                      <View style={styles.flexShrink}>
                         <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
-                          Sound
+                          Edge Guard
+                        </Text>
+                        <Text variant='bodySmall' numberOfLines={1} style={{ color: colors.onSurfaceVariant }}>
+                          Requires a second swipe
                         </Text>
                       </View>
-                    </TouchableRipple>
-                  )}
+                    </View>
+                  </TouchableRipple>
+                )}
 
-                  {/* Already native-only (see showHaptics's own definition) — hideHaptics can hide
-                    it there too, for a game that's deliberately silent on vibration. */}
-                  {showHaptics && (
-                    <TouchableRipple
-                      hapticDisabled
-                      onPress={() => {
-                        const vibrate = !hapticSettings.vibrate
-                        setHapticSettings({ vibrate })
-                        if (vibrate) forceHapticFeedback()
-                      }}
-                      style={styles.toggleButtonInRow}
-                      accessibilityLabel={`Haptics ${hapticSettings.vibrate ? 'on' : 'off'}`}
-                    >
-                      <View style={styles.toggleContent}>
-                        <SettingIcon source={hapticSettings.vibrate ? 'vibrate' : 'vibrate-off'} color={hapticSettings.vibrate ? colors.tertiary : colors.onSurfaceVariant} containerColor={hapticSettings.vibrate ? colors.tertiaryContainer : colors.surfaceVariant} />
+                {/* Side by side, not stacked — neither needs a full row's width (single-line label,
+                  no description under it the way Lock Orientation has), so sharing one row reads
+                  just as clearly and takes half the vertical space. toggleRow carries the same
+                  edge-alignment negative margin toggleButton normally carries itself; the buttons
+                  inside it use toggleButtonInRow (flex: 1) instead so the two don't double up on it.
+                  The row itself only renders when at least one of the two will — an empty flex row
+                  still eats its own gap/margin otherwise. */}
+                {(showSound || showHaptics) && (
+                  <View style={styles.toggleRow}>
+                    {showSound && (
+                      <TouchableRipple
+                        soundDisabled
+                        onPress={() => {
+                          const enabled = !soundSettings.enabled
+                          setSoundSettings({ enabled })
+                          if (enabled) sound.selection?.()
+                        }}
+                        style={styles.toggleButtonInRow}
+                        accessibilityLabel={`Sound ${soundSettings.enabled ? 'on' : 'off'}`}
+                      >
+                        <View style={styles.toggleContent}>
+                          <SettingIcon source={soundSettings.enabled ? 'volume-high' : 'volume-off'} color={soundSettings.enabled ? colors.tertiary : colors.onSurfaceVariant} containerColor={soundSettings.enabled ? colors.tertiaryContainer : colors.surfaceVariant} />
+                          <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
+                            Sound
+                          </Text>
+                        </View>
+                      </TouchableRipple>
+                    )}
+
+                    {/* Already native-only (see showHaptics's own definition) — hideHaptics can hide
+                      it there too, for a game that's deliberately silent on vibration. */}
+                    {showHaptics && (
+                      <TouchableRipple
+                        hapticDisabled
+                        onPress={() => {
+                          const vibrate = !hapticSettings.vibrate
+                          setHapticSettings({ vibrate })
+                          if (vibrate) forceHapticFeedback()
+                        }}
+                        style={styles.toggleButtonInRow}
+                        accessibilityLabel={`Haptics ${hapticSettings.vibrate ? 'on' : 'off'}`}
+                      >
+                        <View style={styles.toggleContent}>
+                          <SettingIcon source={hapticSettings.vibrate ? 'vibrate' : 'vibrate-off'} color={hapticSettings.vibrate ? colors.tertiary : colors.onSurfaceVariant} containerColor={hapticSettings.vibrate ? colors.tertiaryContainer : colors.surfaceVariant} />
+                          <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
+                            Haptics
+                          </Text>
+                        </View>
+                      </TouchableRipple>
+                    )}
+                  </View>
+                )}
+
+                {/* Not a toggle, but it reads like one of the rows above and belongs with them rather than
+                  down in `children` (which sits below Appearance) — this is the "replay the intro"
+                  entry point every game's own how-to-play flow shares. Dismisses this dialog first so
+                  the guide's own overlay never opens on top of a still-visible Settings card. */}
+                {onShowHowToPlay && (
+                  <TouchableRipple
+                    onPress={() => {
+                      onDismiss()
+                      onShowHowToPlay()
+                    }}
+                    style={styles.toggleButton}
+                    accessibilityLabel='How to Play'
+                  >
+                    <View style={styles.toggleContent}>
+                      <SettingIcon source='help-circle-outline' color={colors.secondary} containerColor={colors.secondaryContainer} />
+                      <View style={styles.flexShrink}>
                         <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
-                          Haptics
+                          How to Play
+                        </Text>
+                        <Text variant='bodySmall' numberOfLines={1} style={{ color: colors.onSurfaceVariant }}>
+                          Replay the quick intro
                         </Text>
                       </View>
-                    </TouchableRipple>
-                  )}
+                    </View>
+                  </TouchableRipple>
+                )}
+              </View>
+
+              {showAppearance && (
+                <View style={styles.section}>
+                  <Text variant='labelMedium' style={[styles.sectionLabel, { color: colors.onSurfaceVariant }]}>
+                    APPEARANCE
+                  </Text>
+                  <AutoAppearancePicker showLabels={false} />
                 </View>
               )}
-            </View>
-
-            {showAppearance && (
-              <View style={styles.section}>
-                <Text variant='labelMedium' style={[styles.sectionLabel, { color: colors.onSurfaceVariant }]}>
-                  APPEARANCE
-                </Text>
-                <AutoAppearancePicker showLabels={false} />
-              </View>
-            )}
 
-            {children}
+              {children}
 
-            {/* Native only (a web build has no OTA update concept at all, desktop or mobile browser
-              alike) — hideUpdateCheck can hide it there too, for a native app that isn't wired up
-              for EAS/OTA updates at all. */}
-            {showUpdateCheck && (
-              <View style={styles.section}>
-                <Text variant='labelSmall' style={[styles.sectionLabel, { color: colors.onSurfaceVariant }]}>
-                  VERSION {version}
-                  {updateReady ? ' · UPDATE READY' : ''}
-                </Text>
-                <Button mode='outlined' onPress={check} loading={checking} disabled={checking}>
-                  Check for Updates
-                </Button>
-              </View>
-            )}
-          </ScrollView>
-        </Dialog.ScrollArea>
-      </Dialog>
-      <ConfirmDialog visible={!!updateManifest} title='Update Available' message={updateManifestDate ? `Released ${updateManifestDate.toLocaleDateString()} at ${updateManifestDate.toLocaleTimeString()}` : ''} confirmLabel='Restart' cancelLabel='Later' icon='update' rotation={rotation} onConfirm={() => respondToUpdateConfirm(true)} onCancel={() => respondToUpdateConfirm(false)} />
-      <ConfirmDialog visible={!!infoMessage} title={infoMessage?.title ?? ''} message={infoMessage?.message ?? ''} confirmLabel='OK' icon='information-outline' rotation={rotation} onConfirm={() => setInfoMessage(null)} />
-    </>
+              {/* Native only (a web build has no OTA update concept at all, desktop or mobile browser
+                alike) — hideUpdateCheck can hide it there too, for a native app that isn't wired up
+                for EAS/OTA updates at all. */}
+              {showUpdateCheck && (
+                <View style={styles.section}>
+                  <Text variant='labelSmall' style={[styles.sectionLabel, { color: colors.onSurfaceVariant }]}>
+                    VERSION {version}
+                    {updateReady ? ' · UPDATE READY' : ''}
+                  </Text>
+                  <Button mode='outlined' onPress={check} loading={checking} disabled={checking}>
+                    Check for Updates
+                  </Button>
+                </View>
+              )}
+            </ScrollView>
+          </Dialog.ScrollArea>
+        </Dialog>
+        <ConfirmDialog visible={!!updateManifest} title='Update Available' message={updateManifestDate ? `Released ${updateManifestDate.toLocaleDateString()} at ${updateManifestDate.toLocaleTimeString()}` : ''} confirmLabel='Restart' cancelLabel='Later' icon='update' rotation={0} onConfirm={() => respondToUpdateConfirm(true)} onCancel={() => respondToUpdateConfirm(false)} />
+        <ConfirmDialog visible={!!infoMessage} title={infoMessage?.title ?? ''} message={infoMessage?.message ?? ''} confirmLabel='OK' icon='information-outline' rotation={0} onConfirm={() => setInfoMessage(null)} />
+      </RotatedFrame>
+    </Portal>
   )
 }
 

package/src/ConfirmDialog.tsx

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