astro-website/PRODUCTION_DIAGNOSIS.md

# Production Theme Notch Styling Issue - Diagnostic Report

**Date**: 2026-02-10  
**Status**: CRITICAL - CSS rules missing in production

---

## Executive Summary

The theme notch component appears as plain buttons in normal document flow on production (https://santhoshj.com) because **the CSS rules for `.theme-notch` and related selectors are completely absent from the served `/styles/global.css` file**.

---

## Evidence

### 1. CSS File Status
- **Local file**: `site/public/styles/global.css` ✅ **CONTAINS** `.theme-notch` rules (lines 306-457)
- **Production file**: `https://santhoshj.com/styles/global.css` ❌ **MISSING** `.theme-notch` rules
- **File size**: Local = 1215 lines; Production = ~17,628 bytes (109 CSS rules)
- **Network status**: [200] OK - file loads successfully

### 2. CSS Rules Missing in Production

**Local CSS (lines 306-457) includes:**
```css
.theme-notch {
  position: fixed;
  top: var(--theme-notch-top);
  right: max(8px, env(safe-area-inset-right));
  z-index: 12;
  display: flex;
  align-items: center;
  gap: 10px;
  pointer-events: none;
}

.theme-notch-panel {
  position: absolute;
  right: 60px;
  top: 0;
  display: grid;
  gap: 6px;
  padding: 12px;
  border-radius: 16px;
  border: 1px solid var(--stroke-mid);
  background: var(--surface-1);
  opacity: 0;
  transform: translateX(10px) scale(0.98);
  visibility: hidden;
  pointer-events: none;
  transition: opacity 160ms ease, transform 160ms ease, visibility 0s linear 160ms;
}

.theme-notch-handle { ... }
.theme-notch-glyph { ... }
.theme-notch-option { ... }
.theme-notch-dot { ... }
/* + media queries and forced-colors rules */
```

**Production CSS**: ❌ **ZERO** matches for `.theme-notch*` selectors

### 3. Computed Styles on Production

**Actual computed styles (from browser DevTools):**
```
.theme-notch:
  position: static (WRONG - should be: fixed)
  top: auto (WRONG - should be: 84px)
  right: auto (WRONG - should be: max(8px, env(safe-area-inset-right)))
  display: block (CORRECT - but only by accident)
  opacity: 1 (CORRECT - but only by accident)
  visibility: visible (CORRECT - but only by accident)
  z-index: auto (WRONG - should be: 12)

.theme-notch-panel:
  position: static (WRONG - should be: absolute)
  top: auto (WRONG - should be: 0)
  right: auto (WRONG - should be: 60px)
  display: block (WRONG - should be: grid)
  opacity: 1 (WRONG - should be: 0 initially)
  visibility: visible (WRONG - should be: hidden initially)
```

### 4. HTML Markup Status

✅ **Present and correct:**
- `<aside class="theme-notch" aria-label="Theme" data-theme-notch="" data-open="false">`
- `<div class="theme-notch-panel" id="theme-notch-panel" role="radiogroup" aria-label="Theme selector">`
- `<button class="theme-notch-option" data-theme-option="dark|light|contrast" role="radio" aria-checked="...">`
- SVG glyph present in `.theme-notch-glyph`

### 5. JavaScript Execution

✅ **Inline scripts ARE executing** (no CSP block):
- Theme initialization script runs
- Service worker registration attempted (fails due to unrelated script fetch error)
- Navigation toggle script runs
- Image lazy-load script runs

**Console errors (unrelated to theme-notch CSS):**
- `[ERROR] An unknown error occurred when fetching the script` (service worker)
- `[ERROR] Failed to load resource: net::ERR_INSUFFICIENT_RESOURCES` (analytics)

### 6. Network & Caching

- `/styles/global.css` returns **[200] OK**
- No cache headers preventing updates detected
- File loads successfully but content is stale/incomplete

---

## Root Cause Analysis

### Hypothesis: Build/Deployment Issue

The production CSS file is **missing the theme-notch rules entirely**, suggesting:

1. **Build process did not include the CSS** - The CSS file was generated/minified without the theme-notch section
2. **Stale build artifact** - An older version of global.css is being served
3. **CSS file truncation** - The build process may have failed to include lines 306-457 from the source
4. **Incorrect build output** - The CSS bundler/minifier may have stripped unused rules (unlikely, as the HTML uses the classes)

### Why It Works Locally

- `npm run dev` serves the source CSS directly from `site/public/styles/global.css`
- All rules are present and applied correctly
- Theme notch appears as a fixed, positioned element in the top-right corner

### Why It Fails in Production

- Docker build likely runs `npm run build` which may:
  - Minify/bundle CSS differently
  - Use a different CSS source file
  - Strip rules based on unused CSS detection
  - Output to a different location than `site/public/styles/global.css`

---

## Visual Impact

**Expected (Local):**
- Theme notch appears as a fixed button in top-right corner
- Clicking reveals a dropdown panel with Dark/Light/Contrast options
- Smooth animations and hover effects

**Actual (Production):**
- Theme notch buttons appear inline in normal document flow
- No positioning, no dropdown panel
- Buttons are unstyled (only inherit default browser styles)
- Appears as plain radio buttons in the accessibility tree

---

## Verification Steps Performed

✅ Navigated to https://santhoshj.com and /blog  
✅ Captured console errors and warnings  
✅ Checked network requests (global.css loads with [200])  
✅ Fetched and parsed production CSS file  
✅ Searched for `.theme-notch` selectors (0 matches)  
✅ Inspected computed styles via browser DevTools  
✅ Verified HTML markup is present and correct  
✅ Confirmed inline scripts execute without CSP errors  
✅ Compared with local source CSS (rules present locally)  

---

## Recommended Actions

1. **Immediate**: Check the Docker build process
   - Verify `npm run build` output includes theme-notch CSS
   - Check if CSS is being minified/bundled to a different file
   - Ensure `site/public/styles/global.css` is copied to the Docker image

2. **Verify**: Rebuild and redeploy
   - Run `npm run build` locally and inspect the output CSS
   - Check if `dist/styles/global.css` (or equivalent) contains theme-notch rules
   - Verify the Docker image includes the correct CSS file

3. **Debug**: Add build logging
   - Log CSS file size before/after minification
   - Verify the CSS source file is being read correctly
   - Check for any build warnings about unused CSS

4. **Test**: Validate production deployment
   - After fix, verify `/styles/global.css` contains theme-notch rules
   - Check computed styles in production browser DevTools
   - Confirm theme notch appears in correct position

---

## Files Involved

- **Source**: `site/public/styles/global.css` (lines 306-457)
- **Production**: `https://santhoshj.com/styles/global.css` (missing rules)
- **Build**: `Dockerfile` and `npm run build` process
- **HTML**: `site/src/components/BaseLayout.astro` (renders theme-notch markup)

---

## Conclusion

**The issue is NOT:**
- ❌ CSP blocking inline scripts
- ❌ Missing HTML markup
- ❌ JavaScript not executing
- ❌ Browser caching (file loads fresh)

**The issue IS:**
- ✅ **Production CSS file missing `.theme-notch` rules**
- ✅ **Build/deployment process not including complete CSS**

The fix requires investigating the Docker build and CSS bundling process to ensure all CSS rules are included in the production output.

---

## CRITICAL UPDATE: Root Cause Identified

### Build Verification Results

**Local Build (npm run build):**
- ✅ CSS file generated: `site/dist/styles/global.css`
- ✅ File size: **24,279 bytes**
- ✅ Theme-notch rules: **30 matches** found
- ✅ All CSS rules present and correct

**Production Server:**
- ❌ CSS file served: `https://santhoshj.com/styles/global.css`
- ❌ File size: **~17,628 bytes** (SMALLER than local build)
- ❌ Theme-notch rules: **0 matches** found
- ❌ CSS is STALE/OUTDATED

### Conclusion

**The production server is serving an OLD version of the CSS file that was built BEFORE the theme-notch CSS rules were added to the source.**

This is a **deployment/caching issue**, not a build issue.

### Why This Happened

1. The theme-notch CSS rules exist in the source (`site/public/styles/global.css`)
2. The local build correctly includes them in the output (`site/dist/styles/global.css`)
3. **BUT** the production Docker image contains an older version of the CSS file
4. This suggests:
   - The Docker image was built from an older commit
   - OR the CSS file was not updated in the Docker image
   - OR there's a caching layer serving stale content

### Fix Required

**Option 1: Rebuild and redeploy the Docker image**
```bash
docker compose build --no-cache
docker compose push
# Deploy new image to production
```

**Option 2: If using CI/CD**
- Ensure the latest commit is being built
- Verify the Docker build includes the latest `site/dist/` output
- Check that the image is being pushed with the correct tag
- Redeploy the image to production

**Option 3: Quick verification**
- SSH into production server
- Check the CSS file size: should be ~24,279 bytes (not ~17,628)
- Verify `/styles/global.css` contains "theme-notch" (30+ matches)
- If not, redeploy the Docker image

---

## Summary Table

| Aspect | Local | Production | Status |
|--------|-------|-----------|--------|
| CSS file exists | ✅ Yes | ✅ Yes | OK |
| File size | 24,279 bytes | ~17,628 bytes | ❌ MISMATCH |
| theme-notch rules | 30 matches | 0 matches | ❌ MISSING |
| HTML markup | ✅ Present | ✅ Present | OK |
| JavaScript | ✅ Executing | ✅ Executing | OK |
| Computed styles | ✅ Correct | ❌ Wrong | BROKEN |
| Visual result | ✅ Fixed notch | ❌ Inline buttons | BROKEN |

---

## Next Steps

1. **Verify the fix**: Rebuild Docker image with latest source
2. **Deploy**: Push new image to production
3. **Test**: Verify `/styles/global.css` is ~24,279 bytes and contains theme-notch rules
4. **Validate**: Check production site - theme notch should appear in top-right corner
5. **Monitor**: Watch for any other stale assets