Add missing Chromium form fields with DDD value objects

Add waitForSelector, emulatedMediaFeatures, failOnHttpStatusCodes,
failOnResourceHttpStatusCodes, ignoreResourceHttpStatusDomains, and
failOnResourceLoadingFailed to HtmlConversionBehaviors facet.

Introduce validated DDD value objects (CssSelector, EmulatedMediaFeature,
HttpStatusCode, DomainName) to prevent primitive obsession and enforce
domain constraints at construction time. Serialization to Gotenberg's
wire format is handled internally by FacetBase.

Author: Jaben

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,155 @@ 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<HttpStatusCode> statusCodes)
+    {
+        if (statusCodes == null) throw new ArgumentNullException(nameof(statusCodes));
+
+        _htmlConversionBehaviors.FailOnHttpStatusCodes = statusCodes.ToList();
+
+        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)
+    {
+        return SetFailOnHttpStatusCodes(statusCodes.Select(HttpStatusCode.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<HttpStatusCode> statusCodes)
+    {
+        if (statusCodes == null) throw new ArgumentNullException(nameof(statusCodes));
+
+        _htmlConversionBehaviors.FailOnResourceHttpStatusCodes = statusCodes.ToList();
+
+        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)
+    {
+        return SetFailOnResourceHttpStatusCodes(statusCodes.Select(HttpStatusCode.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)
+    {
+        foreach (var domain in domains)
+        {
+            AddIgnoreResourceHttpStatusDomain(domain);
+        }
+
+        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>

src/Gotenberg.Sharp.Api.Client/Domain/Requests/Facets/FacetBase.cs

@@ -15,6 +15,8 @@
 
 using System.Globalization;
 
+using Gotenberg.Sharp.API.Client.Domain.ValueObjects;
+
 namespace Gotenberg.Sharp.API.Client.Domain.Requests.Facets;
 
 public abstract class FacetBase : IConvertToHttpContent
@@ -78,6 +80,11 @@ public virtual IEnumerable<HttpContent> ToHttpContent()
             LibrePdfFormats format => format.ToFormDataValue(),
             ConversionPdfFormats format => format.ToFormDataValue(),
             List<Cookie> cookies => JsonConvert.SerializeObject(cookies),
+            List<EmulatedMediaFeature> features => JsonConvert.SerializeObject(
+                features.ToDictionary(f => f.Name, f => f.Value)),
+            List<HttpStatusCode> codes => JsonConvert.SerializeObject(codes.Select(c => c.Value)),
+            List<DomainName> domains => JsonConvert.SerializeObject(domains.Select(d => d.Value)),
+            CssSelector selector => selector.Value,
             float f => f.ToString(cultureInfo),
             double d => d.ToString(cultureInfo),
             decimal c => c.ToString(cultureInfo),

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<HttpStatusCode>? 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<HttpStatusCode>? 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; }
 }

src/Gotenberg.Sharp.Api.Client/Domain/ValueObjects/CssSelector.cs

@@ -0,0 +1,57 @@
+// Copyright 2019-2026 Chris Mohan, Jaben Cargman
+//  and GotenbergSharpApiClient Contributors
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+
+namespace Gotenberg.Sharp.API.Client.Domain.ValueObjects;
+
+/// <summary>
+/// Represents a validated CSS selector string used by Chromium's waitForSelector feature.
+/// Delays conversion until the specified element appears in the DOM.
+/// </summary>
+public sealed class CssSelector : IEquatable<CssSelector>
+{
+    public string Value { get; }
+
+    private CssSelector(string value)
+    {
+        Value = value;
+    }
+
+    /// <summary>
+    /// Creates a new CssSelector from the given string.
+    /// </summary>
+    /// <param name="selector">A non-empty CSS selector string (e.g., "#content", ".loaded", "[data-ready]").</param>
+    /// <exception cref="ArgumentException">Thrown when the selector is null or whitespace.</exception>
+    public static CssSelector Create(string selector)
+    {
+        if (string.IsNullOrWhiteSpace(selector))
+            throw new ArgumentException("CSS selector must not be null or empty.", nameof(selector));
+
+        return new CssSelector(selector);
+    }
+
+    public override string ToString() => Value;
+
+    public bool Equals(CssSelector? other) => other is not null && Value == other.Value;
+
+    public override bool Equals(object? obj) => Equals(obj as CssSelector);
+
+    public override int GetHashCode() => Value.GetHashCode();
+
+    public static implicit operator string(CssSelector selector) => selector.Value;
+
+    public static bool operator ==(CssSelector? left, CssSelector? right) => Equals(left, right);
+
+    public static bool operator !=(CssSelector? left, CssSelector? right) => !Equals(left, right);
+}

src/Gotenberg.Sharp.Api.Client/Domain/ValueObjects/DomainName.cs

@@ -0,0 +1,58 @@
+// Copyright 2019-2026 Chris Mohan, Jaben Cargman
+//  and GotenbergSharpApiClient Contributors
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+
+namespace Gotenberg.Sharp.API.Client.Domain.ValueObjects;
+
+/// <summary>
+/// Represents a validated domain name used for Gotenberg's ignoreResourceHttpStatusDomains field.
+/// Domains matching this list are excluded from HTTP status code failure checks.
+/// </summary>
+public sealed class DomainName : IEquatable<DomainName>
+{
+    public string Value { get; }
+
+    private DomainName(string value)
+    {
+        Value = value;
+    }
+
+    /// <summary>
+    /// Creates a validated domain name.
+    /// </summary>
+    /// <param name="domain">A non-empty domain string (e.g., "cdn.example.com", "fonts.googleapis.com").</param>
+    /// <exception cref="ArgumentException">Thrown when domain is null or whitespace.</exception>
+    public static DomainName Create(string domain)
+    {
+        if (string.IsNullOrWhiteSpace(domain))
+            throw new ArgumentException("Domain name must not be null or empty.", nameof(domain));
+
+        return new DomainName(domain.Trim());
+    }
+
+    public override string ToString() => Value;
+
+    public bool Equals(DomainName? other) => other is not null
+        && string.Equals(Value, other.Value, StringComparison.OrdinalIgnoreCase);
+
+    public override bool Equals(object? obj) => Equals(obj as DomainName);
+
+    public override int GetHashCode() => StringComparer.OrdinalIgnoreCase.GetHashCode(Value);
+
+    public static implicit operator string(DomainName domain) => domain.Value;
+
+    public static bool operator ==(DomainName? left, DomainName? right) => Equals(left, right);
+
+    public static bool operator !=(DomainName? left, DomainName? right) => !Equals(left, right);
+}