@tastic/hud 0.16.0 → 0.18.0

package/src/ConfirmDialog.tsx

@@ -3,9 +3,12 @@ import { Button } from '@rific/feedback-press'
 import { toRotationStyle, type ViewRotation } from '@tastic/core'
 import { type ReactNode } from 'react'
 import { StyleSheet, View } from 'react-native'
-import { Icon, Portal, Text } from 'react-native-paper'
+import { Portal, Text } from 'react-native-paper'
 
-import { getOverlayCardColors, overlayActionStyles, overlayStyles } from './overlayCard'
+import { DialogHeader } from './DialogHeader'
+import { overlayActionStyles } from './overlayCard'
+import { OverlayBackdrop, OverlayCard, useOverlayCardColors } from './OverlaySurface'
+import { useCompactDialog } from './useCompactDialog'
 
 export interface ConfirmDialogProps {
   visible: boolean
@@ -19,39 +22,38 @@ export interface ConfirmDialogProps {
   // BaseSettingsDialog's own rotation prop; defaults to 0 for a caller with no per-player zone to
   // match (a portrait-only or single-player game has nothing to stay consistent with).
   rotation?: ViewRotation
-  // Any react-native-paper Icon `source` name, shown above the title - defaults to a plain
-  // question mark, since this component has no way to know why a caller is asking.
+  // Any react-native-paper Icon `source` name, shown in the header (DialogHeader) - defaults to a
+  // plain question mark, since this component has no way to know why a caller is asking.
   icon?: string
   // Whether the confirm button reads as destructive (the fleet's shared `danger` semantic role)
   // instead of the default primary-colored affirmative action.
   destructive?: boolean
 }
 
-// A themed replacement for the native Alert.alert/window.confirm two-button confirm pattern - the
-// same "retro card overlay" look BaseSettingsDialog's own update-check info messages already use
-// (see its onInfo/infoMessage), generalized here into its own reusable, exported component for any
-// caller that needs a real yes/no decision instead of a single OK dismissal. A solid backdrop +
-// centered card, not react-native-paper's own Dialog (which BaseSettingsDialog uses instead) -
+// A themed replacement for the native Alert.alert/window.confirm two-button confirm pattern, the same
+// card BaseSettingsDialog's own update-check info messages use (see its onInfo/infoMessage),
+// generalized into its own reusable, exported component for any caller that needs a real yes/no
+// decision instead of a single OK dismissal. The card and backdrop come from OverlaySurface.tsx: the
+// theme's raised surface, blurred when the player's Blur setting allows it. A backdrop + centered
+// card, not react-native-paper's own Dialog (which BaseSettingsDialog uses instead) -
 // this renders identically on every platform, including web, where react-native-web's Alert.alert
 // is a hard no-op (confirmed: its entire implementation is `static alert() {}`) and Dialog's own
 // Portal-based positioning has its own web quirks BaseSettingsDialog already works around.
 export function ConfirmDialog({ visible, title, message, confirmLabel, cancelLabel, onConfirm, onCancel, rotation = 0, icon = 'help-circle-outline', destructive = false }: ConfirmDialogProps) {
-  const { dark, colors } = useAutoPaperTheme()
+  const { colors } = useAutoPaperTheme()
+  const { fg } = useOverlayCardColors()
+  const { compact, onLayout } = useCompactDialog(rotation)
   if (!visible) return null
 
-  const { fg, cardBg, cardBorder } = getOverlayCardColors(dark)
   const accent = destructive ? colors.danger : colors.primary
   const onAccent = destructive ? colors.onDanger : colors.onPrimary
   const showCancel = cancelLabel !== undefined && onCancel !== undefined
 
   return (
     <Portal>
-      <View style={[overlayStyles.overlay, styles.overlay]}>
-        <View style={[overlayStyles.card, styles.card, { backgroundColor: cardBg, borderColor: cardBorder }, toRotationStyle(rotation)]}>
-          <Icon source={icon} size={64} color={accent} />
-          <Text variant='headlineLarge' style={[styles.title, { color: accent }]}>
-            {title}
-          </Text>
+      <OverlayBackdrop style={styles.overlay} onLayout={onLayout}>
+        <OverlayCard style={[styles.card, toRotationStyle(rotation)]}>
+          <DialogHeader icon={icon} title={title} color={accent} compact={compact} />
           <Text variant='bodyLarge' style={[styles.body, { color: fg }]}>
             {message}
           </Text>
@@ -65,8 +67,8 @@ export function ConfirmDialog({ visible, title, message, confirmLabel, cancelLab
               {confirmLabel}
             </Button>
           </View>
-        </View>
-      </View>
+        </OverlayCard>
+      </OverlayBackdrop>
     </Portal>
   )
 }
@@ -89,12 +91,5 @@ const styles = StyleSheet.create({
   // screen narrower than maxWidth's own 360.
   overlay: {
     paddingHorizontal: 24
-  },
-  // textAlign is load-bearing, not decorative, once `title` wraps to more than one line - centered
-  // within card's own alignItems: 'center' only centers the Text's block as a whole; each wrapped
-  // line inside that block still defaults to left-aligned without this.
-  title: {
-    fontWeight: 'bold',
-    textAlign: 'center'
   }
 })

package/src/DialogHeader.tsx

@@ -0,0 +1,72 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { type StyleProp, StyleSheet, View, type ViewStyle } from 'react-native'
+import { Icon, Text } from 'react-native-paper'
+
+// Below this much height every dialog uses the compact header (and the guide its smaller art). It is
+// the height of the space the dialog lays out in, counted along the CARD's own vertical axis: the
+// frame's height for an upright card, the frame's width for a card turned a quarter (see
+// useCompactDialog.ts). The how-to-play guide borrows this file, so it imports nothing heavier than
+// paper and auto-paper (see guideImports.test.ts); the hook, which needs @tastic/core, lives apart. 528 is the guide's old rule (480 of usable height inside its 24pt gutters): a
+// phone held sideways (320-430) is compact, a small phone upright (568+) and an iPad either way are not.
+export const COMPACT_DIALOG_HEIGHT = 528
+
+export function isCompactDialogHeight(height: number): boolean {
+  return height < COMPACT_DIALOG_HEIGHT
+}
+
+export interface DialogHeaderProps {
+  // Any react-native-paper Icon `source` name.
+  icon: string
+  title: string
+  // The icon and title color. Defaults to the theme's primary; ConfirmDialog passes its danger role
+  // when destructive.
+  color?: string
+  // A short space (see useCompactDialog.ts): the icon moves beside the title, at half size, so a sheet
+  // keeps its reading room.
+  compact?: boolean
+  style?: StyleProp<ViewStyle>
+}
+
+// The one header every dialog in the fleet opens with (Jay, 2026-10-15: "they should all have the same
+// title and maybe an icon"): a 64pt icon over a large bold title, both in the accent color, centered.
+// ConfirmDialog, the How to Play guide, BaseSettingsDialog and every app's own result cards use it,
+// so a dialog never hand-rolls its own title again.
+export function DialogHeader({ icon, title, color, compact = false, style }: DialogHeaderProps) {
+  const { colors } = useAutoPaperTheme()
+  const accent = color ?? colors.primary
+  return (
+    <View style={[compact ? styles.compact : styles.full, style]}>
+      <Icon source={icon} size={compact ? COMPACT_ICON_SIZE : ICON_SIZE} color={accent} />
+      <Text accessibilityRole='header' variant={compact ? 'headlineSmall' : 'headlineLarge'} style={[styles.title, compact && styles.titleCompact, { color: accent }]}>
+        {title}
+      </Text>
+    </View>
+  )
+}
+
+const ICON_SIZE = 64
+const COMPACT_ICON_SIZE = 32
+
+const styles = StyleSheet.create({
+  compact: {
+    alignItems: 'center',
+    alignSelf: 'stretch',
+    flexDirection: 'row',
+    gap: 12,
+    justifyContent: 'center'
+  },
+  full: {
+    alignItems: 'center',
+    alignSelf: 'stretch',
+    gap: 16
+  },
+  // textAlign matters once a title wraps: the card centers the Text's block, but each wrapped line
+  // still defaults to left-aligned without it.
+  title: {
+    fontWeight: 'bold',
+    textAlign: 'center'
+  },
+  titleCompact: {
+    flexShrink: 1
+  }
+})

package/src/OverlaySurface.tsx

@@ -0,0 +1,70 @@
+import { BlurView, useAutoPaperTheme, useBlur } from '@rific/auto-paper'
+import { type ReactNode } from 'react'
+import { type LayoutChangeEvent, type StyleProp, StyleSheet, View, type ViewStyle } from 'react-native'
+
+import { overlayStyles } from './overlayCard'
+
+export interface OverlayCardThemeColors {
+  fg: string
+  fgMuted: string
+  cardBorder: string
+  backdrop: string
+}
+
+// The colors for text and edges on an OverlayCard, taken from the app's own theme (Jay, 2026-10-15:
+// the cards follow each game's palette instead of the old literal black/white "retro" card).
+export function useOverlayCardColors(): OverlayCardThemeColors {
+  const { colors } = useAutoPaperTheme()
+  return { fg: colors.onSurface, fgMuted: colors.onSurfaceVariant, cardBorder: colors.outlineVariant, backdrop: colors.backdrop }
+}
+
+export interface OverlayBackdropProps {
+  children?: ReactNode
+  style?: StyleProp<ViewStyle>
+  // useCompactDialog's onLayout (DialogHeader.tsx): the backdrop fills the space the dialog lays out in.
+  onLayout?: (e: LayoutChangeEvent) => void
+}
+
+// The full-screen dim behind a card: overlayStyles.overlay's geometry in the theme's own backdrop
+// color (the same scrim auto-paper's Dialog uses), lighter than the old solid 72% black.
+export function OverlayBackdrop({ children, style, onLayout }: OverlayBackdropProps) {
+  const { backdrop } = useOverlayCardColors()
+  return (
+    <View onLayout={onLayout} style={[overlayStyles.overlay, { backgroundColor: backdrop }, style]}>
+      {children}
+    </View>
+  )
+}
+
+export interface OverlayCardProps {
+  children?: ReactNode
+  style?: StyleProp<ViewStyle>
+  accessibilityViewIsModal?: boolean
+  testID?: string
+}
+
+// The card itself: the same surface as auto-paper's Dialog, which BaseSettingsDialog's sheet is drawn
+// on, so every dialog in the fleet looks like one family (Jay, 2026-10-15: the card used to sit at
+// elevation 3, MD3's wash of the theme's primary, and next to the plain Settings sheet it read as a
+// different shade; he preferred the sheet). So: auto-paper's BlurView with no elevation (the theme's
+// plain surface), no border, and the Dialog's own corner radius (7 x the theme's roundness, 28 at MD3's
+// default). It blurs whatever is behind it when the player's Blur setting is on and the app has handed
+// expo-blur to auto-paper's Provider, and otherwise paints that surface on its own: on Android (no blur
+// target here), in an app without expo-blur, or with Blur off. Beyond passing expoBlur to auto-paper's
+// Provider, an app wires nothing for the blur.
+// BlurView itself only follows its `blur` prop (on by default), so the setting is read here with
+// useBlur(), the same way auto-paper's own Dialog and Menu read it.
+// overflow: hidden keeps a native blur inside the card's rounded corners.
+export function OverlayCard({ children, style, ...rest }: OverlayCardProps) {
+  const { isV3, roundness } = useAutoPaperTheme()
+  const blur = useBlur()
+  return (
+    <BlurView blur={blur} style={[overlayStyles.card, styles.card, { borderRadius: (isV3 ? 7 : 1) * roundness }, style]} {...rest}>
+      {children}
+    </BlurView>
+  )
+}
+
+const styles = StyleSheet.create({
+  card: { overflow: 'hidden' }
+})

package/src/TriggerGauge.tsx

@@ -77,10 +77,10 @@ const SELECTION_TRANSITION_DURATION_MS = 260
 // Arc of dashes drawn around a SectionedDropdown trigger, purely decorative-informational - the
 // trigger's own icon stays exactly as it is (see SectionedDropdown's triggerIcon), this just frames
 // it with an at-a-glance read of *which* option is active without opening the popover. Each dash is
-// a real Skia arc segment (Path.addArc), not a straight bar approximating one - a straight bar wide
-// enough to look bold started visibly crossing its neighbors on a sparse (e.g. 3-option) gauge,
-// since a chord that long diverges a lot from the circle it's meant to trace; an actual arc stays on
-// the circle at any width. Skia measures angles clockwise from 3 o'clock, so a center angle here
+// a real Skia arc segment (PathBuilder.addArc), not a straight bar approximating one - a straight
+// bar wide enough to look bold started visibly crossing its neighbors on a sparse (e.g. 3-option)
+// gauge, since a chord that long diverges a lot from the circle it's meant to trace; an actual arc
+// stays on the circle at any width. Skia measures angles clockwise from 3 o'clock, so a center angle here
 // (measured clockwise from 12, like startDeg/endDeg) is shifted by -90° before being handed to
 // addArc.
 export function TriggerGauge({ segments, litIndices, size, accentColor, mutedColor, dashWidth, startDeg = DEFAULT_START_DEG, endDeg = startDeg }: TriggerGaugeProps) {
@@ -201,7 +201,7 @@ export function TriggerGauge({ segments, litIndices, size, accentColor, mutedCol
   // there the instant a lit dash starts shrinking off of it, rather than popping in only once the
   // shrink finishes.
   const unlitPath = useDerivedValue(() => {
-    const path = Skia.Path.Make()
+    const path = Skia.PathBuilder.Make()
     for (let i = 0; i < segments; i++) {
       if (litIndices.includes(i)) continue
       let local = 1
@@ -217,7 +217,7 @@ export function TriggerGauge({ segments, litIndices, size, accentColor, mutedCol
       const dashCenterDeg = startDeg + (i + 0.5) * step
       path.addArc(oval, dashCenterDeg - 90 - sweep / 2, sweep)
     }
-    return path
+    return path.detach()
     // litIndicesKey, not litIndices - the array itself is a brand-new reference on every render
     // (including ones triggered by a totally unrelated sibling gauge or settings field), which would
     // otherwise force this worklet to rebuild on every such render. The stable string key only
@@ -226,7 +226,7 @@ export function TriggerGauge({ segments, litIndices, size, accentColor, mutedCol
   }, [segments, litIndicesKey, step, startDeg, dashAngleDeg, totalDurationMs, oval.x, oval.y, oval.width, oval.height])
 
   const litPath = useDerivedValue(() => {
-    const path = Skia.Path.Make()
+    const path = Skia.PathBuilder.Make()
     // The common case - a single-select trigger swapping from one tier to another - is just one
     // full-width arc sitting at angleDeg's current value, which useLayoutEffect above retargets
     // (never resets) on every change; this alone gives a real rotating handoff, including smoothly
@@ -234,7 +234,7 @@ export function TriggerGauge({ segments, litIndices, size, accentColor, mutedCol
     // is done - before that, the sweep-width stagger below owns the reveal instead.
     if (mountProgress.value >= 1 && singleSelect) {
       path.addArc(oval, angleDeg.value - 90 - dashAngleDeg / 2, dashAngleDeg)
-      return path
+      return path.detach()
     }
 
     for (let i = 0; i < segments; i++) {
@@ -261,7 +261,7 @@ export function TriggerGauge({ segments, litIndices, size, accentColor, mutedCol
       const dashCenterDeg = startDeg + (i + 0.5) * step
       path.addArc(oval, dashCenterDeg - 90 - sweep / 2, sweep)
     }
-    return path
+    return path.detach()
     // litIndicesKey/transitionFromKey, not the arrays themselves - see unlitPath's identical comment.
   }, [segments, litIndicesKey, transitionFromKey, singleSelect, step, startDeg, dashAngleDeg, totalDurationMs, oval.x, oval.y, oval.width, oval.height])
 

package/src/chrome/index.ts

@@ -13,10 +13,13 @@ export { BaseStatsScreen } from '../BaseStatsScreen'
 export { ConfirmDialog, type ConfirmDialogProps } from '../ConfirmDialog'
 export { ContentGutter } from '../ContentGutter'
 export { CornerActionButtons } from '../CornerActionButtons'
+export { COMPACT_DIALOG_HEIGHT, DialogHeader, type DialogHeaderProps, isCompactDialogHeight } from '../DialogHeader'
 export { MONO_FONT } from '../fonts'
-export { getOverlayCardColors, overlayActionStyles, type OverlayCardColors, overlayStyles } from '../overlayCard'
+export { overlayActionStyles, overlayStyles } from '../overlayCard'
+export { OverlayBackdrop, type OverlayBackdropProps, OverlayCard, type OverlayCardProps, type OverlayCardThemeColors, useOverlayCardColors } from '../OverlaySurface'
 export { RotatedFrame, type RotatedFrameProps } from '../RotatedFrame'
 export { getStaggeredWordDuration, StaggeredWord, type StaggeredWordProps } from '../StaggeredWord'
 export { StatRow } from '../StatRow'
 export { StatSection } from '../StatSection'
 export { UpdateDialog, type UpdateDialogProps } from '../UpdateDialog'
+export { useCompactDialog } from '../useCompactDialog'

package/src/guide/HowToPlayDialog.tsx

@@ -5,7 +5,9 @@ import { BackHandler, type NativeScrollEvent, type NativeSyntheticEvent, ScrollV
 import { Portal, Text } from 'react-native-paper'
 import { useReducedMotion } from 'react-native-reanimated'
 
-import { getOverlayCardColors, overlayActionStyles, overlayStyles } from '../overlayCard'
+import { DialogHeader, isCompactDialogHeight } from '../DialogHeader'
+import { overlayActionStyles } from '../overlayCard'
+import { OverlayBackdrop, OverlayCard, useOverlayCardColors } from '../OverlaySurface'
 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
@@ -18,9 +20,11 @@ const MAX_CARD_WIDTH = 360
 // 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
+// On a short screen (isCompactDialogHeight, the rule every dialog's header follows) the illustration
+// box shrinks. Before the dialog header, that fit the whole card (padding, art, title, two lines of
+// body, dots, buttons) on a 360pt-wide phone held sideways; the compact header adds 48pt, so a page
+// there now scrolls a little (see the pager below). The art can't shrink further: the apps' own art
+// is drawn at fixed sizes (Solitaire's is 72-98pt tall). The page's own gaps tighten instead (pageCompact).
 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
@@ -33,11 +37,13 @@ export function getGuideCardSize(windowWidth: number, windowHeight: number, rota
   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)
+  const compact = isCompactDialogHeight(turned ? windowWidth : windowHeight)
   return {
     width,
     pageWidth: width - CARD_PADDING * 2,
     maxHeight: availableHeight,
-    artHeight: availableHeight < COMPACT_BELOW ? ART_HEIGHT_COMPACT : ART_HEIGHT
+    artHeight: compact ? ART_HEIGHT_COMPACT : ART_HEIGHT,
+    compact
   }
 }
 
@@ -52,11 +58,15 @@ export interface HowToPlayDialogProps {
   // 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
+  // The dialog's own header (DialogHeader), above the pages: the guide opens unprompted on a first
+  // launch, so it says what it is before the first card's own title (Jay, 2026-10-15).
+  title?: string
+  icon?: string
 }
 
 type CardProps = Omit<HowToPlayDialogProps, 'visible'>
 
-function HowToPlayCard({ steps, onFinish, onSkip, rotation = 0 }: CardProps) {
+function HowToPlayCard({ steps, onFinish, onSkip, rotation = 0, title = 'How to Play', icon = 'help-circle-outline' }: CardProps) {
   const { dark, colors } = useAutoPaperTheme()
   const { width: windowWidth, height: windowHeight } = useWindowDimensions()
   const reducedMotion = useReducedMotion()
@@ -73,8 +83,8 @@ function HowToPlayCard({ steps, onFinish, onSkip, rotation = 0 }: CardProps) {
     return () => subscription.remove()
   }, [onSkip])
 
-  const { fg, cardBg, cardBorder, fgMuted } = getOverlayCardColors(dark)
-  const { width: cardWidth, pageWidth, maxHeight, artHeight } = getGuideCardSize(windowWidth, windowHeight, rotation)
+  const { fg, fgMuted } = useOverlayCardColors()
+  const { width: cardWidth, pageWidth, maxHeight, artHeight, compact } = getGuideCardSize(windowWidth, windowHeight, rotation)
   const rotationStyle = rotation === 0 ? undefined : { transform: [{ rotate: `${rotation}deg` }] }
   const isFirst = index === 0
   const isLast = index === steps.length - 1
@@ -119,14 +129,15 @@ function HowToPlayCard({ steps, onFinish, onSkip, rotation = 0 }: CardProps) {
 
   return (
     <Portal>
-      <View style={[overlayStyles.overlay, styles.overlay]}>
-        <View accessibilityViewIsModal style={[overlayStyles.card, styles.card, { width: cardWidth, maxHeight, backgroundColor: cardBg, borderColor: cardBorder }, rotationStyle]}>
+      <OverlayBackdrop style={styles.overlay}>
+        <OverlayCard accessibilityViewIsModal style={[styles.card, { width: cardWidth, maxHeight }, rotationStyle]}>
+          <DialogHeader icon={icon} title={title} compact={compact} />
           {/* 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}>
+              <ScrollView key={i} nestedScrollEnabled showsVerticalScrollIndicator={false} style={{ width: pageWidth }} contentContainerStyle={[styles.page, compact && styles.pageCompact]}>
                 {step.art !== undefined && <View style={[styles.art, { height: artHeight, backgroundColor: artBackground }]}>{step.art}</View>}
                 <Text variant='headlineSmall' style={[styles.title, { color: fg }]}>
                   {step.title}
@@ -140,8 +151,10 @@ function HowToPlayCard({ steps, onFinish, onSkip, rotation = 0 }: CardProps) {
 
           {steps.length > 1 && (
             <View accessible accessibilityLabel={`Step ${index + 1} of ${steps.length}`} style={styles.dots}>
+              {/* fgMuted is the full-strength onSurfaceVariant, so the inactive dots are dimmed to half or
+                they'd stand out more than the active primary one. */}
               {steps.map((_, i) => (
-                <View key={i} style={[styles.dot, { backgroundColor: i === index ? colors.primary : fgMuted }]} />
+                <View key={i} style={i === index ? [styles.dot, { backgroundColor: colors.primary }] : [styles.dot, styles.dotInactive, { backgroundColor: fgMuted }]} />
               ))}
             </View>
           )}
@@ -161,14 +174,14 @@ function HowToPlayCard({ steps, onFinish, onSkip, rotation = 0 }: CardProps) {
               {isLast ? 'Ready' : 'Next'}
             </Button>
           </View>
-        </View>
-      </View>
+        </OverlayCard>
+      </OverlayBackdrop>
     </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
+// built on the same overlay card as ConfirmDialog (see OverlaySurface.tsx) 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
@@ -193,8 +206,7 @@ const styles = StyleSheet.create({
   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.
+  // overlayCard's shared `card` padding, restated: the page width above is computed from it.
   card: {
     padding: CARD_PADDING
   },
@@ -203,6 +215,9 @@ const styles = StyleSheet.create({
     height: 8,
     width: 8
   },
+  dotInactive: {
+    opacity: 0.5
+  },
   dots: {
     flexDirection: 'row',
     gap: 8
@@ -214,6 +229,11 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     gap: 12
   },
+  // The 8pt this saves is what the compact dialog header cost a page on a 402pt-tall window (a
+  // Pro-size iPhone held sideways, measured on web): without it the body's second line scrolled.
+  pageCompact: {
+    gap: 8
+  },
   pager: {
     flexShrink: 1
   },

package/src/index.ts

@@ -9,11 +9,13 @@ export { ContentGutter } from './ContentGutter'
 export { ControlSchemePicker, type ControlSchemePickerProps } from './ControlSchemePicker'
 export { CornerActionButtons } from './CornerActionButtons'
 export { CornerStatusBadges, type CornerStatusBadgeSeat, type CornerStatusBadgesProps, type OrientationMode } from './CornerStatusBadges'
+export { COMPACT_DIALOG_HEIGHT, DialogHeader, type DialogHeaderProps, isCompactDialogHeight } from './DialogHeader'
 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, overlayActionStyles, type OverlayCardColors, overlayStyles } from './overlayCard'
+export { overlayActionStyles, overlayStyles } from './overlayCard'
+export { OverlayBackdrop, type OverlayBackdropProps, OverlayCard, type OverlayCardProps, type OverlayCardThemeColors, useOverlayCardColors } from './OverlaySurface'
 export { getColorPopoverId, getCpuDifficultyPopoverId, PlayerSetupPanel, type PlayerSetupPanelProps } from './PlayerSetupPanel'
 export { PopoverBody } from './PopoverBody'
 export { PressAwayOverlay } from './PressAwayOverlay'
@@ -36,6 +38,7 @@ export type { TriggerGaugeProps } from './TriggerGauge'
 export { default as TriggerGaugeHost } from './TriggerGaugeHost'
 export { UpdateDialog, type UpdateDialogProps } from './UpdateDialog'
 export { type AlignResult, type PopoverAlign, type PopoverRotation, type PopoverVerticalAlign, useAutoAlign } from './useAutoAlign'
+export { useCompactDialog } from './useCompactDialog'
 export { type PopoverHost, usePopoverHost } from './usePopoverHost'
 export { type QuitConfirmation, useQuitConfirmation } from './useQuitConfirmation'
 export { useZoneClampedAlign } from './useZoneClampedAlign'

package/src/overlayCard.ts

@@ -1,39 +1,21 @@
 import { StyleSheet } from 'react-native'
 
-export interface OverlayCardColors {
-  fg: string
-  fgMuted: string
-  cardBg: string
-  cardBorder: string
-}
-
-// The literal-black/white-by-appearance "retro" formula this package's own BaseSettingsDialog and
-// ConfirmDialog each independently re-derived - deliberately NOT auto-paper's own (seed-color-tinted)
-// background role, see either component's own "High-contrast retro look" comment for why. Every
-// fleet app's own Game-Over/Round-Over/Match-Over/Quit-confirmation overlay re-derives this same
-// three-or-four-line formula again, which is what this export exists to replace.
-export function getOverlayCardColors(dark: boolean): OverlayCardColors {
-  return {
-    fg: dark ? '#FFFFFF' : '#000000',
-    fgMuted: dark ? 'rgba(255,255,255,0.4)' : 'rgba(0,0,0,0.4)',
-    cardBg: dark ? '#111111' : '#F2F2F2',
-    cardBorder: dark ? 'rgba(255,255,255,0.2)' : 'rgba(0,0,0,0.2)'
-  }
-}
-
-// Only the shell shape every overlay card shares (backdrop + card geometry) - deliberately not the
-// title/body styling, which already legitimately varies by consumer (each app's own score/badge/zone
-// content). A consumer applies `{backgroundColor: cardBg, borderColor: cardBorder}` from
-// getOverlayCardColors on top of `card` itself, same as every existing call site already does. The
-// one button row every overlay card with actions shares lives in overlayActionStyles below.
+// Only the shell shape every overlay card shares (backdrop + card geometry). The title is
+// DialogHeader's; the body still legitimately varies by consumer (each app's own score/badge/zone
+// content). Cards should use OverlayBackdrop and OverlayCard (OverlaySurface.tsx), which apply
+// `overlay` and `card` underneath and set the theme's backdrop color and corner radius themselves
+// (the backdrop replaces `overlay`'s rgba(0,0,0,0.72)). The one button row every overlay card with
+// actions shares lives in overlayActionStyles below.
+// No border and 24pt of padding, like the Settings sheet (auto-paper's Dialog, 24pt insets on its
+// title and scroll area), so the two families match (Jay, 2026-10-15). borderRadius is that Dialog's
+// at MD3's default roundness; OverlayCard derives it from the live theme.
 export const overlayStyles = StyleSheet.create({
   card: {
     alignItems: 'center',
-    borderRadius: 20,
-    borderWidth: 1,
+    borderRadius: 28,
     gap: 16,
     maxWidth: 360,
-    padding: 32
+    padding: 24
   },
   overlay: {
     alignItems: 'center',

package/src/useCompactDialog.ts

@@ -0,0 +1,23 @@
+import { useRotatedWindowDimensions, type ViewRotation } from '@tastic/core'
+import { useCallback, useState } from 'react'
+import { type LayoutChangeEvent, useWindowDimensions } from 'react-native'
+
+import { isCompactDialogHeight } from './DialogHeader'
+
+// Whether a dialog should use the compact header, and the onLayout to put on its OverlayBackdrop. The
+// backdrop fills whatever the dialog lays out in, so its measured size is the real answer: a turned
+// game frame, an upright root, either one with a card that turns itself. Before that first layout it
+// guesses: a dialog that turns itself (rotation ±90 or 180) sits at the root, in the upright window; one
+// that doesn't sits in a frame the app has already turned by the live rotation.
+export function useCompactDialog(rotation: ViewRotation = 0): { compact: boolean; onLayout: (e: LayoutChangeEvent) => void } {
+  const window = useWindowDimensions()
+  const framed = useRotatedWindowDimensions()
+  const [measured, setMeasured] = useState<{ width: number; height: number } | null>(null)
+  const onLayout = useCallback((e: LayoutChangeEvent) => {
+    const { width, height } = e.nativeEvent.layout
+    setMeasured((prev) => (prev && prev.width === width && prev.height === height ? prev : { width, height }))
+  }, [])
+  const box = measured ?? (rotation === 0 ? framed : window)
+  const turned = rotation === 90 || rotation === -90
+  return { compact: isCompactDialogHeight(turned ? box.width : box.height), onLayout }
+}