ScadaBridge/src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Deployment/DebugView.razor

@page "/deployment/debug-view"
@using ZB.MOM.WW.ScadaBridge.Security
@using ZB.MOM.WW.ScadaBridge.Commons.Entities.Instances
@using ZB.MOM.WW.ScadaBridge.Commons.Entities.Sites
@using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories
@using ZB.MOM.WW.ScadaBridge.Commons.Messages.DebugView
@using ZB.MOM.WW.ScadaBridge.Commons.Messages.Streaming
@using ZB.MOM.WW.ScadaBridge.Commons.Types
@using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums
@using ZB.MOM.WW.ScadaBridge.Communication
@attribute [Authorize(Policy = AuthorizationPolicies.RequireDeployment)]
@inject ITemplateEngineRepository TemplateEngineRepository
@inject ISiteRepository SiteRepository
@inject ZB.MOM.WW.ScadaBridge.CentralUI.Auth.SiteScopeService SiteScope
@inject DebugStreamService DebugStreamService
@inject IJSRuntime JS
@implements IDisposable

<div class="container-fluid mt-3">
    <h4 class="mb-3">Debug View</h4>

    <ToastNotification @ref="_toast" />

    @if (_loading)
    {
        <LoadingSpinner IsLoading="true" />
    }
    else
    {
        @* Status strip — connection state, instance, last snapshot. *@
        <div class="alert alert-light py-2 mb-3 d-flex justify-content-between align-items-center small flex-wrap gap-2">
            <div class="d-flex align-items-center gap-2">
                <strong>
                    @if (_connected)
                    {
                        var inst = _siteInstances.FirstOrDefault(i => i.Id == _selectedInstanceId);
                        @(inst?.UniqueName ?? "Connected")
                    }
                    else
                    {
                        <span class="text-muted">Not connected</span>
                    }
                </strong>
                @if (_connected)
                {
                    <span class="badge bg-success" aria-label="Connection state: Live">
                        <span class="spinner-grow spinner-grow-sm me-1" style="width: 0.5rem; height: 0.5rem;" aria-hidden="true"></span>
                        Live
                    </span>
                }
                else
                {
                    <span class="badge bg-secondary" aria-label="Connection state: Disconnected">Disconnected</span>
                }
            </div>
            <div class="d-flex align-items-center gap-2">
                @if (_snapshot != null)
                {
                    <span class="text-muted">
                        Last snapshot: @_snapshot.SnapshotTimestamp.LocalDateTime.ToString("HH:mm:ss")
                    </span>
                }
                @if (_connected && _connectedFromStorage)
                {
                    <button class="btn btn-outline-secondary btn-sm" @onclick="StartFresh"
                            aria-label="Clear persisted selection and disconnect">Start fresh</button>
                }
            </div>
        </div>

        <div class="row mb-3 g-2">
            <div class="col-md-3">
                <label class="form-label small">Site</label>
                <select class="form-select form-select-sm" data-test="debug-site-select"
                        @bind="_selectedSiteId" @bind:after="LoadInstancesForSite" disabled="@_connected">
                    <option value="0">Select site...</option>
                    @foreach (var site in _sites)
                    {
                        <option value="@site.Id">@site.Name (@site.SiteIdentifier)</option>
                    }
                </select>
            </div>
            <div class="col-md-4">
                <label class="form-label small">Instance</label>
                <InstancePicker Areas="_siteAreas" Instances="_siteInstances"
                                ItemLabel="InstanceLabel"
                                SelectedInstanceId="_selectedInstanceId" SelectedInstanceIdChanged="OnInstancePicked"
                                Disabled="@_connected" DataTestPrefix="debug-instance" />
            </div>
            <div class="col-md-3 d-flex align-items-end gap-2">
                @if (!_connected)
                {
                    <button class="btn btn-primary btn-sm" @onclick="Connect"
                            disabled="@(_selectedInstanceId == 0 || _selectedSiteId == 0 || _connecting)">
                        @if (_connecting) { <span class="spinner-border spinner-border-sm me-1" role="status" aria-label="Connecting"></span> }
                        Connect
                    </button>
                }
                else
                {
                    <button class="btn btn-outline-danger btn-sm" @onclick="Disconnect">Disconnect</button>
                }
            </div>
        </div>

        @if (_connected && _snapshot != null)
        {
            <div class="card">
                @* Tabbed layout — Attributes / Alarms, each a composition tree. *@
                <div class="card-header py-0 px-0">
                    <ul class="nav nav-tabs card-header-tabs mx-2 mt-2" role="tablist">
                        <li class="nav-item" role="presentation">
                            <button type="button" role="tab"
                                    class="nav-link @(_activeTab == "attributes" ? "active" : "")"
                                    data-test="debug-tab-attributes"
                                    aria-selected="@(_activeTab == "attributes" ? "true" : "false")"
                                    @onclick='() => _activeTab = "attributes"'>
                                Attributes
                            </button>
                        </li>
                        <li class="nav-item" role="presentation">
                            <button type="button" role="tab"
                                    class="nav-link @(_activeTab == "alarms" ? "active" : "")"
                                    data-test="debug-tab-alarms"
                                    aria-selected="@(_activeTab == "alarms" ? "true" : "false")"
                                    @onclick='() => _activeTab = "alarms"'>
                                Alarms
                            </button>
                        </li>
                    </ul>
                </div>
                <div class="card-body">
                    @* ── Attributes tab ── *@
                    <div class="@(_activeTab == "attributes" ? "" : "d-none")"
                         data-test="debug-pane-attributes" role="tabpanel">
                        <div class="mb-2">
                            <input type="text" class="form-control form-control-sm"
                                   style="max-width: 280px;"
                                   placeholder="Filter by attribute…"
                                   @bind="_attrFilter" @bind:event="oninput" @bind:after="OnAttrFilterChanged"
                                   aria-label="Filter attributes" />
                        </div>
                        <TreeView TItem="DebugTreeNode" @ref="_attrTree"
                                  Items="AttributeForest"
                                  ChildrenSelector="n => n.Children"
                                  HasChildrenSelector="n => n.HasChildren"
                                  KeySelector="n => n.Key"
                                  InitiallyExpanded="n => true"
                                  StorageKey="debugview.attrTree">
                            <NodeContent Context="node">
                                @if (node.Attribute is not null)
                                {
                                    @* Leaf — one attribute value. *@
                                    <span class="me-2">@node.Segment</span>
                                    <span class="font-monospace me-2"><strong>@ValueFormatter.FormatDisplayValue(node.Attribute.Value)</strong></span>
                                    <span class="badge @GetQualityBadge(node.Attribute.Quality) me-2"
                                          aria-label="@($"Quality: {node.Attribute.Quality}")">@node.Attribute.Quality</span>
                                    <span class="text-muted small"
                                          title="@node.Attribute.Timestamp.LocalDateTime.ToString("HH:mm:ss.fff")">
                                        @node.Attribute.Timestamp.LocalDateTime.ToString("HH:mm:ss")
                                    </span>
                                }
                                else
                                {
                                    @* Branch — composition member. *@
                                    <span class="fw-semibold">@node.Segment</span>
                                    @if (node.HasBadQuality)
                                    {
                                        <span class="badge bg-warning text-dark ms-2"
                                              aria-label="Contains bad-quality attributes"
                                              title="One or more descendant attributes are off-Good quality">⚠ bad quality</span>
                                    }
                                }
                            </NodeContent>
                            <EmptyContent>
                                <div class="text-muted small p-2">No attributes.</div>
                            </EmptyContent>
                        </TreeView>
                    </div>

                    @* ── Alarms tab ── *@
                    <div class="@(_activeTab == "alarms" ? "" : "d-none")"
                         data-test="debug-pane-alarms" role="tabpanel">
                        <div class="mb-2">
                            <input type="text" class="form-control form-control-sm"
                                   style="max-width: 280px;"
                                   placeholder="Filter by alarm…"
                                   @bind="_alarmFilter" @bind:event="oninput" @bind:after="OnAlarmFilterChanged"
                                   aria-label="Filter alarms" />
                        </div>
                        <TreeView TItem="DebugTreeNode" @ref="_alarmTree"
                                  Items="AlarmForest"
                                  ChildrenSelector="n => n.Children"
                                  HasChildrenSelector="n => n.HasChildren"
                                  KeySelector="n => n.Key"
                                  InitiallyExpanded="n => true"
                                  StorageKey="debugview.alarmTree">
                            <NodeContent Context="node">
                                @if (node.Alarm is not null)
                                {
                                    @* Leaf — computed alarm or native condition. *@
                                    <span class="me-2"
                                          title="@BuildAlarmTooltip(node.Alarm)">@node.Segment</span>
                                    @if (!string.IsNullOrEmpty(node.Alarm.Message))
                                    {
                                        <span class="text-info me-1" aria-label="Has operator message">💬</span>
                                    }
                                    <AlarmStateBadges Alarm="node.Alarm" />
                                }
                                else if (node.IsNativeBinding)
                                {
                                    @* Native source binding branch. *@
                                    <span class="fw-semibold me-2">@node.Segment</span>
                                    @if (node.ActiveCount > 0)
                                    {
                                        <span class="badge @GetAlarmStateBadge(node.WorstState)"
                                              aria-label="@($"{node.ActiveCount} active conditions")">@node.ActiveCount active</span>
                                    }
                                    else if (!node.HasChildren)
                                    {
                                        <span class="text-muted small">no active conditions</span>
                                    }
                                }
                                else
                                {
                                    @* Generic composition branch. *@
                                    <span class="fw-semibold me-2">@node.Segment</span>
                                    @if (node.WorstState == AlarmState.Active)
                                    {
                                        <span class="badge bg-danger"
                                              aria-label="@($"{node.ActiveCount} active alarms")">@node.ActiveCount active</span>
                                    }
                                }
                            </NodeContent>
                            <EmptyContent>
                                <div class="text-muted small p-2">No alarms.</div>
                            </EmptyContent>
                        </TreeView>
                    </div>
                </div>
            </div>
        }
        else if (_connected)
        {
            <LoadingSpinner IsLoading="true" Message="Waiting for snapshot..." />
        }
    }
</div>

@code {
    [SupplyParameterFromQuery] public int? SiteId { get; set; }
    [SupplyParameterFromQuery] public int? InstanceId { get; set; }

    private List<Site> _sites = new();
    private List<Instance> _siteInstances = new();

    // The site's areas, backing the InstancePicker's tree. Both lists are REPLACED
    // (never mutated in place) on a site change — the picker compares them by
    // reference and treats a new object as "the site changed".
    private List<Area> _siteAreas = new();
    private int _selectedSiteId;
    private int _selectedInstanceId;
    private bool _loading = true;
    private bool _connected;
    private bool _connecting;
    private bool _connectedFromStorage;

    // Which tab pane is visible — "attributes" (default) or "alarms".
    private string _activeTab = "attributes";

    private DebugViewSnapshot? _snapshot;
    // Keyed dictionaries hold the latest value per attribute/alarm — the
    // current-status source of truth the composition trees are built from.
    private Dictionary<string, AttributeValueChanged> _attributeValues = new();
    private Dictionary<string, AlarmStateChanged> _alarmStates = new();

    // Per-tab name-contains filters.
    private string _attrFilter = string.Empty;
    private string _alarmFilter = string.Empty;

    private TreeView<DebugTreeNode>? _attrTree;
    private TreeView<DebugTreeNode>? _alarmTree;

    // Retained as a named enumeration target for DebugViewStreamRaceTests (reflection-based);
    // not consumed in the Blazor markup — the trees render from AttributeForest/AlarmForest.
    // Still enumerates the live _attributeValues dict on the render thread (CentralUI-021).
    private IReadOnlyList<AttributeValueChanged> FilteredAttributeValues =>
        string.IsNullOrWhiteSpace(_attrFilter)
            ? _attributeValues.Values.OrderBy(a => a.AttributeName).ToList()
            : _attributeValues.Values
                .Where(a => a.AttributeName.Contains(_attrFilter, StringComparison.OrdinalIgnoreCase))
                .OrderBy(a => a.AttributeName)
                .ToList();

    // ── Tree memoization (arch-review WP2.4) ──────────────────────────────────
    // Both forests used to be rebuilt from scratch on EVERY render — and a render
    // fired per streamed event. A busy instance therefore rebuilt two whole
    // composition trees hundreds of times a second, on the circuit's single
    // dispatcher thread. The rebuild now sits behind a version stamp bumped
    // whenever the underlying dictionaries change (a coalesced stream flush,
    // Connect, Disconnect), so an unrelated re-render (tab switch, toast, status
    // strip tick) reuses the forest instead of rebuilding it. Reusing the same
    // instance also lets Blazor skip re-rendering the TreeView subtree entirely.
    //
    // The cached key includes the dictionary Count as well as the version: the
    // trees must never go stale if the dictionaries are populated by some path
    // that forgets to bump the stamp.
    private int _dataVersion;

    private IReadOnlyList<DebugTreeNode>? _attrForestCache;
    private (int Version, int Count, string Filter) _attrForestKey = (-1, -1, string.Empty);

    private IReadOnlyList<DebugTreeNode>? _alarmForestCache;
    private (int Version, int Count, string Filter) _alarmForestKey = (-1, -1, string.Empty);

    /// <summary>Attribute composition forest, rebuilt only when the underlying data or filter changed.</summary>
    private IReadOnlyList<DebugTreeNode> AttributeForest
    {
        get
        {
            var key = (_dataVersion, _attributeValues.Count, _attrFilter);
            if (_attrForestCache is null || _attrForestKey != key)
            {
                _attrForestCache = DebugTreeBuilder.BuildAttributeTree(_attributeValues.Values, _attrFilter);
                _attrForestKey = key;
            }
            return _attrForestCache;
        }
    }

    /// <summary>Alarm composition forest, rebuilt only when the underlying data or filter changed.</summary>
    private IReadOnlyList<DebugTreeNode> AlarmForest
    {
        get
        {
            var key = (_dataVersion, _alarmStates.Count, _alarmFilter);
            if (_alarmForestCache is null || _alarmForestKey != key)
            {
                _alarmForestCache = DebugTreeBuilder.BuildAlarmTree(_alarmStates.Values, _alarmFilter);
                _alarmForestKey = key;
            }
            return _alarmForestCache;
        }
    }

    private DebugStreamSession? _session;

    /// <summary>
    /// Guards the <see cref="_session"/> slot together with <see cref="_disposed"/>
    /// (arch-review 2026-08-19 P6-6). <c>Connect</c> awaits <c>StartStreamAsync</c> for up
    /// to 30s; the circuit can be torn down inside that window, and <c>Dispose</c> may run
    /// on a non-UI thread, so publishing the session and observing disposal must be one
    /// atomic step. Whoever loses the race is the one that stops the stream.
    /// </summary>
    private readonly object _sessionLock = new();

    private ToastNotification _toast = default!;

    private string? _initError;

    // CentralUI-009: the stream callbacks (onEvent/onTerminated) run on an
    // Akka/gRPC thread and capture `this` and `_toast`. Once the component is
    // disposed, an in-flight callback must no-op rather than touch a disposed
    // component (InvokeAsync would throw ObjectDisposedException) or a disposed
    // ToastNotification.
    private volatile bool _disposed;

    protected override async Task OnInitializedAsync()
    {
        try
        {
            // Site scoping (CentralUI-002): a scoped Deployment user may only
            // debug sites they are permitted on.
            _sites = await SiteScope.FilterSitesAsync(await SiteRepository.GetAllSitesAsync());
        }
        catch (Exception ex)
        {
            _initError = $"Failed to load sites: {ex.Message}";
        }
        _loading = false;
    }

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (!firstRender) return;

        if (_initError != null)
        {
            _toast.ShowError(_initError);
            _initError = null;
        }

        if (SiteId is > 0 && InstanceId is > 0)
        {
            _selectedSiteId = SiteId.Value;
            await LoadInstancesForSite();
            if (_siteInstances.Any(i => i.Id == InstanceId.Value))
            {
                _selectedInstanceId = InstanceId.Value;
                await Connect();
            }
            else
            {
                _toast.ShowError("Requested instance is not available for debug streaming.");
            }
            StateHasChanged();
            return;
        }

        var storedSiteId = await JS.InvokeAsync<string>("localStorage.getItem", "debugView.siteId");
        var storedInstanceId = await JS.InvokeAsync<string>("localStorage.getItem", "debugView.instanceId");

        if (!string.IsNullOrEmpty(storedSiteId) && int.TryParse(storedSiteId, out var siteId)
            && !string.IsNullOrEmpty(storedInstanceId) && int.TryParse(storedInstanceId, out var instanceId))
        {
            _selectedSiteId = siteId;
            await LoadInstancesForSite();
            _selectedInstanceId = instanceId;
            _connectedFromStorage = true;
            StateHasChanged();
            await Connect();

            // Auto-reconnect notice — the user didn't initiate this connection.
            var inst = _siteInstances.FirstOrDefault(i => i.Id == instanceId);
            _toast.ShowInfo(
                $"Auto-reconnected to {inst?.UniqueName ?? "instance"} from previous session.",
                autoDismissMs: 8000);
        }
    }

    private async Task LoadInstancesForSite()
    {
        _siteInstances = new();
        _siteAreas = new();
        _selectedInstanceId = 0;
        if (_selectedSiteId == 0) return;
        // Site scoping (CentralUI-002): re-check the claim server-side — a query
        // string or stale localStorage value could name a site outside the grant.
        if (!await SiteScope.IsSiteAllowedAsync(_selectedSiteId))
        {
            _selectedSiteId = 0;
            _toast.ShowError("You are not permitted to debug instances on that site.");
            return;
        }
        try
        {
            _siteInstances = (await TemplateEngineRepository.GetInstancesBySiteIdAsync(_selectedSiteId))
                .Where(i => i.State == InstanceState.Enabled)
                .ToList();
            _siteAreas = (await TemplateEngineRepository.GetAreasBySiteIdAsync(_selectedSiteId)).ToList();
        }
        catch (Exception ex)
        {
            _toast.ShowError($"Failed to load instances: {ex.Message}");
        }
    }

    /// <summary>
    /// The label the <c>InstancePicker</c> renders on a row and in its field:
    /// the instance's unique name with its lifecycle state.
    /// </summary>
    /// <param name="instance">The instance to label.</param>
    /// <returns>The display label, e.g. <c>Line1.Mixer (Enabled)</c>.</returns>
    private static string InstanceLabel(Instance instance) =>
        $"{instance.UniqueName} ({instance.State})";

    /// <summary>
    /// Records the instance the operator picked in the <c>InstancePicker</c>.
    /// Everything downstream (the Connect button's enablement, <c>Connect()</c>
    /// itself) reads <c>_selectedInstanceId</c>, so there is nothing else to do.
    /// </summary>
    /// <param name="id">Id of the picked instance.</param>
    private void OnInstancePicked(int id) => _selectedInstanceId = id;

    /// <summary>
    /// When the attribute filter changes, expand the tree so any branches holding
    /// freshly-matched leaves are visible (the builder already prunes non-matches).
    /// </summary>
    private void OnAttrFilterChanged() => _attrTree?.ExpandAll();

    /// <summary>As <see cref="OnAttrFilterChanged"/>, for the alarm tree.</summary>
    private void OnAlarmFilterChanged() => _alarmTree?.ExpandAll();

    private async Task Connect()
    {
        if (_selectedInstanceId == 0 || _selectedSiteId == 0) return;
        _connecting = true;
        try
        {
            var session = await DebugStreamService.StartStreamAsync(
                _selectedInstanceId,
                onEvent: HandleStreamEvent,
                onTerminated: () =>
                {
                    _connected = false;
                    _ = TakeSession();
                    // CentralUI-009: skip the toast/render if already disposed.
                    if (_disposed) return;
                    _ = SafeInvokeAsync(() =>
                    {
                        if (_disposed) return;
                        _toast.ShowError("Debug stream terminated (site disconnected).");
                        StateHasChanged();
                    });
                });

            // M2.11: the site returns InstanceNotFound=true when the instance is
            // not deployed there (e.g. deployment not yet pushed, or wrong site).
            if (session.InitialSnapshot.InstanceNotFound)
            {
                DebugStreamService.StopStream(session.SessionId);
                _toast.ShowError(
                    "Instance not found on the selected site — check the deployment target.");
                _connecting = false;
                return;
            }

            // P6-6: the component may have been disposed while StartStreamAsync was in
            // flight. Dispose() would have found _session still null and stopped nothing,
            // so this session would stay registered in the singleton DebugStreamService —
            // whose keepalive renews registered sessions forever, pinning the site
            // subscription, the bridge actor and this dead circuit until process restart.
            // Publish and re-check disposal atomically so exactly one side tears it down.
            bool abandoned;
            lock (_sessionLock)
            {
                abandoned = _disposed;
                if (!abandoned) _session = session;
            }

            if (abandoned)
            {
                DebugStreamService.StopStream(session.SessionId);
                _connecting = false;
                return;
            }

            // Populate initial state from snapshot
            _attributeValues.Clear();
            foreach (var av in session.InitialSnapshot.AttributeValues)
                _attributeValues[av.AttributeName] = av;

            _alarmStates.Clear();
            foreach (var al in session.InitialSnapshot.AlarmStates)
                _alarmStates[al.AlarmName] = al;

            // Snapshot seeding is a data change like any other — bump the stamp so
            // the memoized forests rebuild from it.
            _dataVersion++;
            _snapshot = session.InitialSnapshot;
            _connected = true;

            // Persist selection to localStorage for auto-reconnect on refresh
            await JS.InvokeVoidAsync("localStorage.setItem", "debugView.siteId", _selectedSiteId.ToString());
            await JS.InvokeVoidAsync("localStorage.setItem", "debugView.instanceId", _selectedInstanceId.ToString());

            var instance = _siteInstances.FirstOrDefault(i => i.Id == _selectedInstanceId);
            _toast.ShowSuccess($"Streaming {instance?.UniqueName ?? "instance"}");
        }
        catch (Exception ex)
        {
            _toast.ShowError($"Connect failed: {ex.Message}");
        }
        _connecting = false;
    }

    /// <summary>
    /// Atomically clears the <see cref="_session"/> slot and returns what was there, so
    /// only the caller that actually took the session stops it (P6-6).
    /// </summary>
    private DebugStreamSession? TakeSession()
    {
        lock (_sessionLock)
        {
            var session = _session;
            _session = null;
            return session;
        }
    }

    private async Task Disconnect()
    {
        var session = TakeSession();
        if (session != null)
        {
            DebugStreamService.StopStream(session.SessionId);
        }

        // Clear persisted selection — user explicitly disconnected
        await JS.InvokeVoidAsync("localStorage.removeItem", "debugView.siteId");
        await JS.InvokeVoidAsync("localStorage.removeItem", "debugView.instanceId");

        _connected = false;
        _connectedFromStorage = false;
        _snapshot = null;
        _attributeValues.Clear();
        _alarmStates.Clear();
        // Drop anything the stream buffered for the session we just tore down, so a
        // late flush can't repopulate a disconnected view.
        _pendingAttributes.Clear();
        _pendingAlarms.Clear();
        _dataVersion++;
    }

    /// <summary>
    /// Disconnect and forget the persisted selection. Surfaces in the status
    /// strip whenever the page auto-reconnects from localStorage so the user
    /// can opt out of the carry-over session.
    /// </summary>
    private async Task StartFresh()
    {
        await Disconnect();
        _selectedSiteId = 0;
        _selectedInstanceId = 0;
        _siteInstances = new();
        _siteAreas = new();
        _toast.ShowInfo("Cleared previous session — select a site and instance to begin.", autoDismissMs: 5000);
    }

    // ── Render coalescing (arch-review WP2.4) ─────────────────────────────────
    // Every streamed event used to marshal onto the dispatcher and call
    // StateHasChanged individually, so a chatty instance drove one full render
    // (and two full tree rebuilds) per value change. Events now land in a
    // thread-safe pending map keyed by name — repeated updates to the same tag
    // inside one window collapse to the latest — and exactly ONE dispatcher
    // marshal per window drains them, bumps the version stamp and renders once.
    private const int RenderCoalesceMs = 250;

    private readonly System.Collections.Concurrent.ConcurrentDictionary<string, AttributeValueChanged> _pendingAttributes = new();
    private readonly System.Collections.Concurrent.ConcurrentDictionary<string, AlarmStateChanged> _pendingAlarms = new();

    /// <summary>0/1 flag: whether a coalesce window is already armed. Interlocked-guarded.</summary>
    private int _flushArmed;

    /// <summary>
    /// Handles one debug-stream event. The callback is invoked on an Akka/gRPC
    /// thread, but <see cref="_attributeValues"/>/<see cref="_alarmStates"/> are
    /// <see cref="Dictionary{TKey,TValue}"/> instances also enumerated by the
    /// render thread (the tree forests + <see cref="FilteredAttributeValues"/> are
    /// built from them). <c>Dictionary</c> is not thread-safe (CentralUI-021): a
    /// write racing an enumeration can throw or corrupt the buckets. The event is
    /// therefore parked in a concurrent pending map here and applied on the
    /// renderer's dispatcher by <see cref="FlushPendingAsync"/>, so every access to
    /// the render dictionaries — read and write — still happens on one thread.
    /// </summary>
    private void HandleStreamEvent(object evt)
    {
        // CentralUI-009: the component may have been disposed while this event
        // was in flight on the Akka/gRPC thread.
        if (_disposed) return;

        switch (evt)
        {
            case AttributeValueChanged av:
                _pendingAttributes[av.AttributeName] = av;
                break;
            case AlarmStateChanged al:
                _pendingAlarms[al.AlarmName] = al;
                break;
            default:
                // Unknown event type — nothing to apply, no render needed.
                return;
        }

        // Arm the window if it isn't already. Losers of the CAS have nothing to do:
        // their event is in the pending map and the armed flush will pick it up.
        if (Interlocked.CompareExchange(ref _flushArmed, 1, 0) == 0)
        {
            _ = FlushPendingAsync();
        }
    }

    /// <summary>
    /// Waits out the coalesce window, then applies everything buffered in one
    /// dispatcher pass and renders once.
    /// </summary>
    private async Task FlushPendingAsync()
    {
        try
        {
            await Task.Delay(RenderCoalesceMs);
        }
        catch
        {
            // Delay never faults in practice; if it ever did, fall through and drain.
        }

        if (_disposed)
        {
            Volatile.Write(ref _flushArmed, 0);
            return;
        }

        await SafeInvokeAsync(() =>
        {
            // Disarm BEFORE draining: an event arriving mid-drain then arms a fresh
            // window rather than being stranded until the next unrelated event.
            Volatile.Write(ref _flushArmed, 0);
            if (_disposed) return;

            var applied = false;
            foreach (var key in _pendingAttributes.Keys)
            {
                if (_pendingAttributes.TryRemove(key, out var av))
                {
                    _attributeValues[av.AttributeName] = av;
                    applied = true;
                }
            }
            foreach (var key in _pendingAlarms.Keys)
            {
                if (_pendingAlarms.TryRemove(key, out var al))
                {
                    _alarmStates[al.AlarmName] = al;
                    applied = true;
                }
            }

            if (!applied) return;

            _dataVersion++;
            StateHasChanged();
        });
    }

    private static string GetQualityBadge(string quality) => quality switch
    {
        "Good" => "bg-success",
        "Bad" => "bg-danger",
        "Uncertain" => "bg-warning text-dark",
        _ => "bg-secondary"
    };

    /// <summary>
    /// State badge class shared by the alarm leaf (via <c>AlarmStateBadges</c>)
    /// and the native/composition branch summary badges below (worst-state roll-up).
    /// </summary>
    private static string GetAlarmStateBadge(AlarmState state) => state switch
    {
        AlarmState.Active => "bg-danger",
        AlarmState.Normal => "bg-success",
        _ => "bg-secondary"
    };

    /// <summary>
    /// Builds the row tooltip from the alarm's operator message plus native
    /// metadata (type, category, operator, raise time, current/limit value).
    /// Returns null when there is nothing extra to show.
    /// </summary>
    private static string? BuildAlarmTooltip(AlarmStateChanged a)
    {
        var parts = new List<string>();
        if (!string.IsNullOrEmpty(a.Message)) parts.Add(a.Message);
        if (!string.IsNullOrEmpty(a.AlarmTypeName)) parts.Add($"Type: {a.AlarmTypeName}");
        if (!string.IsNullOrEmpty(a.Category)) parts.Add($"Category: {a.Category}");
        if (!string.IsNullOrEmpty(a.OperatorUser)) parts.Add($"By: {a.OperatorUser}");
        if (!string.IsNullOrEmpty(a.OperatorComment)) parts.Add($"Comment: {a.OperatorComment}");
        if (a.OriginalRaiseTime.HasValue) parts.Add($"Raised: {a.OriginalRaiseTime.Value.LocalDateTime:HH:mm:ss}");
        if (!string.IsNullOrEmpty(a.CurrentValue)) parts.Add($"Value: {a.CurrentValue}");
        if (!string.IsNullOrEmpty(a.LimitValue)) parts.Add($"Limit: {a.LimitValue}");
        return parts.Count == 0 ? null : string.Join(" · ", parts);
    }

    /// <summary>
    /// Runs <paramref name="action"/> on the render thread, guarded against the
    /// component being disposed mid-flight (CentralUI-009): <c>InvokeAsync</c>
    /// throws <see cref="ObjectDisposedException"/> once the circuit is gone.
    /// </summary>
    private async Task SafeInvokeAsync(Action action)
    {
        if (_disposed) return;
        try
        {
            await InvokeAsync(action);
        }
        catch (ObjectDisposedException)
        {
            // Component disposed between the guard and the dispatch — ignore.
        }
    }

    public void Dispose()
    {
        // CentralUI-009: mark disposed first so any in-flight stream callback
        // sees the flag and no-ops, then stop the stream synchronously.
        // P6-6: the flag is set and the session taken under the same lock Connect
        // publishes through, so a Connect still awaiting StartStreamAsync either
        // hands the session over here or stops it itself — never neither.
        DebugStreamSession? session;
        lock (_sessionLock)
        {
            _disposed = true;
            session = _session;
            _session = null;
        }

        if (session != null)
        {
            DebugStreamService.StopStream(session.SessionId);
        }
    }
}