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

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.