# Flow Map — User Guide

The **Flow Map** is an interactive visualization of your cartridge's gameplay structure. It shows every zone, scene, input, and task as a connected graph, so you can see the whole cartridge at a glance — and jump to any point to test it instantly.

---

## Quick Start

```bash
# Launch the flow map for your cartridge
wheriflo flow MyAdventure.lua
```

This opens a browser page at `http://localhost:8070` with your cartridge's flow graph.

---

## What You'll See

The flow map has three panels:

### Left: Sidebar
A categorized list of every gameplay node:
- **Cartridge** — the `OnStart` entry point
- **Zones** — physical locations the player visits
- **Scenes** — functions that show messages or trigger gameplay
- **Inputs** — choice prompts and questions
- **Tasks** — objectives the player completes
- **Completion** — the cartridge end state

Click any node in the sidebar to select it. Right-click for the editing menu.

### Center: Graph Canvas
A visual directed graph (DAG) showing the flow between nodes:
- **Arrows** show transitions: zone activations, function calls, input triggers, task completions
- **Node colors** indicate type:
  - 🟢 Green = Start
  - 🔵 Blue = Zone
  - 🟣 Purple = Scene
  - 🟠 Orange = Input
  - 🟢 Teal = Task
  - 🔴 Red = End/Complete
- **Blue glow** around visited nodes (ones you've tested)
- **Blue arrows** for edges you've traversed during testing; gray for untested

Scroll to navigate the graph. Click any node to select it.

### Right: Detail Panel
Shows details about the selected node:
- **Type** and **Line number** in the source
- **Transitions out** — clickable links to nodes this one leads to
- **Transitions in** — clickable links to nodes that lead here
- **Designer notes** (if you've added any)
- **▶ Jump Here** button — instantly loads the game to this point
- **Edit / Star** buttons for customization

---

## Jump-to-Section

The most powerful feature. Click **▶ Jump Here** on any node to:

1. Load the cartridge engine
2. Automatically navigate to that game state
3. Show the **live game event** in the detail panel

If a message is showing, you'll see the full text with a **Dismiss →** button. If it's an input/choice, you'll see the options and can pick one. The game continues from there — you can play through the scene right in the flow map.

**How it works:** For the Start node, it just runs `OnStart`. For zone nodes, it teleports to that zone (triggering `OnEnter`). For scene nodes deeper in the graph, it finds a zone ancestor and teleports there, then auto-dismisses messages to advance.

> **Tip:** If a jump doesn't land exactly where you expect (e.g., a scene that requires specific prior state), try jumping to the zone first, then manually dismissing/answering through to the scene you want.

---

## Coverage Tracking

As you test by jumping to nodes and dismissing/answering messages, the flow map tracks what you've visited:

- **Header counter**: `X/Y visited (Z%)` — shows how many nodes you've reached
- **Sidebar checkmarks**: ✓ appears next to visited nodes
- **Node glow**: Visited nodes get a subtle blue outline in the graph
- **Edge highlighting**: Traversed edges turn blue; untested edges stay gray

Coverage persists across sessions in the `.wheriflo-flowmap.json` sidecar file. This helps you find untested branches — if a node or edge is still gray, you haven't tested that path yet.

---

## Designer Editing

Right-click any node (in the sidebar or graph) to customize:

| Action | What it does |
|--------|-------------|
| **✏ Rename** | Give the node a human-readable label (e.g., `startHomePlateAtBat` → `Home Plate At-Bat`) |
| **📝 Add Note** | Attach a designer comment (shown in detail panel and as a 📝 badge in sidebar) |
| **⭐ Star** | Mark a node as a favorite jump target (⭐ badge appears on node) |
| **🙈 Hide** | Remove a node from the graph (e.g., internal helper functions). Hidden nodes can be shown via the "Show N hidden" toggle at the bottom of the sidebar. |

All edits are saved to `.wheriflo-flowmap.json` in your cartridge directory. This file is gitignored by default — it's personal workspace state, not part of the cartridge source.

---

## How Nodes Are Discovered

The flow analyzer reads your `.lua` source and automatically finds:

| Source Pattern | Node Type |
|---------------|-----------|
| `cart:OnStart()` or `cart.OnStart = function()` | Start |
| `zone.OnEnter = function()` | Zone |
| `function sceneName()` containing `MessageBox` | Scene |
| `Wherigo.ZInput(cart)` | Input |
| `Wherigo.ZTask(cart)` | Task |
| `cart.Complete = true` | End |

### How Edges Are Discovered

| Source Pattern | Edge |
|---------------|------|
| `zone.Active = true` inside a function | → Zone activation |
| `functionName()` call inside a callback | → Function call |
| `Wherigo.GetInput(inputVar)` | → Input trigger |
| `task.Active = true` or `task.Complete = true` | → Task transition |
| `cart.Complete = true` | → End |

Edges are inferred from static analysis — they show what *could* happen based on the code structure. Runtime coverage then confirms which paths you've actually tested.

---

## MCP Integration

If you're using wheriflo as an MCP server with an AI assistant, you can also analyze flow from the chat:

```
Use wheriflo_flow to analyze the cartridge structure
```

This returns a text summary of nodes and edges, useful for AI-assisted cartridge review.

---

## Tips

- **Start with Jump Here on OnStart** to verify the opening sequence, then work forward through the graph
- **Use Rename generously** — function names like `scene4CorrectResponse` become much clearer as "Scene 4: Correct Answer"
- **Hide utility nodes** that clutter the graph (helpers, internal functions)
- **Star your most-tested scenes** so you can quickly jump back during iteration
- **Check coverage before release** — aim for all major branches visited
- **The flow map updates live** — if you edit your `.lua` file, refresh the page to see the updated graph
