# comic-odin GUI User Guide

## Getting Started

### Launching
```bash
cd odin
./bin/comic_odin gui
```
The application launches in borderless fullscreen on your primary monitor.

### First Run Workflow
1. Enter a **Story Idea** (or leave default)
2. Click **Generate Script Local** (or press `F5`)
3. Click **Generate Panels Local** (or press `F6`)
4. Click **Layout Pages** (or press `F7`)
5. Navigate to **Bubbles** screen to add speech bubbles
6. Click **Export** (or press `F8`) to produce your comic

## Screens

### 1. Story
Enter your comic concept: idea, genre, and target audience. These fields seed script generation.

### 2. Script
View generated script pages. Navigate pages with `< Pg` / `Pg >` buttons or `Ctrl+[` / `Ctrl+]`.

**Script Source Toggle**: Switch between `Local` (deterministic) and `DeepSeek` (AI-generated) modes. DeepSeek requires `DEEPSEEK_API_KEY` environment variable.

### 3. Characters
Character editor is scaffolded. Characters are auto-populated from script generation.

### 4. Panels
View generated panel images and their metadata (dimensions, seed, source). Navigate with `< Pn` / `Pn >` or `Ctrl+[` / `Ctrl+]`. Use **Regenerate** to re-roll a specific panel.

### 5. Layout
View layout wireframe previews with validation badges:
- **Cov**: Page coverage percentage (green if 80-105%)
- **Bind**: Missing panel bindings (green if 0)
- **Bounds**: Cells outside valid range (green if 0)

Navigate pages with `< Ly` / `Ly >` or `Ctrl+[` / `Ctrl+]`. Use **Regen** to cycle the layout pattern.

### 6. Bubbles
Speech bubble editor. Select a panel using `< Pn` / `Pn >` or `Ctrl+[` / `Ctrl+]`, then:
- **Add**: Create a new bubble (Normal type, placeholder text)
- **Auto Place**: Generate bubbles from script dialogue automatically
- **Type selector**: Change bubble type (Normal/Thought/Shout/Whisper/Narration/SFX)
- **x button**: Delete the selected bubble

Use mouse wheel to cycle through panels on the current page.

### 7. Export
Choose format (PDF/PNG/CBZ), set the export path, and click Export. The path extension auto-matches the selected format.

### 8. Community
Placeholder for future sharing/collaboration features.

## Keyboard Shortcuts

### Navigation
| Shortcut | Action |
|----------|--------|
| `1-8` | Switch to screen |
| `Tab` | Next input field |
| `F1-F4` | Focus idea/genre/audience/export path |
| `F11` | Focus local pages |
| `F12` | Focus project path |
| `Ctrl+[` / `Ctrl+]` | Previous/next page or panel |

### Actions
| Shortcut | Action |
|----------|--------|
| `F5` | Generate Script |
| `F6` | Generate Panels |
| `F7` | Layout Auto |
| `F8` | Export |
| `F9` | Next Step |
| `F10` | Auto-All |
| `Ctrl+S` | Save project |
| `Ctrl+O` | Open project |
| `Ctrl+E` | Export |
| `Ctrl+G` | Toggle script source |

### Utilities
| Shortcut | Action |
|----------|--------|
| `/` | Toggle help overlay |
| `Esc` | Close overlays |
| `Ctrl+L` | Clear action log |
| `Ctrl+Shift+A` | Toggle autosave |
| `Ctrl+Backspace` | Clear selected field |
| `Ctrl+V` | Paste into selected field |

### Destructive Actions (require Shift when dirty)
| Shortcut | Action |
|----------|--------|
| `Ctrl+N` | Reset project |
| `Ctrl+Shift+N` | Force reset (when dirty) |
| `Ctrl+Shift+O` | Force open (when dirty) |

## Autosave

Autosave is enabled by default with a 20-second interval. Adjust via:
- **Autosave** button to toggle on/off
- **Interval(s)** field to set seconds
- **15/30/60** preset buttons
- `Ctrl+-` / `Ctrl+=` to decrease/increase by 5s

## Path Management

### Quick-Fix Buttons
- **Fix Exp Ext**: Normalize export path extension to match format
- **Fix Proj Ext**: Normalize project path to `.comic.json`
- **Proj From Exp**: Derive project path from export directory
- **Exp From Proj**: Derive export path from project directory

### Status Indicators
- **P** (red): Project path needs normalization → click to fix
- **E** (red): Export path needs normalization → click to fix
- **PE** (red): Fix both paths at once

## Troubleshooting

### "Export blocked: generate panels + layout first"
You must complete the pipeline in order: Script → Panels → Layout → Export.

### "DeepSeek key missing"
Set the `DEEPSEEK_API_KEY` environment variable before launching, or use Local script generation.

### Project won't save
Check that the project path ends with `.comic.json`. Use **Fix Proj Ext** to normalize.

### GUI looks cramped
The application adapts to screen size. On heights below 860px, non-essential hints are hidden. Resize the window or use a larger display.

### Memory warnings in tests
Some test warnings about string leaks are known (literal strings vs owned strings). These do not affect runtime behavior.