From ee06b957f9a008262e1051e57330b6db2f60aecc Mon Sep 17 00:00:00 2001
From: juanatsap <juanatsap@gmail.com>
Date: Mon, 17 Nov 2025 14:22:23 +0000
Subject: [PATCH] docs: correct PROJECT-MEMORY.md with accurate architecture
 info
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Critical corrections based on user feedback:

1. Hyperscript Parser Limit (Section 2)
   - Changed status to "NEEDS RETESTING" with latest hyperscript version
   - 3 def statement limit may no longer exist after upgrade
   - TODO: Test if limit still applies with current version

2. Toggle + Hover Synchronization (Section 3)
   - Clarified toggle checkboxes WORK perfectly ✅
   - Documented HOVER SYNC BUG for PDF/Print buttons ❌
   - Action bar hover doesn't sync with menu button hover
   - Added file references and bug details
   - Test coverage gap identified

3. Real-Time Rendering + Persistence (Section 4)
   - Corrected misconception: BOTH DOM and localStorage required
   - Not mutually exclusive - need instant feedback AND persistence
   - Added clear examples of correct vs incorrect implementation

4. Architecture - Tech Stack
   - CORRECTED: Backend is Go (NOT Bun/Hono)
   - Go 1.21+ with standard library net/http
   - Bun is ONLY test runner, not the runtime
   - Added complete frontend stack details

5. File Organization
   - CORRECTED: Actual Go project structure
   - main.go entry point (v1.1.0)
   - internal/ package organization
   - Complete template hierarchy
   - Critical files list updated

Fixes hallucinated architecture information and provides accurate
technical foundation for future developers.
---
 PROJECT-MEMORY.md | 156 ++++++++++++++++++++++++++++++++--------------
 1 file changed, 108 insertions(+), 48 deletions(-)

diff --git a/PROJECT-MEMORY.md b/PROJECT-MEMORY.md
index cf69d4f..9e62013 100644
--- a/PROJECT-MEMORY.md
+++ b/PROJECT-MEMORY.md
@@ -32,16 +32,15 @@ const showLogos = ...
 
 ---
 
-### 2. Hyperscript Parser Limit (CRITICAL)
+### 2. Hyperscript Parser Limit (NEEDS RETESTING)
 
-**Maximum 3 `def` statements total across ALL files**
+**⚠️ TO VERIFY: Maximum 3 `def` statements limit with latest hyperscript version**
 
-Hyperscript 0.9.14 has a hard parser limit:
-- ✅ Max 3 `def` statements across entire application
-- ✅ Count includes ALL `<script type="_hyperscript">` blocks
-- ✅ Count includes ALL inline `_="def ..."` attributes
+**Status:** We upgraded to the LATEST hyperscript version. This limit may no longer exist.
 
-**Solution:** Move complex logic to JavaScript functions
+**TODO:** Test if the 3 `def` statement limit still applies with current version
+
+**Current solution (still recommended):** Move complex logic to JavaScript functions
 
 ```javascript
 // ✅ CORRECT - JavaScript functions
@@ -66,15 +65,15 @@ _="def toggleIcons(show)
 
 ---
 
-### 3. Toggle Synchronization (CRITICAL)
+### 3. Toggle Synchronization (WORKING) + Hover Sync (BROKEN)
 
-**Action bar and menu toggles MUST stay synchronized**
+**Toggle checkboxes WORK perfectly ✅**
 
-Every toggle exists in TWO places:
+Every toggle checkbox exists in TWO places and stays synchronized:
 1. Action bar (desktop) - `#lengthToggle`, `#iconToggle`, `#themeToggle`
 2. Hamburger menu (mobile) - `#lengthToggleMenu`, `#iconToggleMenu`, `#themeToggleMenu`
 
-**Required behavior:**
+**Toggle behavior (WORKING):**
 - ✅ Clicking either toggle updates BOTH
 - ✅ Changes are real-time (no page refresh)
 - ✅ localStorage persists the state
@@ -99,25 +98,57 @@ function toggleIcons(showIcons) {
 }
 ```
 
-**Test that enforces this:** `tests/mjs/1-toggles.test.mjs`
+**⚠️ HOVER SYNC BUG - PDF/Print buttons NOT synchronized**
+
+**Action buttons that SHOULD sync hover states:**
+1. Action bar (desktop):
+   - `#action-bar-pdf-btn` - Download PDF button
+   - `.action-bar-print-btn` - Print Friendly button
+2. Hamburger menu (mobile):
+   - PDF button (templates/partials/navigation/hamburger-menu.html:178)
+   - `.menu-print-btn` (templates/partials/navigation/hamburger-menu.html:183)
+
+**Current hover sync functions exist but DON'T WORK:**
+- `syncPdfHover(isHovering)` - SHOULD sync PDF button hover between locations
+- `syncPrintHover(isHovering)` - SHOULD sync Print button hover between locations
+
+**THE BUG:** Hovering action bar buttons DOES NOT highlight menu buttons
+
+**Files affected:**
+- `templates/partials/navigation/action-buttons.html` (lines 9-10, 18-19)
+- `templates/partials/navigation/hamburger-menu.html` (lines 185-186)
+- `static/js/cv-functions.js` - hover sync functions incomplete/broken
+
+**Test coverage:** `tests/mjs/1-toggles.test.mjs` doesn't verify hover states (NEEDS test case)
+
+**Test that enforces toggle sync:** `tests/mjs/1-toggles.test.mjs` ✅
 
 ---
 
-### 4. Real-Time Rendering (CRITICAL)
+### 4. Real-Time Rendering + Persistence (CRITICAL)
 
-**ALL UI changes MUST happen without page refresh**
+**ALL UI changes MUST happen in BOTH DOM and localStorage**
+
+**BOTH are required - not mutually exclusive:**
 
 ```javascript
-// ✅ CORRECT - Immediate DOM update
-paper.classList.add('show-icons');  // CSS change happens instantly
+// ✅ CORRECT - DOM update AND localStorage
+paper.classList.add('show-icons');        // Visual change (instant feedback)
+localStorage.setItem('cv-icons', 'true'); // Persistence (survives reload)
 
-// ❌ WRONG - Requires refresh
-localStorage.setItem('cv-icons', 'true');  // Only storage, no visual change
+// ❌ WRONG - Only DOM (lost on page reload)
+paper.classList.add('show-icons');
+
+// ❌ WRONG - Only storage (no visual feedback)
+localStorage.setItem('cv-icons', 'true');
 ```
 
-**Why:** Users expect instant feedback. Any delay or refresh requirement feels broken.
+**Why both are needed:**
+- **DOM changes** = instant visual feedback (users see it immediately)
+- **localStorage** = state persists across page reloads (users don't lose their preferences)
+- Users need BOTH: instant feedback + remembered preferences
 
-**Test that enforces this:** `tests/mjs/1-toggles.test.mjs` (with screenshot verification)
+**Test that enforces this:** `tests/mjs/1-toggles.test.mjs` (verifies both DOM and localStorage)
 
 ---
 
@@ -156,48 +187,77 @@ bun tests/run-all.mjs
 
 ### Tech Stack
 
-**Runtime & Framework:**
-- ✅ Bun (JavaScript runtime)
-- ✅ Hono (Web framework)
-- ✅ HTMX (Hypermedia)
-- ✅ Hyperscript 0.9.14 (Event handling - LIMITED USE)
+**Backend:**
+- ✅ Go 1.21+ (Backend server)
+- ✅ Standard library `net/http` (HTTP server)
+- ✅ Go templates (Server-side rendering)
+
+**Frontend:**
+- ✅ HTMX (Hypermedia-driven interactions)
+- ✅ Hyperscript (Latest version - event handling)
+- ✅ Vanilla JavaScript (cv-functions.js - toggles, keyboard shortcuts)
+- ✅ Iconify (Icon system)
+
+**Testing:**
+- ✅ Playwright (E2E browser automation)
+- ✅ Bun (Test runner ONLY - NOT the runtime!)
+
+**Why Go:**
+- Fast compilation
+- Single binary deployment
+- Built-in templating
+- Excellent standard library
+- Strong typing
+- Cross-platform
 
 **Why HTMX + Hyperscript:**
 - Server-driven UI (hypermedia pattern)
 - Minimal JavaScript
 - Progressive enhancement
-- Real-time updates via SSE
-
-**Why Bun:**
-- Fast runtime
-- Built-in TypeScript
-- Native test runner
-- Single tool for everything
+- Real-time updates capabilities
 
 ### File Organization
 
 ```
 cv/
-├── server.ts                    # Hono server
+├── main.go                      # Server entry point (v1.1.0)
+├── go.mod, go.sum               # Go dependencies
+├── internal/
+│   ├── config/                  # Configuration
+│   ├── handlers/                # HTTP handlers
+│   ├── middleware/              # HTTP middleware
+│   ├── models/                  # Data models
+│   ├── routes/                  # Route definitions
+│   └── templates/               # Template utilities
 ├── static/
 │   ├── js/
-│   │   └── cv-functions.js     # Global functions (toggles, keyboard shortcuts)
-│   └── css/
-│       └── styles.css
+│   │   └── cv-functions.js      # Global functions (toggles, keyboard, hover sync)
+│   ├── css/                     # Stylesheets
+│   ├── hyperscript/
+│   │   └── functions._hs        # Hyperscript functions (if any)
+│   ├── images/                  # Static images
+│   └── pdf/                     # PDF files
 ├── templates/
-│   ├── index.html              # Main template
+│   ├── index.html               # Main page template
+│   ├── cv-content.html          # CV content
+│   ├── language-switch.html     # Language switcher
 │   └── partials/
-│       └── navigation/
-│           ├── view-controls.html    # Action bar toggles
-│           └── hamburger-menu.html   # Mobile menu
+│       ├── navigation/
+│       │   ├── action-bar.html        # Desktop action bar
+│       │   ├── action-buttons.html    # PDF + Print buttons
+│       │   └── hamburger-menu.html    # Mobile menu (ALL controls + buttons)
+│       ├── widgets/             # Reusable UI components
+│       └── modals/              # Modal dialogs
 └── tests/
-    └── mjs/                     # Systematic test suite
+    └── mjs/                     # Systematic test suite (Playwright + Bun runner)
 ```
 
 **Critical files:**
-- `static/js/cv-functions.js` - All global toggle/keyboard functions
-- `templates/partials/navigation/view-controls.html` - Action bar toggles
-- `templates/partials/navigation/hamburger-menu.html` - Mobile menu toggles
+- `main.go` - Server entry point
+- `static/js/cv-functions.js` - Toggle, keyboard, and hover sync functions
+- `templates/partials/navigation/action-buttons.html` - PDF + Print buttons (action bar)
+- `templates/partials/navigation/hamburger-menu.html` - Complete mobile menu with toggles + buttons
+- `templates/index.html` - Main template structure
 
 ---
 
@@ -369,13 +429,13 @@ document.addEventListener('keydown', (e) => {
 
 ### Must Read Before Changes
 - `tests/README.md` - Test suite accountability
-- `HYPERSCRIPT-RULES.md` - Parser limits and workarounds
+- `doc/HYPERSCRIPT-RULES.md` - Parser limits and workarounds
 - `~/.claude/cv-icons-migration.md` - Icon naming convention
 
 ### Reference Documentation
 - `tests/TEST-SUMMARY.md` - Complete test documentation
 - `tests/mjs/README.md` - Test structure and patterns
-- `MODERN-WEB-TECHNIQUES.md` - Architecture decisions
+- `doc/MODERN-WEB-TECHNIQUES.md` - Architecture decisions
 
 ### Historical Record
 - `tests/archive/README.md` - Legacy tests (reference only)
@@ -405,7 +465,7 @@ document.addEventListener('keydown', (e) => {
 **Rule:** Read framework documentation carefully, especially limits/constraints
 
 ### 4. Synchronization Is Hard
-**Lesson:** Having toggles in two places (action bar + menu) means every change must update both. Forgetting this causes desync bugs.
+**Lesson:** Having toggles in two or more places (action bar + menu) means every change must update all locations. Forgetting this causes desync bugs.
 
 **Rule:** If something appears in multiple places, use a single function to update ALL locations
 
@@ -434,7 +494,7 @@ document.addEventListener('keydown', (e) => {
 1. Which test should have caught this?
 2. Why didn't it?
 3. Fix the test FIRST
-4. Then fix the bug
+4. Then fix the bug, using the debug agent and the htmx expert
 5. Document the lesson in this file
 
 **Remember:**