Jesse.Markowitz/interactive-story
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
480414efe082a4bfe0600a19fe23961f6bddd925
interactive-story/planning/BROWSER-UX-SPEC.md
T
JesseMarkowitzandClaude Opus 5 480414efe0 M7: a first-class imported knowledge library 
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
2026-09-06 15:40:13 -04:00

1544 lines
26 KiB
Markdown
Raw Blame History

# Adventure Storyteller — Browser UX Specification
**Status:** v1.0 UX target — selected base is AI-DnD
**Purpose:** Define the browser-based user experience for v1, including primary storytelling flow, history controls, campaign management, state inspection, imported knowledge, prompt inspection, and future media extension points.
## 1. UX Goal
The application should feel like a focused local interactive-story workspace, not a developer console and not a complicated RPG dashboard.
The main screen should optimize for:
- reading the story,
- entering the next action,
- correcting mistakes,
- retrying narration,
- saving checkpoints,
- understanding what the system currently believes.
The core rule is:
> Advanced state, memory, provenance, and branch mechanics should be available without dominating the normal storytelling experience.
## 2. Primary User Mental Model
The user should think in terms of:
```text
Story
Current situation
What I do next
Undo / Redo
Retry
Save point
```
The user should not need to think in terms of:
```text
branch IDs
node graphs
database rows
embedding vectors
context windows
state event logs
```
Those may exist internally or in advanced diagnostics.
## 3. Browser-First Requirement
v1 should be fully usable through a local browser.
The command line may be used for:
- installation,
- startup,
- troubleshooting.
It should not be required for normal story creation/play.
## 4. Default Layout
Recommended desktop layout:
```text
+-------------------------------------------------------------+
| Campaign title Model/status Settings |
+-------------------------+-----------------------------------+
| | |
| Story Transcript | Context / State Panel |
| | |
| | |
| | |
| | |
+-------------------------+-----------------------------------+
| Undo Redo Retry Save Point |
+-------------------------------------------------------------+
| [ Story input ............................................ ] |
| [ Send ] |
+-------------------------------------------------------------+
```
The right panel should be collapsible.
## 5. Responsive Behavior
Primary target:
- desktop/laptop browser.
Secondary:
- tablet.
Mobile support is optional for v1.
On narrower screens:
- collapse side panel,
- move diagnostics to drawers/tabs,
- keep story input and history controls always accessible.
## 6. Main Story Transcript
The transcript is the primary surface.
Each accepted turn should visually distinguish:
- user input,
- narrator response.
Optional metadata may be hidden by default:
- turn number,
- timestamp,
- model name,
- token count.
## 7. Transcript Ordering
Show only the active story lineage in the normal transcript.
Do not show:
- abandoned/disposable history,
- inactive retry takes,
- alternate branch trees
unless the user explicitly opens a history/retry control.
## 8. Current Story Head
The current endpoint should be clear.
The input box always continues from the currently active story head.
## 9. User Turn Presentation
User messages should support:
- edit,
- optional copy,
- optional inspect turn context.
Editing an older user turn should trigger the defined non-destructive history behavior.
## 10. Narrator Turn Presentation
Narrator messages should support:
- Retry,
- Edit,
- Copy,
- Inspect Context,
- optional media action later.
## 11. Story Input Box
The input box should support free-form natural language.
The layout should reserve space for a future local speech-to-text control, such as a microphone/dictation button, without requiring STT in v1.
Examples:
```text
I enter the tavern.
```
```text
I ask Mara whether she has seen Edrin.
```
```text
I wait quietly and watch the room.
```
## 12. Input Modes
Preferred v1 approach:
One natural-language input field.
Do not require separate rigid modes such as:
- Action,
- Speech,
- Story,
- Command
unless inherited UI makes them useful without complexity.
Optional helpers may exist.
## 13. Out-of-Character Direction
The user should have a way to provide story-direction instructions.
Possible UX:
```text
[ ] Treat as story direction
```
or a small mode selector:
```text
Story Action | Direction
```
Example:
```text
Keep this scene tense, but do not start a fight yet.
```
The UI should make clear that this is not protagonist dialogue.
## 14. Send / Generate
Submitting input should:
1. persist user intent safely,
2. build context,
3. call local Ollama,
4. stream or display narrator output,
5. validate/commit resulting state.
## 15. Streaming
Streaming narrator text is strongly preferred.
Benefits:
- perceived responsiveness,
- natural reading experience.
If streaming complicates atomic state acceptance, narration may stream visually while final state commit occurs afterward.
## 16. Generation State
While generating, show clear state:
```text
Narrating...
```
Controls:
- Stop generation if practical,
- do not accept another conflicting story input until current generation resolves.
## 17. Failed Generation
On failure:
Show:
```text
Generation failed.
[Retry]
```
Do not insert a broken/partial accepted turn.
If partial streamed text exists:
- label it uncommitted,
- discard or allow manual recovery according to implementation.
## 18. Undo Control
Undo should be always accessible near input/history controls.
Behavior:
- one click = one accepted story step backward.
No branch terminology.
## 19. Redo Control
Redo should appear next to Undo.
Disable it when:
- no redo path exists,
- a new continuation invalidated ordinary redo.
## 20. Retry Control
Retry should be attached to the latest narrator response and optionally in the global control row.
Meaning:
```text
Generate another narrator response to the same user input.
```
## 21. Retry Takes
When more than one narrator take exists, show a compact control such as:
```text
Take 2 of 3 < Previous Next >
```
Do not show a branch tree.
## 22. Retry Selection
Selecting a take should update the visible narrator response for that turn.
Before continuing:
- user may move among takes.
Once a next turn is accepted:
- non-selected takes remain retained/disposable.
## 23. Checkpoint Control
Primary action:
```text
Save Point
```
or:
```text
Checkpoint
```
Preferred user-facing label:
```text
Save Point
```
Reason:
- more intuitive than technical "checkpoint."
Internal documentation may still use checkpoint.
## 24. Save Point Dialog
Fields:
```text
Name:
[ Before entering the abbey ]
[Save]
```
Optional:
- note.
Default name suggestion may use:
- current scene,
- turn number.
## 25. Save Point List
Accessible from:
- campaign sidebar,
- top menu,
- dedicated Save Points panel.
Each entry:
```text
Before entering the abbey
Moment 42
[Restore] [Rename] [Delete]
```
**Moment, not Turn.** M4 closeout ruled in favour of the implemented product:
the branch panel and the tree overlay already count in moments (`forked at
moment 9`, `ends at moment 40`), so a Save Point list saying "Turn 42" would
make one screen use two words for one thing. This is a vocabulary alignment and
changes no behaviour; the number is unchanged.
## 26. Restore Confirmation
Restoring is non-destructive.
Confirmation should explain:
```text
The story will return to this save point.
Your current later history will be retained but will no longer be active.
```
Buttons:
```text
Restore
Cancel
```
## 27. Delete Save Point
Explicit confirmation.
Clarify:
```text
Deleting this save point does not delete story history.
```
## 28. Editing User Input
Each user turn should have:
```text
Edit
```
On edit:
- inline editor preferred,
- show warning if later history exists.
Suggested message:
```text
Changing this earlier action will create a new continuation.
The current later story will be retained as discarded history.
```
Buttons:
```text
Save and Continue
Cancel
```
## 29. Editing Narrator Text
Narrator turn supports:
```text
Edit
```
This is useful for:
- correcting continuity,
- fixing wording,
- enforcing preferred story direction.
UX should explain that downstream state may be recalculated.
## 30. Manual State Correction
Advanced panel action:
```text
Correct Story State
```
Potential entry points:
- current state inspector,
- fact/entity inspector.
Do not expose raw JSON as the only interface.
## 31. Current State Panel
Collapsible right-side panel.
Suggested sections:
```text
Current Scene
Characters Present
Important Facts
Items
Relationships
Open Threads
```
Keep concise.
## 32. Current Scene Section
Show:
```text
Location
Time / situation
Characters present
Immediate conditions
```
Future:
- scene illustration.
## 33. Character Section
Each character card may show:
```text
Name
Role
Current status
Relationship
Known important facts
```
Optional:
- visual profile.
## 34. Item Section
Show important story-relevant items.
Example:
```text
Silver Key — carried by Aldric
```
## 35. Open Threads
Example:
```text
Find Edrin — Open
Investigate broken-circle symbol — Open
```
The UI should not behave like a quest game unless desired.
Use "Story Threads" rather than "Quests" as generic terminology.
## 36. State Inspector Depth
Default panel:
- concise.
Clicking an entity opens detailed inspector.
This prevents overwhelming the main story screen.
## 37. Detailed Entity Inspector
Potential fields:
```text
Current state
Known facts
Relationships
History
Source/provenance
Visual profile
```
Advanced data may be hidden behind expandable sections.
## 38. Hidden Narrator State
Some campaigns may contain secrets.
Normal player-facing state panel should not reveal narrator-only facts by default.
Provide optional advanced mode:
```text
Show Hidden Story State
```
with clear warning.
## 39. Campaign Sidebar / Menu
Campaign-level actions:
```text
New Campaign
Open Campaign
Campaign Settings
Save Points
Knowledge
Export
Delete Campaign
```
## 40. Campaign Library
Landing screen should list local campaigns.
Each:
```text
Continuity Test
Last played: ...
Current scene: Crooked Lantern
```
Actions:
- Open,
- Export,
- Delete.
## 41. New Campaign Flow
Recommended steps:
```text
1. Name
2. Campaign profile
3. Narrator/style settings
4. Initial canon / setup
5. Optional imported knowledge
6. Start
```
Keep minimal.
## 42. Campaign Profile
Fields may include:
```text
Genre
Subgenre
Tone
Point of View
Narration Length
```
Do not hardcode fantasy-specific setup.
## 43. Narrator Settings
Potential settings:
```text
Model
Temperature
Response length
Style profile
```
Advanced settings should be collapsible.
## 44. Local Model Status
Header/status area should show:
```text
Ollama: Connected
Model: qwen...
```
If unavailable:
```text
Ollama unavailable
```
with local troubleshooting guidance.
## 45. No Cloud Provider UI
v1 should not show:
- OpenAI,
- Anthropic,
- OpenRouter,
- remote provider sign-in.
This supports the local-only mental model.
## 46. Knowledge Panel
Dedicated campaign section:
```text
Knowledge
```
List imported files.
Columns/cards:
```text
Title
Type: Canon / Reference / Inspiration
Enabled
Last updated
```
## 47. Import Knowledge
Action:
```text
Import File
```
Supported v1:
- `.txt`,
- `.md`.
Flow:
1. choose local file,
2. preview,
3. classify,
4. optional title/tags,
5. import.
## 48. Classification UX
Use explicit choices:
```text
Canon
Authoritative truth for this campaign.
Reference
Supporting information; does not establish story truth.
Inspiration
Creative/style influence only.
```
Do not rely on unexplained icons.
## 49. Knowledge Source Detail
Show:
```text
Original filename
Classification
Enabled
Imported date
Tags
Linked entities
Text preview
Chunks
```
Advanced:
- hash,
- indexing metadata.
## 50. Disable Knowledge
Toggle:
```text
Enabled
```
Disabling should be immediate and reversible.
## 51. Delete Knowledge
Explicit confirmation.
Explain:
- source will stop being used,
- historical turns remain unchanged.
## 52. Retrieval Usage
Source detail may show:
```text
Used in 12 narrator turns
```
Clicking could show turn provenance later.
This is useful but not required for initial UI.
### 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:
```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.
### 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:
```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.
Reference in New Issue View Git Blame Copy Permalink