docs: add cache busting, mobile FAB, and lint workflow documentation

2025-12-06 11:34:57 +00:00
parent 68c9371d76
commit c63ce6dd91
2 changed files with 135 additions and 0 deletions
@@ -1470,6 +1470,11 @@ end
 - ✅ **Print CSS separate** (media="print" for PDF export)
 - ✅ **Makefile targets** (css-dev, css-prod, css-watch)

+### Phase 10 Achievements (Cache Busting & Mobile Optimization):
+- ✅ **CSS version query strings** for cache invalidation
+- ✅ **Mobile FAB overflow fix** (responsive buttons on 375px screens)
+- ✅ **Pre-push lint hook** catches CI issues before push
+
 ### Cumulative Achievements:
 - ✅ **715 lines of JavaScript eliminated total** (74.9% reduction)
 - ✅ **54% CSS size reduction** in production (Lightning CSS bundling)
@@ -1484,6 +1489,107 @@ end

 ---

+## 🔄 Phase 10: Cache Management & Mobile Optimization
+
+### 11. CSS Cache Busting - Version Query Strings
+
+**Problem:** Browser caching (especially mobile Safari) serves stale CSS even after deployments, causing users to see outdated styles.
+
+**Solution:** Add version query strings to CSS bundle URLs, forcing browsers to fetch fresh files after deployments.
+
+#### Implementation:
+
+```html
+<!-- Before: Cached indefinitely until max-age expires -->
+<link rel="stylesheet" href="/static/dist/bundle.min.css">
+
+<!-- After: Cache busted on each deployment -->
+<link rel="stylesheet" href="/static/dist/bundle.min.css?v=20251206">
+```
+
+#### Why This Works:
+- Browsers treat `bundle.min.css?v=1` and `bundle.min.css?v=2` as different resources
+- Cache headers (`max-age=86400`) still provide performance benefits
+- New versions are fetched immediately without manual cache clearing
+- Zero impact on server-side caching (query string ignored by CDNs if configured)
+
+#### Best Practices:
+```html
+<!-- Option 1: Date-based versioning (manual) -->
+<link rel="stylesheet" href="/static/dist/bundle.min.css?v=20251206">
+
+<!-- Option 2: Build hash (automated in CI/CD) -->
+<link rel="stylesheet" href="/static/dist/bundle.min.css?v={{.BuildHash}}">
+
+<!-- Option 3: File modification time (automated) -->
+<link rel="stylesheet" href="/static/dist/bundle.min.css?v={{fileModTime}}">
+```
+
+#### Mobile Safari Considerations:
+- iOS Safari caches aggressively, even with `no-cache` headers
+- Version strings ensure fresh CSS on first visit after deployment
+- Users don't need to manually clear browser data
+
+---
+
+### 12. Responsive FAB Buttons - Mobile-First CSS
+
+**Problem:** Floating Action Buttons (FAB) calculated for 380px minimum width overflow on iPhone 13 mini (375px) and smaller screens.
+
+**Solution:** Progressive CSS with media queries for very small screens.
+
+#### Implementation:
+
+```css
+/* Base mobile styles (≤900px) */
+@media (max-width: 900px) {
+    .download-btn, .info-button, .back-to-top /* ... */ {
+        /* Fluid sizing: 36px at 380px → 50px at 900px */
+        width: clamp(36px, calc(2.7vw + 25.7px), 50px) !important;
+        height: clamp(36px, calc(2.7vw + 25.7px), 50px) !important;
+    }
+}
+
+/* Very small screens (≤400px) - iPhone 13 mini, iPhone SE */
+@media (max-width: 400px) {
+    .download-btn, .info-button, .back-to-top /* ... */ {
+        width: 34px !important;
+        height: 34px !important;
+    }
+
+    /* 6 buttons * 34px + 5 gaps * 6px = 234px total */
+    /* Centered: calc(50% - 117px) to calc(50% + 83px) */
+    .is-mobile-device .download-btn {
+        left: calc(50% - 117px) !important;
+    }
+    /* ... remaining button positions ... */
+}
+```
+
+#### Key Technique: Progressive Enhancement
+1. **Desktop first**: Full-size buttons with hover effects
+2. **Mobile (≤900px)**: Fluid `clamp()` sizing, centered layout
+3. **Very small (≤400px)**: Fixed small size, tight spacing
+
+#### Testing Strategy:
+```javascript
+// Playwright test for mobile overflow
+const iphone13Mini = await page.evaluate(() => {
+    const buttons = document.querySelectorAll('.download-btn, .info-button, ...');
+    let rightMost = 0;
+    buttons.forEach(btn => {
+        rightMost = Math.max(rightMost, btn.getBoundingClientRect().right);
+    });
+    return {
+        overflow: rightMost > window.innerWidth,
+        viewport: window.innerWidth
+    };
+});
+expect(iphone13Mini.overflow).toBe(false);
+```
+
+---
+
 ## 🚀 Phase 7-8: Smooth Toggle Animations - Pure Client-Side Pattern (COMPLETED)

 ### 9. HTMX `hx-swap="none"` + Inline Hyperscript - Client-First Toggles