DevTools & time travel

Getting connected

1. Install the Redux DevTools browser extension.
2. Run the app with <BlexProvider> in place and EnableDevTools left at its default.
3. Open the browser devtools and switch to the Redux tab. The instance is named after options.DevToolsName.
4. Interact with the app. Every action arrives with its argument payload and the state that followed it.
5. Drag the slider, or use the jump buttons, to rewind the application live.

builder.Services.AddBitBlexServices(options =>
{
    options.DevToolsName = "My App";   // shown in the extension's instance dropdown
});

What travels over the bridge

On connect, the manager sends the current tree as the initial state. After that, each recorded action sends an action object and the resulting tree:

// init, on connect
{ "counter": { "Count": 0, "Step": 1 }, "settings": { "Accent": "violet" } }

// send, per action
action: { "type": "counter/SetStep", "payload": { "step": 5 } }
state:  { "counter": { "Count": 0, "Step": 5 }, "settings": { "Accent": "violet" } }

The state tree is keyed by store name - counter, settings and so on - which is exactly what BlexManager.CaptureGlobalState() produces.

Messages Blex handles

Time-travel is driven by the extension sending messages back. HandleDevToolsMessage interprets these:

Applying a snapshot goes through RestoreGlobalState, so it never records new actions - the timeline you are scrubbing does not grow while you scrub it. A store whose slice fails to deserialize is reported to OnError and skipped; the rest still restore.

Pause and lock

The monitor's two recording controls are different in kind, and the difference matters when you are hunting a bug. Pause recording is about the timeline: the app carries on exactly as before, it just stops filling the monitor with noise while you set up the state you actually want to inspect. Lock changes is about the app: every action is refused, so nothing can move underneath you while you scrub.

Both are readable from the manager, so the UI can tell the user why its buttons appear dead:

// Paused: actions apply and are observed, they are just not streamed to the monitor.
if (manager.IsDevToolsPaused)
    _hint = "DevTools recording is paused.";

// Locked: every action is vetoed, exactly as a UseFilter returning false would.
// Restores are deliberately not gated, so the slider still moves.
if (manager.AreChangesLocked)
    _hint = "The monitor has locked changes - unlock it to interact.";

Redacting sensitive state

The state tree is handed to a browser extension. Anything in it is visible to that extension. Blex gives you two hooks plus a shorthand.

builder.Services.AddBitBlexServices(options =>
{
    // Take full control of the state tree...
    options.DevToolsStateSanitizer = state =>
    {
        var clone = (JsonObject)state.DeepClone();
        if (clone["user"] is JsonObject user)
            user["email"] = "<hidden>";
        return clone;
    };

    // ...and redact these keys anywhere in the tree (and in action payloads) on top of it.
    // Register redaction last: it wraps the sanitizer above, but an assignment after this
    // call would replace it.
    options.RedactDevToolsKeys("token", "password", "ssn");

    // The action label has its own hook.
    options.DevToolsActionSanitizer = label => label.Replace(_userId, "<id>");
});

RedactDevToolsKeys walks the whole tree - objects and arrays - replacing matching keys with <redacted>, and it is applied to action payloads as well as state, so an argument named password is redacted too.

It is additive, and it composes. Calling it a second time widens the redaction set rather than replacing it, so a library and an app can each register their own secrets without one silently unmasking the other's. A custom DevToolsStateSanitizer assigned before the call still runs - redaction is applied on top of its output - which lets you reshape the tree and redact it in the same pipeline.

// A shared setup module redacts what it knows about...
options.RedactDevToolsKeys("token");

// ...and the app adds its own. The set widens; "token" stays redacted.
options.RedactDevToolsKeys("ssn", "dateOfBirth");

Turning it off

For production, disable the connection outright. Nothing is serialized and nothing is sent.

<BlexProvider EnableDevTools="@Env.IsDevelopment()">
    <Router ... />
</BlexProvider>

Under the hood

The core package has no JS dependency - it only knows the IBlexDevTools interface. Bit.Blex.Blazor supplies BlexReduxDevToolsConnector, which loads a small ES module and talks to window.__REDUX_DEVTOOLS_EXTENSION__.

public interface IBlexDevTools
{
    void Init(JsonObject globalState);
    void Send(string actionName, JsonObject globalState);
    void Send(string actionName, JsonObject globalState, JsonObject? payload)
        => Send(actionName, globalState);
}

• If the extension is not installed, connect returns false and everything becomes a no-op - no errors, no cost.
• Interop calls are dispatched without blocking the dispatch pipeline, but their tasks are still observed so a transient failure cannot surface as an unobserved exception.
• Disconnecting detaches only Blex's own subscription, rather than killing every DevTools instance on the page.
• The bridge advertises exactly what it implements: jump and export yes; dispatch, skip and reorder no.

Connecting a different sink

IBlexDevTools is public, so the manager can feed anything - a server-side session recorder, a test double, a custom monitor.

public sealed class RecordingDevTools : IBlexDevTools
{
    public List<(string Action, JsonObject State)> Frames { get; } = [];

    public void Init(JsonObject state) => Frames.Add(("@@INIT", state));

    public void Send(string action, JsonObject state) => Frames.Add((action, state));
}

manager.ConnectDevTools(new RecordingDevTools());
// ... and later
manager.DisconnectDevTools();