Sienna Meridian Satterwhite
16deb5d237
BREAKING CHANGES: - Relationship syntax now requires blocks for all participants - Removed self/other perspective blocks from relationships - Replaced 'guard' keyword with 'if' for behavior tree decorators Language Features: - Add tree-sitter grammar with improved if/condition disambiguation - Add comprehensive tutorial and reference documentation - Add SBIR v0.2.0 binary format specification - Add resource linking system for behaviors and schedules - Add year-long schedule patterns (day, season, recurrence) - Add behavior tree enhancements (named nodes, decorators) Documentation: - Complete tutorial series (9 chapters) with baker family examples - Complete reference documentation for all language features - SBIR v0.2.0 specification with binary format details - Added locations and institutions documentation Examples: - Convert all examples to baker family scenario - Add comprehensive working examples Tooling: - Zed extension with LSP integration - Tree-sitter grammar for syntax highlighting - Build scripts and development tools Version Updates: - Main package: 0.1.0 → 0.2.0 - Tree-sitter grammar: 0.1.0 → 0.2.0 - Zed extension: 0.1.0 → 0.2.0 - Storybook editor: 0.1.0 → 0.2.0
388 lines
18 KiB
Markdown
388 lines
18 KiB
Markdown
# 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.*
|