feat: add Windows distribution build with cross-platform server scripts

- Add 'make dist' target to build distribution package in dist/ - Add 'make dist-zip' target to create distributable archive (ZIP or tar.gz) - Create start-server.bat for Windows users (auto-opens browser, starts Python server) - Create start-server.sh for Linux/Mac users with same functionality - Generate DIST_README.md with quick start instructions for all platforms - Add WINDOWS_USAGE.md with comprehensive guide for WSL → Windows deployment - Update .gitignore to exclude dist/ and distribution archives - Update CLAUDE.md with distribution build documentation Distribution package includes: - Core application files (index.html, engine.js, generator.js) - All example projects (example/, example-1/, my-project/) - Documentation (README.md, TEMPLATE_V2_GUIDE.md, TROUBLESHOOTING.md) - Cross-platform server startup scripts The distribution is self-contained and works on Windows filesystems without modification. Paths use forward slashes which browsers handle correctly on all platforms. Users can simply extract and double-click start-server.bat (Windows) or run ./start-server.sh (Linux/Mac) to launch the application. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-23 16:13:16 +01:00
parent 4e92665358
commit 39037587ba
4 changed files with 371 additions and 2 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -180,3 +180,7 @@ node_modules/

 # npm package lock file
 package-lock.json
+
+# Distribution archives
+timeline-svg-dist.zip
+timeline-svg-dist.tar.gz
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -41,6 +41,22 @@ python3 -m http.server 8000

 The application must be served via HTTP (not opened as file://) due to CORS restrictions when loading CSV, CSS, and SVG files.

+### Distribution
+```bash
+make dist                # Build distribution package in dist/
+make dist-zip            # Build distribution and create archive
+```
+
+The distribution package includes:
+- All runtime files (HTML, JS, CSS)
+- Example projects (example/, example-1/, my-project/)
+- Documentation (README.md, TEMPLATE_V2_GUIDE.md, TROUBLESHOOTING.md)
+- Startup scripts for Windows (start-server.bat) and Linux/Mac (start-server.sh)
+
+Use this to deploy the application to Windows or other environments. The distribution is self-contained and requires only a web browser and Python (for the local server).
+
+**For Windows deployment from WSL**: See `WINDOWS_USAGE.md` for detailed instructions on building the distribution in WSL, transferring to Windows, and running the application on Windows OS.
+
 ## Architecture

 ### Core Components
--- a/138
+++ b/138
@@ -1,4 +1,4 @@
-.PHONY: help install test test-watch test-coverage test-ui clean serve lint format deps-check deps-update
+.PHONY: help install test test-watch test-coverage test-ui clean serve lint format deps-check deps-update dist dist-zip

 # Default target
 help:
@@ -25,6 +25,10 @@ help:
 	@echo "  deps-update   Update dependencies"
 	@echo "  deps-audit    Security audit of dependencies"
 	@echo ""
+	@echo "Distribution:"
+	@echo "  dist          Build distribution package in dist/"
+	@echo "  dist-zip      Build distribution and create ZIP archive"
+	@echo ""

 # Development setup
 install:
@@ -138,3 +142,135 @@ setup: clean install test
 	@echo "   • Run 'make test-watch' for TDD"
 	@echo "   • Run 'make serve' to start development server"
 	@echo "   • Open index.html in browser to use the app"
+
+# Distribution build for deployment/Windows
+dist:
+	@echo "Building distribution package..."
+	@# Create dist directory
+	@rm -rf dist
+	@mkdir -p dist
+	@echo "📦 Created dist/ directory"
+
+	@# Copy core application files
+	@cp index.html engine.js generator.js dist/
+	@echo "✅ Copied core files (index.html, engine.js, generator.js)"
+
+	@# Copy project directories
+	@cp -r example example-1 my-project dist/
+	@echo "✅ Copied project directories (example, example-1, my-project)"
+
+	@# Copy documentation
+	@cp README.md LICENSE dist/
+	@[ -f TEMPLATE_V2_GUIDE.md ] && cp TEMPLATE_V2_GUIDE.md dist/ || true
+	@[ -f TROUBLESHOOTING.md ] && cp TROUBLESHOOTING.md dist/ || true
+	@echo "✅ Copied documentation"
+
+	@# Create Windows batch file for serving
+	@echo '@echo off' > dist/start-server.bat
+	@echo 'echo Starting Timeline SVG Generator...' >> dist/start-server.bat
+	@echo 'echo.' >> dist/start-server.bat
+	@echo 'echo Opening browser at http://localhost:8000' >> dist/start-server.bat
+	@echo 'echo Press Ctrl+C to stop the server' >> dist/start-server.bat
+	@echo 'echo.' >> dist/start-server.bat
+	@echo 'start http://localhost:8000' >> dist/start-server.bat
+	@echo 'python -m http.server 8000 2^>nul || python3 -m http.server 8000 2^>nul || (echo Python not found. Please install Python or open index.html in a browser. ^& pause)' >> dist/start-server.bat
+	@echo "✅ Created start-server.bat for Windows"
+
+	@# Create Linux/Mac shell script for serving
+	@echo '#!/bin/bash' > dist/start-server.sh
+	@echo 'echo "Starting Timeline SVG Generator..."' >> dist/start-server.sh
+	@echo 'echo ""' >> dist/start-server.sh
+	@echo 'echo "Opening browser at http://localhost:8000"' >> dist/start-server.sh
+	@echo 'echo "Press Ctrl+C to stop the server"' >> dist/start-server.sh
+	@echo 'echo ""' >> dist/start-server.sh
+	@echo 'if command -v xdg-open >/dev/null 2>&1; then' >> dist/start-server.sh
+	@echo '  xdg-open http://localhost:8000 &' >> dist/start-server.sh
+	@echo 'elif command -v open >/dev/null 2>&1; then' >> dist/start-server.sh
+	@echo '  open http://localhost:8000 &' >> dist/start-server.sh
+	@echo 'fi' >> dist/start-server.sh
+	@echo 'python3 -m http.server 8000 2>/dev/null || python -m SimpleHTTPServer 8000 2>/dev/null || { echo "Python not found. Please install Python or open index.html in a browser."; read -p "Press Enter to exit..."; }' >> dist/start-server.sh
+	@chmod +x dist/start-server.sh
+	@echo "✅ Created start-server.sh for Linux/Mac"
+
+	@# Create distribution README
+	@echo "# Timeline SVG Generator - Distribution Package" > dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "This is a standalone distribution of Timeline SVG Generator." >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "## Quick Start" >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "### Windows" >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "1. Double-click \`start-server.bat\`" >> dist/DIST_README.md
+	@echo "2. Your browser will open automatically at http://localhost:8000" >> dist/DIST_README.md
+	@echo "3. The application will load the example project automatically" >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "### Linux / Mac" >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "1. Run \`./start-server.sh\` (or \`bash start-server.sh\`)" >> dist/DIST_README.md
+	@echo "2. Your browser will open automatically at http://localhost:8000" >> dist/DIST_README.md
+	@echo "3. The application will load the example project automatically" >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "### Alternative: Open Directly" >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "**Note:** Due to browser security restrictions (CORS), opening index.html directly may prevent loading of project files. Using a local server is recommended." >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "## Project Structure" >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "- \`index.html\` - Main application" >> dist/DIST_README.md
+	@echo "- \`engine.js\` - Application logic" >> dist/DIST_README.md
+	@echo "- \`generator.js\` - SVG generation engine" >> dist/DIST_README.md
+	@echo "- \`example/\` - Simple example project" >> dist/DIST_README.md
+	@echo "- \`example-1/\` - Enhanced example with styling" >> dist/DIST_README.md
+	@echo "- \`my-project/\` - Template for your own projects" >> dist/DIST_README.md
+	@echo "- \`README.md\` - Full documentation" >> dist/DIST_README.md
+	@echo "- \`TEMPLATE_V2_GUIDE.md\` - Template creation guide" >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "## Creating Your Own Timeline" >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "1. Copy one of the example folders (e.g., \`example/\`)" >> dist/DIST_README.md
+	@echo "2. Rename it to your project name" >> dist/DIST_README.md
+	@echo "3. Edit \`project.json\` to configure your timeline" >> dist/DIST_README.md
+	@echo "4. Replace \`sample.csv\` with your data" >> dist/DIST_README.md
+	@echo "5. Customize \`style.css\` and \`template-v2.svg\` as needed" >> dist/DIST_README.md
+	@echo "6. Load your project in the application using the file upload controls" >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "See README.md and TEMPLATE_V2_GUIDE.md for detailed instructions." >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "## Troubleshooting" >> dist/DIST_README.md
+	@echo "" >> dist/DIST_README.md
+	@echo "If you encounter issues, see TROUBLESHOOTING.md for solutions to common problems." >> dist/DIST_README.md
+	@echo "✅ Created DIST_README.md"
+
+	@echo ""
+	@echo "🎉 Distribution package created in dist/"
+	@echo ""
+	@echo "Contents:"
+	@echo "  • Core application files (HTML, JS)"
+	@echo "  • Example projects (example, example-1, my-project)"
+	@echo "  • Documentation (README.md, TEMPLATE_V2_GUIDE.md, etc.)"
+	@echo "  • Server startup scripts (start-server.bat, start-server.sh)"
+	@echo ""
+	@echo "To use on Windows:"
+	@echo "  1. Copy the dist/ folder to your Windows machine"
+	@echo "  2. Double-click start-server.bat to run"
+	@echo ""
+	@echo "Or create a ZIP archive with: make dist-zip"
+
+# Create ZIP archive of distribution
+dist-zip: dist
+	@echo "Creating distribution archive..."
+	@if command -v zip >/dev/null 2>&1; then \
+		cd dist && zip -r ../timeline-svg-dist.zip . -x "*.git*" -x "*.DS_Store" && cd ..; \
+		echo "✅ Created timeline-svg-dist.zip"; \
+		echo ""; \
+		echo "📦 Distribution archive ready: timeline-svg-dist.zip"; \
+		echo "   Transfer this file to Windows and extract to use the application."; \
+	else \
+		tar --exclude=".git*" --exclude=".DS_Store" -czf timeline-svg-dist.tar.gz -C dist .; \
+		echo "✅ Created timeline-svg-dist.tar.gz (zip not available)"; \
+		echo ""; \
+		echo "📦 Distribution archive ready: timeline-svg-dist.tar.gz"; \
+		echo "   Transfer this file to Windows, extract with 7-Zip or similar tool."; \
+		echo "   Or install zip: sudo apt-get install zip"; \
+	fi
--- a/WINDOWS_USAGE.md
+++ b/WINDOWS_USAGE.md
@@ -0,0 +1,213 @@
+# Using Timeline SVG on Windows
+
+This guide explains how to use Timeline SVG Generator on Windows after building the distribution in WSL.
+
+## Building the Distribution (in WSL)
+
+1. In your WSL terminal, navigate to the project directory:
+   ```bash
+   cd /home/worsch/timeline-svg
+   ```
+
+2. Build the distribution package:
+   ```bash
+   make dist-zip
+   ```
+
+   This creates either `timeline-svg-dist.zip` (if zip is installed) or `timeline-svg-dist.tar.gz`.
+
+3. The distribution file is now in your project directory and accessible from Windows at:
+   ```
+   \\wsl$\Ubuntu\home\worsch\timeline-svg\timeline-svg-dist.tar.gz
+   ```
+
+   Or if you have the WSL path mounted:
+   ```
+   \\wsl.localhost\Ubuntu\home\worsch\timeline-svg\timeline-svg-dist.tar.gz
+   ```
+
+## Transferring to Windows
+
+### Option 1: Copy from WSL Location
+
+1. Open Windows Explorer
+2. Navigate to `\\wsl$\Ubuntu\home\worsch\timeline-svg\`
+3. Copy `timeline-svg-dist.tar.gz` (or `.zip`) to your Windows directory
+   - Example: `C:\Users\YourName\Documents\timeline-svg\`
+
+### Option 2: Use Command Line
+
+In WSL terminal:
+```bash
+# Copy to Windows user directory
+cp timeline-svg-dist.tar.gz /mnt/c/Users/YourName/Documents/
+```
+
+Or from Windows PowerShell:
+```powershell
+# Copy from WSL to Windows
+Copy-Item "\\wsl$\Ubuntu\home\worsch\timeline-svg\timeline-svg-dist.tar.gz" -Destination "C:\Users\YourName\Documents\"
+```
+
+## Extracting on Windows
+
+### If you have a .zip file:
+- Right-click the file → "Extract All..."
+- Choose destination folder
+
+### If you have a .tar.gz file:
+- Install 7-Zip (free): https://www.7-zip.org/
+- Right-click → 7-Zip → Extract Here (twice - first for .gz, then for .tar)
+
+## Running on Windows
+
+Once extracted, you have several options:
+
+### Option 1: Use the Batch Script (Easiest)
+
+1. Double-click `start-server.bat` in the extracted folder
+2. A command window will open and your browser will launch automatically
+3. The application will be available at http://localhost:8000
+4. To stop the server, close the command window or press Ctrl+C
+
+**Note:** Requires Python to be installed on Windows. Download from https://www.python.org/ if needed.
+
+### Option 2: Use Python Directly
+
+1. Open Command Prompt or PowerShell in the extracted folder
+2. Run one of these commands:
+   ```cmd
+   python -m http.server 8000
+   ```
+   or
+   ```cmd
+   python3 -m http.server 8000
+   ```
+3. Open your browser to http://localhost:8000
+
+### Option 3: Use Node.js http-server
+
+If you have Node.js installed:
+```cmd
+npx http-server -p 8000
+```
+
+### Option 4: Direct File Access (Limited)
+
+You can open `index.html` directly in your browser, but due to CORS restrictions:
+- ✅ UI will load
+- ❌ Auto-loading of example projects won't work
+- ❌ CSV/template files must be manually uploaded
+
+**Recommendation:** Use a local server (Option 1-3) for full functionality.
+
+## Working with Your Own Projects
+
+### Creating a New Project
+
+1. Copy one of the example folders (e.g., `example\`)
+2. Rename it to your project name
+3. Edit the files:
+   - `project.json` - Configure field mappings and settings
+   - `sample.csv` - Replace with your timeline data
+   - `style.css` - Customize colors and fonts
+   - `template-v2.svg` - Design your timeline layout
+
+### Loading Your Project
+
+1. Start the application (using one of the options above)
+2. Use the "Load Project" button to upload your `project.json`
+3. Or manually upload individual CSV/CSS/SVG files
+
+## File Paths on Windows
+
+The application uses forward slashes (`/`) in URLs, which work correctly in browsers on Windows. You don't need to change anything in the code.
+
+**Example project.json on Windows:**
+```json
+{
+  "name": "My Timeline",
+  "dataSource": "sample.csv",
+  "stylesheet": "style.css",
+  "svgTemplate": "template-v2.svg"
+}
+```
+
+These relative paths work the same way on Windows and Linux when served via HTTP.
+
+## Troubleshooting on Windows
+
+### "Python not found"
+
+Install Python:
+1. Download from https://www.python.org/downloads/
+2. **Important:** Check "Add Python to PATH" during installation
+3. Restart Command Prompt
+4. Try running `start-server.bat` again
+
+### Port 8000 already in use
+
+Change the port in `start-server.bat`:
+- Edit the file with Notepad
+- Change `8000` to another port like `8080` or `3000`
+- Update the browser URL accordingly
+
+### Files not loading (CORS errors)
+
+- Make sure you're using the local server (not opening index.html directly)
+- Check that all project files are in the same directory structure
+- Look at browser console (F12) for specific error messages
+
+### Browser doesn't open automatically
+
+If `start http://localhost:8000` doesn't work:
+- Manually open your browser
+- Navigate to http://localhost:8000
+- The application should load normally
+
+## Syncing Between WSL and Windows
+
+If you want to develop in WSL but test on Windows:
+
+### Option 1: Work in WSL-accessible location
+
+Develop in a Windows folder accessed from WSL:
+```bash
+cd /mnt/c/Users/YourName/Documents/timeline-svg
+```
+
+Changes made in WSL are immediately visible in Windows.
+
+### Option 2: Rebuild distribution after changes
+
+1. Make changes in WSL
+2. Rebuild: `make dist-zip`
+3. Copy to Windows
+4. Extract and test
+
+### Option 3: Use the Windows folder directly
+
+The distribution folder can be used from both environments:
+- WSL: `cd /mnt/c/Users/YourName/Documents/timeline-svg/dist`
+- Windows: `C:\Users\YourName\Documents\timeline-svg\dist`
+
+## Performance Notes
+
+- The application runs entirely in the browser (no backend needed)
+- Performance is identical on Windows and Linux
+- Large CSV files (>1000 rows) may take a few seconds to process
+- SVG generation is client-side and depends on your browser/CPU speed
+
+## Additional Resources
+
+- See `README.md` for application overview and features
+- See `TEMPLATE_V2_GUIDE.md` for template customization
+- See `TROUBLESHOOTING.md` for common issues and solutions
+
+## Questions or Issues?
+
+If you encounter problems specific to Windows:
+1. Check the browser console (F12 → Console tab) for error messages
+2. Verify Python is installed and in PATH
+3. Try the alternative server options above
+4. Check file permissions (extracted files should be readable)