Complete library cleanup and documentation overhaul
## Library Code Cleanup (~1,200+ lines removed) - Remove legacy markdown system (markdown.js, previewer.js) - Delete unused EditContext code from ui/editor.js (~400 lines) - Remove version history UI components from form-renderer.js (~180 lines) - Clean unused CSS styles from insertr.css (~120 lines) - Update package.json dependencies (remove marked, turndown) ## Documentation Updates - README.md: Update from markdown to HTML-first approach - AGENTS.md: Add current architecture guidance and HTML-first principles - TODO.md: Complete rewrite with realistic roadmap and current status - demos/README.md: Update for development demo server usage ## System Reality Alignment - All documentation now reflects current working system - Removed aspirational features in favor of actual capabilities - Clear separation between development and production workflows - Accurate description of style-aware editor with HTML preservation ## Code Cleanup Benefits - Simplified codebase focused on HTML-first approach - Removed markdown conversion complexity - Cleaner build process without unused dependencies - Better alignment between frontend capabilities and documentation Ready for Phase 3a server updates with clean foundation.
This commit is contained in:
738
TODO.md
738
TODO.md
@@ -1,497 +1,134 @@
|
||||
# Insertr Development TODO
|
||||
# Insertr Development Roadmap
|
||||
|
||||
## 🔍 Architecture Analysis Complete (Dec 2024)
|
||||
## 🎯 **Current Status** (September 2025)
|
||||
|
||||
**Key Discovery**: The architecture is already 90% complete and brilliantly designed! The missing piece is not LocalStorage persistence, but the **HTTP server application** that implements the API contract both clients expect.
|
||||
### **✅ 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
|
||||
|
||||
## ✅ What's Already Built & Working
|
||||
|
||||
### **Complete Foundation**
|
||||
- ✅ **Go Content Client** - Full REST API client with all CRUD operations (`internal/content/client.go`)
|
||||
- ✅ **JavaScript API Client** - Browser client with same API endpoints (`lib/src/core/api-client.js`)
|
||||
- ✅ **Content Types** - Well-defined data structures (`ContentItem`, `ContentResponse`)
|
||||
- ✅ **Mock Backend** - Working development server with realistic test data
|
||||
- ✅ **Build-Time Enhancement** - Content injection from database → HTML during builds
|
||||
- ✅ **Authentication System** - Complete auth flow ready for server integration
|
||||
- ✅ **Professional Editor** - Modal forms, validation, smart field detection
|
||||
|
||||
### **Architecture Philosophy Preserved**
|
||||
- ✅ **"Tailwind of CMS"** - Zero configuration, build-time optimization
|
||||
- ✅ **Framework Agnostic** - Works with any static site generator
|
||||
- ✅ **Performance First** - Regular visitors get pure static HTML
|
||||
- ✅ **Editor Progressive Enhancement** - Editing assets only load when needed
|
||||
|
||||
## 🚨 **CRITICAL MISSING PIECE**
|
||||
|
||||
### **HTTP Server Application** (90% of work remaining)
|
||||
The CLI client and JavaScript client both expect a server at `/api/content/*`, but **no server exists**!
|
||||
|
||||
**Required API Endpoints**:
|
||||
```
|
||||
GET /api/content/{id}?site_id={site} # Get single content
|
||||
GET /api/content?site_id={site} # Get all content for site
|
||||
GET /api/content/bulk?site_id={site}&ids[]=... # Bulk get content
|
||||
PUT /api/content/{id} # Update existing content
|
||||
POST /api/content # Create new content
|
||||
```
|
||||
|
||||
**Current State**: Both clients make HTTP calls to these endpoints, but they 404 because no server implements them.
|
||||
|
||||
## 🎯 **Immediate Implementation Plan**
|
||||
|
||||
### **🔴 Phase 1: HTTP Server (CRITICAL)**
|
||||
**Goal**: Build the missing server application that implements the API contract
|
||||
|
||||
#### 1.1 **Go HTTP Server** ⭐ **HIGHEST PRIORITY**
|
||||
- [ ] **REST API Server** - Implement all 5 required endpoints
|
||||
- [ ] **Database Layer** - SQLite for development, PostgreSQL for production
|
||||
- [ ] **Authentication Middleware** - JWT/OAuth integration
|
||||
- [ ] **CORS & Security** - Proper headers for browser integration
|
||||
- [ ] **Content Validation** - Input sanitization and type checking
|
||||
|
||||
#### 1.2 **Integration Testing**
|
||||
- [ ] **CLI Client Integration** - Test all CLI commands work with real server
|
||||
- [ ] **JavaScript Client Integration** - Test browser editor saves to real server
|
||||
- [ ] **End-to-End Workflow** - Edit → Save → Build → Deploy cycle
|
||||
|
||||
### **🟡 Phase 2: Production Polish (IMPORTANT)**
|
||||
|
||||
#### 2.1 **Client-Side Enhancements**
|
||||
- [ ] **Editor-Server Integration** - Wire up `handleSave` to use `ApiClient`
|
||||
- [ ] **Optimistic Updates** - Show immediate feedback, sync in background
|
||||
- [ ] **Offline Support** - LocalStorage cache + sync when online
|
||||
- [ ] **Loading States** - Professional feedback during saves
|
||||
|
||||
#### 2.2 **Deployment Pipeline**
|
||||
- [ ] **Build Triggers** - Auto-rebuild sites when content changes
|
||||
- [ ] **Multi-Site Support** - Handle multiple domains/site IDs
|
||||
- [ ] **CDN Integration** - Host insertr.js library on CDN
|
||||
- [ ] **Database Migrations** - Schema versioning and updates
|
||||
|
||||
### **🟢 Phase 3: Advanced Features (NICE-TO-HAVE)**
|
||||
|
||||
#### 3.1 **Content Management Enhancements**
|
||||
- [ ] **Content Versioning** - Track edit history and allow rollbacks
|
||||
- [ ] **Content Validation** - Advanced validation rules per content type
|
||||
- [ ] **Markdown Enhancements** - Live preview, toolbar, syntax highlighting
|
||||
- [ ] **Media Management** - Image upload and asset management
|
||||
|
||||
#### 3.2 **Developer Experience**
|
||||
- [ ] **Development Tools** - Better debugging and development workflow
|
||||
- [ ] **Configuration API** - Extensible field type system
|
||||
- [ ] **Testing Suite** - Comprehensive test coverage
|
||||
- [ ] **Documentation** - API reference and integration guides
|
||||
|
||||
## 💡 **Key Architectural Insights**
|
||||
|
||||
### **Why This Architecture is Brilliant**
|
||||
1. **Performance First**: Regular visitors get pure static HTML with zero CMS overhead
|
||||
2. **Separation of Concerns**: Content editing completely separate from site performance
|
||||
3. **Build-Time Optimization**: Database content gets "baked into" static HTML during builds
|
||||
4. **Progressive Enhancement**: Sites work without JavaScript, editing enhances with JavaScript
|
||||
5. **Framework Agnostic**: Works with Hugo, Next.js, Jekyll, Gatsby, vanilla HTML, etc.
|
||||
|
||||
### **Production Flow**
|
||||
```
|
||||
Content Edits → HTTP API Server → Database
|
||||
↓
|
||||
Static Site Build ← CLI Enhancement ← Database Content
|
||||
↓
|
||||
Enhanced HTML → CDN/Deploy
|
||||
```
|
||||
|
||||
### **Current Working Flow**
|
||||
```
|
||||
✅ Browser Editor → (404) Missing Server → ❌
|
||||
✅ CLI Enhancement ← Mock Data ← ✅
|
||||
✅ Static HTML Generation ← ✅
|
||||
```
|
||||
|
||||
**Gap**: The HTTP server that connects editor saves to database storage.
|
||||
|
||||
## 🗂️ **Next Steps: Server Implementation**
|
||||
|
||||
### **✅ Implemented - Unified Binary Architecture**
|
||||
```
|
||||
✅ COMPLETED: All server functionality integrated into unified binary
|
||||
cmd/
|
||||
├── serve.go # Runtime API server command
|
||||
└── enhance.go # Build-time enhancement command
|
||||
internal/
|
||||
├── api/ # HTTP handlers and middleware
|
||||
├── db/ # Multi-database layer with sqlc
|
||||
└── content/ # Content management logic
|
||||
```
|
||||
|
||||
### **Files to Modify**
|
||||
- `lib/src/core/editor.js:91` - Wire up `ApiClient` to `handleSave` method
|
||||
- `README.md` - Add server setup instructions
|
||||
- `docker-compose.yml` - Add server for development stack
|
||||
|
||||
## 🎯 **Success Criteria**
|
||||
|
||||
### **Phase 1 Complete When**:
|
||||
- ✅ HTTP server running on `localhost:8080` (or configurable port)
|
||||
- ✅ All 5 API endpoints returning proper JSON responses
|
||||
- ✅ JavaScript editor successfully saves edits to database
|
||||
- ✅ CLI enhancement pulls latest content from database
|
||||
- ✅ Full edit → save → build → view cycle working end-to-end
|
||||
|
||||
### **Production Ready When**:
|
||||
- ✅ Multi-site support with proper site isolation
|
||||
- ✅ Authentication and authorization working
|
||||
- ✅ Database migrations strategy
|
||||
- ✅ CDN hosting for insertr.js library
|
||||
- ✅ Deployment documentation and examples
|
||||
|
||||
## Current Architecture Status
|
||||
|
||||
### ✅ **What's Working Well**
|
||||
- **CLI Parser**: Detects 41+ elements across demo site, generates stable IDs
|
||||
- **Authentication System**: Professional login/edit mode toggle with visual states
|
||||
- **Form System**: Dynamic modal forms with smart field detection
|
||||
- **Build Pipeline**: Automated library building and copying to demo site
|
||||
- **Development Experience**: Hot reload with Air integration
|
||||
|
||||
### 🔍 **Investigation Results**
|
||||
- **File Analysis**: All legacy code removed, clean single implementation
|
||||
- **Integration Testing**: CLI ↔ Library integration works seamlessly
|
||||
- **Demo Site**: Both index.html and about.html use modern library correctly
|
||||
- **Content Detection**: CLI successfully identifies text/markdown/link content types
|
||||
|
||||
## Immediate Next Steps
|
||||
|
||||
### 🎯 **Priority 1: Content Persistence**
|
||||
**Goal**: Make edits survive page reload
|
||||
- Create `lib/src/core/content-manager.js` for LocalStorage operations
|
||||
- Integrate with existing form system for automatic save/restore
|
||||
- Add change tracking and storage management
|
||||
|
||||
### 🎯 **Priority 2: Server Application**
|
||||
**Goal**: Backend API for real content storage
|
||||
- Design REST API for content CRUD operations
|
||||
- Add authentication integration (OAuth/JWT)
|
||||
- Consider database choice (SQLite for simplicity vs PostgreSQL for production)
|
||||
### **🏗️ 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
|
||||
|
||||
---
|
||||
|
||||
## 🏁 **Ready to Build**
|
||||
## 🚀 **Priority Roadmap**
|
||||
|
||||
The analysis is complete. The architecture is sound and 90% implemented.
|
||||
### **🔴 Phase 1: Editor Integration Polish** (High Priority)
|
||||
|
||||
**Next Action**: Create the HTTP server application that implements the API contract both clients expect.
|
||||
#### **Frontend-Backend Integration**
|
||||
- [ ] **Editor-API Connection**: Wire up StyleAware editor saves to actual 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
|
||||
|
||||
This will immediately unlock:
|
||||
- ✅ Real content persistence (not just LocalStorage)
|
||||
- ✅ Multi-user editing capabilities
|
||||
- ✅ Production-ready content management
|
||||
- ✅ Full integration between browser editor and CLI enhancement
|
||||
#### **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
|
||||
|
||||
*Let's build the missing server!*
|
||||
### **🟡 Phase 2: Production Deployment** (Medium Priority)
|
||||
|
||||
## 🏗️ **Database Schema Architecture Decision** (Sept 2025)
|
||||
#### **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
|
||||
|
||||
**Issue**: Inlined SQLite schema in `database.go` creates multiple sources of truth, same problem we just solved with model duplication.
|
||||
#### **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
|
||||
|
||||
### **Recommended Solutions** (in order of preference):
|
||||
### **🟢 Phase 3: Advanced CMS Features** (Low Priority)
|
||||
|
||||
#### **🎯 Option 1: Schema-as-Query Pattern** ⭐ **RECOMMENDED**
|
||||
```
|
||||
db/queries/
|
||||
├── content.sql # CRUD queries
|
||||
├── versions.sql # Version control queries
|
||||
├── schema_setup.sql # Schema initialization as named query
|
||||
└── indexes_setup.sql # Index creation as named query
|
||||
#### **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"
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Single source of truth (schema files)
|
||||
- ✅ sqlc generates type-safe setup functions
|
||||
- ✅ Consistent with existing sqlc workflow
|
||||
- ✅ Database-agnostic parameter syntax (`sqlc.arg()`)
|
||||
#### **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
|
||||
|
||||
**Implementation**:
|
||||
```sql
|
||||
-- name: InitializeSchema :exec
|
||||
CREATE TABLE IF NOT EXISTS content (...);
|
||||
CREATE TABLE IF NOT EXISTS content_versions (...);
|
||||
**Priority**: Low - implement after core content management features are stable
|
||||
|
||||
-- name: CreateIndexes :exec
|
||||
CREATE INDEX IF NOT EXISTS idx_content_site_id ON content(site_id);
|
||||
```
|
||||
### **Advanced Style Preview System**
|
||||
|
||||
#### **🔧 Option 2: Migration Tool Integration**
|
||||
- Use `goose`, `golang-migrate`, or `dbmate`
|
||||
- sqlc natively supports parsing migration directories
|
||||
- Professional database management with up/down migrations
|
||||
- **Trade-off**: Additional dependency and complexity
|
||||
**Current State**: Basic style button previews using `getComputedStyle()` to show formatting effects.
|
||||
|
||||
#### **🗂️ Option 3: Embedded Schema Files**
|
||||
- Use `go:embed` to read schema files at compile time
|
||||
- Keep schema in separate `.sql` files
|
||||
- **Trade-off**: Not processed by sqlc, less type safety
|
||||
#### **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
|
||||
|
||||
**✅ COMPLETED**: Implemented Option 1 (Schema-as-Query) with important discovery:
|
||||
### **Advanced Access Control**
|
||||
|
||||
**sqlc Limitations Discovered**:
|
||||
- ✅ sqlc generates functions for `CREATE TABLE` and `ALTER TABLE` statements
|
||||
- ❌ sqlc does **NOT** generate functions for `CREATE INDEX` or `CREATE TRIGGER` statements
|
||||
- 🔧 **Solution**: Handle table creation via sqlc-generated functions, handle indexes/triggers manually in Go initialization code
|
||||
**Current State**: Simple boolean authentication gate for page-level editing access.
|
||||
|
||||
**Final Implementation**:
|
||||
- `db/*/setup.sql` - Contains table creation queries (sqlc generates type-safe functions)
|
||||
- `internal/db/database.go` - Manual index/trigger creation using raw SQL
|
||||
- **Best Practice**: Use sqlc for what it supports, manual SQL for what it doesn't
|
||||
|
||||
## 🔄 **Editor Cache Architecture & Content State Management** (Dec 2024)
|
||||
|
||||
### **Current Architecture Issues Identified**
|
||||
|
||||
**Problem**: Conflict between preview system and content persistence after save operations.
|
||||
|
||||
**Root Cause**: The unified Editor system was designed with preview-first architecture:
|
||||
- `originalContent` stores DOM state when editing begins
|
||||
- `clearPreview()` always restores to `originalContent`
|
||||
- This creates race condition: `applyContent()` → `clearPreview()` → content reverted
|
||||
|
||||
### **✅ Implemented Solution: Post-Save Baseline Update**
|
||||
|
||||
**Strategy**: After successful save, update the stored `originalContent` to match the new saved state.
|
||||
|
||||
**Implementation** (`lib/src/ui/Editor.js`):
|
||||
```js
|
||||
// In save handler:
|
||||
context.applyContent(content); // Apply new content to DOM
|
||||
context.updateOriginalContent(); // Update baseline to match current DOM
|
||||
this.previewer.clearPreview(); // Clear preview (won't revert since baseline matches)
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Content persists after save operations
|
||||
- ✅ Future cancellations restore to saved state, not pre-edit state
|
||||
- ✅ Maintains clean preview functionality
|
||||
- ✅ No breaking changes to existing architecture
|
||||
|
||||
### **Future Considerations: Draft System Architecture**
|
||||
|
||||
**Current State Management**:
|
||||
- **Browser Cache**: DOM elements store current content state
|
||||
- **Server Cache**: Database stores persisted content
|
||||
- **No Intermediate Cache**: Edits are either preview (temporary) or saved (permanent)
|
||||
|
||||
**Potential Draft System Design**:
|
||||
|
||||
#### **Option 1: LocalStorage Drafts**
|
||||
```js
|
||||
// Auto-save drafts locally during editing
|
||||
const draftKey = `insertr_draft_${contentId}_${siteId}`;
|
||||
localStorage.setItem(draftKey, JSON.stringify({
|
||||
content: currentContent,
|
||||
timestamp: Date.now(),
|
||||
originalContent: baseline
|
||||
}));
|
||||
```
|
||||
|
||||
**Benefits**: Offline support, immediate feedback, no server load
|
||||
**Drawbacks**: Per-browser, no cross-device sync, storage limits
|
||||
|
||||
#### **Option 2: Server-Side Drafts**
|
||||
```js
|
||||
// Auto-save drafts to server with special draft flag
|
||||
PUT /api/content/{id}/draft
|
||||
{
|
||||
"value": "Draft content...",
|
||||
"type": "markdown",
|
||||
"is_draft": true
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits**: Cross-device sync, unlimited storage, collaborative editing potential
|
||||
**Drawbacks**: Server complexity, authentication requirements, network dependency
|
||||
|
||||
#### **Option 3: Hybrid Draft System**
|
||||
- **LocalStorage**: Immediate draft saving during typing
|
||||
- **Server Sync**: Periodic sync of drafts (every 30s or on significant changes)
|
||||
- **Conflict Resolution**: Handle cases where server content changed while editing draft
|
||||
|
||||
### **Cache Invalidation Strategy**
|
||||
|
||||
**Current Behavior**:
|
||||
- Content is cached in DOM until page reload
|
||||
- No automatic refresh when content changes on server
|
||||
- No awareness of multi-user editing scenarios
|
||||
|
||||
**Recommended Enhancements**:
|
||||
|
||||
#### **Option A: Manual Refresh Strategy**
|
||||
- Add "Refresh Content" button to editor interface
|
||||
- Check server content before editing (warn if changed)
|
||||
- Simple conflict resolution (server wins vs local wins vs merge)
|
||||
|
||||
#### **Option B: Polling Strategy**
|
||||
- Poll server every N minutes for content changes
|
||||
- Show notification if content was updated by others
|
||||
- Allow user to choose: keep editing, reload, or merge
|
||||
|
||||
#### **Option C: WebSocket Strategy**
|
||||
- Real-time content change notifications
|
||||
- Live collaborative editing indicators
|
||||
- Automatic conflict resolution
|
||||
|
||||
### **Implementation Priority**
|
||||
|
||||
**Phase 1** (Immediate): ✅ **COMPLETED**
|
||||
- Fix content persistence after save (baseline update approach)
|
||||
|
||||
**Phase 2** (Short-term):
|
||||
- Add LocalStorage draft auto-save during editing
|
||||
- Implement draft recovery on page reload
|
||||
- Basic conflict detection (server timestamp vs local timestamp)
|
||||
|
||||
**Phase 3** (Long-term):
|
||||
- Server-side draft support
|
||||
- Real-time collaboration features
|
||||
- Advanced conflict resolution
|
||||
|
||||
### **Design Principles for Draft System**
|
||||
|
||||
1. **Progressive Enhancement**: Site works without drafts, drafts enhance UX
|
||||
2. **Data Safety**: Never lose user content, even in edge cases
|
||||
3. **Performance First**: Drafts shouldn't impact site loading for regular visitors
|
||||
4. **Conflict Transparency**: Always show user what's happening with their content
|
||||
5. **Graceful Degradation**: Fallback to basic editing if draft system fails
|
||||
|
||||
**Note**: Current architecture already supports foundation for all these enhancements through the unified Editor system and API client pattern.
|
||||
|
||||
## 🏗️ **Server-Hosted Static Sites Implementation** (Sept 2025)
|
||||
|
||||
### **✅ COMPLETED: Unified Binary HTTP Server**
|
||||
The HTTP server has been successfully implemented and is production-ready:
|
||||
- ✅ **Full REST API** - All content CRUD operations (`internal/api/handlers.go`)
|
||||
- ✅ **Multi-Database Support** - SQLite + PostgreSQL with sqlc-generated queries
|
||||
- ✅ **Authentication System** - JWT + mock tokens, ready for authentik integration
|
||||
- ✅ **Bulk Operations** - Efficient bulk content retrieval (`injector.go:56-96`)
|
||||
- ✅ **Content Enhancement** - Build-time content injection from database
|
||||
|
||||
### **🎯 NEW PRIORITY: Server-Hosted File Enhancement**
|
||||
|
||||
**Goal**: Enable real-time content updates for server-hosted static sites through database-driven file enhancement.
|
||||
|
||||
**Architecture**: Database as source of truth → Content changes → File updates → Immediate deployment
|
||||
|
||||
### **Phase 1: Core File Enhancement System**
|
||||
- [ ] **Extend enhancer.go** - Add `EnhanceInPlace()` method for in-place file modification
|
||||
- [ ] **Site Manager** - Create registration system for static site paths
|
||||
- [ ] **Handler Integration** - Hook file enhancement into `UpdateContent()` API calls
|
||||
- [ ] **Configuration Extension** - Add sites configuration to `insertr.yaml`
|
||||
|
||||
**Files to modify**:
|
||||
- `internal/content/enhancer.go` - Add in-place enhancement methods
|
||||
- `internal/api/handlers.go:225` - Integrate file enhancement trigger
|
||||
- `insertr.yaml` - Add sites configuration section
|
||||
- `cmd/serve.go` - Initialize site manager in server
|
||||
|
||||
### **Phase 2: Multi-Site Server Management**
|
||||
- [ ] **CLI Site Commands** - `insertr sites register/list/enhance`
|
||||
- [ ] **File Backup System** - Backup original files before enhancement
|
||||
- [ ] **Error Handling** - Graceful file permission and disk space handling
|
||||
- [ ] **Performance Optimization** - Selective file updates, change detection
|
||||
|
||||
### **Phase 3: Production Features**
|
||||
- [ ] **Authentik Integration** - OIDC authentication for production deployment
|
||||
- [ ] **Caddy Integration** - Reverse proxy configuration templates
|
||||
- [ ] **Monitoring & Logging** - Track enhancement operations and errors
|
||||
- [ ] **Multi-Environment** - Development vs production configuration
|
||||
|
||||
### **Implementation Approach: Leverage Existing Architecture**
|
||||
|
||||
**Reuse Existing Components**:
|
||||
- ✅ **Bulk Injection** - `injector.go:56-96` already handles efficient content injection
|
||||
- ✅ **Multi-Site Support** - `siteID` parameter used throughout API and database
|
||||
- ✅ **Authentication** - `auth.go:47-67` supports JWT tokens ready for authentik
|
||||
- ✅ **Content Client Interface** - `types.go:18-28` extensible for new features
|
||||
|
||||
**New Components** (minimal additions):
|
||||
- **Site Manager** - Register static site paths and manage file enhancement
|
||||
- **In-Place Enhancer** - Extend existing enhancer for file modification
|
||||
- **Configuration** - Extend YAML config for site registration
|
||||
|
||||
### **Target Deployment Architecture**
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Caddy Reverse Proxy │
|
||||
├─────────────────┬───────────────────┤
|
||||
│ Static Sites │ Insertr Server │
|
||||
│ /site1/* ────→ │ :8080/api/* │
|
||||
│ /site2/* ────→ │ Authentication │
|
||||
│ /admin/* ────→ │ File Enhancement │
|
||||
└─────────────────┴───────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────┐ ┌─────────────────┐
|
||||
│Static Files │ │ Database + │
|
||||
│/var/www/ │◄───┤ Enhancement │
|
||||
│ site1/ │ │ Engine │
|
||||
│ site2/ │ └─────────────────┘
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
**Content Update Workflow**:
|
||||
1. Editor makes content change → API call to `/api/content/{id}`
|
||||
2. Content saved to database (source of truth)
|
||||
3. File enhancement triggered → Static files updated in-place
|
||||
4. Changes immediately visible to visitors (served by Caddy)
|
||||
|
||||
### **Future CI/CD Integration Features** (Post-Server Implementation)
|
||||
|
||||
#### **External Build Trigger System**
|
||||
- **Webhook Integration**: Trigger external CI/CD pipelines when content changes
|
||||
- **GitHub Actions Templates**: Pre-built workflows for Hugo, Next.js, Jekyll + Insertr
|
||||
- **Platform Integrations**: Native Netlify, Vercel, CloudFlare Pages integration
|
||||
- **Build Status Tracking**: Monitor external build progress and deployment status
|
||||
|
||||
#### **Hybrid Deployment Models**
|
||||
- **File + Pipeline Mode**: Server-hosted sites with optional CI/CD rebuilds
|
||||
- **Content API Mode**: Headless CMS for external static site generators
|
||||
- **Multi-Environment**: Staging/production deployment coordination
|
||||
- **Build Caching**: Intelligent rebuilds based on content vs template changes
|
||||
|
||||
#### **Advanced Content Workflows**
|
||||
- **Scheduled Publishing**: Time-based content activation
|
||||
- **Content Approval**: Multi-user approval workflows before deployment
|
||||
- **A/B Testing**: Content variations for different user segments
|
||||
- **Rollback Integration**: Coordinate content rollbacks with deployment rollbacks
|
||||
|
||||
### **Draft System Foundation** (Ready for Extension)
|
||||
|
||||
**Current Architecture Supports**:
|
||||
- ✅ **Bulk Operations** - `injector.go:56-96` efficient for batch content updates
|
||||
- ✅ **Version Control** - Full version history with rollback capabilities
|
||||
- ✅ **Content Types** - Extensible type system ready for draft fields
|
||||
|
||||
**Future Draft Features**:
|
||||
- **Server-Side Drafts** - Extend `ContentItem` with `is_draft` field
|
||||
- **Batch Publishing** - Publish multiple draft items simultaneously
|
||||
- **Preview Mode** - View sites with draft content before publishing
|
||||
- **Auto-Save Drafts** - Background saving during editing sessions
|
||||
|
||||
### **Benefits of Server-Hosted Approach**
|
||||
|
||||
1. **✅ Immediate Deployment** - Content changes are live instantly
|
||||
2. **✅ Database Source of Truth** - No git-based workflow complexity
|
||||
3. **✅ Content-Only Updates** - No template rebuilds required
|
||||
4. **✅ Existing Infrastructure** - Leverages Caddy + authentik setup
|
||||
5. **✅ Performance** - Static file serving with dynamic content injection
|
||||
6. **✅ Multi-Site** - Single server manages multiple enhanced sites
|
||||
7. **✅ Zero Downtime** - Updates don't require site rebuilds or deploys
|
||||
|
||||
## 🎯 **Future Class Extensions: Advanced Access Control** (Planned)
|
||||
|
||||
### **Granular Permission System for `.insertr-gate`**
|
||||
|
||||
**Current Implementation**: Simple boolean authentication gate for page-level editing access.
|
||||
|
||||
**Future Enhancement Concept**: Role-based access control and section-level permissions for enterprise applications.
|
||||
**Future Enhancement**: Role-based access control and section-level permissions for enterprise applications.
|
||||
|
||||
#### **Potential Extended Gate Classes**
|
||||
```html
|
||||
@@ -506,10 +143,6 @@ The HTTP server has been successfully implemented and is production-ready:
|
||||
<div class="editor-section insertr-gate-editor">
|
||||
<div class="insertr-content">Editor-level rich content</div>
|
||||
</div>
|
||||
|
||||
<div class="premium-content insertr-gate-premium" data-auth-level="subscription">
|
||||
<div class="insertr">Premium subscriber content</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
#### **Enterprise Use Cases**
|
||||
@@ -517,143 +150,40 @@ The HTTP server has been successfully implemented and is production-ready:
|
||||
- **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
|
||||
- **Geographic Restrictions**: Region-specific editing permissions
|
||||
|
||||
#### **Implementation Considerations**
|
||||
- **Configuration Complexity**: How to maintain zero-config philosophy while supporting complex permissions
|
||||
- **Role Definition**: Where and how to define roles and permissions
|
||||
- **Authentication Integration**: Extending current auth system vs external RBAC systems
|
||||
- **Fallback Behavior**: Graceful degradation for unauthorized users
|
||||
- **Performance Impact**: Permission checks shouldn't slow down regular site visitors
|
||||
|
||||
#### **Integration Points**
|
||||
- **Authentik OIDC**: Leverage existing auth provider for role information
|
||||
- **Database Schema**: Extend current content system with permission metadata
|
||||
- **API Endpoints**: New endpoints for permission management and validation
|
||||
- **Editor Interface**: Dynamic interface based on user permissions
|
||||
|
||||
**Priority**: Low - implement after core functionality is stable and enterprise customers request advanced permissions.
|
||||
|
||||
**Design Principle**: Keep simple `.insertr-gate` as default, add optional complexity only when needed.
|
||||
---
|
||||
|
||||
## 🎨 **Style Preview Enhancement System** (Dec 2024)
|
||||
## 📊 **Success Metrics**
|
||||
|
||||
### **✅ IMPLEMENTED: Basic Style Button Previews**
|
||||
### **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
|
||||
|
||||
**Goal**: Make formatting buttons visually preview the styles they represent.
|
||||
### **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
|
||||
|
||||
**Current Implementation**:
|
||||
- ✅ **Dynamic Style Copying** - JavaScript reads computed styles from original elements
|
||||
- ✅ **Selective Property Application** - Copies color, font-weight, text-decoration, text-transform
|
||||
- ✅ **Button Structure Preservation** - Maintains clickable button appearance with backgrounds/borders
|
||||
- ✅ **Cross-Platform Compatibility** - Uses `window.getComputedStyle()` for universal support
|
||||
### **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
|
||||
|
||||
**Example Results**:
|
||||
- "Emphasis" button displays with red bold text (from `.emph { color: #dc2626; font-weight: 700; }`)
|
||||
- "Highlight" button shows preview styling while remaining clickable
|
||||
- "Brand" button demonstrates text-transform and color changes
|
||||
---
|
||||
|
||||
### **🔄 Future Style Preview Enhancements**
|
||||
## 🔧 **Development Principles**
|
||||
|
||||
#### **🎯 Priority 1: Enhanced Style Support**
|
||||
- [ ] **Background Colors** - Safe background preview with contrast protection
|
||||
- [ ] **Border Styles** - Preview border styles while maintaining button structure
|
||||
- [ ] **Typography Styles** - Font-family, font-size adjustments with readability limits
|
||||
- [ ] **Advanced CSS Properties** - Text-shadow, letter-spacing, line-height previews
|
||||
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
|
||||
|
||||
#### **🎯 Priority 2: Interactive Previews**
|
||||
- [ ] **Hover State Previews** - Show hover effects in button previews
|
||||
- [ ] **Animation Previews** - Preview CSS transitions and animations safely
|
||||
- [ ] **Responsive Previews** - Show how styles adapt across screen sizes
|
||||
- [ ] **Nested Style Previews** - Handle complex nested styling scenarios
|
||||
|
||||
#### **🎯 Priority 3: Advanced Preview Features**
|
||||
- [ ] **Custom Style Creation** - Visual style picker with live preview
|
||||
- [ ] **Style Inheritance Display** - Show which properties come from which classes
|
||||
- [ ] **Accessibility Validation** - Ensure previews meet contrast and readability standards
|
||||
- [ ] **Performance Optimization** - Cache computed styles, minimize recomputation
|
||||
|
||||
### **🔧 Technical Implementation Details**
|
||||
|
||||
**Current Approach** (JavaScript-based style copying):
|
||||
```javascript
|
||||
const computedStyle = window.getComputedStyle(styleInfo.element);
|
||||
if (computedStyle.color && computedStyle.color !== 'rgb(0, 0, 0)') {
|
||||
button.style.setProperty('color', computedStyle.color, 'important');
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Works with any CSS framework or custom styles
|
||||
- ✅ No hardcoded style mappings required
|
||||
- ✅ Automatically adapts to theme changes
|
||||
- ✅ Handles complex CSS specificity scenarios
|
||||
|
||||
**Limitations**:
|
||||
- ⚠️ Limited to properties safe for button elements
|
||||
- ⚠️ Background colors skipped to maintain readability
|
||||
- ⚠️ Some complex styles may not preview accurately
|
||||
- ⚠️ Performance impact on large style sets
|
||||
|
||||
### **🎨 Design Considerations**
|
||||
|
||||
**Readability vs Accuracy Trade-offs**:
|
||||
- **Button Backgrounds**: Always use safe background to ensure clickability
|
||||
- **Text Contrast**: Ensure sufficient contrast between text and button background
|
||||
- **Property Selection**: Only preview properties that don't break button functionality
|
||||
- **Fallback Handling**: Graceful degradation when style copying fails
|
||||
|
||||
**User Experience Principles**:
|
||||
- **Immediate Recognition**: Users should instantly understand what each button does
|
||||
- **Consistent Interaction**: Buttons should always feel clickable regardless of style
|
||||
- **Visual Hierarchy**: Style previews shouldn't overpower the editor interface
|
||||
- **Accessibility**: Maintain WCAG compliance for all preview combinations
|
||||
|
||||
### **🧪 Testing Strategy for Style Previews**
|
||||
|
||||
**Cross-Browser Compatibility**:
|
||||
- Test `getComputedStyle()` behavior across major browsers
|
||||
- Validate CSS custom property support and inheritance
|
||||
- Check for inconsistencies in color space handling
|
||||
|
||||
**Edge Case Handling**:
|
||||
- Very long class names or deeply nested selectors
|
||||
- Conflicting CSS properties from multiple stylesheets
|
||||
- High contrast or accessibility mode compatibility
|
||||
- Performance with large numbers of detected styles
|
||||
|
||||
**Real-World Style Testing**:
|
||||
- Test with popular CSS frameworks (Tailwind, Bootstrap, Bulma)
|
||||
- Validate with complex design systems and component libraries
|
||||
- Check compatibility with CSS-in-JS solutions
|
||||
- Test with user-defined custom properties and themes
|
||||
|
||||
### **📊 Future Metrics and Analytics**
|
||||
|
||||
**Style Preview Usage Analytics**:
|
||||
- Track which style previews are most commonly used
|
||||
- Measure user engagement with preview vs non-preview buttons
|
||||
- Identify styles that cause preview rendering issues
|
||||
- Monitor performance impact of style computation
|
||||
|
||||
**User Experience Improvements**:
|
||||
- A/B test preview accuracy vs simplified representations
|
||||
- Test user comprehension of style previews vs text labels
|
||||
- Measure editing efficiency with vs without previews
|
||||
- Gather feedback on preview helpfulness for different user types
|
||||
|
||||
### **Integration with Future Features**
|
||||
|
||||
**Style Management System**:
|
||||
- Style preview integration with custom style creation tools
|
||||
- Preview integration with theme switching and dark mode
|
||||
- Connection to style documentation and design system integration
|
||||
- Preview role in collaborative editing and style consistency
|
||||
|
||||
**Performance Optimization**:
|
||||
- Style preview caching for frequently used styles
|
||||
- Lazy loading of preview computation for off-screen elements
|
||||
- Optimization for mobile devices and slower browsers
|
||||
- Integration with build-time style optimization
|
||||
|
||||
**Note**: Current implementation provides solid foundation for all future enhancements while maintaining the zero-configuration philosophy.
|
||||
**Built with ❤️ for developers who want powerful editing without the complexity**
|
||||
Reference in New Issue
Block a user