fix: sync query_params on browser back/forward navigation

[kimjune01]

Fixes #4153

When users navigate with browser back/forward buttons, the URL changes but mo.query_params doesn't update, leaving cells stale. The frontend tracks URL changes via pushState when cells update query params, but the reverse path (browser navigation → kernel update) was missing.

Fix

Add a popstate listener in useMarimoKernelConnection that parses the new query params and sends them to the kernel via a new update_query_params endpoint. The kernel clears and updates its query_params state, then re-runs dependent cells.

Backend wiring follows the same pattern as set_ui_element_value — @requires("read") permission, command dispatched through the kernel's control request handler.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	May 12, 2026 3:11am

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[cubic-dev-ai]

No issues found across 11 files

Architecture diagram

sequenceDiagram
    participant Browser as Browser (User)
    participant FE as Frontend Runtime (useMarimoKernelConnection)
    participant Router as URL Router (pushState/popstate)
    participant RequestClient as Request Client (sendUpdateQueryParams)
    participant API as API Server (/api/kernel/update_query_params)
    participant Kernel as Kernel Runtime (control handler)
    participant QueryParams as QueryParams State
    participant Scheduler as Cell Scheduler

    Note over Browser,Scheduler: Browser Back/Forward Navigation → Query Param Sync

    Browser->>Router: browser back/forward click
    Router->>Router: URL changes (popstate event)
    Router->>FE: popstate event fires
    FE->>FE: parseQueryParams() from window.location.href
    FE->>RequestClient: sendUpdateQueryParams({ queryParams: {...} })
    
    alt Static/Wasm (Islands or Pyodide)
        RequestClient->>RequestClient: putControlRequest(type: "update-query-params")
    else Server mode
        RequestClient->>API: POST /api/kernel/update_query_params
        API->>API: @requires("read") permission check
        API->>Kernel: dispatchControlRequest(UpdateQueryParamsRequest)
    end

    Kernel->>Kernel: handle_update_query_params()
    Kernel->>QueryParams: clear() + update(request.query_params)
    QueryParams->>QueryParams: _set_value() triggers state change
    QueryParams->>Scheduler: state update notification
    Scheduler->>Scheduler: _run_cells(set()) re-executes dependent cells
    Scheduler->>Kernel: broadcastNotification(CompletedRunNotification)
    Kernel-->>API: SuccessResponse
    API-->>RequestClient: 200 OK
    RequestClient-->>FE: null (void)
    FE-->>Browser: UI updates with new cell values

    Note over Browser,Kernel: Same pattern as set_ui_element_value

Loading

[kimjune01]

I have read the CLA Document and I hereby sign the CLA