perf(ui): retain shaped report text

docs/research/2026-07-25-slice-h-a1-ui-text-cache.md

@@ -0,0 +1,39 @@
+# Slice H-a1 — retained UI text cache gate
+
+## Problem
+
+`UiText` deliberately asks its `LinesProvider` for current content when it
+draws. Appraisal, character information, and effect details had bound that
+cheap question directly to expensive report construction and word wrapping.
+At uncapped presentation rates, an unchanged visible panel rebuilt strings,
+line lists, and wrapping measurements every frame.
+
+## Implemented ownership
+
+- `UiTextLayoutCache<T>` owns one semantic value and its shaped line
+  projection.
+- A projection is reused while content, width, padding, default color, DAT
+  font, bitmap font, and appraisal font-color palette are unchanged.
+- Appraisal publishes item reports and string fields through caches.
+- Effect selection/enchantment events publish the detail string once.
+- Character information subscribes to the current character's object/property
+  and local-character state. It rebuilds the report on the next draw after an
+  event or after the panel is shown.
+- `UiText.LinesProvider` remains the renderer seam. Dynamic one-line fields are
+  not globally cached and no draw/input behavior changed.
+
+## Gate
+
+- Focused appraisal, character, effects, and cache tests: 43 passed.
+- App Release: 3,779 passed / 3 skipped.
+- Complete Release solution: 8,263 passed / 5 skipped.
+- A 1,000-poll stable-provider test observes zero managed bytes allocated on
+  the calling thread.
+- Tests prove value-equal strings reuse the same line collection, source
+  changes rebuild it, and resize changes reshape without rebuilding the
+  character report.
+- `IndicatorDetailText.Shape` and `ItemAppraisalTextLayout.Shape` no longer sit
+  directly behind an uncached per-frame provider.
+
+The complete build remained warning-free for production projects; the solution
+test build reported the same 16 pre-existing test-project warnings.