@tastic/hud 0.8.5 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastic/hud",
-  "version": "0.8.5",
+  "version": "0.13.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",
@@ -71,14 +78,17 @@
   "prettier": "@infinitetoken/eslint-config/prettier",
   "devDependencies": {
     "@infinitetoken/eslint-config": "^0.2.0",
-    "@infinitetoken/jest-config": "^0.3.0",
-    "@infinitetoken/tsconfig": "^0.4.1",
-    "@rific/auto-paper": "^0.11.0",
-    "@rific/core": "^0.1.1",
-    "@rific/feedback-press": "^0.11.1",
+    "@infinitetoken/jest-config": "^0.4.0",
+    "@infinitetoken/tsconfig": "^0.5.0",
+    "@rific/auto-paper": "^0.12.0",
+    "@rific/core": "^0.2.0",
+    "@rific/feedback-press": "^0.12.0",
     "@rific/updater": "^0.6.0",
     "@shopify/react-native-skia": "^2.6.2",
-    "@tastic/core": "^0.4.1",
+    "@tastic/achievements": "^0.2.0",
+    "@tastic/core": "^0.8.0",
+    "@tastic/profile": "^0.7.0",
+    "@tastic/split-screen": "^0.5.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^30.0.0",
@@ -94,19 +104,44 @@
     "react-native": "^0.85.3",
     "react-native-paper": "^5.15.2",
     "react-native-reanimated": "^4.5.1",
+    "react-native-safe-area-context": "^5.10.0",
     "tsup": "^8.0.0",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@rific/auto-paper": ">=0.9.0",
-    "@rific/feedback-press": ">=0.10.0",
+    "@rific/auto-paper": ">=0.9.4",
+    "@rific/feedback-press": ">=0.10.2",
     "@rific/updater": ">=0.4.0",
     "@shopify/react-native-skia": ">=1.5.0",
-    "@tastic/core": ">=0.3.0",
+    "@tastic/achievements": ">=0.2.0",
+    "@tastic/core": ">=0.5.0",
+    "@tastic/profile": ">=0.4.0",
+    "@tastic/split-screen": ">=0.5.0",
     "react": ">=19.0.0",
     "react-native": ">=0.76.0",
     "react-native-paper": ">=5.0.0",
-    "react-native-reanimated": ">=3.0.0"
+    "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/AchievementCatalogSection.tsx

@@ -0,0 +1,60 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import type { AchievementCatalogRow } from '@tastic/achievements'
+import { Fragment } from 'react'
+import { StyleSheet } from 'react-native'
+import { Text } from 'react-native-paper'
+
+import { AchievementRow, LOCKED_BADGE_COLOR } from './AchievementRow'
+import { MONO_FONT } from './fonts'
+
+// AchievementCatalogRow now comes straight from @tastic/achievements' own getAchievementCatalogRows
+// (added in the same 2026-09-18 achievements-scaffolding pass this component belongs to) — no
+// longer duplicated locally now that package has actually published the export (confirmed the two
+// shapes match exactly before wiring this real, type-only peer dependency).
+
+interface Props {
+  rows: AchievementCatalogRow[]
+  label?: string
+  // Independently optional overrides for this section's own heading/row colors - default to the
+  // same useAutoPaperTheme()-derived formula as AchievementRow/StatSection/StatRow/BaseStatsScreen
+  // (see BaseStatsScreen's own doc for why) when omitted, so every existing caller renders
+  // identically to before. Passed straight through to each <AchievementRow>.
+  fg?: string
+  fgMuted?: string
+}
+
+// The "ALL ACHIEVEMENTS" heading + one <AchievementRow> per row - extracted verbatim from every
+// fleet app's own achievements.tsx (Snake, AirHockey, BoxHockey, Pong, LightCycles), where this
+// exact heading/list pair backed the bottom of the stats screen. Returns a Fragment, not a View:
+// every existing call site rendered the heading and each row as flat siblings inside
+// BaseStatsScreen's own gap-spaced ScrollView content, and wrapping them in a container here would
+// change that spacing (BaseStatsScreen's own `content` style already supplies the gap between
+// every child, this component included).
+//
+// Resolves each row's own locked-vs-unlocked badgeColor (tierColor when unlocked,
+// LOCKED_BADGE_COLOR when not) here rather than upstream in row computation, matching
+// AchievementRow's own "badge color is a rendering decision" doc comment - @tastic/achievements'
+// (pending) getAchievementCatalogRows deliberately leaves tierColor unresolved-to-badgeColor for
+// the same reason.
+export function AchievementCatalogSection({ rows, label = 'ALL ACHIEVEMENTS', fg, fgMuted: fgMutedOverride }: Props) {
+  const { dark } = useAutoPaperTheme()
+  const fgMuted = fgMutedOverride ?? (dark ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)')
+
+  return (
+    <Fragment>
+      <Text variant='labelMedium' style={[styles.label, { color: fgMuted, fontFamily: MONO_FONT }]}>
+        {label}
+      </Text>
+      {rows.map((row) => (
+        <AchievementRow key={row.id} icon={row.icon} title={row.title} description={row.description} badgeColor={row.unlockedAt !== undefined ? row.tierColor : LOCKED_BADGE_COLOR} checkColor={row.tierColor} unlockedLabel={row.unlockedLabel} progress={row.progress} deviceMarker={row.deviceMarker} fg={fg} fgMuted={fgMutedOverride} />
+      ))}
+    </Fragment>
+  )
+}
+
+const styles = StyleSheet.create({
+  label: {
+    letterSpacing: 2,
+    marginTop: 8
+  }
+})

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/ActivityStatSection.tsx

@@ -0,0 +1,29 @@
+import { StatRow } from './StatRow'
+import { StatSection } from './StatSection'
+
+interface ActivityStats {
+  distinctDaysPlayed: number
+  currentDayStreak: number
+  bestDayStreak: number
+}
+
+interface Props {
+  stats: ActivityStats
+}
+
+// The "ACTIVITY" StatSection (Days Played / Day Streak / Best Day Streak) - extracted verbatim
+// from every fleet app's own achievements.tsx (Snake, AirHockey, BoxHockey, Pong, LightCycles),
+// where this exact three-row block was byte-for-byte identical. ActivityStats is a plain
+// structural type (matching @tastic/achievements' own DayStreakState shape - distinctDaysPlayed/
+// currentDayStreak/bestDayStreak) rather than importing DayStreakState itself, so this component
+// has no dependency on @tastic/achievements at all: any caller's own stats/statsView object that
+// happens to carry these three fields already satisfies it structurally.
+export function ActivityStatSection({ stats }: Props) {
+  return (
+    <StatSection label='ACTIVITY'>
+      <StatRow label='Days Played' value={String(stats.distinctDaysPlayed)} />
+      <StatRow label='Day Streak' value={String(stats.currentDayStreak)} />
+      <StatRow label='Best Day Streak' value={String(stats.bestDayStreak)} />
+    </StatSection>
+  )
+}

package/src/BaseSettingsDialog.tsx

@@ -67,6 +67,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 +84,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
@@ -235,6 +239,33 @@ export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverr
                   )}
                 </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 }}>
+                        How to Play
+                      </Text>
+                      <Text variant='bodySmall' numberOfLines={1} style={{ color: colors.onSurfaceVariant }}>
+                        Replay the quick intro
+                      </Text>
+                    </View>
+                  </View>
+                </TouchableRipple>
+              )}
             </View>
 
             {showAppearance && (

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'
   },

package/src/ContentGutter.tsx

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

package/src/ControlSchemePicker.tsx

@@ -2,6 +2,7 @@ import { useIsTouchPrimaryDevice } from '@tastic/core'
 import { Platform } from 'react-native'
 
 import { MenuOption, SectionedDropdown } from './SectionedDropdown'
+import { AlignResult, PopoverRotation } from './useAutoAlign'
 import { PopoverHost } from './usePopoverHost'
 
 export interface ControlSchemePickerProps<T extends string | number> {
@@ -21,6 +22,14 @@ export interface ControlSchemePickerProps<T extends string | number> {
   onAccentColor?: string
   dark: boolean
   align?: 'left' | 'right' | 'center'
+  // Passed straight through to the underlying SectionedDropdown — see that component's own
+  // `alignOverride` doc. Lets a caller inside a @tastic/split-screen zone substitute
+  // useZoneClampedAlign's result for this picker's own popover placement.
+  alignOverride?: AlignResult
+  // Passed straight through to the underlying SectionedDropdown — see that component's own
+  // `rotation` doc. Defaults to a live ambient useRotation() read when omitted, same as
+  // SectionedDropdown itself.
+  rotation?: PopoverRotation
   labelFontFamily?: string
 }
 
@@ -45,9 +54,9 @@ export interface ControlSchemePickerProps<T extends string | number> {
 // no keys of their own (a "keep using pointer input" option, say) are purely a per-app label — so a
 // caller always supplies its own `options` (and typically its own `T`) rather than this component
 // importing `@tastic/input` and choosing a set for every consumer.
-export function ControlSchemePicker<T extends string | number>({ id, host, value, onChange, options, takenValue, accentColor, mutedColor, onAccentColor, dark, align, labelFontFamily }: ControlSchemePickerProps<T>) {
+export function ControlSchemePicker<T extends string | number>({ id, host, value, onChange, options, takenValue, accentColor, mutedColor, onAccentColor, dark, align, alignOverride, rotation, labelFontFamily }: ControlSchemePickerProps<T>) {
   const isTouchPrimary = useIsTouchPrimaryDevice()
   if (Platform.OS !== 'web' || isTouchPrimary) return null
 
-  return <SectionedDropdown id={id} host={host} icon='keyboard-outline' accessibilityLabel='Control scheme' sections={[{ kind: 'single', id: 'controls', options, value, onChange, takenValue }]} accentColor={accentColor} mutedColor={mutedColor} onAccentColor={onAccentColor} dark={dark} align={align} labelFontFamily={labelFontFamily} />
+  return <SectionedDropdown id={id} host={host} icon='keyboard-outline' accessibilityLabel='Control scheme' sections={[{ kind: 'single', id: 'controls', options, value, onChange, takenValue }]} accentColor={accentColor} mutedColor={mutedColor} onAccentColor={onAccentColor} dark={dark} align={align} alignOverride={alignOverride} rotation={rotation} labelFontFamily={labelFontFamily} />
 }

package/src/InlineColorPicker.tsx

@@ -6,7 +6,7 @@ import { Icon, Text } from 'react-native-paper'
 
 import { MONO_FONT } from './fonts'
 import { PopoverBody } from './PopoverBody'
-import { PopoverRotation, useAutoAlign } from './useAutoAlign'
+import { AlignResult, PopoverRotation, useAutoAlign } from './useAutoAlign'
 import { PopoverHost } from './usePopoverHost'
 
 // Presence check, not a full-string "is this exactly one emoji" validation — this only decides a
@@ -35,6 +35,26 @@ function widthForColumns(columns: number) {
   return SWATCHES_BORDER_WIDTH * 2 + SWATCHES_PADDING * 2 + SWATCH_SIZE * columns + SWATCHES_GAP * (columns - 1)
 }
 
+// Exported so a caller that needs to independently compute this popover's own content size — to
+// feed useZoneClampedAlign's contentWidth/contentHeight params with, ahead of producing a
+// colorAlignOverride for a picker living inside a @tastic/split-screen zone — can match this
+// component's real rendered size exactly, rather than re-deriving or hardcoding its internal
+// column/row math. Same job as LabeledDropdown's own getLabeledDropdownContentHeight, but this
+// picker's size also depends on window width (via the auto-column clamp below), so windowWidth is
+// a required parameter here rather than an ambient useWindowDimensions() read — a caller computing
+// this ahead of render (to decide alignment before the picker itself has even mounted) has no
+// component instance to read that hook from, so it has to pass the value in instead. The component
+// below calls this same function with its own live useWindowDimensions() read, so there is exactly
+// one place this formula lives.
+export function getInlineColorPickerContentSize(swatchCount: number, windowWidth: number, columns?: number): { width: number; height: number } {
+  const autoColumns = clamp(Math.floor((windowWidth - 2 * SCREEN_MARGIN + SWATCHES_GAP) / (SWATCH_SIZE + SWATCHES_GAP)), MIN_COLUMNS, MAX_COLUMNS)
+  const resolvedColumns = columns ?? autoColumns
+  const width = widthForColumns(resolvedColumns)
+  const rows = Math.ceil(swatchCount / resolvedColumns)
+  const height = SWATCHES_BORDER_WIDTH * 2 + SWATCHES_PADDING * 2 + SWATCH_SIZE * rows + SWATCHES_GAP * (rows - 1)
+  return { width, height }
+}
+
 interface Props {
   id: string
   host: PopoverHost
@@ -59,9 +79,16 @@ interface Props {
   // tradeoff.
   allowSwapTaken?: boolean
   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).
+  // Forces a specific horizontal alignment instead of letting whichever placement result applies
+  // (see alignOverride below) decide.
   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 picker 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/SectionedDropdown'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
   // equivalent) ancestor is currently applying — see SectionedDropdown's identical prop for the
   // full reasoning. Defaults to a live ambient read via @tastic/core's useRotation() when omitted.
@@ -93,20 +120,20 @@ interface Props {
 // 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: 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 }: Props) {
   const ambientRotation = useRotation()
   const rotation = rotationOverride ?? ambientRotation
   const menuBg = dark ? '#000000' : '#FFFFFF'
   const { width: windowWidth } = useWindowDimensions()
-  const autoColumns = clamp(Math.floor((windowWidth - 2 * SCREEN_MARGIN + SWATCHES_GAP) / (SWATCH_SIZE + SWATCHES_GAP)), MIN_COLUMNS, MAX_COLUMNS)
-  const resolvedColumns = columns ?? autoColumns
-  const swatchesWidth = widthForColumns(resolvedColumns)
-  const swatchRows = Math.ceil(swatches.length / resolvedColumns)
-  const swatchesHeight = SWATCHES_BORDER_WIDTH * 2 + SWATCHES_PADDING * 2 + SWATCH_SIZE * swatchRows + SWATCHES_GAP * (swatchRows - 1)
+  const { width: swatchesWidth, height: swatchesHeight } = getInlineColorPickerContentSize(swatches.length, windowWidth, columns)
 
   const open = host.openId === id
-  const { align: autoAlign, maxHeight, measured, triggerRef, verticalAlign } = useAutoAlign(open, swatchesWidth, swatchesHeight, 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, swatchesWidth, swatchesHeight, rotation)
+  const placement = alignOverride ?? auto
+  const { maxHeight, measured, triggerRef, verticalAlign } = placement
+  const align = forcedAlign ?? placement.align
   const displayFor = previewValue ?? ((hex: string) => hex)
   const displayValue = displayFor(value)
   const contrastColor = getContrastColor(displayValue)

package/src/LabeledDropdown.tsx

@@ -1,11 +1,10 @@
 import { getContrastColor } from '@rific/auto-paper'
 import { TouchableRipple } from '@rific/feedback-press'
-import { RefObject } from 'react'
 import { ScrollView, StyleSheet, View } from 'react-native'
 import { Icon, Text } from 'react-native-paper'
 
 import { PopoverBody } from './PopoverBody'
-import { PopoverAlign, PopoverVerticalAlign, useAutoAlign } from './useAutoAlign'
+import { AlignResult, useAutoAlign } from './useAutoAlign'
 import { PopoverHost } from './usePopoverHost'
 
 const TRIGGER_HEIGHT = 28
@@ -29,17 +28,6 @@ export interface LabeledDropdownOption<T extends string> {
   icon?: string
 }
 
-// Same shape useAutoAlign itself returns — lets a caller inside a @tastic/split-screen zone (or
-// any other layout this package doesn't know about) substitute its own alignment decision via
-// `alignOverride` below, without this package taking a dependency on that caller's own hook.
-interface AlignResult {
-  align: PopoverAlign
-  verticalAlign: PopoverVerticalAlign
-  maxHeight: number
-  measured: boolean
-  triggerRef: RefObject<View | null>
-}
-
 interface Props<T extends string> {
   id: string
   host: PopoverHost
@@ -74,10 +62,10 @@ export function LabeledDropdown<T extends string>({ id, host, options, value, on
   const selected = options.find((o) => o.value === value) ?? null
   const contentHeight = LIST_PADDING * 2 + options.length * ROW_HEIGHT
   // Always called, even when alignOverride is supplied and this result goes unused — hooks can't be
-  // called conditionally. A caller passing alignOverride (e.g. LightCycles' own useZoneClampedAlign,
-  // which already wraps this same hook) does end up measuring the trigger twice; an acceptable
-  // tradeoff for keeping this component's own hook usage unconditional and override-shaped rather
-  // than needing a second, hook-free code path.
+  // called conditionally. A caller passing alignOverride (e.g. this package's own
+  // useZoneClampedAlign, which already wraps this same hook) does end up measuring the trigger
+  // twice; an acceptable tradeoff for keeping this component's own hook usage unconditional and
+  // override-shaped rather than needing a second, hook-free code path.
   const auto = useAutoAlign(open, POPOVER_WIDTH, contentHeight)
   const placement = alignOverride ?? auto
   const { maxHeight, measured, triggerRef, verticalAlign } = placement