ChangemakerStudios · Jaben · Mar 29, 2026 · Mar 28, 2026 · Mar 28, 2026 · Mar 29, 2026
diff --git a/README.md b/README.md
@@ -529,37 +529,27 @@ public async Task<Stream> FastConversion()
 }
 ```
 
-### Watermark & Rotation
-*Add text watermarks and rotate PDF pages — available on all request types:*
+### Wait For Selector & Emulated Media Features
+*Wait for a DOM element and emulate CSS media features like dark mode:*
 
 ```csharp
-public async Task<Stream> CreateWatermarkedPdf()
+public async Task<Stream> CreateWithChromiumFeatures()
 {
     var builder = new HtmlRequestBuilder()
-        .AddDocument(doc => doc.SetBody("<html><body><h1>Report</h1></body></html>"))
-        .SetWatermarkOptions(w => w.SetTextWatermark("DRAFT", "1-3"))
-        .SetRotationOptions(r => r.SetAngle(90).SetPages("2"))
+        .AddDocument(doc => doc.SetBody("<html><body><div id='app'>Ready</div></body></html>"))
+        .SetConversionBehaviors(b => b
+            .SetWaitForSelector("#app")
+            .AddEmulatedMediaFeature("prefers-color-scheme", "dark")
+            .SetFailOnHttpStatusCodes(499, 599)
+            .FailOnResourceLoadingFailed()
+            .AddIgnoreResourceHttpStatusDomains("cdn.example.com"))
         .WithPageProperties(pp => pp.UseChromeDefaults());
 
     var request = builder.Build();
     return await _sharpClient.HtmlToPdfAsync(request);
 }
 ```
 
-### Split PDFs
-*Split generated PDFs into chunks or extract specific pages:*
-
-```csharp
-public async Task<Stream> SplitPdf()
-{
-    var builder = new HtmlRequestBuilder()
-        .AddDocument(doc => doc.SetBody("<html><body>Multi-page content</body></html>"))
-        .SetSplitOptions(s => s.SplitByPages("1-3,5", unify: true));
-
-    var request = builder.Build();
-    return await _sharpClient.HtmlToPdfAsync(request);
-}
-```
 
 ### Custom Page Properties
 *Fine-tune page dimensions and properties:*

diff --git a/examples/ChromiumFeatures/ChromiumFeatures.csproj b/examples/ChromiumFeatures/ChromiumFeatures.csproj
@@ -0,0 +1,2 @@
+<Project Sdk="Microsoft.NET.Sdk">
+</Project>
diff --git a/examples/ChromiumFeatures/Program.cs b/examples/ChromiumFeatures/Program.cs
@@ -0,0 +1,81 @@
+using Gotenberg.Sharp.API.Client;
+using Gotenberg.Sharp.API.Client.Domain.Builders;
+using Gotenberg.Sharp.API.Client.Domain.Settings;
+using Gotenberg.Sharp.API.Client.Infrastructure.Pipeline;
+
+using Microsoft.Extensions.Configuration;
+
+var config = new ConfigurationBuilder()
+    .SetBasePath(AppContext.BaseDirectory)
+    .AddJsonFile("appsettings.json")
+    .Build();
+
+var options = new GotenbergSharpClientOptions();
+config.GetSection(nameof(GotenbergSharpClient)).Bind(options);
+
+var destinationDirectory = args.Length > 0 ? args[0] : Path.Combine(Directory.GetCurrentDirectory(), "output");
+Directory.CreateDirectory(destinationDirectory);
+
+var path = await CreateWithChromiumFeatures(destinationDirectory, options);
+Console.WriteLine($"PDF created: {path}");
+
+static async Task<string> CreateWithChromiumFeatures(string destinationDirectory, GotenbergSharpClientOptions options)
+{
+    var handler = new HttpClientHandler();
+    HttpMessageHandler effectiveHandler = handler;
+    if (!string.IsNullOrWhiteSpace(options.BasicAuthUsername) && !string.IsNullOrWhiteSpace(options.BasicAuthPassword))
+        effectiveHandler = new BasicAuthHandler(options.BasicAuthUsername, options.BasicAuthPassword) { InnerHandler = handler };
+
+    using var httpClient = new HttpClient(effectiveHandler, disposeHandler: true)
+    {
+        BaseAddress = options.ServiceUrl,
+        Timeout = options.TimeOut
+    };
+
+    var sharpClient = new GotenbergSharpClient(httpClient);
+
+    // Demonstrates waitForSelector, emulated media features, and error handling options
+    var builder = new HtmlRequestBuilder()
+        .AddDocument(doc => doc.SetBody(@"
+            <html>
+            <head>
+                <style>
+                    @media (prefers-color-scheme: dark) {
+                        body { background: #1a1a2e; color: #eee; }
+                    }
+                </style>
+            </head>
+            <body>
+                <div id='content'>
+                    <h1>Chromium Feature Demo</h1>
+                    <p>This PDF was generated with dark mode emulation, waitForSelector,
+                       and strict error handling.</p>
+                </div>
+            </body>
+            </html>"))
+        .SetConversionBehaviors(b => b
+            // Wait for the #content element before converting
+            .SetWaitForSelector("#content")
+            // Emulate dark mode
+            .AddEmulatedMediaFeature("prefers-color-scheme", "dark")
+            // Fail if the main page returns 4xx or 5xx
+            .SetFailOnHttpStatusCodes(499, 599)
+            // Fail if any resource fails to load
+            .FailOnResourceLoadingFailed()
+            // Fail on any console exceptions
+            .FailOnConsoleExceptions()
+            // Ignore CDN domains for status code checks
+            .AddIgnoreResourceHttpStatusDomains("cdn.example.com")
+        )
+        .WithPageProperties(pp => pp.UseChromeDefaults());
+
+    var request = builder.Build();
+    var response = await sharpClient.HtmlToPdfAsync(request);
+
+    var resultPath = Path.Combine(destinationDirectory, $"ChromiumFeatures-{DateTime.Now:yyyyMMddHHmmss}.pdf");
+
+    await using var destinationStream = File.Create(resultPath);
+    await response.CopyToAsync(destinationStream, CancellationToken.None);
+
+    return resultPath;
+}
diff --git a/src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/HtmlConversionBehaviorBuilder.cs b/src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/HtmlConversionBehaviorBuilder.cs
@@ -13,6 +13,8 @@
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
 
+using Gotenberg.Sharp.API.Client.Domain.ValueObjects;
+
 using Newtonsoft.Json.Linq;
 
 namespace Gotenberg.Sharp.API.Client.Domain.Builders.Faceted;
@@ -174,6 +176,171 @@ public HtmlConversionBehaviorBuilder SkipNetworkIdleEvent()
         return this;
     }
 
+    /// <summary>
+    /// Sets a CSS selector to wait for before conversion.
+    /// Chromium will delay conversion until the specified element appears in the DOM.
+    /// </summary>
+    /// <param name="selector">A validated CSS selector.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder SetWaitForSelector(CssSelector selector)
+    {
+        _htmlConversionBehaviors.WaitForSelector = selector ?? throw new ArgumentNullException(nameof(selector));
+
+        return this;
+    }
+
+    /// <summary>
+    /// Sets a CSS selector to wait for before conversion.
+    /// Chromium will delay conversion until the specified element appears in the DOM.
+    /// </summary>
+    /// <param name="selector">A CSS selector string (e.g., "#content", ".loaded").</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder SetWaitForSelector(string selector)
+    {
+        return SetWaitForSelector(CssSelector.Create(selector));
+    }
+
+    /// <summary>
+    /// Adds a CSS media feature override for Chromium rendering.
+    /// </summary>
+    /// <param name="feature">A validated emulated media feature.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder AddEmulatedMediaFeature(EmulatedMediaFeature feature)
+    {
+        if (feature == null) throw new ArgumentNullException(nameof(feature));
+
+        _htmlConversionBehaviors.EmulatedMediaFeatures ??= new List<EmulatedMediaFeature>();
+        _htmlConversionBehaviors.EmulatedMediaFeatures.Add(feature);
+
+        return this;
+    }
+
+    /// <summary>
+    /// Adds a CSS media feature override by name and value.
+    /// </summary>
+    /// <param name="name">CSS media feature name (e.g., "prefers-color-scheme").</param>
+    /// <param name="value">CSS media feature value (e.g., "dark").</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder AddEmulatedMediaFeature(string name, string value)
+    {
+        return AddEmulatedMediaFeature(EmulatedMediaFeature.Create(name, value));
+    }
+
+    /// <summary>
+    /// Sets HTTP status codes that trigger a 409 Conflict when the main page returns them.
+    /// </summary>
+    /// <param name="statusCodes">Validated HTTP status codes.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder SetFailOnHttpStatusCodes(IEnumerable<GotenbergStatusCode> statusCodes)
+    {
+        if (statusCodes == null) throw new ArgumentNullException(nameof(statusCodes));
+
+        var codes = statusCodes.ToList();
+
+        if (codes.Any(c => c == null))
+            throw new ArgumentException("Status codes collection must not contain null elements.", nameof(statusCodes));
+
+        _htmlConversionBehaviors.FailOnHttpStatusCodes = codes;
+
+        return this;
+    }
+
+    /// <summary>
+    /// Sets HTTP status codes that trigger a 409 Conflict when the main page returns them.
+    /// </summary>
+    /// <param name="statusCodes">Raw HTTP status code integers (must be 100-599).</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder SetFailOnHttpStatusCodes(params int[] statusCodes)
+    {
+        if (statusCodes == null) throw new ArgumentNullException(nameof(statusCodes));
+
+        return SetFailOnHttpStatusCodes(statusCodes.Select(GotenbergStatusCode.Create));
+    }
+
+    /// <summary>
+    /// Sets HTTP status codes that trigger a failure when page resources return them.
+    /// </summary>
+    /// <param name="statusCodes">Validated HTTP status codes.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder SetFailOnResourceHttpStatusCodes(IEnumerable<GotenbergStatusCode> statusCodes)
+    {
+        if (statusCodes == null) throw new ArgumentNullException(nameof(statusCodes));
+
+        var codes = statusCodes.ToList();
+
+        if (codes.Any(c => c == null))
+            throw new ArgumentException("Status codes collection must not contain null elements.", nameof(statusCodes));
+
+        _htmlConversionBehaviors.FailOnResourceHttpStatusCodes = codes;
+
+        return this;
+    }
+
+    /// <summary>
+    /// Sets HTTP status codes that trigger a failure when page resources return them.
+    /// </summary>
+    /// <param name="statusCodes">Raw HTTP status code integers (must be 100-599).</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder SetFailOnResourceHttpStatusCodes(params int[] statusCodes)
+    {
+        if (statusCodes == null) throw new ArgumentNullException(nameof(statusCodes));
+
+        return SetFailOnResourceHttpStatusCodes(statusCodes.Select(GotenbergStatusCode.Create));
+    }
+
+    /// <summary>
+    /// Adds a domain to exclude from HTTP status code checks on resources.
+    /// </summary>
+    /// <param name="domain">A validated domain name.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder AddIgnoreResourceHttpStatusDomain(DomainName domain)
+    {
+        if (domain == null) throw new ArgumentNullException(nameof(domain));
+
+        _htmlConversionBehaviors.IgnoreResourceHttpStatusDomains ??= new List<DomainName>();
+        _htmlConversionBehaviors.IgnoreResourceHttpStatusDomains.Add(domain);
+
+        return this;
+    }
+
+    /// <summary>
+    /// Adds a domain to exclude from HTTP status code checks on resources.
+    /// </summary>
+    /// <param name="domain">A domain string (e.g., "cdn.example.com").</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder AddIgnoreResourceHttpStatusDomain(string domain)
+    {
+        return AddIgnoreResourceHttpStatusDomain(DomainName.Create(domain));
+    }
+
+    /// <summary>
+    /// Adds multiple domains to exclude from HTTP status code checks on resources.
+    /// </summary>
+    /// <param name="domains">Domain strings to exclude.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder AddIgnoreResourceHttpStatusDomains(params string[] domains)
+    {
+        if (domains == null) throw new ArgumentNullException(nameof(domains));
+
+        var validated = domains.Select(DomainName.Create).ToList();
+
+        _htmlConversionBehaviors.IgnoreResourceHttpStatusDomains ??= new List<DomainName>();
+        _htmlConversionBehaviors.IgnoreResourceHttpStatusDomains.AddRange(validated);
+
+        return this;
+    }
+
+    /// <summary>
+    /// Tells Gotenberg to return a 409 Conflict if any resource fails to load due to network errors.
+    /// </summary>
+    /// <returns>The builder instance for method chaining.</returns>
+    public HtmlConversionBehaviorBuilder FailOnResourceLoadingFailed()
+    {
+        _htmlConversionBehaviors.FailOnResourceLoadingFailed = true;
+
+        return this;
+    }
+
     /// <summary>
     ///     Sets the format of the resulting PDF document.
     /// </summary>

diff --git a/src/Gotenberg.Sharp.Api.Client/Domain/Requests/Facets/FacetBase.cs b/src/Gotenberg.Sharp.Api.Client/Domain/Requests/Facets/FacetBase.cs
@@ -77,10 +77,15 @@
        return value switch
        {
            PdfFormat format => format.ToFormDataValue(),
            LibrePdfFormats format => format.ToFormDataValue(),
             ConversionPdfFormats format => format.ToFormDataValue(),
             PdfPassword password => password.Value,
             List<Cookie> cookies => JsonConvert.SerializeObject(cookies),
+            List<EmulatedMediaFeature> features => JsonConvert.SerializeObject(
+                features.ToDictionary(f => f.Name, f => f.Value)),
-            List<EmulatedMediaFeature> features => JsonConvert.SerializeObject(
-                features.ToDictionary(f => f.Name, f => f.Value)),
+            List<EmulatedMediaFeature> features => JsonConvert.SerializeObject(features),
-            List<EmulatedMediaFeature> features => JsonConvert.SerializeObject(
-                features.ToDictionary(f => f.Name, f => f.Value)),
+            List<EmulatedMediaFeature> features => JsonConvert.SerializeObject(features),
+            List<GotenbergStatusCode> codes => JsonConvert.SerializeObject(codes.Select(c => c.Value)),
+            List<DomainName> domains => JsonConvert.SerializeObject(domains.Select(d => d.Value)),
+            CssSelector selector => selector.Value,
             OverlaySource overlaySource => overlaySource.ToFormValue(),
             SplitMode splitMode => splitMode.ToFormValue(),
             float f => f.ToString(cultureInfo),

diff --git a/src/Gotenberg.Sharp.Api.Client/Domain/Requests/Facets/HtmlConversionBehaviors.cs b/src/Gotenberg.Sharp.Api.Client/Domain/Requests/Facets/HtmlConversionBehaviors.cs
@@ -13,6 +13,8 @@
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
 
+using Gotenberg.Sharp.API.Client.Domain.ValueObjects;
+
 using Newtonsoft.Json.Linq;
 
 namespace Gotenberg.Sharp.API.Client.Domain.Requests.Facets;
@@ -85,4 +87,44 @@ public class HtmlConversionBehaviors : FacetBase
     /// </summary>
     [MultiFormHeader(Constants.Gotenberg.Chromium.Shared.HtmlConvert.SkipNetworkIdleEvent)]
     public bool? SkipNetworkIdleEvent { get; set; }
+
+    /// <summary>
+    /// CSS selector to wait for before conversion. Delays until the element appears in the DOM.
+    /// </summary>
+    [MultiFormHeader(Constants.Gotenberg.Chromium.Shared.HtmlConvert.WaitForSelector)]
+    public CssSelector? WaitForSelector { get; set; }
+
+    /// <summary>
+    /// Overrides CSS media features (e.g., prefers-color-scheme, prefers-reduced-motion).
+    /// Sent as a JSON array of {name, value} objects.
+    /// </summary>
+    [MultiFormHeader(Constants.Gotenberg.Chromium.Shared.HtmlConvert.EmulatedMediaFeatures)]
+    public List<EmulatedMediaFeature>? EmulatedMediaFeatures { get; set; }
+
+    /// <summary>
+    /// HTTP status codes that trigger a 409 Conflict response from Gotenberg
+    /// when the main page returns a matching code. Default: [499, 599].
+    /// </summary>
+    [MultiFormHeader(Constants.Gotenberg.Chromium.Shared.HtmlConvert.FailOnHttpStatusCodes)]
+    public List<GotenbergStatusCode>? FailOnHttpStatusCodes { get; set; }
+
+    /// <summary>
+    /// HTTP status codes that trigger a failure when page resources (CSS, images, fonts)
+    /// return a matching code.
+    /// </summary>
+    [MultiFormHeader(Constants.Gotenberg.Chromium.Shared.HtmlConvert.FailOnResourceHttpStatusCodes)]
+    public List<GotenbergStatusCode>? FailOnResourceHttpStatusCodes { get; set; }
+
+    /// <summary>
+    /// Domains to exclude from HTTP status code checks on resources.
+    /// Useful for ignoring third-party CDNs or analytics domains.
+    /// </summary>
+    [MultiFormHeader(Constants.Gotenberg.Chromium.Shared.HtmlConvert.IgnoreResourceHttpStatusDomains)]
+    public List<DomainName>? IgnoreResourceHttpStatusDomains { get; set; }
+
+    /// <summary>
+    /// Tells Gotenberg to return a 409 Conflict if any resource fails to load due to network errors.
+    /// </summary>
+    [MultiFormHeader(Constants.Gotenberg.Chromium.Shared.HtmlConvert.FailOnResourceLoadingFailed)]
+    public bool? FailOnResourceLoadingFailed { get; set; }
 }