docs: move HYPERSCRIPT-RULES.md and MODERN-WEB-TECHNIQUES.md to doc/ folder

doc/HYPERSCRIPT-RULES.md

@@ -0,0 +1,134 @@
+# Hyperscript Development Rules
+
+## MANDATORY RULES - ALWAYS FOLLOW
+
+### Rule 1: Code Cleanliness
+**More than 3 lines of hyperscript → Move to function in file**
+
+- Inline hyperscript in HTML should be kept minimal (≤3 lines)
+- Longer logic MUST be extracted to named functions in .\_hs files
+- HTML templates should be clean and readable
+
+### Rule 2: File Structure - Hyperscript 0.9.12 Limitation
+**Maximum 3 `def` statements TOTAL across ALL files**
+
+⚠️ **CRITICAL**: Hyperscript 0.9.12 has a parser limitation - more than 3 `def` statements **across ALL loaded .\_hs files** causes:
+```
+Error: Expected 'end' but found 'def'
+```
+
+**Solution for Global Reusable Functions**: Use regular JavaScript instead
+- `static/js/cv-functions.js` - Global toggle and utility functions
+  - toggleCVLength(), toggleIcons(), toggleTheme()
+  - syncPdfHover(), syncPrintHover(), highlightZoomControl()
+
+**Solution for Hyperscript-Specific Logic**: Keep max 3 defs
+- `static/hyperscript/functions._hs` - ONLY hyperscript-specific utilities (printFriendly, initScrollBehavior, handleScroll)
+
+**Why JavaScript for Global Functions:**
+- ✅ No artificial limits
+- ✅ Better performance (native JS)
+- ✅ Better debugging
+- ✅ Can still be called from hyperscript using `call toggleIcons(my.checked)`
+
+### Rule 3: HTML Structure Cleanliness
+**HTML must be as clean as possible regarding hyperscript**
+
+✅ **GOOD** - Clean, readable:
+```html
+<input type="checkbox"
+       id="lengthToggle"
+       _="on change call toggleCVLength(my.checked)">
+```
+
+❌ **BAD** - Inline logic nightmare:
+```html
+<input type="checkbox"
+       id="lengthToggle"
+       _="on change
+            if my.checked
+              remove .cv-short from .cv-paper
+              add .cv-long to .cv-paper
+              set localStorage['cv-length'] to 'long'
+              set #lengthToggleMenu's checked to true
+            else
+              remove .cv-long from .cv-paper
+              add .cv-short to .cv-paper
+              set localStorage['cv-length'] to 'short'
+              set #lengthToggleMenu's checked to false
+            end">
+```
+
+## File Organization
+
+```
+static/hyperscript/
+├── functions._hs   → Core utilities (3 defs max)
+├── toggles._hs     → Toggle functions (3 defs max)
+└── hover._hs       → Hover sync functions (3 defs max)
+```
+
+### Load Order in templates/index.html:
+```html
+<script type="text/hyperscript" src="/static/hyperscript/functions._hs"></script>
+<script type="text/hyperscript" src="/static/hyperscript/toggles._hs"></script>
+<script type="text/hyperscript" src="/static/hyperscript/hover._hs"></script>
+<script src="https://unpkg.com/hyperscript.org@0.9.12"></script>
+```
+
+## Required Functions
+
+### Core Functions (functions._hs)
+1. `printFriendly()` - Handle print-friendly view
+2. `initScrollBehavior()` - Initialize scroll variables
+3. `handleScroll()` - Manage scroll behavior and fixed button positioning
+
+### Toggle Functions (toggles._hs)
+1. `toggleCVLength(isLong)` - Switch between short/long CV
+2. `toggleIcons(showIcons)` - Show/hide icons
+3. `toggleTheme(isClean)` - Switch between default/clean theme
+
+### Hover Sync Functions (hover._hs)
+1. `syncPdfHover(show)` - Sync hover state across PDF buttons
+2. `syncPrintHover(show)` - Sync hover state across print buttons
+3. `highlightZoomControl(show)` - Highlight zoom control on hover
+
+## Why These Rules Exist
+
+### Maintainability
+- Functions with descriptive names are self-documenting
+- Easier to test and debug
+- Changes in one place instead of scattered across templates
+
+### Performance
+- Browser caches .\_hs files
+- Reduces HTML payload size
+- Cleaner separation of concerns
+
+### Hyperscript 0.9.12 Limitation
+- Parser breaks with >3 `def` in single file
+- MUST split into multiple files
+- Each file: ≤3 `def` statements
+
+## Common Mistakes to Avoid
+
+❌ **DON'T**: Put all functions in one file if you have >3 defs
+❌ **DON'T**: Write long inline hyperscript in HTML
+❌ **DON'T**: Delete functions to work around the 3-def limit
+
+✅ **DO**: Split functions across multiple .\_hs files
+✅ **DO**: Keep HTML clean with function calls
+✅ **DO**: Maintain all required functions for clean architecture
+
+## Testing After Changes
+
+1. Check browser console for parse errors
+2. Verify all functions are defined (no "X is null" errors)
+3. Test all toggles work correctly
+4. Hard refresh browser (Ctrl+Shift+R) to clear cache
+
+---
+
+**Last Updated**: 2025-01-17
+**Hyperscript Version**: 0.9.12
+**Status**: MANDATORY - ALWAYS FOLLOW