Dynamic badges/achievements system with tiered milestones

CLAUDE.md

@@ -165,6 +165,7 @@ Feature design documents and implementation plans are in `docs/features/`. Each
 - **Stripe Payments**: `docs/features/stripe.md` — Stripe integration for premium membership
 - **Opt-Out Features**: `docs/features/opt-out.md` — Streak and ranking opt-out for players
 - **Competitions Management**: `docs/features/competitions-management/` — Community-driven event creation with admin approval, round management, puzzle assignment, table layout planning, and live stopwatch
+- **XP / Levels / Achievements**: `docs/features/xp-levels/` — XP ledger + level curve (1–50), 16 tiered achievements with Achievement Points, weekly content digest, launch runbook. Feature-flagged (`xp-system`, admin-only) until launch; living doc in `docs/features/xp-levels/README.md`
 - **Referral Program**: `docs/features/referral-program.md` — Members earn 10% of referred subscription revenue. No separate entity — `player.referralProgramJoinedAt` + `player.referralProgramSuspended`. Code = player code. Cookie-based + code-input attribution. Payouts per currency, manual admin payout marking
 
 ### Feature Flags

assets/controllers/badge_reveal_controller.js

@@ -0,0 +1,41 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * First-click badge reveal: flips the medallion with a small confetti burst and
+ * persists the reveal. Fire-and-forget POST — the flip is optimistic.
+ */
+export default class extends Controller {
+    static values = {
+        url: String,
+    };
+
+    reveal() {
+        if (this.element.classList.contains('is-revealed')) {
+            return;
+        }
+
+        this.element.classList.add('is-revealed');
+
+        fetch(this.urlValue, { method: 'POST' });
+
+        this.burstConfetti();
+    }
+
+    burstConfetti() {
+        if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+            return;
+        }
+
+        const confetti = document.createElement('span');
+        confetti.className = 'xp-confetti xp-confetti-burst';
+        confetti.setAttribute('aria-hidden', 'true');
+
+        for (let i = 0; i < 10; i++) {
+            confetti.appendChild(document.createElement('i'));
+        }
+
+        this.element.appendChild(confetti);
+
+        setTimeout(() => confetti.remove(), 3000);
+    }
+}

assets/controllers/xp_count_controller.js

@@ -0,0 +1,34 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * One-shot XP counter spin for the launch reveal page: counts from 0 to the
+ * server-rendered value. Reduced motion → the real number shows instantly
+ * (it is already in the markup for no-JS visitors anyway).
+ */
+export default class extends Controller {
+    static values = {
+        amount: Number,
+        duration: { type: Number, default: 1800 },
+    };
+
+    connect() {
+        if (window.matchMedia('(prefers-reduced-motion: reduce)').matches || this.amountValue <= 0) {
+            return;
+        }
+
+        const start = performance.now();
+        const formatter = new Intl.NumberFormat('en-US');
+
+        const tick = (now) => {
+            const progress = Math.min((now - start) / this.durationValue, 1);
+            const eased = 1 - Math.pow(1 - progress, 3);
+            this.element.textContent = formatter.format(Math.round(eased * this.amountValue));
+
+            if (progress < 1) {
+                requestAnimationFrame(tick);
+            }
+        };
+
+        requestAnimationFrame(tick);
+    }
+}

assets/controllers/xp_reveal_finish_controller.js

@@ -0,0 +1,24 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Launch-reveal "continue" button: persists the one-time-seen marker via the
+ * dismiss-hint endpoint, then moves on to the profile.
+ */
+export default class extends Controller {
+    static values = {
+        url: String,
+        redirect: String,
+    };
+
+    async finish() {
+        try {
+            await fetch(this.urlValue, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: 'type=xp_launch_reveal',
+            });
+        } finally {
+            window.location.assign(this.redirectValue);
+        }
+    }
+}

assets/styles/_components.scss

@@ -20,6 +20,7 @@
 @import 'components/breadcrumb';
 @import 'components/pagination';
 @import 'components/badge';
+@import 'components/xp';
 @import 'components/alert';
 @import 'components/list-group';
 @import 'components/close';

assets/styles/components/_badge.scss

@@ -26,3 +26,111 @@
     box-shadow: 0 .5rem 1.125rem -.275rem rgba($black, .25);
   }
 }
+
+
+// Achievement badge medallions
+// --------------------------------------------------
+
+$badge-tier-bronze:     #cd7f32;
+$badge-tier-silver:     #c0c0c0;
+$badge-tier-gold:       #ffd700;
+$badge-tier-platinum:   #e5e4e2;
+$badge-tier-diamond:    #b9f2ff;
+$badge-tier-supporter:  $primary;
+
+.badge-medallion {
+  width: 72px;
+  height: 72px;
+  border-radius: 50%;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: rgba(40, 40, 40, .95);
+  font-weight: 700;
+  font-size: 1.25rem;
+  box-shadow: 0 4px 14px -2px rgba(0, 0, 0, .25), inset 0 -4px 6px rgba(0, 0, 0, .12);
+  border: 3px solid rgba(255, 255, 255, .7);
+  transition: transform .2s ease, box-shadow .2s ease;
+
+  &:hover {
+    transform: translateY(-1px);
+    box-shadow: 0 8px 20px -2px rgba(0, 0, 0, .3), inset 0 -4px 6px rgba(0, 0, 0, .12);
+  }
+}
+
+.badge-medallion-sm {
+  width: 48px;
+  height: 48px;
+  font-size: .95rem;
+}
+
+.badge-medallion-tier {
+  font-family: Georgia, serif;
+  letter-spacing: .02em;
+  text-shadow: 0 1px 0 rgba(255, 255, 255, .45);
+}
+
+.badge-tier-bronze {
+  background: radial-gradient(circle at 35% 30%, lighten($badge-tier-bronze, 18%), $badge-tier-bronze 70%);
+  color: #3a1d00;
+}
+
+.badge-tier-silver {
+  background: radial-gradient(circle at 35% 30%, lighten($badge-tier-silver, 12%), $badge-tier-silver 70%);
+  color: #2a2a2a;
+}
+
+.badge-tier-gold {
+  background: radial-gradient(circle at 35% 30%, lighten($badge-tier-gold, 10%), $badge-tier-gold 70%);
+  color: #3f2d00;
+}
+
+.badge-tier-platinum {
+  background: radial-gradient(circle at 35% 30%, lighten($badge-tier-platinum, 4%), $badge-tier-platinum 70%);
+  color: #2a2a2a;
+}
+
+.badge-tier-diamond {
+  background: radial-gradient(circle at 35% 30%, lighten($badge-tier-diamond, 4%), $badge-tier-diamond 70%);
+  color: #004854;
+}
+
+.badge-tier-supporter {
+  background: radial-gradient(circle at 35% 30%, lighten($badge-tier-supporter, 15%), $badge-tier-supporter 70%);
+  color: #fff;
+}
+
+.badge-locked {
+  .badge-medallion {
+    filter: grayscale(100%);
+    opacity: .45;
+    box-shadow: none;
+
+    &:hover {
+      transform: none;
+    }
+  }
+}
+
+.badge-new-pill {
+  position: absolute;
+  top: -6px;
+  right: -8px;
+  font-size: .65rem;
+  padding: .2em .45em;
+  box-shadow: 0 2px 6px rgba(0, 0, 0, .25);
+  animation: badge-new-pulse 1.6s ease-in-out infinite;
+}
+
+@keyframes badge-new-pulse {
+  0%, 100% {
+    transform: scale(1);
+  }
+  50% {
+    transform: scale(1.08);
+  }
+}
+
+.badge-earned {
+  min-width: 90px;
+}