# Insertr Development Guide

## Quick Start

### Full-Stack Development (Recommended)
1. **Install dependencies**:
   ```bash
   npm install                    # Root project dependencies
   cd lib && npm install         # Library dependencies
   ```

2. **Start hot reload development**:
   ```bash
   cd insertr-cli && air         # Starts server with library hot reload
   ```
   - Watches both Go CLI changes AND JavaScript library changes
   - Automatically rebuilds library → CLI → serves enhanced content
   - Visit http://localhost:3000 to see results

### Library-Only Development
```bash
cd lib && npm run watch         # Just develop the JavaScript library
```

### Legacy Frontend Development
```bash
npm run dev                     # Legacy live-server (demo-site only)
```

## Development Workflow

### Hot Reload Development (Current Phase)

**🔥 NEW**: Full-stack hot reload with Air integration!

- **Library Source**: `lib/src/` - Independent JavaScript library
- **CLI Integration**: `insertr-cli/` - Go CLI with embedded library
- **Demo Site**: `demo-site/` - Test website for enhancement
- **Automatic Rebuilds**: Changes to JS library trigger full rebuild cycle

#### How Hot Reload Works:
1. Edit JavaScript in `lib/src/` 
2. Air detects changes → Rebuilds library → Copies to CLI → Rebuilds CLI
3. Enhanced development server serves updated content
4. Manual browser refresh shows changes

### Legacy Frontend Development

- **Demo Site**: `demo-site/` contains the prototype website
- **Core Library**: `demo-site/insertr/insertr.js` - the old prototype library  
- **Mock API**: `demo-site/mock-api/content.json` - sample backend data structure

### Testing the Three User Types

1. **Customer View**: Open the site normally - clean, no edit interface
2. **Client View**: Click "Login as Client" then "Edit Mode: On" - see edit buttons
3. **Developer View**: Look at the HTML source to see simple integration

### Making Changes

#### Modern Development (lib/ + insertr-cli/)
- **Library Changes**: Edit `lib/src/**/*.js` → Air automatically rebuilds everything
- **CLI Changes**: Edit Go files in `insertr-cli/` → Air rebuilds and restarts server  
- **Demo Content**: Edit `demo-site/*.html` → Air serves enhanced versions
- **Hot Reload**: Changes trigger full rebuild cycle (library → CLI → enhanced content)

#### Legacy Development (demo-site/)
- **Live Reload**: The server automatically refreshes when you save changes
- **JavaScript**: Edit `demo-site/insertr/insertr.js` for prototype functionality
- **Content**: Edit HTML files to test different content structures

### Adding New Features

1. **Content Types**: Extend the `createEditForm()` method in insertr.js
2. **UI Components**: Add new CSS classes and corresponding JavaScript
3. **Authentication**: Modify the mock auth system in `toggleAuthentication()`

## Project Structure

```
insertr/
├── DEVELOPMENT.md          # This file
├── LIBRARY.md             # Library architecture documentation  
├── package.json           # Root project configuration
│
├── lib/                   # 🆕 Independent JavaScript Library
│   ├── src/
│   │   ├── core/
│   │   │   ├── insertr.js    # Core library functionality
│   │   │   ├── editor.js     # Visual editing interface
│   │   │   └── api-client.js # Content API client
│   │   └── index.js          # Library entry point
│   ├── dist/
│   │   ├── insertr.js        # Built library (development)
│   │   └── insertr.min.js    # Built library (production)
│   ├── package.json          # Library dependencies
│   └── rollup.config.js      # Build configuration
│
├── insertr-cli/           # 🆕 Go CLI with Embedded Library
│   ├── pkg/content/
│   │   ├── assets/           # Embedded library files (auto-copied)
│   │   ├── library.go        # Go embed declarations  
│   │   ├── enhancer.go       # HTML enhancement orchestrator
│   │   ├── injector.go       # Content injection logic
│   │   └── ...
│   ├── scripts/
│   │   └── rebuild-library.sh # Air helper script
│   ├── .air.toml            # Hot reload configuration
│   └── insertr             # Built CLI executable
│
├── demo-site/             # Test website for enhancement
│   ├── index.html         # Demo homepage
│   ├── about.html         # Demo about page
│   └── assets/style.css   # Demo site styling
│
└── scripts/
    └── build.js           # Integrated build script
```

## Development Scripts

### Root Scripts
- `npm run build` - Build library + CLI with embedded assets
- `npm run dev` - Legacy live-server (demo-site only)

### Library Scripts (cd lib/)  
- `npm run build` - Build library to dist/
- `npm run watch` - Watch and rebuild library on changes

### CLI Scripts (cd insertr-cli/)
- `air` - 🔥 Hot reload server (library + CLI + enhanced content)
- `go build -o insertr` - Manual CLI build
- `./insertr enhance <dir>` - Enhance static site
- `./insertr servedev <dir>` - Development server with enhancement

### Hot Reload Workflow
```bash
cd insertr-cli && air    # Start hot reload development
# Edit lib/src/**/*.js   # Air detects → rebuilds → serves
# Edit cmd/**/*.go       # Air detects → rebuilds → serves  
# Edit ../demo-site/     # Air serves enhanced versions
```

## Testing Different Scenarios

### Content Types
- **Simple Text**: Logo, titles, short descriptions
- **Rich Content**: Paragraphs with markdown, lists, links
- **Mixed Content**: Cards with multiple editable sections

### User Flows
1. **First Visit**: Customer sees clean site
2. **Client Login**: Authentication state changes
3. **Edit Mode**: Toggle editing interface
4. **Content Editing**: Click edit → modify → save
5. **Multi-page**: Test persistence across pages

### Browser Testing
Test in different browsers to ensure compatibility:
- Chrome/Edge (Chromium)
- Firefox  
- Safari (if on macOS)

## Future Development Phases

### Phase 2: Backend Integration
- Go HTTP server with REST API
- Real authentication with Authentik OAuth
- File-based content persistence
- Git version control

### Phase 3: Production Features
- Multi-tenant support
- Admin dashboard
- Content validation
- Image upload
- Deployment automation

## Contributing Guidelines

1. **Make changes** in small, focused commits
2. **Test thoroughly** across different content types
3. **Update documentation** when adding new features
4. **Follow existing code style** and patterns

## Debugging Tips

### JavaScript Console
- Open browser dev tools (F12)
- Check for errors in Console tab
- Use `window.insertr` to inspect library state

### Local Storage
- View saved content: `localStorage.getItem('insertr_content')`
- Clear saved content: `localStorage.clear()`

### Network Simulation
- The library simulates network delays and occasional failures
- Check browser Network tab to see mock API calls (when implemented)

## Common Issues

### Live Server Not Working
- Ensure port 3000 is available
- Try different port: `live-server demo-site --port=3001`

### Changes Not Reflecting
- Hard refresh browser (Ctrl+F5 / Cmd+Shift+R)
- Check browser cache settings
- Verify file paths are correct

### Edit Buttons Not Showing
- Check authentication state (click "Login as Client")
- Enable edit mode (click "Edit Mode: Off" → "Edit Mode: On")
- Verify elements have `class="insertr"` and `data-content-id`