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

💥 Error: 422 Unprocessable Entity 💥

PR Preview failed to build. (Last tried on May 18, 2026, 4:25 PM UTC).

More

PR Preview relies on a number of web services to run. There seems to be an issue with the following one:

🚨 Spec Generator - Spec Generator is the web service used to build bikeshed/ReSpec specs

🔗 Related URL

Error output:

[
    {
        "lineNum": null,
        "messageType": "warning",
        "text": "Multiple elements have the same id 'concept-range-is-opaque':\n  <dfn> on line 8691:37, <dfn> on line 8707:37\nDeduping, but this ID may not be stable across revisions."
    },
    {
        "lineNum": "8707:37",
        "messageType": "fatal",
        "text": "Multiple local 'dfn' <dfn>s for 'range' have the same linking text 'is opaque'."
    },
    {
        "lineNum": null,
        "messageType": "failure",
        "text": "Did not generate, due to errors exceeding the allowed error level."
    }
]

This seems to be an issue with the Spec Generator service. PR Preview doesn't manage this service and so has no control over it. If you've identified an issue with it, you can report the issue to the maintainers of Spec Generator directly. Please be courteous. Thank you!

If you don't have enough information above to solve the error by yourself or if the issue doesn't seem related to Spec Generator, you can file an issue with PR Preview.

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

For form controls, they're indices into the value string, even when the range spans multiple nodes. I'm unsure of how this would look for custom elements though.

I've gotten feedback from people testing OpaqueRange on Chromium (e.g. Microsoft Editor SDK) that they rely on the offsets, using value.substring(range.startOffset, range.endOffset) in place of toString(), and comparing the caret index against the offsets to test inside/outside. Dropping them would require a workaround.

I think that means we need a valueFromRange() API or some such on input and textarea. Since the input element or textarea element allocated the OpaqueRange they will know what it contains and can thus answer such a question (if they want to). That would correctly preserve encapsulation and keep the design generic.

And as this range will have to point to the conceptual Text node of the element, the element can naturally only answer the API call for ranges that it created itself.

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?

For custom elements, I was thinking something like ElementInternals.createOpaqueRange(...) instead of a constructor. It ties creation to the element that owns the value (mirroring createValueRange() on form controls) and avoids having a "host-less" OpaqueRange.

We can have a constructor with a mandatory argument?

To make sure I'm understanding things correctly and that we're aligned:

Are we keeping createValueRange() on <input> and <textarea> as the vending API for form controls?

And then adding new OpaqueRange({startContainer: node, ...}) as a separate constructor for custom elements?

Where does ElementInternals.createOpaqueRange(...) fit, if at all? Or do authors just use the constructor directly for custom-elements?

For <input>/<textarea> specifically, which API would devs be expected to use: createValueRange() or the constructor?

Yes, that makes sense to me.

Yes.

We should not need anything on ElementInternals. Web developers can use the constructor and expose APIs such as createValueRange() on their elements as they see fit. Including the more complicated ranges that expose more than just a (conceptual) Text node.

They can't use the constructor because they don't have access to the conceptual Text node. Only input and textarea have access to that information and can thus create the range. As such web developers will have to go through createValueRange().

What does creating a new OpaqueRange(...) really mean? How would a custom element indicate what kind of value getClientRects as an example should return.

(Hmm, is OpaqueRange kind of a proxy object, and then there should be the other side of the thing which affects how it behaves. In case of input and textarea, that other side is native and with Custom Elements it would need to be JS based, maybe. Just mumbling aloud.)

Yeah perhaps we need to go having an OpaqueRangeController (or OpaqueRangeInternals) directly if we offer a constructor. Basically an object that allows you to manipulate the internal values. Either using the revealing constructor pattern or doing something similar to AbortController. I was initially thinking that it might be sufficient if you can just indicate start and end and have the remainder fall out of it being live, but maybe not.

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

Closed

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

rename "is opaque" flag to associated boolean and convert to note

ef8b1eb

stephanieyzhang mentioned this pull request May 28, 2026

OpaqueRange: cross-post from whatwg/html#11478 for DOM community input #1468

Open

annevk linked an issue May 29, 2026 that may be closed by this pull request

OpaqueRange: cross-post from whatwg/html#11478 for DOM community input #1468

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!

💥 Error: 422 Unprocessable Entity 💥

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!

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!

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

stephanieyzhang commented Sep 12, 2025 •

edited by pr-preview Bot

Loading

stephanieyzhang Feb 12, 2026 •

edited

Loading