docs/decisions/0000-template.md

# NNNN. Title stating the decision as a fact

<!-- NNNN is this proposal's PR number. Good title: "Clicks scroll elements into view before
     interacting"; bad: "Click behavior" -->

- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->
- Discussion: <!-- link to this record's PR; add prior issues/threads under Context -->

## Context

What problem are we solving, and what forces are in tension? W3C spec language, user
expectations, existing behavior that differs between bindings, implementation constraints.
Link prior discussions (issues, TLC notes) here as background — but summarize them, since
this section must make sense without following any links.

<!-- Optional: when bindings currently differ, a table makes the divergence concrete. This is
     the as-is state as of this decision (durable rationale) — NOT convergence tracking, which
     lives in the post-acceptance tracking issue. Delete it if the decision is greenfield or the
     bindings already behave the same. -->

| Binding    | Current behavior |
|------------|------------------|
| Java       |                  |
| Python     |                  |
| Ruby       |                  |
| .NET       |                  |
| JavaScript |                  |

## Decision

The decision, stated in language-neutral terms. This is the normative part: what every
binding MUST do, and what is explicitly left to per-language idiom. Record *what* and *why*,
not *how* — implementation lives in the adopting PRs. Use code sketches only to pin down the
API shape being decided, not to specify implementation.

## Considered options

- **Option A** — what it is; why it was rejected or accepted
- **Option B** — what it is; why it was rejected or accepted

<!-- List the alternatives to the decision above and why each was rejected. These are mutually
     exclusive answers to the same question, not a menu of separable features — a record may
     bundle related sub-choices (give each its own options); independent adoptability alone is
     not grounds to split it (see the README's scoping guidance). Revise this section during
     review as alternatives are contested or added — the merged record, not the PR thread, is
     the authoritative account of why each rejected option was not chosen. -->

## Consequences

What gets easier, what gets harder, what users will notice. Deprecations triggered by this
decision and their timelines. Follow-up decisions this one makes necessary.

<!-- Per-binding convergence is NOT tracked here. When this record is accepted, open an ADR
     tracking issue (the "ADR Implementation Tracking" issue template) with one checkbox per
     binding, and link it from this record's PR. Keeping it out of the committed record avoids
     churn on an otherwise immutable file. -->

## Appendix (optional)

Durable supporting material the decision relies on: benchmarks, spec excerpts, survey of
behavior in other tools. Delete this section if there is none — ephemeral evidence belongs
in the PR thread instead.