1 files changed, 71 insertions, 0 deletions
diff --git a/docs/superpowers/specs/2026-05-11-matrix-rain-design.md b/docs/superpowers/specs/2026-05-11-matrix-rain-design.md
new file mode 100644
index 0000000..17d8401
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-11-matrix-rain-design.md
@@ -0,0 +1,71 @@
+# Matrix Rain — Design Spec
+**Date:** 2026-05-11  
+**Repo:** repo-html-structure (`packages.danix.xyz`)
+
+## Goal
+
+Add the matrix rain canvas animation to the `_header.html` of the Slackware package repository, matching the implementation in `danix2-hugo-theme` as closely as possible for brand consistency.
+
+## Architecture
+
+### New file: `.assets/matrix-rain.js`
+
+Served from `$PKGREPO/.assets/matrix-rain.js` (i.e. `https://packages.danix.xyz/.assets/matrix-rain.js`).
+
+Source: `danix2-hugo-theme/assets/js/matrix-rain.js` with minimal adaptations (see below). No logic changes — rendering engine, trail model, CSS var integration, font-ready wait, debounced resize, MutationObserver for theme switching all carried over verbatim.
+
+**Adaptations from danix2 version:**
+
+| danix2 | This repo |
+|--------|-----------|
+| Canvas = `#matrix-rain`, full window width/height | Canvas appended to `.site-header`, width = 65% of header width, height = header height |
+| No fade overlay | Gradient fade `<div>` over left 75% of canvas (matches cgit approach) |
+| `canvas.width = window.innerWidth` | `canvas.width = Math.floor(header.offsetWidth * 0.65)` |
+| `canvas.height = window.innerHeight` | `canvas.height = header.offsetHeight` |
+| Resize: `resizeCanvas()` uses `window.innerWidth/Height` | Resize: recalculate from `header.offsetWidth/Height` |
+| Canvas positioned full-screen fixed | Canvas `position:absolute; top:0; right:0; height:100%; pointer-events:none; z-index:0` |
+
+Everything else (character set, trail rendering, color sampling, `hexToRgba`, `sampleColors`, `MutationObserver`, `document.fonts.ready`, debounced resize) is identical.
+
+### CSS variable addition: `--accent2`
+
+Add to `:root` in the `CSS=` heredoc in `gen_web_hook.sh`:
+
+```css
+--accent2: #4ec97b;
+```
+
+This matches the existing `--green` value and aligns the var name with danix2-hugo-theme.
+
+The script references `--accent2` (green rain) and `--accent` (purple rain) — both already present in this repo's palette.
+
+### Header structure change (in `gen_web_hook.sh` → `write_header()`)
+
+Add `position: relative` to `.site-header` so the absolutely-positioned canvas is contained within it.
+
+Add `<script src="/.assets/matrix-rain.js" defer></script>` to the `<head>` of every generated `_header.html`.
+
+The canvas and fade `<div>` are injected by the JS itself (matching cgit pattern) — no HTML changes needed beyond the `<script>` tag.
+
+### Apache: hide `.assets/` from directory listing
+
+Add to `.htaccess`:
+
+```apache
+IndexIgnore .assets
+```
+
+## File changes summary
+
+| File | Change |
+|------|--------|
+| `gen_web_hook.sh` | Add `--accent2` CSS var; add `position:relative` to `.site-header`; add `<script>` tag in `write_header()` |
+| `.assets/matrix-rain.js` | New file — danix2 engine adapted for header-scoped canvas |
+| `.htaccess` | Add `IndexIgnore .assets` |
+| `CLAUDE.md` | Note `.assets/` directory and CSS var addition |
+
+## Out of scope
+
+- Light theme CSS (no light theme exists yet; MutationObserver in the script already handles it when added)
+- Any changes to `_footer.html` generation
+- Feather icons or any other JS (cgit-specific, not needed here)