Skip to content

0006-mutation-observer-for-tab-detection.md

Latest commit

 

History

History
30 lines (19 loc) · 2.87 KB

0006-mutation-observer-for-tab-detection.md

File metadata and controls

30 lines (19 loc) · 2.87 KB
Raw

ADR 0006: Use MutationObserver to detect Curam tab changes

  • Status: Accepted
  • Date: 2026-05-20 (retroactive)

Context

Curam is a single-page application: navigating between client tabs (Addresses, Living Arrangement, Meal Group, etc.) does not trigger a full page load, so the standard content-script run_at: document_idle lifecycle fires only once at initial load. The extension needs to know each time the user switches to one of the three pages it validates, in order to run the correct validator. Polling for changes would burn CPU; intercepting click handlers would couple us to Curam's event wiring.

Decision

Register a MutationObserver on the Curam tab strip that watches for aria-selected attribute changes on .tabLabel elements. When the attribute flips to "true" on a watched tab, the observer fires handleTitleElement, which inspects the tab's text against the configured page-title prefixes and dispatches to the matching validator. A second observer is also attached so that newly-added tabs are wired up as they appear. See scripts/background.js:21-55.

Consequences

  • Pro — Event-driven; zero work when the user is not switching tabs.
  • Pro — No coupling to Curam's internal JavaScript; relies only on the public ARIA attribute, which is more stable than internal implementation details.
  • Pro — Composable with the page-title-prefix routing in handleTitleElement, so adding a new validator is just a new branch and a new pageTitles entry in scripts/config.js.
  • Con — Depends on Curam emitting .tabLabel elements with an aria-selected attribute and the configured domSelectorPrefix (ADR 0005) in the tab id. Any Curam UI rewrite that drops those will break detection silently.
  • Con — The observer is attached after waitForElement resolves on initial load; on very slow Curam loads the first tab event can be missed, requiring a tab switch to recover.

Production path

Keep MutationObserver as the core mechanism — it is the right tool — but harden it: use stable selectors (request that Curam expose data-page-id or equivalent semantic attributes; fall back to ARIA roles before resorting to id substring matches), add explicit retry / re-attach logic for slow loads, expose a debug mode that logs observed mutations to aid deployment troubleshooting, and cover the dispatch logic with end-to-end tests against a recorded Curam fixture.

References