# Theme-Specific Favicons

This directory contains favicon files for different themes in NetScope.

## Directory Structure

```
assets/img/favicons/
├── netscope.png         # Favicon for default NetScope theme
├── positive-planet.png   # Favicon for Positive Planet theme
├── eca.png              # Favicon for ECA theme
├── esl.png              # Favicon for ESL theme
└── README.md            # This file
```

**Note:** Favicons can be in any format: `.png`, `.ico`, `.svg`, `.jpg`, etc.

**Location:** Favicons are stored in `assets/img/favicons/` (next to the logos folder) and are loaded via Vite's asset system.

## How It Works

The favicon is dynamically set based on the `NETSCOPE_THEME` environment variable:

1. **Theme is configured** via `.env` file:
   ```env
   NETSCOPE_THEME=positive-planet
   ```

2. **Favicon mapping** is defined in `utils/theme-logo.js`:
   ```javascript
   'positive-planet': {
     path: 'Positive_Planet_Wordmark_White.svg',
     favicon: {
       href: 'positive-planet.png',  // Just the filename
       type: 'image/png',
     },
     // ...
   }
   ```

   Or use the simpler string format (type is auto-detected):
   ```javascript
   'positive-planet': {
     path: 'Positive_Planet_Wordmark_White.svg',
     favicon: 'positive-planet.png',  // Just filename - auto-detects type from extension
     // ...
   }
   ```

3. **Dynamic loading** happens via `plugins/dynamic-favicon.ts` which:
   - Reads the theme from runtime config
   - Looks up the favicon path from the theme configuration
   - Dynamically updates the favicon link in the HTML head

## Adding a New Theme Favicon

### 1. Create the favicon file

Add your favicon file (any format) to this directory:
```
assets/img/favicons/your-theme.png
```

**Supported formats:** `.png`, `.ico`, `.svg`, `.jpg`, `.jpeg`

### 2. Update the theme configuration

Edit `utils/theme-logo.js` and add the favicon to your theme.

**Option A - Simple format (recommended):**
```javascript
'your-theme': {
  path: 'your-logo.svg',
  height: 'h-[64px]',
  background: null,
  favicon: 'your-theme.png',  // ← Just filename, type auto-detected from extension
},
```

**Option B - Explicit format (more control):**
```javascript
'your-theme': {
  path: 'your-logo.svg',
  height: 'h-[64px]',
  background: null,
  favicon: {
    href: 'your-theme.png',  // Just filename
    type: 'image/png',  // or 'image/x-icon', 'image/svg+xml', etc.
  },
},
```

### 3. Set the environment variable

In your `.env` file (or deployment environment):
```env
NETSCOPE_THEME=your-theme
```

### 4. Deploy

The favicon will automatically be updated when the app loads!

## File Format Requirements

### Supported Formats

| Format | MIME Type | Best For | Notes |
|--------|-----------|----------|-------|
| `.png` | `image/png` | Modern browsers | ✅ Recommended - widely supported, transparent background |
| `.ico` | `image/x-icon` | Legacy browsers | Good for multi-size icons in one file |
| `.svg` | `image/svg+xml` | Scalable icons | Modern browsers, perfect scaling |
| `.jpg` / `.jpeg` | `image/jpeg` | Photos | Not recommended (no transparency) |

### Recommended Sizes

- **PNG/ICO**: 32x32 pixels (minimum), 512x512 (recommended for high-DPI)
- **SVG**: Any size (scalable)

### Best Practices

- ✅ Use **PNG** for best compatibility and quality
- ✅ Use **transparent backgrounds** for better integration
- ✅ Keep file size small (< 50KB)
- ✅ Test on both light and dark browser themes

## Converting Images to Favicon

### Online Tools (Easiest)
- https://favicon.io/ - Convert PNG/JPG/text to favicon
- https://realfavicongenerator.net/ - Generate all favicon formats
- https://convertio.co/ - Convert between formats

### Command Line (ImageMagick)

```bash
# Convert to PNG (32x32)
convert input.png -resize 32x32 output.png

# Convert to ICO with multiple sizes
convert input.png -define icon:auto-resize=16,32,48 output.ico

# Create high-DPI PNG (512x512)
convert input.png -resize 512x512 output-512.png
```

## Fallback Behavior

If a theme doesn't have a specific favicon configured, the default `netscope.png` from `assets/img/favicons/` will be used.

**Note:** The root `/favicon.ico` file in `static/` is kept as a final fallback for browsers and crawlers that check the root directory, but all themes now consistently use favicons from `assets/img/favicons/` directory.

### Format Auto-Detection

The system automatically detects the MIME type from the file extension:

| Extension | MIME Type |
|-----------|-----------|
| `.ico` | `image/x-icon` |
| `.png` | `image/png` |
| `.svg` | `image/svg+xml` |
| `.jpg`, `.jpeg` | `image/jpeg` |

You can also explicitly specify the type using the object format (see "Adding a New Theme Favicon" above).

## Testing

To test your favicon:

1. Set the theme in `.env`:
   ```env
   NETSCOPE_THEME=your-theme
   ```

2. Run the dev server:
   ```bash
   npm run dev
   ```

3. Check the browser tab - you should see your custom favicon!

## Troubleshooting

### Favicon not updating?

1. **Hard refresh** the browser (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows)
2. **Clear browser cache** for the site
3. **Check browser console** for any errors loading the favicon
4. **Verify file path** - favicons should be in `assets/img/favicons/` directory
5. **Check theme name** - ensure `NETSCOPE_THEME` matches the key in `utils/theme-logo.js`
6. **Check console logs** - look for `[Dynamic Favicon]` debug messages

### Wrong favicon showing?

1. Browser may be caching the old favicon
2. Try incognito/private browsing mode
3. Check Network tab in DevTools to see which favicon is being requested