namespace ZB.MOM.WW.OtOpcUa.Commons.Browsing;

/// <summary>
///     Universal fallback browser: captures any discovery-capable driver's DiscoverAsync
///     output and serves it as a browse session. Resolved by BrowserSessionService only
///     when no bespoke IDriverBrowser matches the driver type (bespoke-first). A separate
///     interface — NOT an IDriverBrowser — because BrowserSessionService indexes those
///     ToDictionary-by-DriverType and the universal browser has no single type.
/// </summary>
public interface IUniversalDriverBrowser
{
    /// <summary>Cheap gate (construct + inspect, no connect): can this driver type + config be
    /// browsed? Never throws. Drives the picker's Browse-button visibility.</summary>
    /// <param name="driverType">The driver type name.</param>
    /// <param name="configJson">The authoring DriverConfig JSON (may be mid-edit / malformed).</param>
    /// <returns>True when a discovery-capable driver can be constructed for this type + config.</returns>
    bool CanBrowse(string driverType, string configJson);

    /// <summary>Construct the driver (with the per-type browse patch), connect, capture one
    /// full discovery pass (with UntilStable settle), shut the driver down (bounded), and
    /// return a session over the captured snapshot. Throws on failure — the caller
    /// (BrowserSessionService) converts to BrowseOpenResult.</summary>
    /// <param name="driverType">The driver type name.</param>
    /// <param name="configJson">The DriverConfig JSON to connect with.</param>
    /// <param name="ct">Cancellation token for the caller's open request.</param>
    /// <returns>A browse session over the captured discovery snapshot.</returns>
    Task<IBrowseSession> OpenAsync(string driverType, string configJson, CancellationToken ct);
}