docs/decisions/0000-template.md

# NNNN. Title stating the decision as a fact

<!-- Good: "Clicks scroll elements into view before interacting"
     Bad:  "Click behavior" -->

- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->
- Date: YYYY-MM-DD <!-- date the status last changed -->
- 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.

## 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. Use code sketches per
language here if the API shape is part of what's being decided.

## Considered options

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

<!-- Options must be mutually exclusive answers to the question stated in Context; if two
     options could both be adopted, they are separate decisions and the document should be
     split. 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.

## Binding status

<!-- Update this table as bindings converge on the decision; table updates don't need
     TLC review. "n/a" with a note if the decision doesn't apply to a binding. -->

| Binding    | Status  | Notes / tracking link |
|------------|---------|-----------------------|
| Java       | pending |                       |
| Python     | pending |                       |
| Ruby       | pending |                       |
| .NET       | pending |                       |
| JavaScript | pending |                       |

## 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.