Reshape BrowserConfiguration API per review (BrowserOptions) while preserving the JS wire format

src/Components/Components/src/PublicAPI.Unshipped.txt

@@ -13,35 +13,3 @@ Microsoft.AspNetCore.Components.IComponentPropertyActivator.GetActivator(System.
 *REMOVED*Microsoft.AspNetCore.Components.Routing.Router.PreferExactMatches.get -> bool
 *REMOVED*Microsoft.AspNetCore.Components.Routing.Router.PreferExactMatches.set -> void
 static Microsoft.Extensions.DependencyInjection.CascadingValueServiceCollectionExtensions.TryAddCascadingValueSupplier<TAttribute>(this Microsoft.Extensions.DependencyInjection.IServiceCollection! serviceCollection, System.Func<System.IServiceProvider!, System.Func<Microsoft.AspNetCore.Components.Rendering.ComponentState!, TAttribute!, Microsoft.AspNetCore.Components.CascadingParameterInfo, Microsoft.AspNetCore.Components.CascadingParameterSubscription!>!>! subscribeFactory) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
-Microsoft.AspNetCore.Components.BrowserConfiguration
-Microsoft.AspNetCore.Components.BrowserConfiguration.BrowserConfiguration() -> void
-Microsoft.AspNetCore.Components.BrowserConfiguration.LogLevel.get -> int?
-Microsoft.AspNetCore.Components.BrowserConfiguration.LogLevel.set -> void
-Microsoft.AspNetCore.Components.BrowserConfiguration.Server.get -> Microsoft.AspNetCore.Components.ServerBrowserOptions!
-Microsoft.AspNetCore.Components.BrowserConfiguration.Server.set -> void
-Microsoft.AspNetCore.Components.BrowserConfiguration.Ssr.get -> Microsoft.AspNetCore.Components.SsrBrowserOptions!
-Microsoft.AspNetCore.Components.BrowserConfiguration.Ssr.set -> void
-Microsoft.AspNetCore.Components.BrowserConfiguration.WebAssembly.get -> Microsoft.AspNetCore.Components.WebAssemblyBrowserOptions!
-Microsoft.AspNetCore.Components.BrowserConfiguration.WebAssembly.set -> void
-Microsoft.AspNetCore.Components.ServerBrowserOptions
-Microsoft.AspNetCore.Components.ServerBrowserOptions.ServerBrowserOptions() -> void
-Microsoft.AspNetCore.Components.ServerBrowserOptions.ReconnectionDialogId.get -> string?
-Microsoft.AspNetCore.Components.ServerBrowserOptions.ReconnectionDialogId.set -> void
-Microsoft.AspNetCore.Components.ServerBrowserOptions.ReconnectionMaxRetries.get -> int?
-Microsoft.AspNetCore.Components.ServerBrowserOptions.ReconnectionMaxRetries.set -> void
-Microsoft.AspNetCore.Components.ServerBrowserOptions.ReconnectionRetryIntervalMilliseconds.get -> int?
-Microsoft.AspNetCore.Components.ServerBrowserOptions.ReconnectionRetryIntervalMilliseconds.set -> void
-Microsoft.AspNetCore.Components.SsrBrowserOptions
-Microsoft.AspNetCore.Components.SsrBrowserOptions.SsrBrowserOptions() -> void
-Microsoft.AspNetCore.Components.SsrBrowserOptions.CircuitInactivityTimeoutMs.get -> int?
-Microsoft.AspNetCore.Components.SsrBrowserOptions.CircuitInactivityTimeoutMs.set -> void
-Microsoft.AspNetCore.Components.SsrBrowserOptions.DisableDomPreservation.get -> bool?
-Microsoft.AspNetCore.Components.SsrBrowserOptions.DisableDomPreservation.set -> void
-Microsoft.AspNetCore.Components.WebAssemblyBrowserOptions
-Microsoft.AspNetCore.Components.WebAssemblyBrowserOptions.WebAssemblyBrowserOptions() -> void
-Microsoft.AspNetCore.Components.WebAssemblyBrowserOptions.ApplicationCulture.get -> string?
-Microsoft.AspNetCore.Components.WebAssemblyBrowserOptions.ApplicationCulture.set -> void
-Microsoft.AspNetCore.Components.WebAssemblyBrowserOptions.EnvironmentName.get -> string?
-Microsoft.AspNetCore.Components.WebAssemblyBrowserOptions.EnvironmentName.set -> void
-Microsoft.AspNetCore.Components.WebAssemblyBrowserOptions.EnvironmentVariables.get -> System.Collections.Generic.Dictionary<string!, string!>!
-Microsoft.AspNetCore.Components.WebAssemblyBrowserOptions.EnvironmentVariables.set -> void

src/Components/Endpoints/src/BrowserConfiguration/BrowserOptions.cs

@@ -0,0 +1,29 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.AspNetCore.Components;
+
+/// <summary>
+/// Options that flow from the server to the Blazor client in the browser
+/// via a DOM comment. Only serializable options are included; callbacks stay
+/// with JS initializers.
+/// </summary>
+public sealed class BrowserOptions
+{
+    /// <summary>
+    /// Gets or sets the log level for the Blazor JS runtime. Applies to all render modes.
+    /// Maps to <c>WebStartOptions.logLevel</c>.
+    /// </summary>
+    public LogLevel? LogLevel { get; set; }
+
+    /// <summary>Gets the WebAssembly-specific options.</summary>
+    public WebAssemblyBrowserOptions WebAssembly { get; } = new();
+
+    /// <summary>Gets the interactive server (circuit) specific options.</summary>
+    public InteractiveServerBrowserOptions Server { get; } = new();
+
+    /// <summary>Gets the SSR-specific options.</summary>
+    public SsrBrowserOptions Ssr { get; } = new();
+}

src/Components/Endpoints/src/BrowserConfiguration/BrowserConfigurationHttpContextExtensions.cs → src/Components/Endpoints/src/BrowserConfiguration/BrowserOptionsHttpContextExtensions.cs

@@ -1,34 +1,36 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-using Microsoft.AspNetCore.Components;
+using Microsoft.AspNetCore.Http;
 
-namespace Microsoft.AspNetCore.Http;
+namespace Microsoft.AspNetCore.Components;
 
 /// <summary>
-/// Extension methods on <see cref="HttpContext"/> for accessing <see cref="BrowserConfiguration"/>.
+/// Extension methods on <see cref="HttpContext"/> for accessing <see cref="BrowserOptions"/>.
 /// </summary>
-public static class BrowserConfigurationHttpContextExtensions
+public static class BrowserOptionsHttpContextExtensions
 {
     private static readonly object Key = new();
 
     /// <summary>
-    /// Gets the <see cref="BrowserConfiguration"/> for the current request.
+    /// Gets the <see cref="BrowserOptions"/> for the current request.
     /// If not already set, seeds from endpoint metadata or creates a new instance.
     /// </summary>
     /// <param name="context">The <see cref="HttpContext"/>.</param>
-    /// <returns>The <see cref="BrowserConfiguration"/> for the current request.</returns>
-    public static BrowserConfiguration GetBrowserConfiguration(this HttpContext context)
+    /// <returns>The <see cref="BrowserOptions"/> for the current request.</returns>
+    public static BrowserOptions GetBrowserOptions(this HttpContext context)
     {
+        ArgumentNullException.ThrowIfNull(context);
+
         if (!context.Items.TryGetValue(Key, out var result))
         {
             // Seed from endpoint metadata if available
-            var metadataConfig = context.GetEndpoint()?.Metadata.GetMetadata<BrowserConfiguration>();
-            var config = metadataConfig ?? new BrowserConfiguration();
+            var metadataConfig = context.GetEndpoint()?.Metadata.GetMetadata<BrowserOptions>();
+            var config = metadataConfig ?? new BrowserOptions();
             context.Items[Key] = config;
             return config;
         }
 
-        return (BrowserConfiguration)result!;
+        return (BrowserOptions)result!;
     }
 }

src/Components/Endpoints/src/BrowserConfiguration/BrowserOptionsJsonConverters.cs

@@ -0,0 +1,48 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.AspNetCore.Components;
+
+// Serializes a nullable <see cref="TimeSpan"/> as whole milliseconds, matching the
+// numeric shape expected by the Blazor JS runtime (e.g. retryIntervalMilliseconds).
+internal sealed class TimeSpanMillisecondsJsonConverter : JsonConverter<TimeSpan?>
+{
+    public override TimeSpan? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        => reader.TokenType is JsonTokenType.Null ? null : TimeSpan.FromMilliseconds(reader.GetDouble());
+
+    public override void Write(Utf8JsonWriter writer, TimeSpan? value, JsonSerializerOptions options)
+    {
+        if (value is { } timeSpan)
+        {
+            writer.WriteNumberValue((long)timeSpan.TotalMilliseconds);
+        }
+        else
+        {
+            writer.WriteNullValue();
+        }
+    }
+}
+
+// Serializes a positive nullable boolean (e.g. PreserveDom) as its negated JS form
+// (e.g. disableDomPreservation), keeping the public API idiomatic while the wire
+// stays aligned with the JS runtime.
+internal sealed class NegatedBooleanJsonConverter : JsonConverter<bool?>
+{
+    public override bool? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        => reader.TokenType is JsonTokenType.Null ? null : !reader.GetBoolean();
+
+    public override void Write(Utf8JsonWriter writer, bool? value, JsonSerializerOptions options)
+    {
+        if (value is { } boolean)
+        {
+            writer.WriteBooleanValue(!boolean);
+        }
+        else
+        {
+            writer.WriteNullValue();
+        }
+    }
+}

src/Components/Endpoints/src/BrowserConfiguration/ConfigureBrowser.cs

@@ -7,19 +7,19 @@ namespace Microsoft.AspNetCore.Components;
 
 /// <summary>
 /// A component that configures the Blazor browser runtime by merging
-/// configuration into the <see cref="BrowserConfiguration"/> on the current
-/// <see cref="HttpContext"/>. The merged configuration is emitted as
+/// options into the <see cref="BrowserOptions"/> on the current
+/// <see cref="HttpContext"/>. The merged options are emitted as
 /// a <c>&lt;!--Blazor-Configuration:{...}--&gt;</c> DOM comment by the renderer.
 /// </summary>
 public sealed class ConfigureBrowser : IComponent
 {
     private RenderHandle _renderHandle;
 
     /// <summary>
-    /// Gets or sets the <see cref="BrowserConfiguration"/> to merge.
+    /// Gets or sets the <see cref="BrowserOptions"/> to merge.
     /// </summary>
     [Parameter, EditorRequired]
-    public BrowserConfiguration Configuration { get; set; } = default!;
+    public BrowserOptions Options { get; set; } = default!;
 
     /// <summary>
     /// Gets or sets the <see cref="HttpContext"/> for the current request.
@@ -38,14 +38,14 @@ Task IComponent.SetParametersAsync(ParameterView parameters)
 
         if (HttpContext is not null)
         {
-            var existing = HttpContext.GetBrowserConfiguration();
-            MergeInto(existing, Configuration);
+            var existing = HttpContext.GetBrowserOptions();
+            MergeInto(existing, Options);
         }
 
         return Task.CompletedTask;
     }
 
-    internal static void MergeInto(BrowserConfiguration target, BrowserConfiguration source)
+    internal static void MergeInto(BrowserOptions target, BrowserOptions source)
     {
         target.LogLevel = source.LogLevel ?? target.LogLevel;
 
@@ -59,11 +59,11 @@ internal static void MergeInto(BrowserConfiguration target, BrowserConfiguration
 
         // Server
         target.Server.ReconnectionMaxRetries = source.Server.ReconnectionMaxRetries ?? target.Server.ReconnectionMaxRetries;
-        target.Server.ReconnectionRetryIntervalMilliseconds = source.Server.ReconnectionRetryIntervalMilliseconds ?? target.Server.ReconnectionRetryIntervalMilliseconds;
+        target.Server.ReconnectionRetryInterval = source.Server.ReconnectionRetryInterval ?? target.Server.ReconnectionRetryInterval;
         target.Server.ReconnectionDialogId = source.Server.ReconnectionDialogId ?? target.Server.ReconnectionDialogId;
 
         // SSR
-        target.Ssr.DisableDomPreservation = source.Ssr.DisableDomPreservation ?? target.Ssr.DisableDomPreservation;
-        target.Ssr.CircuitInactivityTimeoutMs = source.Ssr.CircuitInactivityTimeoutMs ?? target.Ssr.CircuitInactivityTimeoutMs;
+        target.Ssr.PreserveDom = source.Ssr.PreserveDom ?? target.Ssr.PreserveDom;
+        target.Ssr.CircuitInactivityTimeout = source.Ssr.CircuitInactivityTimeout ?? target.Ssr.CircuitInactivityTimeout;
     }
 }

src/Components/Components/src/BrowserConfiguration/ServerBrowserOptions.cs → src/Components/Endpoints/src/BrowserConfiguration/InteractiveServerBrowserOptions.cs

@@ -1,30 +1,34 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Text.Json.Serialization;
+
 namespace Microsoft.AspNetCore.Components;
 
 /// <summary>
-/// Serializable subset of <c>CircuitStartOptions</c>.
+/// Serializable subset of <c>CircuitStartOptions</c> for the interactive server render mode.
 /// Non-serializable options (<c>configureSignalR</c>, <c>reconnectionHandler</c>,
 /// <c>circuitHandlers</c>) must use <c>Blazor.start()</c> or JS initializers.
 /// </summary>
-public sealed class ServerBrowserOptions
+public sealed class InteractiveServerBrowserOptions
 {
     /// <summary>
-    /// Maximum reconnection attempts before giving up.
+    /// Gets or sets the maximum reconnection attempts before giving up.
     /// Maps to <c>CircuitStartOptions.reconnectionOptions.maxRetries</c>.
     /// </summary>
     public int? ReconnectionMaxRetries { get; set; }
 
     /// <summary>
-    /// Base interval in milliseconds between reconnection attempts (scalar form).
+    /// Gets or sets the base interval between reconnection attempts (scalar form).
     /// The function form <c>(retryCount, currentMs) => number</c> requires JS.
     /// Maps to <c>CircuitStartOptions.reconnectionOptions.retryIntervalMilliseconds</c>.
     /// </summary>
-    public int? ReconnectionRetryIntervalMilliseconds { get; set; }
+    [JsonPropertyName("reconnectionRetryIntervalMilliseconds")]
+    [JsonConverter(typeof(TimeSpanMillisecondsJsonConverter))]
+    public TimeSpan? ReconnectionRetryInterval { get; set; }
 
     /// <summary>
-    /// CSS ID of the reconnection dialog element.
+    /// Gets or sets the CSS ID of the reconnection dialog element.
     /// Maps to <c>CircuitStartOptions.reconnectionOptions.dialogId</c>.
     /// </summary>
     public string? ReconnectionDialogId { get; set; }

src/Components/Endpoints/src/BrowserConfiguration/SsrBrowserOptions.cs

@@ -0,0 +1,29 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Text.Json.Serialization;
+
+namespace Microsoft.AspNetCore.Components;
+
+/// <summary>
+/// Serializable subset of <c>SsrStartOptions</c>.
+/// </summary>
+public sealed class SsrBrowserOptions
+{
+    /// <summary>
+    /// Gets or sets a value indicating whether the DOM is preserved during enhanced navigation.
+    /// When <see langword="false"/>, DOM preservation is disabled. <see langword="null"/> leaves the value unset.
+    /// Maps to <c>SsrStartOptions.disableDomPreservation</c>.
+    /// </summary>
+    [JsonPropertyName("disableDomPreservation")]
+    [JsonConverter(typeof(NegatedBooleanJsonConverter))]
+    public bool? PreserveDom { get; set; }
+
+    /// <summary>
+    /// Gets or sets the timeout before an inactive circuit is disposed.
+    /// Maps to <c>SsrStartOptions.circuitInactivityTimeoutMs</c>.
+    /// </summary>
+    [JsonPropertyName("circuitInactivityTimeoutMs")]
+    [JsonConverter(typeof(TimeSpanMillisecondsJsonConverter))]
+    public TimeSpan? CircuitInactivityTimeout { get; set; }
+}

src/Components/Components/src/BrowserConfiguration/WebAssemblyBrowserOptions.cs → src/Components/Endpoints/src/BrowserConfiguration/WebAssemblyBrowserOptions.cs

@@ -11,20 +11,20 @@ namespace Microsoft.AspNetCore.Components;
 public sealed class WebAssemblyBrowserOptions
 {
     /// <summary>
-    /// Hosting environment name (e.g., "Development", "Production").
+    /// Gets or sets the hosting environment name (e.g., "Development", "Production").
     /// Maps to <c>WebAssemblyStartOptions.environment</c>.
     /// </summary>
     public string? EnvironmentName { get; set; }
 
     /// <summary>
-    /// Application culture in BCP 47 format (e.g., "en-US").
+    /// Gets or sets the application culture in BCP 47 format (e.g., "en-US").
     /// Maps to <c>WebAssemblyStartOptions.applicationCulture</c>.
     /// </summary>
     public string? ApplicationCulture { get; set; }
 
     /// <summary>
-    /// Environment variables for the .NET WebAssembly runtime.
+    /// Gets the environment variables for the .NET WebAssembly runtime.
     /// Use for OTEL endpoints, service URLs, etc.
     /// </summary>
-    public Dictionary<string, string> EnvironmentVariables { get; set; } = new();
+    public IDictionary<string, string> EnvironmentVariables { get; } = new Dictionary<string, string>();
 }

src/Components/Endpoints/src/Builder/RazorComponentsEndpointConventionBuilderExtensions.cs

@@ -65,25 +65,25 @@ public static RazorComponentsEndpointConventionBuilder WithStaticAssets(
     }
 
     /// <summary>
-    /// Configures a <see cref="BrowserConfiguration"/> that will be emitted as a DOM comment
+    /// Configures a <see cref="BrowserOptions"/> that will be emitted as a DOM comment
     /// to the browser for all Razor component endpoints.
     /// </summary>
     /// <param name="builder">The <see cref="RazorComponentsEndpointConventionBuilder"/>.</param>
-    /// <param name="configure">An action to configure the <see cref="BrowserConfiguration"/>.</param>
+    /// <param name="configureOptions">An action to configure the <see cref="BrowserOptions"/>.</param>
     /// <returns>The <see cref="RazorComponentsEndpointConventionBuilder"/>.</returns>
-    public static RazorComponentsEndpointConventionBuilder WithBrowserConfiguration(
+    public static RazorComponentsEndpointConventionBuilder WithBrowserOptions(
         this RazorComponentsEndpointConventionBuilder builder,
-        Action<BrowserConfiguration> configure)
+        Action<BrowserOptions> configureOptions)
     {
         ArgumentNullException.ThrowIfNull(builder);
-        ArgumentNullException.ThrowIfNull(configure);
+        ArgumentNullException.ThrowIfNull(configureOptions);
 
-        var config = new BrowserConfiguration();
-        configure(config);
+        var options = new BrowserOptions();
+        configureOptions(options);
 
         builder.Add(endpointBuilder =>
         {
-            endpointBuilder.Metadata.Add(config);
+            endpointBuilder.Metadata.Add(options);
         });
 
         return builder;