interactive-story/planning/BROWSER-UX-SPEC.md

# Adventure Storyteller — Browser UX Specification

**Status:** v1.0 UX target — selected base is AI-DnD  
**Purpose:** Define the browser-based user experience for v1, including primary storytelling flow, history controls, campaign management, state inspection, imported knowledge, prompt inspection, and future media extension points.

## 1. UX Goal

The application should feel like a focused local interactive-story workspace, not a developer console and not a complicated RPG dashboard.

The main screen should optimize for:

- reading the story,
- entering the next action,
- correcting mistakes,
- retrying narration,
- saving checkpoints,
- understanding what the system currently believes.

The core rule is:

> Advanced state, memory, provenance, and branch mechanics should be available without dominating the normal storytelling experience.

## 2. Primary User Mental Model

The user should think in terms of:

```text
Story
Current situation
What I do next
Undo / Redo
Retry
Save point
```

The user should not need to think in terms of:

```text
branch IDs
node graphs
database rows
embedding vectors
context windows
state event logs
```

Those may exist internally or in advanced diagnostics.

## 3. Browser-First Requirement

v1 should be fully usable through a local browser.

The command line may be used for:
- installation,
- startup,
- troubleshooting.

It should not be required for normal story creation/play.

## 4. Default Layout

Recommended desktop layout:

```text
+-------------------------------------------------------------+
| Campaign title        Model/status            Settings      |
+-------------------------+-----------------------------------+
|                         |                                   |
| Story Transcript        | Context / State Panel             |
|                         |                                   |
|                         |                                   |
|                         |                                   |
|                         |                                   |
+-------------------------+-----------------------------------+
| Undo  Redo  Retry  Save Point                              |
+-------------------------------------------------------------+
| [ Story input ............................................ ] |
| [ Send ]                                                    |
+-------------------------------------------------------------+
```

The right panel should be collapsible.

## 5. Responsive Behavior

Primary target:
- desktop/laptop browser.

Secondary:
- tablet.

Mobile support is optional for v1.

On narrower screens:
- collapse side panel,
- move diagnostics to drawers/tabs,
- keep story input and history controls always accessible.

## 6. Main Story Transcript

The transcript is the primary surface.

Each accepted turn should visually distinguish:

- user input,
- narrator response.

Optional metadata may be hidden by default:
- turn number,
- timestamp,
- model name,
- token count.

## 7. Transcript Ordering

Show only the active story lineage in the normal transcript.

Do not show:
- abandoned/disposable history,
- inactive retry takes,
- alternate branch trees

unless the user explicitly opens a history/retry control.

## 8. Current Story Head

The current endpoint should be clear.

The input box always continues from the currently active story head.

## 9. User Turn Presentation

User messages should support:

- edit,
- optional copy,
- optional inspect turn context.

Editing an older user turn should trigger the defined non-destructive history behavior.

## 10. Narrator Turn Presentation

Narrator messages should support:

- Retry,
- Edit,
- Copy,
- Inspect Context,
- optional media action later.

## 11. Story Input Box

The input box should support free-form natural language.

The layout should reserve space for a future local speech-to-text control, such as a microphone/dictation button, without requiring STT in v1.

Examples:

```text
I enter the tavern.
```

```text
I ask Mara whether she has seen Edrin.
```

```text
I wait quietly and watch the room.
```

## 12. Input Modes

Preferred v1 approach:

One natural-language input field.

Do not require separate rigid modes such as:
- Action,
- Speech,
- Story,
- Command

unless inherited UI makes them useful without complexity.

Optional helpers may exist.

## 13. Out-of-Character Direction

The user should have a way to provide story-direction instructions.

Possible UX:

```text
[ ] Treat as story direction
```

or a small mode selector:

```text
Story Action | Direction
```

Example:

```text
Keep this scene tense, but do not start a fight yet.
```

The UI should make clear that this is not protagonist dialogue.

## 14. Send / Generate

Submitting input should:

1. persist user intent safely,
2. build context,
3. call local Ollama,
4. stream or display narrator output,
5. validate/commit resulting state.

## 15. Streaming

Streaming narrator text is strongly preferred.

Benefits:
- perceived responsiveness,
- natural reading experience.

If streaming complicates atomic state acceptance, narration may stream visually while final state commit occurs afterward.

## 16. Generation State

While generating, show clear state:

```text
Narrating...
```

Controls:
- Stop generation if practical,
- do not accept another conflicting story input until current generation resolves.

## 17. Failed Generation

On failure:

Show:

```text
Generation failed.
[Retry]
```

Do not insert a broken/partial accepted turn.

If partial streamed text exists:
- label it uncommitted,
- discard or allow manual recovery according to implementation.

## 18. Undo Control

Undo should be always accessible near input/history controls.

Behavior:
- one click = one accepted story step backward.

No branch terminology.

## 19. Redo Control

Redo should appear next to Undo.

Disable it when:
- no redo path exists,
- a new continuation invalidated ordinary redo.

## 20. Retry Control

Retry should be attached to the latest narrator response and optionally in the global control row.

Meaning:

```text
Generate another narrator response to the same user input.
```

## 21. Retry Takes

When more than one narrator take exists, show a compact control such as:

```text
Take 2 of 3   < Previous   Next >
```

Do not show a branch tree.

## 22. Retry Selection

Selecting a take should update the visible narrator response for that turn.

Before continuing:
- user may move among takes.

Once a next turn is accepted:
- non-selected takes remain retained/disposable.

## 23. Checkpoint Control

Primary action:

```text
Save Point
```

or:

```text
Checkpoint
```

Preferred user-facing label:

```text
Save Point
```

Reason:
- more intuitive than technical "checkpoint."

Internal documentation may still use checkpoint.

## 24. Save Point Dialog

Fields:

```text
Name:
[ Before entering the abbey ]

[Save]
```

Optional:
- note.

Default name suggestion may use:
- current scene,
- turn number.

## 25. Save Point List

Accessible from:
- campaign sidebar,
- top menu,
- dedicated Save Points panel.

Each entry:

```text
Before entering the abbey
Moment 42
[Restore] [Rename] [Delete]
```

**Moment, not Turn.** M4 closeout ruled in favour of the implemented product:
the branch panel and the tree overlay already count in moments (`forked at
moment 9`, `ends at moment 40`), so a Save Point list saying "Turn 42" would
make one screen use two words for one thing. This is a vocabulary alignment and
changes no behaviour; the number is unchanged.

## 26. Restore Confirmation

Restoring is non-destructive.

Confirmation should explain:

```text
The story will return to this save point.
Your current later history will be retained but will no longer be active.
```

Buttons:

```text
Restore
Cancel
```

## 27. Delete Save Point

Explicit confirmation.

Clarify:

```text
Deleting this save point does not delete story history.
```

## 28. Editing User Input

Each user turn should have:

```text
Edit
```

On edit:
- inline editor preferred,
- show warning if later history exists.

Suggested message:

```text
Changing this earlier action will create a new continuation.
The current later story will be retained as discarded history.
```

Buttons:

```text
Save and Continue
Cancel
```

## 29. Editing Narrator Text

Narrator turn supports:

```text
Edit
```

This is useful for:
- correcting continuity,
- fixing wording,
- enforcing preferred story direction.

UX should explain that downstream state may be recalculated.

## 30. Manual State Correction

Advanced panel action:

```text
Correct Story State
```

Potential entry points:
- current state inspector,
- fact/entity inspector.

Do not expose raw JSON as the only interface.

## 31. Current State Panel

Collapsible right-side panel.

Suggested sections:

```text
Current Scene
Characters Present
Important Facts
Items
Relationships
Open Threads
```

Keep concise.

## 32. Current Scene Section

Show:

```text
Location
Time / situation
Characters present
Immediate conditions
```

Future:
- scene illustration.

## 33. Character Section

Each character card may show:

```text
Name
Role
Current status
Relationship
Known important facts
```

Optional:
- visual profile.

## 34. Item Section

Show important story-relevant items.

Example:

```text
Silver Key — carried by Aldric
```

## 35. Open Threads

Example:

```text
Find Edrin — Open
Investigate broken-circle symbol — Open
```

The UI should not behave like a quest game unless desired.

Use "Story Threads" rather than "Quests" as generic terminology.

## 36. State Inspector Depth

Default panel:
- concise.

Clicking an entity opens detailed inspector.

This prevents overwhelming the main story screen.

## 37. Detailed Entity Inspector

Potential fields:

```text
Current state
Known facts
Relationships
History
Source/provenance
Visual profile
```

Advanced data may be hidden behind expandable sections.

## 38. Hidden Narrator State

Some campaigns may contain secrets.

Normal player-facing state panel should not reveal narrator-only facts by default.

Provide optional advanced mode:

```text
Show Hidden Story State
```

with clear warning.

## 39. Campaign Sidebar / Menu

Campaign-level actions:

```text
New Campaign
Open Campaign
Campaign Settings
Save Points
Knowledge
Export
Delete Campaign
```

## 40. Campaign Library

Landing screen should list local campaigns.

Each:

```text
Continuity Test
Last played: ...
Current scene: Crooked Lantern
```

Actions:
- Open,
- Export,
- Delete.

## 41. New Campaign Flow

Recommended steps:

```text
1. Name
2. Campaign profile
3. Narrator/style settings
4. Initial canon / setup
5. Optional imported knowledge
6. Start
```

Keep minimal.

## 42. Campaign Profile

Fields may include:

```text
Genre
Subgenre
Tone
Point of View
Narration Length
```

Do not hardcode fantasy-specific setup.

## 43. Narrator Settings

Potential settings:

```text
Model
Temperature
Response length
Style profile
```

Advanced settings should be collapsible.

## 44. Local Model Status

Header/status area should show:

```text
Ollama: Connected
Model: qwen...
```

If unavailable:

```text
Ollama unavailable
```

with local troubleshooting guidance.

## 45. No Cloud Provider UI

v1 should not show:
- OpenAI,
- Anthropic,
- OpenRouter,
- remote provider sign-in.

This supports the local-only mental model.

## 46. Knowledge Panel

Dedicated campaign section:

```text
Knowledge
```

List imported files.

Columns/cards:

```text
Title
Type: Canon / Reference / Inspiration
Enabled
Last updated
```

## 47. Import Knowledge

Action:

```text
Import File
```

Supported v1:
- `.txt`,
- `.md`.

Flow:
1. choose local file,
2. preview,
3. classify,
4. optional title/tags,
5. import.

## 48. Classification UX

Use explicit choices:

```text
Canon
Authoritative truth for this campaign.

Reference
Supporting information; does not establish story truth.

Inspiration
Creative/style influence only.
```

Do not rely on unexplained icons.

## 49. Knowledge Source Detail

Show:

```text
Original filename
Classification
Enabled
Imported date
Tags
Linked entities
Text preview
Chunks
```

Advanced:
- hash,
- indexing metadata.

## 50. Disable Knowledge

Toggle:

```text
Enabled
```

Disabling should be immediate and reversible.

## 51. Delete Knowledge

Explicit confirmation.

Explain:
- source will stop being used,
- historical turns remain unchanged.

## 52. Retrieval Usage

Source detail may show:

```text
Used in 12 narrator turns
```

Clicking could show turn provenance later.

This is useful but not required for initial UI.

## 53. Prompt / Context Inspector

This is a major advanced feature.

Each narrator turn should offer:

```text
Inspect Context
```

## 54. Context Inspector Sections

Recommended:

```text
Narrator Rules
Campaign Canon
Current State
Story Summary
Retrieved Memories
Retrieved Knowledge
Recent History
Current User Input
Model Settings
Token Usage
```

## 55. Context Inspector Default

Show readable summaries first.

Do not begin with raw prompt text.

Optional advanced tab:

```text
Rendered Prompt
```

## 56. Retrieved Memory Row

Example:

```text
Accepted Story Memory
Turn 38
"The key bears the same symbol as the abbey crypt."
```

Show:
- source turn,
- authority,
- retrieval reason/score if useful.

## 57. Retrieved Knowledge Row

Example:

```text
canon.md
Canon
Section: Old Abbey
```

Click to open source.

## 58. Prompt Token Usage

Display:

```text
Input context: 8,240 tokens
Reserved output: 2,000 tokens
Model limit: 16,384
```

This helps debug long campaigns.

## 59. Summary Inspector

Show current rolling summary.

Advanced:
- source turn range,
- lineage,
- generated timestamp.

## 60. Memory Inspector

Campaign-level advanced panel:

```text
Memories
```

Functions:
- search,
- inspect,
- disable/correct.

Not required to be part of normal play.

## 61. Manual Memory Correction

Possible actions:

```text
Disable
Correct
Promote to Canon
Downgrade to Heuristic
```

Promotion should require explicit user intent.

## 62. History Diagnostics

Advanced feature:

```text
History
```

Initial v1 may show:
- active turn list,
- save points.

Do not expose full branch tree unless needed.

## 63. Discarded History

Not committed for v1.

Future possible menu:

```text
Discarded History
```

Could show:
- abandoned continuations,
- retry takes,
- restore points.

The schema/UX should leave room for this.

## 64. Branch Terminology

Avoid in normal UI:

```text
branch
merge
fork
node
HEAD
```

Preferred words:

```text
current story
save point
retry take
discarded history
restore
```

## 65. Campaign Export

Action:

```text
Export Campaign
```

Suggested options:

```text
Full Export
Without Media
```

If media not implemented:
- one full export option is enough.

## 66. Campaign Import

Landing screen action:

```text
Import Campaign
```

Show summary before import:
- title,
- source count,
- checkpoints,
- media count.

## 67. Delete Campaign

Destructive.

Require confirmation including campaign name.

Optional stronger confirmation:
- type campaign name.

## 68. Autosave

Preferred:

> Every accepted turn and state change is persisted automatically.

No manual Save button required for normal progress.

Save Point is for rollback, not persistence.

## 69. Persistence Status

Small status:

```text
Saved
```

or:

```text
Saving...
```

Optional but reassuring.

## 70. Restart Recovery

After browser refresh/application restart:
- return to campaign library or last campaign,
- active story/state restored.

No special recovery flow should be required after clean shutdown.

## 71. Error Presentation

Errors should distinguish:

```text
Model unavailable
Generation failed
State validation failed
Knowledge indexing failed
Database error
```

Avoid generic:
```text
Something went wrong
```

where useful details are available.

## 72. Technical Detail Toggle

Errors may show:

```text
Show technical details
```

for local debugging.

## 73. Security Indicators

Campaign settings should make local mode clear.

Example:

```text
Runtime mode: Local only
Ollama endpoint: 127.0.0.1:11434
```

## 74. External Link Warning

If user clicks a URL from story/imported content:

```text
This link opens an external website and leaves the local-only environment.
```

Option:
- Open,
- Cancel.

## 75. Remote Images

Do not render remote image URLs inline by default.

Show placeholder:

```text
Remote image blocked
```

## 76. Markdown Rendering

Narrator/user content may use Markdown.

Render safely:
- headings,
- emphasis,
- lists,
- code,
- blockquotes.

Do not allow arbitrary executable HTML.

## 77. Copying Story Text

Support copy:
- one message,
- selected range,
- full active transcript.

Optional export formats:
- Markdown,
- plain text.

## 78. Story Search

Strongly useful later:

```text
Search Story
```

Search active transcript and possibly full retained history.

Not essential to initial v1.

## 79. Keyboard Shortcuts

Potential:

```text
Ctrl/Cmd+Enter — Send
Ctrl/Cmd+Z — Undo
Ctrl/Cmd+Shift+Z — Redo
```

Be careful not to conflict with text editing.

Could defer shortcuts beyond Send.

## 80. Accessibility

Use:
- semantic HTML,
- keyboard navigation,
- visible focus,
- adequate contrast,
- ARIA labels where needed.

Transcript should be screen-reader navigable.

## 81. Font / Theme

Bundle assets locally.

Support:
- light/dark mode if easy.

Not core.

## 82. Reading Width

Long story text should use a readable content width.

Do not stretch prose across very wide monitor.

## 83. Transcript Density

Avoid excessive card chrome around every message.

The story should read like prose/dialogue, not a social-media feed.

## 84. Metadata Density

Turn IDs and technical metadata:
- hidden by default,
- visible in inspector.

## 85. Future Image UX

Narrator turn or scene header may offer:

```text
Generate Image
```

This should be optional.

## 86. Future Scene Image Placement

Possible:
- inline scene illustration,
- side-panel gallery,
- scene header thumbnail.

Do not force media into transcript.

## 87. Future Media Job Status

Example:

```text
Image generating...
```

Story interaction remains available.

## 88. Future Media Gallery

Campaign-level:

```text
Media
```

Group by:
- scene,
- image/video/audio,
- preferred asset.

## 89. Future Media Provenance

Asset detail:

```text
Scene
Turn range
Provider
Model
Seed
Prompt
Generation date
```

## 90. Future Video UX

Select story range:

```text
Create video from turns 210-215
```

Then review:
- scene summary,
- action beats,
- provider settings.

Not v1.

## 91. Future TTS UX

Possible controls:

```text
Read Narration
Read Dialogue
```

Per-character voice assignment belongs in advanced settings.

## 91A. Future Speech-to-Text UX

A future control near the story input field may provide:

```text
Dictate
```

Recommended flow:

```text
[Dictate]
   ->
record locally
   ->
local STT transcription
   ->
place transcript into normal input box
   ->
user reviews/edits
   ->
user presses Send
```

Important behavior:

- transcription is never auto-submitted by default,
- the user can correct names, punctuation, and misheard words,
- a clear recording indicator is required while the microphone is active,
- Stop/Cancel must be available,
- failed transcription must not alter story state,
- microphone audio and transcription stay local by default.

STT should feel like an alternate way to fill the same input box, not a separate storytelling mode.

## 92. UI State vs Story State

Do not mix UI preferences with story canon.

Examples of UI-only state:
- collapsed panels,
- selected tab,
- theme,
- inspector open/closed.

These should not affect story behavior.

## 93. Dangerous Advanced Features

If a fork contains:
- scripting console,
- QuickJS editor,
- arbitrary tool/plugin setup,
- cloud provider management,

remove or hide from v1 rather than exposing confusing advanced controls.

## 94. Selected Base Reuse — AI-DnD

Retain/adapt:
- React/Vite browser shell,
- transcript/streaming foundation,
- alternate-take controls where useful,
- Insights/prompt inspection concepts,
- existing story-history controls as the starting point.

Production UX must simplify RPG-heavy surfaces and hide branch/tree implementation details behind Undo/Redo/Retry/Save Point behavior.

## 95. Reference Reuse — Open Dungeon

Use as a design reference for:
- main story reading layout,
- simple interaction feel,
- Retry/Edit presentation,
- inline image placement,
- visual continuity concepts.

Do not port its destructive history semantics or treat its Next.js UI as a drop-in component source for the React/Vite fork.

## 96. Reference Reuse — ai-adventure

Primarily architectural, not UX.

Useful concepts:
- explicit state transparency,
- checkpoint/head semantics,
- deterministic operation and auditability.

The browser experience remains owned by the AI-DnD-based application.

## 97. V1 Navigation Map

Recommended:

```text
Campaign Library
   |
   +--> Campaign
          |
          +--> Story
          +--> Save Points
          +--> State
          +--> Knowledge
          +--> Context / Insights
          +--> Settings
          +--> Export

Future:
          +--> Media
          +--> Voice / Speech Settings
          +--> Discarded History
```

## 98. Main Story Screen Priority

Visual priority order:

```text
1. Story transcript
2. Input
3. Undo / Redo / Retry
4. Save Point
5. Current scene/state
6. Advanced diagnostics
```

## 99. V1 Required UX

The final v1 browser interface must support:

- campaign library,
- create/open/delete campaign,
- active transcript,
- natural-language input,
- local Ollama status,
- Undo,
- Redo,
- Retry,
- selecting retry takes,
- editing prior user input,
- editing narrator response,
- named Save Points,
- restore Save Point,
- current state inspection,
- imported knowledge management,
- Canon/Reference/Inspiration classification,
- context/prompt inspection,
- export/import.

## 100. Strongly Preferred V1 UX

- streaming narration,
- collapsible state panel,
- direct entity inspector,
- token usage display,
- hidden-state inspector,
- knowledge retrieval provenance,
- clear local-only status.

## 101. Future UX

Not required for v1:

- branch tree,
- discarded-history recovery,
- story comparison,
- automatic media generation,
- video editor,
- voice management,
- multi-user collaboration,
- mobile-first UI.

## 102. UX Acceptance Scenarios

### Scenario A — Normal Play

User:
1. opens campaign,
2. reads transcript,
3. enters action,
4. receives narration,
5. continues.

No advanced panel interaction required.

### Scenario B — Bad Narrator Response

User:
1. clicks Retry,
2. views Take 2,
3. flips back to Take 1,
4. selects preferred take,
5. continues.

No branch terminology shown.

### Scenario C — User Mistake

User:
1. clicks Undo twice,
2. enters different action,
3. continues.

Old future disappears from active transcript but is retained internally.

### Scenario D — Major Decision

User:
1. clicks Save Point,
2. names it,
3. continues,
4. later restores it.

Later history is retained but inactive.

### Scenario E — Continuity Bug

User:
1. notices wrong state,
2. opens State,
3. corrects fact,
4. future narration respects correction.

### Scenario F — Strange Narration

User:
1. opens Inspect Context,
2. sees retrieved memory/reference,
3. identifies bad source,
4. disables/corrects it.

## 103. Phase 0B UX Findings Applied

Phase 0B closed the fork-level UX questions:

- AI-DnD provides the browser shell and prompt/Insights foundation worth retaining.
- Its tree/history complexity can be hidden behind a simple head-cursor Undo/Redo model.
- The frontend needs an explicit Redo control and Save Point workflow.
- RPG-specific presentation must be removed/generalized.
- Open Dungeon remains the stronger visual reference for a focused story-reading experience and future inline media, but its UI is not directly portable and is coupled to destructive history assumptions.
- ai-adventure contributes state/checkpoint concepts rather than browser components.
- the input area should reserve a future local STT affordance, but transcription remains editable draft input and is not implemented in v1.

## 104. Selected UX Direction

Build the browser experience around one uncluttered story screen:

```text
STORY FIRST
```

with advanced capabilities available one layer deeper:

```text
State
Knowledge
Context
Save Points
Settings
```

The user should be able to play for an hour without seeing a branch graph, database concept, embedding control, or developer diagnostic.

When something goes wrong, the system must make state, provenance, and context inspectable enough to explain and correct it.