@tastic/profile 0.4.0 → 0.7.0

package/README.md

@@ -53,7 +53,17 @@ see its own doc comment for why that component is generic over your own `Profile
 - **`ProfilesManager`** — the roster screen itself: create/rename/recolor/retag/delete, editing
   inline in the row you tap, with a destructive-delete confirmation. No navigation of its own (no
   router, no back button) — a host app renders this as a routed screen's body and supplies its own
-  persistence via `profiles`/`onCreate`/`onSave`/`onDelete`.
+  persistence via `profiles`/`onCreate`/`onSave`/`onDelete`. `onCreate`/`onSave` both take a
+  `ProfileEditPatch` (`{ name, color, tag }`) — exported from this package's own public API (it was
+  a private, unexported interface inside `ProfilesManager.tsx` until `ProfilesScreen` below needed
+  to reference it from its own props).
+- **`ProfilesScreen`** — the routed-screen shell around `ProfilesManager`: the container `View`,
+  theme-derived background/foreground, a back button, and the commit-pending-edit-before-navigate
+  composition every app in the fleet used to hand-roll on its own around `ProfilesManager` (see
+  "Routed screens: `ProfilesScreen`" below). Same `ProfileEditPatch`-shaped
+  `profiles`/`defaultColor`/`onCreate`/`onSave`/`onDelete` as `ProfilesManager` itself, plus
+  `onBack`. Owns its own `ProfilesManagerHandle` ref internally — there's no `ref` prop here, since
+  nothing outside it needs one anymore.
 - **`loadSharedProfiles` / `saveSharedProfiles` / `isSharedProfileStoreAvailable`** — an *optional*
   cross-app roster, shared between multiple apps of yours via a native iOS App Group (same Apple
   Developer Team, same `"com.apple.security.application-groups"` entitlement value on every
@@ -88,13 +98,71 @@ see its own doc comment for why that component is generic over your own `Profile
   { "expo": { "ios": { "entitlements": { "com.apple.security.application-groups": ["group.com.yourteam.yourgames"] } } } }
   ```
 
+### Routed screens: `ProfilesScreen`
+
+`ProfilesScreen` is the routed-screen shell every app in the fleet was hand-rolling on its own
+around `ProfilesManager`: a container `View`, theme-derived bg/fg, a `headerLeft` back button, and
+the two-line `managerRef.current?.commitPendingEdit(); onBack()` composition every app's own
+back-button handler used to write out by hand (see `ProfilesManager`'s own `commitPendingEdit` doc
+above for why that flush matters on a router that doesn't genuinely unmount a popped screen). It
+owns that ref itself — there's no `ref` prop on `ProfilesScreen`, since nothing outside it needs
+one any more.
+
+Same `profiles`/`defaultColor`/`onCreate`/`onSave`/`onDelete` props as `ProfilesManager` — still
+`ProfileEditPatch`-shaped, still deliberately not widened to your own richer `CreateProfileInput`;
+compose any extra required fields (a key/control scheme, whatever's specific to your game) in your
+own closure at the call site, exactly as you already would calling `ProfilesManager` directly —
+plus `onBack`. `fg`/`fgMuted`/`bg`/`cardBg`/`titleVariant`/`colorPreview` are all independently
+optional and forward straight through to the internal `ProfilesManager` (`bg` is new here —
+`ProfilesManager` itself has no `bg`, since it doesn't own a container `View` of its own).
+
+A whole routed screen, wired to your own store, is usually this small:
+
+```tsx
+// app/profiles.tsx
+import { defaultColors } from '@rific/auto-paper'
+import { ProfilesScreen } from '@tastic/profile'
+import { router } from 'expo-router'
+
+import { useGameStats } from '@/hooks/useGameStats'
+import { useProfiles } from '@/hooks/useProfiles'
+
+export default function Profiles() {
+  const { profiles, createProfile, updateProfile, deleteProfile } = useProfiles()
+  // Only for wiring onDelete below — clears a deleted profile's own stats record so it doesn't
+  // stick around as an orphan once the profile itself is gone.
+  const { removeProfileStats } = useGameStats()
+
+  return (
+    <ProfilesScreen
+      profiles={profiles}
+      defaultColor={defaultColors[0].value}
+      onCreate={(patch) => createProfile(patch)}
+      onSave={(id, patch) => updateProfile(id, patch)}
+      onDelete={(id) => {
+        deleteProfile(id)
+        removeProfileStats(id)
+      }}
+      onBack={() => router.back()}
+    />
+  )
+}
+```
+
+`useProfiles`/`useGameStats` are your own app's hooks, not exports of this package — `profiles` is
+whatever `Profile[]` (or your own extended shape) you already keep in Redux/context/state, and
+`createProfile`/`updateProfile`/`deleteProfile` are however you already persist it. `onBack` can be
+anything with no arguments — `router.back()`, a `safeBack()`-style helper that no-ops with no back
+stack behind it, `navigation.goBack()` — `ProfilesScreen` only ever calls it after flushing any
+in-progress inline edit first.
+
 ### Redux helpers for the shared roster
 
 The cross-app-roster sketch above is a pattern every `@tastic` game was hand-rolling on its own
 (a roster reducer, a per-profile extension table, the initial-load decision, a foreground-resync
-listener). These four pieces are that logic extracted into reusable, Redux-shaped building blocks —
-plain TypeScript, no dependency on `redux`/`react-redux` themselves, so a host app plugs the
-reducer(s) into whatever store it already has:
+listener, a per-seat selection reducer). These five pieces are that logic extracted into reusable,
+Redux-shaped building blocks — plain TypeScript, no dependency on `redux`/`react-redux` themselves,
+so a host app plugs the reducer(s) into whatever store it already has:
 
 - **`profilesActions` / `profilesReducer` / `createProfileRecord`** — the base roster as a reducer:
   `add`/`update`/`remove`/`setAll` actions, plus `createProfileRecord(input)` to mint a complete
@@ -113,30 +181,70 @@ reducer(s) into whatever store it already has:
   change to mirror it out, and `onRemoteChange` fires with a freshly-loaded roster whenever the app
   returns to the foreground (skipped while a `syncToShared` write is still in flight, so a remote
   refresh can't clobber a write that hasn't landed yet).
+- **`createProfileSelectionSlice<TSeat>(namespace, defaultState)`** — a factory for the *other*
+  per-seat piece of state: which profile id each seat currently has selected (parallel to
+  `createProfileExtensionSlice` above, but keyed by seat instead of by profile id). Returns a
+  `{ actions: { select, clearProfile }, reducer }` pair over a plain `Record<TSeat, string | null>`.
+  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.
+  `{ 1: null, 2: null }`) every app already declares today. `select({ seat, profileId })` sets one
+  seat's selection directly; `clearProfile(profileId)` walks every seat and nulls out any that
+  currently points at that id — call it when a profile is deleted so no seat is left referencing a
+  ghost id. Always local, like the guest/CPU/override colors below — never part of the shared
+  App Group roster, since who's selected on *this* device is naturally per-app, per-device state.
 
-## Install
+## Per-seat color persistence
 
-```bash
-npm install @tastic/profile
+A loadout/lobby screen's color for a given seat is never just "the selected profile's saved
+color" — a seat can be a guest (no profile selected), a CPU opponent, or a profile the player
+manually recolored for a clash-swap without touching the profile itself. Every `@tastic` game
+(AirHockey, BoxHockey, Pong, LightCycles, Snake) ends up needing the same three cooperating pieces
+of state to cover all three cases. This is the established pattern every game should follow — it
+was previously undocumented at the package level, which is exactly why two of the five apps
+(AirHockey, Snake) didn't pick up the third piece below until after they'd already shipped without
+it.
+
+- **`lastGuestColor`** — a `Record<Seat, string>`: what a seat's color was the last time it was a
+  guest (no profile selected). Written only when a guest seat's color changes; a profile-selected
+  seat never reads or writes it.
+- **`lastCpuColor`** — the same idea for the CPU slot, as a single remembered `string` rather than a
+  per-seat record (a CPU opponent only ever occupies one fixed seat in every shipped game so far).
+- **`profileOverride`** — a `Record<Seat, string | null>`: a manual recolor or clash-swap landing on
+  a seat that currently has a profile selected. `null` means "no override — track the profile's own
+  saved color live." Cleared only when that seat's own profile selection genuinely changes, never by
+  merely leaving and returning to the screen.
+
+None of these three are exports of this package today. `lastGuestColor`/`lastCpuColor` predate it
+entirely, and `profileOverride` is still hand-rolled per app — typically alongside
+`createProfileSelectionSlice`'s own selection state, in the same seat-scoped slice (see e.g.
+BoxHockey's `src/redux/seatColorsSlice.ts`) or folded into the app's own `gameSlice.ts` when there's
+no dedicated slice to put it in (see Snake's `src/redux/gameSlice.ts`). This section exists so a new
+app's author reads the convention here first, rather than hand-rolling something that quietly can't
+interop with the rest of the fleet.
+
+The resolution order at a loadout/lobby screen, for one seat:
+
+```ts
+const color = profile
+  ? (profileOverride[seat] ?? profile.color) // profile selected: override wins, else the profile's own color
+  : isCpu
+    ? lastCpuColor // CPU slot: its own remembered color
+    : lastGuestColor[seat] // guest seat: that seat's own remembered color
 ```
 
-Published to the public npm registry via tag-based CI (OIDC trusted publishing — see
-`npm run release:patch`/`:minor`/`:major`); no local linking needed for normal use.
+`lastGuestColor`/`lastCpuColor` are only ever consulted when no profile is selected for that seat at
+all — a profile-selected seat's guest/CPU memory is neither read nor overwritten while it's active,
+so switching a seat back to "guest" later still recalls whatever guest color it had before a profile
+was ever selected there.
 
-To develop against a local change before it's published, use `yalc` instead:
+## Install
 
 ```bash
-cd react-native-game-profile
-npm run build
-yalc publish
-
-cd ../your-game
-yalc add @tastic/profile
-npm install
+npm install @tastic/profile
 ```
 
-Re-run `npm run build && yalc push` from this package after any change to propagate it to every
-linked consumer at once.
+Published to the public npm registry via tag-based CI (OIDC trusted publishing — see
+`npm run release:patch`/`:minor`/`:major`).
 
 ## Peer dependencies
 

package/dist/index.d.mts

@@ -35,7 +35,7 @@ interface ProfilePickerProps<P extends Profile> {
 }
 declare function ProfilePicker<P extends Profile>({ idPrefix, host, profiles, selectedId, takenId, color, dark, align: alignOverride, guestLabel, nullLabel, nullIcon, onSelect, onManage }: ProfilePickerProps<P>): react.JSX.Element;
 
-type MD3TextVariant = 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'labelLarge' | 'labelMedium' | 'labelSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall';
+type MD3TextVariant$1 = 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'labelLarge' | 'labelMedium' | 'labelSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall';
 interface ProfileEditPatch {
     name: string;
     color: string;
@@ -55,11 +55,28 @@ interface ProfilesManagerProps {
     fg?: string;
     fgMuted?: string;
     cardBg?: string;
-    titleVariant?: MD3TextVariant;
+    titleVariant?: MD3TextVariant$1;
     colorPreview?: (hex: string) => string;
 }
 declare function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref, fg: fgOverride, fgMuted: fgMutedOverride, cardBg: cardBgOverride, titleVariant, colorPreview }: ProfilesManagerProps): react.JSX.Element;
 
+type MD3TextVariant = 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'labelLarge' | 'labelMedium' | 'labelSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall';
+interface ProfilesScreenProps {
+    profiles: Profile[];
+    defaultColor: string;
+    onCreate: (patch: ProfileEditPatch) => void;
+    onSave: (id: string, patch: ProfileEditPatch) => void;
+    onDelete: (id: string) => void;
+    onBack: () => void;
+    fg?: string;
+    fgMuted?: string;
+    bg?: string;
+    cardBg?: string;
+    titleVariant?: MD3TextVariant;
+    colorPreview?: (hex: string) => string;
+}
+declare function ProfilesScreen({ profiles, defaultColor, onCreate, onSave, onDelete, onBack, fg: fgOverride, fgMuted, bg: bgOverride, cardBg, titleVariant, colorPreview }: ProfilesScreenProps): react.JSX.Element;
+
 declare const MAX_PROFILE_NAME_LENGTH = 20;
 declare const MAX_TAG_LENGTH = 3;
 declare function isValidTag(value: unknown): value is string;
@@ -93,6 +110,24 @@ interface ProfileExtensionSlice<TExtension> {
 }
 declare function createProfileExtensionSlice<TExtension>(namespace: string): ProfileExtensionSlice<TExtension>;
 
+interface SelectProfilePayload<TSeat> {
+    profileId: string | null;
+    seat: TSeat;
+}
+interface ProfileSelectionActions<TSeat> {
+    clearProfile: ActionCreator<string>;
+    select: ActionCreator<SelectProfilePayload<TSeat>>;
+}
+type ProfileSelectionState<TSeat extends string | number> = Record<TSeat, string | null>;
+interface ProfileSelectionSlice<TSeat extends string | number> {
+    actions: ProfileSelectionActions<TSeat>;
+    reducer: (state: ProfileSelectionState<TSeat> | undefined, action: {
+        type: string;
+        payload?: unknown;
+    }) => ProfileSelectionState<TSeat>;
+}
+declare function createProfileSelectionSlice<TSeat extends string | number>(namespace: string, defaultState: ProfileSelectionState<TSeat>, mountKey?: string): ProfileSelectionSlice<TSeat>;
+
 interface UpdateProfilePayload {
     id: string;
     patch: Partial<Pick<Profile, 'name' | 'color' | 'tag'>>;
@@ -115,6 +150,33 @@ declare function createProfileRecord(input: CreateProfileInput): Profile;
 
 declare function resolveInitialProfiles(groupId: string, localFallback: Profile[]): Promise<Profile[]>;
 
+interface SetLastGuestColorPayload<TSeat> {
+    color: string;
+    seat: TSeat;
+}
+interface SetProfileOverridePayload<TSeat> {
+    color: string | null;
+    seat: TSeat;
+}
+interface SeatColorsActions<TSeat> {
+    setLastCpuColor: ActionCreator<string>;
+    setLastGuestColor: ActionCreator<SetLastGuestColorPayload<TSeat>>;
+    setProfileOverride: ActionCreator<SetProfileOverridePayload<TSeat>>;
+}
+type SeatColorsState<TSeat extends string | number> = {
+    lastCpuColor: string;
+    lastGuestColor: Record<TSeat, string>;
+    profileOverride: Record<TSeat, string | null>;
+};
+interface SeatColorsSlice<TSeat extends string | number> {
+    actions: SeatColorsActions<TSeat>;
+    reducer: (state: SeatColorsState<TSeat> | undefined, action: {
+        type: string;
+        payload?: unknown;
+    }) => SeatColorsState<TSeat>;
+}
+declare function createSeatColorsSlice<TSeat extends string | number>(namespace: string, defaultState: SeatColorsState<TSeat>, mountKey?: string): SeatColorsSlice<TSeat>;
+
 interface UseSharedProfilesSyncOptions {
     groupId: string;
     onRemoteChange: (profiles: Profile[]) => void;
@@ -128,4 +190,4 @@ declare const isSharedProfileStoreAvailable: boolean;
 declare function loadSharedProfiles(groupId: string): Promise<Profile[]>;
 declare function saveSharedProfiles(groupId: string, profiles: Profile[]): Promise<void>;
 
-export { type CreateProfileInput, MAX_PROFILE_NAME_LENGTH, MAX_TAG_LENGTH, type Profile, ProfileChip, type ProfileExtensionActions, type ProfileExtensionSlice, type ProfileExtensionState, ProfilePicker, ProfilesManager, type ProfilesManagerHandle, type ProfilesManagerProps, type SetProfileExtensionPayload, type UpdateProfilePayload, type UseSharedProfilesSyncOptions, type UseSharedProfilesSyncResult, createProfileExtensionSlice, createProfileRecord, isSharedProfileStoreAvailable, isValidProfile, isValidTag, loadSharedProfiles, profilesActions, profilesReducer, resolveInitialProfiles, saveSharedProfiles, useSharedProfilesSync };
+export { type CreateProfileInput, MAX_PROFILE_NAME_LENGTH, MAX_TAG_LENGTH, type Profile, ProfileChip, type ProfileEditPatch, type ProfileExtensionActions, type ProfileExtensionSlice, type ProfileExtensionState, ProfilePicker, type ProfileSelectionActions, type ProfileSelectionSlice, type ProfileSelectionState, ProfilesManager, type ProfilesManagerHandle, type ProfilesManagerProps, ProfilesScreen, type ProfilesScreenProps, type SeatColorsActions, type SeatColorsSlice, type SeatColorsState, type SelectProfilePayload, type SetLastGuestColorPayload, type SetProfileExtensionPayload, type SetProfileOverridePayload, type UpdateProfilePayload, type UseSharedProfilesSyncOptions, type UseSharedProfilesSyncResult, createProfileExtensionSlice, createProfileRecord, createProfileSelectionSlice, createSeatColorsSlice, isSharedProfileStoreAvailable, isValidProfile, isValidTag, loadSharedProfiles, profilesActions, profilesReducer, resolveInitialProfiles, saveSharedProfiles, useSharedProfilesSync };

package/dist/index.d.ts

@@ -35,7 +35,7 @@ interface ProfilePickerProps<P extends Profile> {
 }
 declare function ProfilePicker<P extends Profile>({ idPrefix, host, profiles, selectedId, takenId, color, dark, align: alignOverride, guestLabel, nullLabel, nullIcon, onSelect, onManage }: ProfilePickerProps<P>): react.JSX.Element;
 
-type MD3TextVariant = 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'labelLarge' | 'labelMedium' | 'labelSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall';
+type MD3TextVariant$1 = 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'labelLarge' | 'labelMedium' | 'labelSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall';
 interface ProfileEditPatch {
     name: string;
     color: string;
@@ -55,11 +55,28 @@ interface ProfilesManagerProps {
     fg?: string;
     fgMuted?: string;
     cardBg?: string;
-    titleVariant?: MD3TextVariant;
+    titleVariant?: MD3TextVariant$1;
     colorPreview?: (hex: string) => string;
 }
 declare function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref, fg: fgOverride, fgMuted: fgMutedOverride, cardBg: cardBgOverride, titleVariant, colorPreview }: ProfilesManagerProps): react.JSX.Element;
 
+type MD3TextVariant = 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'labelLarge' | 'labelMedium' | 'labelSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall';
+interface ProfilesScreenProps {
+    profiles: Profile[];
+    defaultColor: string;
+    onCreate: (patch: ProfileEditPatch) => void;
+    onSave: (id: string, patch: ProfileEditPatch) => void;
+    onDelete: (id: string) => void;
+    onBack: () => void;
+    fg?: string;
+    fgMuted?: string;
+    bg?: string;
+    cardBg?: string;
+    titleVariant?: MD3TextVariant;
+    colorPreview?: (hex: string) => string;
+}
+declare function ProfilesScreen({ profiles, defaultColor, onCreate, onSave, onDelete, onBack, fg: fgOverride, fgMuted, bg: bgOverride, cardBg, titleVariant, colorPreview }: ProfilesScreenProps): react.JSX.Element;
+
 declare const MAX_PROFILE_NAME_LENGTH = 20;
 declare const MAX_TAG_LENGTH = 3;
 declare function isValidTag(value: unknown): value is string;
@@ -93,6 +110,24 @@ interface ProfileExtensionSlice<TExtension> {
 }
 declare function createProfileExtensionSlice<TExtension>(namespace: string): ProfileExtensionSlice<TExtension>;
 
+interface SelectProfilePayload<TSeat> {
+    profileId: string | null;
+    seat: TSeat;
+}
+interface ProfileSelectionActions<TSeat> {
+    clearProfile: ActionCreator<string>;
+    select: ActionCreator<SelectProfilePayload<TSeat>>;
+}
+type ProfileSelectionState<TSeat extends string | number> = Record<TSeat, string | null>;
+interface ProfileSelectionSlice<TSeat extends string | number> {
+    actions: ProfileSelectionActions<TSeat>;
+    reducer: (state: ProfileSelectionState<TSeat> | undefined, action: {
+        type: string;
+        payload?: unknown;
+    }) => ProfileSelectionState<TSeat>;
+}
+declare function createProfileSelectionSlice<TSeat extends string | number>(namespace: string, defaultState: ProfileSelectionState<TSeat>, mountKey?: string): ProfileSelectionSlice<TSeat>;
+
 interface UpdateProfilePayload {
     id: string;
     patch: Partial<Pick<Profile, 'name' | 'color' | 'tag'>>;
@@ -115,6 +150,33 @@ declare function createProfileRecord(input: CreateProfileInput): Profile;
 
 declare function resolveInitialProfiles(groupId: string, localFallback: Profile[]): Promise<Profile[]>;
 
+interface SetLastGuestColorPayload<TSeat> {
+    color: string;
+    seat: TSeat;
+}
+interface SetProfileOverridePayload<TSeat> {
+    color: string | null;
+    seat: TSeat;
+}
+interface SeatColorsActions<TSeat> {
+    setLastCpuColor: ActionCreator<string>;
+    setLastGuestColor: ActionCreator<SetLastGuestColorPayload<TSeat>>;
+    setProfileOverride: ActionCreator<SetProfileOverridePayload<TSeat>>;
+}
+type SeatColorsState<TSeat extends string | number> = {
+    lastCpuColor: string;
+    lastGuestColor: Record<TSeat, string>;
+    profileOverride: Record<TSeat, string | null>;
+};
+interface SeatColorsSlice<TSeat extends string | number> {
+    actions: SeatColorsActions<TSeat>;
+    reducer: (state: SeatColorsState<TSeat> | undefined, action: {
+        type: string;
+        payload?: unknown;
+    }) => SeatColorsState<TSeat>;
+}
+declare function createSeatColorsSlice<TSeat extends string | number>(namespace: string, defaultState: SeatColorsState<TSeat>, mountKey?: string): SeatColorsSlice<TSeat>;
+
 interface UseSharedProfilesSyncOptions {
     groupId: string;
     onRemoteChange: (profiles: Profile[]) => void;
@@ -128,4 +190,4 @@ declare const isSharedProfileStoreAvailable: boolean;
 declare function loadSharedProfiles(groupId: string): Promise<Profile[]>;
 declare function saveSharedProfiles(groupId: string, profiles: Profile[]): Promise<void>;
 
-export { type CreateProfileInput, MAX_PROFILE_NAME_LENGTH, MAX_TAG_LENGTH, type Profile, ProfileChip, type ProfileExtensionActions, type ProfileExtensionSlice, type ProfileExtensionState, ProfilePicker, ProfilesManager, type ProfilesManagerHandle, type ProfilesManagerProps, type SetProfileExtensionPayload, type UpdateProfilePayload, type UseSharedProfilesSyncOptions, type UseSharedProfilesSyncResult, createProfileExtensionSlice, createProfileRecord, isSharedProfileStoreAvailable, isValidProfile, isValidTag, loadSharedProfiles, profilesActions, profilesReducer, resolveInitialProfiles, saveSharedProfiles, useSharedProfilesSync };
+export { type CreateProfileInput, MAX_PROFILE_NAME_LENGTH, MAX_TAG_LENGTH, type Profile, ProfileChip, type ProfileEditPatch, type ProfileExtensionActions, type ProfileExtensionSlice, type ProfileExtensionState, ProfilePicker, type ProfileSelectionActions, type ProfileSelectionSlice, type ProfileSelectionState, ProfilesManager, type ProfilesManagerHandle, type ProfilesManagerProps, ProfilesScreen, type ProfilesScreenProps, type SeatColorsActions, type SeatColorsSlice, type SeatColorsState, type SelectProfilePayload, type SetLastGuestColorPayload, type SetProfileExtensionPayload, type SetProfileOverridePayload, type UpdateProfilePayload, type UseSharedProfilesSyncOptions, type UseSharedProfilesSyncResult, createProfileExtensionSlice, createProfileRecord, createProfileSelectionSlice, createSeatColorsSlice, isSharedProfileStoreAvailable, isValidProfile, isValidTag, loadSharedProfiles, profilesActions, profilesReducer, resolveInitialProfiles, saveSharedProfiles, useSharedProfilesSync };

package/dist/index.js

@@ -25,8 +25,11 @@ __export(index_exports, {
   ProfileChip: () => ProfileChip,
   ProfilePicker: () => ProfilePicker,
   ProfilesManager: () => ProfilesManager,
+  ProfilesScreen: () => ProfilesScreen,
   createProfileExtensionSlice: () => createProfileExtensionSlice,
   createProfileRecord: () => createProfileRecord,
+  createProfileSelectionSlice: () => createProfileSelectionSlice,
+  createSeatColorsSlice: () => createSeatColorsSlice,
   isSharedProfileStoreAvailable: () => isSharedProfileStoreAvailable,
   isValidProfile: () => isValidProfile,
   isValidTag: () => isValidTag,
@@ -514,6 +517,29 @@ var styles3 = import_react_native3.StyleSheet.create({
   }
 });
 
+// src/ProfilesScreen.tsx
+var import_auto_paper4 = require("@rific/auto-paper");
+var import_feedback_press3 = require("@rific/feedback-press");
+var import_react3 = require("react");
+var import_react_native4 = require("react-native");
+var import_jsx_runtime4 = require("react/jsx-runtime");
+function ProfilesScreen({ profiles, defaultColor, onCreate, onSave, onDelete, onBack, fg: fgOverride, fgMuted, bg: bgOverride, cardBg, titleVariant, colorPreview }) {
+  const { dark } = (0, import_auto_paper4.useAutoPaperTheme)();
+  const managerRef = (0, import_react3.useRef)(null);
+  const fg = fgOverride ?? (dark ? "#FFFFFF" : "#000000");
+  const bg = bgOverride ?? (dark ? "#000000" : "#FFFFFF");
+  const handleBack = () => {
+    managerRef.current?.commitPendingEdit();
+    onBack();
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_react_native4.View, { style: [styles4.container, { backgroundColor: bg }], children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(ProfilesManager, { ref: managerRef, profiles, defaultColor, onCreate, onSave, onDelete, fg, fgMuted, cardBg, titleVariant, colorPreview, headerLeft: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_feedback_press3.IconButton, { icon: "arrow-left", iconColor: fg, size: 24, onPress: handleBack, accessibilityLabel: "Back" }) }) });
+}
+var styles4 = import_react_native4.StyleSheet.create({
+  container: {
+    flex: 1
+  }
+});
+
 // src/redux/createActionCreator.ts
 function createActionCreator(type) {
   const creator = ((payload) => ({ payload, type }));
@@ -539,6 +565,29 @@ function createProfileExtensionSlice(namespace) {
   return { actions: { remove: remove2, set }, reducer };
 }
 
+// src/redux/profileSelectionSlice.ts
+var REHYDRATE = "persist/REHYDRATE";
+function createProfileSelectionSlice(namespace, defaultState, mountKey = "profileSelection") {
+  const select = createActionCreator(`profileSelection/${namespace}/select`);
+  const clearProfile = createActionCreator(`profileSelection/${namespace}/clearProfile`);
+  function reducer(state = defaultState, action) {
+    if (action.type === REHYDRATE) {
+      const persisted = action.payload?.[mountKey];
+      return { ...defaultState, ...state, ...persisted };
+    }
+    if (select.match(action)) return { ...state, [action.payload.seat]: action.payload.profileId };
+    if (clearProfile.match(action)) {
+      const next = { ...state };
+      for (const seat of Object.keys(state)) {
+        if (next[seat] === action.payload) next[seat] = null;
+      }
+      return next;
+    }
+    return state;
+  }
+  return { actions: { clearProfile, select }, reducer };
+}
+
 // src/redux/profilesSlice.ts
 var setAll = createActionCreator("profiles/setAll");
 var add = createActionCreator("profiles/add");
@@ -609,19 +658,38 @@ async function resolveInitialProfiles(groupId, localFallback) {
   return shared;
 }
 
+// src/redux/seatColorsSlice.ts
+var REHYDRATE2 = "persist/REHYDRATE";
+function createSeatColorsSlice(namespace, defaultState, mountKey = "seatColors") {
+  const setLastCpuColor = createActionCreator(`seatColors/${namespace}/setLastCpuColor`);
+  const setLastGuestColor = createActionCreator(`seatColors/${namespace}/setLastGuestColor`);
+  const setProfileOverride = createActionCreator(`seatColors/${namespace}/setProfileOverride`);
+  function reducer(state = defaultState, action) {
+    if (action.type === REHYDRATE2) {
+      const persisted = action.payload?.[mountKey];
+      return { ...defaultState, ...state, ...persisted };
+    }
+    if (setLastCpuColor.match(action)) return { ...state, lastCpuColor: action.payload };
+    if (setLastGuestColor.match(action)) return { ...state, lastGuestColor: { ...state.lastGuestColor, [action.payload.seat]: action.payload.color } };
+    if (setProfileOverride.match(action)) return { ...state, profileOverride: { ...state.profileOverride, [action.payload.seat]: action.payload.color } };
+    return state;
+  }
+  return { actions: { setLastCpuColor, setLastGuestColor, setProfileOverride }, reducer };
+}
+
 // src/redux/useSharedProfilesSync.ts
-var import_react3 = require("react");
-var import_react_native4 = require("react-native");
+var import_react4 = require("react");
+var import_react_native5 = require("react-native");
 function useSharedProfilesSync({ groupId, onRemoteChange }) {
-  const pendingWriteRef = (0, import_react3.useRef)(false);
-  const onRemoteChangeRef = (0, import_react3.useRef)(onRemoteChange);
-  (0, import_react3.useEffect)(() => {
+  const pendingWriteRef = (0, import_react4.useRef)(false);
+  const onRemoteChangeRef = (0, import_react4.useRef)(onRemoteChange);
+  (0, import_react4.useEffect)(() => {
     onRemoteChangeRef.current = onRemoteChange;
   }, [onRemoteChange]);
-  (0, import_react3.useEffect)(() => {
+  (0, import_react4.useEffect)(() => {
     if (!isSharedProfileStoreAvailable) return;
     let cancelled = false;
-    const sub = import_react_native4.AppState.addEventListener("change", (next) => {
+    const sub = import_react_native5.AppState.addEventListener("change", (next) => {
       if (next !== "active" || pendingWriteRef.current) return;
       loadSharedProfiles(groupId).then((shared) => {
         if (!cancelled) onRemoteChangeRef.current(shared);
@@ -632,7 +700,7 @@ function useSharedProfilesSync({ groupId, onRemoteChange }) {
       sub.remove();
     };
   }, [groupId]);
-  const syncToShared = (0, import_react3.useCallback)(
+  const syncToShared = (0, import_react4.useCallback)(
     (next) => {
       if (!isSharedProfileStoreAvailable) return;
       pendingWriteRef.current = true;
@@ -652,8 +720,11 @@ function useSharedProfilesSync({ groupId, onRemoteChange }) {
   ProfileChip,
   ProfilePicker,
   ProfilesManager,
+  ProfilesScreen,
   createProfileExtensionSlice,
   createProfileRecord,
+  createProfileSelectionSlice,
+  createSeatColorsSlice,
   isSharedProfileStoreAvailable,
   isValidProfile,
   isValidTag,

package/dist/index.mjs

@@ -480,6 +480,29 @@ var styles3 = StyleSheet3.create({
   }
 });
 
+// src/ProfilesScreen.tsx
+import { useAutoPaperTheme as useAutoPaperTheme2 } from "@rific/auto-paper";
+import { IconButton } from "@rific/feedback-press";
+import { useRef as useRef2 } from "react";
+import { StyleSheet as StyleSheet4, View as View4 } from "react-native";
+import { jsx as jsx4 } from "react/jsx-runtime";
+function ProfilesScreen({ profiles, defaultColor, onCreate, onSave, onDelete, onBack, fg: fgOverride, fgMuted, bg: bgOverride, cardBg, titleVariant, colorPreview }) {
+  const { dark } = useAutoPaperTheme2();
+  const managerRef = useRef2(null);
+  const fg = fgOverride ?? (dark ? "#FFFFFF" : "#000000");
+  const bg = bgOverride ?? (dark ? "#000000" : "#FFFFFF");
+  const handleBack = () => {
+    managerRef.current?.commitPendingEdit();
+    onBack();
+  };
+  return /* @__PURE__ */ jsx4(View4, { style: [styles4.container, { backgroundColor: bg }], children: /* @__PURE__ */ jsx4(ProfilesManager, { ref: managerRef, profiles, defaultColor, onCreate, onSave, onDelete, fg, fgMuted, cardBg, titleVariant, colorPreview, headerLeft: /* @__PURE__ */ jsx4(IconButton, { icon: "arrow-left", iconColor: fg, size: 24, onPress: handleBack, accessibilityLabel: "Back" }) }) });
+}
+var styles4 = StyleSheet4.create({
+  container: {
+    flex: 1
+  }
+});
+
 // src/redux/createActionCreator.ts
 function createActionCreator(type) {
   const creator = ((payload) => ({ payload, type }));
@@ -505,6 +528,29 @@ function createProfileExtensionSlice(namespace) {
   return { actions: { remove: remove2, set }, reducer };
 }
 
+// src/redux/profileSelectionSlice.ts
+var REHYDRATE = "persist/REHYDRATE";
+function createProfileSelectionSlice(namespace, defaultState, mountKey = "profileSelection") {
+  const select = createActionCreator(`profileSelection/${namespace}/select`);
+  const clearProfile = createActionCreator(`profileSelection/${namespace}/clearProfile`);
+  function reducer(state = defaultState, action) {
+    if (action.type === REHYDRATE) {
+      const persisted = action.payload?.[mountKey];
+      return { ...defaultState, ...state, ...persisted };
+    }
+    if (select.match(action)) return { ...state, [action.payload.seat]: action.payload.profileId };
+    if (clearProfile.match(action)) {
+      const next = { ...state };
+      for (const seat of Object.keys(state)) {
+        if (next[seat] === action.payload) next[seat] = null;
+      }
+      return next;
+    }
+    return state;
+  }
+  return { actions: { clearProfile, select }, reducer };
+}
+
 // src/redux/profilesSlice.ts
 var setAll = createActionCreator("profiles/setAll");
 var add = createActionCreator("profiles/add");
@@ -575,12 +621,31 @@ async function resolveInitialProfiles(groupId, localFallback) {
   return shared;
 }
 
+// src/redux/seatColorsSlice.ts
+var REHYDRATE2 = "persist/REHYDRATE";
+function createSeatColorsSlice(namespace, defaultState, mountKey = "seatColors") {
+  const setLastCpuColor = createActionCreator(`seatColors/${namespace}/setLastCpuColor`);
+  const setLastGuestColor = createActionCreator(`seatColors/${namespace}/setLastGuestColor`);
+  const setProfileOverride = createActionCreator(`seatColors/${namespace}/setProfileOverride`);
+  function reducer(state = defaultState, action) {
+    if (action.type === REHYDRATE2) {
+      const persisted = action.payload?.[mountKey];
+      return { ...defaultState, ...state, ...persisted };
+    }
+    if (setLastCpuColor.match(action)) return { ...state, lastCpuColor: action.payload };
+    if (setLastGuestColor.match(action)) return { ...state, lastGuestColor: { ...state.lastGuestColor, [action.payload.seat]: action.payload.color } };
+    if (setProfileOverride.match(action)) return { ...state, profileOverride: { ...state.profileOverride, [action.payload.seat]: action.payload.color } };
+    return state;
+  }
+  return { actions: { setLastCpuColor, setLastGuestColor, setProfileOverride }, reducer };
+}
+
 // src/redux/useSharedProfilesSync.ts
-import { useCallback as useCallback2, useEffect as useEffect2, useRef as useRef2 } from "react";
+import { useCallback as useCallback2, useEffect as useEffect2, useRef as useRef3 } from "react";
 import { AppState } from "react-native";
 function useSharedProfilesSync({ groupId, onRemoteChange }) {
-  const pendingWriteRef = useRef2(false);
-  const onRemoteChangeRef = useRef2(onRemoteChange);
+  const pendingWriteRef = useRef3(false);
+  const onRemoteChangeRef = useRef3(onRemoteChange);
   useEffect2(() => {
     onRemoteChangeRef.current = onRemoteChange;
   }, [onRemoteChange]);
@@ -617,8 +682,11 @@ export {
   ProfileChip,
   ProfilePicker,
   ProfilesManager,
+  ProfilesScreen,
   createProfileExtensionSlice,
   createProfileRecord,
+  createProfileSelectionSlice,
+  createSeatColorsSlice,
   isSharedProfileStoreAvailable,
   isValidProfile,
   isValidTag,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastic/profile",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Player profile identity for local-multiplayer React Native games — a saved name/color/tag a player selects per seat, with a picker, an inline-editable roster screen, and a reusable identity badge, deliberately blind to any app-specific fields (control scheme, stats) an app layers on top",
   "keywords": [
     "react-native",
@@ -63,14 +63,14 @@
   "prettier": "@infinitetoken/eslint-config/prettier",
   "devDependencies": {
     "@infinitetoken/eslint-config": "0.2.0",
-    "@infinitetoken/jest-config": "^0.2.4",
-    "@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/focus-chain": "^0.4.7",
     "@rific/toaster": "^0.6.3",
-    "@tastic/core": "^0.2.0",
+    "@tastic/core": "^0.8.0",
     "@tastic/hud": "^0.8.5",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",

package/src/ProfilesManager.tsx

@@ -21,7 +21,10 @@ const CHIP_SIZE = 40
 // as @tastic/hud's BaseStatsScreen does for its own identical titleVariant prop.
 type MD3TextVariant = 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'labelLarge' | 'labelMedium' | 'labelSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall'
 
-interface ProfileEditPatch {
+// Exported (not just used internally) so a host composing a screen around this component — e.g.
+// @tastic/profile's own ProfilesScreen — can reference this exact shape in its own onCreate/onSave
+// prop types without redeclaring it.
+export interface ProfileEditPatch {
   name: string
   color: string
   tag: string

package/src/ProfilesScreen.tsx

@@ -0,0 +1,83 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { IconButton } from '@rific/feedback-press'
+import { useRef } from 'react'
+import { StyleSheet, View } from 'react-native'
+
+import { ProfileEditPatch, ProfilesManager, ProfilesManagerHandle } from './ProfilesManager'
+import { Profile } from './types'
+
+// 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'
+
+export interface ProfilesScreenProps {
+  profiles: Profile[]
+  // 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.
+  defaultColor: string
+  // 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
+  // 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
+  // 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.
+  fg?: string
+  fgMuted?: string
+  bg?: string
+  cardBg?: string
+  titleVariant?: MD3TextVariant
+  colorPreview?: (hex: string) => string
+}
+
+// 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
+// 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 }: ProfilesScreenProps) {
+  const { dark } = useAutoPaperTheme()
+  // 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
+  // here (rather than left to ProfilesManager) so this component's own headerLeft IconButton and
+  // ProfilesManager's title always share the identical color.
+  const fg = fgOverride ?? (dark ? '#FFFFFF' : '#000000')
+  const bg = bgOverride ?? (dark ? '#000000' : '#FFFFFF')
+
+  // Folds in the exact 2-line composition every app hand-rolls today: a hardware back gesture or
+  // swipe-back unmounts ProfilesManager (which flushes on its own), but a host router that keeps a
+  // popped screen mounted-but-hidden instead of unmounting it (expo-router's web renderer) needs
+  // this explicit flush before navigating away, or an in-progress edit is silently lost.
+  const handleBack = () => {
+    managerRef.current?.commitPendingEdit()
+    onBack()
+  }
+
+  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} headerLeft={<IconButton icon='arrow-left' iconColor={fg} size={24} onPress={handleBack} accessibilityLabel='Back' />} />
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1
+  }
+})

package/src/index.ts

@@ -1,10 +1,13 @@
 export { ProfileChip } from './ProfileChip'
 export { ProfilePicker } from './ProfilePicker'
-export { ProfilesManager, type ProfilesManagerHandle, type ProfilesManagerProps } from './ProfilesManager'
+export { type ProfileEditPatch, ProfilesManager, type ProfilesManagerHandle, type ProfilesManagerProps } from './ProfilesManager'
+export { ProfilesScreen, type ProfilesScreenProps } from './ProfilesScreen'
 export { isValidProfile, isValidTag, MAX_PROFILE_NAME_LENGTH, MAX_TAG_LENGTH } from './profilesValidation'
 export { createProfileExtensionSlice, type ProfileExtensionActions, type ProfileExtensionSlice, type ProfileExtensionState, type SetProfileExtensionPayload } from './redux/profileExtensionSlice'
+export { createProfileSelectionSlice, type ProfileSelectionActions, type ProfileSelectionSlice, type ProfileSelectionState, type SelectProfilePayload } from './redux/profileSelectionSlice'
 export { type CreateProfileInput, createProfileRecord, profilesActions, profilesReducer, type UpdateProfilePayload } from './redux/profilesSlice'
 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 type { Profile } from './types'

package/src/redux/profileSelectionSlice.ts

@@ -0,0 +1,81 @@
+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
+// 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.
+const REHYDRATE = 'persist/REHYDRATE'
+
+export interface SelectProfilePayload<TSeat> {
+  profileId: string | null
+  seat: TSeat
+}
+
+export interface ProfileSelectionActions<TSeat> {
+  clearProfile: ActionCreator<string>
+  select: ActionCreator<SelectProfilePayload<TSeat>>
+}
+
+export type ProfileSelectionState<TSeat extends string | number> = Record<TSeat, string | null>
+
+export interface ProfileSelectionSlice<TSeat extends string | number> {
+  actions: ProfileSelectionActions<TSeat>
+  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
+// (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
+// 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
+// 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.
+// `{ 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,
+// 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
+// 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.
+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`)
+
+  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) —
+    // 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.
+    if (action.type === REHYDRATE) {
+      const persisted = (action.payload as Record<string, Partial<ProfileSelectionState<TSeat>>> | undefined)?.[mountKey]
+      return { ...defaultState, ...state, ...persisted }
+    }
+    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[]) {
+        if (next[seat] === action.payload) next[seat] = null
+      }
+      return next
+    }
+    return state
+  }
+
+  return { actions: { clearProfile, select }, reducer }
+}

package/src/redux/seatColorsSlice.ts

@@ -0,0 +1,96 @@
+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
+// 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.
+const REHYDRATE = 'persist/REHYDRATE'
+
+export interface SetLastGuestColorPayload<TSeat> {
+  color: string
+  seat: TSeat
+}
+
+export interface SetProfileOverridePayload<TSeat> {
+  color: string | null
+  seat: TSeat
+}
+
+export interface SeatColorsActions<TSeat> {
+  setLastCpuColor: ActionCreator<string>
+  setLastGuestColor: ActionCreator<SetLastGuestColorPayload<TSeat>>
+  setProfileOverride: ActionCreator<SetProfileOverridePayload<TSeat>>
+}
+
+export type SeatColorsState<TSeat extends string | number> = {
+  lastCpuColor: string
+  lastGuestColor: Record<TSeat, string>
+  profileOverride: Record<TSeat, string | null>
+}
+
+export interface SeatColorsSlice<TSeat extends string | number> {
+  actions: SeatColorsActions<TSeat>
+  reducer: (state: SeatColorsState<TSeat> | undefined, action: { type: string; payload?: unknown }) => SeatColorsState<TSeat>
+}
+
+// Which color a seat should show right now, remembered independently for three sources that must
+// 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
+// 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,
+// generalized over the seat type exactly like createProfileSelectionSlice generalized per-seat
+// profile selection.
+//
+// Snake has the same three fields too, but folded directly into its own catch-all gameSlice.ts
+// 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
+// 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
+// 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
+// {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,
+// 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
+// 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`)
+  const setLastGuestColor = createActionCreator<SetLastGuestColorPayload<TSeat>>(`seatColors/${namespace}/setLastGuestColor`)
+  const setProfileOverride = createActionCreator<SetProfileOverridePayload<TSeat>>(`seatColors/${namespace}/setProfileOverride`)
+
+  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) —
+    // 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`
+    // 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]
+      return { ...defaultState, ...state, ...persisted }
+    }
+    if (setLastCpuColor.match(action)) return { ...state, lastCpuColor: action.payload }
+    if (setLastGuestColor.match(action)) return { ...state, lastGuestColor: { ...state.lastGuestColor, [action.payload.seat]: action.payload.color } as Record<TSeat, string> }
+    if (setProfileOverride.match(action)) return { ...state, profileOverride: { ...state.profileOverride, [action.payload.seat]: action.payload.color } as Record<TSeat, string | null> }
+    return state
+  }
+
+  return { actions: { setLastCpuColor, setLastGuestColor, setProfileOverride }, reducer }
+}