JesseMarkowitzandClaude Opus 5
480414efe0
A campaign can import local .txt and .md files as Canon, Reference or Inspiration, and the class is load-bearing rather than a label: it decides the words a passage is framed with in the prompt, the weight it carries when passages are ranked, and which budget it competes in when the context is tight. This is a separate subsystem, which is the Phase 0B decision (IMPORTED-KNOWLEDGE-DESIGN.md §73). Story Cards do not carry classification, provenance, content identity, chunking, an index or a lifecycle, and they were not promoted into something that does. Nothing here reads or writes one. The subsystem, in backend/app/knowledge/: classes the three classes, their weights, and the prompt framing chunking deterministic, heading-aware, 60-800 tokens, no overlap fts SQLite FTS5 with porter stemming; scoped and bounded in SQL importer validate, hash, store, chunk, index — in one transaction embeddings local Ollama vectors through the shared provider retrieval query construction, hybrid merge, rerank inject the budgeted cut and the rendered prompt sections Relevance admission is a separate stage from ranking, and that separation is the milestone's most expensive lesson. An independent review found the first implementation deciding relevance with a floor expressed as a share of the best candidate — which the best clears by construction — so a passage was admitted on every turn regardless of the scene. A query about tide tables and container tonnage retrieved all five sources of a fantasy campaign, narrator-only hidden Canon among them. So the pipeline is now: candidate generation -> admission -> ranking -> class weighting -> budget Admission reads raw, candidate-set-independent signals: the cosine the model returned, and how many distinct meaningful query terms a passage contains. Ranking reads normalized ones, because bm25 has no fixed range and cosine's zero is not zero. Normalization decides order among things that matched; it can never decide whether anything matched. Authority is applied after admission, so a class orders what matched and never rescues what did not. Retrieval may therefore return nothing, and on a scene unrelated to the library it does. The other decisions that each replaced an obvious wrong one: - The class multiplies relevance rather than adding to it. An additive bonus satisfies "Canon outranks Reference" and makes "do not include irrelevant Canon" impossible, because a large enough constant wins on its own. - The semantic floor is measured, not guessed: 113 production-path pairs against nomic-embed-text put targeted matches at 0.55-0.85 and off-topic pairs at 0.36-0.56, and 0.58 sits between them. Because it is a property of that model and not of cosine similarity, it is keyed to the model rather than applied to whatever is configured: an embedding model with no measured calibration in this build does not borrow the number. Semantic admission is skipped, the campaign retrieves lexically, and the reason is stated in the knowledge status and in the turn's provenance. Degrading to lexical keeps the library usable; lending the threshold to an unmeasured model is how the admitted-everything defect would return. - One lexical term is not evidence. Two distinct meaningful terms, or one that is neither a standing campaign entity nor a negligible share of the query. The stop list grew from 42 words to 261, all function words — no subject matter, because a stop list that removes subject matter stops finding "The Silver Key". - Lexical retrieval is a production path, not a fallback. It finds the proper nouns and invented terms a setting bible is made of, and the library is fully usable with no embedding model configured. Safety is structural rather than filtered. Imported text reaches the prompt whole, inside a section that says what it is, under a rule stating the authority order in words and refusing every instruction inside it. No endpoint accepts a filesystem path, so H08 has no mechanism to escape from. Nothing renders imported content as HTML, so a script tag is five visible characters and a remote image is never fetched. Import, chunking, indexing, retrieval and a turn open no socket at all; only embeddings do, through the endpoint allowlist the memory bank already uses. Provenance is the rendered text, not a foreign key: deleting a source cannot turn a historical turn's evidence into dangling ids. Schema: knowledge_sources, knowledge_chunks, knowledge_embeddings, and an FTS5 virtual table attached to knowledge_chunks as a DDL hook so it is created and dropped with the table it indexes. Migration 92. A pre-M7 database opens unchanged and needs no sources to play. Bundle: the source content and the reader's judgements about it travel; the passages, index rows and vectors are rebuilt on import, so a restored campaign is searchable immediately without a reindex step. One runtime dependency: python-multipart, Starlette's multipart parser. It is what makes the upload surface possible, and the upload surface is why no pathname is ever accepted. The test doubles were the reason the defect shipped, so they were corrected too. The retrieval stub scored unrelated text at 0.06-0.20 where the real model scores it at 0.43-0.44, and its docstring said it had deliberately removed the constant component that "would put a similarity floor under every pair" — which is exactly the property real models have. The stub now has that floor, one test fails if it is ever removed, and another reproduces the superseded rule and asserts it is still fooled by the same fixture. Run against the pre-corrective implementation, the new suite fails 13 of 18. Tests: 939 passed, 14 skipped (836/7 at M6). 110 new across seven files, one of which mocks nothing between itself and Ollama and re-measures the similarity separation on every run. 43/43 checks in a real Firefox, reproduced. Docker build clean. Four other defects found by review or by the browser run were fixed here rather than carried: an unreachable relevance constant that appeared to enforce something and did not; acceptance tests using the wrong fixture files, so G07's trap was never exercised; a bidirectional override surviving into displayed filenames; and, from the implementation pass, the Insights panel showing M5's two state sections as raw keys and the source inspector refetching on every keystroke. M7 was independently reviewed, which returned PASS WITH CORRECTIVE WORK REQUIRED. Both blocking findings are closed, and closeout resolved the embedding-model calibration boundary the corrective pass had left as debt. planning/reports/M7-IMPLEMENTATION-REPORT.md carries the review, the corrective closeout and the closeout verification in sequence, none overwriting another. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017HdaXiFbscatQaLS7dJk6b
26 KiB
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:
- persist user intent safely,
- build context,
- call local Ollama,
- stream or display narrator output,
- 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
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:
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:
- choose local file,
- preview,
- classify,
- optional title/tags,
- 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.
As implemented in M7 (functional, not designed)
The Knowledge panel exists and every M7 behaviour is reachable in a browser without opening the database: import with a class and a narrator-only flag, list with class, enabled, narrator-only, always-include and index/embedding state badges, change the class from a select, toggle enabled and narrator-only, inspect the full source text, inspect every passage with its heading trail and token count, see the original filename, import timestamp, size, passage and embedded counts, parser and chunking versions and the full SHA-256, delete behind a confirmation that explains what deletion does and does not do, and rebuild the derived indexes.
Two things are deliberately not built, and §47's flow is what they come from:
- No preview step before import. The flow is choose, classify, import — the source inspector afterwards is where the text is read. §47 lists a preview; it buys little when the file can be opened immediately after.
- No retrieval-usage count ("Used in 12 narrator turns", §52), which §52 itself marks as not required for initial UI.
M8 owns the design of all of it. What M7 owed was working browser access, and 42 checks in a real Firefox cover it end to end.
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.
As implemented in M7
Each row names the file, the class, the heading trail, the passage number, the
retrieval mode (lexical / semantic / hybrid / always), the lexical and
semantic scores and the combined score, the token cost, a narrator-only badge
where it applies, and the passage text itself. Rows are also shown for passages
that were suppressed as repeating one already chosen, and for passages there
was no budget for, each with the reason — so "why is that not here?" has an
answer rather than a silence.
Click-to-open-source is not implemented; the Knowledge panel is one click away and lists the same file.
The passage text is rendered as a text node in a <pre>, never as markup. That
is where H06 and H07 are decided for imported content, and it is the reason a
Markdown renderer was not added here for appearance.
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:
- opens campaign,
- reads transcript,
- enters action,
- receives narration,
- continues.
No advanced panel interaction required.
Scenario B — Bad Narrator Response
User:
- clicks Retry,
- views Take 2,
- flips back to Take 1,
- selects preferred take,
- continues.
No branch terminology shown.
Scenario C — User Mistake
User:
- clicks Undo twice,
- enters different action,
- continues.
Old future disappears from active transcript but is retained internally.
Scenario D — Major Decision
User:
- clicks Save Point,
- names it,
- continues,
- later restores it.
Later history is retained but inactive.
Scenario E — Continuity Bug
User:
- notices wrong state,
- opens State,
- corrects fact,
- future narration respects correction.
Scenario F — Strange Narration
User:
- opens Inspect Context,
- sees retrieved memory/reference,
- identifies bad source,
- 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.