feat: implement dynamic google font support via URL parameter (JhaSourav07#96)

feat: support dynamic google fonts with security sanitization and updated documentation

Author: Animesh-86

README.md

@@ -76,18 +76,19 @@ URL Parameter > Theme Default > System Fallback
 
 ### Parameter Reference
 
-| Parameter | Type      | Required   | Default       | Description                                           |
-| --------- | --------- | ---------- | ------------- | ----------------------------------------------------- |
-| `user`    | `string`  | ✅ **Yes** | —             | GitHub username to render                             |
-| `theme`   | `string`  | No         | `dark`        | Preset theme name (see below)                         |
-| `bg`      | `hex`     | No         | Theme default | Background color — **without** `#`                    |
-| `accent`  | `hex`     | No         | Theme default | Tower & glow color — **without** `#`                  |
-| `text`    | `hex`     | No         | Theme default | Label & stat text color — **without** `#`             |
-| `radius`  | `number`  | No         | `8`           | Border corner radius in pixels                        |
-| `speed`   | `string`  | No         | `8s`          | Radar scan animation duration (e.g. `4s`, `12s`)      |
-| `scale`   | `string`  | No         | `linear`      | Tower height scaling: `linear` or `log` (logarithmic) |
-| `refresh` | `boolean` | No         | `false`       | Bypass cache for real-time data                       |
-| `year`    | `string`  | No         | —             | Calendar year to render (e.g. `2023`, `2024`)         |
+| Parameter | Type      | Required   | Default                        | Description                                           |
+| --------- | --------- | ---------- | ------------------------------ | ----------------------------------------------------- |
+| `user`    | `string`  | ✅ **Yes** | —                              | GitHub username to render                             |
+| `theme`   | `string`  | No         | `dark`                         | Preset theme name (see below)                         |
+| `bg`      | `hex`     | No         | Theme default                  | Background color — **without** `#`                    |
+| `accent`  | `hex`     | No         | Theme default                  | Tower & glow color — **without** `#`                  |
+| `text`    | `hex`     | No         | Theme default                  | Label & stat text color — **without** `#`             |
+| `radius`  | `number`  | No         | `8`                            | Border corner radius in pixels                        |
+| `speed`   | `string`  | No         | `8s`                           | Radar scan animation duration (e.g. `4s`, `12s`)      |
+| `scale`   | `string`  | No         | `linear`                       | Tower height scaling: `linear` or `log` (logarithmic) |
+| `font`    | `string`  | No         | CommitPulse default typography | Any **Google Font** name (e.g., `Orbitron`, `Inter`)  |
+| `refresh` | `boolean` | No         | `false`                        | Bypass cache for real-time data                       |
+| `year`    | `string`  | No         | —                              | Calendar year to render (e.g. `2023`, `2024`)         |
 
 ### Theme Presets
 
@@ -113,6 +114,10 @@ URL Parameter > Theme Default > System Fallback
 
 ![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=dracula)
 
+<!-- Dynamic Google Fonts — Space-age look with Orbitron -->
+
+![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&font=Orbitron)
+
 <!-- Fully custom — hot orange on void black -->
 
 ![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&bg=080808&accent=ff4500&text=eeeeee&radius=16)

lib/svg/generator.test.ts

@@ -57,13 +57,39 @@ describe('generateSVG', () => {
     expect(svg).toContain('class="heat-particles"');
   });
 
-  it('defaults invalid fonts to JetBrains Mono', () => {
+  it('supports dynamic Google Fonts for non-predefined fonts', () => {
     const svg = generateSVG(
       mockStats,
-      { user: 'avi', font: 'invalidfont' } as unknown as BadgeParams,
+      { user: 'avi', font: 'Inter' } as unknown as BadgeParams,
       mockCalendar
     );
-    expect(svg).toContain('JetBrains Mono');
+
+    expect(svg).toContain(
+      "@import url('https://fonts.googleapis.com/css2?family=Inter&display=swap');"
+    );
+    expect(svg).toContain('font-family: "Inter", sans-serif;');
+  });
+
+  it('replaces spaces with plus sign in dynamic Google Font URLs', () => {
+    const svg = generateSVG(
+      mockStats,
+      { user: 'avi', font: 'Open Sans' } as unknown as BadgeParams,
+      mockCalendar
+    );
+
+    expect(svg).toContain('family=Open+Sans');
+  });
+
+  it('sanitizes dangerous characters in font names to prevent CSS injection', () => {
+    const svg = generateSVG(
+      mockStats,
+      { user: 'avi', font: 'Inter"</style><script>alert(1)</script>' } as unknown as BadgeParams,
+      mockCalendar
+    );
+
+    expect(svg).toContain('family=Interstylescriptalert1script');
+    expect(svg).not.toContain('alert(1)');
+    expect(svg).not.toContain('<script>');
   });
 
   it('handles missing params with defaults', () => {
@@ -73,6 +99,18 @@ describe('generateSVG', () => {
     expect(svg).toContain('ffffff'); // default text
   });
 
+  it('falls back to default typography for completely invalid font names', () => {
+    const svg = generateSVG(
+      mockStats,
+      { user: 'avi', font: '!!!' } as unknown as BadgeParams,
+      mockCalendar
+    );
+    // Should NOT contain a dynamic google fonts import for an empty/invalid family
+    expect(svg).not.toContain('family=&amp;display=swap');
+    // Should use default body font
+    expect(svg).toContain('font-family: "Space Grotesk", sans-serif');
+  });
+
   // ── Auto-theme (prefers-color-scheme) tests ──────────────────────────────
   // These verify that theme=auto produces an SVG that switches between light
   // and dark color palettes using CSS custom properties and a media query,

lib/svg/generator.ts

@@ -153,9 +153,17 @@ export function generateSVG(
   const accent = `#${(params.accent || '00ffaa').replace('#', '')}`;
   const text = `#${(params.text || 'ffffff').replace('#', '')}`;
 
-  const selectedFont = params.font
-    ? FONT_MAP[params.font.toLowerCase()] || '"JetBrains Mono", monospace'
-    : null;
+  const sanitizeFont = (name: string) => name.replace(/[^a-zA-Z0-9\s-]/g, '').trim();
+  const sanitizedFont = params.font ? sanitizeFont(params.font) : null;
+
+  const predefinedFont = sanitizedFont ? FONT_MAP[sanitizedFont.toLowerCase()] : null;
+  const isPredefinedFont = Boolean(predefinedFont);
+
+  const selectedFont = isPredefinedFont
+    ? predefinedFont
+    : sanitizedFont
+      ? `"${sanitizedFont}", sans-serif`
+      : null;
 
   const defaultTitleFont = '"Syncopate", sans-serif';
   const defaultBodyFont = '"Space Grotesk", sans-serif';
@@ -199,6 +207,14 @@ export function generateSVG(
     }
   }
 
+  // dynamic google fonts import
+  const googleFontsImport =
+    sanitizedFont && !isPredefinedFont
+      ? `@import url('https://fonts.googleapis.com/css2?family=${encodeURIComponent(
+          sanitizedFont
+        ).replace(/%20/g, '+')}&display=swap');`
+      : '';
+
   return `
 <svg xmlns="http://www.w3.org/2000/svg" width="600" height="420" viewBox="0 0 600 420" fill="none">
   <defs>
@@ -210,6 +226,7 @@ export function generateSVG(
 
   <style>
   @import url('https://fonts.googleapis.com/css2?family=Fira+Code&amp;family=JetBrains+Mono&amp;family=Roboto&amp;display=swap');
+  ${googleFontsImport}
 
   .title {
     font-family: ${selectedFont || defaultTitleFont};