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:

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

The user should not need to think in terms of:

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:

+-------------------------------------------------------------+
| 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:

I enter the tavern.

I ask Mara whether she has seen Edrin.

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:

[ ] Treat as story direction

or a small mode selector:

Story Action | Direction

Example:

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:

Narrating...

Controls:

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

17. Failed Generation

On failure:

Show:

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:

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:

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:

Save Point

or:

Checkpoint

Preferred user-facing label:

Save Point

Reason:

• more intuitive than technical "checkpoint."

Internal documentation may still use checkpoint.

24. Save Point Dialog

Fields:

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:

Before entering the abbey
Turn 42
[Restore] [Rename] [Delete]

26. Restore Confirmation

Restoring is non-destructive.

Confirmation should explain:

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

Buttons:

Restore
Cancel

27. Delete Save Point

Explicit confirmation.

Clarify:

Deleting this save point does not delete story history.

28. Editing User Input

Each user turn should have:

Edit

On edit:

• inline editor preferred,
• show warning if later history exists.

Suggested message:

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

Buttons:

Save and Continue
Cancel

29. Editing Narrator Text

Narrator turn supports:

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:

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:

Current Scene
Characters Present
Important Facts
Items
Relationships
Open Threads

Keep concise.

32. Current Scene Section

Show:

Location
Time / situation
Characters present
Immediate conditions

Future:

• scene illustration.

33. Character Section

Each character card may show:

Name
Role
Current status
Relationship
Known important facts

Optional:

• visual profile.

34. Item Section

Show important story-relevant items.

Example:

Silver Key — carried by Aldric

35. Open Threads

Example:

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:

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:

Show Hidden Story State

with clear warning.

39. Campaign Sidebar / Menu

Campaign-level actions:

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

40. Campaign Library

Landing screen should list local campaigns.

Each:

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

Actions:

• Open,
• Export,
• Delete.

41. New Campaign Flow

Recommended steps:

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:

Genre
Subgenre
Tone
Point of View
Narration Length

Do not hardcode fantasy-specific setup.

43. Narrator Settings

Potential settings:

Model
Temperature
Response length
Style profile

Advanced settings should be collapsible.

44. Local Model Status

Header/status area should show:

Ollama: Connected
Model: qwen...

If unavailable:

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:

Knowledge

List imported files.

Columns/cards:

Title
Type: Canon / Reference / Inspiration
Enabled
Last updated

47. Import Knowledge

Action:

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:

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:

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

Advanced:

• hash,
• indexing metadata.

50. Disable Knowledge

Toggle:

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:

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:

Inspect Context

54. Context Inspector Sections

Recommended:

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:

Rendered Prompt

56. Retrieved Memory Row

Example:

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:

canon.md
Canon
Section: Old Abbey

Click to open source.

58. Prompt Token Usage

Display:

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:

Memories

Functions:

• search,
• inspect,
• disable/correct.

Not required to be part of normal play.

61. Manual Memory Correction

Possible actions:

Disable
Correct
Promote to Canon
Downgrade to Heuristic

Promotion should require explicit user intent.

62. History Diagnostics

Advanced feature:

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:

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:

branch
merge
fork
node
HEAD

Preferred words:

current story
save point
retry take
discarded history
restore

65. Campaign Export

Action:

Export Campaign

Suggested options:

Full Export
Without Media

If media not implemented:

• one full export option is enough.

66. Campaign Import

Landing screen action:

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:

Saved

or:

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:

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

Avoid generic:

Something went wrong

where useful details are available.

72. Technical Detail Toggle

Errors may show:

Show technical details

for local debugging.

73. Security Indicators

Campaign settings should make local mode clear.

Example:

Runtime mode: Local only
Ollama endpoint: 127.0.0.1:11434

74. External Link Warning

If user clicks a URL from story/imported content:

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:

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:

Search Story

Search active transcript and possibly full retained history.

Not essential to initial v1.

79. Keyboard Shortcuts

Potential:

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:

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:

Image generating...

Story interaction remains available.

88. Future Media Gallery

Campaign-level:

Media

Group by:

• scene,
• image/video/audio,
• preferred asset.

89. Future Media Provenance

Asset detail:

Scene
Turn range
Provider
Model
Seed
Prompt
Generation date

90. Future Video UX

Select story range:

Create video from turns 210-215

Then review:

• scene summary,
• action beats,
• provider settings.

Not v1.

91. Future TTS UX

Possible controls:

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:

Dictate

Recommended flow:

[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:

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:

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:

STORY FIRST

with advanced capabilities available one layer deeper:

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.