docs: correct PROJECT-MEMORY.md with accurate architecture info
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.
This commit is contained in:
juanatsap
+108
-48
@@ -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:**
|
||||
|
||||
Reference in New Issue
Block a user