Design proposal: Blazor server-triggered circuit pause

[ilonatommy]

Related issue: #62327

Problem

Blazor already supports graceful circuit pause/resume, but the supported initiation path is currently client-driven:

• Blazor.pauseCircuit()
• Blazor.resumeCircuit()

What is missing is the symmetric server-side capability:

the server should be able to request that a connected circuit begin the existing graceful pause flow

This matters for scenarios such as:

• planned shutdowns and deployments,
• instance draining,
• maintenance windows,
• app-driven “preserve state before disconnect” workflows.

Existing framework building blocks

The feature is not starting from scratch. The current codebase already contains:

1. Client pause/resume APIs

   • Blazor.pauseCircuit()
   • Blazor.resumeCircuit()

2. Hub endpoints

   • ComponentHub.PauseCircuit()
   • ComponentHub.ResumeCircuit(...)

3. Pause/persistence pipeline

   • CircuitRegistry.PauseCircuitAsync(...)
   • CircuitPersistenceManager.PauseCircuitAsync(...)
   • CircuitHost.SendPersistedStateToClient(...)

4. Paused-session UX

   • the reconnect UI already has a paused state and resume action

The missing work is therefore primarily public API surface and orchestration.

Goals

• Add a first-class server-side pause request API on Circuit.
• Keep the client as the actor that performs the pause and owns the UX.
• Preserve the existing graceful/ungraceful resume model.
• Let apps explicitly choose when to trigger pause.
• Make the return contract small and predictable.

Non-goals

• No automatic inactivity detection.
• No framework decision-making about when an app “should” pause a session.
• No guarantee that the same in-memory circuit survives; resume creates a new circuit from persisted state.
• No rich synchronous payload return from the API.

Proposed public API

namespace Microsoft.AspNetCore.Components.Server.Circuits;

public sealed class Circuit
{
    /// <summary>
    /// Requests that the connected client begin the graceful circuit-pause flow.
    /// </summary>
    /// <param name="cancellationToken">
    /// Cancels the request before it is accepted by the framework.
    /// </param>
    /// <returns>
    /// <see langword="true"/> if the request was accepted and the client was asked to begin pausing;
    /// otherwise <see langword="false"/>.
    /// </returns>
    public ValueTask<bool> RequestCircuitPauseAsync(CancellationToken cancellationToken = default);
}

Resolved design decisions

1. Should pause be explicit or automatic?

Applications explicitly decide when to call RequestCircuitPauseAsync().

This is the preferred model because:

• comparable frameworks generally provide reconnect/reload behavior, not automatic session-pausing logic,
• Blazor already exposes an explicit client-side Blazor.pauseCircuit() API,
• the server-side API is best understood as the symmetric explicit counterpart to the existing client API.

2. What should the return type and semantics be?

The API returns a boolean because it is only answering the narrow question:

was the pause request accepted and the client asked to begin the flow?

That is the right contract because:

• the operation spans multiple asynchronous steps and network roundtrips, so a synchronous return value cannot reliably represent final completion,
• the normal flow does not need to hand app code a rich payload because persisted state is already managed through the existing client-held or server-held resume paths,
• a small acceptance/rejection result is easier to reason about and keeps the public API aligned with the actual boundary of responsibility.

In this model:

• true means the circuit was eligible and the request was accepted,
• false means the circuit was not in a state where graceful pause could begin.

3. How is completion observed?

Completion should be observed through CircuitHandler because Blazor already has a supported lifecycle surface for circuit state transitions. Adding a second, pause-specific completion API would duplicate that model.

The existing lifecycle already exposes the events app authors care about:

• OnCircuitOpenedAsync
• OnConnectionUpAsync
• OnConnectionDownAsync
• OnCircuitClosedAsync

So applications can observe pause progression by implementing a CircuitHandler and watching:

• OnConnectionDownAsync when the client disconnects as part of the pause flow
• OnCircuitClosedAsync when the old circuit is finally discarded

This keeps the API small while reusing a lifecycle hook that developers already understand and can register in DI today.

4. What is the fallback behavior if graceful pause does not complete?

If the pause handshake begins but cannot complete cleanly, the framework should use this fallback order:

1. graceful client-held pause,
2. server-side persistence fallback if available,
3. normal reconnect/reload/remount behavior if neither succeeds.

This matches the current Blazor pause/resume architecture and the common pattern in other comparable frameworks.

5. Where is RequestCircuitPauseAsync() valid to call from?

The framework should validate circuit state, not caller location.

That is the better rule because:

• enforcing “only callable from CircuitHandler” would be brittle and artificial once a caller legitimately has a Circuit reference,
• framework correctness depends on whether the circuit can safely enter the transition, not on which method happened to initiate it,
• state-based validation is easier to document, test, and keep stable over time.

RequestCircuitPauseAsync() is valid from any code that legitimately holds a Circuit reference, provided all of the following checks pass:

1. The circuit is still alive
   The underlying CircuitHost still exists and has not been disposed or permanently closed.

2. The circuit is currently connected
   A graceful pause requires an active client connection that can receive the request and drive the browser-side flow.

3. The circuit is eligible for pause
   The circuit is not already fully paused, or the call is treated idempotently while a pause is already in progress.

4. The transition can be entered safely
   The request is serialized onto the circuit’s normal dispatcher/connection-transition path so it cannot race unsafely with reconnect, disconnect, or disposal.

6. How should active circuits be tracked?

Applications should track active circuits via CircuitHandler.

No dedicated framework “pause registry” is required for the initial design. A common pattern is:

• register a CircuitHandler,
• record circuits on OnConnectionUpAsync,
• remove them on OnConnectionDownAsync / OnCircuitClosedAsync,
• call RequestCircuitPauseAsync() from app-managed shutdown or drain logic.

This is preferable because the framework already provides the lifecycle hooks needed to maintain that set, and the application is the only layer that knows which circuits it wants to pause and when.

7. What are the concurrency and idempotency rules?

The operation should be idempotent and support only one active connection-state transition at a time.

This is the right behavior because shutdown/drain code may fan out pause requests broadly, and repeated requests should not create spurious failures or race-sensitive semantics.

Practical behavior:

• repeated requests while pause is already in progress may return true,
• requests on circuits that are already gone or no longer eligible return false,
• reconnect/disconnect/pause transitions are serialized through the existing circuit execution model.

8. Should the existing paused-session UI be reused?

The existing reconnect dialog should be reused for server-requested pause because the user concept is the same: the session is temporarily unavailable, but a resume path exists.

Reusing it avoids inventing a second UI model for the same state transition and keeps the first version lower-risk and more consistent.

The dialog should:

• show the paused state/message,
• allow resume through the existing flow,
• optionally allow customization later without requiring it for the first version.

9. What telemetry and logging should exist?

The framework should emit explicit events for the key milestones of the flow so acceptance, fallback, and completion can be diagnosed separately.

This is especially important because a boolean return only tells the caller whether the request was accepted; it does not explain what happened afterward.

Useful events include:

• pause requested,
• pause accepted,
• pause rejected,
• persisted state sent to client,
• fallback to server-side persistence,
• pause completed,
• pause timed out / failed,
• resume succeeded / rejected.

Proposed runtime flow

1. App code decides a circuit should pause and calls RequestCircuitPauseAsync().
2. If the circuit is alive, connected, and eligible, the framework accepts the request and returns true.
3. The framework sends a dedicated server-to-client message over the existing circuit connection.
4. The browser-side circuit manager:
   • shows the existing paused-session UI,
   • performs the current internal pause path,
   • persists state,
   • disconnects cleanly.
5. If the client-held graceful path fails, the framework falls back to server-side persistence when possible.
6. Later, resume proceeds through the existing client-led Blazor.resumeCircuit() + ResumeCircuit(...) flow.
7. If no persisted state is available, normal reload/remount behavior applies.

sequenceDiagram
    participant App as App Code
    participant FW as Framework<br/>(CircuitHost)
    participant SR as SignalR
    participant Client as Browser<br/>(CircuitManager)
    participant UI as Reconnect UI

    Note over App,UI: Server-triggered circuit pause flow

    App->>FW: RequestCircuitPauseAsync()
    FW->>FW: Validate: alive? connected? eligible?

    alt Circuit not eligible
        FW-->>App: return false
    else Circuit eligible
        FW-->>App: return true
        FW->>SR: Send JS.RequestPause
        SR->>Client: JS.RequestPause

        Client->>UI: Show paused-session dialog
        Client->>SR: PauseCircuit (hub call)
        SR->>FW: PauseCircuit()

        FW->>FW: Remove from ConnectedCircuits
        FW->>FW: Persist state (ComponentStatePersistenceManager)

        FW->>SR: JS.SavePersistedState
        SR->>Client: JS.SavePersistedState

        alt Client stores state successfully
            Client->>Client: Store persisted state
        else Client push fails
            FW->>FW: Fallback: server-side PersistCircuitAsync
        end

        Client->>SR: disconnect()
        SR->>FW: OnClose

        FW->>FW: CircuitHandler.OnConnectionDownAsync
        FW->>FW: DisposeAsync (components)
        FW->>FW: CircuitHandler.OnCircuitClosedAsync

        Note over App,UI: Later — user clicks Resume

        Client->>SR: New connection
        Client->>SR: ResumeCircuit(circuitId, state)
        SR->>FW: ResumeCircuit()

        FW->>FW: Create new circuit from persisted state
        FW->>SR: Initial render
        SR->>Client: JS.RenderBatch
        Client->>UI: Hide dialog, show app
    end

Loading

[github-actions]

Triage Summary

Area: area-blazor — The issue is entirely about Blazor Server circuits, the Circuit class, CircuitHandler, ComponentHub, and related circuit-lifecycle infrastructure in src/Components/.

Type: api-proposal — This is a formal API design proposal. It proposes a new public method Circuit.RequestCircuitPauseAsync(), includes resolved design decisions, a proposed runtime flow, and an explicit public API surface block.

Potential Duplicates

• [Blazor] Trigger state persistence from the server #62327 - [Blazor] Trigger state persistence from the server (related: this is the originating feature request that the design proposal directly addresses — not a duplicate)

Notes

• The issue already carries the design-proposal label, which is consistent with the content. Adding area-blazor and api-proposal to complete classification.
• No regression is involved; this is purely additive new API surface.

Generated by Issue Triage Agent for dotnet/aspnetcore for issue #66244 · ● 329.3K · ◷

[ilonatommy]

Scenarios that this change should handle

The server-triggered pause flow introduces additional client↔server roundtrips compared to the existing client-triggered path. Now we have two areas for races:

• Window A: Between the server pending the pause message and the client beginning the pause. In this window client may be: processing events/submitting forms/initiating its own pause etc.
• Windows B (pre-existing): Between client's pause request arriving on he server and the server finishing persisntance and sending the SavePersistanceState back. Other hub messages from client (event dispatches/interop calls etc) may still be in the SignalR queue and could arrive while the server is mid-persistet.

         Server                                         Client
         ──────────────────────                     ────────────────
                  │                                        │
  App code calls  │                                        │
  RequestCircuitPauseAsync()                               │
  (validates state, returns true/false)                    │
                  │                                        │
                  ├─────── JS.RequestPause ───────────────►│
                  │                                        │
                  │                              [RACE WINDOW A]
                  │                                        │
                  │                                        ├── shows paused UI
                  │◄──────── PauseCircuit (hub call) ──────┤
                  │                                        │
                  │                              [RACE WINDOW B]
                  │                                        │
  ComponentHub    ├─── JS.SavePersistedState ─────────────►│
  persists state  │                                        ├── stores state
                  │                                        ├── disconnect()
                  │                                        │

Focusing on Window A, we have following scenarios (should be covered with tests):

A. Calling RequestCircuitPauseAsync() in different circuit states

These cover what happens when the API is called depending on the circuit's state: idle, busy, disconnected, disposed, etc.

Connected and idle

A1. Alive, connected, idle circuit

• Setup: Circuit is connected and idle (assert: no rendering, no event handlers executing).
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns true. The framework sends the server-to-client pause message. The client receives it and begins the pause flow.

Connected but busy (not idle)

A2. Event handler is executing synchronous code

• Setup: User clicked a button. The component's @onclick handler is running synchronously on the circuit's dispatcher.
• Action: Server calls RequestCircuitPauseAsync().
• Expected: The pause request is accepted (true), and the server-to-client message is sent. Meanwhile, the event handler runs to completion. When the client eventually calls hub PauseCircuit, the registry serializes the pause transition after the event handler finishes. No partial state.

A3. Event handler is awaiting async work

• Setup: An @onclick handler called await Http.GetAsync(...) and is suspended at the await point.
• Action: Server calls RequestCircuitPauseAsync().
• Expected: The pause message is sent to the client. The client begins the pause flow and calls PauseCircuit. On the server, PauseCircuitAsync runs in the registry under lock. The paused state captures whatever the component state was at that point. The async continuation of the event handler will fail because the circuit host is disposed (dispatcher is gone). The framework should handle this gracefully - no unobserved exceptions propagated to the app.

A4. Rendering in progress (UpdateDisplayAsync executing)

• Setup: A component called StateHasChanged(), and the renderer is serializing a render batch.
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns true. The render batch is written to _unacknowledgedRenderBatches. The pause message is sent. The client may or may not receive the render batch before processing the pause message (depends on SignalR message ordering). Either way, the client enters the pause flow. Unacknowledged batches are abandoned on dispose.

A5. OnAfterRenderAsync is executing

• Setup: A component's OnAfterRenderAsync is running (e.g., doing JS interop setup after first render).
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns true. The OnAfterRenderAsync work may complete or may fail when the circuit disposes (JS interop calls will throw JSDisconnectedException). The pause proceeds. Component state is captured as-is at persistence time.

A6. .NET → JS interop call pending

• Setup: Component code called JSRuntime.InvokeAsync<T>(...) and is awaiting the response.
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns true. The pause message is sent. The client processes the pause flow. When the circuit host is disposed, RemoteJSRuntime is marked permanently disconnected, and the pending interop call completes with JSDisconnectedException. The calling component code should handle this (or it becomes an unhandled circuit error).

A7. JS → .NET interop call in-flight

• Setup: JavaScript code called DotNet.invokeMethodAsync(...) and the server is executing the .NET method.
• Action: Server calls RequestCircuitPauseAsync() concurrently.
• Expected: Returns true. The .NET interop method runs to completion on the dispatcher. The pause message is sent to the client. The JS interop response may or may not make it back to the client depending on timing. The pause proceeds after the interop dispatch completes.

A8. Streaming .NET → JS data transfer active

• Setup: A DotNetStreamReference is being streamed to the client via JS.BeginTransmitStream.
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns true. The stream is interrupted when the connection closes. The client-side ReadableStream controller receives an error. The pause proceeds normally. On resume, the stream is not recovered (the component must re-initiate it).

A9. Component OnInitializedAsync is running (late-added component)

• Setup: A parent component conditionally renders a child. The child's OnInitializedAsync is executing (e.g., loading data).
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns true. The initialization may complete or be interrupted by circuit disposal. State persistence captures whatever was committed to the component tree at that point. The interrupted component may not have fully initialized state - this is expected. On resume, the component reinitializes from persisted state (or from scratch if state wasn't captured).

Not connected or not alive

A10. Circuit already disposed

• Setup: Circuit has been fully disposed (e.g., tab closed, circuit timeout expired).
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns false. No message is sent. No side effects.

A11. Circuit disconnected (in reconnect window)

• Setup: Client has lost its connection. The circuit is in the DisconnectedCircuits cache waiting for reconnect.
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns false. A graceful pause requires an active connection to drive the browser-side flow.

A12. Circuit never completed initialization

• Setup: A CircuitHost exists but InitializeAsync has not completed (e.g., the first UpdateRootComponents hasn't been called yet).
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns false. The circuit is not yet in a state that can be meaningfully paused.

Already paused or pausing

A13. Circuit already fully paused

• Setup: A previous RequestCircuitPauseAsync() or Blazor.pauseCircuit() has already completed.
• Action: Server calls RequestCircuitPauseAsync() again.
• Expected: Returns true (idempotent) or false if the circuit is already gone/disposed. No duplicate pause work is triggered.

A14. Pause already in progress

• Setup: A pause was requested and the client is currently executing the pause flow (hub PauseCircuit call is in-flight or persistence is running).
• Action: Server calls RequestCircuitPauseAsync() again.
• Expected: Returns true (idempotent). The in-progress pause is not interrupted or duplicated.

CancellationToken behavior

A15. CancellationToken cancelled before acceptance

• Setup: Circuit is alive and connected.
• Action: Server calls RequestCircuitPauseAsync(ct) where ct is already cancelled.
• Expected: The task is cancelled or returns false. No pause message is sent.

A16. CancellationToken cancelled after acceptance but before client processes

• Setup: Circuit is alive and connected.
• Action: Server calls RequestCircuitPauseAsync(ct). The framework accepts the request and sends the message, then ct fires.
• Expected: The API already returned true (acceptance). Cancellation does not revoke the in-flight message. The client-side flow proceeds or is a no-op if the message was lost.

B. Client actions racing with the server-triggered pause message

These focus specifically on Race Window A: the client is doing something exactly when the server-to-client pause message arrives.

B1. Client calls Blazor.pauseCircuit() at the same time

• Setup: Circuit is connected. App logic on both sides independently decides to pause.
• Action: Server calls RequestCircuitPauseAsync() AND client calls Blazor.pauseCircuit() concurrently.
• Expected: One pause wins. If the client's pause() starts first, it sets _pausingState in-progress, so the server's message arriving later sees pause already in progress and is a no-op. If the server message arrives first, the client enters pause(remote=true), and the subsequent Blazor.pauseCircuit() call sees _pausingState.isInprogress() and awaits it. No double-pause. No errors.

B2. User clicks a button (event dispatch) as pause message arrives

• Setup: Circuit is connected. User is interacting with the app.
• Action: Server sends pause message. Before the client processes it, the user clicks a button. The click dispatches beginInvokeDotNetFromJS to the hub.
• Expected: SignalR processes hub messages one at a time. The event may be dispatched before or after the PauseCircuit call from the client. If the event arrives first, it executes normally. If PauseCircuit arrives first, subsequent events on the old connection are rejected (circuit removed from connected set). The client should not show errors to the user—the pause UI is already visible.

B3. Client navigates (location change) while pause message is in transit

• Setup: Circuit is connected. User clicks a link causing an OnLocationChanged hub call.
• Action: Server pause message and location change are in-flight simultaneously.
• Expected: If location change is processed first, the component tree updates, then pause proceeds with the updated state. If pause is processed first, the location change either fails (circuit gone) or is ignored. The client shows the paused UI regardless.

B4. Client submits a form while pause message is in transit

• Setup: Circuit is connected. User submits a form, generating a DispatchEvent call.
• Action: Server pause message and form submission event are in-flight simultaneously.
• Expected: Similar to D2. The form event may or may not be processed depending on ordering. If processed, its effects are captured in the paused state. If not, the form submission is effectively lost. The paused UI is shown. On resume, the form state is whatever it was at persistence time.

B5. Client calls Blazor.resumeCircuit() while pause flow is in progress

• Setup: Server triggered a pause. The client is mid-pause (e.g., PauseCircuit hub call in-flight or awaiting JS.SavePersistedState).
• Action: App code or user action calls Blazor.resumeCircuit().
• Expected: The client's resume() method checks _pausingState.isInprogress() and returns false. Resume is rejected until pause completes. After pause finishes, resume can proceed normally.

B6. Multiple events queued on client before pause message is processed

• Setup: Circuit is connected. User rapidly clicks multiple buttons, queuing several beginInvokeDotNetFromJS calls.
• Action: Server sends pause message. Several client-to-server events are already queued in the SignalR send buffer.
• Expected: SignalR delivers messages in order. Events queued before the client processes the pause message will be sent. The server processes them in order. Eventually, PauseCircuit is called. Events that arrive after PauseCircuit (which removes the circuit from ConnectedCircuits) will fail via GetActiveCircuitAsync() returning null, aborting the connection. This is harmless because the client is already in paused-UI mode.

C. Network failure at the new race point

Network drops between the server sending the pause message and the client processing it.

C1. Network drops after server sends pause message but before client receives it

• Setup: Circuit is connected. Server calls RequestCircuitPauseAsync(), which returns true and sends the message.
• Action: Network fails immediately after.
• Expected: Client never receives the pause message. The SignalR connection closes. Client enters the normal reconnect flow (not the pause flow). Server-side, DisconnectAsync moves the circuit to DisconnectedCircuits. If the reconnect window expires, the circuit is evicted and paused/disposed by the server's eviction handler. The client shows the reconnect UI, not the pause UI.

D. Reconnect interactions with the new API

Reconnect transitions colliding with RequestCircuitPauseAsync().

D1. Client reconnects just before server calls RequestCircuitPauseAsync()

• Setup: Client was disconnected briefly, then reconnected (new connection ID). Circuit is back in ConnectedCircuits.
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns true. The pause message is sent on the new connection. Flow proceeds normally. The connection-ID check in PauseCore matches the new connection.

D2. Client reconnects with a new connection while old connection's pause is in-flight

• Setup: Server triggered a pause on connection A. Before the flow completes, the client lost connection A and reconnected on connection B (e.g., network hiccup during pause).
• Action: The client on connection B calls ConnectCircuit. Meanwhile, the PauseCircuit from connection A may still arrive.
• Expected: ConnectCore in the registry sees the circuit is connected to a different connection and Transfer()s the client. PauseCore checks the connection ID—if it doesn't match the current one, it does nothing (connection-ID mismatch guard). The circuit continues on connection B, unpaused. The server may need to re-request pause.

D3. Server triggers pause on circuit that is in the disconnected cache (reconnect window)

• Setup: Client disconnected. Circuit is in DisconnectedCircuits awaiting reconnect or eviction.
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns false. There is no active connection to send the pause message to.

E. Concurrency and idempotency of the new API

Multiple or repeated calls to RequestCircuitPauseAsync().

E1. Multiple concurrent calls to RequestCircuitPauseAsync() on the same circuit

• Setup: Drain logic fans out pause requests broadly, hitting the same circuit multiple times.
• Action: Two or more concurrent calls to RequestCircuitPauseAsync().
• Expected: All calls return true. Only one effective pause operation runs. The CircuitRegistryLock serializes transitions. The first call removes the circuit from ConnectedCircuits; subsequent calls find it already gone and return true (idempotent) or false (already disposed).

E2. Rapid pause → resume → pause cycle

• Setup: Server triggers pause. Client completes it. Client immediately resumes. Server immediately triggers pause again.
• Action: Rapid state transitions.
• Expected: Each transition is serialized. The first pause completes (circuit disposed). Resume creates a new circuit (new circuit ID). The second pause request must target the new circuit reference. If it targets the old one, it returns false (disposed). If the app correctly tracks the new circuit via CircuitHandler, the second pause succeeds.

E3. RequestCircuitPauseAsync() called on a circuit reference that is stale

• Setup: App stored a Circuit reference. The circuit was disposed/closed by some other means (e.g., user navigated away). The app still holds the old reference.
• Action: App calls RequestCircuitPauseAsync() on the stale reference.
• Expected: Returns false. The underlying CircuitHost is null or disposed. No side effects.

F. Deployment and drain

Using RequestCircuitPauseAsync() for app shutdown and instance draining.

F1. Drain all connected circuits simultaneously

• Setup: App shutdown logic iterates all tracked circuits and calls RequestCircuitPauseAsync() on each.
• Action: N pause requests fire concurrently.
• Expected: Each circuit independently enters the pause flow. Circuits that accept the request return true. The registry lock serializes per-circuit, not globally. All circuits eventually disconnect and are disposed. The server can shut down once all pauses complete (observed via CircuitHandler).

F2. Server shutdown while pause operations are in progress

• Setup: Server triggered pause on several circuits. The host's IHostApplicationLifetime.StopAsync() fires, cancelling the application stopping token.
• Action: Host is shutting down while persistence is running.
• Expected: If the CancellationToken from the host propagates to persistence operations, they may be cancelled. Circuits are force-disposed during shutdown. State may or may not be persisted depending on timing. The client sees the connection drop and enters reconnect/pause UI. On the client side, the paused UI is shown if the pause message was received; otherwise, the reconnect UI is shown.

F3. New circuit connects during drain

• Setup: Server is draining existing circuits. A new user navigates to the app and establishes a new circuit.
• Action: New circuit is created while drain is in progress.
• Expected: The new circuit connects normally. It's up to app logic to decide whether to immediately pause the new circuit or allow it to operate. The framework does not automatically prevent new circuits during drain.

G. Client state machine vs. server pause message

The new server-to-client message arriving while the client is in a specific state.

G1. Server pause message arrives while client is in resuming state

• Setup: Client was previously paused. Client called Blazor.resumeCircuit() and is mid-resume (awaiting ResumeCircuit hub response).
• Action: Server sends a pause message on the connection.
• Expected: The client's pause() method checks _resumingState.isInprogress() and returns false (refuses to pause while resuming). The server pause message is effectively rejected by the client. The server should observe this (e.g., via a return value from the client or timeout) and may retry after resume completes.

G2. Server pause message arrives while client is already disconnecting

• Setup: Client is disconnecting (e.g., dispose() was called, page is unloading).
• Action: Server sends a pause message.
• Expected: The client may not process the message at all (connection is closing). The server sees the disconnect. The circuit is cleaned up via the normal disconnect path.

G3. Server pause message arrives while client is processing a render batch

• Setup: Client received JS.RenderBatch and is applying DOM updates.
• Action: Server sends the pause message.
• Expected: SignalR delivers messages in order. The render batch completes first (it's already being processed). Then the pause message is handled. The client enters the pause flow with the latest DOM state.

H. Paused UI for server-triggered pause

UI behavior specific to server-initiated pause.

H1. Paused UI shows correct state for server-triggered vs. client-triggered pause

• Setup: Server triggers pause (vs. client triggers pause).
• Action: Client shows the reconnect dialog.
• Expected: The dialog shows the paused state with appropriate messaging (e.g., "The session has been paused by the server"). The remote flag in the reconnect handler can be used to differentiate the message. The Resume button is available.

H2. Custom reconnect UI handles server-triggered pause

• Setup: App has a custom reconnect UI element with components-reconnect-modal ID and listens for components-reconnect-state-changed events.
• Action: Server triggers pause.
• Expected: The custom element receives the state change event with the pause-specific state. The app can customize the message and behavior (e.g., "Server is restarting, please wait…").

I. Error conditions with the new API

Calling the API on faulted or unusual circuits.

I1. RequestCircuitPauseAsync() called after a recoverable rendering error (error boundary caught it)

• Setup: A component threw an unhandled exception during rendering, but an <ErrorBoundary> caught it. The circuit is still alive and connected, showing the error boundary's fallback content.
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns true. The circuit is still connected. The pause flow proceeds normally. The persisted state includes the component tree in its error-boundary state.

I2. RequestCircuitPauseAsync() called after a fatal rendering error (circuit terminated)

• Setup: A component threw an unhandled exception that was not caught by an error boundary. The circuit is terminated — the error UI is shown and the circuit is disposed.
• Action: Server calls RequestCircuitPauseAsync().
• Expected: Returns false. The circuit is no longer alive. No message is sent.

I3. RequestCircuitPauseAsync() called during OnCircuitOpenedAsync

• Setup: App logic calls RequestCircuitPauseAsync() from within CircuitHandler.OnCircuitOpenedAsync (circuit just created).
• Action: The circuit is being initialized.
• Expected: Returns false. The circuit is alive but not yet fully connected (OnConnectionUpAsync hasn't fired), so the "currently connected" precondition fails.

I4. Server sends pause message but the client's JavaScript is unresponsive

• Setup: Client-side JS had an unhandled error (e.g., a bad JS interop call crashed the event loop). The SignalR connection is still technically open, but the client cannot process incoming messages.
• Action: Server calls RequestCircuitPauseAsync().
• Expected: The server-side check passes (circuit is alive, connected, eligible) so the API returns true and sends the message. The client never processes it. Eventually the SignalR connection times out. Server-side, the circuit transitions to disconnected, then evicted and disposed with server-side persistence.

[javiercn]

@ilonatommy you can ask copilot to write you the nice mermaid markdown diagram, FYI,

Other than that, in a first pass it looks good