@tastic/profile 0.3.8 → 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

@@ -65,8 +65,67 @@ 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

@@ -65,8 +65,67 @@ 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);
 
@@ -508,6 +514,55 @@ var styles3 = import_react_native3.StyleSheet.create({
   }
 });
 
+// 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

@@ -480,6 +480,55 @@ var styles3 = StyleSheet3.create({
   }
 });
 
+// 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.8",
+  "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",
@@ -65,12 +65,13 @@
     "@infinitetoken/eslint-config": "0.2.0",
     "@infinitetoken/jest-config": "^0.2.4",
     "@infinitetoken/tsconfig": "^0.4.1",
-    "@rific/auto-paper": "^0.10.3",
-    "@rific/feedback-press": "^0.10.8",
+    "@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.2.0",
-    "@tastic/hud": "^0.6.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/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 }
+}