# Development Guardrails

## JavaScript Code Principles

### 1. No Inline JavaScript in Python
**NEVER write JavaScript code directly from Python code**

❌ **Wrong:**
```python
script = f"""
function myFunction() {{
    console.log("Hello {name}");
}}
"""
```

✅ **Correct:**
```python
# Load from external files only
components = [
    'js/core/section-manager.js',
    'js/components/debug-panel.js',
    'js/components/document-controls.js'
]
```

### 2. Why This Rule Exists
- **Quoting Problems**: String escaping in Python corrupts JavaScript
- **Syntax Errors**: Template literals and complex JS break when embedded
- **Maintainability**: JS code should be in .js files for proper tooling
- **Architecture**: Follows the established modular component system

### 3. Proper Approach
1. Create separate `.js` files in `markitect/static/js/components/`
2. Load them via `_get_clean_editor_scripts()`
3. Wire up components in the initialization script only

## Testing and Validation

### 1. Always Validate Generated HTML
- Check that HTML files actually render content
- Validate JavaScript syntax before deployment
- Test both viewing and editing modes

### 2. Detect JavaScript Errors Programmatically
- Run syntax validation on generated JS
- Check for common error patterns
- Fail fast when JS is malformed

### 3. Manual Testing Backup
- If automated checks pass but functionality fails
- Open generated HTML in browser
- Check console for runtime errors
- Report specific error messages

## Architecture Principles

### 1. Separation of Concerns
- Python: File generation, template management
- JavaScript: UI components, interaction logic
- HTML: Structure and content only

### 2. Modular Component System
- Each UI component in separate file
- Lazy loading where appropriate
- Clear dependency management

### 3. Error Handling
- Graceful degradation when components fail
- Clear error messages for debugging
- Fallback modes when possible

## Breaking These Rules

If you find yourself writing JavaScript in Python strings:
1. **STOP** - Step back and reconsider
2. Create a proper component file instead
3. Use the existing component loading system
4. Add validation to catch the issue early

These guardrails exist because we've seen the problems when they're violated.