diff --git a/docs/player_gm_ux_redesign_plan.md b/docs/player_gm_ux_redesign_plan.md index 6f4e1c6..1d10640 100644 --- a/docs/player_gm_ux_redesign_plan.md +++ b/docs/player_gm_ux_redesign_plan.md @@ -117,7 +117,7 @@ Show simple information by default. Reveal advanced detail only when the user as ### 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 the raw text and normalized fields in sync. +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 @@ -138,7 +138,7 @@ This layer must contain no importer/debug framing. Accessible to advanced users: - Edit critical cell -- Re-parse from raw text +- Generate from quick parse input - Compare rendered result before and after changes This layer is still user-focused, not developer-focused. @@ -293,7 +293,7 @@ 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 automatic re-parse support. +The edit popup should become a compact result editor with quick parse support. ### Editing goal @@ -303,7 +303,7 @@ A curator should be able to correct a result quickly in a dense popup without gi Show: -- raw cell text +- 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 @@ -318,29 +318,94 @@ Hide from default editing: ### Editor structure -1. Raw text input +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. -### Re-import / re-parse behavior +### OCR source versus quick parse input -When the user edits `RawCellText`: +The app should stop treating OCR-shaped pdf text as the main editing language. -- allow manual re-parse with a clear button -- optionally support debounced auto-parse after input stabilizes +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 -- raw input manually overridden and derived fields generated from raw input or also manually overridden +- 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. @@ -360,7 +425,7 @@ Adding affixes should not require editing raw structured records. - chip labels must use user-facing terminology - the affix legend and effect codes must map cleanly -- the editor should support symbol-driven and numeric affixes +- 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` @@ -437,6 +502,7 @@ Move critical parsing, normalization, and re-parse behavior into a shared assemb 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 @@ -450,7 +516,7 @@ Today the import tool is the authority for generating normalized critical conten A shared assembly would allow the web app to: -- re-parse a single cell from raw text +- 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 @@ -488,15 +554,15 @@ Create a new assembly for critical import/domain transformation logic, for examp ### Web editor workflow after shared parsing 1. User opens a critical cell. -2. The app shows raw text and compact inline edit rows for the visible result. -3. User edits raw text. +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 both raw text and the normalized result. +8. Save persists quick parse input, OCR provenance, and the normalized result. -This is the key UX shift: the system does the import work again at cell scope instead of forcing the curator to manually edit every derived field. +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 @@ -612,6 +678,37 @@ Acceptance criteria: - compact curation remains available - engineering diagnostics remain accessible without defining the normal correction UX +### Phase 6: Friendly quick parse input + +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. @@ -619,10 +716,12 @@ 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 raw text, not persistence internals. +- 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 raw input. +- 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 @@ -653,4 +752,4 @@ Mitigation: ## Recommended Next Step -Implement Phase 5 next. The remaining cleanup is to tighten the boundary between compact curation tools and engineering diagnostics so ordinary correction workflows stay user-facing while deeper diagnostics remain available behind an explicit advanced surface. +Implement Phase 6 next. The current structural gap is the editor input model itself: curators still need a friendly quick parse grammar that treats the first line as prose, all following lines as affix or conditional-affix lines, and comma-separated aliases as the normal typing language instead of OCR-era symbols.