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**
- [x] **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**
- [x] **HTML Semantics Approach**: Use HTML tag semantics for block vs inline detection
- [x] **Framework Agnostic Processing**: No special framework container detection
- [x] **Boundary Rules**: Only `.insertr` elements are boundaries, traverse all other containers
- [x] **Block/Inline Classification**: Clear rules for when elements get `.insertr` vs formatting

#### **Implementation Status** 
- [x] **Backend Container Transformation**: Implemented syntactic sugar transformation in `internal/engine/engine.go`
- [x] **Frontend Container Logic Removal**: Cleaned up `lib/src/core/insertr.js` - frontend finds enhanced elements only
- [x] **Backend Viable Children**: Updated `internal/engine/utils.go` with comprehensive block/inline logic
- [x] **Recursive Traversal**: Deep nesting support with proper boundary respect implemented
- [x] **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**
```yaml
# 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**
```html
<!-- 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**