Merge pull request #17 from goude/claude/backlog-work-DApso

Refactor Header scripts and extract magic numbers to CSS variables

Author: goude

docs/backlog.md

@@ -6,25 +6,17 @@ Last reviewed 2026-04-02.
 
 ### Split large components
 
-Header.astro is 690 lines. Extract SVG logo, theme toggle, and nav into sub-components.
+`opening-the-hood/index.astro` is 1,551 lines. Extract sections into components or partial Astro files.
 
-- File: `src/components/Header.astro`
-- File: `src/pages/ai-generated/opening-the-hood/index.astro` (1,551 lines)
+- File: `src/pages/ai-generated/opening-the-hood/index.astro`
 
 ### Extract large inline scripts
 
 Several pages have 100-260 line inline `<script>` blocks that could live in separate files.
 
-- File: `src/components/Header.astro` (lines 548-690 — theme/mode toggle, menu, icon rotation)
 - File: `src/pages/cop.astro` (lines 53-313 — QR generation, clipboard, encryption)
 - File: `src/pages/egghunt.astro` (lines 580-700+ — decryption, puzzle UI)
 
-### Replace magic numbers with named constants
-
-Animation durations (30s) and max-heights (420px) in content.css should be CSS custom properties.
-
-- File: `src/styles/content.css`
-
 ## Low Priority
 
 ### Resolve TODO comments
@@ -53,35 +45,6 @@ No performance budget exists. Lighthouse CI in the workflow would catch regressi
 
 - File: `.github/workflows/astro.yml`
 
-## Refactoring
-
-Prioritized structural improvements. Address top-down.
-
-### Extract shared markdown rendering utility
-
-`Md.astro` and `docs/[...slug].astro` duplicate the marked + Shiki dual-theme rendering pipeline. Extract to a shared `renderMarkdown()` function in `src/utils/`.
-
-- File: `src/components/Md.astro`
-- File: `src/pages/docs/[...slug].astro`
-
-### Consolidate layout usage
-
-`src/layouts/Layout.astro` and `src/components/Layout.astro` — unclear which is canonical. Audit and collapse to one.
-
-- File: `src/layouts/Layout.astro`
-
-### Extract Header.astro sub-components
-
-Header.astro at 690 lines mixes SVG logo, theme toggle, and navigation. Extract each into its own component.
-
-- File: `src/components/Header.astro`
-
-### Break up opening-the-hood page
-
-At 1,551 lines this is the largest file. Extract sections into components or partial Astro files.
-
-- File: `src/pages/ai-generated/opening-the-hood/index.astro`
-
 ## Simplifications
 
 Opportunities to reduce complexity without changing behavior.

src/components/Header.astro

@@ -258,146 +258,147 @@ const navRight = NAV_ITEMS.filter((item) => item.external);
   }
 </style>
 
+<!-- Critical: apply persisted theme/mode before first paint to prevent FOUC -->
 <script is:inline>
   (function () {
-    "use strict";
-
-    const STORAGE = { theme: "theme", mode: "mode" };
     const THEMES = ["light", "dark"];
     const MODES = ["low", "medium", "high"];
     const root = document.documentElement;
-
     const prefersDark = () =>
       window.matchMedia?.("(prefers-color-scheme: dark)").matches;
-
     const readStored = (key, allowed) => {
       const v = localStorage.getItem(key);
       return allowed.includes(v) ? v : null;
     };
-
-    const cycle = (cur, list) => list[(list.indexOf(cur) + 1) % list.length];
-
     const applyTheme = (t) => {
       root.toggleAttribute("data-theme-dark", t === "dark");
       root.toggleAttribute("data-theme-light", t === "light");
     };
-
-    const applyMode = (m) => {
-      root.setAttribute("data-mode", m);
-    };
-
-    const toggleTheme = () => {
-      const cur = root.hasAttribute("data-theme-dark") ? "dark" : "light";
-      const next = cycle(cur, THEMES);
-      localStorage.setItem(STORAGE.theme, next);
-      applyTheme(next);
-    };
-
-    const toggleMode = () => {
-      const cur = root.getAttribute("data-mode") ?? "medium";
-      const next = cycle(cur, MODES);
-      localStorage.setItem(STORAGE.mode, next);
-      applyMode(next);
-    };
+    const applyMode = (m) => root.setAttribute("data-mode", m);
 
     applyTheme(
-      readStored(STORAGE.theme, THEMES) ?? (prefersDark() ? "dark" : "light")
+      readStored("theme", THEMES) ?? (prefersDark() ? "dark" : "light")
     );
-    applyMode(readStored(STORAGE.mode, MODES) ?? "medium");
+    applyMode(readStored("mode", MODES) ?? "medium");
 
     window
       .matchMedia?.("(prefers-color-scheme: dark)")
       .addEventListener("change", () => {
-        if (!readStored(STORAGE.theme, THEMES)) {
+        if (!readStored("theme", THEMES)) {
           applyTheme(prefersDark() ? "dark" : "light");
         }
       });
+  })();
+</script>
 
-    document
-      .getElementById("theme-toggle")
-      ?.addEventListener("click", toggleTheme);
-    document
-      .getElementById("theme-toggle-menu")
-      ?.addEventListener("click", toggleTheme);
-
-    document
-      .getElementById("mode-toggle")
-      ?.addEventListener("click", toggleMode);
-    document
-      .getElementById("mode-toggle-menu")
-      ?.addEventListener("click", toggleMode);
-
-    const menuBtn = document.getElementById("menu-toggle");
-    const panel = document.getElementById("menu-panel");
-
-    const setOpen = (open) => {
-      root.setAttribute("data-nav-open", open ? "true" : "false");
-      menuBtn?.setAttribute("aria-expanded", open ? "true" : "false");
-    };
-
-    const isOpen = () => root.getAttribute("data-nav-open") === "true";
-
-    setOpen(false);
-
-    menuBtn?.addEventListener("click", () => setOpen(!isOpen()));
-
-    panel?.addEventListener("click", (e) => {
-      if (e.target?.closest?.("a")) setOpen(false);
-    });
-
-    document.addEventListener("keydown", (e) => {
-      if (e.key === "Escape") setOpen(false);
-    });
-
-    window.addEventListener("resize", () => {
-      if (window.innerWidth > 480) setOpen(false);
-    });
-
-    const pickNextDifferent = (arr, cur) => {
-      if (arr.length <= 1) return cur;
-      let next = cur,
-        tries = 0;
-      while (next === cur && tries < 5) {
-        next = arr[Math.floor(Math.random() * arr.length)];
-        tries++;
-      }
-      return next;
-    };
-
-    const INTERVAL = 65536; // ms
-    const rotIcons = Array.from(
-      document.querySelectorAll("i[data-icon-rotate]")
-    );
-    const perItem = rotIcons.length > 0 ? INTERVAL / rotIcons.length : INTERVAL;
-
-    rotIcons.forEach((el, i) => {
-      const scheduleNext = (delay) => {
+<!-- Interactive: toggle handlers and icon rotation (deferred, bundled by Astro) -->
+<script>
+  const THEMES = ["light", "dark"];
+  const MODES = ["low", "medium", "high"];
+  const root = document.documentElement;
+
+  const cycle = (cur: string, list: string[]): string =>
+    list[(list.indexOf(cur) + 1) % list.length]!;
+
+  const applyTheme = (t: string) => {
+    root.toggleAttribute("data-theme-dark", t === "dark");
+    root.toggleAttribute("data-theme-light", t === "light");
+  };
+
+  const applyMode = (m: string) => root.setAttribute("data-mode", m);
+
+  const toggleTheme = () => {
+    const cur = root.hasAttribute("data-theme-dark") ? "dark" : "light";
+    const next = cycle(cur, THEMES);
+    localStorage.setItem("theme", next);
+    applyTheme(next);
+  };
+
+  const toggleMode = () => {
+    const cur = root.getAttribute("data-mode") ?? "medium";
+    const next = cycle(cur, MODES);
+    localStorage.setItem("mode", next);
+    applyMode(next);
+  };
+
+  document
+    .getElementById("theme-toggle")
+    ?.addEventListener("click", toggleTheme);
+  document
+    .getElementById("theme-toggle-menu")
+    ?.addEventListener("click", toggleTheme);
+  document.getElementById("mode-toggle")?.addEventListener("click", toggleMode);
+  document
+    .getElementById("mode-toggle-menu")
+    ?.addEventListener("click", toggleMode);
+
+  const menuBtn = document.getElementById("menu-toggle");
+  const panel = document.getElementById("menu-panel");
+
+  const setOpen = (open: boolean) => {
+    root.setAttribute("data-nav-open", open ? "true" : "false");
+    menuBtn?.setAttribute("aria-expanded", open ? "true" : "false");
+  };
+
+  const isOpen = () => root.getAttribute("data-nav-open") === "true";
+
+  setOpen(false);
+
+  menuBtn?.addEventListener("click", () => setOpen(!isOpen()));
+  panel?.addEventListener("click", (e) => {
+    if ((e.target as Element)?.closest?.("a")) setOpen(false);
+  });
+  document.addEventListener("keydown", (e) => {
+    if (e.key === "Escape") setOpen(false);
+  });
+  window.addEventListener("resize", () => {
+    if (window.innerWidth > 480) setOpen(false);
+  });
+
+  const pickNextDifferent = (arr: string[], cur: string): string => {
+    if (arr.length <= 1) return cur;
+    let next = cur,
+      tries = 0;
+    while (next === cur && tries < 5) {
+      next = arr[Math.floor(Math.random() * arr.length)]!;
+      tries++;
+    }
+    return next;
+  };
+
+  const INTERVAL = 65536; // ms
+  const rotIcons = Array.from(
+    document.querySelectorAll<HTMLElement>("i[data-icon-rotate]")
+  );
+  const perItem = rotIcons.length > 0 ? INTERVAL / rotIcons.length : INTERVAL;
+
+  rotIcons.forEach((el, i) => {
+    const scheduleNext = (delay: number) => {
+      window.setTimeout(() => {
+        const raw = el.getAttribute("data-icons") ?? "";
+        const list = raw.split("|").filter(Boolean);
+        if (list.length <= 1) {
+          scheduleNext(INTERVAL);
+          return;
+        }
+        const cur = Array.from(el.classList)
+          .filter((c) => c !== "rotating")
+          .join(" ");
+        el.classList.add("rotating");
         window.setTimeout(() => {
-          const raw = el.getAttribute("data-icons") || "";
-          const list = raw.split("|").filter(Boolean);
-          if (list.length <= 1) {
+          const next = pickNextDifferent(list, cur);
+          el.className = next + " rotating";
+        }, 140);
+        el.addEventListener(
+          "animationend",
+          () => {
+            el.classList.remove("rotating");
             scheduleNext(INTERVAL);
-            return;
-          }
-          const cur = Array.from(el.classList)
-            .filter((c) => c !== "rotating")
-            .join(" ");
-          el.classList.add("rotating");
-          window.setTimeout(() => {
-            const next = pickNextDifferent(list, cur);
-            el.className = next + " rotating";
-          }, 140);
-          el.addEventListener(
-            "animationend",
-            () => {
-              el.classList.remove("rotating");
-              scheduleNext(INTERVAL);
-            },
-            { once: true }
-          );
-        }, delay);
-      };
-      scheduleNext(i * perItem);
-    });
-  })();
+          },
+          { once: true }
+        );
+      }, delay);
+    };
+    scheduleNext(i * perItem);
+  });
 </script>

src/styles/content.css

@@ -293,7 +293,7 @@ button:focus-visible kbd {
     left: 50%;
     transform: translateX(-50%);
 
-    width: min(90vw, 420px);
+    width: min(90vw, var(--tooltip-max-width));
     max-width: none;
 
     white-space: normal;

src/styles/vars.css

@@ -48,6 +48,7 @@
   /* ---------- Layout ---------- */
   --page-max: 900px;
   --page-pad: 24px;
+  --tooltip-max-width: 420px;
 
   /* ---------- Hero image ---------- */
   --hero-max-height: 420px;