Consolidate url state encoding orchestration

[DarianGill]

This issue is for us to consider an overall architecture tidy-up of how the URL state is managed. We've slowly pulled the url functionality out of certain modules like CesiumWidgetView, but the functionality remains spread out across a wide surface that can be hard to reason about. Right now, SearchParams reads and writes the browser URL, ViewfinderModel resolves and opens actions, ViewfinderView owns the debounce and sync, and MapView/VisualizationPanelView relay the state. Same for the active visualization, which is right now split across activeVisualizationAction, activeVisualizationActionId, and activeVisualizationUrl, which always need to be updated at the same time. We should find a way we can consolidate the URL coordination into a single place and make clearer ownership boundaries.

Here's one way we could do that (conceived with the help of GPT-5.3-codex)

Plan: Single URL Coordinator + Unified Visualization State

The cleanest approach is to make one coordinator the only owner of URL state, and make active visualization a single atomic object. The following could be done in one big refactor PR:

Steps

1. Phase 1: Establish one URL owner (blocks all other phases).
2. Add a coordinator module that is the only code allowed to read, normalize, and write browser query state.
3. Move URL schema logic out of SearchParams.js into the coordinator internals (camera, layers, open panel, active action id, namespaced action params, schema versioning).
4. Keep SearchParams.js as a temporary facade that delegates to coordinator methods to limit import churn during this PR.
5. Parse URL once on app/map init, cache normalized state in coordinator memory, and expose it to consumers so views/models do not repeatedly parse window location.
6. Phase 2: Unify active visualization state (depends on Phase 1).
7. Replace Map attributes activeVisualizationAction, activeVisualizationActionId, and activeVisualizationUrl with one activeVisualization object in Map.js.
8. Refactor write sites to set activeVisualization atomically in ViewfinderModel.js and MapView.js.
9. Refactor read sites to consume activeVisualization atomically in MapView.js, ViewfinderView.js, and VisualizationPanelView.js.
10. Add temporary read-only compatibility aliases in Map for one PR so untouched callers do not break mid-refactor.
11. Phase 3: Move URL sync orchestration into coordinator (depends on Phases 1-2).
12. Replace distributed URL writes from Map/Viewfinder/MapView with coordinator intent methods (camera changed, layers changed, panel changed, visualization opened/closed, visualization state message received).
13. Centralize debounce policy in coordinator so there is one write schedule instead of separate timers in model/view layers.
14. Keep stale-message protection in coordinator by verifying current activeVisualization.actionId before writing namespaced action params.
15. Phase 4: Clarify restore boundaries (depends on Phase 3).
16. Coordinator provides one restored state object to Map and Viewfinder restore paths.
17. Keep ToolbarView URL-agnostic; MapView maps UI events to coordinator intents and initializes UI from restored coordinator state.
18. Replace retry-fragile restore sequencing with explicit idempotent restore attempts when category render completes.
19. Phase 5: Cleanup and boundary enforcement (depends on Phase 4).
20. Remove direct URL mutation calls from MapView.js and ViewfinderView.js.
21. Remove legacy active visualization fields from Map.js after all references migrate.
22. Finalize ownership docs/comments: coordinator owns URL lifecycle, models own domain state, views own rendering and user interaction only.

Relevant files

• SearchParams.js: convert to delegation facade, then shrink or replace.
• Map.js: adopt single activeVisualization object and restored state consumption.
• ViewfinderModel.js: atomic visualization open/close state writes.
• MapView.js: consume unified visualization state, emit coordinator intents.
• ViewfinderView.js: remove URL-writing responsibility and debounce ownership.
• VisualizationPanelView.js: consume unified visualization context, keep trusted message/origin checks.
• UriTemplateUtilities.js: reused by coordinator for action-template expansion/extraction.
• js: add/update coordinator, visualization state, and race-condition coverage.

Verification

1. Unit tests for coordinator parse/normalize/write behavior across camera, layers, panel, action id, and namespaced params.
2. Unit tests for activeVisualization constructors and invariants (valid action, invalid action id, URL-only legacy path, clear).
3. Integration test: visualization open + state message writes expected action-scoped params.
4. Integration test: open action A then B quickly; assert only B wins in URL.
5. Integration test: close visualization then stale message arrives; assert cleared params are not reintroduced.
6. Integration test: full restore from URL (camera + layers + panel + action) is deterministic and idempotent.
7. Run full test suite and manual localhost verification for map pan/zoom, layer toggles, panel open/close, visualization open/close, reload/share URL.

[robyngit]

Thanks for writing this up! I agree with the overall direction. One place coordinating browser query state, and one activeVisualization value would make this much easier to follow.

Some feedback on a few details:

Add a coordinator module that is the only code allowed to read, normalize, and write browser query state.

I would separate two responsibilities here. Backbone Router and History should keep owning paths, page routes, and navigation for now. Native URL and URLSearchParams can handle query syntax.

I would make the shared query mechanics framework independent. Given the current URL and a set of changes, this module would update only the keys owned by that feature and preserve everything else. The coordinator can commit the result through Backbone History so its internal fragment stays in sync.

The map schema and map sync logic can remain map specific. Keeping the underlying query mechanics free of map and visualization concepts would let us reuse them for other features, such as #2114.

Parse URL once on app/map init, cache normalized state in coordinator memory, and expose it to consumers so views/models do not repeatedly parse window location.

I read this as the coordinator becoming the in memory source of truth after initialization. If that is the intention, I would not rely on the cached state for ongoing writes. The browser URL can change through Backbone, back and forward navigation, etc. That could leave the cached copy out of date.

An immutable restore snapshot for one map instance makes sense. Each write should still begin with the current browser URL, change only the parameters owned by the map, and preserve everything else.

Centralize debounce policy in coordinator so there is one write schedule instead of separate timers in model/view layers.

If "one write schedule" means one shared trailing debounce, I would keep separate schedules inside the coordinator for map changes and iframe messages. They have different timing and cleanup needs. Activity from one source should not keep postponing the other. Closing an iframe should also cancel its pending update without affecting a pending map update.

Replace Map attributes activeVisualizationAction, activeVisualizationActionId, and activeVisualizationUrl with one activeVisualization object in Map.js.

Keep stale-message protection in coordinator by verifying current activeVisualization.actionId before writing namespaced action params.

Phase 3 makes me think the new object would store actionId separately. For configured actions, I think this is probably enough:

activeVisualization = { action, resolvedUrl } | null;

The ID can come from action.id when there is an action.

I would keep the URL's restoreState.activeActionId separate. The a= parameter can identify iframe, map, and tab actions too. activeVisualization should describe only the iframe viz that is currently open. If this is already what you intended, then my only suggestion here is to avoid storing the action ID twice.

The race tests and fixes may be worth doing before moving ownership. I see two cases to cover:

1. A restore waiting for remote cards can complete after the user has opened or closed something else. That old restore should no longer run.
2. A same origin message from iframe A can already be queued when iframe B opens. The handler can then associate that message with B because it reads the current action. Since the same iframe element keeps the same contentWindow, the current source check does not distinguish the old message either. Creating a new iframe element for each open seems like the smallest fix.

---

There is a lot of work here, so this probably deserves a few smaller PRs: the race tests and fixes, the generic query mechanics and Backbone integration, then the map coordinator and visualization state changes.

Where you don't need backbone model functionality directly, feel free to use modern ES6 classes instead. That helps us gradually reduce our dependency on backbone (or any framework).