@tastic/hud 0.8.4 → 0.12.0

package/src/SectionedDropdown.tsx

@@ -7,7 +7,7 @@ import { Icon, Text } from 'react-native-paper'
 import { MONO_FONT } from './fonts'
 import { PopoverBody } from './PopoverBody'
 import TriggerGaugeHost from './TriggerGaugeHost'
-import { PopoverRotation, useAutoAlign } from './useAutoAlign'
+import { AlignResult, PopoverRotation, useAutoAlign } from './useAutoAlign'
 import { PopoverHost } from './usePopoverHost'
 
 const MENU_BORDER_WIDTH = 1
@@ -96,10 +96,17 @@ interface Props {
   // background — pass a real design-system "on" color explicitly instead when you have one.
   onAccentColor?: string
   dark: boolean
-  // Manual override — omit to let the popover measure its own trigger and pick whichever alignment
-  // keeps it from overflowing the screen edge (see useAutoAlign). Only pass this to force a specific
-  // side regardless of where the trigger actually sits.
+  // Forces a specific horizontal alignment instead of letting whichever placement result applies
+  // (see alignOverride below) decide. Only pass this to force a specific side regardless of where
+  // the trigger actually sits.
   align?: 'left' | 'right' | 'center'
+  // Substitutes this package's own plain useAutoAlign-based placement wholesale (align,
+  // verticalAlign, maxHeight, measured, triggerRef) with a caller-supplied one — e.g.
+  // useZoneClampedAlign's result, for a dropdown living inside a @tastic/split-screen zone, where
+  // the plain window-relative decision can pick a direction that overflows into the shared row
+  // instead of the zone's own boundary. Same shape LabeledDropdown's own alignOverride takes; omit
+  // for the ordinary case (a popover with nothing but the screen edge to avoid).
+  alignOverride?: AlignResult
   // Explicit override for the rotation a @tastic/split-screen-style FakeLandscapeView (or any other
   // ancestor rotated the same way — a bare CSS `transform: rotate()`, not an actual OS-level
   // orientation change) is currently applying. Defaults to a live ambient read via @tastic/core's
@@ -128,7 +135,7 @@ interface Props {
 // powerups are enabled, say) is just this with one 'multi' section (optionally with allClear); a
 // combined menu (e.g. spawn frequency + which types, in one menu) is just two sections in the same
 // array.
-export function SectionedDropdown({ id, host, icon, accessibilityLabel, sections, accentColor, mutedColor, onAccentColor, dark, align: alignOverride, rotation: rotationOverride, autoDismiss = true, labelFontFamily = MONO_FONT, allClearLabels = { all: 'All', clear: 'Clear' } }: Props) {
+export function SectionedDropdown({ id, host, icon, accessibilityLabel, sections, accentColor, mutedColor, onAccentColor, dark, align: forcedAlign, alignOverride, rotation: rotationOverride, autoDismiss = true, labelFontFamily = MONO_FONT, allClearLabels = { all: 'All', clear: 'Clear' } }: Props) {
   const ambientRotation = useRotation()
   const rotation = rotationOverride ?? ambientRotation
   const menuBg = dark ? '#000000' : '#FFFFFF'
@@ -156,8 +163,12 @@ export function SectionedDropdown({ id, host, icon, accessibilityLabel, sections
       const divider = sectionIndex > 0 ? MENU_DIVIDER_HEIGHT : 0
       return sum + rows + footer + divider
     }, 0)
-  const { align: autoAlign, maxHeight, measured, triggerRef, verticalAlign } = useAutoAlign(open, MENU_MAX_WIDTH, estimatedHeight, rotation)
-  const align = alignOverride ?? autoAlign
+  // 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, MENU_MAX_WIDTH, estimatedHeight, rotation)
+  const placement = alignOverride ?? auto
+  const { maxHeight, measured, triggerRef, verticalAlign } = placement
+  const align = forcedAlign ?? placement.align
 
   // Trigger reflects the selected option's own icon only when there's exactly one section and it's
   // single-select — any other shape (multi-select present, or more than one section) has no single

package/src/StaggeredWord.tsx

@@ -0,0 +1,114 @@
+import { useEffect } from 'react'
+import { LayoutChangeEvent, StyleProp, StyleSheet, TextStyle, View, ViewStyle } from 'react-native'
+import Animated, { Easing, useAnimatedStyle, useSharedValue, withDelay, withTiming } from 'react-native-reanimated'
+
+const STAGGER_MS = 45
+const LETTER_DURATION_MS = 320
+
+// The one formula every consumer's own follow-on animation (a paddle rally, a bouncing puck, a
+// looping trail) needs in order to time its own entrance off "once the letters have mostly
+// landed" — five apps (AirHockey, BoxHockey, Pong, LightCycles, Snake) had each independently
+// re-derived `(letterCount - 1) * STAGGER_MS + LETTER_DURATION_MS` locally as their own
+// `TOTAL_STAGGER_MS` constant. Exported as a pure function, not a component return value, so a
+// caller can compute it once, outside render, the same way every one of those apps already did.
+// `letterCount` is the TOTAL number of letters actually animated, not necessarily a single
+// StaggeredWord's own `word.length` — see `startIndex` below for a multi-word wordmark, where a
+// second word's letters continue the same overall stagger sequence.
+export function getStaggeredWordDuration(letterCount: number): number {
+  return (letterCount - 1) * STAGGER_MS + LETTER_DURATION_MS
+}
+
+interface AnimatedLetterProps {
+  char: string
+  index: number
+  color: string
+  reducedMotion: boolean
+  fontFamily: string
+  fontSize: number
+  lineHeight: number
+  fontWeight?: TextStyle['fontWeight']
+  letterSpacing?: number
+}
+
+function AnimatedLetter({ char, index, color, reducedMotion, fontFamily, fontSize, lineHeight, fontWeight, letterSpacing }: AnimatedLetterProps) {
+  const progress = useSharedValue(reducedMotion ? 1 : 0)
+
+  useEffect(() => {
+    if (reducedMotion) return
+    progress.value = withDelay(index * STAGGER_MS, withTiming(1, { duration: LETTER_DURATION_MS, easing: Easing.out(Easing.back(1.5)) }))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reducedMotion])
+
+  const style = useAnimatedStyle(() => ({
+    opacity: progress.value,
+    transform: [{ translateY: (1 - progress.value) * 12 }, { scale: 0.85 + progress.value * 0.15 }]
+  }))
+
+  return (
+    <Animated.Text allowFontScaling={false} style={[{ color, fontFamily, fontSize, lineHeight, fontWeight, letterSpacing }, style]}>
+      {char}
+    </Animated.Text>
+  )
+}
+
+export interface StaggeredWordProps {
+  word: string
+  color: string
+  fontFamily: string
+  fontSize: number
+  lineHeight: number
+  // Whether to skip the stagger entirely and render every letter already fully settled — wire
+  // straight from react-native-reanimated's own useReducedMotion() at the call site rather than
+  // this component calling it internally, so a caller composing several StaggeredWords (see
+  // `startIndex` below) only needs the one hook call, not one per word.
+  reducedMotion: boolean
+  // Continues the stagger sequence from a larger overall wordmark this word is only one line/part
+  // of — this word's own first letter animates at index `startIndex`, its second at
+  // `startIndex + 1`, and so on. Defaults to 0 for a standalone single-word wordmark (Snake's
+  // "SNAKE", Pong's "PONG"); a caller stacking multiple words (AirHockey's "AIR"/"HOCKEY",
+  // BoxHockey's "BOX"/"HOCKEY", LightCycles' "Light"/"Cycles") passes the running total of letters
+  // already animated by earlier words, so the whole wordmark reads as one continuous cascade
+  // instead of each word restarting its own stagger from zero.
+  startIndex?: number
+  // Every consumer this component was extracted from hardcoded bold letters (baked into a fixed
+  // StyleSheet entry, not a prop) — kept as the default here rather than a fixed style, so the one
+  // consumer that doesn't want it (LightCycles, whose own registered display font is already
+  // sufficiently bold on its own) can opt out with `fontWeight='normal'` instead of this component
+  // forcing it unconditionally.
+  fontWeight?: TextStyle['fontWeight']
+  // Unset by default — only AirHockey/BoxHockey/Pong's shared MONO_FONT-based letter style actually
+  // wants extra tracking; Snake's/LightCycles' own theme fonts don't.
+  letterSpacing?: number
+  // The wrapping row's own style — e.g. LightCycles' own vertical offset for its second word
+  // beneath its first.
+  style?: StyleProp<ViewStyle>
+  // Lets a caller measure this word's own rendered box (e.g. to size/position a follow-on canvas
+  // overlay the way Snake's HeroSnakeTrail or LightCycles' HeroTitleTrails do) the same way it
+  // would measure any other plain View.
+  onLayout?: (e: LayoutChangeEvent) => void
+}
+
+// One row of letters staggering in on mount (or rendered already fully settled under reduced
+// motion) — the "AnimatedLetter" building block five apps' own hero-title screens
+// (AirHockey/BoxHockey/Pong/LightCycles/Snake's own HeroTitle.tsx/AnimatedHeroTitle.tsx) had each
+// hand-rolled independently, identical down to the same 45ms stagger, 320ms per-letter duration,
+// and back-ease overshoot. A single word/line on its own, or one of several stacked/side-by-side
+// words sharing one overall stagger sequence via `startIndex` — this component only ever renders
+// one row of letters; a caller composing more than one word renders more than one StaggeredWord
+// (see `startIndex`'s own doc), the same way every one of those five apps' own `Word` helper
+// already did internally.
+export function StaggeredWord({ word, color, fontFamily, fontSize, lineHeight, reducedMotion, startIndex = 0, fontWeight = 'bold', letterSpacing, style, onLayout }: StaggeredWordProps) {
+  return (
+    <View style={[styles.row, style]} onLayout={onLayout}>
+      {word.split('').map((char, i) => (
+        <AnimatedLetter key={i} char={char} index={startIndex + i} color={color} reducedMotion={reducedMotion} fontFamily={fontFamily} fontSize={fontSize} lineHeight={lineHeight} fontWeight={fontWeight} letterSpacing={letterSpacing} />
+      ))}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: 'row'
+  }
+})

package/src/index.ts

@@ -1,4 +1,6 @@
+export { AchievementCatalogSection } from './AchievementCatalogSection'
 export { AchievementRow, LOCKED_BADGE_COLOR } from './AchievementRow'
+export { ActivityStatSection } from './ActivityStatSection'
 export { BaseSettingsDialog, type BaseSettingsDialogProps } from './BaseSettingsDialog'
 export { BaseStatsScreen } from './BaseStatsScreen'
 export { ConfirmDialog, type ConfirmDialogProps } from './ConfirmDialog'
@@ -7,16 +9,18 @@ export { ControlSchemePicker, type ControlSchemePickerProps } from './ControlSch
 export { CornerActionButtons } from './CornerActionButtons'
 export { CornerStatusBadges, type CornerStatusBadgeSeat, type CornerStatusBadgesProps, type OrientationMode } from './CornerStatusBadges'
 export { MONO_FONT } from './fonts'
-export { InlineColorPicker } from './InlineColorPicker'
+export { getInlineColorPickerContentSize, InlineColorPicker } from './InlineColorPicker'
 export { getLabeledDropdownContentHeight, LABELED_DROPDOWN_POPOVER_WIDTH, LabeledDropdown, type LabeledDropdownOption } from './LabeledDropdown'
 export { loadSkiaWeb } from './loadSkiaWeb'
 export { getOverlayCardColors, type OverlayCardColors, overlayStyles } from './overlayCard'
+export { getColorPopoverId, getCpuDifficultyPopoverId, PlayerSetupPanel, type PlayerSetupPanelProps } from './PlayerSetupPanel'
 export { PopoverBody } from './PopoverBody'
 export { PressAwayOverlay } from './PressAwayOverlay'
 export { ReadyButton } from './ReadyButton'
 export { type MenuOption, type MenuSection, type MultiSelectSection, SectionedDropdown, type SingleSelectSection } from './SectionedDropdown'
 export { SharedActionBand } from './SharedActionBand'
 export { SkiaGate, type SkiaGateProps } from './SkiaGate'
+export { getStaggeredWordDuration, StaggeredWord, type StaggeredWordProps } from './StaggeredWord'
 export { StatRow } from './StatRow'
 export { StatSection } from './StatSection'
 // TriggerGauge itself (the raw Skia-based component) is deliberately NOT exported here, even
@@ -29,5 +33,7 @@ export { StatSection } from './StatSection'
 export type { TriggerGaugeProps } from './TriggerGauge'
 export { default as TriggerGaugeHost } from './TriggerGaugeHost'
 export { UpdateDialog, type UpdateDialogProps } from './UpdateDialog'
-export { type PopoverAlign, type PopoverRotation, type PopoverVerticalAlign, useAutoAlign } from './useAutoAlign'
+export { type AlignResult, type PopoverAlign, type PopoverRotation, type PopoverVerticalAlign, useAutoAlign } from './useAutoAlign'
 export { type PopoverHost, usePopoverHost } from './usePopoverHost'
+export { type QuitConfirmation, useQuitConfirmation } from './useQuitConfirmation'
+export { useZoneClampedAlign } from './useZoneClampedAlign'

package/src/useAutoAlign.ts

@@ -1,5 +1,5 @@
 import { type ViewRotation } from '@tastic/core'
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { RefObject, useCallback, 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
@@ -13,6 +13,22 @@ export type PopoverVerticalAlign = 'below' | 'above'
 // rotation" reads clearer at these call sites than the more general core name.
 export type PopoverRotation = ViewRotation
 
+// Same shape useAutoAlign itself returns — exported so a caller can substitute this package's own
+// plain, screen-edge-aware placement wholesale via a component's own `alignOverride` prop (see
+// LabeledDropdown's, SectionedDropdown's, and InlineColorPicker's own `alignOverride`), most often
+// with useZoneClampedAlign's result for a popover living inside a @tastic/split-screen zone, where
+// the plain window-relative decision can pick a direction that overflows into the shared row
+// instead of the zone's own boundary. Hand-declared rather than `ReturnType<typeof useAutoAlign>`
+// so this stays a stable, self-documented public type regardless of useAutoAlign's own internal
+// implementation shape.
+export interface AlignResult {
+  align: PopoverAlign
+  verticalAlign: PopoverVerticalAlign
+  maxHeight: number
+  measured: boolean
+  triggerRef: RefObject<View | null>
+}
+
 // 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

package/src/useQuitConfirmation.ts

@@ -0,0 +1,61 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+export interface QuitConfirmation {
+  /** Wire directly to <ConfirmDialog visible={...}>. */
+  confirmVisible: boolean
+  /** Wire directly to the back button's onPress (GameActionChips/IconButton onBack/onPress). */
+  requestBack: () => void
+  /** Wire directly to <ConfirmDialog onCancel={...}>. */
+  cancelBack: () => void
+}
+
+// Captures the onBackPress + ConfirmDialog "Quit Match?" pattern every fleet game.tsx already
+// hand-wires (Snake, AirHockey, BoxHockey, Pong, LightCycles): interrupt backing out of a match
+// with a confirmation only when there's something worth losing, otherwise back out immediately.
+//
+// `hasProgress` is a lazy () => boolean, not a plain boolean value taken directly - deliberately
+// corrected from this hook's own first version, which took a plain boolean and broke in practice
+// for AirHockey/BoxHockey/Pong: `paused` (derived from this hook's own confirmVisible) has to be
+// computed and handed to useGameState() BEFORE that call returns the very scores/lives/bricks state
+// hasProgress needs to read, so a plain-boolean argument creates a real render-order circular
+// dependency (confirmVisible -> paused -> useGameState -> state -> hasProgress -> confirmVisible).
+// All three apps independently worked around this with their own bespoke shadow-state ("read last
+// render's value, one commit behind"), converging on the same fix by three different names - a sign
+// the hook's own contract was wrong, not that each call site needed its own patch. A lazy getter
+// breaks the cycle by deferring the read to requestBack's own call time, exactly mirroring how the
+// pre-extraction, hand-rolled version of this pattern in every app read scores/bricks/lives fresh
+// from its own onBackPress closure rather than needing the value available earlier in the render.
+//
+// Mirrored into a ref via this fleet's standard effect-based idiom (useEffect with no dependency
+// array, not a bare render-time assignment - see @rific/core's createSettingsContext.tsx for the
+// same convention) rather than read directly, so a stale closure from an earlier render is never
+// what requestBack ends up calling. This also gives requestBack/cancelBack a stable identity across
+// every render (empty deps arrays), which the original plain-boolean version couldn't offer.
+//
+// Deliberately does NOT own or render a <ConfirmDialog> - title/message/icon/confirmLabel/
+// cancelLabel/rotation are all still game-specific (a score pairing, a lives/bricks count, a
+// round-history pip row) and stay authored at each call site; this only owns the open/closed
+// state and the "should this even ask" gate. onConfirmedBack is a plain callback (every current
+// caller passes its own app's safeBack from @/utils/navigation) rather than hardcoded, so this
+// package takes on no expo-router dependency.
+export function useQuitConfirmation(hasProgress: () => boolean, onConfirmedBack: () => void): QuitConfirmation {
+  const [confirmVisible, setConfirmVisible] = useState(false)
+
+  const hasProgressRef = useRef(hasProgress)
+  useEffect(() => {
+    hasProgressRef.current = hasProgress
+  })
+  const onConfirmedBackRef = useRef(onConfirmedBack)
+  useEffect(() => {
+    onConfirmedBackRef.current = onConfirmedBack
+  })
+
+  const requestBack = useCallback(() => {
+    if (hasProgressRef.current()) setConfirmVisible(true)
+    else onConfirmedBackRef.current()
+  }, [])
+
+  const cancelBack = useCallback(() => setConfirmVisible(false), [])
+
+  return { confirmVisible, requestBack, cancelBack }
+}

package/src/useZoneClampedAlign.ts

@@ -0,0 +1,135 @@
+import { useZoneBounds } from '@tastic/split-screen'
+import { useEffect, useState } from 'react'
+import { useWindowDimensions } from 'react-native'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+
+import { PopoverRotation, PopoverVerticalAlign, useAutoAlign } from './useAutoAlign'
+
+// Matches useAutoAlign's own EDGE_MARGIN convention — not exported from that file, so re-declared
+// here rather than reaching into its internals.
+const EDGE_MARGIN = 12
+
+interface OwnBounds {
+  verticalAlign: PopoverVerticalAlign
+  maxHeight: number
+}
+
+// Wraps useAutoAlign with a zone-aware vertical decision for popovers that live inside a
+// @tastic/split-screen zone (see useZoneBounds' own doc) — a no-op outside one (e.g. a solo,
+// non-split-screen screen), where useAutoAlign's own decision is returned untouched.
+//
+// useAutoAlign picks above-vs-below and its own maxHeight by comparing room against the *full
+// device window* — for a trigger inside a zone, that's wrong in a way a simple clamp on top can't
+// fix: capping its chosen direction after the fact still leaves it capable of *choosing* the
+// direction that points into the shared row (or the opposite player's own zone), which, once
+// correctly capped at that boundary, often has hardly any room at all — nearly useless rather than
+// merely mis-sized. The fix has to re-derive the whole vertical decision using the zone's real
+// boundary instead of the window edge, preferring whichever real-world direction is actually safe
+// (away from the shared row — that direction's room really is bounded by the screen edge, same as
+// useAutoAlign already assumes) and only reaching toward the shared row when the content doesn't
+// fit the safe side and the shared side genuinely has more room — the same "only flips when
+// genuinely better" bias useAutoAlign itself uses, just comparing against the zone's own boundary
+// instead of the opposite screen edge.
+//
+// One more twist specific to p2's 180°-rotated zone: PopoverBody positions itself with plain
+// relative CSS (`top:'100%'`/`bottom:'100%'`) against its trigger, resolved in *local*
+// (pre-rotation) space and then rotated along with everything else in the zone — which inverts it,
+// local 'below' the trigger paints as real-world *above* it once the whole zone flips 180°, and
+// vice versa. This hook's result has to be flipped back to the *local* label PopoverBody expects
+// whenever the zone itself is rotated (zone.rotated), or it ends up choosing the real-world
+// direction it meant to avoid — which is exactly the bug an earlier version of this hook had for
+// p2 specifically (it worked correctly for p1, which isn't rotated, and that's what made the bug
+// easy to miss during testing).
+//
+// CORRECTION (2026-09-18): the paragraph above used to also claim "this hook's own direction math
+// is all real-world (from measureInWindow, which — unlike onLayout — already resolves
+// post-transform)" — that's the exact claim useAutoAlign.ts's own doc documents as having already
+// shipped one real, unnoticed bug once (measureInWindow reports the PRE-transform frame, not
+// post-transform; see that file's own comment). This hook still doesn't apply useAutoAlign's own
+// rotateRect(...) correction to its raw measureInWindow read below (awayRoom/towardRoom are
+// computed straight from the uncorrected y/height) — that's a real, currently-unfixed gap, left
+// alone deliberately rather than guessed at: DualZoneLayout's own sharedEdgeY (see
+// React-Native-Split-Screen's DualZoneLayout.tsx, measureShared) has the identical uncorrected-
+// measureInWindow gap, since sharedRef sits under the same live-rotating outer FakeLandscapeView
+// every real caller wraps this in — and zone.rotated alone isn't sufficient to fix just this
+// hook's own half of it (it captures a trigger's own net rotation for p1/p2 specifically, which
+// happens to fully account for the outer rotation there, but sharedEdgeY's own correction needs
+// the outer rotation directly, which differs from zone.rotated for whichever seat zone.rotated is
+// currently true for). Correcting one side without the other risks making the comparison *more*
+// wrong, not less. No current caller in the fleet actually exercises this path today — every real
+// cpuDifficultyAlignOverride call site across the fleet is a confirmed no-op, never actually
+// rendering inside a live DualZoneLayout zone — so nothing currently miscalculates in practice, but
+// this needs real rotated-zone test coverage (ideally live device testing, not just a unit test
+// stubbing measureInWindow) before either hook's room-size/direction math under live device
+// rotation is trustworthy.
+//
+// `rotation` IS threaded through below, though — that part's unambiguous and low-risk on its own:
+// it only ever reaches useAutoAlign's own (rotation-aware) horizontal align decision, which is
+// exactly what a caller gets back verbatim via the `if (!zone) return auto` fallback whenever this
+// hook is used outside a zone at all (its own documented "safe to reach for even in a component
+// that might or might not end up inside one" case) — matching every sibling rotation-aware
+// component's own default of an ambient `useRotation()` read when the caller omits it.
+//
+// The "away" direction's own room also has to stop at the physical safe area, not the raw window
+// edge — useAutoAlign's own windowHeight is the full device height, notch/status bar and home
+// indicator included, so left alone this hook's fix for the shared-row boundary would just trade
+// one overflow (into the other zone) for another (under the status bar, or behind the home
+// indicator). The toward-shared direction doesn't need this: sharedEdgeY already sits well inside
+// the safe content area on its own.
+export function useZoneClampedAlign(open: boolean, contentWidth: number, contentHeight: number, rotation: PopoverRotation = 0): ReturnType<typeof useAutoAlign> {
+  const auto = useAutoAlign(open, contentWidth, contentHeight, rotation)
+  const zone = useZoneBounds()
+  const { height: windowHeight } = useWindowDimensions()
+  const insets = useSafeAreaInsets()
+  const shouldMeasure = open && auto.measured && zone !== null
+
+  // null until this popover's own zone-aware measurement lands (see the effect below) — separate
+  // from auto.measured, which only covers useAutoAlign's own (zone-blind) measurement.
+  const [ownBounds, setOwnBounds] = useState<OwnBounds | null>(null)
+  // Resets synchronously during render, not in the effect below, the instant shouldMeasure flips
+  // either direction — same "adjust state during render" pattern useAutoAlign itself uses for its
+  // own measured reset (see that hook's own comment), so a stale ownBounds from a previous
+  // open/zone never survives into a render it doesn't apply to, not even for the one frame before
+  // an effect would otherwise catch up.
+  const [prevShouldMeasure, setPrevShouldMeasure] = useState(shouldMeasure)
+  if (shouldMeasure !== prevShouldMeasure) {
+    setPrevShouldMeasure(shouldMeasure)
+    setOwnBounds(null)
+  }
+
+  // Re-measures the same trigger node useAutoAlign itself measures, once *its* measurement has
+  // landed (auto.measured, folded into shouldMeasure) so the ref is guaranteed mounted and settled.
+  // A second measureInWindow call on the same node, not a shared one with useAutoAlign — that
+  // hook's own measurement is fully internal to it, with nothing exposed to piggyback on beyond the
+  // ref itself.
+  useEffect(() => {
+    if (!shouldMeasure) return
+    auto.triggerRef.current?.measureInWindow((_x, y, _width, height) => {
+      const belowShared = zone!.zoneSide === 'belowShared'
+      // Same shape as useAutoAlign's own roomBelow/roomAbove — this is the direction with nothing
+      // else between the popover and the real screen edge — but stopping at the safe area inset
+      // instead of the raw window edge (insets.top/insets.bottom are always real physical-device
+      // edges, unaffected by any rotation applied further down the tree, so this is correct as-is
+      // for p2's rotated zone too, not just p1's).
+      const awayRoom = belowShared ? windowHeight - insets.bottom - (y + height) - EDGE_MARGIN : y - insets.top - EDGE_MARGIN
+      // The other direction runs into the shared row instead of the screen edge.
+      const towardRoom = belowShared ? y - zone!.sharedEdgeY - EDGE_MARGIN : zone!.sharedEdgeY - (y + height) - EDGE_MARGIN
+      const useToward = contentHeight > awayRoom && towardRoom > awayRoom
+      // Real-world direction, before any rotation compensation.
+      let awaySide: PopoverVerticalAlign = belowShared ? 'below' : 'above'
+      let towardSide: PopoverVerticalAlign = belowShared ? 'above' : 'below'
+      // See this hook's own doc — PopoverBody's local-then-rotate positioning inverts 'above'/
+      // 'below' for a rotated zone, so the real-world label chosen above has to flip back to the
+      // local one that actually produces it once painted.
+      if (zone!.rotated) {
+        awaySide = awaySide === 'above' ? 'below' : 'above'
+        towardSide = towardSide === 'above' ? 'below' : 'above'
+      }
+      setOwnBounds({ maxHeight: Math.max(useToward ? towardRoom : awayRoom, 0), verticalAlign: useToward ? towardSide : awaySide })
+    })
+  }, [shouldMeasure, zone, auto.triggerRef, contentHeight, windowHeight, insets.top, insets.bottom])
+
+  if (!zone) return auto
+  if (!ownBounds) return { ...auto, measured: false }
+  return { ...auto, maxHeight: ownBounds.maxHeight, measured: auto.measured, verticalAlign: ownBounds.verticalAlign }
+}