# 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 Turn 42 [Restore] [Rename] [Delete] ``` ## 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.