@tastic/hud 0.24.0 → 0.25.0

package/dist/index.mjs

@@ -24,21 +24,22 @@ import {
   useCompactDialog,
   usePopoverHost,
   useWellColors
-} from "./chunk-BXG44LIA.mjs";
+} from "./chunk-AJD4FMG5.mjs";
+import {
+  loadSkiaWeb,
+  locateSkiaWebFile
+} from "./chunk-3TCJHMJP.mjs";
 import {
   COMPACT_DIALOG_HEIGHT,
   DialogHeader,
   OverlayBackdrop,
   OverlayCard,
+  SecondaryButton,
   isCompactDialogHeight,
   overlayActionStyles,
   overlayStyles,
   useOverlayCardColors
-} from "./chunk-PUF6TABL.mjs";
-import {
-  loadSkiaWeb,
-  locateSkiaWebFile
-} from "./chunk-3TCJHMJP.mjs";
+} from "./chunk-CBH7GQKI.mjs";
 
 // src/AchievementUnlockList.tsx
 import { getContrastColor, useAutoPaperTheme } from "@rific/auto-paper";
@@ -642,6 +643,7 @@ export {
   PressAwayOverlay,
   ReadyButton,
   RotatedFrame,
+  SecondaryButton,
   SectionedDropdown,
   SharedActionBand,
   StaggeredWord,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastic/hud",
-  "version": "0.24.0",
+  "version": "0.25.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",
@@ -84,18 +84,18 @@
   },
   "prettier": "@infinitetoken/eslint-config/prettier",
   "devDependencies": {
-    "@infinitetoken/eslint-config": "^0.2.0",
+    "@infinitetoken/eslint-config": "^0.2.1",
     "@infinitetoken/jest-config": "^0.5.2",
     "@infinitetoken/tsconfig": "^0.6.0",
     "@rific/auto-paper": "^0.13.3",
-    "@rific/core": "^0.4.0",
-    "@rific/feedback-press": "^0.13.0",
+    "@rific/core": "^0.5.0",
+    "@rific/feedback-press": "^0.13.1",
     "@rific/updater": "^0.7.1",
     "@shopify/react-native-skia": "^2.14.0",
     "@tastic/achievements": "^0.6.0",
     "@tastic/core": "^0.14.0",
-    "@tastic/profile": "^0.15.0",
-    "@tastic/split-screen": "^0.5.2",
+    "@tastic/profile": "^0.16.2",
+    "@tastic/split-screen": "^0.5.4",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^30.0.0",

package/src/BaseSettingsDialog.tsx

@@ -157,9 +157,11 @@ export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverr
 
   const showLockOrientation = isTouchPrimary && lockOrientation !== undefined && onLockOrientationChange !== undefined
   const showEdgeGuard = Platform.OS === 'ios' && deferBottomEdgeGestures !== undefined && onDeferBottomEdgeGestures !== undefined
-  // Only in an app that opted in by handing expo-keep-awake to @rific/core's KeepAwakeProvider:
-  // without the module the setting would do nothing. On the same devices as Lock Orientation, since a
-  // desktop/laptop browser stays awake on its own while someone plays with its keyboard or mouse.
+  // Only in an app that opted in by handing expo-keep-awake to @rific/core's KeepAwakeProvider, and
+  // only where it can work: core withholds the module from a browser without the Screen Wake Lock
+  // API (from @rific/core 0.4.1), so without it the setting would do nothing. On the same devices
+  // as Lock Orientation, since a desktop/laptop browser stays awake on its own while someone plays
+  // with its keyboard or mouse.
   const showKeepAwake = isTouchPrimary && expoKeepAwake !== undefined
   const showHaptics = Platform.OS !== 'web' && !hideHaptics
   const showSound = !hideSound

package/src/ConfirmDialog.tsx

@@ -8,6 +8,7 @@ import { Portal, Text } from 'react-native-paper'
 import { DialogHeader } from './DialogHeader'
 import { overlayActionStyles } from './overlayCard'
 import { OverlayBackdrop, OverlayCard, useOverlayCardColors } from './OverlaySurface'
+import { SecondaryButton } from './SecondaryButton'
 import { useCompactDialog } from './useCompactDialog'
 
 export interface ConfirmDialogProps {
@@ -81,11 +82,7 @@ export function ConfirmDialog({ visible, title, message, confirmLabel, cancelLab
             {message}
           </Text>
           <View style={overlayActionStyles.actions}>
-            {showCancel && (
-              <Button mode='outlined' onPress={onCancel} style={overlayActionStyles.actionButton}>
-                {cancelLabel}
-              </Button>
-            )}
+            {showCancel && <SecondaryButton onPress={onCancel}>{cancelLabel}</SecondaryButton>}
             <Button mode='contained' onPress={onConfirm} style={showCancel ? overlayActionStyles.actionButton : overlayActionStyles.actionButtonSingle} buttonColor={accent} textColor={onAccent}>
               {confirmLabel}
             </Button>

package/src/InlineColorPicker.tsx

@@ -1,12 +1,13 @@
 import { defaultColors, getContrastColor, SeedColor } from '@rific/auto-paper'
 import { TouchableRipple } from '@rific/feedback-press'
 import { clamp, useRotation } from '@tastic/core'
+import { type ReactNode, type RefObject } from 'react'
 import { ScrollView, StyleSheet, useWindowDimensions, View } from 'react-native'
 import { Icon, Text } from 'react-native-paper'
 
 import { MONO_FONT } from './fonts'
 import { PopoverBody } from './PopoverBody'
-import { AlignResult, PopoverRotation, useAutoAlign } from './useAutoAlign'
+import { AlignResult, PopoverRotation, useAutoAlign, type ViewInstance } from './useAutoAlign'
 import { PopoverHost } from './usePopoverHost'
 
 // Presence check, not a full-string "is this exactly one emoji" validation - this only decides a
@@ -16,6 +17,8 @@ const EMOJI_PATTERN = /\p{Extended_Pictographic}/u
 
 const DEFAULT_SIZE = 48
 const SWATCH_SIZE = 28
+// The selected swatch's white ring, drawn inside its SWATCH_SIZE.
+const SWATCH_RING_WIDTH = 2
 const SWATCHES_PADDING = 8
 const SWATCHES_GAP = 6
 const SWATCHES_BORDER_WIDTH = 2
@@ -55,6 +58,15 @@ export function getInlineColorPickerContentSize(swatchCount: number, windowWidth
   return { width, height }
 }
 
+// Where a `renderSwatch` drawing goes: the trigger (the color in effect, with its tag or icon on
+// it) or a swatch in the popover's grid.
+export type InlineColorPickerSwatchPlace = 'trigger' | 'swatch'
+
+// Draws one color's swatch in place of its flat fill: a circle `size` across. `color` is the drawn
+// color (after `previewValue`) and stays the primary one: the tag, icon, check, X or swap icon on
+// top takes its contrast from it. Returning null or undefined keeps that swatch's flat fill.
+export type InlineColorPickerSwatchRenderer = (color: string, size: number, place: InlineColorPickerSwatchPlace) => ReactNode
+
 interface Props {
   id: string
   host: PopoverHost
@@ -115,12 +127,25 @@ interface Props {
   // with other fixed-size elements can line this trigger up with them instead of standing out at a
   // mismatched size.
   size?: number
+  // Draws the trigger and each grid swatch in place of the flat fill (a host's three-color pie, say),
+  // behind its tag, icon or mark and clipped to the circle; the selected swatch's drawing sits
+  // inside its ring. Omit for flat swatches, as before.
+  renderSwatch?: InlineColorPickerSwatchRenderer
+  // A View the popover can't leave (see useAutoAlign's `bounds`): the scroll view this picker sits
+  // in, which clips the popover at its edges. Ignored when `alignOverride` places the popover.
+  bounds?: RefObject<ViewInstance | null>
+}
+
+// A renderSwatch drawing: at the swatch's top left (inside any border), behind the mark drawn after
+// it, and clipped to the circle so a square drawing still reads round.
+function SwatchDrawing({ size, children }: { size: number; children: ReactNode }) {
+  return <View style={[styles.drawing, { borderRadius: size / 2, height: size, width: size }]}>{children}</View>
 }
 
 // Renders inline rather than as a full-screen modal, scoped to its own panel - a modal color
 // picker would block the whole screen for one player while another can't touch their own panel at
 // the same time, which defeats the point of a split-screen lobby.
-export function InlineColorPicker({ id, host, value, onChange, previewValue, swatches = defaultColors, takenValue, allowSwapTaken, dark, align: forcedAlign, alignOverride, rotation: rotationOverride, icon = 'palette', tag, labelFontFamily = MONO_FONT, autoDismiss = true, columns, size = DEFAULT_SIZE }: Props) {
+export function InlineColorPicker({ id, host, value, onChange, previewValue, swatches = defaultColors, takenValue, allowSwapTaken, dark, align: forcedAlign, alignOverride, rotation: rotationOverride, icon = 'palette', tag, labelFontFamily = MONO_FONT, autoDismiss = true, columns, size = DEFAULT_SIZE, renderSwatch, bounds }: Props) {
   const ambientRotation = useRotation()
   const rotation = rotationOverride ?? ambientRotation
   const menuBg = dark ? '#000000' : '#FFFFFF'
@@ -130,7 +155,7 @@ export function InlineColorPicker({ id, host, value, onChange, previewValue, swa
   const open = host.openId === id
   // Always called, even when alignOverride is supplied and this result goes unused - hooks can't be
   // called conditionally. See LabeledDropdown's identical comment for the same tradeoff.
-  const auto = useAutoAlign(open, swatchesWidth, swatchesHeight, rotation)
+  const auto = useAutoAlign(open, swatchesWidth, swatchesHeight, rotation, bounds)
   const placement = alignOverride ?? auto
   const { maxHeight, measured, triggerRef, verticalAlign } = placement
   const align = forcedAlign ?? placement.align
@@ -142,11 +167,13 @@ export function InlineColorPicker({ id, host, value, onChange, previewValue, swa
   // still looks small for an emoji tag at the identical size - this bumps emoji up to the icon's own
   // ratio instead, since a single emoji is closer in visual weight to an icon glyph than to text.
   const tagFontSize = size * (tag && EMOJI_PATTERN.test(tag) ? 0.6 : 0.4)
+  const triggerDrawing = renderSwatch?.(displayValue, size, 'trigger') ?? null
 
   return (
     <View style={[styles.anchor, open && styles.anchorOpen]}>
-      <TouchableRipple onPress={() => host.toggle(id)} borderless style={[styles.trigger, { backgroundColor: displayValue, borderRadius: size / 2, height: size, width: size }]}>
+      <TouchableRipple onPress={() => host.toggle(id)} borderless style={[styles.trigger, triggerDrawing === null && { backgroundColor: displayValue }, { borderRadius: size / 2, height: size, width: size }]}>
         <View ref={triggerRef} collapsable={false} style={styles.triggerMeasure}>
+          {triggerDrawing !== null && <SwatchDrawing size={size}>{triggerDrawing}</SwatchDrawing>}
           {/* Sized as a fraction of the trigger's own diameter rather than a fixed pixel size, so
           the glyph still reads as a deliberate part of the circle instead of shrinking toward its
           center on a larger trigger. */}
@@ -176,6 +203,10 @@ export function InlineColorPicker({ id, host, value, onChange, previewValue, swa
             const taken = !selected && !!takenValue && swatch.value.toLowerCase() === takenValue.toLowerCase()
             const swappable = taken && allowSwapTaken
             const swatchDisplay = displayFor(swatch.value)
+            const contrast = getContrastColor(swatchDisplay)
+            const drawnSize = selected ? SWATCH_SIZE - 2 * SWATCH_RING_WIDTH : SWATCH_SIZE
+            const drawing = renderSwatch?.(swatchDisplay, drawnSize, 'swatch') ?? null
+            const mark = selected ? <Icon source='check' size={16} color={contrast} /> : swappable ? <Icon source='swap-horizontal' size={16} color={contrast} /> : taken ? <Icon source='close' size={16} color={contrast} /> : <View />
             return (
               <TouchableRipple
                 key={swatch.value}
@@ -185,9 +216,18 @@ export function InlineColorPicker({ id, host, value, onChange, previewValue, swa
                   if (autoDismiss) host.close()
                 }}
                 borderless
-                style={[styles.swatch, { backgroundColor: swatchDisplay }, selected && styles.swatchSelected, taken && !swappable && styles.swatchTaken]}
+                style={[styles.swatch, drawing === null && { backgroundColor: swatchDisplay }, selected && styles.swatchSelected, taken && !swappable && styles.swatchTaken]}
               >
-                {selected ? <Icon source='check' size={16} color={getContrastColor(swatchDisplay)} /> : swappable ? <Icon source='swap-horizontal' size={16} color={getContrastColor(swatchDisplay)} /> : taken ? <Icon source='close' size={16} color={getContrastColor(swatchDisplay)} /> : <View />}
+                {/* TouchableRipple takes one child, so a drawing and its mark share a face that fills
+                the circle inside the ring. */}
+                {drawing !== null ? (
+                  <View style={styles.swatchFace}>
+                    <SwatchDrawing size={drawnSize}>{drawing}</SwatchDrawing>
+                    {mark}
+                  </View>
+                ) : (
+                  mark
+                )}
               </TouchableRipple>
             )
           })}
@@ -207,6 +247,14 @@ const styles = StyleSheet.create({
   anchorOpen: {
     zIndex: 100
   },
+  // A renderSwatch drawing (see SwatchDrawing).
+  drawing: {
+    left: 0,
+    overflow: 'hidden',
+    pointerEvents: 'none',
+    position: 'absolute',
+    top: 0
+  },
   swatch: {
     alignItems: 'center',
     borderRadius: SWATCH_SIZE / 2,
@@ -214,9 +262,19 @@ const styles = StyleSheet.create({
     justifyContent: 'center',
     width: SWATCH_SIZE
   },
+  // A drawn swatch (see SwatchDrawing) and its mark: the whole circle inside the selected one's ring.
+  swatchFace: {
+    alignItems: 'center',
+    bottom: 0,
+    justifyContent: 'center',
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0
+  },
   swatchSelected: {
     borderColor: '#ffffff',
-    borderWidth: 2
+    borderWidth: SWATCH_RING_WIDTH
   },
   swatchTaken: {
     opacity: 0.35

package/src/SecondaryButton.tsx

@@ -0,0 +1,17 @@
+import { Button, type ButtonProps } from '@rific/feedback-press'
+
+import { overlayActionStyles } from './overlayCard'
+import { useOverlayCardColors } from './OverlaySurface'
+
+export type SecondaryButtonProps = ButtonProps
+
+// The secondary action on an overlay card's action row (Cancel, Skip, Back, a result card's Quit):
+// outlined, labeled in the card's own text color (fg) rather than Paper's default (the theme's
+// primary), and sized as one of the row's buttons. A secondary takes no theme or seat color, so a
+// seat's card never shows another seat's color and the contained primary beside it is the only
+// colored button (Jay, 2026-10-20). Every prop overrides those defaults (a `style` is laid over the
+// row's button style).
+export function SecondaryButton({ style, ...props }: SecondaryButtonProps) {
+  const { fg } = useOverlayCardColors()
+  return <Button mode='outlined' textColor={fg} {...props} style={[overlayActionStyles.actionButton, style]} />
+}

package/src/chrome/index.ts

@@ -18,17 +18,18 @@ export { ContentGutter } from '../ContentGutter'
 export { CornerActionButtons } from '../CornerActionButtons'
 export { COMPACT_DIALOG_HEIGHT, DialogHeader, type DialogHeaderProps, isCompactDialogHeight } from '../DialogHeader'
 export { MONO_FONT } from '../fonts'
-export { getInlineColorPickerContentSize, InlineColorPicker } from '../InlineColorPicker'
+export { getInlineColorPickerContentSize, InlineColorPicker, type InlineColorPickerSwatchPlace, type InlineColorPickerSwatchRenderer } from '../InlineColorPicker'
 export { overlayActionStyles, overlayStyles } from '../overlayCard'
 export { OverlayBackdrop, type OverlayBackdropProps, OverlayCard, type OverlayCardProps, type OverlayCardThemeColors, useOverlayCardColors } from '../OverlaySurface'
 export { PopoverBody } from '../PopoverBody'
 export { PressAwayOverlay } from '../PressAwayOverlay'
 export { RotatedFrame, type RotatedFrameProps } from '../RotatedFrame'
+export { SecondaryButton, type SecondaryButtonProps } from '../SecondaryButton'
 export { getStaggeredWordDuration, StaggeredWord, type StaggeredWordProps } from '../StaggeredWord'
 export { StatRow } from '../StatRow'
 export { StatSection } from '../StatSection'
 export { UpdateDialog, type UpdateDialogProps } from '../UpdateDialog'
-export { type AlignResult, type PopoverAlign, type PopoverRotation, type PopoverVerticalAlign, useAutoAlign } from '../useAutoAlign'
+export { type AlignResult, type PopoverAlign, type PopoverRotation, type PopoverVerticalAlign, useAutoAlign, type ViewInstance } from '../useAutoAlign'
 export { useCompactDialog } from '../useCompactDialog'
 export { type PopoverHost, usePopoverHost } from '../usePopoverHost'
 export { useWellColors, WELL_SHADOW, type WellColors } from '../wellSurface'

package/src/guide/HowToPlayDialog.tsx

@@ -1,6 +1,6 @@
 import { useAutoPaperTheme } from '@rific/auto-paper'
 import { Button } from '@rific/feedback-press'
-import { useEffect, useRef, useState } from 'react'
+import { type ComponentRef, 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'
@@ -8,6 +8,7 @@ import { useReducedMotion } from 'react-native-reanimated'
 import { DialogHeader, isCompactDialogHeight } from '../DialogHeader'
 import { overlayActionStyles } from '../overlayCard'
 import { OverlayBackdrop, OverlayCard, useOverlayCardColors } from '../OverlaySurface'
+import { SecondaryButton } from '../SecondaryButton'
 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
@@ -71,7 +72,7 @@ function HowToPlayCard({ steps, onFinish, onSkip, rotation = 0, title = 'How to
   const { width: windowWidth, height: windowHeight } = useWindowDimensions()
   const reducedMotion = useReducedMotion()
   const [index, setIndex] = useState(0)
-  const scrollRef = useRef<ScrollView>(null)
+  const scrollRef = useRef<ComponentRef<typeof 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.
@@ -165,11 +166,7 @@ function HowToPlayCard({ steps, onFinish, onSkip, rotation = 0, title = 'How to
             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>
-            )}
+            {!isOnly && <SecondaryButton onPress={isFirst ? onSkip : () => goTo(index - 1)}>{isFirst ? 'Skip' : 'Back'}</SecondaryButton>}
             <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>

package/src/index.ts

@@ -11,7 +11,7 @@ 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 { getInlineColorPickerContentSize, InlineColorPicker, type InlineColorPickerSwatchPlace, type InlineColorPickerSwatchRenderer } from './InlineColorPicker'
 export { getLabeledDropdownContentHeight, LABELED_DROPDOWN_POPOVER_WIDTH, LabeledDropdown, type LabeledDropdownOption } from './LabeledDropdown'
 export { loadSkiaWeb } from './loadSkiaWeb'
 export { locateSkiaWebFile } from './locateSkiaWebFile'
@@ -22,6 +22,7 @@ export { PopoverBody } from './PopoverBody'
 export { PressAwayOverlay } from './PressAwayOverlay'
 export { ReadyButton } from './ReadyButton'
 export { RotatedFrame, type RotatedFrameProps } from './RotatedFrame'
+export { SecondaryButton, type SecondaryButtonProps } from './SecondaryButton'
 export { type MenuOption, type MenuSection, type MultiSelectSection, SectionedDropdown, type SingleSelectSection } from './SectionedDropdown'
 export { SharedActionBand } from './SharedActionBand'
 export { getStaggeredWordDuration, StaggeredWord, type StaggeredWordProps } from './StaggeredWord'
@@ -37,7 +38,7 @@ export { StatSection } from './StatSection'
 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 { type AlignResult, type PopoverAlign, type PopoverRotation, type PopoverVerticalAlign, useAutoAlign, type ViewInstance } from './useAutoAlign'
 export { useCompactDialog } from './useCompactDialog'
 export { type PopoverHost, usePopoverHost } from './usePopoverHost'
 export { type QuitConfirmation, useQuitConfirmation } from './useQuitConfirmation'

package/src/useAutoAlign.ts

@@ -1,11 +1,19 @@
 import { type ViewRotation } from '@tastic/core'
-import { RefObject, useCallback, useEffect, useRef, useState } from 'react'
+import { type ComponentRef, RefObject, useEffect, useRef, useState } from 'react'
 import { useWindowDimensions, View } from 'react-native'
 
 // Minimum breathing room between a popover's outer edge and the screen edge - matches the general
 // "don't butt content right up against the bezel" margin used elsewhere in this app.
 const EDGE_MARGIN = 12
 
+// The edges a popover has room up to: the window's, or a bounds view's (see useAutoAlign).
+interface Limits {
+  left: number
+  top: number
+  right: number
+  bottom: number
+}
+
 export type PopoverAlign = 'left' | 'right' | 'center'
 export type PopoverVerticalAlign = 'below' | 'above'
 // Same set of values as @tastic/core's own ViewRotation - re-exported under this package's existing
@@ -26,9 +34,14 @@ export interface AlignResult {
   verticalAlign: PopoverVerticalAlign
   maxHeight: number
   measured: boolean
-  triggerRef: RefObject<View | null>
+  triggerRef: RefObject<ViewInstance | null>
 }
 
+// What a ref on a View holds. React Native 0.88's strict types make View a function, so a bare
+// `RefObject<View>` there names a ref to the function itself, with no measureInWindow; this is the
+// instance in both its legacy and strict types.
+export type ViewInstance = ComponentRef<typeof View>
+
 // Reflects a rect from the PRE-rotation layout frame measureInWindow actually reports (see
 // useAutoAlign's own comment below for why that's what it reports, not the post-rotation visual
 // position) into its true, post-rotation position - needed for a trigger sitting inside a
@@ -84,8 +97,15 @@ export function rotateRect(x: number, y: number, width: number, height: number,
 //
 // Re-measures on every open (not continuously) - the trigger's screen position can't change while
 // its own popover is showing anyway, so there's nothing to gain from tracking it beyond that.
-export function useAutoAlign(open: boolean, contentWidth: number, contentHeight: number, rotation: PopoverRotation = 0) {
-  const triggerRef = useRef<View>(null)
+//
+// `bounds` is a View the popover can't leave, when that's narrower or shorter than the window: a
+// scroll view the trigger sits in clips its popover at the scroll view's edges, so a popover
+// centred against the window can be cut off by a column narrower than it (a roster capped to a
+// column in a wide window). With it the room on every side is measured to the bounds' edges
+// instead of the window's (measured and rotated the same way as the trigger). Omit it for the
+// window, as before.
+export function useAutoAlign(open: boolean, contentWidth: number, contentHeight: number, rotation: PopoverRotation = 0, bounds?: RefObject<ViewInstance | null>) {
+  const triggerRef = useRef<ViewInstance>(null)
   const { width: windowWidth, height: windowHeight } = useWindowDimensions()
   const [align, setAlign] = useState<PopoverAlign>('center')
   const [verticalAlign, setVerticalAlign] = useState<PopoverVerticalAlign>('below')
@@ -108,12 +128,20 @@ export function useAutoAlign(open: boolean, contentWidth: number, contentHeight:
     if (open) setMeasured(false)
   }
 
-  const measure = useCallback(() => {
-    triggerRef.current?.measureInWindow((rawX, rawY, rawWidth, rawHeight) => {
+  // Re-measures whenever `open` flips true, and also if the content size, the window, the rotation or
+  // the bounds change while already open - e.g. a live window resize, or the device being physically
+  // turned while the popover is showing - so it never goes stale while the popover is actually
+  // showing. `measured` only resets on a genuine (re)open, via the render-phase check above - not here
+  // on every re-measure, so an already-visible popover never flickers hidden again just because the
+  // window resized (or rotated) under it. (The measurement lives in the effect itself, not a
+  // useCallback, so the bounds view is read when it runs.)
+  useEffect(() => {
+    if (!open) return
+    const place = (limits: Limits) => (rawX: number, rawY: number, rawWidth: number, rawHeight: number) => {
       const { x, y, width: triggerWidth, height: triggerHeight } = rotateRect(rawX, rawY, rawWidth, rawHeight, rotation, windowWidth, windowHeight)
       const centerX = x + triggerWidth / 2
-      const overflowsRight = centerX + contentWidth / 2 > windowWidth - EDGE_MARGIN
-      const overflowsLeft = centerX - contentWidth / 2 < EDGE_MARGIN
+      const overflowsRight = centerX + contentWidth / 2 > limits.right - EDGE_MARGIN
+      const overflowsLeft = centerX - contentWidth / 2 < limits.left + EDGE_MARGIN
       // Both directions overflowing means the popover is simply wider than the screen has room for
       // either way - 'center' is the least-bad choice there (symmetric clipping beats asymmetric).
       if (overflowsRight && !overflowsLeft) setAlign('right')
@@ -123,24 +151,25 @@ export function useAutoAlign(open: boolean, contentWidth: number, contentHeight:
       // Below is the default/preferred direction - only flips to above when there's genuinely more
       // room that way, not merely whenever below is imperfect, so a popover close to fitting either
       // way doesn't flip-flop from a one-pixel margin difference.
-      const roomBelow = windowHeight - (y + triggerHeight) - EDGE_MARGIN
-      const roomAbove = y - EDGE_MARGIN
+      const roomBelow = limits.bottom - (y + triggerHeight) - EDGE_MARGIN
+      const roomAbove = y - limits.top - EDGE_MARGIN
       const above = contentHeight > roomBelow && roomAbove > roomBelow
       setVerticalAlign(above ? 'above' : 'below')
       setMaxHeight(Math.max(above ? roomAbove : roomBelow, 0))
       setMeasured(true)
+    }
+    const screen: Limits = { left: 0, top: 0, right: windowWidth, bottom: windowHeight }
+    const boundsView = bounds?.current
+    if (!boundsView) {
+      triggerRef.current?.measureInWindow(place(screen))
+      return
+    }
+    boundsView.measureInWindow((rawX, rawY, rawWidth, rawHeight) => {
+      const b = rotateRect(rawX, rawY, rawWidth, rawHeight, rotation, windowWidth, windowHeight)
+      // Kept inside the window: a bounds view running past it doesn't make room past the screen.
+      triggerRef.current?.measureInWindow(place({ left: Math.max(b.x, 0), top: Math.max(b.y, 0), right: Math.min(b.x + b.width, windowWidth), bottom: Math.min(b.y + b.height, windowHeight) }))
     })
-  }, [contentWidth, contentHeight, windowWidth, windowHeight, rotation])
-
-  // Re-measures whenever `open` flips true, and also if `measure` itself changes identity (i.e.
-  // contentWidth/contentHeight/windowWidth/windowHeight/rotation changed) while already open - e.g.
-  // a live window resize, or the device being physically turned while the popover is showing - so it
-  // never goes stale while the popover is actually showing. `measured` only resets on a genuine
-  // (re)open, via the render-phase check above - not here on every re-measure, so an already-visible
-  // popover never flickers hidden again just because the window resized (or rotated) under it.
-  useEffect(() => {
-    if (open) measure()
-  }, [open, measure])
+  }, [open, contentWidth, contentHeight, windowWidth, windowHeight, rotation, bounds])
 
   return { align, maxHeight, measured, triggerRef, verticalAlign }
 }