insertr/TODO.md

Insertr Development Roadmap

🎯 Current Status (September 2025)

✅ Complete Full-Stack CMS

• Style-Aware Editor: Rich text editing with automatic style detection and formatting toolbar
• HTML Preservation: Perfect fidelity editing that maintains all element attributes and styling
• HTTP API Server: Full REST API with authentication, version control, and rollback
• Multi-Database Support: SQLite (development) + PostgreSQL (production)
• Authentication System: Mock (development) + Authentik OIDC (production)
• Build-Time Enhancement: Content injection from database to static HTML
• Development Workflow: Hot reload, auto-enhanced demo sites, seamless testing
• Container Transformation: CLASSES.md syntactic sugar - containers auto-expand to viable children

🏗️ Architecture Achievements

• Zero Configuration: Just add class="insertr" to any element
• Framework Agnostic: Works with any static site generator
• Performance First: Regular visitors get pure static HTML with zero CMS overhead
• HTML-First: No lossy markdown conversion - perfect attribute preservation
• Unified System: Single HTML preservation path for all content types
• Element-Based Behavior: Automatic editing interface based on HTML tag semantics

---

🚀 Priority Roadmap

🔴 Phase 1: Editor Integration Polish (High Priority)

Frontend-Backend Integration

• Editor-API Connection: StyleAware editor saves successfully to HTTP API
• Error Handling: Proper error states, loading indicators, offline handling
• Content Validation: Client-side validation before API calls
• Save Feedback: Professional save/error feedback in editor interface

User Experience Enhancements

• Draft Auto-Save: LocalStorage drafts during editing with recovery
• Optimistic Updates: Immediate UI feedback, background sync
• Conflict Resolution: Handle concurrent editing scenarios
• Editor Performance: Optimize style detection for large pages

🟡 Phase 2: Production Deployment (Medium Priority)

Production Workflows

• CI/CD Integration: GitHub Actions templates for static site generators
• Deployment Examples: Netlify, Vercel, CloudFlare Pages integration guides
• CDN Configuration: Library asset hosting and optimization
• Database Migrations: Schema versioning and update strategies

Enterprise Features

• Multi-Site API: Single server managing multiple site content
• User Management: Role-based access control and permissions
• Content Approval: Editorial workflows and publishing controls
• Performance Monitoring: Analytics and optimization tools

✅ Phase 3: Container Expansion Intelligence (Complete)

Element Classification and Boundaries

• HTML Semantics Approach: Use HTML tag semantics for block vs inline detection
• Framework Agnostic Processing: No special framework container detection
• Boundary Rules: Only .insertr elements are boundaries, traverse all other containers
• Block/Inline Classification: Clear rules for when elements get .insertr vs formatting

Implementation Status

• Backend Container Transformation: Implemented syntactic sugar transformation in internal/engine/engine.go
• Frontend Container Logic Removal: Cleaned up lib/src/core/insertr.js - frontend finds enhanced elements only
• Backend Viable Children: Updated internal/engine/utils.go with comprehensive block/inline logic
• Recursive Traversal: Deep nesting support with proper boundary respect implemented
• CLASSES.md Compliance: Container expansion now follows specification exactly

Complex Element Handling (Deferred)

• Table Editing: Complex hierarchy needs separate planning for <table>, <tr>, <td> elements

  • Tables have nested semantic structure that doesn't fit simple block/inline model
  • Need to determine: Should individual cells be editable? Entire table? Row-level?
  • Consider: Table headers, captions, complex layouts, accessibility concerns

• Form Element Editing: Interactive form controls need specialized editors

  • <input> fields: Different types need different editing interfaces (text, email, etc.)
  • <textarea>: Should get rich text editing or preserve plain text?
  • <select> options: Need dynamic option management interface
  • <form> containers: Validation rules, action URLs, method selection
  • Consider: Form submission handling, validation, accessibility

• Self-Closing Element Management: Media and input elements

  • <img>: Alt text, src, responsive image sets, lazy loading
  • <video>/<audio>: Multiple sources, controls, accessibility features
  • <input>: Type-specific validation, placeholder text, required fields

🟢 Phase 4: Advanced CMS Features (Low Priority)

Content Management Enhancements

• Media Management: Image upload, asset management, optimization
• Content Templates: Reusable content blocks and page templates
• Search and Filtering: Content discovery and organization tools
• Import/Export: Bulk content operations and migration tools

Developer Experience

• Plugin System: Extensible content types and field configurations
• Testing Framework: Automated testing for content workflows
• Documentation Site: Interactive documentation with live examples
• Performance Profiling: Development tools and optimization guides

---

🌐 Future Features (Planned)

Production Static Site Hosting

Goal: Extend current development multi-site server to production static site hosting

Current State: Development server hosts enhanced demo sites at /sites/{site_id}/ for testing convenience.

Future Enhancement: Production-ready static site hosting with content management.

Proposed Production Static Site Server

• Use Case: Small to medium sites that want unified hosting + content management
• Alternative to: Netlify CMS + hosting, Forestry + Vercel, etc.
• Benefit: Single server handles both static hosting AND content API

Architecture: Static file serving WITHOUT enhancement

• Static Serving: Serve pre-enhanced files efficiently (like nginx/Apache)
• Content API: Separate /api/* endpoints for content management
• Build Triggers: Content changes trigger static site rebuilds
• Multi-Tenant: Multiple sites with custom domains

Configuration Example

# insertr.yaml (future production mode)
server:
  mode: "production"
  sites:
    - site_id: "mysite"
      domain: "mysite.com"
      path: "/var/www/mysite"          # Pre-enhanced static files
      ssl_cert: "/etc/ssl/mysite.pem"
      rebuild_command: "hugo && insertr enhance ./public --output /var/www/mysite"
    
    - site_id: "blog" 
      domain: "blog.example.com"
      path: "/var/www/blog"
      rebuild_command: "npm run build"

Implementation Plan

• Static File Server: Efficient static file serving (no enhancement)
• Domain Routing: Route custom domains to appropriate site directories
• SSL/TLS Support: Automatic certificate management (Let's Encrypt)
• Build Triggers: Webhook system to trigger site rebuilds after content changes
• Performance: CDN integration, compression, caching headers
• Monitoring: Site uptime, performance metrics, error logging

Priority: Low - implement after core content management features are stable

Advanced Style Preview System

Current State: Basic style button previews using getComputedStyle() to show formatting effects.

Future Style Preview Enhancements

• Enhanced Style Support: Background colors, borders, typography with safety constraints
• Interactive Previews: Hover effects, animations, responsive previews
• Custom Style Creation: Visual style picker with live preview
• Style Inheritance Display: Show which properties come from which CSS classes
• Accessibility Validation: Ensure previews meet contrast and readability standards

Advanced Access Control

Current State: Simple boolean authentication gate for page-level editing access.

Future Enhancement: Role-based access control and section-level permissions for enterprise applications.

Potential Extended Gate Classes

<!-- Current: Simple page-level auth -->
<div class="insertr-gate"></div>

<!-- Future: Role-based section permissions -->
<div class="admin-content insertr-gate-admin">
  <div class="insertr-add">Admin-only dynamic content</div>
</div>

<div class="editor-section insertr-gate-editor">
  <div class="insertr-content">Editor-level rich content</div>
</div>

Enterprise Use Cases

• Multi-tenant Applications: Different organizations editing separate content areas
• Editorial Workflows: Writers, editors, and admins with different capabilities
• Subscription Content: Different content areas for different subscription tiers
• Department Permissions: Marketing vs Engineering vs Sales content areas

Priority: Low - implement after core functionality is stable and enterprise customers request advanced permissions.

---

📊 Success Metrics

Phase 1 Complete When:

• ✅ Editor saves successfully to HTTP API in all demo sites
• ✅ Error handling provides clear feedback for all failure scenarios
• ✅ Draft auto-save prevents content loss during editing
• ✅ Performance is acceptable on large pages with many editable elements

Phase 2 Complete When:

• ✅ Production deployment guides for major platforms (Netlify, Vercel, etc.)
• ✅ Enterprise authentication working with real Authentik instances
• ✅ Multi-site content management for production use cases
• ✅ CDN hosting for insertr.js library with version management

Production Ready When:

• ✅ Real-world sites using Insertr in production successfully
• ✅ Performance benchmarks meet or exceed existing CMS solutions
• ✅ Security audit completed for authentication and content handling
• ✅ Documentation and examples cover all major use cases

---

🔧 Development Principles

1. Zero Configuration: Markup-driven approach, no schema files
2. HTML-First: Perfect attribute preservation, no lossy conversions
3. Performance: Zero runtime cost for regular site visitors
4. Framework Agnostic: Works with any static site generator
5. Developer Experience: Minimal cognitive overhead, stays in markup
6. Progressive Enhancement: Sites work without JavaScript, editing enhances with JavaScript

Built with ❤️ for developers who want powerful editing without the complexity