@tastic/profile 0.11.0 → 0.12.0

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