@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/_general/frontend/redux-localstorage-auth-desync.md

@@ -0,0 +1,126 @@
+---
+name: redux-localstorage-auth-desync
+category: frontend
+version: 1.0.0
+contributed: 2026-03-06
+contributor: ministry-lms
+last_updated: 2026-03-06
+tags: [redux, react, auth, localStorage, infinite-loop, redirect, login]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Redux + localStorage Auth State Desync (Infinite Login Loop)
+
+## Problem
+
+After a token expires or `getMe()` API call fails, the app enters an infinite redirect loop between `/login` and `/dashboard`:
+
+```
+Login → checks localStorage → has token → navigate(/dashboard)
+  → PrivateRoute → checks Redux isAuthenticated → false → navigate(/login)
+    → Login → checks localStorage → has token → navigate(/dashboard)
+      → ... "Maximum update depth exceeded"
+```
+
+The browser console shows: `Warning: Maximum update depth exceeded` and the page flickers rapidly between routes.
+
+## Root Cause
+
+**Two auth sources are out of sync:**
+
+1. **Redux store** — `isAuthenticated: false` (correctly cleared by `getMe.rejected`)
+2. **localStorage** — still has `token` and `user` (NOT cleared by Redux reducer)
+
+The Login page checks `localStorage.getItem('token')` on mount and auto-redirects to dashboard if a token exists. But `PrivateRoute` checks Redux `isAuthenticated` and bounces back to login. Neither clears localStorage, so the loop never breaks.
+
+## Solution Pattern
+
+**Clear localStorage in the same reducer that clears Redux state.** When the auth verification fails, BOTH state stores must be cleaned:
+
+```javascript
+// authSlice.js — getMe.rejected reducer
+builder.addCase(getMe.rejected, (state) => {
+  state.loading = false;
+  state.isAuthenticated = false;
+  state.user = null;
+  state.token = null;
+  // CRITICAL: Clear localStorage to prevent Login→PrivateRoute redirect loop
+  localStorage.removeItem('token');
+  localStorage.removeItem('user');
+});
+```
+
+## Code Example
+
+```javascript
+// Before (broken) — Redux clears, localStorage doesn't
+builder.addCase(getMe.rejected, (state) => {
+  state.loading = false;
+  state.isAuthenticated = false;
+  state.user = null;
+  state.token = null;
+  // localStorage still has token → Login sees it → redirects to dashboard → loop
+});
+
+// After (fixed) — Both stores cleared atomically
+builder.addCase(getMe.rejected, (state) => {
+  state.loading = false;
+  state.isAuthenticated = false;
+  state.user = null;
+  state.token = null;
+  localStorage.removeItem('token');
+  localStorage.removeItem('user');
+});
+```
+
+## Implementation Steps
+
+1. Identify all places where Redux auth state is cleared (rejected thunks, logout)
+2. Add `localStorage.removeItem()` calls in each one
+3. Verify Login page checks are consistent (Redux OR localStorage, not both independently)
+4. Test by manually expiring the token and refreshing the page
+
+## When to Use
+
+- Login page flickers or shows "Maximum update depth exceeded"
+- Users can't log in after token expiration (stuck in redirect loop)
+- App uses BOTH Redux and localStorage for auth state
+- `getMe()` or token verification endpoint returns 401 but user sees login flash
+
+## When NOT to Use
+
+- App uses only Redux for auth (no localStorage persistence)
+- App uses only localStorage (no Redux)
+- Auth is handled by httpOnly cookies (no client-side token storage)
+- The infinite loop is caused by something other than auth state desync
+
+## Common Mistakes
+
+- Clearing only Redux state, not localStorage
+- Clearing only on logout, not on token verification failure
+- Having Login check localStorage while PrivateRoute checks Redux (inconsistent sources)
+- Not clearing on ALL rejection paths (login.rejected, getMe.rejected, etc.)
+
+## Architectural Lesson
+
+**Single source of truth for auth.** If you persist auth in localStorage AND Redux, they MUST be updated atomically. The safest pattern:
+
+1. Redux is the source of truth for the running app
+2. localStorage is ONLY for persistence across page reloads
+3. On app start: read localStorage → hydrate Redux → then ONLY use Redux
+4. On any auth state change: update Redux FIRST, then sync to localStorage
+5. On any auth failure: clear BOTH simultaneously
+
+## Related Skills
+
+- [auth-jwt-basics](../../common-tasks/auth-jwt-basics.md) - JWT auth patterns
+- [postgresql-to-mysql-runtime-translation](../../database-solutions/postgresql-to-mysql-runtime-translation.md) - The migration that surfaced this bug
+
+## References
+
+- React Router v6 redirect behavior: navigation inside useEffect creates render loops
+- Redux Toolkit createAsyncThunk: rejected case must handle side effects
+- Discovered during: MINISTRY-LMS PG→MySQL migration (getMe API failing due to DB errors triggered the loop)
+- File: `client/src/store/slices/authSlice.js` line 304-312

package/skills-library/_general/frontend/safari-csp-theme-color-debugging.md

@@ -0,0 +1,124 @@
+---
+name: safari-csp-theme-color-debugging
+category: frontend
+version: 1.0.0
+contributed: 2026-02-26
+contributor: my-other-project
+last_updated: 2026-02-26
+tags: [safari, csp, theme-color, ios, mobile, debugging, helmet]
+difficulty: medium
+---
+
+# Safari CSP & Theme-Color Debugging
+
+## Problem
+
+Safari on iOS renders differently from Chrome on iOS due to:
+1. **Dual CSP headers** — Apache .htaccess and Node.js Helmet can get out of sync
+2. **theme-color meta tag** — Safari paints the status bar and browser chrome with this color, creating visible colored bars above/below the page content
+3. **CSP enforcement differences** — Safari can be stricter about CSP violations than Chrome
+
+**Symptoms:**
+- Purple/colored bars at top and bottom of the page in Safari
+- Content blocked in Safari but not Chrome (CSP mismatch)
+- `@headlessui/react` Transition leaving elements at `opacity-0` (Safari animation bug)
+- Site showing fallback content instead of dynamic CMS content
+
+## Solution Pattern
+
+### 1. Keep CSP in Sync (Apache + Helmet)
+
+When using both Apache .htaccess CSP AND Node.js Helmet CSP, they MUST match. Check which CSP applies to which responses:
+
+```
+HTML pages (SPA routes):     Apache .htaccess CSP
+API responses (proxied):     Helmet CSP (Node.js)
+Static files (JS/CSS/imgs):  Apache .htaccess CSP
+```
+
+Verify with curl:
+```bash
+# Check HTML page CSP
+curl -s -I https://yoursite.com/ | grep -i content-security
+
+# Check API response CSP
+curl -s -I https://yoursite.com/api/health | grep -i content-security
+```
+
+### 2. Fix theme-color for Dark Themes
+
+The `<meta name="theme-color">` controls Safari's status bar and browser chrome color. It must match your active theme:
+
+```html
+<!-- Before: Purple for old theme -->
+<meta name="theme-color" content="#7C3AED" />
+
+<!-- After: Dark for Aurora Borealis theme -->
+<meta name="theme-color" content="#030712" />
+```
+
+For dynamic themes, update via React Helmet:
+```jsx
+<Helmet>
+  <meta name="theme-color" content={theme.backgroundColor} />
+</Helmet>
+```
+
+### 3. Safari Animation Fix
+
+`@headlessui/react` `<Transition appear={true}>` can fail silently on Safari, leaving elements stuck at `opacity-0`. Replace with CSS keyframe animations:
+
+```css
+/* In overrides.css */
+@keyframes heroFadeUp {
+    from { opacity: 0; transform: translateY(2rem); }
+    to { opacity: 1; transform: translateY(0); }
+}
+```
+
+```jsx
+{/* Before: Transition that fails on Safari */}
+<Transition appear={true} show={true} enter="..." enterFrom="opacity-0" enterTo="opacity-100">
+  <h1>Content</h1>
+</Transition>
+
+{/* After: CSS animation that works everywhere */}
+<h1 style={{ animation: 'heroFadeUp 1s ease-out both' }}>Content</h1>
+```
+
+## Debugging Workflow
+
+1. **Verify API is alive:** `curl -s https://yoursite.com/api/health`
+2. **Compare CSP headers:** Check both Apache and Helmet CSPs match
+3. **Test CORS preflight:** `curl -v -X OPTIONS -H "Origin: https://yoursite.com" https://yoursite.com/api/endpoint`
+4. **Check theme-color:** View source or `curl -s https://yoursite.com/ | grep theme-color`
+5. **Test Safari Private Mode:** If Private Mode fails but regular doesn't, check SW. If both fail, check CSP/CORS.
+6. **Check for content blockers:** Safari supports iOS content blockers that Chrome doesn't
+
+## When to Use
+
+- Site looks different in Safari vs Chrome on iOS
+- Colored bars appearing in Safari browser chrome
+- Content blocked or missing in Safari
+- Animations not playing in Safari
+- Dual Apache + Node.js server setup
+
+## When NOT to Use
+
+- Issue reproduces identically in both browsers
+- Desktop-only rendering issues
+- Server-side errors (check logs first)
+
+## Common Mistakes
+
+- Updating .htaccess CSP but forgetting Helmet CSP (or vice versa)
+- Setting theme-color to old brand color after theme change
+- Using `@headlessui/react` Transition for critical above-fold content
+- Not testing in Safari Private Mode (different behavior than regular)
+- Assuming Chrome on iOS = Safari on iOS (they share WebKit but have different extensions, storage, and privacy features)
+
+## References
+
+- MDN: theme-color — https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name/theme-color
+- MDN: CSP — https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
+- Contributed from: my-other-project Safari debugging session (Feb 26, 2026)

package/skills-library/_general/frontend/safari-sw-cache-poisoning.md

@@ -0,0 +1,138 @@
+---
+name: safari-sw-cache-poisoning
+category: frontend
+version: 1.0.0
+contributed: 2026-02-26
+contributor: my-other-project
+last_updated: 2026-02-26
+tags: [safari, service-worker, pwa, caching, ios, debugging]
+difficulty: hard
+---
+
+# Safari Service Worker Cache Poisoning
+
+## Problem
+
+Safari caches service worker files according to HTTP caching headers (e.g., `ExpiresByType application/javascript "access plus 1 year"`). When a stale SW is cached for months/years, it continues intercepting ALL requests (API calls, navigation, static assets) even after the server-side SW file is updated.
+
+**Symptoms:**
+- "Network Error" on ALL API calls in Safari (axios reports no response)
+- Site loads HTML/CSS but can't communicate with server
+- Chrome works fine (separate SW registration)
+- Login, CMS data loading, and all authenticated features broken
+- Safari DevTools shows SW intercepting requests
+
+**Root Cause Chain:**
+1. Apache `ExpiresByType application/javascript` applies to `sw.js` too
+2. Safari respects the 1-year cache and never checks for SW updates
+3. Old SW's `fetch` handler intercepts API calls and either fails or returns stale data
+4. No amount of server-side fixes help because the browser never fetches the updated SW
+
+## Solution Pattern
+
+### 1. Prevent Future Cache Poisoning (.htaccess)
+
+Add a specific no-cache rule for `sw.js` BEFORE the general JS caching rule:
+
+```apache
+# Prevent caching of service worker (must always fetch fresh)
+<FilesMatch "sw\.js$">
+    Header set Cache-Control "no-cache, no-store, must-revalidate"
+    Header set Pragma "no-cache"
+    Header set Expires 0
+</FilesMatch>
+
+# General JS caching (sw.js excluded by rule above)
+<IfModule mod_expires.c>
+  ExpiresByType application/javascript "access plus 1 year"
+</IfModule>
+```
+
+### 2. Nuclear SW Purge (main entry point)
+
+Add to your app's entry point (e.g., `main.jsx`). This runs on every page load, unregisters ALL stale SWs, purges ALL caches, then registers fresh:
+
+```javascript
+// Nuclear SW cleanup — force-purge stale SWs + caches, then register fresh.
+// Safari cached old sw.js for 1 year, causing stale SW to intercept API calls.
+if ('serviceWorker' in navigator) {
+  window.addEventListener('load', async () => {
+    try {
+      // Step 1: Unregister ALL existing service workers
+      const regs = await navigator.serviceWorker.getRegistrations();
+      await Promise.all(regs.map(reg => reg.unregister()));
+
+      // Step 2: Purge all SW caches
+      const cacheNames = await caches.keys();
+      await Promise.all(cacheNames.map(name => caches.delete(name)));
+
+      // Step 3: Register fresh SW (production only)
+      if (import.meta.env.PROD) {
+        navigator.serviceWorker.register('/sw.js', {
+          updateViaCache: 'none'  // Bypass HTTP cache for SW fetch
+        }).catch(() => {});
+      }
+    } catch (e) {
+      // SW API failures are non-fatal — site works fine without SW
+    }
+  });
+}
+```
+
+### 3. Use `updateViaCache: 'none'`
+
+Always register SWs with `updateViaCache: 'none'` to tell the browser to bypass HTTP cache when checking for SW updates:
+
+```javascript
+navigator.serviceWorker.register('/sw.js', { updateViaCache: 'none' });
+```
+
+## Key Insight: Safari Private Mode
+
+Safari Private Browsing **completely disables service workers**. If the site works in regular Safari but breaks in Private Mode (or vice versa), the SW is likely NOT the issue. Check:
+- CSP headers
+- `theme-color` meta tag
+- Content blockers / ad blockers (Safari-only on iOS)
+- Cookie handling differences
+
+## When to Use
+
+- Site works in Chrome but breaks in Safari with "Network Error"
+- API calls fail but HTML/CSS loads fine
+- SW was registered before proper cache headers were set
+- Deploying to shared hosting where Apache serves SW files
+- Any PWA where `ExpiresByType` or `Cache-Control` applies to JS broadly
+
+## When NOT to Use
+
+- If the issue reproduces in Chrome too (not SW-specific)
+- If Safari Private Mode also fails (SWs are disabled there — look elsewhere)
+- If the server itself is down (check `/api/health` first)
+- For sites that don't use service workers
+
+## Debugging Checklist
+
+1. `curl -s https://yoursite.com/api/health` — Server alive?
+2. `curl -s -I https://yoursite.com/sw.js` — Check Cache-Control headers
+3. `curl -v -X OPTIONS -H "Origin: https://yoursite.com" https://yoursite.com/api/endpoint` — CORS preflight works?
+4. Check if Safari has website data stored (Settings > Safari > Advanced > Website Data)
+5. Test in Safari Private Mode — if it works there, SW is the culprit
+
+## Common Mistakes
+
+- Assuming `sw.js` is exempt from `ExpiresByType` rules (it's not)
+- Using `Header set` instead of `Header always set` in .htaccess
+- Forgetting that unregistering a SW doesn't stop it controlling the CURRENT page (only takes effect on next navigation)
+- Not wrapping SW API calls in try-catch (throws SecurityError in Private Mode)
+- Using `caches` API without checking it exists (throws in some contexts)
+
+## Related Skills
+
+- CSP header synchronization (keep .htaccess and Helmet in sync)
+- Safari theme-color meta tag (affects browser chrome appearance)
+
+## References
+
+- MDN: Service Worker Lifecycle — https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers
+- MDN: updateViaCache — https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration/updateViaCache
+- Contributed from: my-other-project Safari debugging session (Feb 26, 2026)

package/skills-library/_general/frontend/svg-sparkline-no-charting-library.md

@@ -0,0 +1,131 @@
+---
+name: svg-sparkline-no-charting-library
+category: frontend
+version: 1.0.0
+contributed: 2026-02-26
+contributor: scribe-bible
+last_updated: 2026-02-26
+tags: [svg, sparkline, chart, visualization, react, lightweight, no-dependencies]
+difficulty: easy
+usage_count: 0
+success_rate: 100
+---
+
+# SVG Sparkline Without Charting Library
+
+## Problem
+
+You need a compact frequency/distribution chart (sparkline) in a React app but don't want to add D3.js (~230KB), Chart.js (~180KB), or Recharts (~140KB) as dependencies. The chart is simple — thin bars showing values across categories — but charting libraries bring configuration overhead and bundle bloat for what's essentially a few SVG rectangles.
+
+## Solution Pattern
+
+Build the sparkline as a **pure SVG component** using React. Use `viewBox` with percentage-based bar widths for automatic responsiveness. Each bar is a `<rect>` element with height proportional to its value. Add interactivity with React state for hover/click.
+
+The pattern: `viewBox="0 0 100 {height}"` creates a percentage coordinate system where bar widths are `100 / count` — the SVG scales to any container width automatically via `preserveAspectRatio="none"`.
+
+## Code Example
+
+```tsx
+interface SparklineProps {
+  data: { label: string; value: number; color: string }[];
+  height?: number;
+  onBarClick?: (label: string) => void;
+}
+
+function Sparkline({ data, height = 60, onBarClick }: SparklineProps) {
+  const [hovered, setHovered] = useState<number | null>(null);
+  const max = Math.max(...data.map(d => d.value), 1);
+  const barWidth = 100 / data.length;
+  const gap = 0.15; // percentage gap between bars
+
+  return (
+    <div className="relative">
+      <svg
+        viewBox={`0 0 100 ${height}`}
+        preserveAspectRatio="none"
+        className="w-full cursor-pointer"
+        style={{ height: `${height}px` }}
+      >
+        {data.map((d, i) => {
+          const barH = d.value > 0
+            ? Math.max((d.value / max) * (height - 4), 2) // min 2px visible
+            : 0;
+          return (
+            <rect
+              key={i}
+              x={i * barWidth + gap / 2}
+              y={height - barH}
+              width={barWidth - gap}
+              height={barH}
+              fill={d.color}
+              opacity={hovered !== null ? (hovered === i ? 1 : 0.3) : 0.75}
+              rx={0.3}
+              className="transition-opacity duration-150"
+              onMouseEnter={() => setHovered(i)}
+              onMouseLeave={() => setHovered(null)}
+              onClick={() => d.value > 0 && onBarClick?.(d.label)}
+            />
+          );
+        })}
+      </svg>
+
+      {/* Hover tooltip */}
+      {hovered !== null && (
+        <div
+          className="absolute -top-10 bg-gray-900 text-white text-xs rounded px-2 py-1 pointer-events-none"
+          style={{
+            left: `${(hovered / data.length) * 100}%`,
+            transform: 'translateX(-50%)',
+          }}
+        >
+          {data[hovered].label}: {data[hovered].value}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Implementation Steps
+
+1. Define `viewBox="0 0 100 {height}"` — 100-unit wide coordinate system
+2. Calculate `barWidth = 100 / data.length` for even distribution
+3. Normalize bar heights: `(value / maxValue) * (height - padding)`
+4. Set minimum visible height (e.g., `Math.max(barH, 2)`) so small values aren't invisible
+5. Use `preserveAspectRatio="none"` so SVG stretches to container width
+6. Add hover state with opacity dimming on non-hovered bars
+7. Position tooltip using percentage left offset
+
+## When to Use
+
+- Compact distribution charts (frequency across categories, activity over time)
+- Inline sparklines in tables, cards, or dashboards
+- When bundle size matters (0KB added vs 140-230KB for a charting library)
+- When you need full control over styling (Tailwind classes work directly)
+- Simple bar/column charts with <200 data points
+
+## When NOT to Use
+
+- Complex charts (line, area, scatter, pie) — use a library
+- Charts with axes, legends, gridlines, zoom, pan — use Recharts/D3
+- Real-time streaming data with >60fps updates — use Canvas/WebGL
+- Charts that need accessibility features (ARIA roles, keyboard navigation)
+
+## Common Mistakes
+
+- Using `preserveAspectRatio="xMidYMid meet"` (default) — bars don't stretch to fill width
+- Forgetting minimum bar height — values of 1 when max is 10000 become invisible
+- Not handling zero values — `height={0}` rect still renders a hairline in some browsers
+- Using pixel-based widths instead of viewBox percentages — breaks responsiveness
+- Placing tooltip inside the SVG — HTML tooltips are easier to style than SVG text
+
+## Related Skills
+
+- [react-flow-animated-layout-switching](react-flow-animated-layout-switching.md) — Graph visualizations
+- [framer-motion-layoutid-grouping](framer-motion-layoutid-grouping.md) — Animated data transitions
+
+## References
+
+- SVG viewBox specification: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox
+- Discovered in: scribe-bible word study frequency sparkline (Phase 5)
+- 66-bar Bible book distribution chart — zero dependencies, full interactivity