JesseMarkowitzandClaude Opus 5
144406cd48
The release-validation milestone, and the thing it had to settle first was whether any of the earlier evidence meant what it said. M8 measured a deployment enforcing a 4,096-token input window while the application budgeted 16,384. Every request returned 200. What Ollama does with the excess is drop the oldest tokens, and the oldest tokens here are the system block — the narrator's rules and the campaign canon. A hundred-turn certification against that server would have looked perfect and proved nothing, which is why this milestone could not begin with a hundred turns. So the application asks now. Ollama's window is a property of how a model was loaded rather than of the request — sending num_ctx is accepted, ignored, and worse, reloads the model at the server's own default — so the only honest move is to find out and then tell the truth about it. /api/ps reports what a resident model is being served with, /api/show what an unloaded one will load with, both on the same host inference already uses, through the same endpoint policy and the same TLS trust store. A verified window is a ceiling on the budget; an unverified one leaves the budget alone and is recorded as unverified in the turn's own provenance, so an old turn can be asked afterwards whether it was built against a checked window. There is no third behaviour, and in particular no hard-coded 4,096: a number the server did not say would be right on one machine and wrong on the next. The proof that this is doing something is a campaign whose canon sits at the front of the prompt, 120 turns of history, and a 4,096-token window. The canon is still there afterwards and the oldest history is gone. The same campaign built the old way produces a prompt more than twice the window — the defect, reproduced, so the fix is measured against it rather than asserted. Two defects the validation found on its own, and they are the same defect twice: something was true and nobody was told. A manual state correction of four changes with one bad reference applied three, returned 201, and said nothing — while recording the refusal on the audit row nobody reads. It came to light because the identity diagnostic's own fixture was refused that way and the whole run proceeded on a campaign with no scene, which would have read as a model failure. And the narration-length setting moved no number: brief, medium and long each became one English sentence, while the numeric hint the model actually reads was derived from the global reply cap and said the same thing for all three. Both now say what they did. The other two post-M8 findings are closed as well. The tab said AI D&D, which no document had ever claimed it did not; it says Interactive Story now, with the open campaign first, and the name is the owner's decision rather than a find-and-replace to something narrower than the engine. After an Undo the reader could not tell where they had landed; the control row now ends with "Moment 11 · later story ahead", from the server's own answer, in the word the transcript already uses, with none of head, branch or depth anywhere near it. The identity diagnostic exists and the root cause does not. That campaign was destroyed, so no cause can be established — what M11 owes the finding is something that can classify the next occurrence, and a diagnostic that makes only the judgements a program can honestly make: duplicate keys, shared names, protagonist drift, state and context disagreeing. Whether prose misattributed a line is left to a person reading it beside its prompt, because a regex cannot read dialogue and one that pretended to would produce exactly the confident wrong answer this finding is about. Its detectors are proved to fire against a planted second Alice. Two entities may still share a display name. That was checked first, as the finding asked, and left permitted: a mother and a daughter, or a stranger giving a false name, are ordinary fiction, and refusing them to guard against a model mistake would refuse the wrong thing. What was missing was that it happened silently. It is reported now. Evidence, not inference: a hundred accepted turns against a real narrator with genuine process restarts; a real browser against the built SPA; a container with no network at all; a campaign moved into a data directory that never existed. Each was discarded and re-run whenever the product changed under it, and the runs that were thrown away are listed in the report with the reason, along with ten defects in the harnesses themselves — because a harness that has only ever agreed with itself is not evidence, and two of M8's five harness defects were masking real ones. No dependency was added, removed or upgraded. No acceptance test was retired, relaxed or reclassified. M11 is implemented and verified; it is not accepted, and there is no release tag. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Qyn3oRd4D6pi72nKBG725B
33 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.
8A. The reader must be able to tell where they are (recorded 2026-09-07)
A hands-on session against accepted M8 found the sentence above too weak to hold the behaviour it names. Undo worked correctly, the input box did continue from the active head — so both statements above were satisfied — and the reader still could not tell which point in the story they had moved to.
The requirement, stated so that a working implementation cannot satisfy it while a reader is lost:
After Undo, Redo, a Save Point restore, an edit to an earlier turn, or any other movement of the active story position, the reader should be able to identify where they now are in the visible story — and, where it matters, whether later story remains available ahead of them.
Two constraints on any solution:
- No implementation terminology.
branch,fork,node,headanddepthstay off the reader-facing surface (§38), which is what makes this a presentation problem rather than a labelling one. - It must be observable, not merely inferable from the transcript scrolling, so that a release test can decide it.
No wording is prescribed here, and none is ratified. A lightweight named
position — Moment 8 becoming Moment 7 after an Undo, optionally noting that
later story is available — is one candidate among others. Ownership is M11
release polish; V1-ACCEPTANCE-TESTS.md §P1 records what must be settled before
this can become an acceptance test.
As implemented (M11)
The candidate above, built. A status line sits at the end of the story-control
row and reads Moment 12, gaining · later story ahead whenever the server
says Redo is available:
Continue Retry Undo Redo Save Point Moment 11 · later story ahead
Three properties, because they are what make it answer §8A rather than merely occupy the corner:
- It is the server's answer, not the browser's. The number is the count of
actions on the active line as the server reports it, and "later story ahead"
is
can_redo. A component that decided either for itself would be wrong exactly when it mattered — Undo can reach past the loaded window. - It changes visibly. After an Undo the number decreases and the clause appears; both are asserted, in the component suite and in the browser regression, because a requirement that a working implementation can satisfy while the reader is lost is the requirement §8A replaced.
- It uses no implementation vocabulary (§38): not head, not branch, not
depth.
Momentis the word the transcript already uses for the same thing ("Read the 12 earlier moments"), so it introduces no new concept.
Evidence: frontend/src/m11.test.jsx ("finding B") and the B rows of
tools/m11_browser.py.
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.
As implemented in M8
One field. The inherited Do / Say / Story selector is gone: an action and
a piece of quoted dialogue are both just what the reader wrote, and B01/B02
confirmed against a real narrator that the model reads the quotes without being
told. What survived from Story mode is the direction toggle in §13, which is
deliberately not a fourth mode — it changes who is being spoken to, not what
kind of action is taken.
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.
As implemented in M8
The server groups the state and the panel renders the groups, so the section headings are whatever the campaign has established rather than a fixed list — a campaign with no items shows no Items heading. Nothing is rendered as JSON, and each row offers Correct and, for a fact, That's wrong.
There is no hidden dimension in the narrative state, so there is nothing here to reveal. A secret never enters authoritative state: it lives in a knowledge source marked narrator-only, which the narrator is told not to disclose. M7 verified against a real narrator that the secret stays out of the state document. §38's requirement is met by this panel simply not containing narrator-only information; the surface that must actively withhold it is the context inspector — see §57.
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 Information / Spoilers
Some campaigns contain secrets the narrator knows and the protagonist does not.
The requirement is:
- ordinary State and story surfaces must not expose narrator-only information;
- an advanced inspection surface that can contain hidden Canon or narrator-only context must withhold it by default;
- revealing it requires an explicit, clearly labelled user action;
- the UI must warn that doing so may reveal campaign secrets;
- withheld material must be absent from the rendered DOM, not merely
visually collapsed — a closed
<details>, ahiddenattribute or adisplay: nonerule still leaves the text findable by browser search, by the accessibility tree and by anyone reading the page source; - no second hidden-state store or duplicate representation may be introduced solely to give the UI something to toggle.
Where the secret actually lives (ratified at M8)
This section originally described a Show Hidden Story State control on the
state panel. That named the wrong surface, and M8's review ratified the
correction.
Narrator-only material is not held in the narrative state. It is held in the knowledge/canon system, as a source marked narrator-only, and the narrator is instructed not to disclose it. A secret therefore never enters the state document at all — M7 verified that against a real narrator — so a toggle on the state panel would reveal nothing, and building a hidden-state dimension to give it something to reveal would create exactly the duplicate representation the requirement above forbids.
The surface that genuinely needs protecting is advanced context inspection, because a retrieved narrator-only passage is reachable there. That is where the default-withheld behaviour belongs, and where §57 records it as implemented.
The vocabulary for this is hidden-information inspection — not "hidden-state", which implies a state subsystem that does not exist.
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
As implemented in M8
The M7 panel opened on 11,996 characters of assembled prompt. The M8 panel opens on the same campaign at about 1,400: token usage, then what the narrator read, what the story remembered, the summary, how much history was sent, and what produced it — each collapsible. The assembled prompt is the last section and is closed.
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.
As implemented in M8
Click-to-open-source is implemented: the row carries source_id, and the
filename is a button that opens the Knowledge panel on that source rather than
on the list.
The rows were also rewritten to read rather than to enumerate — found by hybrid · closeness 0.71 · 40 tokens in place of a run of raw scores — and the
class tag is now the same component the Knowledge panel uses, so a class looks
the same wherever a reader meets it.
Narrator-only passage text is withheld by default. This is where §38's hidden-information requirement actually lands: the only place a campaign's secrets are reachable from an ordinary screen is a retrieved passage that was marked narrator-only. The row shows the file, the class and the badge, and the text is replaced by "Hidden — this passage is narrator-only" until the reader ticks a control that says what it will reveal. Turning it on is a preference in that component and nothing else: it changes no retrieval, no prompt and no state.
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,
- spoiler-aware advanced inspection of hidden narrator information,
- 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.