feat: add dynamic contribution shading and volumetric gradients (JhaSourav07#808)

## Description
Fixes JhaSourav07#793

This PR implements premium dynamic contribution-level color shading,
multi-accent color mapping, and volumetric tower gradients on the 3D
contribution monolith.

## Changes Made
- **API Parameters:** Added `shading`, `gradient`, and array-support for
`accent` parameters in `BadgeParams` and `streakParamsSchema`.
- **Tower Math:** Integrated quartile calculation logic (1 to 4) inside
`computeTowers` based on maximum commit counts.
- **Volumetric Gradients:** Added dynamic SVG `<linearGradient>`
injection fading upward from the background color to the tower's
level-specific accent color. Left and right faces use the gradient fill,
while the top cap retains a solid glow.
- **Multi-accent Mapping:** Allowed comma-separated color lists under
the `accent` parameter mapping directly to quartile levels 1-4.
- **Safety Refactors:** Resolved array mapping in `generateMonthlySVG`
to safe fallback strings.
- **Testing:** Added 4 comprehensive test suites in
`lib/svg/generator.test.ts` covering shading, disabling shading,
gradients, and multi-accent arrays.

## Pillar
- [x] 🎨 Pillar 1 — New Theme Design
- [x] 📐 Pillar 2 — Geometric SVG Improvement
- [ ] 🕐 Pillar 3 — Timezone Logic Optimization
- [ ] 🛠️ Other

## Visual Preview
- Flat Shading (`shading=true`): Towers fade into the floor for
lower-intensity contribution days.
- Volumetric Gradients (`gradient=true`): Sleek vertical linear
gradients fading from the background up to the tower tops.

## Checklist before requesting a review:
- [x] I have read the `CONTRIBUTING.md` file.
- [x] I have tested these changes locally
(`localhost:3000/api/streak?user=YOUR_USERNAME`).
- [x] I have run `npm run format` and `npm run lint` locally and
resolved all errors (CI will fail otherwise).
- [x] My commits follow the Conventional Commits format (e.g.,
`feat(themes): ...`, `fix(calculate): ...`).
- [x] I have updated `README.md` if I added a new theme or URL
parameter.
- [x] I have started the repo.
- [x] I have made sure that i have only one commit to merge in this PR.
- [x] The SVG output matches the CommitPulse "premium quality" aesthetic
standard (no raw elements, smooth animations, correct fonts).
- [x] (Recommended) I joined the CommitPulse Discord community for
contributor discussions, mentorship, and faster PR support.
### Multi-accent quartile coloring
(`accent=ff4444,ff8800,ffcc00,00ffaa`)
<img width="768" height="541" alt="image"
src="https://github.com/user-attachments/assets/d6b72f3e-0ed3-48e3-8d9f-c97549d8147d"
/>


### Gradient volumetric effect (`gradient=true`)
<img width="767" height="534" alt="image"
src="https://github.com/user-attachments/assets/b81776ba-5a9f-4816-879e-989529d17ddd"
/>

### Combined (`gradient=true&accent=ff4444,ff8800,ffcc00,00ffaa`)
<img width="749" height="526" alt="image"
src="https://github.com/user-attachments/assets/89338fc9-8901-46f3-9f19-971d5669bf8e"
/>

Author: Sahitya3105

app/api/streak/route.ts

@@ -62,6 +62,8 @@ export async function GET(request: Request) {
       labels,
       labelColor,
       versus,
+      shading,
+      gradient,
     } = parseResult.data;
 
     const themeName = theme || 'dark';
@@ -133,6 +135,8 @@ export async function GET(request: Request) {
       labels,
       labelColor,
       versus,
+      shading,
+      gradient,
     };
 
     let calendar;
@@ -204,7 +208,13 @@ function buildErrorResponse(error: unknown, parseResult: ParseResult): NextRespo
     message.toLowerCase().includes('could not resolve');
 
   const errBg = `#${(parseResult.success && parseResult.data.bg) || '0d1117'}`;
-  const errAccent = `#${(parseResult.success && parseResult.data.accent) || '58a6ff'}`;
+  const errAccent = `#${
+    (parseResult.success &&
+      (Array.isArray(parseResult.data.accent)
+        ? parseResult.data.accent[parseResult.data.accent.length - 1]
+        : parseResult.data.accent)) ||
+    '58a6ff'
+  }`;
   const errText = `#${(parseResult.success && parseResult.data.text) || 'c9d1d9'}`;
   const errRadius = parseResult.success
     ? (() => {

components/dashboard/ComparisonStatsCard.test.tsx

@@ -138,12 +138,6 @@ describe('ComparisonStatsCard', () => {
       />
     );
 
-    const progressSegments = container.querySelectorAll(
-      '.w-full.bg-gray-700\\/50 div, .relative div'
-    );
-
-    const allDivs = Array.from(container.querySelectorAll('div'));
-
     const emeraldElement =
       container.querySelector('[className*="emerald"]') ||
       container.querySelector('.text-emerald-400');

lib/export3d.test.ts

@@ -21,6 +21,7 @@ describe('generateMonolithSTL', () => {
         strokeWidth: 1,
         row: 0,
         col: 0,
+        intensityLevel: 2,
       },
       {
         x: 0,
@@ -37,6 +38,7 @@ describe('generateMonolithSTL', () => {
         strokeWidth: 1,
         row: 1,
         col: 1,
+        intensityLevel: 0,
       },
     ];
 
@@ -67,6 +69,7 @@ it('generates structurally valid ASCII STL facets', () => {
       strokeWidth: 1,
       row: 0,
       col: 0,
+      intensityLevel: 2,
     },
   ];
 

lib/svg/generator.test.ts

@@ -811,6 +811,158 @@ describe('generateMonthlySVG', () => {
   });
 });
 
+describe('shading and gradients', () => {
+  const mockStats: StreakStats = {
+    currentStreak: 5,
+    longestStreak: 10,
+    totalContributions: 100,
+    todayDate: '2024-06-12',
+  };
+
+  const mockCalendar = {
+    weeks: [
+      {
+        contributionDays: [
+          { contributionCount: 0, date: '2024-06-10' },
+          { contributionCount: 5, date: '2024-06-11' },
+          { contributionCount: 15, date: '2024-06-12' },
+        ],
+      },
+    ],
+  } as ContributionCalendar;
+
+  it('renders linearGradient definitions when gradient=true', () => {
+    const svg = generateSVG(
+      mockStats,
+      { user: 'avi', gradient: true } as unknown as BadgeParams,
+      mockCalendar
+    );
+    expect(svg).toContain('<linearGradient id="tower-grad-level-1"');
+    expect(svg).toContain('<linearGradient id="tower-grad-level-4"');
+    expect(svg).toContain('fill="url(#tower-grad-level-');
+  });
+
+  it('does not render linearGradient definitions when gradient=false', () => {
+    const svg = generateSVG(
+      mockStats,
+      { user: 'avi', gradient: false } as unknown as BadgeParams,
+      mockCalendar
+    );
+    expect(svg).not.toContain('<linearGradient id="tower-grad-level-1"');
+  });
+
+  it('supports mapping colors in array accent lists to towers', () => {
+    const calendarWithAllQuartiles = {
+      weeks: [
+        {
+          contributionDays: [
+            { contributionCount: 2, date: '2024-06-10' }, // Level 1 (2/15 <= 0.25)
+            { contributionCount: 6, date: '2024-06-11' }, // Level 2 (6/15 <= 0.5)
+            { contributionCount: 10, date: '2024-06-12' }, // Level 3 (10/15 <= 0.75)
+            { contributionCount: 15, date: '2024-06-13' }, // Level 4
+          ],
+        },
+      ],
+    } as ContributionCalendar;
+
+    const svg = generateSVG(
+      mockStats,
+      { user: 'avi', accent: ['111111', '222222', '333333', '444444'] } as unknown as BadgeParams,
+      calendarWithAllQuartiles
+    );
+    expect(svg).toContain('fill="#111111"');
+    expect(svg).toContain('fill="#222222"');
+    expect(svg).toContain('fill="#333333"');
+    expect(svg).toContain('fill="#444444"');
+  });
+
+  it('gracefully handles and clamps accent color arrays with fewer than 4 items without crashing', () => {
+    const calendarWithAllQuartiles = {
+      weeks: [
+        {
+          contributionDays: [
+            { contributionCount: 2, date: '2024-06-10' },
+            { contributionCount: 6, date: '2024-06-11' },
+            { contributionCount: 10, date: '2024-06-12' },
+            { contributionCount: 15, date: '2024-06-13' },
+          ],
+        },
+      ],
+    } as ContributionCalendar;
+
+    const svg = generateSVG(
+      mockStats,
+      { user: 'avi', accent: ['111111'] } as unknown as BadgeParams,
+      calendarWithAllQuartiles
+    );
+    expect(svg).toContain('fill="#111111"');
+  });
+});
+
+describe('shading', () => {
+  // A calendar with a mix of contribution counts to produce towers at different
+  // intensity levels — needed so that shading multipliers actually apply.
+  const shadingCalendar = {
+    weeks: [
+      {
+        contributionDays: [
+          { contributionCount: 2, date: '2024-06-10' }, // low intensity
+          { contributionCount: 10, date: '2024-06-11' }, // mid intensity
+          { contributionCount: 15, date: '2024-06-12' }, // high intensity
+        ],
+      },
+    ],
+  } as ContributionCalendar;
+
+  const shadingStats: StreakStats = {
+    currentStreak: 3,
+    longestStreak: 10,
+    totalContributions: 27,
+    todayDate: '2024-06-12',
+  };
+
+  it('applies reduced face-opacity (shading) when shading is not disabled', () => {
+    // With shading on, low-intensity towers use opacity multiplier 0.4, so their
+    // face-opacity should be lower than the unshaded base value.
+    const svgShading = generateSVG(
+      shadingStats,
+      { user: 'avi', shading: true } as unknown as BadgeParams,
+      shadingCalendar
+    );
+    // The shaded SVG should still contain the tower paths
+    expect(svgShading).toContain('class="cp-tower"');
+    // For level 1 (mult=0.4), base top face opacity 0.7 becomes 0.28
+    // Check for that specific derived value to ensure shading actually multiplied it.
+    expect(svgShading).toContain('fill-opacity="0.28"');
+  });
+
+  it('does not apply shading multipliers when shading=false', () => {
+    const svgShading = generateSVG(
+      shadingStats,
+      { user: 'avi', shading: true } as unknown as BadgeParams,
+      shadingCalendar
+    );
+    const svgNoShading = generateSVG(
+      shadingStats,
+      { user: 'avi', shading: false } as unknown as BadgeParams,
+      shadingCalendar
+    );
+    // The two renders must differ — shading changes face opacities
+    expect(svgShading).not.toBe(svgNoShading);
+  });
+
+  it('falls back to default accent #00ffaa when accent array is empty', () => {
+    const svg = generateSVG(
+      shadingStats,
+      // Simulate what validation returns for accent=,,, (empty array is
+      // now normalised to undefined, but if it somehow reached the renderer
+      // as [] the fallback should still fire without crashing).
+      { user: 'avi', accent: [] } as unknown as BadgeParams,
+      shadingCalendar
+    );
+    expect(svg).toContain('00ffaa');
+  });
+});
 describe('escapeXML', () => {
   it('escapes ampersands (&)', () => {
     expect(escapeXML('foo & bar')).toBe('foo &amp; bar');