acdream/src/AcDream.App/UI/Layout/RowTemplateResolver.cs

namespace AcDream.App.UI.Layout;

/// <summary>
/// Caching row-template resolver for <see cref="UiTemplateListBox"/>
/// consumers whose row COUNT can change across a session (a live roster,
/// not a fixed authored set) — Friends, Squelch, and (Campaign FA slice
/// FA4) Fellowship all resolve their <c>0x64</c> template entries through
/// one instance of this class.
///
/// <para>
/// Originally a private local function inside
/// <see cref="RetailUiRuntime.MountSocialPanel"/> (Campaign FA slice FA3
/// fix-round blast SF-2): the ORIGINAL shape re-ran
/// <c>LayoutImporter.ImportInfos</c> — a full DAT tree walk — under the
/// shared DAT lock on EVERY row, every revision, even while the panel was
/// closed. The fix caches each template id pair's resolved
/// <see cref="ElementInfo"/> tree the FIRST time it is imported and never
/// re-imports for that pair again; <see cref="Resolve"/> still calls
/// <paramref name="build"/> (constructor parameter) on every invocation
/// because each row needs its OWN <see cref="UiElement"/> instance — only
/// the expensive per-row DAT tree WALK is memoized, not the built widget.
/// </para>
///
/// <para>
/// Extracted to its own class in FA4 (carry-forward 2, the FA3 re-review's
/// non-blocking finding: "add a production-resolver test for the new
/// template cache") so this caching behavior is unit-testable against fake
/// <paramref name="importInfos"/>/<paramref name="build"/> delegates — no
/// live DAT access needed to prove the cache actually short-circuits a
/// repeat import. Production callers still take the shared DAT lock
/// AROUND <see cref="Resolve"/> at the call site (see
/// <c>RetailUiRuntime.MountSocialPanel</c>) — this class has no lock of its
/// own, matching the "controller has no DAT dependency of its own" shape
/// every other hermetically-testable page controller in this codebase
/// already follows.
/// </para>
/// </summary>
public sealed class RowTemplateResolver
{
    private readonly Dictionary<(uint LayoutId, uint ElementId), ElementInfo?> _cache = new();
    private readonly Func<uint, uint, ElementInfo?> _importInfos;
    private readonly Func<ElementInfo, UiElement?> _build;

    /// <summary>Number of times <paramref name="importInfos"/> (the constructor
    /// parameter) actually ran — i.e. cache MISSES. Exposed for the
    /// production-resolver conformance test; not used by any production
    /// code path.</summary>
    public int ImportCount { get; private set; }

    public RowTemplateResolver(
        Func<uint, uint, ElementInfo?> importInfos,
        Func<ElementInfo, UiElement?> build)
    {
        _importInfos = importInfos ?? throw new ArgumentNullException(nameof(importInfos));
        _build = build ?? throw new ArgumentNullException(nameof(build));
    }

    /// <summary>Resolves one row template. Null if the (layoutId, elementId)
    /// pair does not import (cached as a miss — a permanently-unresolvable
    /// template is not retried on every call; see the class doc's cache
    /// contract). <see cref="UiTemplateListBox.TemplateResolver"/>'s exact
    /// signature.</summary>
    public UiElement? Resolve(uint templateLayoutId, uint templateElementId)
    {
        var key = (templateLayoutId, templateElementId);
        if (!_cache.TryGetValue(key, out ElementInfo? info))
        {
            info = _importInfos(templateLayoutId, templateElementId);
            _cache[key] = info;
            ImportCount++;
        }
        return info is null ? null : _build(info);
    }

    /// <summary>The cached import half alone — the template's resolved
    /// <see cref="ElementInfo"/> without building a widget. Same cache, same
    /// miss contract as <see cref="Resolve"/>. Consumers that need the
    /// template's AUTHORED shape beyond what the built widget carries (the
    /// map town markers' button-swallowed highlight child + its per-state
    /// property bags — 2026-08-17 morning gate finding 3) read it here
    /// instead of a second cold import.</summary>
    public ElementInfo? ResolveInfo(uint templateLayoutId, uint templateElementId)
    {
        var key = (templateLayoutId, templateElementId);
        if (!_cache.TryGetValue(key, out ElementInfo? info))
        {
            info = _importInfos(templateLayoutId, templateElementId);
            _cache[key] = info;
            ImportCount++;
        }
        return info;
    }
}