Merge branch 'main' into refactor/extract-renderRadarScan-helper

Author: prachimaskar

.github/workflows/ci.yml

@@ -5,6 +5,7 @@ on:
     branches: [main, dev]
   pull_request:
     branches: [main, dev]
+  merge_group: # Run CI on the merged commit before it lands on main
 
 jobs:
   quality:

.github/workflows/conflict-notifier.yml

@@ -81,7 +81,7 @@ jobs:
                   });
                 }
 
-                // Check existing comments to enforce a 2-hour notification gap
+                // Check existing comments to enforce a 24-hour notification gap
                 const { data: comments } = await github.rest.issues.listComments({
                   owner: context.repo.owner,
                   repo: context.repo.repo,
@@ -101,8 +101,8 @@ jobs:
                   const lastComment = conflictComments[conflictComments.length - 1];
                   const lastCommentTime = new Date(lastComment.created_at).getTime();
                   const nowTime = new Date().getTime();
-                  const TWO_HOURS_MS = 2 * 60 * 60 * 1000;
-                  if (nowTime - lastCommentTime >= TWO_HOURS_MS) {
+                  const TWENTY_FOUR_HOURS_MS = 24 * 60 * 60 * 1000;
+                  if (nowTime - lastCommentTime >= TWENTY_FOUR_HOURS_MS) {
                     shouldComment = true;
                   }
                 }

CONTRIBUTING.md

@@ -9,7 +9,7 @@
 
 - [The Standard We Hold](#-the-standard-we-hold)
 - [Local Setup](#-local-setup)
-- [Testing Your Changes](#-testing-your-changes)
+- [Testing & Previewing Your Changes](#-testing--previewing-your-changes)
 - [What to Contribute](#-what-to-contribute)
 - [Automated Issue Management & Claiming](#-automated-issue-management--claiming)
 - [Branch & Commit Conventions](#-branch--commit-conventions)
@@ -89,13 +89,13 @@ http://localhost:3000/api/streak?user=YOUR_GITHUB_USERNAME
 
 ---
 
-## 🧪 Testing Your Changes
+## 🧪 Testing & Previewing Your Changes
 
-This section covers everything you need to verify your changes work correctly **before opening a PR**. There are two layers of testing: visual browser preview and the automated test suite.
+Before opening a PR, every contributor is expected to verify their changes locally across three areas: **visual SVG output**, **unit tests**, and **branch coverage**. This section explains how to do all three.
 
 ### 1. Visual Browser Preview
 
-With your dev server running (`npm run dev`), open your browser and visit these URLs to preview the SVG output directly:
+With your dev server running (`npm run dev`), open your browser and visit these URLs to preview the SVG output directly — **open them as raw URLs, not embedded in an `<img>` tag or Markdown preview**:
 
 **Standard badge — valid username:**
 
@@ -127,46 +127,90 @@ http://localhost:3000/api/streak?user=vivek%20Sangani
 http://localhost:3000/api/streak?user=xyzabc999notreallll
 ```
 
+**Useful DevTools tricks:**
+
+- **Inspect SVG structure:** Open DevTools (`Cmd+Option+I` / `F12`) → Elements panel → expand the `<svg>` node to inspect every path, rect, and text element
+- **Force a fresh fetch:** Add `&refresh=true` to bypass the cache: `http://localhost:3000/api/streak?user=YOUR_GITHUB_USERNAME&refresh=true`
+- **Test different params live:** `?theme=obsidian`, `?size=large`, `?grace=2`, `?autoTheme=true`
+
 > **⚠️ Browser XML error warning:** If your browser shows an `EntityRef: expecting ';'` error instead of rendering the SVG, it means an unescaped `&` character exists somewhere in the SVG output. All `&` characters inside SVG `<style>` blocks (e.g. in Google Fonts `@import` URLs) must be written as `&amp;`. Check `lib/svg/generator.ts` for any raw `&` in template literals.
 
 > **💡 Tip:** For a cleaner SVG preview, open the URL in **Firefox** — it renders SVG directly in the browser with no wrapper page. Chrome wraps it in an XML viewer which can show false parse warnings.
 
-### 2. Running the Vitest Test Suite
+### 2. Offline SVG Inspection with SVG Viewer
+
+When you cannot run a dev server — or you want to inspect the raw SVG geometry in isolation — use **[SVG Viewer](https://www.svgviewer.dev/)**.
+
+**Step-by-step:**
+
+1. With the dev server running, open the badge URL in your browser
+2. Right-click anywhere on the page → **View Page Source** (`Cmd+U` / `Ctrl+U`)
+3. Select all (`Cmd+A`) → Copy (`Cmd+C`)
+4. Go to [https://www.svgviewer.dev/](https://www.svgviewer.dev/)
+5. Paste the SVG source into the left panel — the right panel renders it instantly
+
+**What to check in SVG Viewer:**
+
+- Tower geometry is correctly positioned on the isometric grid
+- No overlapping paths or misaligned elements
+- Text labels are readable and not clipped by the SVG boundary
+- Glow filter (`<feGaussianBlur>`) renders at the correct intensity
+- The `<title>` accessibility tag is present on every tower group (required by CONTRIBUTING.md a11y rules)
+
+### 3. Running the Vitest Test Suite
 
 CommitPulse uses **Vitest** for unit and integration tests. Run the full test suite with:
 
 ```bash
+# Run all tests once (use before committing)
 npm run test
-```
 
-To run tests in watch mode while you develop (reruns on every file save):
-
-```bash
+# Re-run automatically on every file save (use during active development)
 npm run test -- --watch
-```
 
-To run only a specific test file:
-
-```bash
+# Run only a specific test file in isolation (fastest way to debug a failure)
 npm run test -- lib/calculate.test.ts
+
+# Run only tests whose name matches a pattern
+npm run test -- --reporter=verbose -t "generateVersusSVG"
 ```
 
 **What a passing run looks like:**
 
 ```
-✓ lib/calculate.test.ts (12 tests)
-✓ lib/svg/generator.test.ts (8 tests)
-✓ app/api/streak/route.test.ts (6 tests)
+✓ lib/calculate.test.ts (43 tests)
+✓ lib/svg/generator.test.ts (19 tests)
+✓ app/api/streak/route.test.ts (112 tests)
 
-Test Files  3 passed (3)
-Tests       26 passed (26)
+Test Files  70 passed (70)
+Tests  819 passed (819)
 ```
 
 > **🚨 All tests must pass before you open a PR.** The CI pipeline runs `npm run test` automatically on every pull request and will block merging if any test fails.
 
-### 3. Interpreting SVG Output in the Browser
+### 4. Interpreting Vitest Output
+
+Vitest output can look intimidating at first. Here is how to read it:
+
+```
+FAIL  lib/svg/generator.test.ts
+
+AssertionError: expected '<svg width="600"…' to include 'width="100%"'
+
+- Expected: width="100%"
++ Received: width="600"
+```
+
+| Part of output                       | What it means                                                     |
+| ------------------------------------ | ----------------------------------------------------------------- |
+| `FAIL lib/svg/generator.test.ts`     | The test file that contains the failing test                      |
+| `AssertionError`                     | The `expect()` assertion did not match                            |
+| `- Expected`                         | What the test wanted to see in your output                        |
+| `+ Received`                         | What your code actually produced                                  |
+| `stderr \| …`                        | Expected console output from error-handling tests — **not a bug** |
+| `✓ lib/calculate.test.ts (43 tests)` | This file passed — all good                                       |
 
-When you open a badge URL in your browser, here is what each response means:
+**Interpreting SVG URL responses in the browser:**
 
 | What you see                                 | What it means                                              |
 | -------------------------------------------- | ---------------------------------------------------------- |
@@ -177,15 +221,61 @@ When you open a badge URL in your browser, here is what each response means:
 | Browser XML parse error / blank white page   | ❌ Bug — unescaped `&` or malformed SVG in generator       |
 | `401 Unauthorized` in the terminal           | ❌ Your `GITHUB_PAT` in `.env.local` is missing or invalid |
 
-### 4. Lint and Format
+### 5. Checking Branch Coverage Before Pushing
+
+The CI pipeline enforces a **minimum 70% branch coverage** across all `lib/` files. If your PR drops coverage below this threshold, it will be **blocked from merging automatically** — no exceptions.
+
+Always run the coverage report locally before pushing:
+
+```bash
+npm run test:coverage
+```
+
+The output shows a table like this:
+
+```
+File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
+-------------------|---------|----------|---------|---------|------------------
+lib/svg/generator  |   72.22 |   49.73  |  72.22  |  72.72  | 823-885,1116,1136
+lib/calculate      |   99.00 |   93.54  | 100.00  |  98.92  | 167
+```
+
+**What each column means:**
+
+| Column              | CI Gate   | What it measures                                                           |
+| ------------------- | --------- | -------------------------------------------------------------------------- |
+| `% Branch`          | **≥ 70%** | Every `if/else`, ternary, `??`, and `&&` path covered by at least one test |
+| `% Funcs`           | ≥ 70%     | Every exported function called at least once in tests                      |
+| `% Stmts`           | ≥ 70%     | Every statement executed at least once                                     |
+| `Uncovered Line #s` | —         | Exact lines with no test coverage — start here when fixing gaps            |
+
+**The most important file:** `lib/svg/generator.ts` has the most complex branch logic (auto-theme vs static, size scaling, particle generation, ghost city mode, versus mode). If you add any new `if/else` or ternary logic here, you **must** add tests that exercise both branches — otherwise coverage will drop and block your PR.
+
+**If coverage drops below 70%:**
+
+1. Look at the `Uncovered Line #s` column for the failing file
+2. Open the file and find those exact lines
+3. Identify which branch condition is untested (the `if` path? the `else`? a ternary fallback?)
+4. Add a test that reaches that code path
+5. Re-run `npm run test:coverage` and confirm the percentage recovered
+
+> **Tip:** The coverage report is also generated as an HTML file. Open it in your browser for a visual, line-by-line view of exactly which branches are hit (green) and which are missed (red):
+
+```bash
+open coverage/index.html      # macOS
+xdg-open coverage/index.html  # Linux
+start coverage/index.html     # Windows
+```
+
+### 6. Lint and Format
 
 Run these before every commit:
 
 ```bash
-# Auto-format all files
+# Auto-format all files to match the project's Prettier config
 npm run format
 
-# Check for linting errors
+# Check for any remaining linting errors
 npm run lint
 ```
 
@@ -386,6 +476,7 @@ Use the following format: `type/short-description`
 | Timezone work   | `fix/utc-midnight-edge-case` |
 | Documentation   | `docs/readme-update`         |
 | Refactor        | `refactor/generator-cleanup` |
+| Testing         | `test/generator-coverage`    |
 
 ### Commit Messages
 
@@ -399,6 +490,7 @@ feat(themes): add aurora preset with teal-pink palette
 fix(calculate): handle grace period when today has zero contributions
 docs(readme): add aurora theme to parameter table
 refactor(generator): extract tower path builder into helper function
+test(generator): add Vitest coverage for generateVersusSVG
 ```
 
 **Types:** `feat`, `fix`, `docs`, `refactor`, `chore`, `test`
@@ -433,6 +525,8 @@ Fixes # (issue number)
 - [ ] I have read the `CONTRIBUTING.md` file.
 - [ ] I have tested these changes locally (`localhost:3000/api/streak?user=YOUR_USERNAME`).
 - [ ] I have run `npm run format` and `npm run lint` locally and resolved all errors (CI will fail otherwise).
+- [ ] I have run `npm run test` and all tests pass locally.
+- [ ] I have run `npm run test:coverage` and branch coverage is at or above 70%.
 - [ ] My commits follow the Conventional Commits format (e.g., `feat(themes): ...`, `fix(calculate): ...`).
 - [ ] I have updated `README.md` if I added a new theme or URL parameter.
 - [ ] I have started the repo.
@@ -464,10 +558,29 @@ npm run lint
 
 # 3. Ensure all tests pass
 npm run test
+
+# 4. Verify branch coverage stays at or above 70%
+npm run test:coverage
 ```
 
 Fix every error before pushing. If you add new logic or features, you are expected to write tests for them.
 
+### Coverage Threshold
+
+The CI pipeline enforces a **minimum 70% branch coverage** across all measured files. This is not optional — PRs that drop coverage below this threshold are automatically blocked from merging.
+
+The threshold exists because branch coverage (covering every `if/else`, ternary, and `??` path) is the most reliable indicator that edge cases are tested. Statement coverage alone is not enough.
+
+**Files most likely to affect the gate:**
+
+| File                      | Why it matters                                                             |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `lib/svg/generator.ts`    | Most complex branching — auto-theme, size scaling, ghost city, versus mode |
+| `lib/calculate.ts`        | Streak logic — grace period, timezone edge cases, empty calendars          |
+| `app/api/streak/route.ts` | Request handling — validation, rate limit, not-found, error paths          |
+
+If you add a new `if/else`, ternary, or optional-chain (`?.`) anywhere in `lib/`, you must add a test covering both the truthy and falsy paths before pushing.
+
 ### Testing Guidelines
 
 We use **Vitest** alongside **React Testing Library** for our test suite.
@@ -479,7 +592,7 @@ We use **Vitest** alongside **React Testing Library** for our test suite.
 - **Humanic Comments:** Comments in test files should explain _why_ a test exists or what specific edge-case it covers, rather than just repeating what the code does line-by-line.
 
 > **🚨 GitHub Actions CI Gate**
-> Our CI pipeline runs `npm run lint`, `npm run format --check`, and `npm run test` automatically on **every pull request**. If your code fails any check, **the PR will be blocked from merging** until the issues are resolved. There is no way to bypass this gate — so run the commands locally first and save yourself the round-trip.
+> Our CI pipeline runs `npm run lint`, `npm run format --check`, `npm run test`, and `npm run test:coverage` automatically on **every pull request**. If your code fails any check, **the PR will be blocked from merging** until the issues are resolved. There is no way to bypass this gate — so run the commands locally first and save yourself the round-trip.
 
 **Key style rules:**
 

README.md

@@ -177,6 +177,7 @@ URL Parameter > Theme Default > System Fallback
 | `tz`              | `string`  | No         | Omitted = UTC                  | IANA timezone (e.g. `Asia/Kolkata`, `America/New_York`) — aligns "today" with the user local midnight. Note: `?tz=UTC` is valid but cached separately from omitting `tz`. |
 | `lang`            | `string`  | No         | `en`                           | Language code for labels (`en`, `es`, `hi`, `fr`, `pt`, `ko`, `ja`, `de`, `zh`)                                                                                           |
 | `view`            | `string`  | No         | `default`                      | Rendering mode: `default` (3D Monolith), `monthly` (Compact monthly stats), or `heatmap` (flat 2D contribution heatmap)                                                   |
+| `entrance`        | `string`  | No         | `rise`                         | Entrance animation for towers: `rise` (default), `fade`, `slide`, or `none`.                                                                                              |
 | `delta_format`    | `string`  | No         | `percent`                      | Format for month-over-month delta in monthly view: `percent` (e.g. +12%), `absolute` (e.g. +15 commits), or `both`                                                        |
 | `width`           | `number`  | No         | `300`                          | Custom width for the SVG canvas (currently only applies to `view=monthly`)                                                                                                |
 | `height`          | `number`  | No         | `120`                          | Custom height for the SVG canvas (currently only applies to `view=monthly`)                                                                                               |
@@ -188,6 +189,7 @@ URL Parameter > Theme Default > System Fallback
 | `labelColor`      | `hex`     | No         | —                              | Custom text color for the isometric labels — **without** `#`                                                                                                              |
 | `versus`          | `string`  | No         | —                              | GitHub username of an opponent to compare against in side-by-side versus mode                                                                                             |
 | `shading`         | `boolean` | No         | `false`                        | Apply intensity-based opacity shading to tower faces so lower intensity levels appear slightly dimmer                                                                     |
+| `opacity`         | `number`  | No         | `1.0`                          | Global opacity scalar for all tower fill-opacity values (0.1–1.0). `opacity=0.5` = semi-transparent ghost look. `opacity=0.8` = faded, great on light backgrounds.        |
 | `gradient`        | `boolean` | No         | `false`                        | Opt-in to show volumetric gradients on the monolith floor                                                                                                                 |
 
 ### Grace Period Examples
@@ -220,6 +222,7 @@ URL Parameter > Theme Default > System Fallback
 | `random`           | Surprise theme on reload    | _varies_ | _varies_ | _varies_ |
 | `highcontrast`     | Accessibility high contrast | `0a0a0a` | `ff4500` | `ffffff` |
 | `cyber-pulse`      | AMOLED true-black & cyan    | `000000` | `00ffee` | `ffffff` |
+| `obsidian`         | Deep charcoal & amber gold  | `1a1a2e` | `f59e0b` | `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.
 
@@ -320,6 +323,14 @@ Explore some of the built-in CommitPulse themes and quickly copy the style you l
 
 ![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&gradient=true&shading=true)
 
+<!-- Semi-transparent ghost city look -->
+
+![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&opacity=0.5)
+
+<!-- Slightly faded — perfect for light background embeds -->
+
+![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&opacity=0.8)
+
 <!-- GitHub-style Heatmap View -->
 
 ![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&view=heatmap)

THEMES.md

@@ -1,6 +1,6 @@
 # 🎨 CommitPulse Themes
 
-All 19 available themes for your CommitPulse badge. Use the `?theme=<slug>` query parameter to apply a theme.
+All 20 available themes for your CommitPulse badge. Use the `?theme=<slug>` query parameter to apply a theme.
 
 ```
 https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&theme=<slug>
@@ -30,6 +30,7 @@ https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&theme=<slug>
 | solarized_light  | `#fdf6e3`  | `#586e75` | `#268bd2` |
 | gruvbox_light    | `#fbf1c7`  | `#3c3836` | `#d65d0e` |
 | nord_light       | `#eceff4`  | `#2e3440` | `#5e81ac` |
+| obsidian         | `#1a1a2e`  | `#e2e8f0` | `#f59e0b` |
 | cyber-pulse      | `#000000`  | `#ffffff` | `#00ffee` |
 
 ---
@@ -264,6 +265,18 @@ https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&theme=<slug>
 
 ---
 
+### 🪨 Obsidian
+
+![obsidian](https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=obsidian)
+
+| Parameter | Value  |
+| --------- | ------ |
+| `bg`      | 1a1a2e |
+| `text`    | e2e8f0 |
+| `accent`  | f59e0b |
+
+---
+
 ## 🎛️ Custom Theme
 
 Not finding what you want? Build your own using raw color parameters — all values are hex codes **without** the `#` prefix: