docs: document option 2 DOM API shape

Author: codex

docs/content/docs/api-surface.mdx

@@ -37,8 +37,9 @@ Global singleton APIs such as `Location`, `Crypto`, and `Performance` expose dir
 functions and properties. Object-owned APIs still use the value as the receiver.
 
 ```ReScript
+let href = WebAPI.Location.href
 let location = WebAPI.Location.current
-let href = location.href
+let sameHref = location.href
 
 WebAPI.Location.reload()
 ```
@@ -51,8 +52,7 @@ helper modules.
 ```ReScript
 let req: WebAPI.Request.t = WebAPI.Request.fromURL("https://example.com")
 let headers = WebAPI.Headers.make()
-let document = WebAPI.Window.current->WebAPI.Window.document
-let element = document->WebAPI.Document.createElement("button")
+let element: WebAPI.Element.t = WebAPI.Document.createElement("button")
 ```
 
 With `"-open WebAPI"`, the same modules can be referenced without the `WebAPI.` prefix:
@@ -266,30 +266,24 @@ let redirect = WebAPI.Response.redirect(~url="/login", ~status=302)
 
 ## DOM
 
-DOM values are operated on through public interface modules.
-`WebAPI.Element` is the method module for element values. When you need to name the element type explicitly, use `WebAPI.DOM.element`; most examples can rely on inference from `Document.createElement`, `Document.querySelector`, and related DOM helpers.
+Common document entry points are exposed directly on `WebAPI.Document`, bound to
+`globalThis.document`. DOM object properties use dot syntax, and instance methods stay
+receiver-based through the owner module. When you need to name an element type explicitly,
+use `WebAPI.Element.t`.
 
 ```ReScript
-let document = WebAPI.Window.current->WebAPI.Window.document
-
-let maybeButton = document
-->WebAPI.Document.querySelector("button")
-->Null.toOption
-
-switch maybeButton {
-| Some(button) =>
-  switch button->WebAPI.Element.getAttribute("data-user-id") {
-  | Null.Value(id) => Console.log(id)
-  | Null => Console.log("anonymous")
-  }
-| None => Console.log("button not found")
-}
+let button: WebAPI.Element.t = WebAPI.Document.createElement("button")
+button.id = "save"
+button.className = "primary"
+button.innerHTML = "Save"
+button->WebAPI.Element.setAttribute(~qualifiedName="data-state", ~value="ready")
+let maybeButton = WebAPI.Document.querySelector("#save")->Null.toOption
 ```
 
 Use conversion helpers when moving between related DOM interface types.
 
 ```ReScript
-let element: WebAPI.DOM.element = document->WebAPI.Document.createElement("div")
+let element: WebAPI.Element.t = WebAPI.Document.createElement("div")
 let node = element->WebAPI.Element.asNode
 ```
 

docs/content/docs/contributing/api-module-structure.mdx

@@ -64,7 +64,14 @@ type rec node = {
 and element = Base__Element.t
 ```
 
-For shared DOM base interfaces such as `Element`, keep the root type as a thin opaque owner such as `Base__Element.t`. The DOM API module can expose `DOM.element` as a public alias while method modules use `DomTypes.element`.
+Public interface modules own their public `t` type. For example, `Element.res` exposes
+`Element.t`, `Document.res` exposes `Document.t`, and `Location.res` exposes `Location.t`.
+These public `t` types are the names consumers should use in annotations.
+
+When an interface needs a shared structural owner across APIs or inheritance chains, keep
+that shared shape in a base module such as `Base__Element.t`. The public interface module
+then aliases the base shape as its own `t`, while generated structural modules can keep
+using internal aliases such as `DomTypes.element` where needed.
 
 ## Auxiliary Types
 

docs/content/docs/contributing/module-type-structure.mdx

@@ -76,22 +76,26 @@ external checkValidity: htmlButtonElement => bool = "checkValidity"
 
 <Code code={buttonModule} title="DOMAPI/HTMLButtonElement.res" lang="ReScript"></Code>
 
-## Shared element base
+## Shared Object Bases
 
-`Element.res` is a method module. It does not define the `element` type directly. The shared DOM element type is a thin opaque base handle threaded back into DOM through aliases:
+Public interface modules expose their own `t` type even when the underlying shape is shared.
+For a shared DOM object base, keep the structural owner in a base module and make the public
+interface module a same-type alias of that base:
 
 ```ReScript
 // Base__Element.res
 type t = private {}
 
-// DomTypes.res
-type element = Base__Element.t = private {...Base__Element.t}
-
 // Element.res
-include Impl({type t = DomTypes.element})
+type t = Base__Element.t = {...Base__Element.t}
+
+// DomTypes.res
+type element = Base__Element.t = {...Base__Element.t}
 ```
 
-This keeps `Element.Impl` reusable for element subtypes while giving the package one shared base element handle. Subtype modules should continue to include the nearest base method implementation:
+This keeps `Element.t` as the public type name while still allowing generated DOM structural
+types to share the same object identity. `Element.Impl` remains reusable for element subtypes,
+and subtype modules should continue to include the nearest base method implementation:
 
 ```ReScript
 // HTMLElement.res
@@ -101,4 +105,4 @@ include Element.Impl({type t = DomTypes.htmlElement})
 include HTMLElement.Impl({type t = DomTypes.htmlButtonElement})
 ```
 
-Use `asElement` when a subtype needs to be passed to a function that expects the shared element type.
+Use `asElement` when a subtype needs to be passed to a function that expects `Element.t`.

docs/content/docs/philosophy.mdx

@@ -20,14 +20,12 @@ In other words, if you are searching for a specific JavaScript binding, begin yo
 The bindings are exposed under the `WebAPI` namespace with the same flat module structure as the original package.
 
 ```ReScript
-open WebAPI.DOM
-
-let myElement: WebAPI.DOM.element = document->WebAPI.Document.createElement("div")
+let myElement: WebAPI.Element.t = WebAPI.Document.createElement("div")
 let id = myElement.id
 ```
 
 Consumers can also configure `rescript.json` with `"compiler-flags": ["-open WebAPI"]`
-when they want to use modules such as `DOM`, `Document`, and `Element` without the
+when they want to use modules such as `Document`, `Element`, and `Location` without the
 `WebAPI.` prefix.
 
 ## Interfaces
@@ -40,7 +38,7 @@ Methods are modeled as functions in a separate module. The idea is that these wi
 
 Inherited methods are duplicated in the inheriting module to eliminate the need to cast the type to the base type.
 
-For DOM elements, `WebAPI.Element` is the method module. The element type itself is exposed as `WebAPI.DOM.element`. Most code does not need to annotate the type because functions such as `Document.createElement` and `Document.querySelector` already return it.
+For DOM elements, `WebAPI.Element.t` is the public element type and `WebAPI.Element` is the method module. Most code does not need to annotate the type because functions such as `Document.createElement` and `Document.querySelector` already return it.
 
 ### Overloads
 
@@ -51,9 +49,7 @@ JavaScript supports function overloads, where a function can have multiple signa
 In some cases, type conversion will be required. Subtypes can safely be cast to their base type using conversion helpers within their module.
 
 ```ReScript
-open WebAPI.DOM
-
-let element: WebAPI.DOM.element = document->WebAPI.Document.createElement("div")
+let element: WebAPI.Element.t = WebAPI.Document.createElement("div")
 let node = element->WebAPI.Element.asNode
 ```
 

tests/DOMAPI/HTMLInputElement__test.res

@@ -1,5 +1,4 @@
 external toHTMLInputElement: DomTypes.element => DomTypes.htmlInputElement = "%identity"
 
-let input: DomTypes.htmlInputElement =
-  Document.createElement("input")->toHTMLInputElement
+let input: DomTypes.htmlInputElement = Document.createElement("input")->toHTMLInputElement
 input->HTMLInputElement.checkValidity->ignore