storybook/examples/alice-in-wonderland/README.md

# Alice's Adventures in Wonderland - Storybook Example

A comprehensive demonstration of the Storybook DSL, modeling Lewis Carroll's *Alice's Adventures in Wonderland* with accuracy to the source material and showcasing all advanced language features.

## Overview

This example shows how Storybook enables complex narrative modeling for agent simulation games. It demonstrates:

- **Advanced behavior trees** for complex, context-dependent character actions
- **Life arcs** tracking transformative character journeys
- **Schedules** modeling eternal time loops and recurring events
- **Template composition** with inheritance and strict mode
- **Bidirectional relationships** with asymmetric perspectives
- **Cross-file references** creating an interconnected world model

## Contents

### Schema Layer

**`schema/core_enums.sb`**
- Core value types used throughout: `Size`, `EmotionalState`, `CardSuit`, `CardRank`, `TimeState`, `ManifestationLevel`
- Demonstrates enumeration definitions

**`schema/templates.sb`**
- Base template `WonderlandCreature` for all sentient beings
- Specialized templates with `include`: `SizeChanging`, `MadTeaPartyMember`, `Supernatural`
- **Strict template** `PlayingCard` enforcing concrete values
- Shows vertical inheritance (includes) and horizontal composition (multiple `from` clauses)

**`schema/species.sb`**
- Species definitions: `Human`, `Rabbit`, `Cat`, `Hare`, `Dormouse`, `Caterpillar`, `PlayingCardPerson`
- Rich prose blocks describing characteristics and abilities

### World Layer

#### Characters

**`alice.sb`** - The protagonist
- Inherits from `SizeChanging` template
- **Life arc `AliceJourney`** with states: `falling`, `tiny_alice`, `giant_alice`, `normal_alice_garden`, `enlightened_alice`
- Shows how life arcs track transformative journeys with state-specific field modifications

**`white_rabbit.sb`** - The anxious herald
- **Behavior tree `WhiteRabbit_ConstantlyLate`** using selectors (`?`) and sequences (`>`)
- Demonstrates hierarchical behavior modeling with panic strategies

**`cheshire_cat.sb`** - The enigmatic guide
- **Three behavior trees**:
  - `CheshireCat_AppearDisappear` - context-dependent materialization
  - `CheshireCat_GradualManifestation` - piece-by-piece appearance (grin first!)
  - `CheshireCat_GradualDematerialization` - fading away (grin lingers longest)
- Shows complex multi-step sequences with timing and state transitions

**`mad_tea_party.sb`** - The eternal tea party trio
- Three characters: `MadHatter`, `MarchHare`, `Dormouse`
- **Schedule `MadTeaPartyRotation`** modeling the time loop (always 6 o'clock)
- **Behavior `MadTeaParty_CoordinatedMadness`** showing multi-agent coordination
- Demonstrates repeater decorator (`*`) for infinite loops

**`royal_court.sb`** - The Court of Hearts
- Characters: `QueenOfHearts`, `KingOfHearts`, `CardGardenerTwo`, `CardGardenerFive`, `CardGardenerSeven`
- Inherits from `PlayingCard` strict template - card suit/rank must be concrete
- **Behavior `QueenOfHearts_RagePattern`** - hair-trigger temper response
- **Behavior `KingOfHearts_SecretPardons`** - background mercy system

**`caterpillar.sb`** - The philosophical teacher
- **Behavior `Caterpillar_SocraticMethod`** - interrogative teaching style
- Shows question-answer tree structures

#### Locations

**`wonderland_places.sb`**
- `RabbitHole`, `HallOfDoors`, `Garden`, `MadTeaPartyTable`, `CroquetGround`, `QueensPalace`, `MushroomTop`
- Each location has physical properties, symbolic meaning, and narrative significance
- Demonstrates rich prose blocks for description and analysis

#### Institutions

**`wonderland_institutions.sb`**
- `CourtOfHearts` - tyrannical monarchy with interesting power dynamics
- `MadTeaParty` - eternal social gathering stuck in time
- `WonderlandDreamLogic` - the meta-institution governing reality itself
- Shows how social structures can be modeled with hierarchies and rules

#### Relationships

**`wonderland_relationships.sb`**
- **Bidirectional relationships** with `self` and `other` blocks showing asymmetric perspectives:
  - `AliceAndWhiteRabbit` - pursuer/unwitting guide
  - `AliceAndCheshireCat` - seeker/amused observer
  - `QueenAndKing` - tyrant/secret rebel
  - `AliceAndCaterpillar` - frustrated student/Socratic teacher
- Demonstrates how different characters perceive the same relationship differently

#### Behaviors

**`alice_behaviors.sb`** - Alice's strategic behaviors
- `Alice_SizeManagement` - learning to control size through trial and error
- `Alice_NavigateConversation` - dealing with nonsensical logic
- `Alice_EmotionalJourney` - state transitions from curiosity to enlightenment
- `Alice_ProblemSolving` - adapting normal-world logic to Wonderland

## Language Features Demonstrated

### 1. Template Composition

```storybook
template WonderlandCreature {
    current_size: Size
    emotional_state: EmotionalState
    follows_logic: false..true
}

template SizeChanging {
    include WonderlandCreature
    natural_size: Size
    size_changes_today: 0..50
}

character Alice from SizeChanging {
    // Inherits all fields from WonderlandCreature and SizeChanging
    age: 7
    current_size: normal
}
```

### 2. Strict Templates

```storybook
template strict PlayingCard {
    suit: CardSuit
    rank: CardRank
    // Characters using this template MUST provide concrete values
}

character QueenOfHearts from PlayingCard {
    suit: hearts    // Required: must be concrete enum value
    rank: queen     // Required: must be concrete enum value
}
```

### 3. Life Arcs

```storybook
life_arc AliceJourney {
    state tiny_alice {
        on enter {
            Alice.current_size: tiny
            Alice.size_changes_today: +1
        }
    }

    state giant_alice {
        on enter {
            Alice.current_size: huge
        }
    }
}
```

### 4. Schedules

```storybook
schedule MadTeaPartyRotation {
    18:00 -> 18:01: TeaRound { }
    18:01 -> 18:02: RiddlePhase { }
    // ... more phases
    18:05 -> 18:00: LoopToBeginning { }  // Loops back!
}
```

### 5. Behavior Trees

```storybook
behavior CheshireCat_AppearDisappear {
    ? {  // Selector: try branches until one succeeds
        > {  // Sequence: all must succeed in order
            IsInvisible
            DecideToAppear
            GradualManifestation
        }
        > {
            IsVisible
            DecideToLeave
            GradualDematerialization
        }
    }
}
```

### 6. Repeater Decorator

```storybook
behavior MadTeaParty_CoordinatedMadness {
    * {  // Repeater: loop forever
        ? {
            > { AskRiddle; ReceiveNoAnswer }
            > { RotateSeats; CheckTime }
        }
    }
}
```

### 7. Bidirectional Relationships

```storybook
relationship QueenAndKing {
    QueenOfHearts
    KingOfHearts

    bond: 0.4

    self {
        // Queen's perspective
        role: dominant_spouse
        aware_of_pardons: false
    }

    other {
        // King's perspective
        role: secret_moderator
        subverts_authority: 1.0
    }
}
```

### 8. Rich Prose Blocks

```storybook
character CheshireCat {
    ---description
    A large cat with a permanent, unsettling grin. Possesses the
    ability to appear and disappear at will, often leaving only
    its grin behind.
    ---

    ---philosophy
    The Cheshire Cat represents the absurdist nature of Wonderland
    itself. His vanishing act defies physical law but seems
    perfectly natural in Wonderland's logic.
    ---
}
```

### 9. Cross-File References

```storybook
// In alice.sb
use schema::core_enums::{Size, EmotionalState};
use schema::templates::SizeChanging;

character Alice from SizeChanging {
    current_size: normal  // Uses Size enum from core_enums
}
```

### 10. Field Modifications in Life Arcs

```storybook
state enlightened_alice {
    on enter {
        Alice.emotional_state: brave
        Alice.awareness_of_absurdity: 1.0  // Absolute assignment
        Alice.size_changes_today: +1       // Increment
    }
}
```

## Accuracy to Source Material

This example stays faithful to Carroll's original text:

- **Mad Tea Party**: Time frozen at 6 o'clock, rotating seats, butter in the watch
- **Cheshire Cat**: Grin appearing first/last, cryptic directions, "we're all mad here"
- **Queen of Hearts**: Constant "Off with their heads!", card gardeners, croquet with flamingos
- **Alice's transformations**: Specific size states from the book
- **Caterpillar's advice**: Terse questions, mushroom sides
- **Character dynamics**: White Rabbit's anxiety, Dormouse's drowsiness, King's secret mercy

## Running the Example

```bash
# Validate the entire project
sb validate examples/alice-in-wonderland/

# Query characters
sb query "characters where follows_logic == false"

# Inspect a specific character
sb inspect Alice

# Show all relationships
sb query "relationships where bond > 0.5"
```

## What This Demonstrates

### For Content Authors (Lonni)

- **Rich character modeling**: Personality traits, motivations, relationships
- **Narrative structure**: Life arcs track character journeys
- **World building**: Locations, institutions, social dynamics
- **Prose integration**: Backstories, descriptions, and philosophical notes

### For Developers (Sienna)

- **Complex behavior trees**: Multi-level selectors, sequences, repeaters
- **State management**: Life arcs with field modifications
- **Scheduling systems**: Time loops and recurring events
- **Type safety**: Strict templates enforce constraints
- **Cross-referencing**: Build interconnected world models

### For Agent Simulation

This model could drive an agent-based simulation where:

- Alice's behavior tree decides how to navigate conversations and obstacles
- The Mad Tea Party schedule creates a time-loop environment
- Cheshire Cat's appearance/disappearance behavior creates mystery
- Queen's rage pattern generates conflict
- Relationships determine interaction dynamics

## Extending This Example

Ideas for additions:

- **More chapters**: Mock Turtle, Gryphon, Trial scene
- **Croquet game logic**: Behavior trees for live hedgehog/flamingo equipment
- **Size change mechanics**: Fine-grained mushroom nibbling behavior
- **Dream logic system**: Meta-rules governing Wonderland physics
- **Alice's awakening**: Final life arc state transitioning back to reality

## License

Source material: *Alice's Adventures in Wonderland* by Lewis Carroll (public domain)
Storybook adaptation: MIT License