interactive-story/planning/BROWSER-UX-SPEC.md

# Adventure Storyteller — Browser UX Specification

**Status:** v1.0 UX target — selected base is AI-DnD  
**Purpose:** Define the browser-based user experience for v1, including primary storytelling flow, history controls, campaign management, state inspection, imported knowledge, prompt inspection, and future media extension points.

## 1. UX Goal

The application should feel like a focused local interactive-story workspace, not a developer console and not a complicated RPG dashboard.

The main screen should optimize for:

- reading the story,
- entering the next action,
- correcting mistakes,
- retrying narration,
- saving checkpoints,
- understanding what the system currently believes.

The core rule is:

> Advanced state, memory, provenance, and branch mechanics should be available without dominating the normal storytelling experience.

## 2. Primary User Mental Model

The user should think in terms of:

```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.

### 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`, `head` and
  `depth` stay 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.

## 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.

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

```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.

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

```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 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>`, a `hidden` attribute or a
  `display: none` rule 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:

```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
```

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

```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.

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

```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,
- 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:
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.