From 8b32c9f4654a29749aec912dd5c116d9120c0eeb Mon Sep 17 00:00:00 2001
From: Josh Vlk <josh@vlkpack.com>
Date: Mon, 3 Aug 2026 14:21:47 -0400
Subject: [PATCH 1/3] refactor: introduce DOMTree foundation

---
 rescript.json              |  1 +
 src/DOM/DOMStringMap.res   |  5 +++++
 src/DOM/DOMTree.res        | 20 ++++++++++++++++++++
 src/DOM/HTMLCollection.res | 16 ++++++++++++++--
 4 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 src/DOM/DOMStringMap.res
 create mode 100644 src/DOM/DOMTree.res

diff --git a/rescript.json b/rescript.json
index 0b45fbdf..050c31e5 100644
--- a/rescript.json
+++ b/rescript.json
@@ -95,6 +95,7 @@
         "DOMRectReadOnly",
         "DOMStringList",
         "DOMTokenList",
+        "DOMTree",
         "Document",
         "DocumentFragment",
         "DocumentTimeline",
diff --git a/src/DOM/DOMStringMap.res b/src/DOM/DOMStringMap.res
new file mode 100644
index 00000000..c37a79a6
--- /dev/null
+++ b/src/DOM/DOMStringMap.res
@@ -0,0 +1,5 @@
+/**
+Used by the dataset HTML attribute to represent data for custom attributes added to elements.
+[See DOMStringMap on MDN](https://developer.mozilla.org/docs/Web/API/DOMStringMap)
+*/
+type t = {}
diff --git a/src/DOM/DOMTree.res b/src/DOM/DOMTree.res
new file mode 100644
index 00000000..facea8f9
--- /dev/null
+++ b/src/DOM/DOMTree.res
@@ -0,0 +1,20 @@
+/**
+ * Compatibility aliases for the recursive DOM interface family.
+ *
+ * Keeping these aliases in one module lets interface modules migrate from
+ * DOM/DomTypes independently. The aliases are replaced with the concrete
+ * recursive definitions once all consumers use DOMTree.
+ */
+type shadowRootMode = DOM.shadowRootMode
+type slotAssignmentMode = DOM.slotAssignmentMode
+type customStateSet = DOM.customStateSet
+
+type node = DOM.node
+type element = DOM.element
+type documentFragment = DOM.documentFragment
+type shadowRoot = DOM.shadowRoot
+type htmlElement = DOM.htmlElement
+type htmlFormElement = DOM.htmlFormElement
+type htmlFormControlsCollection = DOM.htmlFormControlsCollection
+type htmlSlotElement = DOM.htmlSlotElement
+type elementInternals = DOM.elementInternals
diff --git a/src/DOM/HTMLCollection.res b/src/DOM/HTMLCollection.res
index 5a387983..94861cdd 100644
--- a/src/DOM/HTMLCollection.res
+++ b/src/DOM/HTMLCollection.res
@@ -1,13 +1,25 @@
+/**
+A generic collection (array-like object similar to arguments) of elements (in document order) and offers methods and properties for selecting from the list.
+[See HTMLCollection on MDN](https://developer.mozilla.org/docs/Web/API/HTMLCollection)
+*/
+type t<'item> = private {
+  /**
+    Sets or retrieves the number of objects in a collection.
+    [Read more on MDN](https://developer.mozilla.org/docs/Web/API/HTMLCollection/length)
+    */
+  length: int,
+}
+
 /**
 Retrieves an object from various collections.
 [Read more on MDN](https://developer.mozilla.org/docs/Web/API/HTMLCollection/item)
 */
 @send
-external item: (DomTypes.htmlCollection<'t>, int) => 't = "item"
+external item: (t<'item>, int) => 'item = "item"
 
 /**
 Retrieves a select object or an object from an options collection.
 [Read more on MDN](https://developer.mozilla.org/docs/Web/API/HTMLCollection/namedItem)
 */
 @send
-external namedItem: (DomTypes.htmlCollection<'t>, string) => 't = "namedItem"
+external namedItem: (t<'item>, string) => 'item = "namedItem"

From cae019a6fe06b56f9a25d2f64fd6dcc8c669f0ad Mon Sep 17 00:00:00 2001
From: Josh Vlk <josh@vlkpack.com>
Date: Thu, 6 Aug 2026 16:01:38 -0400
Subject: [PATCH 2/3] Apply suggestion from @jderochervlk

---
 src/DOM/DOMStringMap.res | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/DOM/DOMStringMap.res b/src/DOM/DOMStringMap.res
index c37a79a6..639c8bce 100644
--- a/src/DOM/DOMStringMap.res
+++ b/src/DOM/DOMStringMap.res
@@ -2,4 +2,4 @@
 Used by the dataset HTML attribute to represent data for custom attributes added to elements.
 [See DOMStringMap on MDN](https://developer.mozilla.org/docs/Web/API/DOMStringMap)
 */
-type t = {}
+type t = private {}

From fc6076a9cfff5fcbe1a78936c2d797921eb67c05 Mon Sep 17 00:00:00 2001
From: Josh Vlk <josh@vlkpack.com>
Date: Thu, 6 Aug 2026 16:07:21 -0400
Subject: [PATCH 3/3] docs: clarify DOMTree alias lifecycle

---
 src/DOM/DOMTree.res | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/DOM/DOMTree.res b/src/DOM/DOMTree.res
index facea8f9..fc81c0cb 100644
--- a/src/DOM/DOMTree.res
+++ b/src/DOM/DOMTree.res
@@ -1,9 +1,10 @@
 /**
  * Compatibility aliases for the recursive DOM interface family.
  *
- * Keeping these aliases in one module lets interface modules migrate from
- * DOM/DomTypes independently. The aliases are replaced with the concrete
- * recursive definitions once all consumers use DOMTree.
+ * DOMTree and these public type names are permanent; only the aliases below
+ * are temporary. PRs #302 through #308 migrate consumers from DOM/DomTypes,
+ * then PR #310 replaces the aliases in place with concrete recursive
+ * definitions and removes their old DOM/DomTypes definitions.
  */
 type shadowRootMode = DOM.shadowRootMode
 type slotAssignmentMode = DOM.slotAssignmentMode