@tastic/profile 0.3.7 → 0.4.0

package/README.md

@@ -67,7 +67,8 @@ see its own doc comment for why that component is generic over your own `Profile
   TypeScript type.
 
   ```ts
-  // App-side sketch — see BoxHockey's or LightCycles' own useProfiles.tsx for a full example.
+  // Conceptual sketch of the pattern — see "Redux helpers for the shared roster" below for a
+  // ready-made version of it.
   const GROUP_ID = 'group.com.yourteam.yourgames'
   const base = isSharedProfileStoreAvailable ? await loadSharedProfiles(GROUP_ID) : localBaseFallback
   const profiles = base.map((p) => ({ ...p, controlScheme: localExtensions[p.id]?.controlScheme ?? DEFAULT_CONTROL_SCHEME }))
@@ -87,9 +88,42 @@ 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"] } } } }
   ```
 
-## Install (local dev via yalc)
+### 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:
+
+- **`profilesActions` / `profilesReducer` / `createProfileRecord`** — the base roster as a reducer:
+  `add`/`update`/`remove`/`setAll` actions, plus `createProfileRecord(input)` to mint a complete
+  `Profile` (id + timestamps) ready to dispatch via `profilesActions.add`.
+- **`createProfileExtensionSlice<TExtension>(namespace)`** — a factory for a host app's own
+  per-profile extension fields (a control scheme, a key scheme, ...): returns a
+  `{ actions: { set, remove }, reducer }` pair over a plain `Record<profileId, TExtension>`,
+  namespaced so more than one extension slice in the same app never collides. Not auto-cleared when
+  `profilesReducer` removes a profile — an app already dispatches its own cleanup action(s) on
+  delete, so this stays a self-contained reducer rather than new cross-slice wiring.
+- **`resolveInitialProfiles(groupId, localFallback)`** — the one-time initial-load decision: shared
+  store unavailable → `localFallback` verbatim; shared store empty → seed it from `localFallback`;
+  otherwise the shared roster always wins over a possibly-stale local snapshot.
+- **`useSharedProfilesSync({ groupId, onRemoteChange })`** — keeps a Redux-backed roster in sync for
+  the rest of the app's lifetime: call the returned `syncToShared(next)` right after a local roster
+  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).
+
+## Install
 
-Not published to the public npm registry yet.
+```bash
+npm install @tastic/profile
+```
+
+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.
+
+To develop against a local change before it's published, use `yalc` instead:
 
 ```bash
 cd react-native-game-profile
@@ -109,5 +143,10 @@ linked consumer at once.
 `react`, `react-native`, `react-native-paper`, `react-native-safe-area-context`, `@rific/auto-paper`
 (`getContrastColor`, `useAutoPaperTheme`), `@rific/feedback-press` (`TouchableRipple`),
 `@rific/focus-chain` (`useFocusChain`), `@rific/toaster` (`useToast`), `@tastic/hud`
-(`InlineColorPicker`, `PopoverBody`, `PopoverHost`, `useAutoAlign`, `usePopoverHost`) — none of these
-are bundled, so use whatever versions your app already has.
+(`InlineColorPicker`, `PopoverBody`, `PopoverHost`, `useAutoAlign`, `usePopoverHost`), `@tastic/core`
+(a peer of `@tastic/hud` itself) — none of these are bundled, so use whatever versions your app
+already has.
+
+`expo-modules-core` is an *optional* peer — only resolved by `loadSharedProfiles`/`saveSharedProfiles`
+for the native App Group bridge described above; safe to omit entirely on an Android/web-only
+consumer.

package/dist/index.d.mts

@@ -35,6 +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';
 interface ProfileEditPatch {
     name: string;
     color: string;
@@ -51,16 +52,80 @@ interface ProfilesManagerProps {
     onDelete: (id: string) => void;
     headerLeft?: ReactNode;
     ref?: Ref<ProfilesManagerHandle>;
+    fg?: string;
+    fgMuted?: string;
+    cardBg?: string;
+    titleVariant?: MD3TextVariant;
+    colorPreview?: (hex: string) => string;
 }
-declare function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref }: ProfilesManagerProps): react.JSX.Element;
+declare function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref, fg: fgOverride, fgMuted: fgMutedOverride, cardBg: cardBgOverride, titleVariant, colorPreview }: ProfilesManagerProps): react.JSX.Element;
 
 declare const MAX_PROFILE_NAME_LENGTH = 20;
 declare const MAX_TAG_LENGTH = 3;
 declare function isValidTag(value: unknown): value is string;
 declare function isValidProfile(value: unknown): value is Profile;
 
+interface ReduxAction<P> {
+    payload: P;
+    type: string;
+}
+type ActionCreator<P> = ((payload: P) => ReduxAction<P>) & {
+    type: string;
+    match: (action: {
+        type: string;
+    }) => action is ReduxAction<P>;
+};
+
+interface SetProfileExtensionPayload<TExtension> {
+    extension: TExtension;
+    id: string;
+}
+interface ProfileExtensionActions<TExtension> {
+    remove: ActionCreator<string>;
+    set: ActionCreator<SetProfileExtensionPayload<TExtension>>;
+}
+type ProfileExtensionState<TExtension> = Record<string, TExtension>;
+interface ProfileExtensionSlice<TExtension> {
+    actions: ProfileExtensionActions<TExtension>;
+    reducer: (state: ProfileExtensionState<TExtension> | undefined, action: {
+        type: string;
+    }) => ProfileExtensionState<TExtension>;
+}
+declare function createProfileExtensionSlice<TExtension>(namespace: string): ProfileExtensionSlice<TExtension>;
+
+interface UpdateProfilePayload {
+    id: string;
+    patch: Partial<Pick<Profile, 'name' | 'color' | 'tag'>>;
+}
+declare const profilesActions: {
+    add: ActionCreator<Profile>;
+    remove: ActionCreator<string>;
+    setAll: ActionCreator<Profile[]>;
+    update: ActionCreator<UpdateProfilePayload>;
+};
+declare function profilesReducer(state: Profile[] | undefined, action: {
+    type: string;
+}): Profile[];
+interface CreateProfileInput {
+    name: string;
+    color: string;
+    tag: string;
+}
+declare function createProfileRecord(input: CreateProfileInput): Profile;
+
+declare function resolveInitialProfiles(groupId: string, localFallback: Profile[]): Promise<Profile[]>;
+
+interface UseSharedProfilesSyncOptions {
+    groupId: string;
+    onRemoteChange: (profiles: Profile[]) => void;
+}
+interface UseSharedProfilesSyncResult {
+    syncToShared: (next: Profile[]) => void;
+}
+declare function useSharedProfilesSync({ groupId, onRemoteChange }: UseSharedProfilesSyncOptions): UseSharedProfilesSyncResult;
+
 declare const isSharedProfileStoreAvailable: boolean;
 declare function loadSharedProfiles(groupId: string): Promise<Profile[]>;
 declare function saveSharedProfiles(groupId: string, profiles: Profile[]): Promise<void>;
 
-export { MAX_PROFILE_NAME_LENGTH, MAX_TAG_LENGTH, type Profile, ProfileChip, ProfilePicker, ProfilesManager, type ProfilesManagerHandle, type ProfilesManagerProps, isSharedProfileStoreAvailable, isValidProfile, isValidTag, loadSharedProfiles, saveSharedProfiles };
+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 };

package/dist/index.d.ts

@@ -35,6 +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';
 interface ProfileEditPatch {
     name: string;
     color: string;
@@ -51,16 +52,80 @@ interface ProfilesManagerProps {
     onDelete: (id: string) => void;
     headerLeft?: ReactNode;
     ref?: Ref<ProfilesManagerHandle>;
+    fg?: string;
+    fgMuted?: string;
+    cardBg?: string;
+    titleVariant?: MD3TextVariant;
+    colorPreview?: (hex: string) => string;
 }
-declare function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref }: ProfilesManagerProps): react.JSX.Element;
+declare function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref, fg: fgOverride, fgMuted: fgMutedOverride, cardBg: cardBgOverride, titleVariant, colorPreview }: ProfilesManagerProps): react.JSX.Element;
 
 declare const MAX_PROFILE_NAME_LENGTH = 20;
 declare const MAX_TAG_LENGTH = 3;
 declare function isValidTag(value: unknown): value is string;
 declare function isValidProfile(value: unknown): value is Profile;
 
+interface ReduxAction<P> {
+    payload: P;
+    type: string;
+}
+type ActionCreator<P> = ((payload: P) => ReduxAction<P>) & {
+    type: string;
+    match: (action: {
+        type: string;
+    }) => action is ReduxAction<P>;
+};
+
+interface SetProfileExtensionPayload<TExtension> {
+    extension: TExtension;
+    id: string;
+}
+interface ProfileExtensionActions<TExtension> {
+    remove: ActionCreator<string>;
+    set: ActionCreator<SetProfileExtensionPayload<TExtension>>;
+}
+type ProfileExtensionState<TExtension> = Record<string, TExtension>;
+interface ProfileExtensionSlice<TExtension> {
+    actions: ProfileExtensionActions<TExtension>;
+    reducer: (state: ProfileExtensionState<TExtension> | undefined, action: {
+        type: string;
+    }) => ProfileExtensionState<TExtension>;
+}
+declare function createProfileExtensionSlice<TExtension>(namespace: string): ProfileExtensionSlice<TExtension>;
+
+interface UpdateProfilePayload {
+    id: string;
+    patch: Partial<Pick<Profile, 'name' | 'color' | 'tag'>>;
+}
+declare const profilesActions: {
+    add: ActionCreator<Profile>;
+    remove: ActionCreator<string>;
+    setAll: ActionCreator<Profile[]>;
+    update: ActionCreator<UpdateProfilePayload>;
+};
+declare function profilesReducer(state: Profile[] | undefined, action: {
+    type: string;
+}): Profile[];
+interface CreateProfileInput {
+    name: string;
+    color: string;
+    tag: string;
+}
+declare function createProfileRecord(input: CreateProfileInput): Profile;
+
+declare function resolveInitialProfiles(groupId: string, localFallback: Profile[]): Promise<Profile[]>;
+
+interface UseSharedProfilesSyncOptions {
+    groupId: string;
+    onRemoteChange: (profiles: Profile[]) => void;
+}
+interface UseSharedProfilesSyncResult {
+    syncToShared: (next: Profile[]) => void;
+}
+declare function useSharedProfilesSync({ groupId, onRemoteChange }: UseSharedProfilesSyncOptions): UseSharedProfilesSyncResult;
+
 declare const isSharedProfileStoreAvailable: boolean;
 declare function loadSharedProfiles(groupId: string): Promise<Profile[]>;
 declare function saveSharedProfiles(groupId: string, profiles: Profile[]): Promise<void>;
 
-export { MAX_PROFILE_NAME_LENGTH, MAX_TAG_LENGTH, type Profile, ProfileChip, ProfilePicker, ProfilesManager, type ProfilesManagerHandle, type ProfilesManagerProps, isSharedProfileStoreAvailable, isValidProfile, isValidTag, loadSharedProfiles, saveSharedProfiles };
+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 };

package/dist/index.js

@@ -25,11 +25,17 @@ __export(index_exports, {
   ProfileChip: () => ProfileChip,
   ProfilePicker: () => ProfilePicker,
   ProfilesManager: () => ProfilesManager,
+  createProfileExtensionSlice: () => createProfileExtensionSlice,
+  createProfileRecord: () => createProfileRecord,
   isSharedProfileStoreAvailable: () => isSharedProfileStoreAvailable,
   isValidProfile: () => isValidProfile,
   isValidTag: () => isValidTag,
   loadSharedProfiles: () => loadSharedProfiles,
-  saveSharedProfiles: () => saveSharedProfiles
+  profilesActions: () => profilesActions,
+  profilesReducer: () => profilesReducer,
+  resolveInitialProfiles: () => resolveInitialProfiles,
+  saveSharedProfiles: () => saveSharedProfiles,
+  useSharedProfilesSync: () => useSharedProfilesSync
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -287,14 +293,14 @@ function deriveTag(name) {
   const trimmed = name.trim();
   return trimmed ? trimmed[0].toUpperCase() : "";
 }
-function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref }) {
+function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref, fg: fgOverride, fgMuted: fgMutedOverride, cardBg: cardBgOverride, titleVariant = "headlineSmall", colorPreview }) {
   const { dark, colors } = (0, import_auto_paper3.useAutoPaperTheme)();
   const insets = (0, import_react_native_safe_area_context.useSafeAreaInsets)();
   const { error: showErrorToast } = (0, import_toaster.useToast)();
   const host = (0, import_hud2.usePopoverHost)();
-  const fg = dark ? "#FFFFFF" : "#000000";
-  const fgMuted = dark ? "rgba(255,255,255,0.5)" : "rgba(0,0,0,0.5)";
-  const cardBg = dark ? "#111111" : "#F2F2F2";
+  const fg = fgOverride ?? (dark ? "#FFFFFF" : "#000000");
+  const fgMuted = fgMutedOverride ?? (dark ? "rgba(255,255,255,0.5)" : "rgba(0,0,0,0.5)");
+  const cardBg = cardBgOverride ?? (dark ? "#111111" : "#F2F2F2");
   const cardBorder = dark ? "rgba(255,255,255,0.2)" : "rgba(0,0,0,0.2)";
   const cancelBg = dark ? "#2A2A2A" : "#E0E0E0";
   const cancelFg = dark ? "#FFFFFF" : "#000000";
@@ -363,7 +369,7 @@ function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, h
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_jsx_runtime3.Fragment, { children: [
     /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_react_native3.View, { style: [styles3.header, { paddingTop: 8 + insets.top, paddingLeft: 8 + insets.left }], children: [
       headerLeft,
-      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react_native_paper3.Text, { variant: "displaySmall", style: [styles3.title, { color: fg }], children: "Profiles" })
+      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react_native_paper3.Text, { variant: titleVariant, style: [styles3.title, { color: fg }], children: "Profiles" })
     ] }),
     /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react_native3.KeyboardAvoidingView, { behavior: import_react_native3.Platform.OS === "ios" ? "padding" : void 0, style: styles3.keyboardAvoiding, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react_native3.ScrollView, { style: styles3.scrollView, contentContainerStyle: [styles3.content, { paddingBottom: 32 + insets.bottom }], showsVerticalScrollIndicator: false, keyboardShouldPersistTaps: "handled", children: rows.map((row) => {
       if (row.kind === "new") {
@@ -373,11 +379,11 @@ function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, h
             /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react_native_paper3.Text, { variant: "bodyLarge", style: { color: fg }, children: "New Profile" })
           ] }) }, "new");
         }
-        return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(EditRow, { draftName, onNameChange: handleNameChange, draftColor, onColorChange: setDraftColor, draftTag, onTagChange: handleTagChange, onSubmit: commitEdit, autoFocus: true, fgMuted, host, dark }, "new");
+        return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(EditRow, { draftName, onNameChange: handleNameChange, draftColor, onColorChange: setDraftColor, draftTag, onTagChange: handleTagChange, onSubmit: commitEdit, autoFocus: true, fgMuted, host, dark, colorPreview }, "new");
       }
       const { profile } = row;
       if (editingId === profile.id) {
-        return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(EditRow, { draftName, onNameChange: handleNameChange, draftColor, onColorChange: setDraftColor, draftTag, onTagChange: handleTagChange, onSubmit: commitEdit, onDelete: () => setConfirmDeleteId(profile.id), fgMuted, host, dark }, profile.id);
+        return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(EditRow, { draftName, onNameChange: handleNameChange, draftColor, onColorChange: setDraftColor, draftTag, onTagChange: handleTagChange, onSubmit: commitEdit, onDelete: () => setConfirmDeleteId(profile.id), fgMuted, host, dark, colorPreview }, profile.id);
       }
       return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_feedback_press2.TouchableRipple, { onPress: () => startEdit(profile), style: styles3.row, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_react_native3.View, { style: styles3.rowInner, children: [
         /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ProfileChip, { profile, size: CHIP_SIZE }),
@@ -397,7 +403,7 @@ function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, h
     ] }) }) })
   ] });
 }
-function EditRow({ draftName, onNameChange, draftColor, onColorChange, draftTag, onTagChange, onSubmit, onDelete, autoFocus, fgMuted, host, dark }) {
+function EditRow({ draftName, onNameChange, draftColor, onColorChange, draftTag, onTagChange, onSubmit, onDelete, autoFocus, fgMuted, host, dark, colorPreview }) {
   const register = (0, import_focus_chain.useFocusChain)();
   const tag = register();
   const name = register();
@@ -409,7 +415,7 @@ function EditRow({ draftName, onNameChange, draftColor, onColorChange, draftTag,
     if (host.openId === "color") tagFocusRef.current();
   }, [host.openId]);
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_react_native3.View, { style: styles3.editRow, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_hud2.InlineColorPicker, { id: "color", host, value: draftColor, onChange: onColorChange, tag: draftTag, dark }),
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_hud2.InlineColorPicker, { id: "color", host, value: draftColor, onChange: onColorChange, previewValue: colorPreview, tag: draftTag, dark }),
     /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react_native_paper3.TextInput, { ref: tag.ref, ...tag.props, value: draftTag, onChangeText: onTagChange, accessibilityLabel: "Tag", autoCapitalize: "characters", selectTextOnFocus: true, returnKeyType: "next", style: styles3.hiddenTagInput, pointerEvents: "none" }),
     /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react_native_paper3.TextInput, { ref: name.ref, ...name.props, onSubmitEditing: onSubmit, mode: "outlined", dense: true, value: draftName, onChangeText: onNameChange, maxLength: MAX_PROFILE_NAME_LENGTH, placeholder: "Name", autoFocus, returnKeyType: "done", style: styles3.nameInput }),
     onDelete && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_feedback_press2.TouchableRipple, { onPress: onDelete, style: styles3.iconButton, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react_native_paper3.Icon, { source: "trash-can-outline", size: 18, color: fgMuted }) })
@@ -432,6 +438,15 @@ var styles3 = import_react_native3.StyleSheet.create({
     gap: 4,
     paddingBottom: 8
   },
+  // 1x1 and fully transparent — there's nothing to see here on purpose (see EditRow's own comment
+  // above the field this styles). position: 'absolute' pulls it out of editRow's flex flow
+  // entirely, so it doesn't reserve a gap in the row the way a normal flex sibling would.
+  hiddenTagInput: {
+    height: 1,
+    opacity: 0,
+    position: "absolute",
+    width: 1
+  },
   iconButton: {
     alignItems: "center",
     borderRadius: 8,
@@ -493,21 +508,61 @@ var styles3 = import_react_native3.StyleSheet.create({
   scrollView: {
     flex: 1
   },
-  // 1x1 and fully transparent — there's nothing to see here on purpose (see EditRow's own comment
-  // above the field this styles). position: 'absolute' pulls it out of editRow's flex flow
-  // entirely, so it doesn't reserve a gap in the row the way a normal flex sibling would.
-  hiddenTagInput: {
-    height: 1,
-    opacity: 0,
-    position: "absolute",
-    width: 1
-  },
   title: {
     flexShrink: 1,
     fontWeight: "bold"
   }
 });
 
+// src/redux/createActionCreator.ts
+function createActionCreator(type) {
+  const creator = ((payload) => ({ payload, type }));
+  creator.type = type;
+  creator.match = (action) => action.type === type;
+  return creator;
+}
+
+// src/redux/profileExtensionSlice.ts
+function createProfileExtensionSlice(namespace) {
+  const set = createActionCreator(`profileExtension/${namespace}/set`);
+  const remove2 = createActionCreator(`profileExtension/${namespace}/remove`);
+  function reducer(state = {}, action) {
+    if (set.match(action)) return { ...state, [action.payload.id]: action.payload.extension };
+    if (remove2.match(action)) {
+      if (!(action.payload in state)) return state;
+      const next = { ...state };
+      delete next[action.payload];
+      return next;
+    }
+    return state;
+  }
+  return { actions: { remove: remove2, set }, reducer };
+}
+
+// src/redux/profilesSlice.ts
+var setAll = createActionCreator("profiles/setAll");
+var add = createActionCreator("profiles/add");
+var update = createActionCreator("profiles/update");
+var remove = createActionCreator("profiles/remove");
+var profilesActions = { add, remove, setAll, update };
+function profilesReducer(state = [], action) {
+  if (setAll.match(action)) return action.payload;
+  if (add.match(action)) return [...state, action.payload];
+  if (update.match(action)) {
+    const { id, patch } = action.payload;
+    return state.map((p) => p.id === id ? { ...p, ...patch, updatedAt: Date.now() } : p);
+  }
+  if (remove.match(action)) return state.filter((p) => p.id !== action.payload);
+  return state;
+}
+function generateProfileId() {
+  return `profile-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function createProfileRecord(input) {
+  const now = Date.now();
+  return { color: input.color, createdAt: now, id: generateProfileId(), name: input.name, tag: input.tag, updatedAt: now };
+}
+
 // src/sharedProfileStore.ts
 var native = null;
 try {
@@ -541,6 +596,55 @@ async function saveSharedProfiles(groupId, profiles) {
   } catch {
   }
 }
+
+// src/redux/resolveInitialProfiles.ts
+async function resolveInitialProfiles(groupId, localFallback) {
+  if (!isSharedProfileStoreAvailable) return localFallback;
+  const shared = await loadSharedProfiles(groupId);
+  if (shared.length === 0 && localFallback.length > 0) {
+    saveSharedProfiles(groupId, localFallback).catch(() => {
+    });
+    return localFallback;
+  }
+  return shared;
+}
+
+// src/redux/useSharedProfilesSync.ts
+var import_react3 = require("react");
+var import_react_native4 = 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)(() => {
+    onRemoteChangeRef.current = onRemoteChange;
+  }, [onRemoteChange]);
+  (0, import_react3.useEffect)(() => {
+    if (!isSharedProfileStoreAvailable) return;
+    let cancelled = false;
+    const sub = import_react_native4.AppState.addEventListener("change", (next) => {
+      if (next !== "active" || pendingWriteRef.current) return;
+      loadSharedProfiles(groupId).then((shared) => {
+        if (!cancelled) onRemoteChangeRef.current(shared);
+      });
+    });
+    return () => {
+      cancelled = true;
+      sub.remove();
+    };
+  }, [groupId]);
+  const syncToShared = (0, import_react3.useCallback)(
+    (next) => {
+      if (!isSharedProfileStoreAvailable) return;
+      pendingWriteRef.current = true;
+      saveSharedProfiles(groupId, next).catch(() => {
+      }).finally(() => {
+        pendingWriteRef.current = false;
+      });
+    },
+    [groupId]
+  );
+  return { syncToShared };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MAX_PROFILE_NAME_LENGTH,
@@ -548,9 +652,15 @@ async function saveSharedProfiles(groupId, profiles) {
   ProfileChip,
   ProfilePicker,
   ProfilesManager,
+  createProfileExtensionSlice,
+  createProfileRecord,
   isSharedProfileStoreAvailable,
   isValidProfile,
   isValidTag,
   loadSharedProfiles,
-  saveSharedProfiles
+  profilesActions,
+  profilesReducer,
+  resolveInitialProfiles,
+  saveSharedProfiles,
+  useSharedProfilesSync
 });

package/dist/index.mjs

@@ -259,14 +259,14 @@ function deriveTag(name) {
   const trimmed = name.trim();
   return trimmed ? trimmed[0].toUpperCase() : "";
 }
-function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref }) {
+function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref, fg: fgOverride, fgMuted: fgMutedOverride, cardBg: cardBgOverride, titleVariant = "headlineSmall", colorPreview }) {
   const { dark, colors } = useAutoPaperTheme();
   const insets = useSafeAreaInsets();
   const { error: showErrorToast } = useToast();
   const host = usePopoverHost();
-  const fg = dark ? "#FFFFFF" : "#000000";
-  const fgMuted = dark ? "rgba(255,255,255,0.5)" : "rgba(0,0,0,0.5)";
-  const cardBg = dark ? "#111111" : "#F2F2F2";
+  const fg = fgOverride ?? (dark ? "#FFFFFF" : "#000000");
+  const fgMuted = fgMutedOverride ?? (dark ? "rgba(255,255,255,0.5)" : "rgba(0,0,0,0.5)");
+  const cardBg = cardBgOverride ?? (dark ? "#111111" : "#F2F2F2");
   const cardBorder = dark ? "rgba(255,255,255,0.2)" : "rgba(0,0,0,0.2)";
   const cancelBg = dark ? "#2A2A2A" : "#E0E0E0";
   const cancelFg = dark ? "#FFFFFF" : "#000000";
@@ -335,7 +335,7 @@ function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, h
   return /* @__PURE__ */ jsxs2(Fragment2, { children: [
     /* @__PURE__ */ jsxs2(View3, { style: [styles3.header, { paddingTop: 8 + insets.top, paddingLeft: 8 + insets.left }], children: [
       headerLeft,
-      /* @__PURE__ */ jsx3(Text3, { variant: "displaySmall", style: [styles3.title, { color: fg }], children: "Profiles" })
+      /* @__PURE__ */ jsx3(Text3, { variant: titleVariant, style: [styles3.title, { color: fg }], children: "Profiles" })
     ] }),
     /* @__PURE__ */ jsx3(KeyboardAvoidingView, { behavior: Platform.OS === "ios" ? "padding" : void 0, style: styles3.keyboardAvoiding, children: /* @__PURE__ */ jsx3(ScrollView2, { style: styles3.scrollView, contentContainerStyle: [styles3.content, { paddingBottom: 32 + insets.bottom }], showsVerticalScrollIndicator: false, keyboardShouldPersistTaps: "handled", children: rows.map((row) => {
       if (row.kind === "new") {
@@ -345,11 +345,11 @@ function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, h
             /* @__PURE__ */ jsx3(Text3, { variant: "bodyLarge", style: { color: fg }, children: "New Profile" })
           ] }) }, "new");
         }
-        return /* @__PURE__ */ jsx3(EditRow, { draftName, onNameChange: handleNameChange, draftColor, onColorChange: setDraftColor, draftTag, onTagChange: handleTagChange, onSubmit: commitEdit, autoFocus: true, fgMuted, host, dark }, "new");
+        return /* @__PURE__ */ jsx3(EditRow, { draftName, onNameChange: handleNameChange, draftColor, onColorChange: setDraftColor, draftTag, onTagChange: handleTagChange, onSubmit: commitEdit, autoFocus: true, fgMuted, host, dark, colorPreview }, "new");
       }
       const { profile } = row;
       if (editingId === profile.id) {
-        return /* @__PURE__ */ jsx3(EditRow, { draftName, onNameChange: handleNameChange, draftColor, onColorChange: setDraftColor, draftTag, onTagChange: handleTagChange, onSubmit: commitEdit, onDelete: () => setConfirmDeleteId(profile.id), fgMuted, host, dark }, profile.id);
+        return /* @__PURE__ */ jsx3(EditRow, { draftName, onNameChange: handleNameChange, draftColor, onColorChange: setDraftColor, draftTag, onTagChange: handleTagChange, onSubmit: commitEdit, onDelete: () => setConfirmDeleteId(profile.id), fgMuted, host, dark, colorPreview }, profile.id);
       }
       return /* @__PURE__ */ jsx3(TouchableRipple2, { onPress: () => startEdit(profile), style: styles3.row, children: /* @__PURE__ */ jsxs2(View3, { style: styles3.rowInner, children: [
         /* @__PURE__ */ jsx3(ProfileChip, { profile, size: CHIP_SIZE }),
@@ -369,7 +369,7 @@ function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, h
     ] }) }) })
   ] });
 }
-function EditRow({ draftName, onNameChange, draftColor, onColorChange, draftTag, onTagChange, onSubmit, onDelete, autoFocus, fgMuted, host, dark }) {
+function EditRow({ draftName, onNameChange, draftColor, onColorChange, draftTag, onTagChange, onSubmit, onDelete, autoFocus, fgMuted, host, dark, colorPreview }) {
   const register = useFocusChain();
   const tag = register();
   const name = register();
@@ -381,7 +381,7 @@ function EditRow({ draftName, onNameChange, draftColor, onColorChange, draftTag,
     if (host.openId === "color") tagFocusRef.current();
   }, [host.openId]);
   return /* @__PURE__ */ jsxs2(View3, { style: styles3.editRow, children: [
-    /* @__PURE__ */ jsx3(InlineColorPicker, { id: "color", host, value: draftColor, onChange: onColorChange, tag: draftTag, dark }),
+    /* @__PURE__ */ jsx3(InlineColorPicker, { id: "color", host, value: draftColor, onChange: onColorChange, previewValue: colorPreview, tag: draftTag, dark }),
     /* @__PURE__ */ jsx3(TextInput, { ref: tag.ref, ...tag.props, value: draftTag, onChangeText: onTagChange, accessibilityLabel: "Tag", autoCapitalize: "characters", selectTextOnFocus: true, returnKeyType: "next", style: styles3.hiddenTagInput, pointerEvents: "none" }),
     /* @__PURE__ */ jsx3(TextInput, { ref: name.ref, ...name.props, onSubmitEditing: onSubmit, mode: "outlined", dense: true, value: draftName, onChangeText: onNameChange, maxLength: MAX_PROFILE_NAME_LENGTH, placeholder: "Name", autoFocus, returnKeyType: "done", style: styles3.nameInput }),
     onDelete && /* @__PURE__ */ jsx3(TouchableRipple2, { onPress: onDelete, style: styles3.iconButton, children: /* @__PURE__ */ jsx3(Icon3, { source: "trash-can-outline", size: 18, color: fgMuted }) })
@@ -404,6 +404,15 @@ var styles3 = StyleSheet3.create({
     gap: 4,
     paddingBottom: 8
   },
+  // 1x1 and fully transparent — there's nothing to see here on purpose (see EditRow's own comment
+  // above the field this styles). position: 'absolute' pulls it out of editRow's flex flow
+  // entirely, so it doesn't reserve a gap in the row the way a normal flex sibling would.
+  hiddenTagInput: {
+    height: 1,
+    opacity: 0,
+    position: "absolute",
+    width: 1
+  },
   iconButton: {
     alignItems: "center",
     borderRadius: 8,
@@ -465,21 +474,61 @@ var styles3 = StyleSheet3.create({
   scrollView: {
     flex: 1
   },
-  // 1x1 and fully transparent — there's nothing to see here on purpose (see EditRow's own comment
-  // above the field this styles). position: 'absolute' pulls it out of editRow's flex flow
-  // entirely, so it doesn't reserve a gap in the row the way a normal flex sibling would.
-  hiddenTagInput: {
-    height: 1,
-    opacity: 0,
-    position: "absolute",
-    width: 1
-  },
   title: {
     flexShrink: 1,
     fontWeight: "bold"
   }
 });
 
+// src/redux/createActionCreator.ts
+function createActionCreator(type) {
+  const creator = ((payload) => ({ payload, type }));
+  creator.type = type;
+  creator.match = (action) => action.type === type;
+  return creator;
+}
+
+// src/redux/profileExtensionSlice.ts
+function createProfileExtensionSlice(namespace) {
+  const set = createActionCreator(`profileExtension/${namespace}/set`);
+  const remove2 = createActionCreator(`profileExtension/${namespace}/remove`);
+  function reducer(state = {}, action) {
+    if (set.match(action)) return { ...state, [action.payload.id]: action.payload.extension };
+    if (remove2.match(action)) {
+      if (!(action.payload in state)) return state;
+      const next = { ...state };
+      delete next[action.payload];
+      return next;
+    }
+    return state;
+  }
+  return { actions: { remove: remove2, set }, reducer };
+}
+
+// src/redux/profilesSlice.ts
+var setAll = createActionCreator("profiles/setAll");
+var add = createActionCreator("profiles/add");
+var update = createActionCreator("profiles/update");
+var remove = createActionCreator("profiles/remove");
+var profilesActions = { add, remove, setAll, update };
+function profilesReducer(state = [], action) {
+  if (setAll.match(action)) return action.payload;
+  if (add.match(action)) return [...state, action.payload];
+  if (update.match(action)) {
+    const { id, patch } = action.payload;
+    return state.map((p) => p.id === id ? { ...p, ...patch, updatedAt: Date.now() } : p);
+  }
+  if (remove.match(action)) return state.filter((p) => p.id !== action.payload);
+  return state;
+}
+function generateProfileId() {
+  return `profile-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function createProfileRecord(input) {
+  const now = Date.now();
+  return { color: input.color, createdAt: now, id: generateProfileId(), name: input.name, tag: input.tag, updatedAt: now };
+}
+
 // src/sharedProfileStore.ts
 var native = null;
 try {
@@ -513,15 +562,70 @@ async function saveSharedProfiles(groupId, profiles) {
   } catch {
   }
 }
+
+// src/redux/resolveInitialProfiles.ts
+async function resolveInitialProfiles(groupId, localFallback) {
+  if (!isSharedProfileStoreAvailable) return localFallback;
+  const shared = await loadSharedProfiles(groupId);
+  if (shared.length === 0 && localFallback.length > 0) {
+    saveSharedProfiles(groupId, localFallback).catch(() => {
+    });
+    return localFallback;
+  }
+  return shared;
+}
+
+// src/redux/useSharedProfilesSync.ts
+import { useCallback as useCallback2, useEffect as useEffect2, useRef as useRef2 } from "react";
+import { AppState } from "react-native";
+function useSharedProfilesSync({ groupId, onRemoteChange }) {
+  const pendingWriteRef = useRef2(false);
+  const onRemoteChangeRef = useRef2(onRemoteChange);
+  useEffect2(() => {
+    onRemoteChangeRef.current = onRemoteChange;
+  }, [onRemoteChange]);
+  useEffect2(() => {
+    if (!isSharedProfileStoreAvailable) return;
+    let cancelled = false;
+    const sub = AppState.addEventListener("change", (next) => {
+      if (next !== "active" || pendingWriteRef.current) return;
+      loadSharedProfiles(groupId).then((shared) => {
+        if (!cancelled) onRemoteChangeRef.current(shared);
+      });
+    });
+    return () => {
+      cancelled = true;
+      sub.remove();
+    };
+  }, [groupId]);
+  const syncToShared = useCallback2(
+    (next) => {
+      if (!isSharedProfileStoreAvailable) return;
+      pendingWriteRef.current = true;
+      saveSharedProfiles(groupId, next).catch(() => {
+      }).finally(() => {
+        pendingWriteRef.current = false;
+      });
+    },
+    [groupId]
+  );
+  return { syncToShared };
+}
 export {
   MAX_PROFILE_NAME_LENGTH,
   MAX_TAG_LENGTH,
   ProfileChip,
   ProfilePicker,
   ProfilesManager,
+  createProfileExtensionSlice,
+  createProfileRecord,
   isSharedProfileStoreAvailable,
   isValidProfile,
   isValidTag,
   loadSharedProfiles,
-  saveSharedProfiles
+  profilesActions,
+  profilesReducer,
+  resolveInitialProfiles,
+  saveSharedProfiles,
+  useSharedProfilesSync
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastic/profile",
-  "version": "0.3.7",
+  "version": "0.4.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",
@@ -62,15 +62,16 @@
   },
   "prettier": "@infinitetoken/eslint-config/prettier",
   "devDependencies": {
-    "@infinitetoken/eslint-config": "^0.1.8",
-    "@infinitetoken/jest-config": "^0.2.1",
-    "@infinitetoken/tsconfig": "^0.3.0",
-    "@rific/auto-paper": "^0.10.3",
-    "@rific/feedback-press": "^0.10.8",
+    "@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",
     "@rific/focus-chain": "^0.4.7",
     "@rific/toaster": "^0.6.3",
-    "@tastic/core": "^0.1.5",
-    "@tastic/hud": "^0.1.6",
+    "@tastic/core": "^0.2.0",
+    "@tastic/hud": "^0.8.5",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^30.0.0",

package/src/ProfilesManager.tsx

@@ -16,6 +16,11 @@ import { Profile } from './types'
 // size for every circle on this screen, rather than each picking its own.
 const CHIP_SIZE = 40
 
+// 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 @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 {
   name: string
   color: string
@@ -52,6 +57,25 @@ export interface ProfilesManagerProps {
   // React 19 accepts `ref` as a plain prop on a function component (no forwardRef needed) — see
   // ProfilesManagerHandle's own doc for why a host may need this.
   ref?: Ref<ProfilesManagerHandle>
+  // Independently optional overrides for this screen's text/card colors — each defaults to the same
+  // literal-black/white-by-appearance formula as before when omitted, so every existing caller
+  // (none of which pass these) renders identically to before. Same convention as @tastic/hud's
+  // BaseStatsScreen fg/cardBg overrides, for a caller with its own app-wide chrome palette instead
+  // of that literal black/white convention. cardBorder/cancelBg/cancelFg have no override, matching
+  // BaseStatsScreen's identical reasoning for cardBorder: their low-alpha/neutral values already
+  // read fine against any cardBg, and (for Cancel specifically) are deliberately neutral rather than
+  // theme-derived so a host's own live gameplay/seat color can't land there by coincidence.
+  fg?: string
+  fgMuted?: string
+  cardBg?: string
+  // 'headlineSmall' (this screen's own default, below), matching BaseStatsScreen's own settled
+  // default and the reasoning behind it — this title sits next to a small headerLeft back-button
+  // glyph the same way, and the previous hardcoded 'displaySmall' read as oversized there too.
+  titleVariant?: MD3TextVariant
+  // Transforms the color swatch grid's own preview per-swatch — forwarded straight to the internal
+  // InlineColorPicker's identical prop (see its own doc). Leaves draftColor/onCreate/onSave's actual
+  // color value untouched; only what's rendered changes.
+  colorPreview?: (hex: string) => string
 }
 
 type Row = { kind: 'profile'; profile: Profile } | { kind: 'new' }
@@ -74,16 +98,16 @@ function deriveTag(name: string): string {
 // really unmounts it on a given host's router — see ProfilesManagerHandle's own doc for the
 // react-navigation-web case where it doesn't, and why a host there needs the `ref` escape hatch
 // instead of relying on the unmount fallback alone.
-export function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref }: ProfilesManagerProps) {
+export function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDelete, headerLeft, ref, fg: fgOverride, fgMuted: fgMutedOverride, cardBg: cardBgOverride, titleVariant = 'headlineSmall', colorPreview }: ProfilesManagerProps) {
   const { dark, colors } = useAutoPaperTheme()
   const insets = useSafeAreaInsets()
   const { error: showErrorToast } = useToast()
   // Only one row is ever in edit mode at a time (see commitEdit, called before any new row opens),
   // so every EditRow instance can safely share this one host instead of each needing its own.
   const host = usePopoverHost()
-  const fg = dark ? '#FFFFFF' : '#000000'
-  const fgMuted = dark ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)'
-  const cardBg = dark ? '#111111' : '#F2F2F2'
+  const fg = fgOverride ?? (dark ? '#FFFFFF' : '#000000')
+  const fgMuted = fgMutedOverride ?? (dark ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)')
+  const cardBg = cardBgOverride ?? (dark ? '#111111' : '#F2F2F2')
   const cardBorder = dark ? 'rgba(255,255,255,0.2)' : 'rgba(0,0,0,0.2)'
   // A contained neutral, not an outlined one — reads as "the other button" next to Delete's solid
   // danger fill, rather than looking unfinished/secondary beside it.
@@ -198,7 +222,7 @@ export function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDe
     <>
       <View style={[styles.header, { paddingTop: 8 + insets.top, paddingLeft: 8 + insets.left }]}>
         {headerLeft}
-        <Text variant='displaySmall' style={[styles.title, { color: fg }]}>
+        <Text variant={titleVariant} style={[styles.title, { color: fg }]}>
           Profiles
         </Text>
       </View>
@@ -226,12 +250,12 @@ export function ProfilesManager({ profiles, defaultColor, onCreate, onSave, onDe
                   </TouchableRipple>
                 )
               }
-              return <EditRow key='new' draftName={draftName} onNameChange={handleNameChange} draftColor={draftColor} onColorChange={setDraftColor} draftTag={draftTag} onTagChange={handleTagChange} onSubmit={commitEdit} autoFocus fgMuted={fgMuted} host={host} dark={dark} />
+              return <EditRow key='new' draftName={draftName} onNameChange={handleNameChange} draftColor={draftColor} onColorChange={setDraftColor} draftTag={draftTag} onTagChange={handleTagChange} onSubmit={commitEdit} autoFocus fgMuted={fgMuted} host={host} dark={dark} colorPreview={colorPreview} />
             }
 
             const { profile } = row
             if (editingId === profile.id) {
-              return <EditRow key={profile.id} draftName={draftName} onNameChange={handleNameChange} draftColor={draftColor} onColorChange={setDraftColor} draftTag={draftTag} onTagChange={handleTagChange} onSubmit={commitEdit} onDelete={() => setConfirmDeleteId(profile.id)} fgMuted={fgMuted} host={host} dark={dark} />
+              return <EditRow key={profile.id} draftName={draftName} onNameChange={handleNameChange} draftColor={draftColor} onColorChange={setDraftColor} draftTag={draftTag} onTagChange={handleTagChange} onSubmit={commitEdit} onDelete={() => setConfirmDeleteId(profile.id)} fgMuted={fgMuted} host={host} dark={dark} colorPreview={colorPreview} />
             }
 
             // No delete affordance at rest — tap the row to start editing, which is the one place
@@ -295,6 +319,7 @@ interface EditRowProps {
   fgMuted: string
   host: PopoverHost
   dark: boolean
+  colorPreview?: (hex: string) => string
 }
 
 // One row, expanded: the color trigger (@tastic/hud's InlineColorPicker) — doubling as the tag's
@@ -309,7 +334,7 @@ interface EditRowProps {
 // own — submitting the *name* field is what actually commits the row, so its registration's own
 // onSubmitEditing (a no-op — it's last in the chain) is overridden with onSubmit below, matching
 // how a normal multi-field form reads: fill fields in order, the last one finishes it.
-function EditRow({ draftName, onNameChange, draftColor, onColorChange, draftTag, onTagChange, onSubmit, onDelete, autoFocus, fgMuted, host, dark }: EditRowProps) {
+function EditRow({ draftName, onNameChange, draftColor, onColorChange, draftTag, onTagChange, onSubmit, onDelete, autoFocus, fgMuted, host, dark, colorPreview }: EditRowProps) {
   const register = useFocusChain()
   const tag = register()
   const name = register()
@@ -336,7 +361,7 @@ function EditRow({ draftName, onNameChange, draftColor, onColorChange, draftTag,
 
   return (
     <View style={styles.editRow}>
-      <InlineColorPicker id='color' host={host} value={draftColor} onChange={onColorChange} tag={draftTag} dark={dark} />
+      <InlineColorPicker id='color' host={host} value={draftColor} onChange={onColorChange} previewValue={colorPreview} tag={draftTag} dark={dark} />
       {/* Invisible on purpose (styles.hiddenTagInput: zero footprint, position: 'absolute' so it
       doesn't reserve space in the row's own flex layout) — the swatch above is the only place this
       value is ever meant to be seen. pointerEvents='none' is what actually keeps it out of the
@@ -380,6 +405,15 @@ const styles = StyleSheet.create({
     gap: 4,
     paddingBottom: 8
   },
+  // 1x1 and fully transparent — there's nothing to see here on purpose (see EditRow's own comment
+  // above the field this styles). position: 'absolute' pulls it out of editRow's flex flow
+  // entirely, so it doesn't reserve a gap in the row the way a normal flex sibling would.
+  hiddenTagInput: {
+    height: 1,
+    opacity: 0,
+    position: 'absolute',
+    width: 1
+  },
   iconButton: {
     alignItems: 'center',
     borderRadius: 8,
@@ -441,15 +475,6 @@ const styles = StyleSheet.create({
   scrollView: {
     flex: 1
   },
-  // 1x1 and fully transparent — there's nothing to see here on purpose (see EditRow's own comment
-  // above the field this styles). position: 'absolute' pulls it out of editRow's flex flow
-  // entirely, so it doesn't reserve a gap in the row the way a normal flex sibling would.
-  hiddenTagInput: {
-    height: 1,
-    opacity: 0,
-    position: 'absolute',
-    width: 1
-  },
   title: {
     flexShrink: 1,
     fontWeight: 'bold'

package/src/index.ts

@@ -2,5 +2,9 @@ export { ProfileChip } from './ProfileChip'
 export { ProfilePicker } from './ProfilePicker'
 export { ProfilesManager, type ProfilesManagerHandle, type ProfilesManagerProps } from './ProfilesManager'
 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 { type CreateProfileInput, createProfileRecord, profilesActions, profilesReducer, type UpdateProfilePayload } from './redux/profilesSlice'
+export { resolveInitialProfiles } from './redux/resolveInitialProfiles'
+export { useSharedProfilesSync, type UseSharedProfilesSyncOptions, type UseSharedProfilesSyncResult } from './redux/useSharedProfilesSync'
 export { isSharedProfileStoreAvailable, loadSharedProfiles, saveSharedProfiles } from './sharedProfileStore'
 export type { Profile } from './types'

package/src/redux/createActionCreator.ts

@@ -0,0 +1,21 @@
+export interface ReduxAction<P> {
+  payload: P
+  type: string
+}
+
+export type ActionCreator<P> = ((payload: P) => ReduxAction<P>) & {
+  type: string
+  match: (action: { type: string }) => action is 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
+// 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> {
+  const creator = ((payload: P) => ({ payload, type })) as ActionCreator<P>
+  creator.type = type
+  creator.match = (action: { type: string }): action is ReduxAction<P> => action.type === type
+  return creator
+}

package/src/redux/profileExtensionSlice.ts

@@ -0,0 +1,55 @@
+import { ActionCreator, createActionCreator } from './createActionCreator'
+
+export interface SetProfileExtensionPayload<TExtension> {
+  extension: TExtension
+  id: string
+}
+
+export interface ProfileExtensionActions<TExtension> {
+  remove: ActionCreator<string>
+  set: ActionCreator<SetProfileExtensionPayload<TExtension>>
+}
+
+export type ProfileExtensionState<TExtension> = Record<string, TExtension>
+
+export interface ProfileExtensionSlice<TExtension> {
+  actions: ProfileExtensionActions<TExtension>
+  reducer: (state: ProfileExtensionState<TExtension> | undefined, action: { type: string }) => ProfileExtensionState<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
+// 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
+// Record<profileId, TExtension> reducer before this factory existed; this is that shape,
+// generalized over the extension's own type so a future game's own per-profile preference doesn't
+// 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
+// @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,
+// 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`
+// alongside those is one more such dispatch, not new cross-slice wiring.
+export function createProfileExtensionSlice<TExtension>(namespace: string): ProfileExtensionSlice<TExtension> {
+  const set = createActionCreator<SetProfileExtensionPayload<TExtension>>(`profileExtension/${namespace}/set`)
+  const remove = createActionCreator<string>(`profileExtension/${namespace}/remove`)
+
+  function reducer(state: ProfileExtensionState<TExtension> = {}, action: { type: string }): ProfileExtensionState<TExtension> {
+    if (set.match(action)) return { ...state, [action.payload.id]: action.payload.extension }
+    if (remove.match(action)) {
+      if (!(action.payload in state)) return state
+      const next = { ...state }
+      delete next[action.payload]
+      return next
+    }
+    return state
+  }
+
+  return { actions: { remove, set }, reducer }
+}

package/src/redux/profilesSlice.ts

@@ -0,0 +1,47 @@
+import { Profile } from '../types'
+import { createActionCreator } from './createActionCreator'
+
+export interface UpdateProfilePayload {
+  id: string
+  patch: Partial<Pick<Profile, 'name' | 'color' | 'tag'>>
+}
+
+// setAll: full-replace, for hydrating from resolveInitialProfiles or a remote refresh
+// (useSharedProfilesSync's onRemoteChange). add/update/remove: the actual roster CRUD every
+// @tastic game already hand-rolled an identical version of in its own useProfiles.tsx.
+const setAll = createActionCreator<Profile[]>('profiles/setAll')
+const add = createActionCreator<Profile>('profiles/add')
+const update = createActionCreator<UpdateProfilePayload>('profiles/update')
+const remove = createActionCreator<string>('profiles/remove')
+
+export const profilesActions = { add, remove, setAll, update }
+
+export function profilesReducer(state: Profile[] = [], action: { type: string }): Profile[] {
+  if (setAll.match(action)) return action.payload
+  if (add.match(action)) return [...state, action.payload]
+  if (update.match(action)) {
+    const { id, patch } = action.payload
+    return state.map((p) => (p.id === id ? { ...p, ...patch, updatedAt: Date.now() } : p))
+  }
+  if (remove.match(action)) return state.filter((p) => p.id !== action.payload)
+  return state
+}
+
+function generateProfileId(): string {
+  return `profile-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+export interface CreateProfileInput {
+  name: string
+  color: string
+  tag: string
+}
+
+// Builds a complete Profile (id + timestamps) ready to dispatch via profilesActions.add. Kept as
+// its own plain function rather than folded into the `add` action creator, so `add` itself stays a
+// simple "append this exact record" primitive (useful for rehydration/tests too, where the record
+// already exists and shouldn't get a second, different id/timestamp minted for it).
+export function createProfileRecord(input: CreateProfileInput): Profile {
+  const now = Date.now()
+  return { color: input.color, createdAt: now, id: generateProfileId(), name: input.name, tag: input.tag, updatedAt: now }
+}

package/src/redux/resolveInitialProfiles.ts

@@ -0,0 +1,26 @@
+import { isSharedProfileStoreAvailable, loadSharedProfiles, 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
+// 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, 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
+//   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.
+export async function resolveInitialProfiles(groupId: string, localFallback: Profile[]): Promise<Profile[]> {
+  if (!isSharedProfileStoreAvailable) return localFallback
+  const shared = await loadSharedProfiles(groupId)
+  if (shared.length === 0 && localFallback.length > 0) {
+    saveSharedProfiles(groupId, localFallback).catch(() => {})
+    return localFallback
+  }
+  return shared
+}

package/src/redux/useSharedProfilesSync.ts

@@ -0,0 +1,74 @@
+import { useCallback, useEffect, useRef } from 'react'
+import { AppState } from 'react-native'
+
+import { isSharedProfileStoreAvailable, loadSharedProfiles, 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
+  // 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.
+  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
+  // hook existed. Fire-and-forget: never throws, never awaited by this hook itself.
+  syncToShared: (next: Profile[]) => void
+}
+
+// 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
+// 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
+  // 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
+  // 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)
+  useEffect(() => {
+    onRemoteChangeRef.current = onRemoteChange
+  }, [onRemoteChange])
+
+  useEffect(() => {
+    if (!isSharedProfileStoreAvailable) return
+    let cancelled = false
+    const sub = AppState.addEventListener('change', (next) => {
+      if (next !== 'active' || pendingWriteRef.current) return
+      loadSharedProfiles(groupId).then((shared) => {
+        if (!cancelled) onRemoteChangeRef.current(shared)
+      })
+    })
+    return () => {
+      cancelled = true
+      sub.remove()
+    }
+  }, [groupId])
+
+  const syncToShared = useCallback(
+    (next: Profile[]) => {
+      if (!isSharedProfileStoreAvailable) return
+      pendingWriteRef.current = true
+      saveSharedProfiles(groupId, next)
+        .catch(() => {})
+        .finally(() => {
+          pendingWriteRef.current = false
+        })
+    },
+    [groupId]
+  )
+
+  return { syncToShared }
+}