Document children() child indexes

Author: ItsMeSamey

README.md

@@ -110,6 +110,8 @@ Two bundles are used by the benchmark harness and conformance runner:
 - eager child views off (child views are built lazily if `children()` is called)
 - drop whitespace-only text nodes during parse
 
+`children()` returns a borrowed `[]const u32` index slice into the document's node array.
+
 ## Selector Support (v1)
 
 Supported (intentionally limited scope):

docs/api-reference.md

@@ -46,6 +46,7 @@ Content/attributes:
 - `getAttributeValue(name)`
 - `innerText(arena_allocator)`
 - `innerTextWithOptions(arena_allocator, TextOptions)`
+- `children()` returns borrowed `[]const u32` child indexes
 
 Scoped query entrypoints:
 

docs/architecture.md

@@ -26,4 +26,4 @@
 
 - Parser is permissive and attempts recovery for malformed markup.
 - Raw-text elements and optional-close behavior use table/tag-aware logic.
-- Parse options can defer attribute parsing and child-view materialization when needed.
+- Parse options currently tune child-view eagerness and whitespace-only text-node dropping.

examples/navigation_and_children.zig

@@ -19,6 +19,9 @@ fn run() !void {
 
     const children = main.children();
     try std.testing.expectEqual(@as(usize, 3), children.len);
+    const first_idx = children[0];
+    const first_via_index = main.doc.nodeAt(first_idx) orelse return error.TestUnexpectedResult;
+    try std.testing.expectEqualStrings("title", first_via_index.getAttributeValue("id").?);
 }
 
 test "navigation and borrowed children slice" {

src/examples_tests.zig

@@ -63,7 +63,10 @@ test "example parity: navigation and children" {
 
     try std.testing.expectEqualStrings("title", first.getAttributeValue("id").?);
     try std.testing.expectEqualStrings("body", last.getAttributeValue("id").?);
-    try std.testing.expectEqual(@as(usize, 3), main.children().len);
+    const children = main.children();
+    try std.testing.expectEqual(@as(usize, 3), children.len);
+    const first_via_index = main.doc.nodeAt(children[0]) orelse return error.TestUnexpectedResult;
+    try std.testing.expectEqualStrings("title", first_via_index.getAttributeValue("id").?);
 }
 
 test "example parity: innerText options" {