markitect-main/GUARDRAILS.md

Development Guardrails

JavaScript Code Principles

1. No Inline JavaScript in Python

NEVER write JavaScript code directly from Python code

❌ Wrong:

script = f"""
function myFunction() {{
    console.log("Hello {name}");
}}
"""

✅ Correct:

# 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.