# Player And Gamemaster UX Redesign Plan

## Purpose

This document defines a frontend UX direction for the Rolemaster web app with players and gamemasters as the primary audience during play.

The current UI exposes too much implementation detail:

- importer ownership
- tech stack details
- import source details
- SQLite and storage details
- table counts and reference-data counts
- parse/debug fields
- raw JSON artifacts
- technical labels that matter to development but not to play

That information is useful for engineering and data curation, but it is noise during a session. The redesign should make the gameplay outcome the center of the experience and move technical detail behind developer-only tooling.

## Audience Priority

### Primary

- gamemasters resolving attacks and criticals quickly during a session
- players checking the resulting card and consequences without reading import metadata

### Secondary

- curators repairing imported cells

### Tertiary

- developers working on importer/debug workflows

The key design rule is that secondary and tertiary needs must not dominate the primary experience.

## Current UX Problems

The current app structure already shows the main issues.

### Home page

The current landing page in [Home.razor](D:\Code\RolemasterDB\src\RolemasterDb.App\Components\Pages\Home.razor) emphasizes:

- starter dataset wording
- importer-managed wording
- attack table count
- critical table count
- armor type count
- SQLite file name

This is system status, not gameplay guidance.

### Lookup result card

The current lookup card in [CriticalLookupResultCard.razor](D:\Code\RolemasterDB\src\RolemasterDb.App\Components\Shared\CriticalLookupResultCard.razor) exposes:

- table key
- column role
- parse status
- critical family
- source document
- roll band internals
- raw imported cell
- parsed JSON

Only a small subset of that is useful to a player or GM during play.

### Critical tables page

The current tables page in [Tables.razor](D:\Code\RolemasterDB\src\RolemasterDb.App\Components\Pages\Tables.razor) presents the page as an importer authority surface and frames the legend, groups, columns, and full matrix primarily from a data-management perspective.

### Cell editor popup

The current edit dialog in [CriticalCellEditorDialog.razor](D:\Code\RolemasterDB\src\RolemasterDb.App\Components\Shared\CriticalCellEditorDialog.razor) exposes nearly the full persistence model, including internal fields such as:

- `ParseStatus`
- `ParsedJson`
- branch `ConditionJson`
- branch `ParsedJson`
- effect `SourceType`
- raw affix text everywhere

That makes the editor feel like a database inspector instead of a card editor.

### Critical table cell layout

The current cell layout in [CompactCriticalCell.razor](D:\Code\RolemasterDB\src\RolemasterDb.App\Components\Shared\CompactCriticalCell.razor) and [app.css](D:\Code\RolemasterDB\src\RolemasterDb.App\wwwroot\app.css) already pushes affix badges downward with `margin-top: auto`, but branch stacks are not explicitly bottom-aligned as part of the same card layout contract. That weakens visual consistency in dense table rows.

## UX Design Principles

### 1. Gameplay first

The first screenful must answer:

- what happened
- how many hits
- what critical applies
- what effects matter now
- what optional follow-up input is still needed

### 2. Remove technical noise

Do not show implementation details in player/GM flows unless the user has explicitly entered an advanced curation mode.

### 3. Edit the result, not the database row

When a critical cell is edited, the main object is the rendered card the user wants to fix. The underlying import/debug representation should be derived where possible, not manually curated in parallel by default.

### 4. Fastest common action wins

During play, the most common action is a direct resolution flow. The interface should reduce required reading, scrolling, and field-by-field interpretation.

### 5. Progressive disclosure

Show simple information by default. Reveal advanced detail only when the user asks for it.

### 6. Shared parsing logic

The same import interpretation rules should drive the import tool and the web editor. The user should not need to manually keep quick parse input, OCR provenance, and normalized fields in sync.

## Target Information Architecture

The application should separate into three user-facing layers.

### Layer 1: Session tools

Primary navigation for live play:

- Attack lookup
- Critical lookup
- Critical tables

This layer must contain no importer/debug framing.

### Layer 2: Curation tools

Accessible to advanced users:

- Edit critical cell
- Generate from quick parse input
- Compare rendered result before and after changes

This layer is still user-focused, not developer-focused.

### Layer 3: Engineering diagnostics

Hidden from normal users and placed in a separate developer/admin surface:

- parse status
- parsed JSON
- source document internals
- import artifacts
- schema/debug diagnostics

## Proposed UX Direction By Surface

### 1. Landing Page / Main Lookup

Replace the current technically framed hero with a task-first entry point.

### Proposed hero

- title focused on fast resolution during play
- one sentence of instruction
- immediate access to the two main lookup actions

### Remove from the hero and main summary

- tech stack references
- SQLite references
- import source references
- table counts
- importer-managed wording
- starter dataset wording
- reference-data framing

### Proposed attack lookup flow

Fields:

- attack table
- armor type
- attack roll
- enemy db (attack malus)
- optional critical roll

Controls:

- resolve button
- dice button beside attack roll
- dice button beside critical roll

Behavior:

- if attack roll is present and critical roll is empty, stop after attack result
- if a critical is produced and no critical roll is entered, show a prominent next-step prompt
- if critical roll exists, show the full critical card inline

### Proposed direct critical lookup flow

Fields:

- critical table
- column
- optional group, only when required
- critical roll

Controls:

- resolve button
- dice button beside critical roll

Behavior:

- hide irrelevant group controls when the selected table has no groups
- use human-readable labels, not implementation terminology

### 2. Lookup Result Card

The lookup card should become a gameplay card, not a parser inspection panel.

### Keep visible by default

- critical table name
- chosen severity or column label
- group label when relevant
- roll used
- main prose result
- normalized effect chips
- branch cards with conditions and effects

### Remove from default card

- parse status
- critical family
- source document
- column key
- column role
- raw imported cell
- parsed JSON
- roll band implementation details

### Optional advanced disclosure

If advanced users still need provenance, place it behind a collapsed "Technical details" disclosure that is hidden by default and not present in the main lookup flow for ordinary users.

### Visual direction

- result prose should be the dominant element
- effects should scan as chips/badges
- branch cards should read as conditional outcomes, not nested records
- warning and follow-up effects should be grouped by urgency if possible

### 3. Critical Tables Page

The tables browser should support reading and choosing results quickly.

### Reframe the page

Current framing centers imported data. The new framing should center reading the table during play and correcting a result when necessary.

### Page goals

- pick a table quickly
- scan a row and column intersection quickly
- open a clean card editor when correction is needed

### Remove or demote

- importer authority language
- source-document-first labeling
- any explanation centered on how the data was loaded

### Keep

- table name
- notes only if they help interpret the table in play
- affix legend because it helps users read chip meaning

### Cell layout requirement

`.critical-branch-stack` should be bottom-aligned with `.critical-cell`.

Practical CSS intent:

- make `.critical-cell` a full-height column flex container
- reserve flexible vertical space above branches
- ensure the branch stack sits at the bottom edge of the cell card
- keep affix badges and branch cards visually anchored

This creates a stable reading rhythm across rows with uneven prose length.

### 4. Critical Cell Editing

The edit popup should become a compact result editor with quick parse support.

### Editing goal

A curator should be able to correct a result quickly in a dense popup without giving up space to a separate preview panel.

### Default editor content

Show:

- quick parse input
- one-line result text editing when manual override is needed
- compact inline affix/effect rows with the same badges/icons used in read mode
- compact inline condition rows with their own effect chips

Hide from default editing:

- parse status
- parsed JSON
- condition JSON
- effect source type
- other importer/debug-only properties

### Editor structure

1. Quick parse input
2. Compact inline parsed sections the user can adjust
3. Save actions
4. Optional advanced diagnostics disclosure

There should be no dedicated preview panel in the popup. The edit rows themselves should carry the same affix badges, branch labels, and visible wording that the final result uses.

### OCR source versus quick parse input

The app should stop treating OCR-shaped pdf text as the main editing language.

Two separate sources are needed:

- `OCR source`: the imported pdf text, shown for provenance and troubleshooting
- `Quick parse input`: the curator-facing typed input used for regeneration

`OCR source` should be read-only by default and placed in advanced disclosure. It exists so curators can inspect the imported source when necessary, but they should not be expected to type or repair extravagant OCR symbols such as `π`, `∑`, `∏`, and `∫`.

`Quick parse input` should be the normal text-generation surface.

### Quick parse input grammar

The grammar should be intentionally small and easy to type.

Rules:

- the first line is always the main prose result
- each following line is either a base affix line or a conditional affix line
- affixes on those lines are comma-separated
- a conditional line uses `condition: affix, affix, affix`

Examples:

```text
Foe brings his guard up, frightened by your display.
+5, 1mp
```

```text
Blast arcs through shield rim and into sword arm.
+10, 2s, -15
w/o shield: +15, 3s, 3np, 1hpr, -20, +20b
```

### Friendly affix aliases

The quick parse input should accept friendly aliases instead of OCR symbols.

Examples:

- `+15` for direct hits
- `3s` for stunned 3 rounds
- `3np` for no parry 3 rounds
- `1mp` for must parry 1 round
- `1hpr` for 1 hit per round bleed
- `-20` for foe penalty
- `+20b` for attacker bonus next round

The parser may continue to accept OCR-era symbols as compatibility aliases, but they must not be required in the normal editor workflow.

### Generate behavior

When the user edits `QuickParseInput`:

- allow manual generate with a clear button
- optionally support debounced generation after input stabilizes
- regenerate description, effects, branches, and conditions from shared parser logic
- preserve user edits only where the user explicitly overrode generated values
- surface parser notes in advanced disclosure instead of spending default popup space on them

### No-silent-loss parser rule

The generator must never silently drop recognized content.

Requirements:

- if a token is recognized, the generated card must contain the corresponding effect
- if a token is not recognized, the compare/review workflow must surface that token explicitly
- generated-versus-current comparison must call out dropped or unresolved affix tokens in plain language

This rule is more important than preserving OCR fidelity. A parser that quietly loses `1mp` or `π` is not acceptable for curation.

### Manual override model

A critical result should support two states:

- imported from the pdf
- quick parse input manually overridden and derived fields generated from quick parse input or also manually overridden

This avoids the current problem where re-imports using the tool discards user curations.

### 5. Affix Editing UX

Adding affixes should not require editing raw structured records.

### Proposed interaction

- show each effect as a compact inline row with its affix badge and dropdown
- keep add/remove actions small and local to the row
- let the user choose the effect type from the same row they are editing
- show only the minimum value input needed for that effect type
- update the visible badge and label directly in the row without a separate preview area

### Requirements

- chip labels must use user-facing terminology
- the affix legend and effect codes must map cleanly
- the editor should support friendly alias affixes and numeric affixes
- deleting an affix should be one click from the row
- do not waste space on a redundant title when the dropdown already identifies the effect
- do not show a `Target` field for `direct_hits`
- do not show a `Permanent` checkbox in the default editor
- keep source metadata and internal links out of the default row layout

### 6. Condition And Branch Editing UX

Branch editing should follow the same interaction model as affixes.

### Proposed interaction

- branches render as compact inline condition rows
- include a small add button for `Add condition`
- user selects or types the condition text directly in the row
- user enters optional outcome prose inline
- branch effects are edited with the same compact affix rows used on the base result

### Branch card contents

- condition label
- optional prose outcome
- effect chips

### Remove from default branch editing

- condition JSON
- parsed JSON
- internal branch kind values unless required by the UX

If internal branch kinds remain necessary in the model, map them to friendly labels and keep raw values hidden.

### 7. Dice Button Support

Both lookup flows need an alternative to manual roll entry.

### Automatic Attack Lookup

Add dice buttons beside:

- attack roll input
- critical roll input

### Direct Critical Lookup

Add a dice button beside:

- critical roll input

### Behavior

- clicking the button fills the corresponding input with a random legal value
- for attack roll, use the supported app range
- for critical roll, use `1-100`
- allow reroll without extra confirmation

### UX value

This supports fast table use at the table and removes the need to type known random values manually.

## Shared Import Assembly Direction

The import tool and the web app should stop duplicating or bypassing import logic.

### Goal

Move critical parsing, normalization, and re-parse behavior into a shared assembly consumed by both:

- `RolemasterDb.ImportTool`
- `RolemasterDb.App`

### Candidate shared responsibilities

Based on the current importer structure under [src/RolemasterDb.ImportTool](D:\Code\RolemasterDB\src\RolemasterDb.ImportTool), the shared assembly should own:

- raw cell parsing
- quick parse input parsing
- affix legend interpretation
- affix-to-effect normalization
- branch extraction
- condition key normalization
- parsed artifact creation for a single cell or branch
- validation rules for structurally invalid cells

### Why this matters

Today the import tool is the authority for generating normalized critical content, but the web editor exposes many of the final persisted fields directly. That encourages manual edits to derived data instead of reusing the parser.

A shared assembly would allow the web app to:

- generate a single cell from quick parse input
- regenerate effects and branches consistently with bulk import
- reduce manual entry
- remove most debug/import fields from the user-facing editor

### Proposed architecture

### New shared project

Create a new assembly for critical import/domain transformation logic, for example:

- `src/RolemasterDb.CriticalParsing`

### Move or extract into the shared assembly

- parsing contracts for cell-level input and output
- affix parsing logic
- branch extraction logic
- normalization helpers
- validation logic

### Keep in the import tool

- CLI command surface
- manifest loading
- artifact extraction from PDFs
- batch import orchestration
- artifact writing for diagnostics

### Keep in the app

- HTTP endpoints
- Blazor UI
- persistence orchestration for save/update flows

### Web editor workflow after shared parsing

1. User opens a critical cell.
2. The app shows quick parse input and compact inline edit rows for the visible result.
3. User edits quick parse input.
4. The app calls shared parsing logic for that cell.
5. The parser returns normalized description, affixes, conditions, branches, and validation messages.
6. The UI updates the inline editing rows automatically.
7. The user makes small manual fixes only where generation is insufficient.
8. Save persists quick parse input, OCR provenance, and the normalized result.

This is the key UX shift: the system uses a curator-friendly text grammar at cell scope instead of forcing the curator to either type OCR-era symbols or manually edit every derived field.

## Implemented Foundation

The following groundwork is already implemented in the web app as of March 15, 2026:

- visible technical chrome has been removed from the primary lookup and table flows
- lookup result cards now lead with gameplay outcome instead of parse metadata
- the critical table browser is framed for play use rather than import administration
- critical cells support re-parse from shared parser logic
- advanced diagnostics have been separated from the primary editing flow
- advanced curation now includes a generated-versus-current comparison view for re-parse review
- critical cells now open with quick parse input derived from the imported result instead of requiring OCR-era symbol typing

These changes are real and complete, but they are no longer the active roadmap because the detailed acceptance checklist still has unfinished items.

## Remaining Implementation Phases

### Phase 1: Complete live lookup flow ergonomics

Status:

- implemented in the web app on March 15, 2026

Scope:

- add dice buttons to the attack and direct critical lookup inputs
- support fast reroll without manual typing
- tighten any remaining lookup prompts so a first-time GM can move through the flow without reading extra copy

Acceptance criteria:

- both lookup flows support random roll entry without typing
- the main lookup page fully satisfies the live-play checklist item for random lookup support

### Phase 2: Compact inline cell editor

Status:

- implemented in the web app on March 15, 2026

Scope:

- remove the dedicated preview panel from the critical cell popup
- convert effect editing to dense inline rows with badges/icons and minimal controls
- convert branch editing to the same compact inline model
- remove redundant effect titles and any non-essential controls from the default edit surface

Acceptance criteria:

- the popup spends its space on actual editing rather than preview duplication
- common effect and branch corrections require less scrolling than the current popup
- `direct_hits` has no unused `Target` field in the default editor
- the default editor has no `Permanent` checkbox

### Phase 3: Generated versus overridden state model

Status:

- implemented in the web app on March 15, 2026

Implemented model:

- result-level override flags separate generated description and collection state from manual edits
- effect rows and condition rows carry explicit origin keys plus override markers
- re-parse now merges generated parser output with the current override state instead of replacing the whole editor payload
- saved editor state is persisted so later edit sessions keep the same generated-versus-overridden boundaries

Scope:

- explicitly track which values are parser-generated and which values were manually overridden
- ensure re-parse refreshes generated values without silently discarding intentional edits
- define how save and future import refresh flows respect manual overrides

Acceptance criteria:

- shared parsing can regenerate derived data without clobbering preserved overrides
- the manual override model described in this document is implemented rather than only implied

### Phase 4: Compare and review workflow

Status:

- implemented in the web app on March 15, 2026

Implemented model:

- re-parse now returns the freshly generated parser output alongside the merged editor state
- the editor captures the pre-reparse card as a review baseline before applying the merged state
- advanced curation shows side-by-side cards for the prior edit, the fresh generated parse, and the merged post-reparse result when available
- diff summary chips call out result-text, base-effect, and condition changes without requiring raw JSON inspection

Scope:

- add a clear comparison surface for generated result versus current edited result
- let curators review what changed after re-parse before accepting or keeping overrides
- keep this comparison workflow in advanced curation, not in the primary live-play path

Acceptance criteria:

- curators can inspect generated-versus-current differences without reading raw JSON first
- compare tooling exists for the override workflow described above

### Phase 5: Final tooling boundary cleanup

Scope:

- verify that normal curation mode contains only user-facing correction tools
- move any remaining engineering-only diagnostics into a separate developer or admin surface if they still leak into curation mode
- leave advanced curation available without forcing ordinary users through engineering concepts

Acceptance criteria:

- the primary play flow stays clean
- compact curation remains available
- engineering diagnostics remain accessible without defining the normal correction UX

### Phase 6: Friendly quick parse input

Status:

- implemented in the web app on March 15, 2026

Implemented model:

- the editor now treats quick parse input as the primary generation surface
- existing imported results are translated into quick parse notation on the fly when the editor opens
- the popup shows a supported shorthand legend directly under the quick input field
- generation supports all currently available effect types, including power-point modifiers such as `+2d10-3pp`
- OCR glyph tokens remain accepted as compatibility aliases, but they are no longer the primary editing language

Scope:

- add a dedicated `Quick parse input` field distinct from OCR provenance
- define the first-line prose rule plus affix and conditional-affix follow-up lines
- support comma-separated affix tokens and user-friendly aliases such as `1mp`, `3s`, `3np`, `1hpr`, `-20`, and `+20b`
- keep OCR glyph support only as a backward-compatible parser alias, not the primary typing model

Acceptance criteria:

- a curator can type a valid result without entering `π`, `∑`, `∏`, or `∫`
- the parser accepts the documented first-line-plus-affix-lines grammar
- conditional affixes can be entered with `condition: affix, affix, affix`
- the default editor teaches the friendly grammar instead of relying on symbol lore

### Phase 7: Parser trustworthiness and token review

Scope:

- remove silent-loss behavior from generation
- surface unknown or dropped tokens directly in compare/review
- ensure known affix tokens produce stable effects across re-generation
- add targeted examples and tests for problematic tables such as Arcane Aether

Acceptance criteria:

- a recognized affix token never disappears silently from the generated card
- unknown tokens are shown explicitly to the curator in compare/review
- example regressions such as Arcane Aether B16 are covered by tests

## Detailed Acceptance Checklist

The redesign should be considered successful when all of the following are true.

- A first-time GM can resolve an attack or critical without reading technical copy.
- The main result card shows gameplay consequences without raw JSON or parse details.
- The critical table browser feels usable during a session, not like an import admin screen.
- Editing a critical cell starts from the rendered card and quick parse input, not persistence internals.
- Adding an affix or condition is a small chip-driven action.
- Shared parsing logic can regenerate most derived data from minimal quick parse input.
- Dice buttons support random lookup flows without manual typing.
- A curator can type common affixes without OCR-era symbols.
- The compare workflow makes dropped or unknown tokens explicit.

## Risks And Tradeoffs

### Risk: loss of technical visibility

If technical detail is removed completely, curation becomes harder.

Mitigation:

- move technical detail to an advanced mode, not the primary mode

### Risk: parser and UI divergence

If the web app implements its own light parser, it will drift from the import tool.

Mitigation:

- one shared parsing assembly
- one canonical normalized result contract

### Risk: override complexity

Generated fields and manual overrides can conflict.

Mitigation:

- explicit generated vs overridden state for editable sections

## Recommended Next Step

Implement Phase 7 next. The remaining parser gap is trustworthiness under imperfect input: unknown tokens still need stronger surfaced review, and no-silent-loss behavior should be enforced comprehensively across compare output and regression coverage.