Pennington.Infrastructure.IHtmlResponseRewriter

namespace Pennington.Infrastructure;

/// A participant in the unified HTML response rewriting pipeline. Multiple rewriters share a single parsed IDocument per response, so the DOM is parsed and serialized exactly once regardless of how many rewriters apply. Consumed by HtmlResponseRewritingProcessor, which is the single IResponseProcessor doing HTML rewriting.
public interface IHtmlResponseRewriter
{
    /// Mutate the shared parsed document. The orchestrator serializes it once after every rewriter has run.
    
Task ApplyAsync(IDocument document, HttpContext context);

    /// Sort order within the HTML rewriting pipeline. Rewriters run in ascending Order. Xref resolution at 10, locale prefixing at 20, base-URL prefixing at 30 — the outside-in order that was previously expressed across separate IResponseProcessors.
    
int Order { get; }

    /// Regex / string pre-pass over the raw HTML before AngleSharp parses it. Exists for constructs that are not valid HTML (such as raw <xref:uid> tags) and therefore must be substituted out before the parser runs. Default: pass-through. Rewriters that only touch the DOM should not override this.
    
Task<string> PreParseAsync(string html, HttpContext context);

    /// Cheap gate checked before parsing. Return false to skip both PreParseAsync and ApplyAsync for this response. If every rewriter returns false, the orchestrator skips parsing entirely.
    
bool ShouldApply(HttpContext context);
}