Merge remote-tracking branch 'origin/main' into fix/api-student-resume-upload-timezone

Author: ashishraj1504

.env.local.example

@@ -57,3 +57,10 @@ NEXT_ALLOWED_DEV_ORIGINS=
 # Find your GitHub user ID at https://api.github.com/users/<username> (the "id" field).
 # Example: ENTERPRISE_ADMIN_GITHUB_IDS=12345678,87654321
 ENTERPRISE_ADMIN_GITHUB_IDS=
+
+# Spotify Integration (Optional)
+# Required for the "Currently Playing" SVG feature.
+# Follow the setup guide in the documentation to get these credentials.
+SPOTIFY_CLIENT_ID=
+SPOTIFY_CLIENT_SECRET=
+SPOTIFY_REFRESH_TOKEN=

.github/workflows/ci.yml

@@ -47,6 +47,14 @@ jobs:
       - name: Run Unit Tests (Vitest)
         run: npm run test:coverage
 
+      - name: Upload Visual Regression Diffs
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: visual-test-diffs
+          path: tests/visual/diffs/
+          if-no-files-found: ignore
+
   build:
     name: Production Build
     runs-on: ubuntu-latest

.gitignore

@@ -12,6 +12,7 @@
 
 # testing
 /coverage
+/tests/visual/diffs/
 
 # next.js
 /.next/

README.md

@@ -139,18 +139,35 @@ Transform your GitHub contribution history into a cinematic 3D monolith.
 | `monokai`          | Classic vibrant dark         | `272822` | `a6e22e` | `f8f8f2` |
 | `midnight_ocean`   | Deep navy bioluminescent     | `020c1b` | `0af5ff` | `ccd6f6` |
 | `india`            | Saffron & India green        | `0a0a0a` | `FF9933` | `ffffff` |
+| `ocean`            | Deep sea teal & navy         | `0a192f` | `64ffda` | `ccd6f6` |
+| `sunset`           | Warm dusk orange             | `1a0a0a` | `ff6b35` | `ffd6c0` |
+| `forest`           | Emerald woodland green       | `0d1f0d` | `39d353` | `c8f0c8` |
+| `rose`             | Blush pink romance           | `1f0d14` | `ff6b9d` | `f0c8d4` |
+| `nord`             | Arctic frost blue            | `2e3440` | `88c0d0` | `d8dee9` |
+| `synthwave`        | 80s retro pink glow          | `0d0221` | `ff2d78` | `f8f8f2` |
+| `aurora_cyberpunk` | Aurora violet neon           | `090B13` | `9D5CFF` | `EAF2FF` |
+| `catppuccin_latte` | Pastel latte light           | `eff1f5` | `1e66f5` | `4c4f69` |
+| `solarized_light`  | Warm solarized light         | `fdf6e3` | `268bd2` | `586e75` |
+| `gruvbox_light`    | Retro warm light             | `fbf1c7` | `d65d0e` | `3c3836` |
+| `nord_light`       | Arctic frost light           | `eceff4` | `5e81ac` | `2e3440` |
+| `cyberpunk`        | Neon yellow cyberpunk        | `fce22a` | `ff003c` | `111111` |
+| `cyberpunk_neon`   | Electric cyan neon           | `0d0d14` | `ff0055` | `00f3ff` |
+| `enterprise`       | Professional indigo dark     | `1a1a2e` | `6366f1` | `e2e8f0` |
 
 > **`auto` uses CSS `@media (prefers-color-scheme)`** inside the SVG so the badge switches between the `light` and `dark` palettes based on the viewer's OS setting — no JavaScript required. This is ideal for GitHub profile READMEs where visitors may use either mode.
 
 For all URL parameters and configuration possibilities (including grace periods, custom fonts, timezone overrides, versus comparison mode, heatmap view, LOC mode, and layout dimensions), check out the **[🎨 Customization Guide & Parameters](docs/customization.md)**.
 
+For advanced usage examples including custom gradient backgrounds, multi-user comparisons, organization dashboards, and custom date ranges, see the **[🚀 Advanced Usage Examples](docs/customization.md#-advanced-usage-examples)** section in the customization guide.
+
 ---
 
 ## ✨ Features
 
 CommitPulse transforms GitHub contribution data into visually engaging and highly customizable SVG badges.
 
 - **🎨 Theme & Customization**: Multiple built-in themes, custom colors (`bg`, `accent`, `text`), dynamic font selection, adjustable dimensions, border radius, opacity, and system-aware `auto` light/dark theme.
+- **🎵 Spotify "Currently Playing"**: Showcase your current Spotify playback on your GitHub profile with a customizable, near real-time SVG card.
 - **📈 Contribution Analytics**: Current streak and longest streak tracking, monthly contribution summaries, historical year-by-year viewing, and custom grace period configurations.
 - **🔥 Visualization Modes**: Isometric 3D monolith rendering (with ghost city blueprint foundations), GitHub-style heatmap, monthly statistics view, and radar chart view.
 - **🌍 Localization & Accessibility**: Multi-language support (e.g. English, Hindi, Simplified Chinese, Portuguese), timezone-aware calculations, and high-contrast accessibility themes.
@@ -166,6 +183,7 @@ To keep the repository clean and readable, technical details have been modulariz
 - **[🎨 Customization Guide & Parameters](docs/customization.md)**: Explore the list of over 30 URL parameters including `theme`, `view` (e.g. `skyline`, `heatmap`, `radar`, `monthly`), `radius`, `grace`, `tz`, `entrance`, `versus`, and layout dimensions to style your monolith.
 - **[🏛️ Architecture & Design Philosophy](docs/architecture.md)**: Read about why we built isometric 3D monolith landscapes instead of flat meters, and check out our Next.js 16 Edge computing pipeline.
 - **[🚀 Self-Hosting & Deployment](docs/self_hosting.md)**: Step-by-step instructions to clone, configure `.env.local` with GitHub Personal Access Tokens (PAT), set up MongoDB tracking, and deploy to Vercel with one click.
+- **[🎵 Spotify Setup Guide](docs/SPOTIFY_SETUP.md)**: Instructions for setting up Spotify integration for the Currently Playing feature.
 - **[🤖 Automated Contributor Workflow](docs/contributor_workflow.md)**: Overview of GSSoC contribution automation, self-claiming comments `/claim`, anti-hoarding rules, stale unassign scripts, and Gemini AI-powered semantic issue duplication check.
 - **[🎯 Real-Time Accuracy & Caching](docs/accuracy.md)**: Deep dive into the "off-by-N contributions" problem and how CommitPulse solves it with UTC midnight CDN expiration and no-store GraphQL fetches.
 - **[❓ FAQ & Troubleshooting](docs/faq.md)**: Answers to common questions regarding timezone overrides, private contribution visibility, GitHub API rate limits, and troubleshooting.

THEMES.md

@@ -41,6 +41,7 @@ https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&theme=<slug>
 | monokai          | `#272822`  | `#f8f8f2` | `#a6e22e` |
 | retro-terminal   | `#000000`  | `#00ff41` | `#00ff41` |
 | midnight_ocean   | `#020c1b`  | `#ccd6f6` | `#0af5ff` |
+| ayu_mirage       | `#212733`  | `#D9D7CE` | `#FFCC66` |
 
 ---
 
@@ -394,6 +395,16 @@ https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&theme=<slug>
 
 ---
 
+### Ayu Mirage
+
+![ayu_mirage](https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=ayu_mirage)
+
+| Parameter | Value  |
+| --------- | ------ |
+| `bg`      | 212733 |
+| `text`    | D9D7CE |
+| `accent`  | FFCC66 |
+
 ## Custom Theme
 
 Not finding what you want? Build your own using raw color parameters - all values are hex codes **without** the `#` prefix:

app/(root)/dashboard/[username]/page.tsx

@@ -92,6 +92,7 @@ export default async function DashboardPage({
     month?: string;
     from?: string;
     to?: string;
+    excludeBots?: string;
   }>;
 }) {
   const { username } = await params;
@@ -116,9 +117,11 @@ async function DashboardContent({
     month?: string;
     from?: string;
     to?: string;
+    excludeBots?: string;
   };
 }) {
   const bypassCache = searchParams?.refresh === 'true';
+  const excludeBots = searchParams?.excludeBots === 'true';
   const compareUsername = searchParams?.compare;
   const period = resolveDashboardPeriod({
     year: searchParams?.year,
@@ -137,6 +140,7 @@ async function DashboardContent({
       to: period.to,
       rangeLabel: period.label,
       token: userToken,
+      excludeBots,
     });
   } catch (error) {
     if (error instanceof Error && error.message.includes('not found')) {
@@ -176,6 +180,7 @@ async function DashboardContent({
       compareData = await getFullDashboardData(compareUsername, {
         bypassCache,
         token: userToken,
+        excludeBots,
       });
     } catch {
       compareData = null;

app/(root)/dashboard/layout.error-resilience.test.tsx

@@ -0,0 +1,60 @@
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+import React, { Component, ReactNode, ErrorInfo } from 'react';
+import DashboardLayout from './layout';
+
+vi.mock('sonner', () => ({
+  Toaster: () => <div data-testid="toaster" />,
+}));
+
+class TestErrorBoundary extends Component<{ children: ReactNode }, { hasError: boolean }> {
+  constructor(props: { children: ReactNode }) {
+    super(props);
+    this.state = { hasError: false };
+  }
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    // catch silently for tests
+  }
+  render() {
+    if (this.state.hasError) {
+      return <div>Test Fallback UI</div>;
+    }
+    return this.props.children;
+  }
+}
+
+const ThrowError = () => {
+  throw new Error('Hydration error simulated');
+};
+
+describe('DashboardLayout - Error Resilience', () => {
+  it('prevents layout structural crash when child components throw errors', () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    render(
+      <TestErrorBoundary>
+        <DashboardLayout>
+          <ThrowError />
+        </DashboardLayout>
+      </TestErrorBoundary>
+    );
+
+    expect(screen.getByText('Test Fallback UI')).toBeInTheDocument();
+
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('renders gracefully with fallback UI placeholders during hydration', () => {
+    render(
+      <DashboardLayout>
+        <div data-testid="hydration-fallback">Loading layout skeleton...</div>
+      </DashboardLayout>
+    );
+
+    expect(screen.getByTestId('hydration-fallback')).toBeInTheDocument();
+    expect(screen.getByTestId('toaster')).toBeInTheDocument();
+  });
+});

app/(root)/dashboard/layout.mock-integrations.test.tsx

@@ -0,0 +1,54 @@
+import { render, screen, act } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import DashboardLayout from './layout';
+import React from 'react';
+
+vi.mock('sonner', () => ({
+  Toaster: () => <div data-testid="toaster" />,
+}));
+
+describe('DashboardLayout - mock integrations', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  it('renders children asynchronously resolving from a mocked service layer', async () => {
+    const MockAsyncChild = () => {
+      const [data, setData] = React.useState<string | null>(null);
+      React.useEffect(() => {
+        setTimeout(() => setData('Async Data Loaded'), 100);
+      }, []);
+      return <div data-testid="async-child">{data || 'Loading...'}</div>;
+    };
+
+    render(
+      <DashboardLayout>
+        <MockAsyncChild />
+      </DashboardLayout>
+    );
+
+    expect(screen.getByTestId('async-child')).toHaveTextContent('Loading...');
+
+    await act(async () => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(screen.getByTestId('async-child')).toHaveTextContent('Async Data Loaded');
+  });
+
+  it('renders correctly with a local cache stub', () => {
+    const cachedData = { user: 'Test User', cached: true };
+    render(
+      <DashboardLayout>
+        <div data-testid="cache-child">{cachedData.user}</div>
+      </DashboardLayout>
+    );
+    expect(screen.getByTestId('cache-child')).toHaveTextContent('Test User');
+    expect(screen.getByTestId('toaster')).toBeInTheDocument();
+  });
+});

app/(root)/dashboard/layout.timezone-boundaries.test.tsx

@@ -0,0 +1,53 @@
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import DashboardLayout from './layout';
+import { mockTimezone, restoreTimezone } from '@/test-utils/timezone-mock';
+
+vi.mock('sonner', () => ({
+  Toaster: () => <div data-testid="toaster" />,
+}));
+
+describe('DashboardLayout - Timezone Boundaries', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    restoreTimezone();
+  });
+
+  it('maintains structural integrity across varying timezones', () => {
+    const timezones = ['America/New_York', 'Asia/Kolkata', 'Asia/Tokyo'] as const;
+
+    for (const tz of timezones) {
+      mockTimezone(tz);
+
+      const { unmount } = render(
+        <DashboardLayout>
+          <div>Timezone Content: {tz}</div>
+        </DashboardLayout>
+      );
+
+      expect(screen.getByText(`Timezone Content: ${tz}`)).toBeInTheDocument();
+      expect(screen.getByRole('main')).toHaveClass('max-w-[1600px]', 'mx-auto', 'min-h-screen');
+
+      unmount();
+      restoreTimezone();
+    }
+  });
+
+  it('handles leap year boundaries correctly', () => {
+    vi.setSystemTime(new Date('2024-02-29T12:00:00Z'));
+
+    render(
+      <DashboardLayout>
+        <div>Leap Year Content</div>
+      </DashboardLayout>
+    );
+
+    expect(screen.getByText('Leap Year Content')).toBeInTheDocument();
+    expect(screen.getByTestId('toaster')).toBeInTheDocument();
+  });
+});

app/(root)/dashboard/org/[orgname]/page.tsx

@@ -11,6 +11,7 @@ import CommitClock from '@/components/dashboard/CommitClock';
 import Heatmap from '@/components/dashboard/Heatmap';
 import AIInsights from '@/components/dashboard/AIInsights';
 import Achievements from '@/components/dashboard/Achievements';
+import BotFilterToggle from '@/components/dashboard/BotFilterToggle';
 import { getOrgDashboardData, buildCommitClock, generateAchievements } from '@/lib/github';
 import logger from '@/lib/logger';
 import { getUserGitHubToken } from '@/lib/githubtoken';
@@ -50,17 +51,18 @@ export default async function OrgDashboardPage({
   searchParams,
 }: {
   params: Promise<{ orgname: string }>;
-  searchParams: Promise<{ refresh?: string }>;
+  searchParams: Promise<{ refresh?: string; excludeBots?: string }>;
 }) {
   const { orgname } = await params;
   const refreshParams = await searchParams;
   const bypassCache = refreshParams?.refresh === 'true';
+  const excludeBots = refreshParams?.excludeBots === 'true';
   const userToken = await getUserGitHubToken();
 
   let data;
 
   try {
-    data = await getOrgDashboardData(orgname, { bypassCache, token: userToken });
+    data = await getOrgDashboardData(orgname, { bypassCache, token: userToken, excludeBots });
   } catch (error) {
     logger.error('Failed to load organization page', {
       error,
@@ -144,6 +146,7 @@ export default async function OrgDashboardPage({
               languages: [], // Orgs skip language donut chart for now
             }}
           />
+          <BotFilterToggle />
           <Achievements achievements={achievements} />
         </aside>