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/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)