# Storybook Editor UI Architecture

> Structured creative tools for non-technical storytelling

## Design Philosophy

**Primary User (Lonni)**: Creative writer who thinks in characters, relationships, and narrative arcs—NOT files and syntax.

**Secondary User (Sienna)**: Developer who needs access to raw `.sb` files for behavior trees, schemas, and engine integration.

**Core Principle**: The editor should feel like **writing**, not coding. Structured panes guide creation. The file editor is "manual mode" for power users.

## Application Structure

```
┌─────────────────────────────────────────────────────────────────────┐
│  Storybook Editor - examples/alice-in-wonderland/                   │
├──────────────┬──────────────────────────────────────┬───────────────┤
│              │                                      │               │
│   Entity     │        Character Editor              │  Quick        │
│   Browser    │                                      │  Actions      │
│              │  ┌─────────────────────────────────┐ │               │
│  Characters  │  │ Name: Alice                     │ │ ✓ Validate    │
│  ├─ Alice    │  │ Age: 7                          │ │ ⎇ Versions    │
│  ├─ Rabbit   │  │ Species: Human                  │ │ ⊕ New Char    │
│  └─ Queen    │  │                                 │ │ ⊕ New Rel     │
│              │  │ Traits                          │ │ ⊕ New Place   │
│  Relations   │  │  curiosity: 0.95 [━━━━━━━━━•─] │ │               │
│  ├─ Alice    │  │  politeness: 0.75 [━━━━━━━•───] │ │ 🔍 Search...  │
│  │  ↔ Rabbit │  │                                 │ │               │
│  └─ Queen    │  │ Backstory                       │ │ Git           │
│     ↔ King   │  │ ┌─────────────────────────────┐ │ │  main         │
│              │  │ │ Alice was beginning to get  │ │ │  3m ago       │
│  Places      │  │ │ very tired of sitting by    │ │ │  12 changes   │
│  ├─ Rabbit   │  │ │ her sister on the bank...   │ │ │               │
│  │  Hole     │  │ │                             │ │ └───────────────┘
│  └─ Tea      │  │ └─────────────────────────────┘ │
│     Party    │  │                                 │
│              │  │ [Portrait slot: click to add]   │
│  Schedules   │  │                                 │
│  Templates   │  │             [Save Character]    │
│  Behaviors   │  └─────────────────────────────────┘
│              │                                      │
│  [Manual]    │  Tabs: Traits | Backstory | Schedule│
│              │        Relationships | Behavior     │
└──────────────┴──────────────────────────────────────┴───────────────┘
```

## Primary Views (Structured Editing)

### 1. Character Editor

**Purpose**: Create and edit characters through forms and rich text, NOT raw `.sb` syntax.

**Layout**:
- **Header**: Name input (large, prominent)
- **Metadata Row**: Age, species, template dropdowns
- **Traits Section**: Sliders for numeric traits, chips for tags
- **Prose Sections**: Tabbed rich text areas for backstory, appearance, personality
- **Portrait**: Image upload with preview
- **Relationships**: Quick list with "Edit" buttons
- **Schedule**: Mini timeline preview with "Edit Full Schedule" button

**Interaction**:
- All changes auto-save to `.sb` file (no explicit save button for small edits)
- Git auto-commit on major milestones (e.g., "Update Alice: added backstory")
- Validation errors show inline (e.g., red border + tooltip for out-of-range trait)

**Example**:
```
┌─────────────────────────────────────────────────────┐
│ Name: Alice                               [Portrait]│
│ Age: 7    Species: Human    Template: Child         │
├─────────────────────────────────────────────────────┤
│ Traits                                              │
│  curiosity     0.95  [━━━━━━━━━━━━━━━•─]           │
│  politeness    0.75  [━━━━━━━━━━━•─────]           │
│  fear_of_queen 0.10  [━•──────────────────]         │
│                                                     │
│  Tags: [imaginative] [brave] [+ Add Tag]           │
├─────────────────────────────────────────────────────┤
│ ⎔ Backstory  │  Appearance  │  Personality         │
├─────────────────────────────────────────────────────┤
│ Alice was beginning to get very tired of sitting    │
│ by her sister on the bank, and of having nothing    │
│ to do...                                            │
│                                                     │
│ [Rich text editor with basic formatting]           │
└─────────────────────────────────────────────────────┘
```

### 2. Relationship Editor

**Purpose**: Visually connect characters and define relationship properties.

**Layout**:
- **Graph View**: Force-directed graph with character nodes
- **Edge Selection**: Click edge to edit relationship details
- **Properties Panel**: Bond strength, coordination level, bond type
- **Asymmetric Fields**: "From Alice's perspective" / "From Rabbit's perspective"

**Interaction**:
- Drag nodes to rearrange
- Click edge → properties panel appears
- Slider for bond strength (0.0 to 1.0)
- Dropdown for bond type (romantic, familial, friendship, etc.)

**Example**:
```
┌─────────────────────────────────────────────────────────────┐
│ Relationship: Alice ↔ White Rabbit                          │
├─────────────────────────────────────────────────────────────┤
│  Bond Strength: 0.65  [━━━━━━━•──────]                      │
│  Bond Type: friendship                                      │
│  Coordination: ad_hoc                                       │
├─────────────────────────────────────────────────────────────┤
│  From Alice's perspective:                                  │
│    Respect for punctuality: 0.80 [━━━━━━━━•──]             │
│                                                             │
│  From White Rabbit's perspective:                           │
│    Anxiety about lateness: 0.95 [━━━━━━━━━━━•─]            │
├─────────────────────────────────────────────────────────────┤
│                   [Graph View]                              │
│                                                             │
│        Alice ●━━━━━━● White Rabbit                         │
│                                                             │
│    Queen ●━━━━━━━━━━● King                                 │
│       ╲             ╱                                       │
│        ●━━━━━━━━━━●                                         │
│       Guards                                                │
└─────────────────────────────────────────────────────────────┘
```

### 3. Schedule Builder

**Purpose**: Visual timeline for daily routines (no typing time codes!).

**Layout**:
- **Timeline**: Horizontal 24-hour view with draggable blocks
- **Activity Palette**: Drag activities from sidebar onto timeline
- **Activity Editor**: Click block to edit parameters

**Interaction**:
- Drag edges to resize time blocks
- Drag from palette to add new activity
- Snap to 15-minute increments
- Validation: overlapping blocks show warning

**Example**:
```
┌─────────────────────────────────────────────────────────────┐
│ Schedule: Alice's Day                                        │
├────┬────────────────────────────────────────────────────────┤
│    │ 00:00     06:00     12:00     18:00     24:00         │
│    ├───────────────────────────────────────────────────────┤
│ Su │ ████Sleep████│Breakfast│Play│Tea│Study│Play│█Sleep██  │
│ Mo │ ████Sleep████│Breakfast│School██████│Play│██Sleep███  │
│    └───────────────────────────────────────────────────────┘
│                                                             │
│ Palette:                                                    │
│  [Sleep] [Eat] [Play] [Study] [Social] [+ Custom]          │
│                                                             │
│ Selected: Tea Party (16:00 → 17:00)                        │
│  Location: Garden                                           │
│  Participants: Mad Hatter, March Hare, Dormouse            │
└─────────────────────────────────────────────────────────────┘
```

### 4. Behavior Tree Builder (Advanced)

**Purpose**: Visual node graph for programmable behaviors (Sienna's domain, but approachable for Lonni).

**Layout**:
- **Canvas**: Infinite 2D space for nodes
- **Node Palette**: Selector, Sequence, Condition, Action, Decorator
- **Inspector**: Selected node's properties

**Interaction**:
- Drag nodes from palette
- Connect with edges (parent → children)
- Right-click node → context menu (delete, duplicate, etc.)
- Validation: orphan nodes, missing actions show errors

**Example**:
```
┌─────────────────────────────────────────────────────────────┐
│ Behavior: WorkAtBakery                                      │
├─────────────────────────────────────────────────────────────┤
│  Palette: [Selector] [Sequence] [?Condition] [→Action]     │
│                                                             │
│  Canvas:                                                    │
│                                                             │
│           ┌─────────────┐                                   │
│           │  Selector   │                                   │
│           └──────┬──────┘                                   │
│         ┌────────┼────────┐                                 │
│         ▼        ▼        ▼                                 │
│     ┌──────┐ ┌──────┐ ┌──────┐                             │
│     │ Prep │ │ Bake │ │ Sell │                             │
│     │ Dough│ │Bread │ │ Bread│                             │
│     └──────┘ └──────┘ └──────┘                             │
│                                                             │
│  Selected: PrepDough                                        │
│    Action: knead_dough                                      │
│    Duration: 30 minutes                                     │
│    Required Skill: baking > 0.5                             │
└─────────────────────────────────────────────────────────────┘
```

## Secondary View (Manual Mode)

### File Editor

**Purpose**: Direct `.sb` syntax editing for power users and edge cases.

**When to Use**:
- Behavior trees (until visual editor is built)
- Templates with ranges
- Advanced features not yet in GUI
- Bulk find-replace across characters

**Layout**:
- Syntax-highlighted text editor (Monaspace Neon)
- Live validation with inline errors
- File tree on left

**Interaction**:
- Standard text editor keybindings
- Ctrl+S saves (git auto-commit)
- Errors show inline with gold underline
- Click error → jump to diagnostic

## Entity Browser (Left Sidebar)

**Purpose**: Navigate the storybook's content hierarchy.

**Structure**:
```
📂 characters/
├─ 👤 Alice
├─ 🐰 White Rabbit
├─ 👑 Queen of Hearts
└─ 👑 King of Hearts

💑 relationships/
├─ Alice ↔ White Rabbit
├─ Queen ↔ King
└─ Queen → Subjects (all)

📍 locations/
├─ 🕳️ Rabbit Hole
├─ 🫖 Tea Party Garden
└─ 🏰 Queen's Castle

📋 templates/
├─ WonderlandCreature
├─ PlayingCard
└─ CourtMember

🎭 behaviors/
├─ WorkAtBakery
└─ AttendTeaParty

📅 schedules/
└─ DailyRoutine
```

**Interaction**:
- Click entity → load in main panel
- Right-click → context menu (delete, duplicate, etc.)
- Drag-drop to reorder or move files
- Search box filters by name

## Quick Actions Pane (Right Sidebar)

**Purpose**: Common tasks and project status at fingertips.

**Sections**:

1. **Actions**
   - ✓ Validate All
   - ⊕ New Character
   - ⊕ New Relationship
   - ⊕ New Location
   - 🔍 Search Everything

2. **Git Status**
   - Current branch: `main`
   - Last change: `3 minutes ago`
   - Uncommitted changes: `12 files`
   - [View History] button → timeline view

3. **Diagnostics**
   - ✓ No errors
   - ⚠ 2 warnings
   - Click to expand inline

4. **Project Info**
   - Characters: 12
   - Relationships: 7
   - Locations: 5

## Responsive Behavior

### Wide Screen (> 1440px)
Three columns: Entity Browser | Main Editor | Quick Actions

### Standard (1024–1440px)
Two columns: Entity Browser | Main Editor
Quick Actions → collapsible panel

### Compact (< 1024px)
Single column focus mode
Entity Browser → drawer (slides in from left)
Quick Actions → toolbar at top

## Technical Implementation Notes

### Iced Framework
- Use `iced::widget::*` for built-in components
- Custom widgets for:
  - Timeline (schedule builder)
  - Graph (relationship map)
  - Node Canvas (behavior tree builder)
  - Trait Slider (with live value display)

### File Synchronization
- Watch `.sb` files for external changes
- Reload editor state on change
- Warn if unsaved changes conflict

### Git Integration
- Auto-commit on save with descriptive messages:
  - "Update Alice: modified backstory"
  - "Add relationship: Alice ↔ White Rabbit"
  - "Create character: Cheshire Cat"
- Use `git2` crate (no shell commands)
- Expose branches as "versions" in UI

### Theme Application
- Load colors from `design/color-palette.md`
- Apply 8px grid to all spacing
- Use Monaspace Neon for code blocks
- Geist for UI text
- Gradient background: aubergine (sides) → cream (center) in main editor panel

## User Workflows

### Lonni Creates a New Character

1. Click "⊕ New Character" in Quick Actions
2. Fill in name, age, species (dropdowns guided by schema)
3. Adjust trait sliders (validation prevents out-of-range)
4. Write backstory in rich text area
5. Upload portrait image
6. Click "Save" → `.sb` file created, git commit happens
7. Character appears in Entity Browser

### Lonni Builds a Relationship

1. Click "⊕ New Relationship"
2. Select two characters from dropdowns
3. Drag bond strength slider
4. Pick bond type from predefined options
5. Fill in asymmetric fields (Alice's view vs. Rabbit's view)
6. Save → `.sb` file updated, git commit

### Sienna Edits a Behavior Tree

1. Click behavior in Entity Browser
2. See visual node graph
3. Drag new "Action" node from palette
4. Connect to parent Sequence
5. Set action parameters in inspector
6. Save → `.sb` file updated

### Both Users Check Validation

1. Quick Actions shows "⚠ 2 warnings"
2. Click to expand → shows inline errors
3. Click error → jumps to problematic entity
4. Fix in structured editor
5. Validation updates live

---

*This architecture prioritizes Lonni's creative flow while keeping power-user features accessible for Sienna.*
