From b943b22f0b80840ffb91472cb1330be2a3d5824f Mon Sep 17 00:00:00 2001
From: "Danilo M." <danix@danix.xyz>
Date: Tue, 21 Apr 2026 23:29:43 +0200
Subject: docs: add tag cloud spiral implementation plan

---
 .../plans/2026-04-21-tag-cloud-spiral.md           | 336 +++++++++++++++++++++
 1 file changed, 336 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-04-21-tag-cloud-spiral.md

(limited to 'docs/superpowers/plans/2026-04-21-tag-cloud-spiral.md')

diff --git a/docs/superpowers/plans/2026-04-21-tag-cloud-spiral.md b/docs/superpowers/plans/2026-04-21-tag-cloud-spiral.md
new file mode 100644
index 0000000..808b2cb
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-21-tag-cloud-spiral.md
@@ -0,0 +1,336 @@
+# Tag Cloud Spiral Layout 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:** Replace the flat flex-wrap tag cloud with an Archimedean spiral layout where big tags cluster at center and smaller tags scatter outward, deterministically per tag text.
+
+**Architecture:** Vanilla JS module reads `data-weight` attributes rendered by the Hugo partial, sorts tags by weight, places them along an outward Archimedean spiral with AABB collision detection, then sets absolute positions. Falls back to existing centered flex layout when JS is disabled or container is < 400px wide.
+
+**Tech Stack:** Hugo (partial modification), Vanilla JS (ES5-compatible, no build step), Hugo Pipes (minify), existing CSS variables for theming.
+
+---
+
+## File Map
+
+| Action | Path | Responsibility |
+|--------|------|----------------|
+| Modify | `themes/danix-xyz-hacker/layouts/partials/tag-cloud.html` | Add `data-weight` attr to links, `data-tag-cloud` to container |
+| Modify | `themes/danix-xyz-hacker/assets/css/main.css` | Add `overflow: visible` to `.tag-cloud` |
+| Create | `themes/danix-xyz-hacker/assets/js/tag-cloud-spiral.js` | Spiral placement algorithm |
+| Modify | `themes/danix-xyz-hacker/layouts/_default/baseof.html` | Load spiral script via Hugo Pipes |
+
+---
+
+### Task 1: Add data attributes to tag-cloud partial
+
+**Files:**
+- Modify: `themes/danix-xyz-hacker/layouts/partials/tag-cloud.html:42,49,57`
+
+- [ ] **Step 1: Add `data-tag-cloud` to both container divs**
+
+In `tag-cloud.html`, both render paths have `<div class="tag-cloud">`. Add `data-tag-cloud` attribute to each:
+
+```html
+{{- if $wrapInWidget -}}
+<div class="sidebar-widget">
+  <p class="sidebar-widget-label"># {{ i18n "topTags" }}</p>
+  <nav aria-label="{{ i18n "exploreTopics" }}">
+    <div class="tag-cloud" data-tag-cloud>
+{{- else -}}
+<section aria-labelledby="tag-cloud-heading">
+  <{{ $headingLevel }} id="tag-cloud-heading" class="text-lg font-semibold text-accent mb-4">
+    {{ $heading }}
+  </{{ $headingLevel }}>
+  <nav aria-label="{{ i18n "exploreTopics" }}">
+    <div class="tag-cloud" data-tag-cloud>
+{{- end -}}
+```
+
+- [ ] **Step 2: Add `data-weight` to each tag link**
+
+In the `range $orderedTags` block, add `data-weight="{{ printf "%.4f" $ratio }}"` to the `<a>` tag:
+
+```html
+        <a
+          href="{{ .Page.RelPermalink }}"
+          class="tag-cloud-link"
+          data-weight="{{ printf "%.4f" $ratio }}"
+          {{- if ge $ratio 0.5 }}
+          style="font-size: {{ $size }}rem; color: var(--accent); opacity: {{ $opacity }};"
+          {{- else }}
+          style="font-size: {{ $size }}rem; color: var(--text-dim); opacity: {{ $opacity }};"
+          {{- end }}
+          aria-label="{{ .Name }}{{- if $showCount }} ({{ i18n "postCount" $count }}){{- end -}}"
+        >
+```
+
+- [ ] **Step 3: Verify Hugo renders correctly**
+
+Run: `hugo serve` and inspect homepage tag cloud in browser devtools.
+Expected: each `<a>` has `data-weight="0.XXXX"`, container `<div>` has `data-tag-cloud` attribute.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add themes/danix-xyz-hacker/layouts/partials/tag-cloud.html
+git commit -m "feat: add data-weight and data-tag-cloud attributes to tag cloud partial"
+```
+
+---
+
+### Task 2: Add `overflow: visible` to `.tag-cloud` CSS
+
+**Files:**
+- Modify: `themes/danix-xyz-hacker/assets/css/main.css:357`
+
+- [ ] **Step 1: Update `.tag-cloud` rule**
+
+Find `.tag-cloud` rule (around line 357) and add `overflow: visible`:
+
+```css
+.tag-cloud {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 0.75rem;
+  align-items: baseline;
+  overflow: visible;
+}
+```
+
+- [ ] **Step 2: Rebuild CSS**
+
+Run: `npm run build`
+Expected: exits 0, `main.min.css` updated.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add themes/danix-xyz-hacker/assets/css/main.css themes/danix-xyz-hacker/assets/css/main.min.css
+git commit -m "feat: add overflow visible to tag-cloud container"
+```
+
+---
+
+### Task 3: Create the spiral JS module
+
+**Files:**
+- Create: `themes/danix-xyz-hacker/assets/js/tag-cloud-spiral.js`
+
+- [ ] **Step 1: Create the file with full algorithm**
+
+```javascript
+document.addEventListener('DOMContentLoaded', function () {
+  var containers = document.querySelectorAll('[data-tag-cloud]');
+  if (!containers.length) return;
+
+  Array.prototype.forEach.call(containers, function (container) {
+    if (container.offsetWidth < 400) return;
+
+    var links = Array.prototype.slice.call(
+      container.querySelectorAll('.tag-cloud-link')
+    );
+    if (!links.length) return;
+
+    // Sort descending by weight (biggest first = placed near center)
+    links.sort(function (a, b) {
+      return parseFloat(b.dataset.weight) - parseFloat(a.dataset.weight);
+    });
+
+    // String hash → deterministic angle seed (0..2π)
+    function hashAngle(str) {
+      var h = 0;
+      for (var i = 0; i < str.length; i++) {
+        h = (h * 31 + str.charCodeAt(i)) & 0xffffffff;
+      }
+      return ((h >>> 0) / 0xffffffff) * 2 * Math.PI;
+    }
+
+    // AABB collision check
+    function overlaps(a, b) {
+      return !(
+        a.right  < b.left  ||
+        a.left   > b.right ||
+        a.bottom < b.top   ||
+        a.top    > b.bottom
+      );
+    }
+
+    var placed = [];
+    var containerWidth = container.offsetWidth;
+    var cx = containerWidth / 2;
+
+    // Measure each tag before repositioning
+    var sizes = links.map(function (link) {
+      var rect = link.getBoundingClientRect();
+      return { w: rect.width, h: rect.height };
+    });
+
+    // Switch container to relative positioning
+    container.style.position = 'relative';
+    container.style.display = 'block';
+
+    var padding = 8; // px gap between tags
+    var aStep = 0.3; // radians per spiral step
+    var rScale = (containerWidth * 0.018); // spiral tightness
+
+    var minTop = 0, maxBottom = 0;
+
+    links.forEach(function (link, i) {
+      var w = sizes[i].w;
+      var h = sizes[i].h;
+      var seed = hashAngle(link.textContent.trim());
+      var theta = seed;
+      var placed_rect;
+
+      // Step along spiral until no collision
+      for (var attempt = 0; attempt < 2000; attempt++) {
+        var r = rScale * theta;
+        var x = cx + r * Math.cos(theta) - w / 2;
+        var y = r * Math.sin(theta) - h / 2;
+
+        var candidate = { left: x, top: y, right: x + w, bottom: y + h };
+        var collision = false;
+
+        for (var j = 0; j < placed.length; j++) {
+          var p = placed[j];
+          var padded = {
+            left: p.left - padding,
+            top: p.top - padding,
+            right: p.right + padding,
+            bottom: p.bottom + padding
+          };
+          if (overlaps(candidate, padded)) {
+            collision = true;
+            break;
+          }
+        }
+
+        if (!collision) {
+          placed_rect = candidate;
+          break;
+        }
+        theta += aStep;
+      }
+
+      if (!placed_rect) {
+        // Fallback: just append to flow if spiral exhausted
+        link.style.position = 'static';
+        return;
+      }
+
+      placed.push(placed_rect);
+
+      link.style.position = 'absolute';
+      link.style.left = Math.round(placed_rect.left) + 'px';
+      link.style.top = Math.round(placed_rect.top) + 'px';
+
+      if (placed_rect.top < minTop) minTop = placed_rect.top;
+      if (placed_rect.bottom > maxBottom) maxBottom = placed_rect.bottom;
+    });
+
+    // Normalize: shift all tags so topmost is at y=16px
+    var offset = 16 - minTop;
+    links.forEach(function (link) {
+      if (link.style.position === 'absolute') {
+        link.style.top = (parseInt(link.style.top) + offset) + 'px';
+      }
+    });
+
+    // Set container height to fit all tags + 2rem bottom padding
+    container.style.height = (maxBottom - minTop + 48) + 'px';
+  });
+});
+```
+
+- [ ] **Step 2: Verify file saved correctly**
+
+Run: `wc -l themes/danix-xyz-hacker/assets/js/tag-cloud-spiral.js`
+Expected: ~100 lines.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add themes/danix-xyz-hacker/assets/js/tag-cloud-spiral.js
+git commit -m "feat: add Archimedean spiral layout engine for tag cloud"
+```
+
+---
+
+### Task 4: Load the script via Hugo Pipes in baseof.html
+
+**Files:**
+- Modify: `themes/danix-xyz-hacker/layouts/_default/baseof.html`
+
+- [ ] **Step 1: Add script block after existing JS entries**
+
+In `baseof.html`, find the block of script tags (around line 83–120). Add after the last existing script block (before `</body>`):
+
+```html
+  <!-- Tag cloud spiral layout -->
+  {{ $tagCloudScript := resources.Get "js/tag-cloud-spiral.js" | minify }}
+  <script src="{{ $tagCloudScript.RelPermalink }}"></script>
+```
+
+- [ ] **Step 2: Verify Hugo builds without error**
+
+Run: `hugo` (build, not serve)
+Expected: exits 0, no errors about missing resources.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add themes/danix-xyz-hacker/layouts/_default/baseof.html
+git commit -m "feat: load tag-cloud-spiral.js via Hugo Pipes"
+```
+
+---
+
+### Task 5: End-to-end verification
+
+**Files:** None modified — verification only.
+
+- [ ] **Step 1: Start dev server and open homepage**
+
+Run: `hugo serve`
+Open: `http://localhost:1313`
+Expected: tag cloud at bottom of homepage shows spiral layout. Big tags near center, smaller tags scattered outward.
+
+- [ ] **Step 2: Test narrow viewport fallback**
+
+In browser devtools, set viewport width to 375px (iPhone SE).
+Expected: tag cloud falls back to flex-wrap layout (no absolute positioning applied).
+
+- [ ] **Step 3: Test JS-disabled fallback**
+
+In devtools → Settings → Debugger → "Disable JavaScript". Reload.
+Expected: tag cloud shows centered flex-wrap (current layout). No broken positioning.
+
+- [ ] **Step 4: Test sidebar tag cloud**
+
+Open any article page with sidebar.
+Expected: sidebar tag cloud (≤15 tags) also renders in spiral if container ≥ 400px; flex fallback on narrow.
+
+- [ ] **Step 5: Test 404 page**
+
+Open: `http://localhost:1313/404.html`
+Expected: tag cloud renders spiral layout.
+
+- [ ] **Step 6: Keyboard navigation**
+
+Tab through tags on homepage. Expected: all tags focusable in DOM order (weight descending), visible focus ring (accent outline).
+
+- [ ] **Step 7: Dark/light mode**
+
+Toggle theme. Expected: tag colors correct in both modes (CSS variables, not hardcoded).
+
+- [ ] **Step 8: Determinism check**
+
+Hard-reload page 3 times. Expected: tag positions identical each load.
+
+- [ ] **Step 9: Final commit if any fixups made**
+
+```bash
+git add -p
+git commit -m "fix: tag cloud spiral fixups from e2e verification"
+```
-- 
cgit v1.2.3