Add OpaqueRange interface by stephanieyzhang · Pull Request #1404 · whatwg/dom

stephanieyzhang · 2025-09-12T13:58:15Z

OpaqueRange is a specialized, live AbstractRange subtype whose boundary points reference internal nodes within host-defined elements (e.g., <input>/<textarea> today, with a path to custom elements in the future). It enables range-based operations over encapsulated content while avoiding exposure of internal DOM nodes. This PR also updates AbstractRange so startContainer/endContainer are nullable (Node?), which allows OpaqueRange to return null for those getters while Range/StaticRange continue returning nodes.

Explainer: https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/OpaqueRange/explainer.md
WHATWG Discussion: OpaqueRange Interface html#11478
Corresponding HTML Spec PR: Integrate OpaqueRange hooks into text controls (input/textarea) html#11741
Corresponding CSSOM PRs:
- [cssom-view-1] Define OpaqueRange geometry APIs (getClientRects/getBoundingClientRect) w3c/csswg-drafts#12904
- [css-highlight-api-1] Integrate OpaqueRange into Highlight and highlightsFromPoint w3c/csswg-drafts#13929
At least two implementers are interested (and none opposed):
Tests are written and can be reviewed and commented upon at:
- https://wpt.fyi/results/dom/ranges/tentative?label=master&label=experimental&aligned
- PR to make tests non-tentative: Coming soon
Implementation bugs are filed:
- Chromium: https://issues.chromium.org/issues/421421332
- Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=1990256
- WebKit: https://bugs.webkit.org/show_bug.cgi?id=299375
MDN issue is filed: …
The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

Preview | Diff

dandclark

Great to see a spec for this coming together!

rniwa · 2025-09-29T17:13:08Z

FWIW, I'd rather extend Range so that it can work with shadow host in general instead of creating a new interface specifically for form controls.

stephanieyzhang · 2025-09-30T20:10:42Z

FWIW, I'd rather extend Range so that it can work with shadow host in general instead of creating a new interface specifically for form controls.

We explored extending Range, including shadow host support, but found compatibility and encapsulation issues that made it risky to change existing Range semantics. Based on feedback across discussions, we went with a dedicated FormControlRange instead. The trade-offs and alternatives are covered in the explainer.

rniwa · 2025-09-30T20:43:22Z

FWIW, I'd rather extend Range so that it can work with shadow host in general instead of creating a new interface specifically for form controls.

We explored extending Range, including shadow host support, but found compatibility and encapsulation issues that made it risky to change existing Range semantics. Based on feedback across discussions, we went with a dedicated FormControlRange instead. The trade-offs and alternatives are covered in the explainer.

Changing the behavior of setStart/setEnd wouldn't be an only way to solve this problem. I'd instead add a new argument or a new function which specifies "offset" within element's shadow tree.

dandclark

This is looking good! Next big steps will be defining the right integration points from the HTML spec, and working towards consensus on the API shape.

dandclark · 2025-09-30T21:37:56Z

+ <a>this</a>'s <a for=FormControlRange>end offset</a> to <var>endOffset</var>.
+</ol>
+
+<p>If an {{HTMLInputElement}}'s <code>type</code> changes to a type that does not


(this, too, will likely need to be something that we'll need to put in the HTML spec)

dandclark · 2025-09-30T22:09:46Z

Changing the behavior of setStart/setEnd wouldn't be an only way to solve this problem. I'd instead add a new argument or a new function which specifies "offset" within element's shadow tree.

@rniwa Thanks for the feedback! Yeah, there are a lot of ways this could be done. This suggestion sounds closer to the 2nd considered approach here. There are enough differences in how a Range inside a builtin element would work vs a "normal" range that we believe it will be overall cleaner and less confusing to split the functionality into a different type. For example the behavior we propose here is that a FormControlRange can't have one boundary point inside a <textarea>/<input> and another boundary point outside, which would be a clumsier invariant to express with the Range API surface. Adding this to Range would also add confusion about what things like Range.selectNodeContents should do; should it move the range to select an <input>'s value string, or not? We could add a parameter to all the setter functions to switch the behavior, but again it seems cleaner to relegate the behavior to a different interface vs adding parameters to a bunch of Range functions.

Anyway, whatwg/html#11478 is a better place to have this discussion -- more folks are following that issue vs this draft PR. @stephanieyzhang it might be helpful if you could update the PR description for this to point to that issue, as well as a direct link to the explainer.

…into fcr-initial

smaug---- · 2026-02-10T22:18:20Z

+interface OpaqueRange : AbstractRange {
+  DOMRectList getClientRects();
+  DOMRect getBoundingClientRect();
+};


Is there a reason why OpaqueRange offsets are readonly? Or there isn't any method to update them?

The offsets are readonly since they're inherited from AbstractRange. Currently the HTML PR defines createValueRange(start, end) on the element for creation. We haven't yet added an API for updating, so that's an open question. Some options could be an element-side API (e.g. updateValueRange(range, start, end)) to keep OpaqueRange generic, or setters directly on OpaqueRange.

Would appreciate your thoughts @annevk @smaug----

I think we actually don't want to expose the offsets as per my other comment. I'm not sure if we want to expose collapsed. Perhaps it should just be separate from AbstractRange.

Implement disconnect() per WHATWG DOM spec PR #1404 [0]. Detaches the range from its element, stopping live offset updates and zeroing offsets. Calling it multiple times is safe and has no additional effect. Adds WPT tests covering disconnect behavior. Automatic disconnection when the element is removed from the tree or changes type will be handled in a follow-up CL. [0] whatwg/dom#1404 (comment) Low-Coverage-Reason: COVERAGE_UNDERREPORTED Bug: 421421332 Change-Id: I6f0bb55d57f1eb1876779faad018a19d23b1d665 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7595177 Reviewed-by: Dan Clark <daniec@microsoft.com> Commit-Queue: Stephanie Zhang <stephanie.zhang@microsoft.com> Reviewed-by: Ana Sollano Kim <ansollan@microsoft.com> Reviewed-by: Mason Freed <masonf@chromium.org> Cr-Commit-Position: refs/heads/main@{#1588113}

…estonly Automatic update from web-platform-tests Add OpaqueRange disconnect() method Implement disconnect() per WHATWG DOM spec PR #1404 [0]. Detaches the range from its element, stopping live offset updates and zeroing offsets. Calling it multiple times is safe and has no additional effect. Adds WPT tests covering disconnect behavior. Automatic disconnection when the element is removed from the tree or changes type will be handled in a follow-up CL. [0] whatwg/dom#1404 (comment) Low-Coverage-Reason: COVERAGE_UNDERREPORTED Bug: 421421332 Change-Id: I6f0bb55d57f1eb1876779faad018a19d23b1d665 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7595177 Reviewed-by: Dan Clark <daniec@microsoft.com> Commit-Queue: Stephanie Zhang <stephanie.zhang@microsoft.com> Reviewed-by: Ana Sollano Kim <ansollan@microsoft.com> Reviewed-by: Mason Freed <masonf@chromium.org> Cr-Commit-Position: refs/heads/main@{#1588113} -- wpt-commits: 60a655bbbf88ba39ae3959de9e405c4284dd0eba wpt-pr: 57954

Co-authored-by: Copilot <copilot@github.com>

annevk · 2026-05-08T09:47:49Z

 <dfn export id=concept-range-end-offset for=range>end offset</dfn> is its <a for=range>end</a>'s
 <a for="boundary point">offset</a>.

+<p>A <a>range</a> has an associated <dfn export for=range id=concept-range-is-opaque>is opaque</dfn>


associated boolean*

We don't want flags anymore.

annevk · 2026-05-08T09:48:31Z

+flag, initially false. When true, the {{AbstractRange/startContainer}} and
+{{AbstractRange/endContainer}} getters return null. Only {{OpaqueRange}} objects have this flag set
+to true.


This second bit should probably be in a note.

annevk · 2026-05-08T09:49:43Z

 interface AbstractRange {
-  readonly attribute Node startContainer;
+  readonly attribute Node? startContainer;
  readonly attribute unsigned long startOffset;


Does it make sense to expose startOffset and endOffset if this range potentially spans multiple nodes? They will not have meaningful values I think for opaque ranges.

annevk · 2026-05-08T09:50:31Z

+</pre>
+
+<p>Objects implementing the {{OpaqueRange}} interface are known as {{OpaqueRange}} objects.
+{{OpaqueRange}} objects cannot be constructed directly; they are created by specifications defining


I thought we would have a constructor so people can create these for custom elements?

annevk · 2026-05-08T09:53:45Z

+interface OpaqueRange : AbstractRange {
+  DOMRectList getClientRects();
+  DOMRect getBoundingClientRect();
+};


I think we actually don't want to expose the offsets as per my other comment. I'm not sure if we want to expose collapsed. Perhaps it should just be separate from AbstractRange.

annevk · 2026-05-08T09:57:43Z

+
+<p>An {{OpaqueRange}} has an
+<dfn export for=OpaqueRange>associated element</dfn> (an {{Element}} or null), initially null. It is
+set by the specification that creates the {{OpaqueRange}}.


Why do we need this and disconnect()? Can't that be with the APIs that vend OpaqueRange objects? It's also a bit unclear what disconnecting means beyond that, maybe in part because this doesn't actually integrate with the tree mutation algorithms yet.

annevk · 2026-05-08T09:58:51Z

+
+<p>An {{Element}}
+<dfn export id=supports-opaque-range>supports opaque ranges</dfn> if its specification defines that
+it does. In HTML, this includes certain {{HTMLInputElement}} types and {{HTMLTextAreaElement}}.


I'm not sure why we need this concept.

annevk · 2026-05-08T10:01:03Z

+
+<p class=note>Other specifications can designate additional elements, including custom elements.
+
+<p>An {{OpaqueRange}} is live, meaning its offsets are automatically updated when the underlying


I think we should define this very differently. We should define opaque ranges the same way we define live ranges. And then in HTML we should say that these elements have some kind of underlying Text node that this opaque range "exposes".

The reason for that is because we want opaque ranges to be a generic container. And the way you have specified them they are still very much restricted to specific elements.

annevk · 2026-05-08T10:05:22Z

It also seems this needs some rebasing.

Implement disconnect() per WHATWG DOM spec PR #1404 [0]. Detaches the range from its element, stopping live offset updates and zeroing offsets. Calling it multiple times is safe and has no additional effect. Adds WPT tests covering disconnect behavior. Automatic disconnection when the element is removed from the tree or changes type will be handled in a follow-up CL. [0] whatwg/dom#1404 (comment) Low-Coverage-Reason: COVERAGE_UNDERREPORTED Bug: 421421332 Change-Id: I6f0bb55d57f1eb1876779faad018a19d23b1d665 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7595177 Reviewed-by: Dan Clark <daniec@microsoft.com> Commit-Queue: Stephanie Zhang <stephanie.zhang@microsoft.com> Reviewed-by: Ana Sollano Kim <ansollan@microsoft.com> Reviewed-by: Mason Freed <masonf@chromium.org> Cr-Commit-Position: refs/heads/main@{#1588113}

initial changes

e19d60b

stephanieyzhang changed the title ~~initial changes~~ Add FormControlRange interface Sep 23, 2025

update to match format of other ranges

d7b3bee

dandclark reviewed Sep 26, 2025

View reviewed changes

stephanieyzhang added 2 commits September 29, 2025 11:27

address dan's comments

05b6b0a

formatting

e5b3361

stephanieyzhang added 2 commits September 29, 2025 13:19

pt 2 of Dan's comments

55b34b7

remove commit-sha

9858599

dandclark reviewed Sep 30, 2025

View reviewed changes

fixes for dan's comments

f65c447

This was referenced Oct 9, 2025

[cssom-view-1] Define OpaqueRange geometry APIs (getClientRects/getBoundingClientRect) w3c/csswg-drafts#12904

Draft

Integrate OpaqueRange hooks into text controls (input/textarea) whatwg/html#11741

Open

OpaqueRange Interface whatwg/html#11478

Open

stephanieyzhang added 2 commits October 16, 2025 14:38

add geometry methods

a6c4f52

rename to PlainTextRange + tpac changes

c947ca1

stephanieyzhang changed the title ~~Add FormControlRange interface~~ Add PlainTextRange interface Dec 4, 2025

annevk reviewed Dec 8, 2025

View reviewed changes

Comment thread dom.bs Outdated

Comment thread dom.bs Outdated

Comment thread dom.bs Outdated

Comment thread dom.bs Outdated

stephanieyzhang mentioned this pull request Dec 8, 2025

Rename FormControlRange to OpaqueRange and incorporate TPAC design feedback MicrosoftEdge/MSEdgeExplainers#1204

Merged

Merge branch 'whatwg:main' into fcr-initial

3d5050a

stephanieyzhang changed the title ~~Add PlainTextRange interface~~ Add OpaqueRange interface Jan 14, 2026

stephanieyzhang added 3 commits January 14, 2026 11:04

add OpaqueRange + allow null AbstractRange containers

96e153b

Merge branch 'fcr-initial' of https://github.com/stephanieyzhang/dom …

da26d0a

…into fcr-initial

remove explicit 'opaque range string'

cf4259e

cleanup redundancies between abstractrange and opaquerange

b3108ac

stephanieyzhang mentioned this pull request Feb 10, 2026

Align OpaqueRange explainer with DOM and HTML spec PRs MicrosoftEdge/MSEdgeExplainers#1248

Merged

smaug---- reviewed Feb 10, 2026

View reviewed changes

smaug---- reviewed Feb 11, 2026

View reviewed changes

Comment thread dom.bs

chromium-wpt-export-bot mentioned this pull request Feb 20, 2026

Add OpaqueRange disconnect() method web-platform-tests/wpt#57954

Merged

This was referenced Mar 13, 2026

New feature ID for OpaqueRange web-platform-dx/web-features#3863

Closed

Other Spec Review: OpaqueRange w3ctag/design-reviews#1206

Open

stephanieyzhang marked this pull request as ready for review April 23, 2026 16:07

stephanieyzhang and others added 2 commits April 27, 2026 16:57

add disconnect

b95b1b6

Co-authored-by: Copilot <copilot@github.com>

add mutationobserver to fix disconnect build break

8ea58fc

Co-authored-by: Copilot <copilot@github.com>

stephanieyzhang mentioned this pull request Apr 28, 2026

Add disconnect() method MicrosoftEdge/MSEdgeExplainers#1310

Merged

annevk reviewed May 8, 2026

View reviewed changes

Merge branch 'whatwg:main' into fcr-initial

72acd04

stephanieyzhang mentioned this pull request May 15, 2026

[css-highlight-api-1] Integrate OpaqueRange into Highlight and highlightsFromPoint w3c/csswg-drafts#13929

Open


		<p class=note>Other specifications can designate additional elements, including custom elements.

		<p>An {{OpaqueRange}} is live, meaning its offsets are automatically updated when the underlying

Conversation

stephanieyzhang commented Sep 12, 2025 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dandclark left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rniwa commented Sep 29, 2025

Uh oh!

stephanieyzhang commented Sep 30, 2025

Uh oh!

rniwa commented Sep 30, 2025

Uh oh!

dandclark left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dandclark commented Sep 30, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephanieyzhang Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

annevk commented May 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

5 participants

stephanieyzhang commented Sep 12, 2025 •

edited by pr-preview Bot

Loading

stephanieyzhang Feb 12, 2026 •

edited

Loading