chore(release): 3.20.0 [skip ci]

## [3.20.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.19.0...v3.20.0) (2025-10-15)

### Features

* adjust tier probabilities for more abacus flavor ([49219e3](49219e34cd))

### Code Refactoring

* use per-word-type tier selection for name generation ([499ee52](499ee525a8))

CHANGELOG.md

@@ -1,3 +1,22 @@
+## [3.20.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.19.0...v3.20.0) (2025-10-15)
+
+
+### Features
+
+* adjust tier probabilities for more abacus flavor ([49219e3](https://github.com/antialias/soroban-abacus-flashcards/commit/49219e34cde32736155a11929d10581e783cba69))
+
+
+### Code Refactoring
+
+* use per-word-type tier selection for name generation ([499ee52](https://github.com/antialias/soroban-abacus-flashcards/commit/499ee525a835249b439044cf602bf9f0ff322cec))
+
+## [3.19.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.18.1...v3.19.0) (2025-10-15)
+
+
+### Features
+
+* implement avatar-themed name generation with probabilistic mixing ([76a8472](https://github.com/antialias/soroban-abacus-flashcards/commit/76a8472f12d251071b97f2288f62f0b358576232))
+
 ## [3.18.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.18.0...v3.18.1) (2025-10-15)
 
 

apps/web/.claude/settings.local.json

@@ -70,7 +70,12 @@
       "Bash(lsof:*)",
       "Bash(killall:*)",
       "Bash(echo:*)",
-      "Bash(git restore:*)"
+      "Bash(git restore:*)",
+      "Bash(timeout 10 npm run dev:*)",
+      "Bash(timeout 30 npm run dev)",
+      "Bash(pkill:*)",
+      "Bash(for i in {1..30})",
+      "Bash(do gh run list --limit 1 --json conclusion,status,name,databaseId --jq '.[0] | \"\"\\(.status) - \\(.conclusion // \"\"running\"\") - Run ID: \\(.databaseId)\"\"')"
     ],
     "deny": [],
     "ask": []

apps/web/src/components/nav/PlayerConfigDialog.tsx

@@ -52,7 +52,7 @@ export function PlayerConfigDialog({ playerId, onClose }: PlayerConfigDialogProp
   const handleGenerateNewName = () => {
     const allPlayers = Array.from(players.values())
     const existingNames = allPlayers.filter((p) => p.id !== playerId).map((p) => p.name)
-    const newName = generateUniquePlayerName(existingNames)
+    const newName = generateUniquePlayerName(existingNames, player.emoji)
 
     setLocalName(newName)
     updatePlayer(playerId, { name: newName })

apps/web/src/contexts/GameModeContext.tsx

@@ -11,7 +11,7 @@ import {
 } from '@/hooks/useUserPlayers'
 import { useViewerId } from '@/hooks/useViewerId'
 import { getNextPlayerColor } from '../types/player'
-import { generateUniquePlayerName, generateUniquePlayerNames } from '../utils/playerNames'
+import { generateUniquePlayerName } from '../utils/playerNames'
 
 // Client-side Player type (compatible with old type)
 export interface Player {
@@ -141,8 +141,13 @@ export function GameModeProvider({ children }: { children: ReactNode }) {
   useEffect(() => {
     if (!isLoading && !isInitialized) {
       if (dbPlayers.length === 0) {
-        // Generate unique names for default players
-        const generatedNames = generateUniquePlayerNames(DEFAULT_PLAYER_CONFIGS.length)
+        // Generate unique names for default players, themed by their emoji
+        const existingNames: string[] = []
+        const generatedNames = DEFAULT_PLAYER_CONFIGS.map((config) => {
+          const name = generateUniquePlayerName(existingNames, config.emoji)
+          existingNames.push(name)
+          return name
+        })
 
         // Create default players with generated names
         DEFAULT_PLAYER_CONFIGS.forEach((config, index) => {
@@ -167,10 +172,11 @@ export function GameModeProvider({ children }: { children: ReactNode }) {
   const addPlayer = (playerData?: Partial<Player>) => {
     const playerList = Array.from(players.values())
     const existingNames = playerList.map((p) => p.name)
+    const emoji = playerData?.emoji ?? '🎮'
 
     const newPlayer = {
-      name: playerData?.name ?? generateUniquePlayerName(existingNames),
-      emoji: playerData?.emoji ?? '🎮',
+      name: playerData?.name ?? generateUniquePlayerName(existingNames, emoji),
+      emoji,
       color: playerData?.color ?? getNextPlayerColor(playerList),
       isActive: playerData?.isActive ?? false,
     }
@@ -254,8 +260,13 @@ export function GameModeProvider({ children }: { children: ReactNode }) {
       deletePlayer(player.id)
     })
 
-    // Generate unique names for default players
-    const generatedNames = generateUniquePlayerNames(DEFAULT_PLAYER_CONFIGS.length)
+    // Generate unique names for default players, themed by their emoji
+    const existingNames: string[] = []
+    const generatedNames = DEFAULT_PLAYER_CONFIGS.map((config) => {
+      const name = generateUniquePlayerName(existingNames, config.emoji)
+      existingNames.push(name)
+      return name
+    })
 
     // Create default players with generated names
     DEFAULT_PLAYER_CONFIGS.forEach((config, index) => {

apps/web/src/utils/__tests__/playerNames.test.ts

@@ -47,7 +47,7 @@ describe('playerNames', () => {
     it('should append number if all combinations are exhausted', () => {
       // Create a mock with limited attempts
       const existingNames = ['Swift Ninja']
-      const name = generateUniquePlayerName(existingNames, 1)
+      const name = generateUniquePlayerName(existingNames, undefined, 1)
 
       // Should either be unique or have a number appended
       expect(name).toBeTruthy()

apps/web/src/utils/playerNames.ts

@@ -1,8 +1,14 @@
 /**
  * Fun automatic player name generation system
  * Generates creative names by combining adjectives with nouns/roles
+ *
+ * Supports avatar-specific theming! Each emoji can have its own personality-matched words.
+ * Falls back gracefully: emoji-specific → category → generic abacus theme
  */
 
+import { EMOJI_SPECIFIC_WORDS, EMOJI_TO_THEME, THEMED_WORD_LISTS } from './themedWords'
+
+// Generic abacus-themed words (used as ultimate fallback)
 const ADJECTIVES = [
   // Abacus-themed adjectives
   'Ancient',
@@ -114,32 +120,96 @@ const NOUNS = [
 ]
 
 /**
- * Generate a random player name by combining an adjective and noun
+ * Select a word list tier using weighted random selection
+ * Balanced mix: emoji-specific (50%), category (25%), global abacus (25%)
  */
-export function generatePlayerName(): string {
-  const adjective = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)]
-  const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)]
+function selectWordListTier(emoji: string, wordType: 'adjectives' | 'nouns'): string[] {
+  // Collect available tiers
+  const availableTiers: Array<{ weight: number; words: string[] }> = []
+
+  // Emoji-specific tier (50% preference)
+  const emojiSpecific = EMOJI_SPECIFIC_WORDS[emoji]
+  if (emojiSpecific) {
+    availableTiers.push({ weight: 50, words: emojiSpecific[wordType] })
+  }
+
+  // Category tier (25% preference)
+  const category = EMOJI_TO_THEME[emoji]
+  if (category) {
+    const categoryTheme = THEMED_WORD_LISTS[category]
+    if (categoryTheme) {
+      availableTiers.push({ weight: 25, words: categoryTheme[wordType] })
+    }
+  }
+
+  // Global abacus tier (25% preference)
+  availableTiers.push({ weight: 25, words: wordType === 'adjectives' ? ADJECTIVES : NOUNS })
+
+  // Weighted random selection
+  const totalWeight = availableTiers.reduce((sum, tier) => sum + tier.weight, 0)
+  let random = Math.random() * totalWeight
+
+  for (const tier of availableTiers) {
+    random -= tier.weight
+    if (random <= 0) {
+      return tier.words
+    }
+  }
+
+  // Fallback (should never reach here)
+  return wordType === 'adjectives' ? ADJECTIVES : NOUNS
+}
+
+/**
+ * Generate a random player name by combining an adjective and noun
+ * Optionally themed based on avatar emoji for ultra-personalized names!
+ * Uses per-word-type probabilistic tier selection for natural variety
+ *
+ * @param emoji - Optional emoji avatar to theme the name around
+ * @returns A creative player name like "Grinning Calculator" or "Lightning Smiler"
+ */
+export function generatePlayerName(emoji?: string): string {
+  if (!emoji) {
+    // No emoji provided, use pure abacus theme
+    const adjective = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)]
+    const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)]
+    return `${adjective} ${noun}`
+  }
+
+  // Select tier independently for each word type
+  // This creates natural mixing: adjective might be emoji-specific while noun is global
+  const adjectiveList = selectWordListTier(emoji, 'adjectives')
+  const nounList = selectWordListTier(emoji, 'nouns')
+
+  const adjective = adjectiveList[Math.floor(Math.random() * adjectiveList.length)]
+  const noun = nounList[Math.floor(Math.random() * nounList.length)]
+
   return `${adjective} ${noun}`
 }
 
 /**
  * Generate a unique player name that doesn't conflict with existing players
  * @param existingNames - Array of names already in use
+ * @param emoji - Optional emoji avatar to theme the name around
  * @param maxAttempts - Maximum attempts to find a unique name (default: 50)
  * @returns A unique player name
  */
-export function generateUniquePlayerName(existingNames: string[], maxAttempts = 50): string {
+export function generateUniquePlayerName(
+  existingNames: string[],
+  emoji?: string,
+  maxAttempts = 50
+): string {
   const existingNamesSet = new Set(existingNames.map((name) => name.toLowerCase()))
 
   for (let i = 0; i < maxAttempts; i++) {
-    const name = generatePlayerName()
+    const name = generatePlayerName(emoji)
     if (!existingNamesSet.has(name.toLowerCase())) {
       return name
     }
   }
 
   // Fallback: if we can't find a unique name, append a number
-  const baseName = generatePlayerName()
+  const baseName = generatePlayerName(emoji)
   let counter = 1
   while (existingNamesSet.has(`${baseName} ${counter}`.toLowerCase())) {
     counter++
@@ -150,12 +220,13 @@ export function generateUniquePlayerName(existingNames: string[], maxAttempts =
 /**
  * Generate a batch of unique player names
  * @param count - Number of names to generate
+ * @param emoji - Optional emoji avatar to theme the names around
  * @returns Array of unique player names
  */
-export function generateUniquePlayerNames(count: number): string[] {
+export function generateUniquePlayerNames(count: number, emoji?: string): string[] {
   const names: string[] = []
   for (let i = 0; i < count; i++) {
-    const name = generateUniquePlayerName(names)
+    const name = generateUniquePlayerName(names, emoji)
     names.push(name)
   }
   return names

package.json

@@ -1,6 +1,6 @@
 {
   "name": "soroban-monorepo",
-  "version": "3.18.1",
+  "version": "3.20.0",
   "private": true,
   "description": "Beautiful Soroban Flashcard Generator - Monorepo",
   "workspaces": [