path: root/docs/superpowers/plans/2026-05-11-matrix-rain.md

# Matrix Rain Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add matrix rain canvas animation to `packages.danix.xyz` headers, using the `danix2-hugo-theme` engine adapted for the header-scoped layout.

**Architecture:** A single JS file at `.assets/matrix-rain.js` is served from the repo root and loaded via `<script defer>` in every generated `_header.html`. The script appends a canvas + gradient fade div to `.site-header` at runtime. CSS vars `--accent`, `--accent2`, `--bg` drive colors — no hardcoded values.

**Tech Stack:** Vanilla JS (ES5-compatible IIFE), HTML Canvas API, Apache `.htaccess`, bash (`gen_web_hook.sh`)

---

### Task 1: Add `--accent2` CSS variable and `position:relative` to `.site-header`

**Files:**
- Modify: `gen_web_hook.sh` (CSS heredoc and `.site-header` rule)

- [ ] **Step 1: Add `--accent2` to the `:root` block in the `CSS=` heredoc**

In `gen_web_hook.sh`, find the `:root {` block inside the `CSS='<style>` heredoc (around line 37). Add `--accent2` after `--green`:

```bash
# Before:
  --green:     #4ec97b;

# After:
  --green:     #4ec97b;
  --accent2:   #4ec97b;
```

- [ ] **Step 2: Add `position: relative` to `.site-header`**

In the same `CSS=` heredoc, find the `.site-header {` rule (around line 56). Add `position: relative;`:

```css
.site-header { border-bottom: 1px solid var(--border); padding: 2rem 2.5rem 1.5rem; background: var(--bg-card); position: relative; overflow: hidden; }
```

(`overflow: hidden` clips the canvas to the header bounds.)

- [ ] **Step 3: Verify the heredoc is syntactically intact**

```bash
bash -n gen_web_hook.sh
```

Expected: no output (no syntax errors).

- [ ] **Step 4: Commit**

```bash
git add gen_web_hook.sh
git commit -m "style: add --accent2 CSS var and position:relative to .site-header"
```

---

### Task 2: Create `.assets/matrix-rain.js`

**Files:**
- Create: `.assets/matrix-rain.js`

This is the danix2 engine with canvas targeting changed from `#matrix-rain` (full-screen) to a dynamically created canvas appended to `.site-header` (65% width, right-aligned, with gradient fade div).

- [ ] **Step 1: Create the `.assets/` directory and write the file**

```bash
mkdir -p .assets
```

Write `.assets/matrix-rain.js` with the following content (danix2 engine, header-scoped):

```javascript
// Matrix rain background effect — header-scoped build for packages.danix.xyz
// Derived from danix2-hugo-theme/assets/js/matrix-rain.js
(function() {
  if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;

  var header = document.querySelector('.site-header');
  if (!header) return;

  // Canvas
  var canvas = document.createElement('canvas');
  canvas.id = 'matrix-rain';
  canvas.style.cssText = 'position:absolute;top:0;right:0;height:100%;pointer-events:none;z-index:0;';
  header.appendChild(canvas);

  // Gradient fade div — covers left 75% of canvas area, left→transparent
  var fade = document.createElement('div');
  fade.style.cssText = 'position:absolute;top:0;right:0;bottom:0;width:' + Math.floor(0.65 * 100) + '%;background:linear-gradient(to right,var(--bg-card) 0%,transparent 60%);pointer-events:none;z-index:1;';
  header.appendChild(fade);

  var ctx = canvas.getContext('2d');

  var columns = [];
  var frameCount = 0;
  var colors = { accent: '#5c9cf5', accent2: '#4ec97b', bg: '#161b25', head: '#ffffff' };

  var ASCII = Array.from({ length: 94 }, function(_, i) { return String.fromCharCode(33 + i); });
  var KATA  = Array.from({ length: 96 }, function(_, i) { return String.fromCodePoint(0x30a0 + i); });
  var CHARS = shuffle([].concat(ASCII, KATA, KATA, KATA));

  function shuffle(arr) {
    for (var i = arr.length - 1; i > 0; i--) {
      var j = Math.floor(Math.random() * (i + 1));
      var tmp = arr[i]; arr[i] = arr[j]; arr[j] = tmp;
    }
    return arr;
  }

  function hexToRgba(color, alpha) {
    var rgbMatch = color.match(/rgb\((\d+),\s*(\d+),\s*(\d+)\)/);
    if (rgbMatch) return 'rgba(' + rgbMatch[1] + ',' + rgbMatch[2] + ',' + rgbMatch[3] + ',' + alpha + ')';
    var hex = color.replace('#', '');
    var r = parseInt(hex.substring(0, 2), 16);
    var g = parseInt(hex.substring(2, 4), 16);
    var b = parseInt(hex.substring(4, 6), 16);
    return 'rgba(' + r + ',' + g + ',' + b + ',' + alpha + ')';
  }

  function sampleColors() {
    var style = getComputedStyle(document.documentElement);
    var isDark = !document.documentElement.classList.contains('theme-light');
    colors.accent  = style.getPropertyValue('--accent').trim()  || '#5c9cf5';
    colors.accent2 = style.getPropertyValue('--accent2').trim() || '#4ec97b';
    colors.bg      = style.getPropertyValue('--bg-card').trim() || '#161b25';
    colors.head    = isDark ? '#ffffff' : '#1a0533';
  }

  function resizeCanvas() {
    canvas.width  = Math.floor(header.offsetWidth * 0.65);
    canvas.height = header.offsetHeight;
    ctx.font = '14px "IBM Plex Mono", monospace';
    ctx.textBaseline = 'top';
    initColumns();
  }

  function initColumns() {
    columns = [];
    var columnWidth = 14;
    var columnCount = Math.floor(canvas.width / columnWidth);
    for (var i = 0; i < columnCount; i++) {
      columns.push({
        x:          i * columnWidth,
        y:          -Math.floor(Math.random() * 40),
        speed:      2 + Math.floor(Math.random() * 3),
        color:      Math.random() < 0.6 ? 'accent2' : 'accent',
        charIndex:  Math.floor(Math.random() * CHARS.length),
        length:     8 + Math.floor(Math.random() * 13)
      });
    }
  }

  function setupThemeObserver() {
    var observer = new MutationObserver(function(mutations) {
      for (var i = 0; i < mutations.length; i++) {
        if (mutations[i].attributeName === 'class') { sampleColors(); break; }
      }
    });
    observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
  }

  function drawFrame() {
    frameCount++;
    ctx.fillStyle = hexToRgba(colors.bg, 0.085);
    ctx.fillRect(0, 0, canvas.width, canvas.height);

    for (var ci = 0; ci < columns.length; ci++) {
      var col = columns[ci];
      if (frameCount % col.speed !== 0) continue;

      ctx.fillStyle = colors[col.color];
      for (var i = 1; i <= col.length; i++) {
        var trailY = (col.y - i) * 14;
        if (trailY < 0) continue;
        var trailCharIndex = (col.charIndex - i + CHARS.length) % CHARS.length;
        ctx.fillText(CHARS[trailCharIndex], col.x, trailY);
      }

      ctx.fillStyle = colors.head;
      ctx.fillText(CHARS[col.charIndex % CHARS.length], col.x, col.y * 14);

      col.y++;
      col.charIndex = (col.charIndex + 1) % CHARS.length;

      if (col.y * 14 > canvas.height + col.length * 14) {
        col.y         = -Math.floor(Math.random() * 20);
        col.charIndex = Math.floor(Math.random() * CHARS.length);
        col.color     = Math.random() < 0.6 ? 'accent2' : 'accent';
      }
    }

    requestAnimationFrame(drawFrame);
  }

  sampleColors();
  resizeCanvas();
  setupThemeObserver();

  var resizeTimer;
  window.addEventListener('resize', function() {
    clearTimeout(resizeTimer);
    resizeTimer = setTimeout(resizeCanvas, 150);
  });

  document.fonts.ready.then(function() {
    requestAnimationFrame(drawFrame);
  });
})();
```

- [ ] **Step 2: Commit**

```bash
git add .assets/matrix-rain.js
git commit -m "feat: add matrix-rain.js (danix2 engine, header-scoped)"
```

---

### Task 3: Wire `<script>` tag into `write_header()` in `gen_web_hook.sh`

**Files:**
- Modify: `gen_web_hook.sh` (`write_header()` function)

- [ ] **Step 1: Add the `<script>` tag to `write_header()`**

In `gen_web_hook.sh`, find `write_header()` (around line 241). Inside the `cat > "$dir/_header.html" << EOF` block, add the script tag in `<head>`, after the Google Fonts `<link>` and before `${CSS}`:

```bash
  <script src="/.assets/matrix-rain.js" defer></script>
  ${CSS}
```

Full `<head>` block after change:

```bash
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>danix Slackware Repository</title>
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&family=IBM+Plex+Sans:wght@300;400;600&display=swap" rel="stylesheet">
  <script src="/.assets/matrix-rain.js" defer></script>
  ${CSS}
</head>
```

- [ ] **Step 2: Verify syntax**

```bash
bash -n gen_web_hook.sh
```

Expected: no output.

- [ ] **Step 3: Commit**

```bash
git add gen_web_hook.sh
git commit -m "feat: load matrix-rain.js in generated _header.html"
```

---

### Task 4: Hide `.assets/` from Apache directory listing

**Files:**
- Modify: `htaccess`

- [ ] **Step 1: Add `IndexIgnore .assets` to `htaccess`**

In `htaccess`, find the `IndexIgnore` line (around line 15). Append `.assets` to it:

```apache
IndexIgnore _header.html _footer.html .htaccess .htpasswd \
            CHECKSUMS.md5 CHECKSUMS.md5.asc CHECKSUMS.md5.gz CHECKSUMS.md5.gz.asc \
            FILELIST.TXT MANIFEST.bz2 \
            PACKAGES.TXT PACKAGES.TXT.gz \
            ChangeLog.txt.gz GPG-KEY \
            .assets
```

- [ ] **Step 2: Commit**

```bash
git add htaccess
git commit -m "chore: hide .assets dir from Apache autoindex"
```

---

### Task 5: Update CLAUDE.md

**Files:**
- Modify: `CLAUDE.md`

- [ ] **Step 1: Add `.assets/` and `--accent2` notes to CLAUDE.md**

In the **CSS design system** section, update the CSS variables list to include `--accent2`:

```markdown
- Colors: `--bg`, `--bg-card`, `--bg-hover`, `--border`, `--accent`, `--accent-dim`, `--accent2`, `--green`, `--text`, `--text-dim`, `--text-head`
```

Add a new **Static assets** section after the CSS section:

```markdown
## Static assets

`.assets/matrix-rain.js` — matrix rain canvas animation. Served from `$PKGREPO/.assets/`. Loaded via `<script defer>` in every `_header.html`. Hidden from Apache autoindex via `IndexIgnore .assets` in `.htaccess`. When updating, copy the adapted file to `$PKGREPO/.assets/matrix-rain.js` on the server — it is not regenerated by `gen_web_hook.sh`.
```

- [ ] **Step 2: Commit**

```bash
git add CLAUDE.md
git commit -m "docs: document .assets/ dir and --accent2 var in CLAUDE.md"
```

---

### Task 6: Smoke-test the generated output

**Files:** none (verification only)

- [ ] **Step 1: Run `gen_web_hook.sh` against a test directory**

```bash
mkdir -p /tmp/test-pkgrepo/audio/ffmpeg
echo "ffmpeg: FFmpeg multimedia framework" > /tmp/test-pkgrepo/audio/ffmpeg/ffmpeg-6.1-x86_64-1.txt
bash gen_web_hook.sh /tmp/test-pkgrepo
```

Expected output:
```
gen_web_hook: Generating static web files in /tmp/test-pkgrepo ...
gen_web_hook: Written: /tmp/test-pkgrepo/_header.html
gen_web_hook: Written: /tmp/test-pkgrepo/_footer.html
gen_web_hook: Written: /tmp/test-pkgrepo/audio/_header.html
gen_web_hook: Written: /tmp/test-pkgrepo/audio/_footer.html
gen_web_hook: Written: /tmp/test-pkgrepo/audio/ffmpeg/_header.html
gen_web_hook: Written: /tmp/test-pkgrepo/audio/ffmpeg/_footer.html
gen_web_hook: Done.
```

- [ ] **Step 2: Verify `_header.html` contains expected elements**

```bash
grep -c 'matrix-rain.js' /tmp/test-pkgrepo/_header.html
grep -c '\-\-accent2' /tmp/test-pkgrepo/_header.html
grep -c 'position: relative' /tmp/test-pkgrepo/_header.html
grep -c 'overflow: hidden' /tmp/test-pkgrepo/_header.html
```

Expected: each command prints `1`.

- [ ] **Step 3: Validate HTML structure**

```bash
grep -A2 'matrix-rain' /tmp/test-pkgrepo/_header.html
```

Expected output contains:
```html
<script src="/.assets/matrix-rain.js" defer></script>
```

- [ ] **Step 4: Clean up**

```bash
rm -rf /tmp/test-pkgrepo
```