Celebration animations for purchases, XP gains & achievement unlocks

- New global celebration system: celebration-store (queue) + CelebrationOverlay
  (animated: count-up XP, filling bar, level-up pop, achievement cards; plays
  levelUp/award sounds; tap or auto-dismiss). Rendered in page.tsx.
- Shop: every purchase now celebrates — XP packs animate XP gain + level-up,
  cosmetics show a "purchased!" pop. Newly-unlocked achievements (diffed from
  the profile before/after) animate too.
- XP purchases now actually evaluate achievements: gamification.evaluateAchievements
  (client) + Gamification.EvaluateAchievements (server, called in ShopBuy xp path)
  unlock level milestones + grant their coins.

Verified live: buying XP took L1→L5, unlocked level_5 server-side and credited its
reward. tsc + dotnet + next build clean; images rebuilt :1500/:1505.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

server/src/Hokm.Server/Profiles/Gamification.cs

@@ -148,6 +148,25 @@ public static class Gamification
         p.Xp = r.xp;
     }
 
+    /// <summary>Re-evaluate achievements vs current state (outside a match), unlock new
+    /// ones + grant their coins, and return the newly-unlocked list.</summary>
+    public static List<AchievementUnlockDto> EvaluateAchievements(ProfileDto p)
+    {
+        var list = new List<AchievementUnlockDto>();
+        foreach (var d in Achs)
+        {
+            int prog = AchProgress(d, p.Stats, p.Rating, p.Level);
+            p.Achievements[d.Id] = prog;
+            if (prog >= d.Goal && !p.Unlocked.Contains(d.Id))
+            {
+                p.Unlocked.Add(d.Id);
+                p.Coins += d.Coin;
+                list.Add(new() { Id = d.Id, NameFa = d.NameFa, NameEn = d.NameEn, Icon = d.Icon, CoinReward = d.Coin });
+            }
+        }
+        return list;
+    }
+
     private static (int level, int xp, bool up) AddXp(int level, int xp, int gain)
     {
         bool up = false;

server/src/Hokm.Server/Profiles/ProfileService.cs

@@ -131,6 +131,7 @@ public class ProfileService
             if (p.Coins < pk.Price) return (false, p, "insufficient");
             p.Coins -= pk.Price;
             Gamification.GrantXp(p, pk.Xp);
+            Gamification.EvaluateAchievements(p); // unlock any level milestones reached
             await Save(p);
             await Ledger(uid, "xp", -pk.Price, id);
             return (true, p, "");

src/app/page.tsx

@@ -18,6 +18,7 @@ import { AuthScreen } from "@/components/screens/AuthScreen";
 import { DailyRewardModal } from "@/components/online/DailyRewardModal";
 import { NotificationToaster } from "@/components/online/NotificationToaster";
 import { ResumeGameBar } from "@/components/online/ResumeGameBar";
+import { CelebrationOverlay } from "@/components/online/CelebrationOverlay";
 import { CapacitorBack } from "@/components/CapacitorBack";
 import { useSessionStore } from "@/lib/session-store";
 import { useGameStore } from "@/lib/game-store";
@@ -141,6 +142,7 @@ export default function Page() {
       <DailyRewardModal />
       <NotificationToaster />
       <ResumeGameBar />
+      <CelebrationOverlay />
       <CapacitorBack />
       {loading && null}
     </>

src/components/online/CelebrationOverlay.tsx

@@ -0,0 +1,165 @@
+"use client";
+
+import { AnimatePresence, motion } from "framer-motion";
+import { Coins, Sparkles, Star, TrendingUp } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { useCelebrationStore } from "@/lib/celebration-store";
+import { useI18n } from "@/lib/i18n";
+import { sound } from "@/lib/sound";
+
+function useCountUp(target: number, ms = 900, run = true) {
+  const [v, setV] = useState(0);
+  const raf = useRef<number | null>(null);
+  useEffect(() => {
+    if (!run) return;
+    const start = performance.now();
+    const tick = (now: number) => {
+      const p = Math.min(1, (now - start) / ms);
+      // ease-out
+      setV(Math.round(target * (1 - Math.pow(1 - p, 3))));
+      if (p < 1) raf.current = requestAnimationFrame(tick);
+    };
+    raf.current = requestAnimationFrame(tick);
+    return () => { if (raf.current) cancelAnimationFrame(raf.current); };
+  }, [target, ms, run]);
+  return v;
+}
+
+/** Global animated celebration for purchases / XP gains / achievement unlocks. */
+export function CelebrationOverlay() {
+  const current = useCelebrationStore((s) => s.current);
+  const dismiss = useCelebrationStore((s) => s.dismiss);
+
+  useEffect(() => {
+    if (!current) return;
+    const leveled = (current.levelAfter ?? 0) > (current.levelBefore ?? 0);
+    const cue = setTimeout(() => {
+      if (leveled) sound.play("levelUp");
+      else if (current.achievements?.length) sound.play("award");
+    }, 350);
+    const auto = setTimeout(() => dismiss(), current.achievements?.length ? 5200 : 3600);
+    return () => { clearTimeout(cue); clearTimeout(auto); };
+  }, [current, dismiss]);
+
+  return (
+    <AnimatePresence>
+      {current && <Card key={current.id} />}
+    </AnimatePresence>
+  );
+}
+
+function Card() {
+  const { t, locale } = useI18n();
+  const current = useCelebrationStore((s) => s.current)!;
+  const dismiss = useCelebrationStore((s) => s.dismiss);
+  const leveled = (current.levelAfter ?? 0) > (current.levelBefore ?? 0);
+  const xp = useCountUp(current.xpGained ?? 0, 900, current.variant === "xp");
+
+  return (
+    <motion.div
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      exit={{ opacity: 0 }}
+      onClick={dismiss}
+      className="fixed inset-0 z-[80] flex items-center justify-center bg-navy-950/80 backdrop-blur-sm p-6"
+    >
+      <motion.div
+        initial={{ scale: 0.8, y: 20 }}
+        animate={{ scale: 1, y: 0 }}
+        exit={{ scale: 0.9, opacity: 0 }}
+        transition={{ type: "spring", stiffness: 200, damping: 18 }}
+        onClick={(e) => e.stopPropagation()}
+        className="glass rounded-3xl p-7 w-full max-w-xs text-center relative overflow-hidden"
+      >
+        {/* radiating glow */}
+        <div className="pointer-events-none absolute -inset-10 bg-gold-500/15 blur-3xl" />
+
+        <motion.div
+          initial={{ scale: 0, rotate: -20 }}
+          animate={{ scale: 1, rotate: 0 }}
+          transition={{ type: "spring", stiffness: 180, delay: 0.1 }}
+          className="relative text-6xl mb-1"
+        >
+          {current.icon ?? (current.variant === "xp" ? "⚡" : "🛍️")}
+        </motion.div>
+
+        {current.title && (
+          <h2 className="relative gold-text text-xl font-black mt-1">{current.title}</h2>
+        )}
+
+        {/* XP gain */}
+        {current.variant === "xp" && (current.xpGained ?? 0) > 0 && (
+          <div className="relative mt-3">
+            <div className="inline-flex items-center gap-2 btn-gold rounded-full px-5 py-2 font-black text-lg">
+              <Star className="size-5" fill="currentColor" />
+              +{xp.toLocaleString()} XP
+            </div>
+            <motion.div
+              className="mt-3 h-2 rounded-full bg-navy-900 overflow-hidden"
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+            >
+              <motion.div
+                className="h-full bg-gradient-to-r from-gold-500 to-gold-300"
+                initial={{ width: "0%" }}
+                animate={{ width: "100%" }}
+                transition={{ duration: 0.9, ease: "easeOut" }}
+              />
+            </motion.div>
+          </div>
+        )}
+
+        {/* level up */}
+        {leveled && (
+          <motion.div
+            initial={{ scale: 0 }}
+            animate={{ scale: 1 }}
+            transition={{ type: "spring", stiffness: 220, delay: 0.5 }}
+            className="relative mt-4 inline-flex items-center gap-2 rounded-full bg-teal-500/20 text-teal-200 px-5 py-1.5 font-black"
+          >
+            <TrendingUp className="size-4" />
+            {t("reward.levelUp")} → {current.levelAfter}
+          </motion.div>
+        )}
+
+        {/* achievements */}
+        {current.achievements && current.achievements.length > 0 && (
+          <div className="relative mt-4 space-y-2">
+            {current.achievements.map((a, i) => (
+              <motion.div
+                key={a.id}
+                initial={{ opacity: 0, x: locale === "fa" ? 24 : -24 }}
+                animate={{ opacity: 1, x: 0 }}
+                transition={{ delay: 0.6 + i * 0.15, type: "spring", stiffness: 200 }}
+                className="glass rounded-xl px-3 py-2 flex items-center gap-2 text-start"
+              >
+                <span className="text-2xl">{a.icon}</span>
+                <span className="flex-1 min-w-0">
+                  <span className="block text-[10px] text-gold-400">{t("reward.newAchievement")}</span>
+                  <span className="block text-sm font-semibold text-cream truncate">
+                    {locale === "fa" ? a.nameFa : a.nameEn}
+                  </span>
+                </span>
+                <span className="text-xs text-gold-300 flex items-center gap-1 shrink-0">
+                  +{a.coinReward}
+                  <Coins className="size-3" />
+                </span>
+              </motion.div>
+            ))}
+          </div>
+        )}
+
+        {current.variant === "purchase" && !current.achievements?.length && (
+          <p className="relative text-teal-300 font-bold text-sm mt-2 flex items-center justify-center gap-1.5">
+            <Sparkles className="size-4" />
+            {t("celebrate.purchased")}
+          </p>
+        )}
+
+        <button onClick={dismiss} className="relative btn-gold w-full rounded-xl py-2.5 mt-6 font-bold">
+          {t("reward.continue")}
+        </button>
+      </motion.div>
+    </motion.div>
+  );
+}

src/components/screens/ShopScreen.tsx

@@ -9,7 +9,9 @@ import { useSessionStore } from "@/lib/session-store";
 import { useI18n } from "@/lib/i18n";
 import { getService } from "@/lib/online/service";
 import { sound } from "@/lib/sound";
-import { ShopItem } from "@/lib/online/types";
+import { achievementById } from "@/lib/online/gamification";
+import { celebrate } from "@/lib/celebration-store";
+import { AchievementUnlock, ShopItem } from "@/lib/online/types";
 import { cn } from "@/lib/cn";
 
 /** The product artwork, used on the card and (bigger) in the detail sheet. */
@@ -75,11 +77,40 @@ export function ShopScreen() {
   };
 
   const buy = async (item: ShopItem) => {
+    const before = profile;
     const res = await getService().buyItem(item.id);
     if (res.ok && res.profile) {
-      setProfile(res.profile);
+      const after = res.profile;
+      setProfile(after);
       sound.play("purchase");
       setDetail(null);
+
+      // newly-unlocked achievements (e.g. an XP pack crossing a level milestone)
+      const newAch: AchievementUnlock[] = after.unlocked
+        .filter((id) => !before.unlocked.includes(id))
+        .map((id) => achievementById(id))
+        .filter((d): d is NonNullable<typeof d> => !!d)
+        .map((d) => ({ id: d.id, nameFa: d.nameFa, nameEn: d.nameEn, icon: d.icon, coinReward: d.coinReward }));
+
+      if (item.kind === "xp") {
+        celebrate({
+          variant: "xp",
+          icon: "⚡",
+          title: locale === "fa" ? "امتیاز تجربه" : "Experience",
+          xpGained: item.xp ?? 0,
+          levelBefore: before.level,
+          levelAfter: after.level,
+          achievements: newAch.length ? newAch : undefined,
+        });
+      } else {
+        celebrate({
+          variant: "purchase",
+          // avatar/reaction previews are emojis; others fall back to the default glyph
+          icon: item.kind === "avatar" || item.kind === "reactionpack" ? item.preview : undefined,
+          title: locale === "fa" ? item.nameFa : item.nameEn,
+          achievements: newAch.length ? newAch : undefined,
+        });
+      }
     } else {
       setMsg(locale === "fa" ? res.messageFa : res.messageEn);
       setTimeout(() => setMsg(""), 1800);

src/lib/celebration-store.ts

@@ -0,0 +1,45 @@
+"use client";
+
+import { create } from "zustand";
+import { AchievementUnlock } from "./online/types";
+
+/** A queued celebration shown by <CelebrationOverlay/>. */
+export interface Celebration {
+  id: number;
+  variant: "xp" | "purchase";
+  title?: string;
+  /** emoji/glyph shown big at the top */
+  icon?: string;
+  xpGained?: number;
+  levelBefore?: number;
+  levelAfter?: number;
+  achievements?: AchievementUnlock[];
+}
+
+interface CelebrationStore {
+  current: Celebration | null;
+  queue: Celebration[];
+  celebrate: (c: Omit<Celebration, "id">) => void;
+  dismiss: () => void;
+}
+
+let _id = 1;
+
+export const useCelebrationStore = create<CelebrationStore>((set, get) => ({
+  current: null,
+  queue: [],
+  celebrate: (c) => {
+    const item: Celebration = { ...c, id: _id++ };
+    if (get().current) set({ queue: [...get().queue, item] });
+    else set({ current: item });
+  },
+  dismiss: () => {
+    const [next, ...rest] = get().queue;
+    set({ current: next ?? null, queue: rest });
+  },
+}));
+
+/** Convenience helper usable from anywhere (no hook needed). */
+export function celebrate(c: Omit<Celebration, "id">) {
+  useCelebrationStore.getState().celebrate(c);
+}

src/lib/i18n.tsx

@@ -33,6 +33,7 @@ const fa: Dict = {
   "resume.cta": "بازگشت به بازی",
   "resume.matchEnded": "بازی به پایان رسید",
   "resume.matchEndedBody": "نتیجه و جایزه را ببینید",
+  "celebrate.purchased": "خرید با موفقیت انجام شد!",
 
   "achv.title": "دستاوردها",
   "achv.unlocked": "باز شده",
@@ -299,6 +300,7 @@ const en: Dict = {
   "resume.cta": "Return to game",
   "resume.matchEnded": "Match ended",
   "resume.matchEndedBody": "See the result and reward",
+  "celebrate.purchased": "Purchase complete!",
 
   "achv.title": "Achievements",
   "achv.unlocked": "Unlocked",

src/lib/online/gamification.ts

@@ -298,6 +298,40 @@ export function achievementById(id: string): AchievementDef | undefined {
   return ACHIEVEMENTS.find((a) => a.id === id);
 }
 
+/**
+ * Re-evaluate all achievements against the profile's current state (used outside
+ * matches, e.g. after an XP-pack purchase crosses a level milestone). Unlocks new
+ * ones, grants their coin rewards, and returns the newly-unlocked list.
+ */
+export function evaluateAchievements(profile: UserProfile): {
+  profile: UserProfile;
+  newAchievements: AchievementUnlock[];
+} {
+  const achievements = { ...profile.achievements };
+  const unlocked = [...profile.unlocked];
+  const newAchievements: AchievementUnlock[] = [];
+  let coins = 0;
+  for (const def of ACHIEVEMENTS) {
+    const prog = achievementProgress(def, profile.stats, profile.rating, profile.level);
+    achievements[def.id] = prog;
+    if (prog >= def.goal && !unlocked.includes(def.id)) {
+      unlocked.push(def.id);
+      coins += def.coinReward;
+      newAchievements.push({
+        id: def.id,
+        nameFa: def.nameFa,
+        nameEn: def.nameEn,
+        icon: def.icon,
+        coinReward: def.coinReward,
+      });
+    }
+  }
+  return {
+    profile: { ...profile, achievements, unlocked, coins: profile.coins + coins },
+    newAchievements,
+  };
+}
+
 /** The sticker pack (if any) that unlocking this achievement grants. */
 export function stickerPackForAchievement(achId: string): StickerPackDef | undefined {
   return STICKER_PACKS.find((p) => p.unlockAchievement === achId);

src/lib/online/mock-service.ts

@@ -11,6 +11,7 @@ import {
   addXp,
   applyMatchResult,
   dailyRewardFor,
+  evaluateAchievements,
   faNum,
   xpNeededForLevel,
 } from "./gamification";
@@ -898,7 +899,10 @@ export class MockOnlineService implements OnlineService {
         return { ok: false, messageFa: "سکه کافی نیست", messageEn: "Not enough coins" };
       const pack = XP_PACKS.find((x) => x.id === id)!;
       const lvl = addXp(p.level, p.xp, pack.xp);
-      this.profile = { ...p, coins: p.coins - item.price, level: lvl.level, xp: lvl.xp };
+      const leveled = { ...p, coins: p.coins - item.price, level: lvl.level, xp: lvl.xp };
+      // unlock any level milestones the new level reaches
+      const { profile: evaluated } = evaluateAchievements(leveled);
+      this.profile = evaluated;
       this.saveProfile();
       return { ok: true, profile: this.profile, messageFa: "امتیاز اضافه شد", messageEn: "XP added" };
     }