#import <UIKit/UIKit.h>
#import <WebKit/WebKit.h>
#if __has_include(<TencentQianWebView/TQWebViewConfig.h>)
#import <TencentQianWebView/TQWebViewConfig.h>
#else
#import "TQWebViewConfig.h"
#endif
#if __has_include(<TencentQianWebView/TQSignCallbacks.h>)
#import <TencentQianWebView/TQSignCallbacks.h>
#else
#import "TQSignCallbacks.h"
#endif

NS_ASSUME_NONNULL_BEGIN

/// SDK 注入句柄。
///
/// - ``detach``: 仅解绑 SDK 注入的 delegate,WKWebView 实例保留可继续使用。
/// - ``detachAndDestroy``: 解绑 SDK 并销毁 WKWebView,释放全部资源。
@interface TQWebViewHandle : NSObject

/// 加载 URL。UA 已在 WKWebViewConfiguration 创建时同步注入,直接加载即可。
- (void)loadURL:(NSURL *)url;

/// 解绑 SDK 注入的 delegate,但**不销毁** WKWebView。
///
/// 适用于客户需要复用同一个 WKWebView 实例的场景(例如解绑后加载其他非签署页面)。
/// 调用后 WKWebView 仍可正常使用,只是不再具备 SDK 能力。
- (void)detach;

/// 解绑 SDK 并销毁 WKWebView,释放全部资源。
///
/// 等价于 ``detach`` + 标准 WKWebView 销毁流程:
/// `stopLoading → loadRequest(about:blank) → removeFromSuperview`。
///
/// 适用于页面退出时一并释放 WKWebView 资源的场景(最常见用法)。
/// 调用后 WKWebView 实例不可再使用。
- (void)detachAndDestroy;

/// 主动触发白屏自检,适合在 host VC 重新可见时调用(`viewDidAppear:`)。
///
/// **覆盖场景**:`<input type="file">` 拍照返回后、系统模态 dismiss 后等。
///
/// **判定规则**:webView.URL 为空或 `about:blank` 且非加载中 → 用最近一次主框架 URL 重新 `loadRequest:`。
/// 已经在加载或 URL 有效 → no-op,幂等可重复调用。
- (void)attemptBlankRecoveryIfNeeded;

- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;

@end


/// **配置模式**:让客户已有 WKWebView 获得 SDK 全部能力。
///
/// **API**:
/// ```objc
/// TQWebViewHandle *handle = [TQWebViewConfigurator applyToWebView:myWebView
///                                                  hostController:self
///                                                          config:cfg
///                                                       callbacks:callbacks];
/// [handle loadURL:url];
/// // 退出页面时:
/// [handle detachAndDestroy];
/// ```
///
/// **幂等性**:对同一 WKWebView 二次 apply 会替换前次 delegate,不堆叠。
/// **chained delegate**:本期暂未保留客户原 delegate;客户应在 apply 之前不要自行赋值。
@interface TQWebViewConfigurator : NSObject

+ (TQWebViewHandle *)applyToWebView:(WKWebView *)webView
                     hostController:(nullable UIViewController *)hostController
                             config:(nullable TQWebViewConfig *)config
                          callbacks:(nullable TQSignCallbacks *)callbacks;

@end

NS_ASSUME_NONNULL_END
