[FEATURE] "Ghost City" Mode for Zero Contributions (JhaSourav07#114)

## Description

Fixes JhaSourav07#97

1. Ghost City Mode: Zero-contribution days now show as thin 4px
blueprint foundations to maintain a premium 3D look across the entire
calendar.
2. Auto-Theme Support: Refactored the logic so these new foundations
automatically switch colors between Dark and Light mode.
3. Modular Rendering: Moved tower calculations into helper functions
(computeTowers, computeFaceOpacity) to make the code cleaner and easier
to manage.
4. Upstream Sync: Integrated the changes with the latest project updates
(Auto-Theme and Dynamic Fonts) to ensure no features were broken.
5. Documentation: Preserved all original maintainer comments and added
new JSDoc for the refactored functions.

## Pillar

- [ ] 🎨 Pillar 1 — New Theme Design
- [x ] 📐 Pillar 2 — Geometric SVG Improvement
- [ ] 🕐 Pillar 3 — Timezone Logic Optimization
- [ ] 🛠️ Other (Bug fix, refactoring, docs)

## Visual Preview

Preview in the comments


## 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).

Author: JhaSourav07

README.md

@@ -32,7 +32,11 @@ Most GitHub stat badges are **flat**. Flat bars, flat text, flat colors. They bl
 
 **CommitPulse is different.**
 
-We render your contribution data as a **3D Isometric City** — a grid of glowing towers where each column's height is directly proportional to your commit count that day. The more you grind, the taller your skyline grows. This is not decoration. This is a **live, animated data visualization** that makes your dedication impossible to ignore.
+We render your contribution data as a **3D Isometric City** — a grid of glowing towers where each column's height is directly proportional to your commit count that day. The more you grind, the taller your skyline grows.
+
+**Ghost City Architecture:** In this mode, zero-contribution days aren't just empty space. They are rendered as thin, wireframe-style **blueprint foundations** (4px high). This gives your commit landscape a structured, architectural "work-in-progress" look even during rest days, maintaining the premium 3D aesthetic across the entire calendar.
+
+This is not decoration. This is a **live, animated data visualization** that makes your dedication impossible to ignore.
 
 ### Why Isometric > Flat
 

lib/svg/generator.test.ts

@@ -202,4 +202,51 @@ describe('generateSVG', () => {
       expect(svg).toContain('prefers-reduced-motion');
     });
   });
+
+  // Ghost City Placeholder Mode tests
+  describe('Ghost City Mode', () => {
+    const emptyCalendar: ContributionCalendar = {
+      totalContributions: 0,
+      weeks: [
+        {
+          contributionDays: [
+            { contributionCount: 0, date: '2024-06-10' },
+            { contributionCount: 0, date: '2024-06-11' },
+          ],
+        },
+      ],
+    };
+
+    const activeCalendar: ContributionCalendar = {
+      totalContributions: 5,
+      weeks: [
+        {
+          contributionDays: [
+            { contributionCount: 0, date: '2024-06-10' },
+            { contributionCount: 5, date: '2024-06-11' },
+          ],
+        },
+      ],
+    };
+
+    it('renders Ghost City blueprint when user has 0 total contributions', () => {
+      const svg = generateSVG(mockStats, { user: 'avi' } as unknown as BadgeParams, emptyCalendar);
+
+      // Should contain wireframe strokes
+      expect(svg).toContain('stroke-width="0.5"');
+      expect(svg).toContain('stroke-opacity="0.3"');
+      // Should use the GHOST_HEIGHT_PX which is 4 (10 + 4 = 14)
+      expect(svg).toContain('L0 14 L-16 4 L-16 0 Z');
+    });
+
+    it('does not render Ghost City when user has active contributions', () => {
+      const svg = generateSVG(mockStats, { user: 'avi' } as unknown as BadgeParams, activeCalendar);
+
+      // Should NOT contain wireframe strokes
+      expect(svg).not.toContain('stroke-width="0.5"');
+      expect(svg).not.toContain('stroke-opacity="0.3"');
+      // Active mode empty days should have h=0 (10 + 0 = 10)
+      expect(svg).toContain('L0 10 L-16 0 L-16 0 Z');
+    });
+  });
 });