# Feature flags, browser-session ownership, and chart-contract acceptance

Use this reference when a gated browser feature introduces local chart assets and a Same-Origin API session.

## Single-owner activation contract

- The server/renderer is authoritative for activation. Emit an explicit DOM marker such as `data-feature-enabled="1"` only when the generator flag is enabled.
- Without the flag, emit `0`, omit feature-only assets, and prove that no session or API request occurs.
- Do not leave a query-string override in the regular activation path; it can bypass the server-authoritative flag and makes tests validate a path users do not run.
- Exactly one client component owns `POST /api/.../browser-session`. A general page client and a feature client must never both bootstrap the same session.
- Test 20 sequential page loads when bootstrap races are plausible. Assert one bootstrap per load and zero 403 responses.

## Asynchronous UI races

Two recurring hazards:

1. A target listener can observe state before an ancestor bubble listener updates ARIA/state. A microtask may still run before the full event dispatch finishes. Prefer one state owner; otherwise defer with a later task or call a shared state transition explicitly.
2. An older request can finish after a newer mode/range request and overwrite the UI. Increment a request generation at refresh start and discard results whose generation is no longer current.

Acceptance must check the final mode in the chart contract, not only the button's `aria-pressed` value.

## Medical reference-band rendering

- Draw a global band only when every observed point has a verified reference and all verified `(min,max,source)` tuples are identical.
- When verified ranges differ, render observation-specific or bounded time segments rather than one global band.
- A point marked `missing_reference` never contributes to a band or segment.
- Keep baseline and reference semantics distinct: a personal past-only baseline is not a laboratory reference interval.
- Add deterministic synthetic chart-contract tests for uniform ranges, changing ranges, missing references, and baseline series.

## Test-matrix ownership

- Standard page suite: proves feature assets, session bootstrap, and API requests are absent when disabled.
- Session suite: proves HttpOnly/SameSite/path/CSP behavior and no Basic/Bearer exposure.
- Feature suite: proves regular URL activation from rendered flag, bootstrap count, race resistance, events, point-to-ISO-day hook, chart contract, and narrow-screen table fallback.
- If Chromium reports a bootstrap request peculiarity, do not silently ignore all request failures. Move that endpoint's behavioral assertion to the dedicated session suite and keep general request-failure checks for every other request.