feat: add streak freeze enhancement with visual dashboard integration

[sudeekshaballanda-hub]

Summary

This PR implements a comprehensive streak freeze enhancement with visual dashboard integration, allowing users to manage and track their freeze tokens directly from the dashboard. It adds database fields, API endpoints, and a UI widget for complete streak freeze functionality.

Closes #2935

---

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that changes existing behavior)
• 📝 Documentation update
• ♻️ Refactor / code cleanup (no functional change)
• ⚡ Performance improvement
• 🔒 Security fix
• 🧪 Tests only

---

What Changed

• Database: Added freeze_tokens_remaining, last_freeze_date, and freeze_history columns to the profiles table with appropriate constraints and indexes
• API Endpoints:
  • GET /api/streak/freeze/status - Returns current freeze status, token count, eligibility, and history
  • POST /api/streak/freeze/apply - Applies a freeze token to the current day with validation
• UI Components: Created FreezeStatusWidget component that displays:
  • Remaining freeze tokens with visual indicator
  • Freeze availability status (Available/Not available)
  • Last freeze date and next eligibility date
  • Recent freeze history (last 3 entries)
  • Interactive "Freeze Streak" button with confirmation
• Dashboard Integration: Added "❄️ Streak Protection" section to the dashboard
• Token Management: Implemented automatic token refresh (2 tokens) on the 1st of each month

---

How to Test

1. Sign in to DevTrack with GitHub OAuth
2. Navigate to the dashboard (/dashboard)
3. Scroll to the "❄️ Streak Protection" section
4. Verify the widget shows:
   • "1 token remaining"
   • Status: "✅ Available"
   • "Freeze Streak" button is clickable
5. Click the "Freeze Streak" button
6. Confirm the success message appears
7. Verify the widget updates to show:
   • "0 tokens remaining"
   • Status: "❌ Not available"
   • Last Freeze Date: Today's date

Expected result: The streak freeze is applied successfully, token count decrements, and the widget updates in real-time.

---

Screenshots / Recordings

Widget Before Freeze

![Before Freeze]

Widget After Freeze

![After Freeze]

State	Screenshot
Before Freeze	[Screenshot 1]
After Freeze	[Screenshot 2]

---

Checklist

• Linked the related issue above
• Self-reviewed my own diff
• No unnecessary console.log, debug code, or commented-out blocks
• npm run lint passes locally
• No TypeScript errors (npm run type-check)
• Added or updated tests where applicable (Tests will be added in follow-up PR)
• Updated documentation / comments if behavior changed

---

Accessibility (UI changes only)

• Keyboard navigation works correctly
• Color contrast meets WCAG AA standard
• ARIA labels / roles added where needed
• Tested on mobile / responsive layout

---

Additional Context

This feature was built as part of the GirlScript Summer of Code (GSSoC) program. The implementation includes:

• Database: Row Level Security (RLS) policies are enabled for data protection
• API Security: All endpoints require authentication and validate user permissions
• Error Handling: Comprehensive error responses for edge cases (no tokens, already frozen today, etc.)
• Performance: Optimized database queries with proper indexing
• User Experience: Loading states, success/error notifications, and clear visual feedback

Follow-up improvements planned:

• Add unit tests for freeze calculation logic
• Add E2E tests for the complete freeze flow
• Heatmap integration to show frozen days distinctly
• Freeze history view with calendar
• Integration with Discord webhook notifications for freeze events

🧪 Test Status

I've written E2E tests for the streak freeze feature (e2e/freeze.spec.ts).

Note on Test Environment:
The current test environment has a pre-existing issue with next-auth and ES modules. This affects all existing E2E tests (e2e/streak.spec.ts, e2e/dashboard.spec.ts, etc.) and is not specific to this PR.

The freeze feature itself has been tested manually and works correctly. I'm happy to help resolve the test environment issue as part of the quality sprint.

📝 Documentation Opportunity

I noticed the test environment is currently broken. I can help:

1. Document the current test environment issues
2. Help fix the next-auth ES module conflict
3. Improve test setup documentation for future contributors

[vercel]

@sudeekshaballanda-hub is attempting to deploy a commit to the legitox's projects Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

GSSoC Label Checklist 🏷️

@Priyanshu-byte-coder — please apply the appropriate labels before merging:

Difficulty (pick one):

• level:beginner — 20 pts
• level:intermediate — 35 pts
• level:advanced — 55 pts
• level:critical — 80 pts

Quality (optional):

• quality:clean — ×1.2 multiplier
• quality:exceptional — ×1.5 multiplier

Validation (required to score):

• gssoc:approved — counts for points
• gssoc:invalid / gssoc:spam / gssoc:ai-slop — does not score

Type labels (type:*) are auto-detected from files and title. Review and adjust if needed.
Points formula: (difficulty × quality_multiplier) + type_bonus

[Priyanshu-byte-coder]

Hi — new features and visual UI additions are currently on hold while we focus on code quality (see discussion #2651). Please hold this PR until the quality sprint wraps up. PRs for tests, refactoring, bug fixes, and docs are welcome in the meantime.

[sudeekshaballanda-hub]

@Priyanshu-byte-coder @Legit-Ox

I've updated this PR with:

• ✅ E2E tests for the freeze feature
• ✅ Documentation of the test environment issues
• ✅ Offer to help with test environment documentation/fixes

Please let me know if there's anything else I can do to help. I'm also available to work on the test environment issues if that would be helpful for the quality sprint.

Thanks for your time! 🙏

[Priyanshu-byte-coder]

New UI/feature PRs are on hold during the code quality sprint — see discussion #2651. PRs for tests, refactoring, bug fixes, docs, and performance are welcome.

[Priyanshu-byte-coder]

New feature/UI PRs are on hold during the code-quality sprint — see discussion #2651. We'll revisit this after the sprint; meanwhile tests, refactors, and bug-fix PRs are very welcome.