timeline-svg/WINDOWS_USAGE.md

# 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

You have two options:

#### Option 1: Load Entire Project Folder (Recommended)

1. Click **"📂 Load Project Folder"**
2. Select your project folder (e.g., `example\` or your custom project folder)
3. All files (project.json, CSV, SVG, CSS) will be loaded automatically
4. Timeline generates immediately

This is the easiest method - one click loads everything!

#### Option 2: Load Files Individually

1. Click **"📁 Load"** next to "Project Configuration"
2. Select your `project.json` file
3. Manually upload CSV, CSS, and SVG files using the respective buttons

**Note:** Due to browser security, uploading just project.json won't automatically load the other files from the same directory. Use the folder picker (Option 1) for automatic loading.

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