@tastic/profile 0.11.0 → 0.13.0

package/src/ProfilesScreen.tsx

@@ -6,7 +6,7 @@ import { StyleSheet, View } from 'react-native'
 import { ProfileEditPatch, ProfilesManager, ProfilesManagerHandle, ProfilesManagerProps } from './ProfilesManager'
 import { Profile } from './types'
 
-// react-native-paper's own MD3 Text variant names — mirrored locally rather than importing its
+// react-native-paper's own MD3 Text variant names - mirrored locally rather than importing its
 // internal VariantProp/MD3TypescaleKey (not exported from the package's public entry point), same
 // as ProfilesManager's own identical titleVariant prop does.
 type MD3TextVariant = 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'labelLarge' | 'labelMedium' | 'labelSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall'
@@ -16,28 +16,27 @@ export interface ProfilesScreenProps {
   // Same reasoning as ProfilesManager's own defaultColor: this component has no opinion on the
   // host's palette, so it stays required rather than defaulted. Callers already differ here today
   // (most apps pass @rific/auto-paper's defaultColors[0].value; one passes its own local
-  // DEFAULT_P1_COLOR constant instead) — this prop is exactly what lets both keep working unchanged.
+  // DEFAULT_P1_COLOR constant instead) - this prop is exactly what lets both keep working unchanged.
   defaultColor: string
-  // Same ProfileEditPatch shape ProfilesManager's own onCreate/onSave already take — deliberately
+  // Same ProfileEditPatch shape ProfilesManager's own onCreate/onSave already take - deliberately
   // NOT widened to accept a host's own richer CreateProfileInput. A host whose profile shape has
   // extra required fields (e.g. a control/key scheme) composes those in its own closure at the call
   // site, exactly as it already does calling <ProfilesManager> today.
   onCreate: (patch: ProfileEditPatch) => void
   onSave: (id: string, patch: ProfileEditPatch) => void
-  // Irreversible, same as ProfilesManager's own onDelete — fires once, after this component's
+  // Irreversible, same as ProfilesManager's own onDelete - fires once, after this component's
   // internal confirmation card. If the host tracks anything else keyed by profile id (stats,
   // achievement-unlock history), clear that on its own side inside this callback, same as every
   // current app's `(id) => { deleteProfile(id); removeProfileStats(id) }`.
   onDelete: (id: string) => void
   onBack: () => void
   // Independently optional overrides, each defaulting to the same literal-black/white-by-appearance
-  // formula every current caller renders with unchanged (none of them pass these today) — same
+  // formula every current caller renders with unchanged (none of them pass these today) - same
   // convention as BaseStatsScreen's and ProfilesManager's own fg/bg-shaped overrides. fg/fgMuted/
-  // cardBg/titleVariant/colorPreview are forwarded straight through to the internal ProfilesManager.
+  // titleVariant/colorPreview are forwarded straight through to the internal ProfilesManager.
   fg?: string
   fgMuted?: string
   bg?: string
-  cardBg?: string
   titleVariant?: MD3TextVariant
   colorPreview?: (hex: string) => string
   // Forwarded straight through to the internal ProfilesManager - a placement hook for the color swatch popover, for
@@ -49,13 +48,13 @@ export interface ProfilesScreenProps {
 // The routed profiles-roster screen shell every app in this fleet hand-rolls around ProfilesManager
 // today: the container View + theme-derived bg/fg + back button + commit-pending-edit-before-
 // navigate composition. Lives here rather than in @tastic/hud since it has zero generic/non-profile
-// UI content — it's one layer up from ProfilesManager, not a different kind of thing. Deliberately
-// still doesn't call useProfiles()/useGameStats() (or any host-specific hook) itself — those two
+// UI content - it's one layer up from ProfilesManager, not a different kind of thing. Deliberately
+// still doesn't call useProfiles()/useGameStats() (or any host-specific hook) itself - those two
 // hooks' shapes are genuinely app-specific (different CreateProfileInput/GameStatsContextValue per
 // app), so this stays props-in/callbacks-out, exactly like ProfilesManager itself.
-export function ProfilesScreen({ profiles, defaultColor, onCreate, onSave, onDelete, onBack, fg: fgOverride, fgMuted, bg: bgOverride, cardBg, titleVariant, colorPreview, useColorPickerAlign }: ProfilesScreenProps) {
+export function ProfilesScreen({ profiles, defaultColor, onCreate, onSave, onDelete, onBack, fg: fgOverride, fgMuted, bg: bgOverride, titleVariant, colorPreview, useColorPickerAlign }: ProfilesScreenProps) {
   const { dark } = useAutoPaperTheme()
-  // Owns the ref itself — nothing outside this component ever needs it, since this is now the one
+  // Owns the ref itself - nothing outside this component ever needs it, since this is now the one
   // thing that both renders ProfilesManager AND owns the only navigation trigger next to it.
   const managerRef = useRef<ProfilesManagerHandle>(null)
   // Same literal-black/white-by-appearance formula as ProfilesManager's own fg default, resolved
@@ -75,7 +74,7 @@ export function ProfilesScreen({ profiles, defaultColor, onCreate, onSave, onDel
 
   return (
     <View style={[styles.container, { backgroundColor: bg }]}>
-      <ProfilesManager ref={managerRef} profiles={profiles} defaultColor={defaultColor} onCreate={onCreate} onSave={onSave} onDelete={onDelete} fg={fg} fgMuted={fgMuted} cardBg={cardBg} titleVariant={titleVariant} colorPreview={colorPreview} useColorPickerAlign={useColorPickerAlign} headerLeft={<IconButton icon='arrow-left' iconColor={fg} size={24} onPress={handleBack} accessibilityLabel='Back' />} />
+      <ProfilesManager ref={managerRef} profiles={profiles} defaultColor={defaultColor} onCreate={onCreate} onSave={onSave} onDelete={onDelete} fg={fg} fgMuted={fgMuted} titleVariant={titleVariant} colorPreview={colorPreview} useColorPickerAlign={useColorPickerAlign} headerLeft={<IconButton icon='arrow-left' iconColor={fg} size={24} onPress={handleBack} accessibilityLabel='Back' />} />
     </View>
   )
 }

package/src/index.ts

@@ -10,5 +10,6 @@ export { type CreateProfileInput, createProfileRecord, profilesActions, profiles
 export { resolveInitialProfiles } from './redux/resolveInitialProfiles'
 export { createSeatColorsSlice, type SeatColorsActions, type SeatColorsSlice, type SeatColorsState, type SetLastGuestColorPayload, type SetProfileOverridePayload } from './redux/seatColorsSlice'
 export { useSharedProfilesSync, type UseSharedProfilesSyncOptions, type UseSharedProfilesSyncResult } from './redux/useSharedProfilesSync'
-export { isSharedProfileStoreAvailable, loadSharedProfiles, saveSharedProfiles } from './sharedProfileStore'
+export { avoidSeatColorClash } from './seatColorClash'
+export { isSharedProfileStoreAvailable, loadSharedProfiles, readSharedProfiles, saveSharedProfiles } from './sharedProfileStore'
 export type { Profile } from './types'

package/src/profilesValidation.ts

@@ -1,7 +1,7 @@
 import { Profile } from './types'
 
 export const MAX_PROFILE_NAME_LENGTH = 20
-// In code points, not JS string length — a single emoji can span more than one UTF-16 code unit
+// In code points, not JS string length - a single emoji can span more than one UTF-16 code unit
 // (surrogate pairs, variation selectors), which .length would overcount.
 export const MAX_TAG_LENGTH = 3
 
@@ -11,23 +11,23 @@ function isValidHexColor(value: unknown): value is string {
 
 // Codepoint 0xFE0F is the variation selector that forces an emoji-style rendering of an otherwise
 // dual-purpose glyph; 0x200D is the zero-width joiner that chains multiple pictographs into one
-// compound emoji (a family, a flag, a skin-tone variant) — built from String.fromCodePoint rather
+// compound emoji (a family, a flag, a skin-tone variant) - built from String.fromCodePoint rather
 // than embedded directly in a regex literal so this file's own source has no invisible characters
 // in it.
 const VARIATION_SELECTOR = String.fromCodePoint(0xfe0f)
 const ZERO_WIDTH_JOINER = String.fromCodePoint(0x200d)
-// Matches one emoji as a single unit, including a ZWJ-joined compound — good enough for telling
+// Matches one emoji as a single unit, including a ZWJ-joined compound - good enough for telling
 // "the user typed an emoji" from "the user typed letters" without needing full Unicode grapheme
 // segmentation (Intl.Segmenter's own Hermes support is inconsistent enough not to lean on here).
 const EMOJI_PATTERN = new RegExp(`^\\p{Extended_Pictographic}${VARIATION_SELECTOR}?(${ZERO_WIDTH_JOINER}\\p{Extended_Pictographic}${VARIATION_SELECTOR}?)*$`, 'u')
 
-// Presence check, not the full anchored EMOJI_PATTERN above — clampTag below only needs to know
+// Presence check, not the full anchored EMOJI_PATTERN above - clampTag below only needs to know
 // whether a just-typed chunk contains a pictograph at all, not whether an entire value is exactly
 // one (possibly ZWJ-joined) emoji. Same distinction @tastic/hud's InlineColorPicker draws for its
 // own font-sizing check.
 const EMOJI_PRESENT = /\p{Extended_Pictographic}/u
 
-// Empty is valid too — a profile can have no tag yet, same as it can go without ever entering an
+// Empty is valid too - a profile can have no tag yet, same as it can go without ever entering an
 // editor's own tag field at all; every place this renders falls back to a generic icon in that case
 // (see ProfileChip).
 export function isValidTag(value: unknown): value is string {
@@ -45,8 +45,8 @@ export function clampTag(previous: string, next: string): string {
   const previousCodepoints = Array.from(previous)
   const nextCodepoints = Array.from(next)
 
-  // Shrinking (backspace/delete, or a selectTextOnFocus-driven wholesale replacement — see
-  // ProfilesManager's own EditRow — reporting its own replacement text as no longer than what it
+  // Shrinking (backspace/delete, or a selectTextOnFocus-driven wholesale replacement - see
+  // ProfilesManager's own EditRow - reporting its own replacement text as no longer than what it
   // overwrote) always passes through untouched: there's nothing to clamp about removing content.
   if (nextCodepoints.length <= previousCodepoints.length) return next
 
@@ -54,7 +54,7 @@ export function clampTag(previous: string, next: string): string {
   while (sharedPrefixLength < previousCodepoints.length && previousCodepoints[sharedPrefixLength] === nextCodepoints[sharedPrefixLength]) sharedPrefixLength++
   const added = nextCodepoints.slice(sharedPrefixLength).join('')
 
-  // A tag is either a handful of plain characters or exactly one emoji, never a mix — typing more
+  // A tag is either a handful of plain characters or exactly one emoji, never a mix - typing more
   // of either kind on top of the other one starts fresh with just what's newly typed, rather than
   // producing a combination isValidTag would reject anyway (an emoji followed by letters, or a
   // second emoji tacked onto the first).
@@ -63,7 +63,7 @@ export function clampTag(previous: string, next: string): string {
   return nextCodepoints.length > MAX_TAG_LENGTH ? previous : next
 }
 
-// Validates only the fields this package's own `Profile` type declares — an app that extends
+// Validates only the fields this package's own `Profile` type declares - an app that extends
 // Profile with its own fields (a control scheme, anything else) needs its own wrapper that runs
 // this first and then checks its own additions, same as it extends the type itself. See this
 // package's own README for the composition pattern.

package/src/redux/createActionCreator.ts

@@ -10,7 +10,7 @@ export type ActionCreator<P> = ((payload: P) => ReduxAction<P>) & {
 
 // Same low-level shape @rific/core's createSettingsSlice gives every other slice in the fleet
 // (namespaced type string, .type, .match). Shared internally between profilesSlice.ts and
-// profileExtensionSlice.ts rather than each hand-rolling its own copy — not exported from
+// profileExtensionSlice.ts rather than each hand-rolling its own copy - not exported from
 // index.ts, since it's an implementation detail of how this package's own reducers are built, not
 // something a consuming app needs.
 export function createActionCreator<P>(type: string): ActionCreator<P> {

package/src/redux/profileExtensionSlice.ts

@@ -19,7 +19,7 @@ export interface ProfileExtensionSlice<TExtension> {
 
 // A per-profile extension is any app-specific field that doesn't belong on the shared base Profile
 // type (a control scheme, a key-binding preference, a difficulty setting, ...) but still needs to
-// travel WITH a specific profile id, entirely locally — never synced to the shared App Group
+// travel WITH a specific profile id, entirely locally - never synced to the shared App Group
 // roster (a profile created on a sibling @tastic game has no idea this extension exists at all,
 // same as this package's own README describes for any app-specific field). Two real @tastic games
 // (BoxHockey's controlScheme, LightCycles' keyScheme) each hand-rolled an almost-identical
@@ -28,10 +28,10 @@ export interface ProfileExtensionSlice<TExtension> {
 // need a third copy.
 //
 // `namespace` prefixes every action type (e.g. 'profileExtension/controlScheme/set') so an app with
-// more than one independent per-profile extension never collides between them — same convention
+// more than one independent per-profile extension never collides between them - same convention
 // @rific/core's createSettingsSlice uses its own namespace argument for.
 //
-// Deliberately NOT auto-cleared when the base `profiles` slice removes an id — this stays a plain,
+// Deliberately NOT auto-cleared when the base `profiles` slice removes an id - this stays a plain,
 // self-contained reducer rather than importing profilesActions.remove's action type to listen for.
 // An app already dispatches multiple independent actions when deleting a profile (profilesActions.
 // remove, and typically its own local selection-slice cleanup); calling this slice's own `remove`

package/src/redux/profileSelectionSlice.ts

@@ -1,7 +1,7 @@
 import { ActionCreator, createActionCreator } from './createActionCreator'
 
 // redux-persist's own REHYDRATE action-type constant, inlined as a literal rather than taking a
-// dependency on the package itself — this factory otherwise has no opinion on whether the
+// dependency on the package itself - this factory otherwise has no opinion on whether the
 // consuming app uses redux-persist at all, and the string itself is a long-stable part of
 // redux-persist's own public contract (unchanged across every major version). See the reducer's
 // own REHYDRATE case below for why this needs handling at all.
@@ -25,30 +25,30 @@ export interface ProfileSelectionSlice<TSeat extends string | number> {
   reducer: (state: ProfileSelectionState<TSeat> | undefined, action: { type: string; payload?: unknown }) => ProfileSelectionState<TSeat>
 }
 
-// Which profile each seat last picked — always local, never part of the shared App Group roster
+// Which profile each seat last picked - always local, never part of the shared App Group roster
 // (this package's own profiles slice, see profilesSlice.ts): who's selected on THIS device is
 // naturally a per-app, per-device thing, not something a sibling @tastic game should see or
 // influence. Five @tastic games (AirHockey, BoxHockey, Pong, LightCycles, Snake) each hand-rolled
-// an identical Record<Seat, string | null> reducer before this factory existed — same duplication
+// an identical Record<Seat, string | null> reducer before this factory existed - same duplication
 // createProfileExtensionSlice generalized away for per-profile extensions, this is that shape for
 // per-seat selection instead.
 //
 // `namespace` prefixes every action type (e.g. 'profileSelection/loadout/select') so an app with
-// more than one independent seat-selection concern never collides between them — same convention
+// more than one independent seat-selection concern never collides between them - same convention
 // createProfileExtensionSlice's own namespace argument follows.
 //
 // Unlike createProfileExtensionSlice, the seat set can't be derived from TSeat alone (types don't
-// exist at runtime), so callers pass their own `defaultState` — the same literal object (e.g.
+// exist at runtime), so callers pass their own `defaultState` - the same literal object (e.g.
 // `{ 1: null, 2: null }`) each app already declares as its own `defaultProfileSelectionState`
 // constant today. `clearProfile` walks that state's own keys rather than assuming any particular
 // seat count, so it reproduces the 5 apps' current two-seat behavior without hardcoding "1"/"2".
 //
-// `mountKey` defaults to 'profileSelection' — the literal key every current consumer (AirHockey,
+// `mountKey` defaults to 'profileSelection' - the literal key every current consumer (AirHockey,
 // BoxHockey, Pong, LightCycles, Snake) already mounts this reducer under in its own
 // combineReducers({...}) call (e.g. `combineReducers({ ..., profileSelection })`). It has to be
 // passed explicitly rather than inferred, since redux-persist's REHYDRATE payload is keyed by
 // whatever name the app's own root reducer happens to use, which this factory has no way to see
-// from inside its own reducer function — only worth overriding if some future consumer ever mounts
+// from inside its own reducer function - only worth overriding if some future consumer ever mounts
 // this under a different key. Note `namespace` above is a different thing: it's the app's own name
 // (e.g. 'airhockey', 'boxhockey'), used only to prefix action types, not the mount key.
 //
@@ -56,6 +56,15 @@ export interface ProfileSelectionSlice<TSeat extends string | number> {
 // after any profilesActions.setAll (initial reconcile, onRemoteChange), since a sibling app can
 // delete a profile without this app's own deleteProfile ever running. It returns the same state
 // object when nothing changes, so dispatching it on every foreground resume costs no re-render.
+//
+// One profile is never on two seats. `select` picking a profile another seat already has swaps
+// the two: that seat takes this seat's previous pick (a profile, or null for guest), the same rule
+// as @tastic/input's assignSeatScheme. A picker's takenProfileId only hides the other seat's
+// profile while both seats are on screen, so without the swap a 1 Player pick of seat 2's saved
+// profile left both seats on it, and every later 2 Player round recorded a win and a loss for that
+// one profile. A host showing per-seat state tied to the selection (a profile's color override)
+// should reset it for both seats when a pick swaps. REHYDRATE also drops any duplicate saved before
+// this rule existed, keeping the profile on the first seat.
 export function createProfileSelectionSlice<TSeat extends string | number>(namespace: string, defaultState: ProfileSelectionState<TSeat>, mountKey = 'profileSelection'): ProfileSelectionSlice<TSeat> {
   const select = createActionCreator<SelectProfilePayload<TSeat>>(`profileSelection/${namespace}/select`)
   const clearProfile = createActionCreator<string>(`profileSelection/${namespace}/clearProfile`)
@@ -64,16 +73,35 @@ export function createProfileSelectionSlice<TSeat extends string | number>(names
   function reducer(state: ProfileSelectionState<TSeat> = defaultState, action: { type: string; payload?: unknown }): ProfileSelectionState<TSeat> {
     // redux-persist's own default stateReconciler (autoMergeLevel1) HARD-REPLACES this slice's
     // entire persisted sub-state on rehydration rather than backfilling missing fields (confirmed
-    // against autoMergeLevel1's actual source: `newState[key] = inboundState[key]`, not a merge) —
+    // against autoMergeLevel1's actual source: `newState[key] = inboundState[key]`, not a merge) -
     // so a device with a blob persisted before a new seat existed would otherwise rehydrate with
     // that seat's key missing entirely, and every consumer indexes into it (`state[seat]`) with no
     // fallback. Spreading `defaultState` first, then the incoming persisted value, backfills exactly
-    // that gap — the same pattern createSeatColorsSlice's own REHYDRATE case already uses.
+    // that gap - the same pattern createSeatColorsSlice's own REHYDRATE case already uses.
     if (action.type === REHYDRATE) {
       const persisted = (action.payload as Record<string, Partial<ProfileSelectionState<TSeat>>> | undefined)?.[mountKey]
-      return { ...defaultState, ...state, ...persisted }
+      const merged = { ...defaultState, ...state, ...persisted }
+      const seen = new Set<string>()
+      for (const seat of Object.keys(merged) as TSeat[]) {
+        const profileId = merged[seat]
+        if (profileId === null) continue
+        if (seen.has(profileId)) merged[seat] = null
+        else seen.add(profileId)
+      }
+      return merged
+    }
+    if (select.match(action)) {
+      const { profileId, seat } = action.payload
+      const previous = state[seat] ?? null
+      const next = { ...state, [seat]: profileId } as ProfileSelectionState<TSeat>
+      if (profileId !== null) {
+        // Object.keys yields strings, so a numeric seat compares as a string.
+        for (const other of Object.keys(state) as TSeat[]) {
+          if (String(other) !== String(seat) && state[other] === profileId) next[other] = previous === profileId ? null : previous
+        }
+      }
+      return next
     }
-    if (select.match(action)) return { ...state, [action.payload.seat]: action.payload.profileId } as ProfileSelectionState<TSeat>
     if (clearProfile.match(action)) {
       const next = { ...state }
       for (const seat of Object.keys(state) as TSeat[]) {

package/src/redux/resolveInitialProfiles.ts

@@ -1,23 +1,27 @@
-import { isSharedProfileStoreAvailable, loadSharedProfiles, saveSharedProfiles } from '../sharedProfileStore'
+import { isSharedProfileStoreAvailable, readSharedProfiles, saveSharedProfiles } from '../sharedProfileStore'
 import { Profile } from '../types'
 
 // Resolves the roster an app should start with, given whatever it already had saved in its own
-// local fallback storage (however that app stores it — this never touches AsyncStorage itself,
-// only the shared App Group store via loadSharedProfiles/saveSharedProfiles). Every @tastic game
+// local fallback storage (however that app stores it - this never touches AsyncStorage itself,
+// only the shared App Group store via readSharedProfiles/saveSharedProfiles). Every @tastic game
 // hand-rolled an identical version of this exact decision inline in its own useProfiles.tsx; this
 // is that logic, extracted verbatim.
 //
 // - Shared store unavailable (Android/web, or an iOS build that hasn't run `expo prebuild` since
 //   the entitlement was added): `localFallback` IS the roster, verbatim.
+// - Shared store available, but its roster couldn't be read (readSharedProfiles' null):
+//   `localFallback`, and nothing is written. Seeding here would overwrite every other app's
+//   profiles with this app's local snapshot.
 // - Shared store available, and genuinely empty: either a first launch, or the first time THIS
-//   app has synced since the App Group entitlement was added — seed it from `localFallback` (so
+//   app has synced since the App Group entitlement was added - seed it from `localFallback` (so
 //   an upgrading user's own profiles don't just vanish), and mirror that seed to the shared store
 //   (fire-and-forget; a failed seed write just means the next successful write catches up).
 // - Shared store available and non-empty: shared always wins over a stale local snapshot, never
-//   merged with it — avoids resurrecting a profile that was deleted from another app.
+//   merged with it - avoids resurrecting a profile that was deleted from another app.
 export async function resolveInitialProfiles(groupId: string, localFallback: Profile[]): Promise<Profile[]> {
   if (!isSharedProfileStoreAvailable) return localFallback
-  const shared = await loadSharedProfiles(groupId)
+  const shared = await readSharedProfiles(groupId)
+  if (shared === null) return localFallback
   if (shared.length === 0 && localFallback.length > 0) {
     saveSharedProfiles(groupId, localFallback).catch(() => {})
     return localFallback

package/src/redux/seatColorsSlice.ts

@@ -1,7 +1,7 @@
 import { ActionCreator, createActionCreator } from './createActionCreator'
 
 // redux-persist's own REHYDRATE action-type constant, inlined as a literal rather than taking a
-// dependency on the package itself — this factory otherwise has no opinion on whether the
+// dependency on the package itself - this factory otherwise has no opinion on whether the
 // consuming app uses redux-persist at all, and the string itself is a long-stable part of
 // redux-persist's own public contract (unchanged across every major version). See the reducer's
 // own REHYDRATE case below for why this needs handling at all.
@@ -38,9 +38,9 @@ export interface SeatColorsSlice<TSeat extends string | number> {
 // never fight over one value: a guest seat's own last pick, the CPU seat's own last pick, and a
 // manual recolor/clash-swap override landing on a seat that currently has a profile selected (null
 // meaning "no override, track that profile's own saved color live"). Four @tastic games (AirHockey,
-// BoxHockey, LightCycles, Pong) each hand-rolled an identical dedicated seatColorsSlice.ts — same
+// BoxHockey, LightCycles, Pong) each hand-rolled an identical dedicated seatColorsSlice.ts - same
 // three fields, same createSlice-based reducer, differing only in their own seat type's name
-// (Player) and default-color constants — before this factory existed; this is that shape,
+// (Player) and default-color constants - before this factory existed; this is that shape,
 // generalized over the seat type exactly like createProfileSelectionSlice generalized per-seat
 // profile selection.
 //
@@ -48,25 +48,25 @@ export interface SeatColorsSlice<TSeat extends string | number> {
 // alongside a dozen unrelated persisted settings (wrapEdges, cpuDifficulty, speedTier, ...) rather
 // than in a standalone slice of their own. There's no separate `seatColors` sub-state there for this
 // factory's reducer to own without restructuring gameSlice's top-level shape to nest these three
-// fields under their own key first — a real state-shape migration (and a redux-persist rehydration
+// fields under their own key first - a real state-shape migration (and a redux-persist rehydration
 // concern, see gameSlice's own REHYDRATE extraReducer), not a drop-in swap. This factory
 // intentionally targets the standalone-slice shape the other four apps already have; Snake staying
 // hand-rolled inside gameSlice is a deliberate scope call for this pass, not an oversight.
 //
 // `namespace` prefixes every action type (e.g. 'seatColors/loadout/setLastGuestColor') so an app
-// with more than one independent seat-colors concern never collides between them — same convention
+// with more than one independent seat-colors concern never collides between them - same convention
 // createProfileSelectionSlice's and createProfileExtensionSlice's own namespace arguments follow.
 //
 // Unlike createProfileExtensionSlice, the seat set can't be derived from TSeat alone (types don't
-// exist at runtime), so callers pass their own `defaultState` — same reasoning, and the same
+// exist at runtime), so callers pass their own `defaultState` - same reasoning, and the same
 // {1: ..., 2: ...}-shaped literal each app already declares as its own defaultSeatColorsState
 // constant today, as createProfileSelectionSlice's own defaultState parameter.
 //
-// `mountKey` defaults to 'seatColors' — the literal key every current consumer (AirHockey,
+// `mountKey` defaults to 'seatColors' - the literal key every current consumer (AirHockey,
 // BoxHockey, Pong) already mounts this reducer under in its own combineReducers({...}) call (e.g.
 // `combineReducers({ ..., seatColors })`). It has to be passed explicitly rather than inferred,
 // since redux-persist's REHYDRATE payload is keyed by whatever name the app's own root reducer
-// happens to use, which this factory has no way to see from inside its own reducer function — only
+// happens to use, which this factory has no way to see from inside its own reducer function - only
 // worth overriding if some future consumer ever mounts this under a different key.
 export function createSeatColorsSlice<TSeat extends string | number>(namespace: string, defaultState: SeatColorsState<TSeat>, mountKey = 'seatColors'): SeatColorsSlice<TSeat> {
   const setLastCpuColor = createActionCreator<string>(`seatColors/${namespace}/setLastCpuColor`)
@@ -76,11 +76,11 @@ export function createSeatColorsSlice<TSeat extends string | number>(namespace:
   function reducer(state: SeatColorsState<TSeat> = defaultState, action: { type: string; payload?: unknown }): SeatColorsState<TSeat> {
     // redux-persist's own default stateReconciler (autoMergeLevel1) HARD-REPLACES this slice's
     // entire persisted sub-state on rehydration rather than backfilling missing fields (confirmed
-    // against autoMergeLevel1's actual source: `newState[key] = inboundState[key]`, not a merge) —
+    // against autoMergeLevel1's actual source: `newState[key] = inboundState[key]`, not a merge) -
     // so a device with a blob persisted before `profileOverride` existed would otherwise rehydrate
     // with `state.profileOverride === undefined`, and every consumer indexes into it (`profileOverride[seat]`)
     // with no fallback, throwing. Spreading `defaultState` first, then the incoming persisted
-    // value, backfills exactly that gap — the same pattern Snake's own hand-rolled `gameSlice.ts`
+    // value, backfills exactly that gap - the same pattern Snake's own hand-rolled `gameSlice.ts`
     // already uses for its equivalent (non-factory) fields via its own REHYDRATE extraReducer.
     if (action.type === REHYDRATE) {
       const persisted = (action.payload as Record<string, Partial<SeatColorsState<TSeat>>> | undefined)?.[mountKey]

package/src/redux/useSharedProfilesSync.ts

@@ -1,23 +1,24 @@
 import { useCallback, useEffect, useRef } from 'react'
 import { AppState } from 'react-native'
 
-import { isSharedProfileStoreAvailable, loadSharedProfiles, saveSharedProfiles } from '../sharedProfileStore'
+import { isSharedProfileStoreAvailable, readSharedProfiles, saveSharedProfiles } from '../sharedProfileStore'
 import { Profile } from '../types'
 
 export interface UseSharedProfilesSyncOptions {
   groupId: string
-  // Called with a freshly-read shared roster whenever the app returns to the foreground — the
+  // Called with a freshly-read shared roster whenever the app returns to the foreground - the
   // shared store has no cross-process change notification, so this is what catches "edited a
   // profile in a different @tastic app, then switched back to this one." Skipped while a
-  // syncToShared write is still in flight (see pendingWriteRef below), and never called at all
-  // when the shared store isn't available.
+  // syncToShared write is still in flight (see pendingWriteRef below), skipped when the read fails
+  // (a failed read is not an empty roster, see readSharedProfiles), and never called at all when
+  // the shared store isn't available.
   onRemoteChange: (profiles: Profile[]) => void
 }
 
 export interface UseSharedProfilesSyncResult {
   // Call right after applying a roster change locally (dispatching profilesActions.setAll/add/
   // update/remove) to mirror it to the shared store. No-ops when the shared store isn't available
-  // — the caller is responsible for its own local persistence in that case, same as before this
+  // - the caller is responsible for its own local persistence in that case, same as before this
   // hook existed. Fire-and-forget: never throws, never awaited by this hook itself.
   syncToShared: (next: Profile[]) => void
 }
@@ -25,16 +26,16 @@ export interface UseSharedProfilesSyncResult {
 // Bundles the two things every @tastic game needs around the shared App Group roster once
 // `profiles` lives in its own Redux store: mirroring local writes out to the shared store, and
 // picking up remote writes a sibling app made while this one was backgrounded. Deliberately
-// separate from resolveInitialProfiles — that one's for the one-time initial load, this one's for
+// separate from resolveInitialProfiles - that one's for the one-time initial load, this one's for
 // the app's whole lifetime after that.
 export function useSharedProfilesSync({ groupId, onRemoteChange }: UseSharedProfilesSyncOptions): UseSharedProfilesSyncResult {
-  // True for the duration of an in-flight syncToShared write — the foreground-refresh effect below
+  // True for the duration of an in-flight syncToShared write - the foreground-refresh effect below
   // skips a refresh while this is true, rather than risk reading back a pre-write snapshot and
   // handing the caller an onRemoteChange that reverts the write still landing. A ref, not state:
   // read from inside the AppState listener's closure, which is only created once per subscription
   // and would otherwise see whatever this was at mount time, forever.
   const pendingWriteRef = useRef(false)
-  // Same reasoning, for onRemoteChange itself — an app typically passes an inline callback that
+  // Same reasoning, for onRemoteChange itself - an app typically passes an inline callback that
   // closes over its own latest dispatch/state, so the listener must always call the current one,
   // not whichever was in scope when the effect below first subscribed.
   const onRemoteChangeRef = useRef(onRemoteChange)
@@ -47,8 +48,8 @@ export function useSharedProfilesSync({ groupId, onRemoteChange }: UseSharedProf
     let cancelled = false
     const sub = AppState.addEventListener('change', (next) => {
       if (next !== 'active' || pendingWriteRef.current) return
-      loadSharedProfiles(groupId).then((shared) => {
-        if (!cancelled) onRemoteChangeRef.current(shared)
+      readSharedProfiles(groupId).then((shared) => {
+        if (!cancelled && shared !== null) onRemoteChangeRef.current(shared)
       })
     })
     return () => {

package/src/seatColorClash.ts

@@ -0,0 +1,13 @@
+// Seat 2's color, moved off seat 1's when the two resolve to the same color. Each seat's color
+// comes from its own source (a selected profile's saved color, or a remembered guest/CPU color, see
+// createSeatColorsSlice), and picking a profile has no swap step the way a manual recolor does, so
+// a profile saved as the other seat's color would otherwise give both seats the same color. On a
+// clash, seat 2 takes seat 1's default color, or seat 2's default when seat 1 is already on its own
+// default. Colors compare case-insensitively. The result is for display, not for persisting: call
+// it wherever the two seats' colors are resolved, so a guest's or the CPU's remembered color is
+// left alone.
+export function avoidSeatColorClash(p1Color: string, p2Color: string, defaults: readonly [p1Default: string, p2Default: string]): string {
+  if (p2Color.toLowerCase() !== p1Color.toLowerCase()) return p2Color
+  const [p1Default, p2Default] = defaults
+  return p2Color.toLowerCase() === p1Default.toLowerCase() ? p2Default : p1Default
+}

package/src/sharedProfileStore.ts

@@ -6,7 +6,7 @@ interface NativeTasticProfile {
   setSharedJSON(groupId: string, key: string, value: string): Promise<void>
 }
 
-// Lazily/optionally resolved — this package has no hard dependency on expo-modules-core (it's a
+// Lazily/optionally resolved - this package has no hard dependency on expo-modules-core (it's a
 // peer, provided by whatever Expo app consumes it), and the native module itself only registers on
 // iOS (see ios/TasticProfileModule.swift and expo-module.config.json's "apple"-only platform list).
 // Guarding both the require and the lookup means Android/web, and an iOS build that hasn't run
@@ -22,35 +22,50 @@ try {
 
 const PROFILES_KEY = 'sharedProfiles'
 
-// True once at module load — a consuming app uses this to decide whether to fall back to its own
+// True once at module load - a consuming app uses this to decide whether to fall back to its own
 // local-only storage for the base roster too (see this package's README's App Group section).
 export const isSharedProfileStoreAvailable = native !== null
 
-// Reads the shared base-identity roster out of a given App Group suite. Always resolves to an
-// array, never null/throws — an unavailable store, a missing/empty blob, and a corrupt blob all
-// read the same as "nothing shared yet." Entries that fail isValidProfile are dropped individually
+// Reads the shared base-identity roster out of a given App Group suite, telling a failed read
+// apart from an empty roster. Resolves to [] when nothing has been shared yet (a missing/empty
+// blob) or the store is unavailable, and to null when the store is there but its roster couldn't
+// be read: the native call threw, the blob isn't JSON or isn't an array, or it held entries and
+// none of them were valid. Never throws. Entries that fail isValidProfile are dropped individually
 // rather than invalidating the whole roster, since the base fields validated here are the ONLY
-// thing this store is a source of truth for — a host app's own extension fields (a control scheme,
+// thing this store is a source of truth for - a host app's own extension fields (a control scheme,
 // anything else) never travel through it at all; see the README for the base/extension split this
 // is meant to be used with.
-export async function loadSharedProfiles(groupId: string): Promise<Profile[]> {
+//
+// A caller that replaces its roster with what it reads, or writes the roster back afterward, must
+// skip a null: taken as an empty roster, a failed read empties the app's roster, and its next
+// write then deletes every profile from the shared store, for every app in the group.
+export async function readSharedProfiles(groupId: string): Promise<Profile[] | null> {
   if (!native) return []
   let json: string | null = null
   try {
     json = await native.getSharedJSON(groupId, PROFILES_KEY)
   } catch {
-    return []
+    return null
   }
   if (!json) return []
   try {
     const parsed: unknown = JSON.parse(json)
-    return Array.isArray(parsed) ? parsed.filter(isValidProfile) : []
+    if (!Array.isArray(parsed)) return null
+    const profiles = parsed.filter(isValidProfile)
+    return parsed.length > 0 && profiles.length === 0 ? null : profiles
   } catch {
-    return []
+    return null
   }
 }
 
-// Overwrites the entire shared roster — same whole-blob-write discipline a host app's own
+// readSharedProfiles with a failed read flattened to []: always resolves to an array, never
+// null/throws. Kept unchanged for apps that call it directly; prefer readSharedProfiles anywhere a
+// read can replace the roster or lead to a write (see its doc above).
+export async function loadSharedProfiles(groupId: string): Promise<Profile[]> {
+  return (await readSharedProfiles(groupId)) ?? []
+}
+
+// Overwrites the entire shared roster - same whole-blob-write discipline a host app's own
 // AsyncStorage-backed profile store already uses, not an incremental per-profile update. A write
 // failure (store unavailable, or some other native error) is swallowed rather than thrown: the
 // caller's own local state is already the source of truth for what just changed, and this is a
@@ -60,6 +75,6 @@ export async function saveSharedProfiles(groupId: string, profiles: Profile[]):
   try {
     await native.setSharedJSON(groupId, PROFILES_KEY, JSON.stringify(profiles))
   } catch {
-    // Best-effort — see doc comment above.
+    // Best-effort - see doc comment above.
   }
 }

package/src/types.ts

@@ -1,13 +1,13 @@
 // A saved player identity: just enough for a picker/roster UI to show and let someone select "who
-// am I this round" — deliberately nothing else. An app that needs more (a key/control scheme, a
+// am I this round" - deliberately nothing else. An app that needs more (a key/control scheme, a
 // stats bucket, anything else keyed by profile id) extends this shape on its own, in its own
 // storage layer, and structural typing carries it straight through every component here that only
-// ever reads these five fields — no wrapper or adapter needed on the app's side.
+// ever reads these five fields - no wrapper or adapter needed on the app's side.
 export interface Profile {
   id: string
   name: string
   color: string
-  // User-typed identity mark shown on a seat's own color trigger and in the profile picker/roster —
+  // User-typed identity mark shown on a seat's own color trigger and in the profile picker/roster -
   // one emoji, or up to MAX_TAG_LENGTH plain characters (see profilesValidation.ts's isValidTag).
   // Can be empty (no tag yet), which just falls back to a generic icon wherever it's shown.
   tag: string