acdream/src/AcDream.App/UI/SpewBoxController.cs

using System.Numerics;
using AcDream.UI.Abstractions.Panels.SpewBox;

namespace AcDream.App.UI;

/// <summary>
/// Retained presentation of retail's <c>gmSpewBoxUI</c> (research doc
/// §1.1/§7.3/§7.4) — the transient top-of-viewport interface-text queue.
/// Modeled directly on <see cref="PortalWaitNoticeController"/>: a single
/// <c>ClickThrough</c> <see cref="UiText"/> block at a high
/// <see cref="UiElement.ZOrder"/>. Unlike that controller's single
/// overwrite-only slot, this reads <see cref="SpewBoxVM"/>'s bounded,
/// newest-on-top, per-entry-expiring queue every frame.
/// </summary>
/// <remarks>
/// <b>CH2 REJECT-review rework, BLOCKER 1
/// (<c>docs/research/2026-08-09-ch2-review-findings.md</c>):</b> the
/// original landing drove the queue drain from
/// <see cref="UiText.LinesProvider"/>, which <c>UiText.OnDraw</c> only
/// calls when the element is ALREADY <c>Visible</c> — and the element
/// starts invisible, so the provider was never invoked, no line ever drew,
/// and <see cref="SpewBoxState"/>'s pending queue never drained (an
/// unbounded per-session leak). Retail's own <c>gmSpewBoxUI::Update</c>
/// drains off the UI tick (global message 3,
/// <c>UIElementManager::UseTime @0x0045CFD0</c>), not off drawing —
/// <see cref="GlobalTimeSink"/> reproduces that: it is a zero-size child
/// mounted alongside <see cref="_text"/> purely so <see cref="UiRoot"/>'s
/// per-frame <c>BroadcastGlobalUiTime</c> walk reaches it (the same
/// pattern <c>VendorUiController.DragOverGlobalTimeSink</c> uses for
/// <c>gmVendorUI::ListenToGlobalMessage</c>). <see cref="Tick"/> pulls
/// <see cref="SpewBoxVM.Lines"/>, caches the resulting lines, and sets
/// <see cref="_text"/>'s <c>Visible</c> flag; <see cref="UiText.LinesProvider"/>
/// now only ever returns the cache — it is polled by drawing, but no
/// longer double-duties as the tick source, so lines become visible and
/// the queue drains even across a frame where nothing gets drawn (headless,
/// a hidden window, or simply before the first render pass).
/// </remarks>
/// <remarks>
/// <b>Position / font / colour are still PLACEHOLDERS; extent and
/// max-items are now AUTHORED.</b> CH2 REJECT-review rework, NIT 3
/// (<c>docs/research/2026-08-09-ch2-review-findings.md</c>): the task C.7
/// LayoutDesc dump (<c>SpewBoxLayoutDumpDiagnostic</c>) originally searched
/// only <c>dats.Portal</c> — EXHAUSTIVELY, against the entire installed
/// LayoutDesc id range (<c>0x21000000</c>-<c>0x21000075</c>, 101 of 118
/// possible ids populated, sanity-checked against 3 independently-known
/// ids) — and found ZERO elements of class <c>0x10000016</c> there.
/// Extending the identical sweep to <c>dats.Local</c>
/// (<c>client_local_English.dat</c>) found it: LayoutDesc
/// <c>0x21000011</c>, element <c>0x10000048</c> (<c>gmSpewBoxUI</c>),
/// position <c>(0,0)</c> RELATIVE TO ITS PARENT (edge codes
/// <c>leftEdge=3/rightEdge=3</c> — <c>ElementReader.ToAnchors</c>'s own doc
/// comment names 3 as "centered", a mode that projection cannot represent;
/// <c>topEdge=1</c> — top-anchored per that same helper), size
/// <c>450×72</c>, one child (ListBox <c>0x10000049</c>, matching
/// <c>gmSpewBoxUI::PostInit</c>'s <c>GetChildRecursive(0x10000049)</c>
/// verbatim) carrying <c>MaxConcurrentItems</c> (property
/// <c>0x10000028</c>) = <c>4</c>, not retail's code-default <c>1</c>. The
/// PARENT this element mounts under (and therefore the ABSOLUTE screen
/// position) is still unresolved — <c>(0,0)</c> is parent-relative, and the
/// parent is presumably assigned by the same C++ code the research doc's
/// §1.1 describes, not by another LayoutDesc this sweep can walk to. See
/// the divergence register rows this class cites for each remaining
/// placeholder.
/// </remarks>
internal sealed class SpewBoxController : IDisposable
{
    /// <summary>
    /// Register row AP-178 (screen position): retail's authored ABSOLUTE
    /// screen position is still unknown — the LayoutDesc dump (see class
    /// remarks) recovered the element's position as <c>(0,0)</c> relative
    /// to a PARENT this sweep could not identify, so this centered-top
    /// placement remains acdream's own choice, not a resolved retail value.
    /// (The SIBLING row AP-177 — the invented line-lifetime timeout — lives
    /// in <see cref="SpewBoxState.DefaultLifetime"/>'s own doc comment, not
    /// here; this controller does not own that concern.)
    /// </summary>
    private const float TopOffset = 60f;

    /// <summary>
    /// Register row AP-178 (extent): AUTHORED, not a placeholder — the
    /// LayoutDesc dump (see class remarks) found the SpewBox element sized
    /// <c>450×72</c> in <c>dats.Local</c>. Retail's own edge codes
    /// (<c>leftEdge=3</c>/<c>rightEdge=3</c>, "centered" per
    /// <c>ElementReader.ToAnchors</c>'s doc comment) mean the box is a
    /// FIXED-width block horizontally centered in its parent, not a
    /// full-viewport stretch — the constructor below anchors it that way
    /// (a one-time centered <see cref="UiText.Left"/> computed against
    /// <see cref="UiRoot.Width"/>, <see cref="AnchorEdges.Top"/> only) since
    /// <see cref="AnchorEdges"/> has no "centered, fixed-width" flag
    /// combination to express retail's mode 3 directly.
    /// </summary>
    private const float SpewBoxWidth = 450f;
    private const float SpewBoxHeight = 72f;

    /// <summary>
    /// Register row AP-178 (colour): retail's authored colour for THIS
    /// element remains unresolved — the LayoutDesc dump (see class remarks)
    /// found only two direct-state properties on the SpewBox element/ListBox
    /// (a bool at <c>0x3B</c> and the <c>MaxConcurrentItems</c> integer at
    /// <c>0x10000028</c>); no colour property surfaced in that direct-state
    /// dump, and the per-<c>UIStateId</c> <c>States</c> dictionary (hover/
    /// pressed/etc. variants, which could carry it) was not walked this
    /// pass. The chat colour table's <c>0x1A</c> entry
    /// (<c>colorBrightRed</c>) is explicitly NOT this — retail's own
    /// <c>BuildChatColorLookupTable</c> writes to <c>ChatInterface::m_chatLog</c>,
    /// a completely different element tree the SpewBox never touches
    /// (research doc §3.2.3). This warm-yellow placeholder follows the
    /// user's own recollection of the retail SpewBox's colour (unconfirmed
    /// by any decompiled or DAT-authored source) rather than an arbitrary
    /// choice.
    /// </summary>
    private static readonly Vector4 SpewBoxColor = new(1f, 1f, 0.4f, 1f);

    private readonly UiRoot _root;
    private readonly UiText _text;
    private readonly SpewBoxVM _vm;
    private readonly GlobalTimeSink _timeSink;
    private UiText.Line[] _lines = Array.Empty<UiText.Line>();
    private bool _disposed;

    public SpewBoxController(UiRoot root, SpewBoxVM vm)
    {
        _root = root ?? throw new ArgumentNullException(nameof(root));
        _vm = vm ?? throw new ArgumentNullException(nameof(vm));
        _text = new UiText
        {
            Name = "SpewBox",
            // Centered fixed-width block (retail's "mode 3" edge code on
            // both left and right) — see the AP-178 extent comment above.
            Left = (root.Width - SpewBoxWidth) / 2f,
            Top = TopOffset,
            Width = SpewBoxWidth,
            Height = SpewBoxHeight,
            Anchors = AnchorEdges.Top,
            Centered = true,
            // AUTHORED MaxConcurrentItems is 4, not retail's code-default 1
            // (see SpewBoxState.MaxConcurrentItems) — OneLine=true would
            // silently collapse the box back down to showing only the
            // newest of up to 4 concurrent lines.
            OneLine = false,
            ClickThrough = true,
            ZOrder = int.MaxValue,
            DefaultColor = SpewBoxColor,
            Visible = false,
        };
        _text.LinesProvider = () => _lines;
        _root.AddChild(_text);

        _timeSink = new GlobalTimeSink(Tick);
        _root.AddChild(_timeSink);
    }

    /// <summary>
    /// The SpewBox's per-frame tick, driven by <see cref="UiRoot"/>'s
    /// global-message-3 broadcast via <see cref="GlobalTimeSink"/> — the
    /// direct analogue of <c>gmSpewBoxUI::Update</c>. Drains
    /// <see cref="SpewBoxState"/>'s pending queue and prunes expired
    /// entries (see <see cref="SpewBoxVM.Lines"/>), caches the resulting
    /// display lines, and sets <see cref="_text"/>'s visibility. Runs
    /// whether or not a draw pass follows.
    /// </summary>
    /// <param name="nowSeconds">
    /// <see cref="UiRoot"/>'s own per-frame clock — <b>not</b>
    /// <c>Environment.TickCount64</c> — matching every other
    /// <see cref="IUiGlobalTimeListener"/> consumer's time source.
    /// </param>
    private void Tick(double nowSeconds)
    {
        // SpewBoxVM.Lines returns newest-first, matching retail's
        // InsertItem(item, 0) — with OneLine now false and the AUTHORED
        // MaxConcurrentItems == 4 (see SpewBoxState.MaxConcurrentItems),
        // up to 4 lines render, newest on top.
        IReadOnlyList<SpewBoxLine> lines = _vm.Lines(nowSeconds);
        _text.Visible = lines.Count > 0;
        if (lines.Count == 0)
        {
            _lines = Array.Empty<UiText.Line>();
            return;
        }

        var result = new UiText.Line[lines.Count];
        for (int i = 0; i < lines.Count; i++)
            result[i] = new UiText.Line(lines[i].Text, SpewBoxColor);
        _lines = result;
    }

    public void Dispose()
    {
        if (_disposed)
            return;

        _root.RemoveChild(_text);
        _root.RemoveChild(_timeSink);
        _disposed = true;
    }

    /// <summary>
    /// A runtime-only, zero-size, always-invisible-to-hit-testing helper
    /// that opts this controller into retail's global UI message 3 — see
    /// the class remarks and <c>VendorUiController.DragOverGlobalTimeSink</c>
    /// for the identical pattern. <see cref="SpewBoxController"/> is not
    /// itself a <see cref="UiElement"/> (it wraps one), so it cannot
    /// directly implement <see cref="IUiGlobalTimeListener"/> the way
    /// <see cref="UiButton"/> does — <see cref="UiRoot.Tick"/>'s broadcast
    /// walks the ELEMENT tree, not arbitrary controllers.
    /// </summary>
    private sealed class GlobalTimeSink : UiElement, IUiGlobalTimeListener
    {
        private readonly Action<double> _onGlobalUiTime;
        public GlobalTimeSink(Action<double> onGlobalUiTime) => _onGlobalUiTime = onGlobalUiTime;
        public void OnGlobalUiTime(double nowSeconds) => _onGlobalUiTime(nowSeconds);
    }
}