docs: document dom query helpers

tritao · tritao · commit 442045284592 · 2026-01-28T01:10:52.000Z
diff --git a/docs/api/dom.md b/docs/api/dom.md
@@ -18,14 +18,111 @@ Gets a handle to the `<body>` element of the document.
 webcc::DOMElement get_body();
 ```
 
+### `get_active_element`
+
+Gets a handle to the currently focused element (`document.activeElement`).
+Returns an invalid handle (`-1`) if no active element exists.
+
+```cpp
+webcc::DOMElement get_active_element();
+```
+
 ### `get_element_by_id`
 
 Gets a handle to an element by its ID.
+Returns an invalid handle (`-1`) if the element does not exist.
 
 ```cpp
 webcc::DOMElement get_element_by_id(webcc::string_view id);
 ```
 
+### `get_parent_node`
+
+Gets the parent element of a node.
+Returns an invalid handle (`-1`) if the node has no parent element.
+
+```cpp
+webcc::DOMElement get_parent_node(webcc::DOMElement node_handle);
+```
+
+### `is_connected`
+
+Returns true if the node is currently connected to the document.
+
+```cpp
+bool is_connected(webcc::DOMElement node_handle);
+```
+
+### `is_valid`
+
+Returns true if the handle currently refers to a valid DOM element.
+This is useful for checking results of selector-based APIs which can return `-1`.
+
+```cpp
+bool is_valid(webcc::DOMElement handle);
+```
+
+### `contains`
+
+Returns true if `container` contains `other` in the DOM tree.
+
+```cpp
+bool contains(webcc::DOMElement container_handle, webcc::DOMElement other_handle);
+```
+
+### `query_selector`
+
+Queries a descendant element using a CSS selector.
+Returns an invalid handle (`-1`) if nothing matches.
+
+```cpp
+webcc::DOMElement query_selector(webcc::DOMElement root_handle, webcc::string_view selector);
+```
+
+### `closest`
+
+Returns the closest ancestor (including the node itself) that matches a selector.
+Returns an invalid handle (`-1`) if nothing matches.
+
+```cpp
+webcc::DOMElement closest(webcc::DOMElement node_handle, webcc::string_view selector);
+```
+
+### `query_selector_all_count`
+
+Returns the number of matches for a CSS selector under `root`.
+
+```cpp
+int32_t query_selector_all_count(webcc::DOMElement root_handle, webcc::string_view selector);
+```
+
+### `query_selector_all_fill`
+
+Fills a contiguous range of handles with the results of `querySelectorAll`.
+Use `webcc::reserve_deferred_handles(count)` to reserve `[start, start+count)` and then convert
+entries back to `webcc::DOMElement` via `webcc::DOMElement(start + i)`.
+
+```cpp
+void query_selector_all_fill(webcc::DOMElement root_handle, webcc::string_view selector, int32_t start, int32_t count);
+```
+
+### `child_element_count`
+
+Returns the number of element children of `root`.
+
+```cpp
+int32_t child_element_count(webcc::DOMElement root_handle);
+```
+
+### `child_element_fill`
+
+Fills a contiguous range of handles with the element children of `root`.
+Use `webcc::reserve_deferred_handles(count)` to reserve `[start, start+count)`.
+
+```cpp
+void child_element_fill(webcc::DOMElement root_handle, int32_t start, int32_t count);
+```
+
 ### `create_element`
 
 Creates a new HTML element with the specified tag name.
@@ -180,3 +277,9 @@ inline int32_t next_deferred_handle() {
     return counter++;
 }
 ```
+
+To reserve a contiguous range (useful for fill-style APIs):
+
+```cpp
+inline int32_t reserve_deferred_handles(int32_t count);
+```
diff --git a/docs/api/websocket.md b/docs/api/websocket.md
@@ -20,6 +20,14 @@ webcc::WebSocket connect(webcc::string_view url);
 
 All events (message, open, close, error) are automatically subscribed.
 
+### `is_connected`
+
+Returns true if the WebSocket exists and is currently open.
+
+```cpp
+bool is_connected(webcc::WebSocket handle);
+```
+
 ### `send`
 
 Sends a text message over the WebSocket connection.
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -55,6 +55,13 @@ webcc::flush();
 
 Deferred handles start at `0x100000` and increment upward, while JS-assigned handles use lower values, ensuring no collisions. This pattern is essential for high-performance DOM manipulation.
 
+For APIs that need a contiguous range (e.g. `*_fill` APIs), use:
+
+```cpp
+int32_t start = webcc::reserve_deferred_handles(count);
+// range is [start, start+count)
+```
+
 ## C++ Standard Library Compatibility
 WebCC provides a lightweight compatibility layer for common C++ Standard Library headers (located in `include/webcc/compat/`). 
 
