Release 4.2.0

- PUBLISH_VERSION 4.1.1 -> 4.2.0
- CHANGELOG: promote [Unreleased] -> [4.2.0] (2026-06-08) + compare link
- README: bump install snippets to 4.2.0

Adds the Android target for tree-structure and tree-structure-compose,
the default TreeNodeRow composable + LazyTree(label=...) overload, and a
runnable Android sample. All additive, no breaking changes.

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Docs
+
+on:
+  release:
+    types: [released]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Dokka HTML
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+      - name: Generate API docs
+        run: ./gradlew :dokkaGeneratePublicationHtml --console=plain
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/dokka/html
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publishRelease.yml

@@ -5,17 +5,21 @@ on:
     # We'll run this workflow when a new GitHub release is created
     types: [released]
 
+permissions:
+  contents: read
 
 jobs:
   test:
     uses: ./.github/workflows/test.yml
-    secrets: inherit
 
   publish:
     needs: test
     name: Publish Production
     environment: production
-    runs-on: ubuntu-latest
+    # MUST be macOS: Kotlin/Native Apple targets (iosArm64/iosX64/iosSimulatorArm64) can only be
+    # built on a macOS host. On a Linux runner those tasks are silently skipped, so the iOS klibs
+    # never get uploaded (the build still goes green) — exactly what happened for 3.1.5–4.1.0.
+    runs-on: macos-latest
     steps:
       - name: Check out code
         uses: actions/checkout@v4
@@ -24,8 +28,12 @@ jobs:
         with:
           distribution: temurin
           java-version: '21'
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
 
-        # Runs upload, and then closes & releases the repository
+        # Uploads & stages the release on Central Portal. The final "Publish"
+        # step is manual there, because build.gradle.kts sets
+        # publishToMavenCentral(automaticRelease = false).
       - name: Publish to MavenCentral
         run: ./gradlew publishToMavenCentral
         env:
@@ -33,4 +41,3 @@ jobs:
           ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
           ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.SIGNING_KEY }}
           ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.SIGNING_PASSWORD }}
-          SNAPSHOT: false

.github/workflows/test.yml

@@ -2,9 +2,17 @@ name: Test
 
 on:
   push:
-    branches-ignore: [master]
+    branches: [master]
+  pull_request:
   workflow_call:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   test:
     name: ${{ matrix.name }}
@@ -13,9 +21,9 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - name: JVM / JS / Wasm / Native + API check
+          - name: JVM / JS / Wasm / Native / Android + API check
             os: ubuntu-latest
-            tasks: jvmTest jsNodeTest wasmJsNodeTest nativeTest apiCheck
+            tasks: jvmTest jsNodeTest wasmJsNodeTest nativeTest :assembleRelease :tree-structure-compose:assembleRelease :samples-android:assembleDebug :samples:test :samples:run apiCheck
           - name: iOS
             os: macos-latest
             tasks: iosSimulatorArm64Test
@@ -27,5 +35,7 @@ jobs:
         with:
           distribution: temurin
           java-version: '21'
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
       - name: Test
         run: ./gradlew ${{ matrix.tasks }} --console=plain

.gitignore

@@ -1,5 +1,6 @@
 *.iml
 .gradle
+/.kotlin/
 /local.properties
 /.idea/caches
 /.idea/libraries
@@ -18,3 +19,6 @@ build/
 /.idea/jarRepositories.xml
 /.idea/deploymentTargetDropDown.xml
 /.idea/
+
+# Local superpowers working docs (design specs, plans) — not part of the repo
+docs/superpowers/

CHANGELOG.md

@@ -4,7 +4,48 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [4.2.0] - 2026-06-08
+
+### Added
+- **Android target.** The core `tree-structure` module and `tree-structure-compose` now publish an
+  `-android` variant (`minSdk` 21), so both can be consumed directly in Android projects.
+- `tree-structure-compose`: a foundation-only `TreeNodeRow` composable — a sensible default node row
+  (clickable, indented, with a `▾`/`▸` marker and no Material dependency) — plus a no-content
+  `LazyTree(root, label = …)` overload that renders each node with it. The existing lambda overload
+  is unchanged.
+- A runnable Android sample app in the new `samples` module, with `@Preview` composables.
+
+### Changed
+- Upgraded the Gradle wrapper to 8.10.2 and introduced Android Gradle Plugin 8.7.2 (`compileSdk` 35).
+  No source or behavior changes to existing targets.
+
+## [4.1.1] - 2026-06-08
+
+### Fixed
+- Restored the Apple/iOS artifacts (`iosArm64`, `iosX64`, `iosSimulatorArm64`) for the core and every
+  module. The release workflow published from a Linux runner, which cannot build Kotlin/Native Apple
+  targets, so they were silently omitted from 3.1.5–4.1.0; publishing now runs on macOS. No API or
+  behavior changes from 4.1.0 — this is a packaging fix only.
+
+## [4.1.0] - 2026-06-07
+
+### Added
+- Structural mutation helpers on `TreeNode`: `insertChild`, `removeChildAt`, `replaceChild`,
+  `moveChild`, `addChildren`, and `sortChildren`.
+- Tree query extensions: `lowestCommonAncestor`, `distance`, `pathBetween`, and `contains` for
+  finding common ancestors, edge distances, the path between two nodes, and value membership.
+- Customizable `prettyString(connectors, render)` extension: choose connector glyphs via
+  `TreeConnectors` (`Default` box-drawing or `Ascii`) and supply a per-node renderer that receives
+  the value, its depth and whether it is its parent's last child. The all-defaults call is
+  byte-identical to the existing no-arg `prettyString()`.
+- New `tree-structure-immutable` module: a persistent `ImmutableTreeNode` with structural sharing
+  (`addChild`/`removeChild`/`mapValues` return new roots; pre/post/level-order traversals,
+  `nodeCount`, and `height`).
+
+### Changed
+- Rewrote the README for clarity: one consistent example tree, task-oriented sections
+  (building, traversal, navigation, functional, utilities, mutating), per-module usage, and a
+  condensed maintainer "Releasing" section.
 
 ## [4.0.0]
 
@@ -71,7 +112,9 @@ A breaking release that cleans up the core API and enforces an explicit public s
 ## [3.1.3]
 - iOS targets and Maven Central (Sonatype Central Portal) publishing.
 
-[Unreleased]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v4.0.0...HEAD
+[4.2.0]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v4.1.1...v4.2.0
+[4.1.1]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v4.1.0...v4.1.1
+[4.1.0]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v4.0.0...v4.1.0
 [4.0.0]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v3.4.0...v4.0.0
 [3.4.0]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v3.1.5...v3.4.0
 [3.1.5]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v3.1.3...v3.1.5

README.md

@@ -2,17 +2,27 @@
 [![maven](https://img.shields.io/maven-central/v/com.github.adriankuta/tree-structure?style=plastic)](https://mvnrepository.com/artifact/com.github.adriankuta/tree-structure)
 [![License: MIT](https://img.shields.io/github/license/AdrianKuta/Tree-Data-Structure?style=plastic)](https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/LICENSE)
 [![Publish](https://github.com/AdrianKuta/Tree-Data-Structure/actions/workflows/publishRelease.yml/badge.svg)](https://github.com/AdrianKuta/Tree-Data-Structure/actions/workflows/publishRelease.yml)
+[![API docs](https://img.shields.io/badge/docs-API%20reference-blue?style=plastic)](https://adriankuta.github.io/Tree-Data-Structure/)
 
-Lightweight Kotlin Multiplatform tree data structure for Kotlin and Java. Includes a small DSL, multiple traversal iterators, and pretty-print support.
+📖 **[API reference](https://adriankuta.github.io/Tree-Data-Structure/)** — full KDoc for the core and all modules.
 
-- Kotlin Multiplatform (JVM, JS, Wasm, iOS, and Native host)
-- Pre-order, Post-order, and Level-order iteration
-- Lazy `Sequence` traversal that composes with the Kotlin stdlib (`map`/`filter`/`firstOrNull`…)
-- Navigation helpers: `root()`, `ancestors()`, `siblings()`, `leaves()`, `descendants()`, `isLeaf`, `degree`
-- Functional helpers: `findNode`, `filterNodes`, `anyNode`, `allNodes`, `foldNodes`, `mapValues`, `deepCopy`, `structurallyEquals`
-- Stack-safe: traversal and `height()`/`nodeCount()`/`clear()` handle arbitrarily deep trees without `StackOverflowError`
-- Simple DSL: tree { child(...) }
-- Utilities: nodeCount(), height(), depth(), path(), prettyString(), clear(), removeChild()
+A lightweight n-ary tree for Kotlin Multiplatform. You get a generic `TreeNode<T>`, a small DSL for
+building trees, three traversal orders, lazy `Sequence` traversal, and a set of navigation and
+functional helpers. The core artifact has no third-party dependencies.
+
+It fits homogeneous trees of arbitrary depth: UI component hierarchies, file-system views, org
+charts, and category menus. For fixed, typed hierarchies (like a compiler AST) a sealed class is
+usually a better fit.
+
+## Features
+
+- Kotlin Multiplatform: JVM, Android, JS, Wasm, iOS, and a native host target.
+- Build trees with a `tree { child(...) }` DSL or node by node with `addChild`.
+- Pre-order, post-order, and level-order traversal, as iterators or lazy `Sequence`s.
+- Navigation: `root()`, `ancestors()`, `siblings()`, `leaves()`, `descendants()`, `isLeaf`, `degree`.
+- Functional helpers: `findNode`, `filterNodes`, `anyNode`, `allNodes`, `foldNodes`, `mapValues`, `deepCopy`, `structurallyEquals`.
+- Utilities: `nodeCount()`, `height()`, `depth()`, `path()`, `prettyString()`.
+- Stack-safe: traversal and `height()`/`nodeCount()`/`clear()` handle very deep trees without `StackOverflowError`.
 
 ## Installation
 
@@ -20,14 +30,14 @@ Gradle (Kotlin DSL):
 ```kotlin
 // commonMain for KMP projects, or any sourceSet/module where you need it
 dependencies {
-    implementation("com.github.adriankuta:tree-structure:4.0.0") // see badge above for the latest version
+    implementation("com.github.adriankuta:tree-structure:4.2.0") // latest version is on the badge above
 }
 ```
 
 Gradle (Groovy):
 ```groovy
 dependencies {
-    implementation "com.github.adriankuta:tree-structure:4.0.0" // see badge above for the latest
+    implementation "com.github.adriankuta:tree-structure:4.2.0"
 }
 ```
 
@@ -36,31 +46,13 @@ Maven:
 <dependency>
   <groupId>com.github.adriankuta</groupId>
   <artifactId>tree-structure</artifactId>
-  <version>4.0.0</version>
+  <version>4.2.0</version>
 </dependency>
 ```
 
-## Usage
+## Building a tree
 
-**Kotlin**
-```kotlin
-val root = TreeNode("World")
-val northA = TreeNode("North America")
-val europe = TreeNode("Europe")
-root.addChild(northA)
-root.addChild(europe)
-
-val usa = TreeNode("USA")
-northA.addChild(usa)
-
-val poland = TreeNode("Poland")
-val france = TreeNode("France")
-europe.addChild(poland)
-europe.addChild(france)
-println(root.prettyString())
-```
-
-**Pretty Kotlin (DSL)**
+The DSL is the shortest way to build one:
 ```kotlin
 val root = tree("World") {
     child("North America") { child("USA") }
@@ -71,144 +63,141 @@ val root = tree("World") {
 }
 ```
 
-**Java**
+The same node-by-node API works from Kotlin and Java:
 ```java
 TreeNode<String> root = new TreeNode<>("World");
-TreeNode<String> northA = new TreeNode<>("North America");
+TreeNode<String> northAmerica = new TreeNode<>("North America");
+root.addChild(northAmerica);
+northAmerica.addChild(new TreeNode<>("USA"));
+
 TreeNode<String> europe = new TreeNode<>("Europe");
-root.addChild(northA);
 root.addChild(europe);
-
-TreeNode<String> usa = new TreeNode<>("USA");
-northA.addChild(usa);
-
-TreeNode<String> poland = new TreeNode<>("Poland");
-TreeNode<String> france = new TreeNode<>("France");
-europe.addChild(poland);
-europe.addChild(france);
-System.out.println(root.prettyString());
+europe.addChild(new TreeNode<>("Poland"));
+europe.addChild(new TreeNode<>("Germany"));
 ```
 
-Output:
+`prettyString()` renders the tree for logs and debugging:
 ```
 World
 ├── North America
 │   └── USA
 └── Europe
     ├── Poland
-    └── France
+    └── Germany
 ```
 
-### Traversal and utilities
-```kotlin
-val root = TreeNode("root")
-// ... build your tree
+## Traversal
 
-// Choose iteration order per call (the default order is set in the constructor and is read-only)
+Iterating a node visits the node and all of its descendants. The default order is set in the
+constructor (pre-order by default) and is read-only. Pass an order per call when you need a
+different one:
+```kotlin
+for (node in root) println(node.value)                            // default pre-order
 for (node in root.asSequence(TreeNodeIterators.PostOrder)) println(node.value)
-
-// Utilities
-root.nodeCount()   // number of descendants
-root.height()      // longest path to a leaf (in edges)
-root.depth()       // distance from current node to the root
-val path = root.path(root.children.first()) // nodes from descendant up to root
-
-// Mutations — removeChild removes a *direct* child; detach() unhooks a node from wherever it lives
-val child = root.children.first()
-root.removeChild(child)   // child is now detached from root
-root.clear()              // remove all descendants of root
 ```
 
-### Lazy traversal with Sequence
-
-Traversal is exposed as a lazy `Sequence`, so it composes with the Kotlin standard library and
-short-circuits (it never materializes the whole tree just to find one node):
-
+Traversal is also exposed as a lazy `Sequence`, so it composes with the standard library and stops
+early instead of materializing the whole tree:
 ```kotlin
-val tree = tree("World") {
-    child("North America") { child("USA") }
-    child("Europe") {
-        child("Poland")
-        child("Germany")
-    }
-}
-
-// Pick an order explicitly — no need to mutate the node's state.
-tree.preOrderSequence().map { it.value }.toList()    // [World, North America, USA, Europe, Poland, Germany]
-tree.levelOrderSequence().first { it.value == "USA" } // stops as soon as it's found
-tree.asSequence(TreeNodeIterators.PostOrder).count()  // 6
+root.preOrderSequence().map { it.value }.toList()       // [World, North America, USA, Europe, Poland, Germany]
+root.levelOrderSequence().first { it.value == "USA" }   // stops as soon as it is found
+root.asSequence(TreeNodeIterators.PostOrder).count()    // 6
 ```
 
-### Navigation
-
+## Navigation
 ```kotlin
-val usa = tree.findNode { it == "USA" }!!
+val usa = root.findNode { it == "USA" }!!
 
-usa.isLeaf           // true
-usa.depth()          // 2
-usa.root().value     // "World"
-usa.ancestors().map { it.value } // [North America, World]
-tree.leaves().map { it.value }   // [USA, Poland, Germany]
-val europe = tree.findNode { it == "Europe" }!!
-europe.children.first().siblings().map { it.value } // [Germany]
+usa.isLeaf                          // true
+usa.depth()                        // 2
+usa.root().value                   // "World"
+usa.ancestors().map { it.value }   // [North America, World]
+root.leaves().map { it.value }     // [USA, Poland, Germany]
 ```
 
-### Functional operations
-
+## Functional operations
 ```kotlin
-tree.anyNode { it == "Poland" }            // true
-tree.filterNodes { it.length > 5 }         // nodes whose value is longer than 5 chars
-tree.countNodes { it.startsWith("U") }     // 1
+root.anyNode { it == "Poland" }        // true
+root.filterNodes { it.length > 5 }     // nodes whose value is longer than 5 characters
+root.countNodes { it.startsWith("U") } // 1
 
-// Transform values into a brand-new tree (the original is untouched); stack-safe.
-val lengths: TreeNode<Int> = tree.mapValues { it.length }
+val lengths: TreeNode<Int> = root.mapValues { it.length } // a new tree; the original is untouched
+val copy = root.deepCopy()
+root.structurallyEquals(copy)          // true: same values and shape, different nodes
+```
 
-// Deep copy + structural comparison.
-val copy = tree.deepCopy()
-tree.structurallyEquals(copy)              // true (same values, same shape, different nodes)
+## Utilities
+```kotlin
+root.nodeCount()  // number of descendants, excluding the root
+root.height()     // edges on the longest path down to a leaf
+root.depth()      // edges from this node up to the root
+root.path(usa)    // [USA, North America, World], or null if usa is not a descendant
+```
+
+## Mutating a tree
+```kotlin
+// addChild rejects a node that already has a parent or that would create a cycle.
+root.addChild(TreeNode("Asia"))
+
+// removeChild removes a direct child of the receiver and returns true if it was present.
+root.removeChild(root.children.first())
+
+// detach() unhooks a node from wherever it currently lives.
+root.findNode { it == "Germany" }?.detach()
+
+// clear() removes every descendant of the node.
+root.clear()
 ```
 
 ## Optional modules
 
-The core `tree-structure` artifact has no third-party dependencies. Ecosystem integrations ship as
-separate, opt-in artifacts that depend on the core.
+The core artifact has no third-party dependencies. Each integration is a separate, opt-in artifact
+that depends on the core.
 
-### Serialization — `tree-structure-serialization`
+### Serialization (`tree-structure-serialization`)
 
-`kotlinx.serialization` support. A `TreeNode` holds a parent back-reference (a cycle), so it cannot
-be `@Serializable` directly — convert to/from the acyclic `TreeNodeDto` instead.
+`kotlinx.serialization` support. A `TreeNode` keeps a reference back to its parent, so it cannot be
+`@Serializable` directly. Convert to and from the acyclic `TreeNodeDto` instead.
 
 ```kotlin
-implementation("com.github.adriankuta:tree-structure-serialization:4.0.0")
+implementation("com.github.adriankuta:tree-structure-serialization:4.2.0")
 ```
-
 ```kotlin
-val json = Json.encodeToString(tree.toDto())
+val json = Json.encodeToString(root.toDto())
 val restored = Json.decodeFromString<TreeNodeDto<String>>(json).toTreeNode()
 ```
 
-### Coroutines — `tree-structure-coroutines`
+### Coroutines (`tree-structure-coroutines`)
 
-Traverse a tree as a cold `Flow` (handy in coroutine/`ViewModel` pipelines).
+Traverse a tree as a cold `Flow`, which is handy inside coroutine and `ViewModel` pipelines.
 
 ```kotlin
-implementation("com.github.adriankuta:tree-structure-coroutines:4.0.0")
+implementation("com.github.adriankuta:tree-structure-coroutines:4.2.0")
 ```
+```kotlin
+root.preOrderFlow().collect { println(it.value) }
+root.asFlow(TreeNodeIterators.LevelOrder).map { it.value }
+```
+
+### Compose UI (`tree-structure-compose`)
+
+A `LazyTree` composable for Compose Multiplatform (JVM/desktop, Android, iOS, Wasm). Only the visible
+nodes are composed.
 
 ```kotlin
-tree.preOrderFlow().collect { println(it.value) }
-tree.asFlow(TreeNodeIterators.LevelOrder).map { it.value }
+implementation("com.github.adriankuta:tree-structure-compose:4.2.0")
 ```
 
-### Compose UI — `tree-structure-compose`
-
-A `LazyTree` composable for Compose Multiplatform (JVM/desktop, iOS, Wasm). Only the visible nodes
-are composed, and you decide how each node looks:
+For the common case, the no-content overload renders each node with the built-in `TreeNodeRow`
+(a clickable, indented row with a `▾`/`▸` marker — foundation-only, no Material dependency):
 
 ```kotlin
-implementation("com.github.adriankuta:tree-structure-compose:4.0.0")
+LazyTree(root)                         // sensible default
+LazyTree(root, label = { it.name })    // map a node's value to its text
 ```
 
+Or supply your own row for full control:
+
 ```kotlin
 LazyTree(root) { node, depth, expanded, toggle ->
     Row(Modifier.padding(start = (depth * 16).dp).clickable(onClick = toggle)) {
@@ -218,37 +207,52 @@ LazyTree(root) { node, depth, expanded, toggle ->
 }
 ```
 
-## Publishing to Maven Central (central.sonatype.com)
+A runnable Android demo lives in the [`samples-android`](samples-android) module.
 
-This project is configured to publish artifacts to Maven Central via the Sonatype Central Portal.
+### Immutable (`tree-structure-immutable`)
 
-There are two supported ways to publish:
+A persistent `ImmutableTreeNode` with structural sharing. Every operation (`addChild`,
+`removeChild`, `mapValues`) returns a **new** root and leaves the original untouched; unchanged
+subtrees are reused, so updates are cheap and old roots stay valid. Backed by
+`kotlinx.collections.immutable`.
 
-1) Via GitHub Actions (recommended)
-- Create a GitHub Release (tag) in this repository. When a release is published, the workflow .github/workflows/publishRelease.yml runs automatically.
-- The workflow uses the Gradle task publishToMavenCentral to upload artifacts through the Central Portal.
-- Make sure these repository secrets are configured in GitHub:
-  - MAVEN_CENTRAL_USERNAME — Your Sonatype Central username (not email).
-  - MAVEN_CENTRAL_PASSWORD — Your Sonatype Central password or a token from central.sonatype.com.
-  - SIGNING_KEY — ASCII‑armored GPG private key (exported, single line; for in‑memory signing).
-  - SIGNING_PASSWORD — Passphrase for the key above.
-- The workflow uses JDK 21 and publishes the version defined in build.gradle.kts.
+```kotlin
+implementation("com.github.adriankuta:tree-structure-immutable:4.2.0")
+```
+```kotlin
+val root = ImmutableTreeNode("World").addChild(ImmutableTreeNode("Europe"))
+val bigger = root.addChild(ImmutableTreeNode("Asia")) // root is unchanged; bigger is a new tree
 
-2) Locally via Gradle
-- Ensure you have a Sonatype Central account and that the groupId com.github.adriankuta is verified in central.sonatype.com (Namespace Rules → Verify).
-- Export the same credentials/signing values as environment variables or pass them as Gradle properties:
-  - ORG_GRADLE_PROJECT_mavenCentralUsername
-  - ORG_GRADLE_PROJECT_mavenCentralPassword
-  - ORG_GRADLE_PROJECT_signingInMemoryKey
-  - ORG_GRADLE_PROJECT_signingInMemoryKeyPassword
-- Then run:
-  - ./gradlew publishToMavenCentral
-- For snapshot publishing, set -Psnapshot=true (the version is derived from PUBLISH_VERSION with -SNAPSHOT).
+bigger.preOrder().forEach { println(it.value) } // pre/post/level-order, nodeCount(), height()
+```
 
-Notes
-- Publishing is powered by the com.vanniktech.maven.publish Gradle plugin and Sonatype Central Portal (no legacy Nexus staging URLs needed).
-- The plugin is configured to sign all publications. Coordinates and POM metadata are defined in build.gradle.kts.
-- If using the combined task is preferred, you can also run publishAndReleaseToMavenCentral when automatic release is enabled; this repository currently uploads with publishToMavenCentral from CI.
+## Examples
+
+A runnable `:samples` module bundles compile-checked, assertion-verified examples of the core API
+and the serialization, coroutines, and immutable modules. Run them with:
+
+```
+./gradlew :samples:run
+```
+
+## Notes
+
+`TreeNode` is mutable and not thread-safe. Add your own synchronization if you share a tree across
+threads, and do not modify a tree while you iterate it. Equality is by reference; use
+`structurallyEquals` to compare two trees by value and shape.
+
+Coming from 3.x? See [CHANGELOG.md](CHANGELOG.md) for the 4.0 migration notes.
+
+## Releasing (maintainers)
+
+Releases go to Maven Central through the Sonatype Central Portal using the
+`com.vanniktech.maven.publish` plugin. Creating a GitHub release runs
+`.github/workflows/publishRelease.yml`, which signs and uploads every module; the deployment is then
+published from central.sonatype.com. The published version comes from `PUBLISH_VERSION` in
+`build.gradle.kts`. CI needs the `MAVEN_CENTRAL_USERNAME`, `MAVEN_CENTRAL_PASSWORD`, `SIGNING_KEY`,
+and `SIGNING_PASSWORD` repository secrets. To publish from a local machine, set the matching
+`ORG_GRADLE_PROJECT_*` properties and run `./gradlew publishToMavenCentral` (add `-Psnapshot=true`
+for a snapshot build).
 
 ## License
 
@@ -273,5 +277,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
----

api/android/tree-structure.api

@@ -6,10 +6,34 @@ public final class com/github/adriankuta/datastructure/tree/ChildDeclarationInte
 	public static synthetic fun child$default (Lcom/github/adriankuta/datastructure/tree/ChildDeclarationInterface;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
 }
 
+public final class com/github/adriankuta/datastructure/tree/TreeConnectors {
+	public static final field Companion Lcom/github/adriankuta/datastructure/tree/TreeConnectors$Companion;
+	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
+	public final fun component1 ()Ljava/lang/String;
+	public final fun component2 ()Ljava/lang/String;
+	public final fun component3 ()Ljava/lang/String;
+	public final fun component4 ()Ljava/lang/String;
+	public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Lcom/github/adriankuta/datastructure/tree/TreeConnectors;
+	public static synthetic fun copy$default (Lcom/github/adriankuta/datastructure/tree/TreeConnectors;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lcom/github/adriankuta/datastructure/tree/TreeConnectors;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getBranch ()Ljava/lang/String;
+	public final fun getEmpty ()Ljava/lang/String;
+	public final fun getLastBranch ()Ljava/lang/String;
+	public final fun getVertical ()Ljava/lang/String;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeConnectors$Companion {
+	public final fun getAscii ()Lcom/github/adriankuta/datastructure/tree/TreeConnectors;
+	public final fun getDefault ()Lcom/github/adriankuta/datastructure/tree/TreeConnectors;
+}
+
 public class com/github/adriankuta/datastructure/tree/TreeNode : com/github/adriankuta/datastructure/tree/ChildDeclarationInterface, java/lang/Iterable, kotlin/jvm/internal/markers/KMappedMarker {
 	public fun <init> (Ljava/lang/Object;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;)V
 	public synthetic fun <init> (Ljava/lang/Object;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun addChild (Lcom/github/adriankuta/datastructure/tree/TreeNode;)V
+	public final fun addChildren ([Lcom/github/adriankuta/datastructure/tree/TreeNode;)V
 	public synthetic fun child (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
 	public final fun clear ()V
 	public final fun depth ()I
@@ -19,13 +43,18 @@ public class com/github/adriankuta/datastructure/tree/TreeNode : com/github/adri
 	public final fun getTreeIterator ()Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
 	public final fun getValue ()Ljava/lang/Object;
 	public final fun height ()I
+	public final fun insertChild (ILcom/github/adriankuta/datastructure/tree/TreeNode;)V
 	public final fun isRoot ()Z
 	public fun iterator ()Ljava/util/Iterator;
 	public final fun iterator (Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;)Ljava/util/Iterator;
+	public final fun moveChild (Lcom/github/adriankuta/datastructure/tree/TreeNode;I)Z
 	public final fun nodeCount ()I
 	public final fun path (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
 	public final fun prettyString ()Ljava/lang/String;
 	public final fun removeChild (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Z
+	public final fun removeChildAt (I)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public final fun replaceChild (ILcom/github/adriankuta/datastructure/tree/TreeNode;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public final fun sortChildren (Ljava/util/Comparator;)V
 	public fun toString ()Ljava/lang/String;
 }
 
@@ -51,6 +80,18 @@ public final class com/github/adriankuta/datastructure/tree/TreeNodeNavigationEx
 	public static final fun siblings (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
 }
 
+public final class com/github/adriankuta/datastructure/tree/TreeNodePrettyPrintExtKt {
+	public static final fun prettyString (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeConnectors;Lkotlin/jvm/functions/Function3;)Ljava/lang/String;
+	public static synthetic fun prettyString$default (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeConnectors;Lkotlin/jvm/functions/Function3;ILjava/lang/Object;)Ljava/lang/String;
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeNodeQueryExtKt {
+	public static final fun contains (Lcom/github/adriankuta/datastructure/tree/TreeNode;Ljava/lang/Object;)Z
+	public static final fun distance (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/lang/Integer;
+	public static final fun lowestCommonAncestor (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public static final fun pathBetween (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+}
+
 public final class com/github/adriankuta/datastructure/tree/TreeNodeSequenceExtKt {
 	public static final fun asSequence (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;)Lkotlin/sequences/Sequence;
 	public static synthetic fun asSequence$default (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;ILjava/lang/Object;)Lkotlin/sequences/Sequence;

api/jvm/tree-structure.api

@@ -0,0 +1,142 @@
+public abstract interface class com/github/adriankuta/datastructure/tree/ChildDeclarationInterface {
+	public abstract synthetic fun child (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+}
+
+public final class com/github/adriankuta/datastructure/tree/ChildDeclarationInterface$DefaultImpls {
+	public static synthetic fun child$default (Lcom/github/adriankuta/datastructure/tree/ChildDeclarationInterface;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeConnectors {
+	public static final field Companion Lcom/github/adriankuta/datastructure/tree/TreeConnectors$Companion;
+	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
+	public final fun component1 ()Ljava/lang/String;
+	public final fun component2 ()Ljava/lang/String;
+	public final fun component3 ()Ljava/lang/String;
+	public final fun component4 ()Ljava/lang/String;
+	public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Lcom/github/adriankuta/datastructure/tree/TreeConnectors;
+	public static synthetic fun copy$default (Lcom/github/adriankuta/datastructure/tree/TreeConnectors;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lcom/github/adriankuta/datastructure/tree/TreeConnectors;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getBranch ()Ljava/lang/String;
+	public final fun getEmpty ()Ljava/lang/String;
+	public final fun getLastBranch ()Ljava/lang/String;
+	public final fun getVertical ()Ljava/lang/String;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeConnectors$Companion {
+	public final fun getAscii ()Lcom/github/adriankuta/datastructure/tree/TreeConnectors;
+	public final fun getDefault ()Lcom/github/adriankuta/datastructure/tree/TreeConnectors;
+}
+
+public class com/github/adriankuta/datastructure/tree/TreeNode : com/github/adriankuta/datastructure/tree/ChildDeclarationInterface, java/lang/Iterable, kotlin/jvm/internal/markers/KMappedMarker {
+	public fun <init> (Ljava/lang/Object;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;)V
+	public synthetic fun <init> (Ljava/lang/Object;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun addChild (Lcom/github/adriankuta/datastructure/tree/TreeNode;)V
+	public final fun addChildren ([Lcom/github/adriankuta/datastructure/tree/TreeNode;)V
+	public synthetic fun child (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public final fun clear ()V
+	public final fun depth ()I
+	public final fun detach ()Z
+	public final fun getChildren ()Ljava/util/List;
+	public final fun getParent ()Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public final fun getTreeIterator ()Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+	public final fun getValue ()Ljava/lang/Object;
+	public final fun height ()I
+	public final fun insertChild (ILcom/github/adriankuta/datastructure/tree/TreeNode;)V
+	public final fun isRoot ()Z
+	public fun iterator ()Ljava/util/Iterator;
+	public final fun iterator (Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;)Ljava/util/Iterator;
+	public final fun moveChild (Lcom/github/adriankuta/datastructure/tree/TreeNode;I)Z
+	public final fun nodeCount ()I
+	public final fun path (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+	public final fun prettyString ()Ljava/lang/String;
+	public final fun removeChild (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Z
+	public final fun removeChildAt (I)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public final fun replaceChild (ILcom/github/adriankuta/datastructure/tree/TreeNode;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public final fun sortChildren (Ljava/util/Comparator;)V
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeNodeFunctionalExtKt {
+	public static final fun allNodes (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)Z
+	public static final fun anyNode (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)Z
+	public static final fun countNodes (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)I
+	public static final fun deepCopy (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public static final fun filterNodes (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)Ljava/util/List;
+	public static final fun findNode (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public static final fun foldNodes (Lcom/github/adriankuta/datastructure/tree/TreeNode;Ljava/lang/Object;Lkotlin/jvm/functions/Function2;)Ljava/lang/Object;
+	public static final fun mapValues (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public static final fun structurallyEquals (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeNode;)Z
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeNodeNavigationExtKt {
+	public static final fun ancestors (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+	public static final fun descendants (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+	public static final fun getDegree (Lcom/github/adriankuta/datastructure/tree/TreeNode;)I
+	public static final fun isLeaf (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Z
+	public static final fun leaves (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+	public static final fun root (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public static final fun siblings (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeNodePrettyPrintExtKt {
+	public static final fun prettyString (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeConnectors;Lkotlin/jvm/functions/Function3;)Ljava/lang/String;
+	public static synthetic fun prettyString$default (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeConnectors;Lkotlin/jvm/functions/Function3;ILjava/lang/Object;)Ljava/lang/String;
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeNodeQueryExtKt {
+	public static final fun contains (Lcom/github/adriankuta/datastructure/tree/TreeNode;Ljava/lang/Object;)Z
+	public static final fun distance (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/lang/Integer;
+	public static final fun lowestCommonAncestor (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public static final fun pathBetween (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeNodeSequenceExtKt {
+	public static final fun asSequence (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;)Lkotlin/sequences/Sequence;
+	public static synthetic fun asSequence$default (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;ILjava/lang/Object;)Lkotlin/sequences/Sequence;
+	public static final fun levelOrderSequence (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lkotlin/sequences/Sequence;
+	public static final fun postOrderSequence (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lkotlin/sequences/Sequence;
+	public static final fun preOrderSequence (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lkotlin/sequences/Sequence;
+}
+
+public final class com/github/adriankuta/datastructure/tree/exceptions/TreeNodeException : java/lang/RuntimeException {
+	public fun <init> ()V
+	public fun <init> (Ljava/lang/String;)V
+	public fun <init> (Ljava/lang/String;Ljava/lang/Throwable;)V
+	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+}
+
+public final class com/github/adriankuta/datastructure/tree/iterators/LevelOrderTreeIterator : java/util/Iterator, kotlin/jvm/internal/markers/KMappedMarker {
+	public fun <init> (Lcom/github/adriankuta/datastructure/tree/TreeNode;)V
+	public fun hasNext ()Z
+	public fun next ()Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public synthetic fun next ()Ljava/lang/Object;
+	public fun remove ()V
+}
+
+public final class com/github/adriankuta/datastructure/tree/iterators/PostOrderTreeIterator : java/util/Iterator, kotlin/jvm/internal/markers/KMappedMarker {
+	public fun <init> (Lcom/github/adriankuta/datastructure/tree/TreeNode;)V
+	public fun hasNext ()Z
+	public fun next ()Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public synthetic fun next ()Ljava/lang/Object;
+	public fun remove ()V
+}
+
+public final class com/github/adriankuta/datastructure/tree/iterators/PreOrderTreeIterator : java/util/Iterator, kotlin/jvm/internal/markers/KMappedMarker {
+	public fun <init> (Lcom/github/adriankuta/datastructure/tree/TreeNode;)V
+	public fun hasNext ()Z
+	public fun next ()Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public synthetic fun next ()Ljava/lang/Object;
+	public fun remove ()V
+}
+
+public final class com/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators : java/lang/Enum {
+	public static final field LevelOrder Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+	public static final field PostOrder Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+	public static final field PreOrder Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+	public static fun getEntries ()Lkotlin/enums/EnumEntries;
+	public static fun valueOf (Ljava/lang/String;)Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+	public static fun values ()[Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+}
+

build.gradle.kts

@@ -7,11 +7,16 @@ plugins {
     alias(libs.plugins.binaryCompatibilityValidator)
     alias(libs.plugins.kover)
     signing
+    alias(libs.plugins.androidLibrary)
+    // Loaded once here (with a known version) so the Android application/library variants can be
+    // applied across subprojects without the "already on the classpath with an unknown version" clash.
+    alias(libs.plugins.androidApplication) apply false
+    alias(libs.plugins.kotlinAndroid) apply false
 }
 
 val PUBLISH_GROUP_ID = "com.github.adriankuta"
 val PUBLISH_ARTIFACT_ID = "tree-structure"    // base artifact; KMP will add -jvm, -ios*, etc.
-val PUBLISH_VERSION = "4.0.0"
+val PUBLISH_VERSION = "4.2.0"
 
 val snapshot: String? by project
 
@@ -57,6 +62,37 @@ mavenPublishing {
 
 repositories {
     mavenCentral()
+    google()
+}
+
+apiValidation {
+    // Neither sample module is a published artifact, so neither has a .api dump.
+    ignoredProjects.add("samples")
+    ignoredProjects.add("samples-android")
+}
+
+dependencies {
+    // Include this module's own docs in the aggregation — DGP v2 requires the
+    // aggregating project to list itself explicitly.
+    dokka(project(":"))
+    dokka(project(":tree-structure-serialization"))
+    dokka(project(":tree-structure-coroutines"))
+    dokka(project(":tree-structure-compose"))
+    dokka(project(":tree-structure-immutable"))
+}
+
+dokka {
+    moduleName.set("Tree Data Structure")
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            localDirectory.set(projectDir.resolve("src"))
+            // For the root project projectDir == rootDir, so `module` is "" and links resolve to /blob/master/src.
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
 }
 
 kotlin {
@@ -65,6 +101,15 @@ kotlin {
 
     jvm()
 
+    androidTarget {
+        publishLibraryVariants("release")
+        // Build the Android variant at JVM 17 so Android consumers (JVM 11/17) can inline the
+        // library's inline DSL (`tree { }`) — they cannot inline the default JVM-21 bytecode.
+        compilerOptions {
+            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+        }
+    }
+
     js(IR) {
         browser()
         nodejs()
@@ -97,3 +142,15 @@ kotlin {
         }
     }
 }
+
+android {
+    namespace = "com.github.adriankuta.datastructure.tree"
+    compileSdk = libs.versions.androidCompileSdk.get().toInt()
+    defaultConfig {
+        minSdk = libs.versions.androidMinSdk.get().toInt()
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+}

docs/superpowers/plans/2026-06-07-api-reference-github-pages.md

@@ -0,0 +1,435 @@
+# API Reference (Dokka HTML) on GitHub Pages — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Migrate Dokka to 2.x and publish an aggregated, source-linked multi-module API reference for all four modules to GitHub Pages on each release and on demand.
+
+**Architecture:** Bump Dokka `1.9.20 → 2.2.0` and switch on the Dokka Gradle Plugin v2 (`V2Enabled`). The root project (the published core module) aggregates the three submodules via `dokka(project(...))` dependencies, producing one HTML site at `build/dokka/html`. A new `docs.yml` workflow builds that site and deploys it with the official GitHub Pages Actions. The vanniktech maven-publish plugin (0.34.0) keeps building the Maven Central `-javadoc.jar` — it already supports Dokka V2, so the release pipeline is unaffected.
+
+**Tech Stack:** Kotlin Multiplatform 2.1.0, Gradle 8.5, Dokka Gradle Plugin 2.2.0, vanniktech maven-publish 0.34.0, GitHub Actions (`upload-pages-artifact@v3`, `deploy-pages@v4`).
+
+**Spec:** `docs/superpowers/specs/2026-06-07-publish-api-reference-dokka-github-pages-design.md`
+
+> **Note on "tests":** This is build/CI work, so each task's verification is a Gradle command or a YAML lint with a concrete expected result rather than a unit test. Treat the "verify" steps as the failing/passing check.
+
+---
+
+## File Structure
+
+| File | Responsibility | Action |
+| --- | --- | --- |
+| `gradle/libs.versions.toml` | Centralized Dokka version | Modify (`dokka = "2.2.0"`) |
+| `gradle.properties` | Enable DGP v2 plugin mode | Modify (add 2 flags) |
+| `build.gradle.kts` (root) | Aggregate 3 submodules; root site title + source links | Modify (add `dependencies` + `dokka {}` blocks) |
+| `tree-structure-serialization/build.gradle.kts` | Source links for this module | Modify (add `dokka {}` block) |
+| `tree-structure-coroutines/build.gradle.kts` | Source links for this module | Modify (add `dokka {}` block) |
+| `tree-structure-compose/build.gradle.kts` | Source links for this module | Modify (add `dokka {}` block) |
+| `.github/workflows/docs.yml` | Build + deploy site to Pages | Create |
+| `README.md` | Docs badge + link | Modify |
+
+Work happens on branch `docs/api-reference-github-pages` (already created; spec already committed there).
+
+---
+
+## Task 1: Migrate Dokka to 2.2.0 and enable DGP v2
+
+**Files:**
+- Modify: `gradle/libs.versions.toml` (line `dokka = "1.9.20"`)
+- Modify: `gradle.properties`
+
+- [ ] **Step 1: Bump the Dokka version in the catalog**
+
+In `gradle/libs.versions.toml`, change the `dokka` version under `[versions]`:
+
+```toml
+dokka = "2.2.0"
+```
+
+(Leave the `dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }` plugin line unchanged.)
+
+- [ ] **Step 2: Enable the Dokka Gradle Plugin v2**
+
+Append these two lines to `gradle.properties` (current content is only `kotlin.code.style=official`):
+
+```properties
+# Dokka Gradle Plugin v2 (https://kotl.in/dokka-gradle-migration)
+org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
+org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true
+```
+
+- [ ] **Step 3: Verify the v2 task exists and there is no V1 warning**
+
+Run: `./gradlew :dokkaGeneratePublicationHtml --dry-run --console=plain`
+
+Expected: `BUILD SUCCESSFUL`, a list of `:dokkaGenerate*` tasks printed, and **no** message containing `Dokka Gradle plugin V1` or `migration guide`. (At this point only the root/core module is documented — aggregation is added in Task 2.)
+
+- [ ] **Step 4: Verify the Maven Central javadoc jar still builds under Dokka 2.x**
+
+Run: `./gradlew javadocJar --console=plain`
+
+Expected: `BUILD SUCCESSFUL`. This is the vanniktech-generated jar that Maven Central requires; it must keep working. (If the task name isn't found, list it with `./gradlew tasks --all | grep -i javadoc` and run the reported task — it is the per-module `javadocJar`.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add gradle/libs.versions.toml gradle.properties
+git commit -m "build: migrate Dokka 1.9.20 -> 2.2.0 (DGP v2) (#32)"
+```
+
+---
+
+## Task 2: Aggregate all modules + root site title and source links
+
+**Files:**
+- Modify: `build.gradle.kts` (root)
+
+- [ ] **Step 1: Add the Dokka aggregation dependencies**
+
+Add this top-level block to the root `build.gradle.kts` (place it after the `repositories { mavenCentral() }` block, at the top level — not inside `kotlin {}`):
+
+```kotlin
+dependencies {
+    dokka(project(":tree-structure-serialization"))
+    dokka(project(":tree-structure-coroutines"))
+    dokka(project(":tree-structure-compose"))
+}
+```
+
+- [ ] **Step 2: Add the root `dokka {}` configuration (site title + source links)**
+
+Add this top-level block to the root `build.gradle.kts` (e.g. right after the `dependencies {}` block from Step 1):
+
+```kotlin
+dokka {
+    moduleName.set("Tree Data Structure")
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            localDirectory.set(projectDir.resolve("src"))
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
+}
+```
+
+- [ ] **Step 3: Build the aggregated site**
+
+Run: `./gradlew :dokkaGeneratePublicationHtml --console=plain`
+
+Expected: `BUILD SUCCESSFUL` and the file `build/dokka/html/index.html` exists.
+
+Run: `ls build/dokka/html`
+
+Expected: per-module output directories including `tree-structure`, `tree-structure-serialization`, `tree-structure-coroutines`, and `tree-structure-compose` (plus `index.html`, `navigation.html`, assets).
+
+- [ ] **Step 4: Verify the four modules and root source links are present**
+
+Run: `grep -roh "tree-structure-serialization\|tree-structure-coroutines\|tree-structure-compose" build/dokka/html/index.html | sort -u`
+
+Expected: all three submodule names listed (confirming aggregation).
+
+Run: `grep -rl "github.com/AdrianKuta/Tree-Data-Structure/blob/master/src/" build/dokka/html/tree-structure | head -1`
+
+Expected: at least one file path printed (confirming the root/core module's source links resolve to `.../blob/master/src/...`). Optionally open `build/dokka/html/index.html` in a browser and click a core class's "source" link to confirm it lands on the right GitHub file.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add build.gradle.kts
+git commit -m "docs: aggregate all modules into one Dokka HTML site with source links (#32)"
+```
+
+---
+
+## Task 3: Source links for the three submodules
+
+The submodules are documented by the aggregation but need their own `sourceLink` so their symbols point at the correct subdirectory on GitHub. The block below is **path-derived and identical** for every module — add the exact same block to all three files.
+
+**Files:**
+- Modify: `tree-structure-serialization/build.gradle.kts`
+- Modify: `tree-structure-coroutines/build.gradle.kts`
+- Modify: `tree-structure-compose/build.gradle.kts`
+
+- [ ] **Step 1: Add the `dokka {}` block to `tree-structure-serialization/build.gradle.kts`**
+
+Add this top-level block (after the `repositories {}` block, before `kotlin {}`):
+
+```kotlin
+dokka {
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            localDirectory.set(projectDir.resolve("src"))
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
+}
+```
+
+- [ ] **Step 2: Add the same block to `tree-structure-coroutines/build.gradle.kts`**
+
+Add the identical block (after `repositories {}`, before `kotlin {}`):
+
+```kotlin
+dokka {
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            localDirectory.set(projectDir.resolve("src"))
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
+}
+```
+
+- [ ] **Step 3: Add the same block to `tree-structure-compose/build.gradle.kts`**
+
+Add the identical block (after the `repositories { mavenCentral(); google() }` block, before `kotlin {}`):
+
+```kotlin
+dokka {
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            localDirectory.set(projectDir.resolve("src"))
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
+}
+```
+
+- [ ] **Step 4: Rebuild the site**
+
+Run: `./gradlew :dokkaGeneratePublicationHtml --console=plain`
+
+Expected: `BUILD SUCCESSFUL`.
+
+- [ ] **Step 5: Verify each submodule's source links resolve to its subdirectory**
+
+Run:
+```bash
+for m in serialization coroutines compose; do
+  echo -n "tree-structure-$m: "
+  grep -rl "github.com/AdrianKuta/Tree-Data-Structure/blob/master/tree-structure-$m/src/" build/dokka/html/tree-structure-$m | head -1 || echo "MISSING"
+done
+```
+
+Expected: a file path printed for each of the three modules (none "MISSING").
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add tree-structure-serialization/build.gradle.kts tree-structure-coroutines/build.gradle.kts tree-structure-compose/build.gradle.kts
+git commit -m "docs: add Dokka source links to serialization/coroutines/compose modules (#32)"
+```
+
+---
+
+## Task 4: GitHub Pages workflow
+
+**Files:**
+- Create: `.github/workflows/docs.yml`
+
+- [ ] **Step 1: Create the workflow file**
+
+Create `.github/workflows/docs.yml` with exactly:
+
+```yaml
+name: Docs
+
+on:
+  release:
+    types: [released]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Dokka HTML
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+      - name: Generate API docs
+        run: ./gradlew :dokkaGeneratePublicationHtml --console=plain
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/dokka/html
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+- [ ] **Step 2: Validate the YAML is well-formed**
+
+Run: `ruby -ryaml -e "YAML.load_file('.github/workflows/docs.yml'); puts 'OK'"`
+
+Expected: prints `OK` with no error. (Ruby ships with macOS. Alternatively, if `actionlint` is installed: `actionlint .github/workflows/docs.yml` → no output.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .github/workflows/docs.yml
+git commit -m "ci: add docs workflow to deploy Dokka HTML to GitHub Pages (#32)"
+```
+
+---
+
+## Task 5: Link the site from the README
+
+**Files:**
+- Modify: `README.md` (top badge block, lines 1-6)
+
+- [ ] **Step 1: Add the API docs badge**
+
+In `README.md`, immediately after the existing `Publish` badge line:
+
+```markdown
+[![Publish](https://github.com/AdrianKuta/Tree-Data-Structure/actions/workflows/publishRelease.yml/badge.svg)](https://github.com/AdrianKuta/Tree-Data-Structure/actions/workflows/publishRelease.yml)
+```
+
+add this new line:
+
+```markdown
+[![API docs](https://img.shields.io/badge/docs-API%20reference-blue?style=plastic)](https://adriankuta.github.io/Tree-Data-Structure/)
+```
+
+- [ ] **Step 2: Add a one-line pointer under the badges**
+
+After the badge block and its following blank line, and **before** the intro paragraph that starts `A lightweight n-ary tree for Kotlin Multiplatform.`, insert:
+
+```markdown
+📖 **[API reference](https://adriankuta.github.io/Tree-Data-Structure/)** — full KDoc for the core and all modules.
+
+```
+
+- [ ] **Step 3: Verify the link is present**
+
+Run: `grep -n "adriankuta.github.io/Tree-Data-Structure" README.md`
+
+Expected: two matches (the badge and the 📖 line).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: link the published API reference from the README (#32)"
+```
+
+---
+
+## Task 6: Full verification, push, and pull request
+
+**Files:** none (verification + integration)
+
+- [ ] **Step 1: Full local verification**
+
+Run each and confirm `BUILD SUCCESSFUL`:
+
+```bash
+./gradlew :dokkaGeneratePublicationHtml --console=plain   # site builds, all 4 modules
+./gradlew javadocJar --console=plain                       # release javadoc jar intact
+./gradlew apiCheck --console=plain                         # binary-compat baseline unchanged
+```
+
+Expected: all three succeed. `apiCheck` must pass with no diff — this change touches only build config and docs, not public API. Optionally open `build/dokka/html/index.html` in a browser for a final visual check (module nav + a couple of source links).
+
+- [ ] **Step 2: Push the branch**
+
+```bash
+git push -u origin docs/api-reference-github-pages
+```
+
+- [ ] **Step 3: Open the pull request**
+
+```bash
+gh pr create --base master --head docs/api-reference-github-pages \
+  --title "Publish API reference (Dokka HTML) to GitHub Pages (#32)" \
+  --body "$(cat <<'EOF'
+Closes #32.
+
+Migrates Dokka 1.9.20 → 2.2.0 (DGP v2) and publishes an aggregated, source-linked
+multi-module API reference to GitHub Pages.
+
+## What changed
+- **Dokka 2.2.0 / DGP v2** (`V2Enabled` in `gradle.properties`). Gradle 8.5 and Kotlin
+  2.1.0 already satisfy Dokka 2.2.0's minimums (7.6+ / 1.9+), so no wrapper/Kotlin bump.
+- **Aggregation**: the root (core) module pulls in `-serialization`, `-coroutines`, and
+  `-compose` via `dokka(project(...))` → one site at `build/dokka/html`
+  (`:dokkaGeneratePublicationHtml`).
+- **Source links** on every module, pointing each symbol at its source on `master`.
+- **`.github/workflows/docs.yml`**: builds the site and deploys via the official Pages
+  Actions on each release and on manual `workflow_dispatch`.
+- **README**: docs badge + link to https://adriankuta.github.io/Tree-Data-Structure/
+
+## Release pipeline unaffected
+vanniktech 0.34.0 already supports Dokka `V2Enabled`, so the Maven Central
+`-javadoc.jar` keeps building (verified locally with `./gradlew javadocJar`).
+
+## ⚠️ One-time manual step required before the site goes live
+Enable Pages: **Settings → Pages → Source = "GitHub Actions"**. Until then the
+`deploy` job will fail. After enabling, run the **Docs** workflow once via
+*Actions → Docs → Run workflow* (`workflow_dispatch`) to publish without waiting for a
+release.
+EOF
+)"
+```
+
+Expected: PR URL printed.
+
+- [ ] **Step 4: Post-merge manual steps (call these out to the repo owner)**
+
+1. **Settings → Pages → Source = "GitHub Actions"** (one-time; otherwise `deploy` fails).
+2. Trigger **Actions → Docs → Run workflow** (`workflow_dispatch`) to publish immediately.
+3. Confirm the site is live at https://adriankuta.github.io/Tree-Data-Structure/ and the module nav + source links work.
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- Dokka 1.9.20 → 2.2.0 + V2 mode → Task 1 ✓
+- Multi-module aggregation in root → Task 2 ✓
+- Source links (root + 3 submodules) + site title → Tasks 2 & 3 ✓
+- `docs.yml` (release + workflow_dispatch, official Pages Actions) → Task 4 ✓
+- README badge + link → Task 5 ✓
+- Verify javadoc jar / apiCheck / local docs build → Tasks 1, 2, 6 ✓
+- Manual Pages-enable prerequisite → Tasks 4/6 PR body + post-merge steps ✓
+- Out-of-scope items (versioned docs, Module.md, vanniktech swap, CI cache) → correctly excluded ✓
+
+**Placeholder scan:** No TBD/TODO/"handle edge cases"/"similar to Task N". The identical source-link block is repeated in full in each of Task 3's steps (not referenced) ✓
+
+**Type/name consistency:** Task name `:dokkaGeneratePublicationHtml`, output dir `build/dokka/html`, config functions (`moduleName.set`, `dokkaSourceSets.configureEach`, `sourceLink { localDirectory.set / remoteUrl / remoteLineSuffix.set }`), and `dokka(project(...))` aggregation are used identically across Tasks 1–6 and the workflow ✓
+
+**Open risk carried from spec:** if Dokka cannot resolve Apple source sets on `ubuntu-latest` in CI (Task 4), switch the `build` job's `runs-on` to `macos-latest` (mirrors the iOS test job). Local verification runs on macOS, which covers Apple source sets.

docs/superpowers/specs/2026-06-07-publish-api-reference-dokka-github-pages-design.md

@@ -0,0 +1,237 @@
+# Design: Publish API reference (Dokka HTML) to GitHub Pages
+
+- **Issue:** [#32](https://github.com/AdrianKuta/Tree-Data-Structure/issues/32) — *Publish API reference (Dokka HTML) to GitHub Pages*
+- **Date:** 2026-06-07
+- **Status:** Approved (design); pending spec review
+
+## Summary
+
+Generate a browsable, multi-module API reference with Dokka and host it on GitHub
+Pages. The site aggregates the core (`tree-structure`) plus the `-serialization`,
+`-coroutines`, and `-compose` modules, links every symbol back to its source on
+GitHub, and is (re)deployed on each GitHub release or on demand. The README points
+to it.
+
+## Background / current state
+
+- **Dokka 1.9.20** is applied to all four modules (root core + three submodules) via
+  `alias(libs.plugins.dokka)`. Today it runs only because the **vanniktech
+  maven-publish plugin (0.34.0)** uses it to build the `-javadoc.jar` that Maven
+  Central requires. There is no aggregation config, no docs site, no source links.
+- Plugin/library versions are centralized in `gradle/libs.versions.toml`.
+- The **root project is itself the published core module** and the natural Dokka
+  aggregation root.
+- Existing workflows: `test.yml` (reusable matrix: JVM/JS/Wasm/Native + `apiCheck`,
+  plus iOS on macOS) and `publishRelease.yml` (on GitHub release → tests →
+  `./gradlew publishToMavenCentral`). Both use `actions/checkout@v4` +
+  `actions/setup-java@v4` (temurin, JDK 21) with no Gradle cache action.
+- Gradle wrapper **8.5**; Kotlin **2.1.0**.
+
+### Verified compatibility (de-risking)
+
+- **Dokka 2.2.0** (latest stable) requires **Gradle 7.6+** and **Kotlin 1.9+** → our
+  8.5 / 2.1.0 satisfy both. **No wrapper bump, no Kotlin bump.**
+- **vanniktech 0.34.0** already supports Dokka `V2Enabled` (added in 0.30.0), so the
+  Maven Central `-javadoc.jar` keeps building under Dokka 2.x. **No vanniktech bump.**
+  (For reference, 0.36.0 *removes* Dokka v1 support entirely — so V2 is the forward
+  direction regardless.)
+
+## Goals
+
+1. Migrate Dokka `1.9.20` → `2.2.0` (DGP v2 / `V2Enabled`) without breaking the
+   release pipeline's javadoc jar.
+2. Produce one aggregated multi-module HTML site for all four modules.
+3. Link every documented symbol to its source on GitHub.
+4. Deploy the site to GitHub Pages on each release and on manual dispatch.
+5. Link the site from the README.
+
+## Non-goals (per the issue's "follow-up" note)
+
+- Versioned / per-release docs (one published version at a time, tracking the latest
+  release / manual run).
+- Long-form `Module.md` package descriptions.
+- Changing the publishing tool (vanniktech stays; out of scope for #32).
+- Adding a Gradle cache action to CI (keep parity with existing workflows).
+
+## Detailed design
+
+### 1. Dokka 2.x migration
+
+**`gradle/libs.versions.toml`**
+
+```toml
+dokka = "2.2.0"   # was 1.9.20
+```
+
+**`gradle.properties`** — enable DGP v2 and silence the migration notice:
+
+```properties
+org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
+org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true
+```
+
+The four `alias(libs.plugins.dokka)` plugin applications stay unchanged.
+
+### 2. Multi-module aggregation (root `build.gradle.kts`)
+
+Add a top-level `dependencies { }` block declaring the three submodules as Dokka
+aggregation inputs. The root documents itself and pulls in the three:
+
+```kotlin
+dependencies {
+    dokka(project(":tree-structure-serialization"))
+    dokka(project(":tree-structure-coroutines"))
+    dokka(project(":tree-structure-compose"))
+}
+```
+
+- Generating task: **`:dokkaGeneratePublicationHtml`** (root project).
+- Output directory: **`build/dokka/html`** (the aggregated site, default location).
+
+### 3. Source links + site title
+
+A `dokka { }` block is added to **each of the four module build files**. The
+`sourceLink` derives the per-module GitHub path from the project layout so each
+module is correct without hardcoding paths:
+
+```kotlin
+dokka {
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            localDirectory.set(projectDir.resolve("src"))
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
+}
+```
+
+- For the **root** module, `module` is empty → links resolve to `…/blob/master/src/…`.
+- For a submodule (e.g. serialization) → `…/blob/master/tree-structure-serialization/src/…`.
+- Links point at the **`master`** branch. Trade-off: a previously deployed page links
+  to current `master`, which may have drifted. Accepted for simplicity; tag-accurate
+  links are a possible follow-up.
+
+The **root** module additionally sets a friendly site title:
+
+```kotlin
+dokka {
+    moduleName.set("Tree Data Structure")
+    // ...sourceLink block as above...
+}
+```
+
+Submodules keep their default module names (`tree-structure-serialization`,
+`tree-structure-coroutines`, `tree-structure-compose`).
+
+### 4. Pages workflow — `.github/workflows/docs.yml`
+
+```yaml
+name: Docs
+
+on:
+  release:
+    types: [released]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Dokka HTML
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+      - name: Generate API docs
+        run: ./gradlew :dokkaGeneratePublicationHtml --console=plain
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/dokka/html
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+- Triggers: `release: [released]` (matches the issue) **+** `workflow_dispatch`
+  (manual rebuild without a release).
+- Official GitHub Pages Actions (no `gh-pages` branch).
+- Runs on `ubuntu-latest` to match `publishRelease.yml`. **Fallback:** if Dokka
+  cannot resolve the Apple source sets on Linux CI, switch the `build` job to
+  `macos-latest` (as the iOS test job already does).
+
+### 5. README
+
+In the badge row near the top, add a docs badge and a one-line pointer:
+
+```markdown
+[![API docs](https://img.shields.io/badge/docs-API%20reference-blue?style=plastic)](https://adriankuta.github.io/Tree-Data-Structure/)
+```
+
+Plus a short line under the badges:
+
+```markdown
+📖 **[API reference](https://adriankuta.github.io/Tree-Data-Structure/)** — full KDoc for all modules.
+```
+
+Site URL: `https://adriankuta.github.io/Tree-Data-Structure/`.
+
+### 6. One-time manual step (repo owner, not code)
+
+GitHub Pages must be enabled once: **Settings → Pages → Source = "GitHub Actions"**.
+Until then the `deploy` job fails. This will be called out in the PR / final summary.
+
+## Verification (before claiming done)
+
+1. `./gradlew :dokkaGeneratePublicationHtml --console=plain` locally on **macOS**
+   (covers Apple source sets) → confirm `build/dokka/html/index.html` exists and the
+   site lists **all four** modules, with working source links.
+2. `./gradlew javadocJar --console=plain` → confirm the vanniktech javadoc jar(s)
+   still build under Dokka 2.x (release pipeline unaffected). Optionally
+   `./gradlew publishToMavenLocal -Psnapshot=true` for an end-to-end check.
+3. `./gradlew apiCheck` and the existing test tasks still pass (no API/source impact).
+4. Validate `docs.yml` YAML (well-formed, correct action versions).
+
+## Risks & mitigations
+
+| Risk | Mitigation |
+| --- | --- |
+| Dokka 2.x breaks the javadoc jar | vanniktech 0.34.0 supports `V2Enabled`; verify with `javadocJar` step 2 above. |
+| Dokka can't resolve Apple source sets on Linux CI | Verify locally on macOS; fallback `macos-latest` for the build job. |
+| Source-link paths wrong for a module | Derived from `projectDir.relativeTo(rootDir)`; visually verify links in step 1. |
+| Pages deploy fails on first run | Documented manual prerequisite (Settings → Pages → GitHub Actions). |
+
+## Files touched
+
+- `gradle/libs.versions.toml` — Dokka version bump.
+- `gradle.properties` — `V2Enabled` flags.
+- `build.gradle.kts` (root) — aggregation `dependencies`, `dokka { moduleName + sourceLink }`.
+- `tree-structure-serialization/build.gradle.kts` — `dokka { sourceLink }`.
+- `tree-structure-coroutines/build.gradle.kts` — `dokka { sourceLink }`.
+- `tree-structure-compose/build.gradle.kts` — `dokka { sourceLink }`.
+- `.github/workflows/docs.yml` — new Pages workflow.
+- `README.md` — docs badge + link.

gradle.properties

@@ -1 +1,10 @@
 kotlin.code.style=official
+# Dokka Gradle Plugin v2 (https://kotl.in/dokka-gradle-migration)
+org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
+org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true
+# Android: Compose pulls AndroidX artifacts, which AGP requires this flag to consume.
+android.useAndroidX=true
+# AGP loads many classes into the Gradle daemon's Metaspace; combined with the KMP
+# matrix, binary-compatibility-validator, Kover and Dokka in a single build, the
+# default 512m heap / 384m Metaspace is exhausted (daemon OOM). Raise both.
+org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g -Dfile.encoding=UTF-8

gradle/libs.versions.toml

@@ -1,16 +1,24 @@
 [versions]
 kotlin = "2.1.0"
-dokka = "1.9.20"
+agp = "8.7.2"
+androidCompileSdk = "35"
+androidMinSdk = "21"
+activityCompose = "1.9.3"
+dokka = "2.2.0"
 mavenPublish = "0.34.0"
 binaryCompatibilityValidator = "0.16.3"
 kover = "0.8.3"
 coroutines = "1.9.0"
 kotlinxSerialization = "1.7.3"
+kotlinxCollectionsImmutable = "0.3.8"
 composeMultiplatform = "1.7.3"
 
 [plugins]
 kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
+kotlinAndroid = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
 kotlinSerialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+androidLibrary = { id = "com.android.library", version.ref = "agp" }
+androidApplication = { id = "com.android.application", version.ref = "agp" }
 dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }
 mavenPublish = { id = "com.vanniktech.maven.publish", version.ref = "mavenPublish" }
 binaryCompatibilityValidator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "binaryCompatibilityValidator" }
@@ -22,3 +30,5 @@ composeCompiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "k
 kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
 kotlinx-coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", version.ref = "coroutines" }
 kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerialization" }
+kotlinx-collections-immutable = { module = "org.jetbrains.kotlinx:kotlinx-collections-immutable", version.ref = "kotlinxCollectionsImmutable" }
+androidx-activity-compose = { module = "androidx.activity:activity-compose", version.ref = "activityCompose" }

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

samples-android/build.gradle.kts

@@ -0,0 +1,48 @@
+plugins {
+    alias(libs.plugins.androidApplication)
+    alias(libs.plugins.kotlinAndroid)
+    alias(libs.plugins.composeMultiplatform)
+    alias(libs.plugins.composeCompiler)
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+kotlin {
+    jvmToolchain(21)
+    // Match the Kotlin bytecode target to the Java level in android.compileOptions below.
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
+android {
+    namespace = "com.github.adriankuta.treestructure.sample"
+    compileSdk = libs.versions.androidCompileSdk.get().toInt()
+
+    defaultConfig {
+        applicationId = "com.github.adriankuta.treestructure.sample"
+        minSdk = libs.versions.androidMinSdk.get().toInt()
+        targetSdk = libs.versions.androidCompileSdk.get().toInt()
+        versionCode = 1
+        versionName = rootProject.version.toString()
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+}
+
+dependencies {
+    implementation(project(":"))
+    implementation(project(":tree-structure-compose"))
+
+    implementation(compose.foundation)
+    implementation(compose.material3)
+    implementation(compose.components.uiToolingPreview)
+    implementation(libs.androidx.activity.compose)
+    debugImplementation(compose.uiTooling)
+}

samples-android/src/main/AndroidManifest.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <application
+        android:allowBackup="true"
+        android:label="Tree Sample"
+        android:theme="@android:style/Theme.Material.Light.NoActionBar">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

samples-android/src/main/kotlin/com/github/adriankuta/treestructure/sample/MainActivity.kt

@@ -0,0 +1,73 @@
+package com.github.adriankuta.treestructure.sample
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import com.github.adriankuta.datastructure.tree.TreeNode
+import com.github.adriankuta.datastructure.tree.compose.LazyTree
+import com.github.adriankuta.datastructure.tree.compose.TreeNodeRow
+import com.github.adriankuta.datastructure.tree.tree
+import org.jetbrains.compose.ui.tooling.preview.Preview
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            MaterialTheme {
+                Surface(modifier = Modifier.fillMaxSize()) {
+                    TreeSampleScreen()
+                }
+            }
+        }
+    }
+}
+
+/** Renders the [sampleTree] with the library's default [TreeNodeRow] via the one-line [LazyTree]. */
+@Composable
+fun TreeSampleScreen() {
+    LazyTree(sampleTree())
+}
+
+private fun sampleTree(): TreeNode<String> = tree("World") {
+    child("North America") {
+        child("USA")
+        child("Canada")
+    }
+    child("Europe") {
+        child("Poland")
+        child("Germany")
+        child("Spain")
+    }
+    child("Asia") {
+        child("Japan")
+        child("India")
+    }
+}
+
+@Preview
+@Composable
+private fun TreeSampleScreenPreview() {
+    MaterialTheme {
+        Surface {
+            TreeSampleScreen()
+        }
+    }
+}
+
+@Preview
+@Composable
+private fun TreeNodeRowPreview() {
+    MaterialTheme {
+        TreeNodeRow(
+            node = TreeNode("Europe").apply { addChild(TreeNode("Poland")) },
+            depth = 1,
+            expanded = true,
+            toggle = {},
+        )
+    }
+}

samples/build.gradle.kts

@@ -0,0 +1,35 @@
+plugins {
+    // No version: the Kotlin Gradle plugin is already on the build classpath via the root
+    // project's kotlinMultiplatform plugin, so requesting a version here would clash.
+    kotlin("jvm")
+    application
+}
+
+kotlin {
+    jvmToolchain(21)
+}
+
+application {
+    mainClass.set("com.github.adriankuta.samples.SamplesKt")
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation(project(":"))
+    implementation(project(":tree-structure-serialization"))
+    implementation(project(":tree-structure-coroutines"))
+    implementation(project(":tree-structure-immutable"))
+    // ImmutableTreeNode.children returns a PersistentList, so consumers that touch it need
+    // kotlinx.collections.immutable on their own classpath (the module declares it as implementation).
+    implementation(libs.kotlinx.collections.immutable)
+
+    testImplementation(kotlin("test"))
+}
+
+// kotlin("test") auto-selects the JUnit 5 adapter when the test task uses the JUnit Platform.
+tasks.test {
+    useJUnitPlatform()
+}

samples/src/main/kotlin/com/github/adriankuta/samples/Samples.kt

@@ -0,0 +1,121 @@
+package com.github.adriankuta.samples
+
+import com.github.adriankuta.datastructure.tree.TreeNode
+import com.github.adriankuta.datastructure.tree.ancestors
+import com.github.adriankuta.datastructure.tree.anyNode
+import com.github.adriankuta.datastructure.tree.countNodes
+import com.github.adriankuta.datastructure.tree.deepCopy
+import com.github.adriankuta.datastructure.tree.distance
+import com.github.adriankuta.datastructure.tree.filterNodes
+import com.github.adriankuta.datastructure.tree.findNode
+import com.github.adriankuta.datastructure.tree.isLeaf
+import com.github.adriankuta.datastructure.tree.leaves
+import com.github.adriankuta.datastructure.tree.levelOrderSequence
+import com.github.adriankuta.datastructure.tree.lowestCommonAncestor
+import com.github.adriankuta.datastructure.tree.mapValues
+import com.github.adriankuta.datastructure.tree.pathBetween
+import com.github.adriankuta.datastructure.tree.preOrderSequence
+import com.github.adriankuta.datastructure.tree.structurallyEquals
+import com.github.adriankuta.datastructure.tree.tree
+import com.github.adriankuta.datastructure.tree.coroutines.asFlow
+import com.github.adriankuta.datastructure.tree.coroutines.preOrderFlow
+import com.github.adriankuta.datastructure.tree.immutable.ImmutableTreeNode
+import com.github.adriankuta.datastructure.tree.immutable.preOrder
+import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
+import com.github.adriankuta.datastructure.tree.serialization.TreeNodeDto
+import com.github.adriankuta.datastructure.tree.serialization.toDto
+import com.github.adriankuta.datastructure.tree.serialization.toTreeNode
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.toList
+import kotlinx.coroutines.runBlocking
+import kotlinx.serialization.decodeFromString
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+
+private fun sampleTree(): TreeNode<String> = tree("World") {
+    child("North America") {
+        child("USA")
+    }
+    child("Europe") {
+        child("Poland")
+        child("Germany")
+    }
+}
+
+/** Core API: DSL, pretty-print, traversal, navigation, functional, query, utilities, mutation. */
+fun coreSample(): String = buildString {
+    val root = sampleTree()
+
+    appendLine("prettyString():")
+    append(root.prettyString())
+    appendLine()
+
+    appendLine("pre-order:   " + root.preOrderSequence().map { it.value }.toList())
+    appendLine("level-order: " + root.levelOrderSequence().map { it.value }.toList())
+
+    val usa = root.findNode { it == "USA" }!!
+    val poland = root.findNode { it == "Poland" }!!
+    appendLine("usa.depth():       " + usa.depth())
+    appendLine("usa.ancestors():   " + usa.ancestors().map { it.value })
+    appendLine("root.leaves():     " + root.leaves().map { it.value })
+    appendLine("usa.isLeaf:        " + usa.isLeaf)
+
+    appendLine("anyNode == Poland: " + root.anyNode { it == "Poland" })
+    appendLine("filterNodes len>5: " + root.filterNodes { it.length > 5 }.map { it.value })
+    appendLine("countNodes 'U*':   " + root.countNodes { it.startsWith("U") })
+    appendLine("mapValues length:  " + root.mapValues { it.length }.preOrderSequence().map { it.value }.toList())
+    appendLine("deepCopy equals:   " + root.structurallyEquals(root.deepCopy()))
+
+    appendLine("lowestCommonAncestor(USA, Poland): " + usa.lowestCommonAncestor(poland)?.value)
+    appendLine("pathBetween(USA, Poland):          " + usa.pathBetween(poland)?.map { it.value })
+    appendLine("distance(USA, Poland):             " + usa.distance(poland))
+
+    appendLine("nodeCount(): " + root.nodeCount())
+    appendLine("height():    " + root.height())
+    appendLine("path(USA):   " + root.path(usa)?.map { it.value })
+
+    // Mutation on a copy; the shared sampleTree() stays untouched.
+    val mutable = root.deepCopy()
+    mutable.addChild(TreeNode("Asia"))
+    mutable.findNode { it == "Germany" }?.detach()
+    appendLine("after addChild(Asia) + detach(Germany): " + mutable.preOrderSequence().map { it.value }.toList())
+}
+
+/** Serialization satellite: TreeNode -> TreeNodeDto -> JSON -> TreeNodeDto -> TreeNode round-trip. */
+fun serializationSample(): String = buildString {
+    val root = sampleTree()
+    val json = Json.encodeToString(root.toDto())
+    appendLine("JSON: $json")
+    val restored = Json.decodeFromString<TreeNodeDto<String>>(json).toTreeNode()
+    appendLine("round-trips structurallyEquals: " + root.structurallyEquals(restored))
+}
+
+/** Coroutines satellite: traverse the tree as a cold Flow. */
+fun coroutinesSample(): String = buildString {
+    val root = sampleTree()
+    val preOrder = runBlocking { root.preOrderFlow().map { it.value }.toList() }
+    val levelOrder = runBlocking { root.asFlow(TreeNodeIterators.LevelOrder).map { it.value }.toList() }
+    appendLine("preOrderFlow():     $preOrder")
+    appendLine("asFlow(LevelOrder): $levelOrder")
+}
+
+/** Immutable satellite: persistent tree; every op returns a new root, leaving the original intact. */
+fun immutableSample(): String = buildString {
+    val root = ImmutableTreeNode("World").addChild(ImmutableTreeNode("Europe"))
+    val bigger = root.addChild(ImmutableTreeNode("Asia"))
+    appendLine("root.children:   " + root.children.map { it.value })
+    appendLine("bigger.children: " + bigger.children.map { it.value })
+    appendLine("root unchanged:  " + (root.children.size == 1))
+    appendLine("bigger.mapValues uppercase preOrder: " + bigger.mapValues { it.uppercase() }.preOrder().map { it.value })
+}
+
+fun main() {
+    println("== Core ==")
+    println(coreSample())
+    println("== Serialization ==")
+    println(serializationSample())
+    println("== Coroutines ==")
+    println(coroutinesSample())
+    println("== Immutable ==")
+    println(immutableSample())
+}

samples/src/test/kotlin/com/github/adriankuta/samples/SamplesTest.kt

@@ -0,0 +1,46 @@
+package com.github.adriankuta.samples
+
+import kotlin.test.Test
+import kotlin.test.assertContains
+
+class SamplesTest {
+
+    @Test
+    fun coreSampleRendersTreeAndTraversals() {
+        val out = coreSample()
+        assertContains(
+            out,
+            "World\n" +
+                "├── North America\n" +
+                "│   └── USA\n" +
+                "└── Europe\n" +
+                "    ├── Poland\n" +
+                "    └── Germany\n",
+        )
+        assertContains(out, "[World, North America, USA, Europe, Poland, Germany]")
+        assertContains(out, "[North America, World]") // usa.ancestors()
+        assertContains(out, "[USA, Poland, Germany]") // root.leaves()
+    }
+
+    @Test
+    fun serializationSampleRoundTrips() {
+        val out = serializationSample()
+        assertContains(out, "\"World\"")
+        assertContains(out, "round-trips structurallyEquals: true")
+    }
+
+    @Test
+    fun coroutinesSampleCollectsFlows() {
+        val out = coroutinesSample()
+        assertContains(out, "preOrderFlow():     [World, North America, USA, Europe, Poland, Germany]")
+        assertContains(out, "asFlow(LevelOrder): [World, North America, Europe, USA, Poland, Germany]")
+    }
+
+    @Test
+    fun immutableSampleLeavesRootUnchanged() {
+        val out = immutableSample()
+        assertContains(out, "root.children:   [Europe]")
+        assertContains(out, "bigger.children: [Europe, Asia]")
+        assertContains(out, "root unchanged:  true")
+    }
+}

settings.gradle.kts

@@ -1,5 +1,16 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
 rootProject.name = "tree-structure"
 
 include(":tree-structure-serialization")
 include(":tree-structure-coroutines")
 include(":tree-structure-compose")
+include(":tree-structure-immutable")
+include(":samples")
+include(":samples-android")

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/TreeNode.kt

@@ -61,6 +61,19 @@ public open class TreeNode<T>(public val value: T, public val treeIterator: Tree
      *   a cycle (i.e. [child] is this node or one of its ancestors).
      */
     public fun addChild(child: TreeNode<T>) {
+        validateAttachable(child)
+        child._parent = this
+        _children.add(child)
+    }
+
+    /**
+     * Validates that [child] can be attached as a direct child of this node, throwing if it cannot.
+     *
+     * @param child the node about to be attached.
+     * @throws TreeNodeException if [child] already has a parent, or if attaching it here would create
+     *   a cycle (i.e. [child] is this node or one of its ancestors).
+     */
+    private fun validateAttachable(child: TreeNode<T>) {
         if (child._parent != null) {
             throw TreeNodeException("$child already has a parent; call detach() before re-attaching it.")
         }
@@ -78,8 +91,6 @@ public open class TreeNode<T>(public val value: T, public val treeIterator: Tree
                 ancestor = ancestor._parent
             }
         }
-        child._parent = this
-        _children.add(child)
     }
 
     /**
@@ -118,6 +129,102 @@ public open class TreeNode<T>(public val value: T, public val treeIterator: Tree
         return removed
     }
 
+    /**
+     * Inserts [child] as a direct child of this node at the given [index], shifting any existing
+     * children at and after [index] one position to the right.
+     *
+     * @param index the position at which to insert [child]; must be in `0..children.size`.
+     * @param child a node that is not already attached to a tree. To move a node that already has a
+     *   parent, call [detach] on it first.
+     * @throws IndexOutOfBoundsException if [index] is out of range.
+     * @throws TreeNodeException if [child] already has a parent, or if attaching it here would create
+     *   a cycle (i.e. [child] is this node or one of its ancestors).
+     */
+    public fun insertChild(index: Int, child: TreeNode<T>) {
+        validateAttachable(child)
+        child._parent = this
+        _children.add(index, child)
+    }
+
+    /**
+     * Removes the direct child at the given [index], detaching it (its parent becomes `null`).
+     *
+     * @param index the position of the child to remove; must be in `0 until children.size`.
+     * @return the detached child that was at [index].
+     * @throws IndexOutOfBoundsException if [index] is out of range.
+     */
+    public fun removeChildAt(index: Int): TreeNode<T> {
+        val removed = _children.removeAt(index)
+        removed._parent = null
+        return removed
+    }
+
+    /**
+     * Replaces the direct child at the given [index] with [child], detaching the previous child
+     * (its parent becomes `null`).
+     *
+     * @param index the position of the child to replace; must be in `0 until children.size`.
+     * @param child a node that is not already attached to a tree. To move a node that already has a
+     *   parent, call [detach] on it first.
+     * @return the previous child that was at [index], now detached.
+     * @throws IndexOutOfBoundsException if [index] is out of range.
+     * @throws TreeNodeException if [child] already has a parent, or if attaching it here would create
+     *   a cycle (i.e. [child] is this node or one of its ancestors).
+     */
+    public fun replaceChild(index: Int, child: TreeNode<T>): TreeNode<T> {
+        validateAttachable(child)
+        val old = _children[index]
+        old._parent = null
+        child._parent = this
+        _children[index] = child
+        return old
+    }
+
+    /**
+     * Moves an existing direct [child] to a new position within this node's [children].
+     *
+     * [toIndex] is coerced into the valid range, so out-of-range targets clamp to the first or last
+     * position. Because [child] is already a direct child, no re-parenting or cycle check is needed.
+     *
+     * @param child the node to reorder; must already be a direct child of this node.
+     * @param toIndex the target position for [child] after removal, coerced into `0..children.size`.
+     * @return `true` if [child] was a direct child and has been moved; `false` otherwise.
+     */
+    public fun moveChild(child: TreeNode<T>, toIndex: Int): Boolean {
+        val from = _children.indexOf(child)
+        if (from < 0) return false
+        _children.removeAt(from)
+        _children.add(toIndex.coerceIn(0, _children.size), child)
+        return true
+    }
+
+    /**
+     * Adds each of [children] as a direct child of this node, in order, validating each one the same
+     * way as [addChild].
+     *
+     * Validation is performed per node as it is added, so if one node fails the children added before
+     * it remain attached (the same partial-application behaviour as calling [addChild] in a loop).
+     *
+     * @param children nodes that are not already attached to a tree.
+     * @throws TreeNodeException if any node already has a parent, or if attaching it here would create
+     *   a cycle (i.e. it is this node or one of its ancestors).
+     */
+    public fun addChildren(vararg children: TreeNode<T>) {
+        for (child in children) {
+            addChild(child)
+        }
+    }
+
+    /**
+     * Sorts this node's direct [children] in place according to the given [comparator]. Only the
+     * immediate children are reordered; their subtrees are left untouched.
+     *
+     * @param comparator the comparator used to order the children.
+     */
+    public fun sortChildren(comparator: Comparator<TreeNode<T>>) {
+        _children.sortWith(comparator)
+    }
+
     /**
      * This function go through tree and counts children. Root element is not counted.
      * @return All child and nested child count.

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/TreeNodePrettyPrintExt.kt

@@ -0,0 +1,106 @@
+package com.github.adriankuta.datastructure.tree
+
+/**
+ * The four glyph strings used to draw the tree branches in [prettyString].
+ *
+ * Each value is the literal text emitted at the matching position:
+ * - [branch] precedes a child that is **not** its parent's last child.
+ * - [lastBranch] precedes a child that **is** its parent's last child.
+ * - [vertical] is accumulated into the prefix of the descendants of a non-last child (it keeps the
+ *   vertical guide line going).
+ * - [empty] is accumulated into the prefix of the descendants of a last child (no guide line is
+ *   needed past the last branch).
+ *
+ * Use [Default] for the box-drawing style or [Ascii] for a plain-ASCII style, or supply your own.
+ *
+ * @property branch drawn before a non-last child.
+ * @property vertical continuation prefix for descendants of a non-last child.
+ * @property lastBranch drawn before the last child.
+ * @property empty continuation prefix for descendants of a last child.
+ */
+public data class TreeConnectors(
+    public val branch: String,
+    public val vertical: String,
+    public val lastBranch: String,
+    public val empty: String,
+) {
+    public companion object {
+        /** Box-drawing connectors, matching the output of the no-arg [TreeNode.prettyString]. */
+        public val Default: TreeConnectors = TreeConnectors(
+            branch = "├── ",
+            vertical = "│   ",
+            lastBranch = "└── ",
+            empty = "    ",
+        )
+
+        /** Plain-ASCII connectors for terminals or fonts that lack box-drawing glyphs. */
+        public val Ascii: TreeConnectors = TreeConnectors(
+            branch = "|-- ",
+            vertical = "|   ",
+            lastBranch = "`-- ",
+            empty = "    ",
+        )
+    }
+}
+
+/**
+ * Renders this subtree as a multi-line string, one node per line, with branch connectors.
+ *
+ * Calling this with all defaults produces output byte-identical to the no-arg member
+ * [TreeNode.prettyString]. Customise the drawing with [connectors] (e.g. [TreeConnectors.Ascii]) and
+ * the per-node text with [render].
+ *
+ * @param connectors the glyph set used to draw the branches. Defaults to [TreeConnectors.Default].
+ * @param render produces the text for each node from its `value`, its `depth` (distance from this
+ *   receiver, which is `0`) and `isLast` (whether the node is its parent's last child; the root is
+ *   considered `true`). Defaults to the value's string form (`"$value"`), which renders a `null`
+ *   value as `"null"` to match the no-arg member.
+ * @return the rendered tree, each line terminated by `\n`.
+ */
+public fun <T> TreeNode<T>.prettyString(
+    connectors: TreeConnectors = TreeConnectors.Default,
+    render: (value: T, depth: Int, isLast: Boolean) -> String = { value, _, _ -> "$value" },
+): String {
+    val stringBuilder = StringBuilder()
+    appendPretty(stringBuilder, "", "", 0, true, connectors, render)
+    return stringBuilder.toString()
+}
+
+private fun <T> TreeNode<T>.appendPretty(
+    stringBuilder: StringBuilder,
+    prefix: String,
+    childrenPrefix: String,
+    depth: Int,
+    isLast: Boolean,
+    connectors: TreeConnectors,
+    render: (value: T, depth: Int, isLast: Boolean) -> String,
+) {
+    stringBuilder.append(prefix)
+    stringBuilder.append(render(value, depth, isLast))
+    stringBuilder.append('\n')
+    val childIterator = children.iterator()
+    while (childIterator.hasNext()) {
+        val node = childIterator.next()
+        if (childIterator.hasNext()) {
+            node.appendPretty(
+                stringBuilder,
+                childrenPrefix + connectors.branch,
+                childrenPrefix + connectors.vertical,
+                depth + 1,
+                false,
+                connectors,
+                render,
+            )
+        } else {
+            node.appendPretty(
+                stringBuilder,
+                childrenPrefix + connectors.lastBranch,
+                childrenPrefix + connectors.empty,
+                depth + 1,
+                true,
+                connectors,
+                render,
+            )
+        }
+    }
+}

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/TreeNodeQueryExt.kt

@@ -0,0 +1,88 @@
+package com.github.adriankuta.datastructure.tree
+
+/**
+ * The lowest (deepest) node that is an ancestor of both this node and [other], where every node is
+ * considered an ancestor of itself.
+ *
+ * Nodes are compared by identity (`===`), so this only returns a node when both arguments live in
+ * the same tree.
+ *
+ * @param other the other node to find the common ancestor with.
+ * @return the lowest common ancestor, or `null` when the two nodes belong to different trees and
+ *   therefore share no common ancestor.
+ *
+ * Runs in `O(da + db)` time and `O(da + db)` space, where `da`/`db` are the depths of the two nodes.
+ */
+public fun <T> TreeNode<T>.lowestCommonAncestor(other: TreeNode<T>): TreeNode<T>? {
+    // TreeNode has identity equality, so a HashSet gives O(1) identity membership and keeps the
+    // overall walk at O(da + db). Collect [other] and its ancestors, then climb from this node
+    // upward; the first node already on [other]'s chain is the deepest common ancestor.
+    val ancestorsOfOther = HashSet<TreeNode<T>>(other.ancestors())
+    ancestorsOfOther.add(other)
+    var node: TreeNode<T>? = this
+    while (node != null) {
+        if (node in ancestorsOfOther) return node
+        node = node.parent
+    }
+    return null
+}
+
+/**
+ * The number of edges on the shortest path between this node and [other].
+ *
+ * Computed as `depth() + other.depth() - 2 * lca.depth()`, where `lca` is their
+ * [lowestCommonAncestor]. The distance from a node to itself is `0`.
+ *
+ * @param other the other node to measure the distance to.
+ * @return the edge count, or `null` when the two nodes belong to different trees.
+ *
+ * Runs in `O(da + db)` time, where `da`/`db` are the depths of the two nodes.
+ */
+public fun <T> TreeNode<T>.distance(other: TreeNode<T>): Int? {
+    val lca = lowestCommonAncestor(other) ?: return null
+    return depth() + other.depth() - 2 * lca.depth()
+}
+
+/**
+ * The shortest path of nodes from this node to [other], inclusive of both endpoints.
+ *
+ * The path ascends from this node up to their [lowestCommonAncestor] and then descends to [other];
+ * the common ancestor appears exactly once. When `this === other` the result is `listOf(this)`. When
+ * one node is an ancestor of the other the path is simply the chain between them.
+ *
+ * @param other the node the path ends at.
+ * @return the path `[this, …, lca, …, other]`, or `null` when the two nodes belong to different
+ *   trees.
+ *
+ * Runs in `O(da + db)` time and space, where `da`/`db` are the depths of the two nodes.
+ */
+public fun <T> TreeNode<T>.pathBetween(other: TreeNode<T>): List<TreeNode<T>>? {
+    val lca = lowestCommonAncestor(other) ?: return null
+    val up = mutableListOf<TreeNode<T>>()
+    var node: TreeNode<T> = this
+    up.add(node)
+    while (node !== lca) {
+        node = node.parent!!
+        up.add(node)
+    }
+    val down = mutableListOf<TreeNode<T>>()
+    node = other
+    down.add(node)
+    while (node !== lca) {
+        node = node.parent!!
+        down.add(node)
+    }
+    return up + down.dropLast(1).reversed()
+}
+
+/**
+ * Returns `true` when this subtree contains a node whose value equals [value], including the
+ * receiver itself. Values are compared with `==` ([equals]).
+ *
+ * @param value the value to search for.
+ * @return `true` if any node in the pre-order traversal of this subtree holds [value].
+ *
+ * Runs in `O(n)` time over the `n` nodes of this subtree and stops at the first match.
+ */
+public fun <T> TreeNode<T>.contains(value: T): Boolean =
+    preOrderSequence().any { it.value == value }

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodeMutationTest.kt

@@ -0,0 +1,151 @@
+package com.github.adriankuta.datastructure.tree
+
+import com.github.adriankuta.datastructure.tree.exceptions.TreeNodeException
+import kotlin.test.Test
+import kotlin.test.assertContentEquals
+import kotlin.test.assertFailsWith
+import kotlin.test.assertFalse
+import kotlin.test.assertNull
+import kotlin.test.assertSame
+import kotlin.test.assertTrue
+
+class TreeNodeMutationTest {
+
+    @Test
+    fun insertChildAtStartMiddleAndEnd() {
+        val root = TreeNode("root")
+        val a = TreeNode("a")
+        val b = TreeNode("b")
+        val c = TreeNode("c")
+        val d = TreeNode("d")
+
+        root.insertChild(0, b)          // [b]
+        root.insertChild(0, a)          // [a, b]
+        root.insertChild(2, d)          // [a, b, d] (end)
+        root.insertChild(2, c)          // [a, b, c, d] (middle)
+
+        assertContentEquals(listOf(a, b, c, d), root.children)
+        // Each inserted node is re-parented to root.
+        assertSame(root, a.parent)
+        assertSame(root, b.parent)
+        assertSame(root, c.parent)
+        assertSame(root, d.parent)
+    }
+
+    @Test
+    fun removeChildAtReturnsDetachedNodeAndClearsParent() {
+        val root = TreeNode("root")
+        val a = TreeNode("a")
+        val b = TreeNode("b")
+        val c = TreeNode("c")
+        root.addChildren(a, b, c)
+
+        val removed = root.removeChildAt(1)
+
+        assertSame(b, removed)
+        assertNull(removed.parent)
+        assertContentEquals(listOf(a, c), root.children)
+    }
+
+    @Test
+    fun replaceChildSwapsAndDetachesTheOld() {
+        val root = TreeNode("root")
+        val a = TreeNode("a")
+        val b = TreeNode("b")
+        val replacement = TreeNode("replacement")
+        root.addChildren(a, b)
+
+        val old = root.replaceChild(0, replacement)
+
+        assertSame(a, old)
+        assertNull(old.parent)
+        assertSame(root, replacement.parent)
+        assertContentEquals(listOf(replacement, b), root.children)
+    }
+
+    @Test
+    fun moveChildReordersChildren() {
+        val root = TreeNode("root")
+        val a = TreeNode("a")
+        val b = TreeNode("b")
+        val c = TreeNode("c")
+        root.addChildren(a, b, c)
+
+        assertTrue(root.moveChild(a, 2))
+        assertContentEquals(listOf(b, c, a), root.children)
+        // Parent pointer is unchanged after a move.
+        assertSame(root, a.parent)
+    }
+
+    @Test
+    fun moveChildReturnsFalseForNonChild() {
+        val root = TreeNode("root")
+        val a = TreeNode("a")
+        root.addChild(a)
+
+        val stranger = TreeNode("stranger")
+        assertFalse(root.moveChild(stranger, 0))
+        assertContentEquals(listOf(a), root.children)
+    }
+
+    @Test
+    fun addChildrenAppendsAllInOrder() {
+        val root = TreeNode("root")
+        val a = TreeNode("a")
+        val b = TreeNode("b")
+        val c = TreeNode("c")
+
+        root.addChildren(a, b, c)
+
+        assertContentEquals(listOf(a, b, c), root.children)
+        assertSame(root, a.parent)
+        assertSame(root, b.parent)
+        assertSame(root, c.parent)
+    }
+
+    @Test
+    fun addChildrenRejectsNodeThatAlreadyHasAParent() {
+        val root = TreeNode("root")
+        val attached = TreeNode("attached")
+        TreeNode("other").addChild(attached)
+
+        assertFailsWith<TreeNodeException> { root.addChildren(attached) }
+    }
+
+    @Test
+    fun insertChildRejectsNodeThatAlreadyHasAParent() {
+        val root = TreeNode("root")
+        val attached = TreeNode("attached")
+        TreeNode("other").addChild(attached)
+
+        assertFailsWith<TreeNodeException> { root.insertChild(0, attached) }
+    }
+
+    @Test
+    fun replaceChildRejectsNodeThatAlreadyHasAParent() {
+        val root = TreeNode("root")
+        val existing = TreeNode("existing")
+        root.addChild(existing)
+
+        val attached = TreeNode("attached")
+        TreeNode("other").addChild(attached)
+
+        assertFailsWith<TreeNodeException> { root.replaceChild(0, attached) }
+        // The original child is untouched after a failed replace.
+        assertContentEquals(listOf(existing), root.children)
+        assertSame(root, existing.parent)
+    }
+
+    @Test
+    fun sortChildrenReordersByComparator() {
+        val root = TreeNode("root")
+        val c = TreeNode("c")
+        val a = TreeNode("a")
+        val b = TreeNode("b")
+        root.addChildren(c, a, b)
+
+        root.sortChildren(compareBy { it.value })
+
+        assertContentEquals(listOf(a, b, c), root.children)
+    }
+}

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodePrettyPrintTest.kt

@@ -0,0 +1,100 @@
+package com.github.adriankuta.datastructure.tree
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class TreeNodePrettyPrintTest {
+
+    private fun sampleTree(): TreeNode<String> {
+        val root = TreeNode("Root")
+        val beverages = TreeNode("Beverages")
+        val curd = TreeNode("Curd")
+        root.addChild(beverages)
+        root.addChild(curd)
+
+        val tea = TreeNode("tea")
+        val coffee = TreeNode("coffee")
+        beverages.addChild(tea)
+        beverages.addChild(coffee)
+
+        tea.addChild(TreeNode("ginger tea"))
+        tea.addChild(TreeNode("normal tea"))
+
+        curd.addChild(TreeNode("yogurt"))
+        curd.addChild(TreeNode("lassi"))
+        return root
+    }
+
+    @Test
+    fun defaultConnectorsMatchMemberPrettyString() {
+        val root = sampleTree()
+        assertEquals(root.prettyString(), root.prettyString(connectors = TreeConnectors.Default))
+    }
+
+    @Test
+    fun defaultRenderMatchesMemberForNullValues() {
+        // The member prettyString() appends the value via StringBuilder, rendering null as "null".
+        // The all-defaults extension must stay byte-identical, including for null-valued nodes.
+        val root = TreeNode<String?>(null)
+        root.addChild(TreeNode("child"))
+        root.addChild(TreeNode<String?>(null))
+        assertEquals(root.prettyString(), root.prettyString(connectors = TreeConnectors.Default))
+        assertEquals(
+            "null\n" +
+                "├── child\n" +
+                "└── null\n",
+            root.prettyString(),
+        )
+    }
+
+    @Test
+    fun asciiConnectorsRenderPlainAscii() {
+        val root = sampleTree()
+        assertEquals(
+            "Root\n" +
+                "|-- Beverages\n" +
+                "|   |-- tea\n" +
+                "|   |   |-- ginger tea\n" +
+                "|   |   `-- normal tea\n" +
+                "|   `-- coffee\n" +
+                "`-- Curd\n" +
+                "    |-- yogurt\n" +
+                "    `-- lassi\n",
+            root.prettyString(connectors = TreeConnectors.Ascii),
+        )
+    }
+
+    @Test
+    fun customRenderIsApplied() {
+        val root = sampleTree()
+        assertEquals(
+            "ROOT\n" +
+                "├── BEVERAGES\n" +
+                "│   ├── TEA\n" +
+                "│   │   ├── GINGER TEA\n" +
+                "│   │   └── NORMAL TEA\n" +
+                "│   └── COFFEE\n" +
+                "└── CURD\n" +
+                "    ├── YOGURT\n" +
+                "    └── LASSI\n",
+            root.prettyString { value, _, _ -> value.uppercase() },
+        )
+    }
+
+    @Test
+    fun depthAndIsLastArePassedToRender() {
+        val root = sampleTree()
+        assertEquals(
+            "Root depth=0 last=true\n" +
+                "├── Beverages depth=1 last=false\n" +
+                "│   ├── tea depth=2 last=false\n" +
+                "│   │   ├── ginger tea depth=3 last=false\n" +
+                "│   │   └── normal tea depth=3 last=true\n" +
+                "│   └── coffee depth=2 last=true\n" +
+                "└── Curd depth=1 last=true\n" +
+                "    ├── yogurt depth=2 last=false\n" +
+                "    └── lassi depth=2 last=true\n",
+            root.prettyString { value, depth, isLast -> "$value depth=$depth last=$isLast" },
+        )
+    }
+}

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodePropertyTest.kt

@@ -0,0 +1,455 @@
+package com.github.adriankuta.datastructure.tree
+
+import kotlin.random.Random
+import kotlin.test.Test
+import kotlin.test.assertContentEquals
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertNotNull
+import kotlin.test.assertTrue
+
+/**
+ * Property-based tests for traversal and structural invariants (issue #38).
+ *
+ * Instead of a handful of hand-written example trees, each property is checked against many
+ * randomly generated trees. Generation is seeded ([BASE_SEED] + iteration index), so a failing case
+ * is fully reproducible: rerun [randomTree] with the seed printed in the failure message. No
+ * external dependency is used, so these run on every Kotlin target (JVM/JS/Wasm/Native).
+ */
+class TreeNodePropertyTest {
+
+    // -----------------------------------------------------------------------------------------
+    // Traversal node-set invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun allThreeOrdersVisitTheSameSetOfNodes() = forEachRandomTree { tree, seed ->
+        val pre = tree.preOrderSequence().toList()
+        val post = tree.postOrderSequence().toList()
+        val level = tree.levelOrderSequence().toList()
+
+        assertEquals(pre.toSet(), post.toSet(), "pre vs post node set (seed=$seed)")
+        assertEquals(pre.toSet(), level.toSet(), "pre vs level node set (seed=$seed)")
+    }
+
+    @Test
+    fun allThreeOrdersHaveTheSameCardinalityAndNoDuplicates() = forEachRandomTree { tree, seed ->
+        val pre = tree.preOrderSequence().toList()
+        val post = tree.postOrderSequence().toList()
+        val level = tree.levelOrderSequence().toList()
+        val expectedSize = tree.nodeCount() + 1 // traversal includes the root; nodeCount excludes it
+
+        assertEquals(expectedSize, pre.size, "pre-order size (seed=$seed)")
+        assertEquals(expectedSize, post.size, "post-order size (seed=$seed)")
+        assertEquals(expectedSize, level.size, "level-order size (seed=$seed)")
+        assertEquals(pre.size, pre.toSet().size, "pre-order visits no node twice (seed=$seed)")
+        assertEquals(post.size, post.toSet().size, "post-order visits no node twice (seed=$seed)")
+        assertEquals(level.size, level.toSet().size, "level-order visits no node twice (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Per-order ordering invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun preOrderEmitsEverySubtreeAsAContiguousBlockAfterItsRoot() = forEachRandomTree { tree, seed ->
+        val pre = tree.preOrderSequence().toList()
+        val index = pre.indexMap()
+        for (node in pre) {
+            val start = index.getValue(node) + 1
+            val block = pre.subList(start, start + node.nodeCount())
+            assertEquals(node.descendants().toSet(), block.toSet(), "pre-order subtree of $node (seed=$seed)")
+        }
+    }
+
+    @Test
+    fun postOrderEmitsEverySubtreeAsAContiguousBlockBeforeItsRoot() = forEachRandomTree { tree, seed ->
+        val post = tree.postOrderSequence().toList()
+        val index = post.indexMap()
+        for (node in post) {
+            val end = index.getValue(node)
+            val block = post.subList(end - node.nodeCount(), end)
+            assertEquals(node.descendants().toSet(), block.toSet(), "post-order subtree of $node (seed=$seed)")
+        }
+    }
+
+    @Test
+    fun levelOrderVisitsNodesInNonDecreasingDepth() = forEachRandomTree { tree, seed ->
+        val depths = tree.levelOrderSequence().map { it.depth() }.toList()
+        for (i in 1 until depths.size) {
+            assertTrue(depths[i - 1] <= depths[i], "level-order depth not monotonic at $i (seed=$seed)")
+        }
+    }
+
+    @Test
+    fun preAndLevelOrderVisitEveryParentBeforeItsChildren() = forEachRandomTree { tree, seed ->
+        for (order in listOf(tree.preOrderSequence(), tree.levelOrderSequence())) {
+            val index = order.toList().indexMap()
+            for (node in index.keys) {
+                for (child in node.children) {
+                    assertTrue(index.getValue(node) < index.getValue(child), "parent before child (seed=$seed)")
+                }
+            }
+        }
+    }
+
+    @Test
+    fun postOrderVisitsEveryChildBeforeItsParent() = forEachRandomTree { tree, seed ->
+        val index = tree.postOrderSequence().toList().indexMap()
+        for (node in index.keys) {
+            for (child in node.children) {
+                assertTrue(index.getValue(child) < index.getValue(node), "child before parent (seed=$seed)")
+            }
+        }
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // depth / height invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun depthMatchesAnIndependentBfsLevelAndEveryChildIsOneDeeper() = forEachRandomTree { tree, seed ->
+        assertEquals(0, tree.depth(), "root depth (seed=$seed)")
+        // Independent oracle: derive each node's level by walking DOWN through children (BFS), then
+        // cross-check against depth(), which walks UP through parent pointers. A bug in the parent
+        // walk cannot corrupt both derivations identically.
+        val levelByNode = HashMap<TreeNode<Int>, Int>()
+        levelByNode[tree] = 0
+        val queue = ArrayDeque<TreeNode<Int>>()
+        queue.add(tree)
+        while (queue.isNotEmpty()) {
+            val node = queue.removeFirst()
+            for (child in node.children) {
+                levelByNode[child] = levelByNode.getValue(node) + 1
+                queue.add(child)
+            }
+        }
+        for (node in tree) {
+            assertEquals(levelByNode.getValue(node), node.depth(), "depth matches BFS level (seed=$seed)")
+            for (child in node.children) {
+                assertEquals(node.depth() + 1, child.depth(), "child depth (seed=$seed)")
+            }
+        }
+    }
+
+    @Test
+    fun heightEqualsDeepestDescendantDistanceAndLeavesHaveHeightZero() = forEachRandomTree { tree, seed ->
+        for (node in tree) {
+            val expected = node.asSequence().maxOf { it.depth() } - node.depth()
+            assertEquals(expected, node.height(), "height of $node (seed=$seed)")
+            if (node.isLeaf) assertEquals(0, node.height(), "leaf height (seed=$seed)")
+        }
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // nodeCount invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun nodeCountEqualsDescendantCountForEveryNode() = forEachRandomTree { tree, seed ->
+        for (node in tree) {
+            // Independent oracle: nodeCount() walks an explicit stack; the pre-order sequence is a
+            // separate traversal, so agreeing pins the count without circularity.
+            assertEquals(node.asSequence().count() - 1, node.nodeCount(), "nodeCount vs traversal (seed=$seed)")
+            // Recursive self-consistency: a node's count is the sum of (each child + its subtree).
+            assertEquals(node.children.sumOf { it.nodeCount() + 1 }, node.nodeCount(), "nodeCount recursive sum (seed=$seed)")
+        }
+    }
+
+    @Test
+    fun nodeCountAndTraversalStayConsistentAcrossAttachAndDetach() = forEachRandomTree { tree, seed ->
+        // A second, independent tree we graft onto a random node of `tree`, then remove again.
+        val grafted = randomTree(Random(seed * 31 + 7), maxNodes = 20)
+        val host = tree.toList().random(Random(seed xor SELECT_SALT))
+
+        val countBefore = tree.nodeCount()
+        val graftSize = grafted.nodeCount() + 1 // the grafted root plus its descendants
+
+        host.addChild(grafted)
+        assertEquals(countBefore + graftSize, tree.nodeCount(), "nodeCount after addChild (seed=$seed)")
+        assertTrue(tree.toSet().containsAll(grafted.toList()), "grafted nodes now reachable (seed=$seed)")
+        assertSameNode(host, grafted.parent, "graft re-parented (seed=$seed)")
+
+        assertTrue(grafted.detach(), "detach returns true (seed=$seed)")
+        assertEquals(countBefore, tree.nodeCount(), "nodeCount restored after detach (seed=$seed)")
+        assertTrue(grafted.isRoot, "grafted is a root again (seed=$seed)")
+        assertFalse(tree.toSet().contains(grafted), "grafted no longer reachable (seed=$seed)")
+    }
+
+    @Test
+    fun removeAndReinsertKeepNodeCountAndPointersConsistent() = forEachRandomTree { tree, seed ->
+        val rnd = Random(seed xor 0x55AA_55AAL)
+        val parents = tree.toList().filter { it.children.isNotEmpty() }
+        if (parents.isEmpty()) return@forEachRandomTree // single-node tree: nothing to remove
+
+        val parent = parents.random(rnd)
+        val countBefore = tree.nodeCount()
+        val index = rnd.nextInt(parent.children.size)
+        val subtreeSize = parent.children[index].nodeCount() + 1
+
+        val removed = parent.removeChildAt(index)
+        assertTrue(removed.isRoot, "removeChildAt detaches the child (seed=$seed)")
+        assertEquals(countBefore - subtreeSize, tree.nodeCount(), "nodeCount drops by the subtree (seed=$seed)")
+        assertFalse(tree.toSet().contains(removed), "removed subtree no longer reachable (seed=$seed)")
+
+        val insertAt = rnd.nextInt(parent.children.size + 1)
+        parent.insertChild(insertAt, removed)
+        assertEquals(countBefore, tree.nodeCount(), "nodeCount restored after insertChild (seed=$seed)")
+        assertSameNode(parent, removed.parent, "re-inserted subtree is re-parented (seed=$seed)")
+        assertSameNode(removed, parent.children[insertAt], "re-inserted at the requested index (seed=$seed)")
+        for (node in tree) {
+            for (child in node.children) {
+                assertSameNode(node, child.parent, "parent pointers stay consistent (seed=$seed)")
+            }
+        }
+    }
+
+    @Test
+    fun clearRemovesEveryDescendantAndKeepsTheNodeAttached() = forEachRandomTree { tree, seed ->
+        val node = tree.toList().random(Random(seed xor SELECT_SALT))
+        val parentBefore = node.parent
+        node.clear()
+        assertEquals(0, node.nodeCount(), "nodeCount after clear (seed=$seed)")
+        assertTrue(node.children.isEmpty(), "children empty after clear (seed=$seed)")
+        assertSameNode(parentBefore, node.parent, "node keeps its own parent after clear (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Structural / parent-pointer invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun parentAndChildPointersAreConsistentForEveryNode() = forEachRandomTree { tree, seed ->
+        assertTrue(tree.isRoot, "generated root is a root (seed=$seed)")
+        for (node in tree) {
+            assertEquals(node.parent == null, node.isRoot, "isRoot matches null parent (seed=$seed)")
+            assertSameNode(tree, node.root(), "root() returns the tree root (seed=$seed)")
+            for (child in node.children) {
+                assertSameNode(node, child.parent, "child points back to parent (seed=$seed)")
+            }
+            val parent = node.parent
+            if (parent != null) {
+                assertTrue(parent.children.any { it === node }, "node listed in its parent (seed=$seed)")
+                // Note: TreeNode is Iterable, so `list + node` would flatten the node's subtree —
+                // compare siblings against the parent's other children directly instead.
+                assertEquals(
+                    parent.children.filter { it !== node }.toSet(),
+                    node.siblings().toSet(),
+                    "siblings are exactly the parent's other children (seed=$seed)",
+                )
+                assertFalse(node.siblings().any { it === node }, "siblings exclude self (seed=$seed)")
+            }
+        }
+    }
+
+    @Test
+    fun ancestorChainOfEveryNodeTerminatesAtTheRoot() = forEachRandomTree { tree, seed ->
+        for (node in tree) {
+            val ancestors = node.ancestors()
+            assertEquals(node.depth(), ancestors.size, "ancestor count equals depth (seed=$seed)")
+            if (ancestors.isNotEmpty()) {
+                assertSameNode(tree, ancestors.last(), "topmost ancestor is the root (seed=$seed)")
+            }
+            ancestors.forEach { assertTrue(it.depth() < node.depth(), "ancestors are shallower (seed=$seed)") }
+        }
+    }
+
+    @Test
+    fun leavesAreExactlyTheChildlessNodes() = forEachRandomTree { tree, seed ->
+        assertEquals(tree.asSequence().filter { it.isLeaf }.toSet(), tree.leaves().toSet(), "leaves (seed=$seed)")
+        assertTrue(tree.leaves().all { it.isLeaf }, "every leaf is childless (seed=$seed)")
+        assertEquals(tree.toList().size, tree.descendants().size + 1, "descendants + self (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Transform / structural-equality invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun deepCopyAndIdentityMapPreserveShapeWithFreshNodes() = forEachRandomTree { tree, seed ->
+        assertTrue(tree.structurallyEquals(tree), "structurallyEquals is reflexive (seed=$seed)")
+
+        val copy = tree.deepCopy()
+        assertTrue(copy.structurallyEquals(tree), "deepCopy is structurally equal (seed=$seed)")
+        assertEquals(tree.nodeCount(), copy.nodeCount(), "deepCopy node count (seed=$seed)")
+        assertEquals(tree.height(), copy.height(), "deepCopy height (seed=$seed)")
+        assertTrue(copy.toSet().intersect(tree.toSet()).isEmpty(), "deepCopy shares no node object (seed=$seed)")
+
+        val mapped = tree.mapValues { it }
+        assertTrue(mapped.structurallyEquals(tree), "identity mapValues preserves structure (seed=$seed)")
+        assertTrue(mapped.toSet().intersect(tree.toSet()).isEmpty(), "mapValues yields fresh nodes (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Functional / value-query invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun valueQueriesAgreeWithTraversalOverUniqueValues() = forEachRandomTree { tree, seed ->
+        val values = tree.asSequence().map { it.value }.toList()
+        assertEquals(values.size, values.toSet().size, "generated values are unique (seed=$seed)")
+        assertEquals(values.size, tree.countNodes { true }, "countNodes(true) == size (seed=$seed)")
+        for (value in values) {
+            assertTrue(tree.contains(value), "contains present value $value (seed=$seed)")
+            assertNotNull(tree.findNode { it == value }, "findNode present value $value (seed=$seed)")
+        }
+        val absent = values.max() + 1 // values are unique and dense from 0, so this one is absent
+        assertFalse(tree.contains(absent), "absent value not contained (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Query algorithms (lca / distance / pathBetween)
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun lowestCommonAncestorIsTheDeepestSharedAncestor() = forEachRandomTree { tree, seed ->
+        val nodes = tree.toList()
+        val rnd = Random(seed xor 0x1234_5678L)
+        repeat(PAIRS_PER_TREE) {
+            val a = nodes.random(rnd)
+            val b = nodes.random(rnd)
+
+            val lca = a.lowestCommonAncestor(b)
+            assertNotNull(lca, "lca within one tree is non-null (seed=$seed)")
+            assertSameNode(lca, b.lowestCommonAncestor(a), "lca is symmetric (seed=$seed)")
+
+            val ancestorsAndSelfA = (listOf(a) + a.ancestors()).toSet()
+            val ancestorsAndSelfB = (listOf(b) + b.ancestors()).toSet()
+            assertTrue(lca in ancestorsAndSelfA, "lca is an ancestor-or-self of a (seed=$seed)")
+            assertTrue(lca in ancestorsAndSelfB, "lca is an ancestor-or-self of b (seed=$seed)")
+            // Common ancestors form a chain, so the deepest one is unique; it must be the lca itself.
+            val deepestShared = ancestorsAndSelfA.intersect(ancestorsAndSelfB).maxByOrNull { it.depth() }
+            assertSameNode(deepestShared, lca, "lca is the deepest shared ancestor (seed=$seed)")
+        }
+    }
+
+    @Test
+    fun distanceAndPathBetweenAreConsistent() = forEachRandomTree { tree, seed ->
+        val nodes = tree.toList()
+        val rnd = Random(seed xor 0x0F0F_0F0FL)
+        repeat(PAIRS_PER_TREE) {
+            val a = nodes.random(rnd)
+            val b = nodes.random(rnd)
+
+            val distance = a.distance(b)
+            assertNotNull(distance, "distance within one tree is non-null (seed=$seed)")
+            assertTrue(distance >= 0, "distance is non-negative (seed=$seed)")
+            assertEquals(distance, b.distance(a), "distance is symmetric (seed=$seed)")
+
+            val path = a.pathBetween(b)
+            assertNotNull(path, "path within one tree is non-null (seed=$seed)")
+            assertSameNode(a, path.first(), "path starts at a (seed=$seed)")
+            assertSameNode(b, path.last(), "path ends at b (seed=$seed)")
+            assertEquals(distance, path.size - 1, "distance == path edges (seed=$seed)")
+            assertEquals(path.size, path.toSet().size, "path has no repeated node (seed=$seed)")
+            for (i in 1 until path.size) {
+                val (p, q) = path[i - 1] to path[i]
+                assertTrue(p.parent === q || q.parent === p, "consecutive path nodes are an edge (seed=$seed)")
+            }
+        }
+    }
+
+    @Test
+    fun distanceAndPathToSelfAreTrivial() = forEachRandomTree { tree, seed ->
+        val node = tree.toList().random(Random(seed xor SELECT_SALT))
+        assertEquals(0, node.distance(node), "distance to self is 0 (seed=$seed)")
+        assertSameNode(node, node.lowestCommonAncestor(node), "lca with self is self (seed=$seed)")
+        assertEquals(listOf(node), node.pathBetween(node), "path to self is the singleton (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Termination and ordering on degenerate (deep / wide) trees
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun everyTraversalTerminatesAndIsCorrectlyOrderedOnADeepChain() {
+        val depth = 5_000
+        val root = TreeNode(0)
+        var current = root
+        for (i in 1..depth) {
+            val child = TreeNode(i)
+            current.addChild(child)
+            current = child
+        }
+
+        // On a chain pre- and level-order descend the chain; post-order returns it leaf-first. These
+        // pin the actual ordering, not merely that every order visits the same number of nodes.
+        assertContentEquals((0..depth).toList(), root.preOrderSequence().map { it.value }.toList(), "pre-order of a chain")
+        assertContentEquals((0..depth).toList(), root.levelOrderSequence().map { it.value }.toList(), "level-order of a chain")
+        assertContentEquals((depth downTo 0).toList(), root.postOrderSequence().map { it.value }.toList(), "post-order of a chain")
+        assertEquals(depth, root.height(), "height on deep chain")
+        assertEquals(depth, root.nodeCount(), "nodeCount on deep chain")
+        assertEquals(depth, current.depth(), "depth of the deepest node")
+    }
+
+    @Test
+    fun everyTraversalTerminatesAndIsCorrectlyOrderedOnAWideTree() {
+        val width = 5_000
+        val root = TreeNode(0)
+        for (i in 1..width) root.addChild(TreeNode(i))
+
+        // pre- and level-order list the root then its children in order; post-order lists the
+        // children in order then the root.
+        assertContentEquals(listOf(0) + (1..width), root.preOrderSequence().map { it.value }.toList(), "pre-order of a star")
+        assertContentEquals(listOf(0) + (1..width), root.levelOrderSequence().map { it.value }.toList(), "level-order of a star")
+        assertContentEquals((1..width).toList() + 0, root.postOrderSequence().map { it.value }.toList(), "post-order of a star")
+        assertEquals(1, root.height(), "height on wide tree")
+        assertEquals(width, root.nodeCount(), "nodeCount on wide tree")
+        assertTrue(root.children.all { it.depth() == 1 }, "every child of a wide root is at depth 1")
+    }
+}
+
+// ---------------------------------------------------------------------------------------------
+// Random tree generation + property harness
+// ---------------------------------------------------------------------------------------------
+
+private const val ITERATIONS = 200
+private const val BASE_SEED = 0x5EEDL
+
+/** How many random node pairs each query property samples per generated tree. */
+private const val PAIRS_PER_TREE = 8
+
+/** Decorrelates node-selection RNGs from the tree-construction RNG that shares the same seed. */
+private const val SELECT_SALT = 0x2545_F491_4F6C_DD1DL
+
+/** Runs [property] against [iterations] freshly generated random trees, one per derived seed. */
+private fun forEachRandomTree(
+    iterations: Int = ITERATIONS,
+    maxNodes: Int = 80,
+    property: (tree: TreeNode<Int>, seed: Long) -> Unit,
+) {
+    for (i in 0 until iterations) {
+        val seed = BASE_SEED + i
+        property(randomTree(Random(seed), maxNodes), seed)
+    }
+}
+
+/**
+ * Builds a random tree of `1..[maxNodes]` nodes by uniform random attachment: each new node (value
+ * `1, 2, …`) is attached under a uniformly chosen existing node. This samples a broad spread of
+ * shapes — chains, bushy, and lopsided trees, plus single-node trees — without the left-heavy skew
+ * of a depth-first node budget, and is iterative so it never risks the call stack. Values are unique
+ * and dense from `0` (the root). Deterministic for a given [random], so the seed reproduces it.
+ */
+private fun randomTree(random: Random, maxNodes: Int): TreeNode<Int> {
+    val size = random.nextInt(1, maxNodes + 1)
+    val root = TreeNode(0)
+    val nodes = ArrayList<TreeNode<Int>>(size)
+    nodes.add(root)
+    for (value in 1 until size) {
+        val parent = nodes[random.nextInt(nodes.size)]
+        val child = TreeNode(value)
+        parent.addChild(child)
+        nodes.add(child)
+    }
+    return root
+}
+
+/** Maps each node to its position in this traversal. Keys compare by identity (TreeNode equality). */
+private fun List<TreeNode<Int>>.indexMap(): Map<TreeNode<Int>, Int> =
+    withIndex().associate { (i, node) -> node to i }
+
+/** Asserts two references point at the same node object (TreeNode uses identity equality). */
+private fun assertSameNode(expected: TreeNode<*>?, actual: TreeNode<*>?, message: String) {
+    assertTrue(expected === actual, "$message — expected same node as $expected but was $actual")
+}

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodeQueryTest.kt

@@ -0,0 +1,123 @@
+package com.github.adriankuta.datastructure.tree
+
+import kotlin.test.Test
+import kotlin.test.assertContentEquals
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertNull
+import kotlin.test.assertSame
+import kotlin.test.assertTrue
+
+class TreeNodeQueryTest {
+
+    // root(1)
+    // ├── n2(2)
+    // │   ├── n4(4)
+    // │   └── n5(5)
+    // └── n3(3)
+    //     └── n6(6)
+    private val root = TreeNode(1)
+    private val n2 = TreeNode(2)
+    private val n3 = TreeNode(3)
+    private val n4 = TreeNode(4)
+    private val n5 = TreeNode(5)
+    private val n6 = TreeNode(6)
+
+    // A completely separate tree.
+    private val otherRoot = TreeNode(10)
+    private val o11 = TreeNode(11)
+
+    init {
+        root.addChild(n2)
+        root.addChild(n3)
+        n2.addChild(n4)
+        n2.addChild(n5)
+        n3.addChild(n6)
+
+        otherRoot.addChild(o11)
+    }
+
+    @Test
+    fun lowestCommonAncestorOfTwoLeaves() {
+        assertSame(n2, n4.lowestCommonAncestor(n5))
+        assertSame(root, n4.lowestCommonAncestor(n6))
+    }
+
+    @Test
+    fun lowestCommonAncestorOfSameNode() {
+        assertSame(n4, n4.lowestCommonAncestor(n4))
+    }
+
+    @Test
+    fun lowestCommonAncestorOfAncestorAndDescendant() {
+        assertSame(n2, n2.lowestCommonAncestor(n4))
+        assertSame(n2, n4.lowestCommonAncestor(n2))
+        assertSame(root, root.lowestCommonAncestor(n6))
+    }
+
+    @Test
+    fun lowestCommonAncestorOfNodesInDifferentTreesIsNull() {
+        assertNull(n4.lowestCommonAncestor(o11))
+        assertNull(o11.lowestCommonAncestor(n4))
+    }
+
+    @Test
+    fun distanceValues() {
+        assertEquals(0, n4.distance(n4))
+        assertEquals(2, n4.distance(n5))
+        assertEquals(1, n2.distance(n4))
+        assertEquals(4, n4.distance(n6))
+        assertEquals(2, root.distance(n4))
+    }
+
+    @Test
+    fun distanceOfNodesInDifferentTreesIsNull() {
+        assertNull(n4.distance(o11))
+    }
+
+    @Test
+    fun pathBetweenSameNode() {
+        assertContentEquals(listOf(n4), n4.pathBetween(n4))
+    }
+
+    @Test
+    fun pathBetweenTwoLeaves() {
+        // n4 -> n2 -> n5 (lca = n2 appears once, endpoints are n4 and n5)
+        assertContentEquals(listOf(n4, n2, n5), n4.pathBetween(n5))
+        // n4 -> n2 -> root -> n3 -> n6 (lca = root appears once)
+        assertContentEquals(listOf(n4, n2, root, n3, n6), n4.pathBetween(n6))
+    }
+
+    @Test
+    fun pathBetweenWithUnequalDepthLegs() {
+        // Neither is an ancestor of the other and the legs differ in length: n4 is at depth 2, n3 at
+        // depth 1, lca = root. Exercises the asymmetric up/down assembly.
+        assertContentEquals(listOf(n4, n2, root, n3), n4.pathBetween(n3))
+        assertContentEquals(listOf(n3, root, n2, n4), n3.pathBetween(n4))
+    }
+
+    @Test
+    fun pathBetweenAncestorAndDescendant() {
+        assertContentEquals(listOf(n2, n4), n2.pathBetween(n4))
+        assertContentEquals(listOf(n4, n2), n4.pathBetween(n2))
+        assertContentEquals(listOf(root, n3, n6), root.pathBetween(n6))
+    }
+
+    @Test
+    fun pathBetweenOfNodesInDifferentTreesIsNull() {
+        assertNull(n4.pathBetween(o11))
+    }
+
+    @Test
+    fun containsTrueForValuesInSubtree() {
+        assertTrue(root.contains(1)) // the receiver itself
+        assertTrue(root.contains(6))
+        assertTrue(n2.contains(5))
+    }
+
+    @Test
+    fun containsFalseForValuesNotInSubtree() {
+        assertFalse(n2.contains(6)) // n6 lives under n3, not n2
+        assertFalse(root.contains(99))
+    }
+}

tree-structure-compose/api/android/tree-structure-compose.api

@@ -0,0 +1,9 @@
+public final class com/github/adriankuta/datastructure/tree/compose/LazyTreeKt {
+	public static final fun LazyTree (Lcom/github/adriankuta/datastructure/tree/TreeNode;Landroidx/compose/ui/Modifier;ZLkotlin/jvm/functions/Function6;Landroidx/compose/runtime/Composer;II)V
+	public static final fun LazyTree-hGBTI10 (Lcom/github/adriankuta/datastructure/tree/TreeNode;Landroidx/compose/ui/Modifier;ZFLkotlin/jvm/functions/Function1;Landroidx/compose/runtime/Composer;II)V
+}
+
+public final class com/github/adriankuta/datastructure/tree/compose/TreeNodeRowKt {
+	public static final fun TreeNodeRow-PfoAEA0 (Lcom/github/adriankuta/datastructure/tree/TreeNode;IZLkotlin/jvm/functions/Function0;Landroidx/compose/ui/Modifier;FLkotlin/jvm/functions/Function1;Landroidx/compose/runtime/Composer;II)V
+}
+

tree-structure-compose/api/jvm/tree-structure-compose.api

@@ -0,0 +1,9 @@
+public final class com/github/adriankuta/datastructure/tree/compose/LazyTreeKt {
+	public static final fun LazyTree (Lcom/github/adriankuta/datastructure/tree/TreeNode;Landroidx/compose/ui/Modifier;ZLkotlin/jvm/functions/Function6;Landroidx/compose/runtime/Composer;II)V
+	public static final fun LazyTree-hGBTI10 (Lcom/github/adriankuta/datastructure/tree/TreeNode;Landroidx/compose/ui/Modifier;ZFLkotlin/jvm/functions/Function1;Landroidx/compose/runtime/Composer;II)V
+}
+
+public final class com/github/adriankuta/datastructure/tree/compose/TreeNodeRowKt {
+	public static final fun TreeNodeRow-PfoAEA0 (Lcom/github/adriankuta/datastructure/tree/TreeNode;IZLkotlin/jvm/functions/Function0;Landroidx/compose/ui/Modifier;FLkotlin/jvm/functions/Function1;Landroidx/compose/runtime/Composer;II)V
+}
+

tree-structure-compose/api/tree-structure-compose.api

@@ -1,4 +0,0 @@
-public final class com/github/adriankuta/datastructure/tree/compose/LazyTreeKt {
-	public static final fun LazyTree (Lcom/github/adriankuta/datastructure/tree/TreeNode;Landroidx/compose/ui/Modifier;ZLkotlin/jvm/functions/Function6;Landroidx/compose/runtime/Composer;II)V
-}
-

tree-structure-compose/build.gradle.kts

@@ -2,6 +2,7 @@ import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
 
 plugins {
     alias(libs.plugins.kotlinMultiplatform)
+    alias(libs.plugins.androidLibrary)
     alias(libs.plugins.composeMultiplatform)
     alias(libs.plugins.composeCompiler)
     alias(libs.plugins.dokka)
@@ -49,12 +50,33 @@ repositories {
     google()
 }
 
+dokka {
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            // Resolve this module's GitHub source path relative to the repo root.
+            localDirectory.set(projectDir.resolve("src"))
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
+}
+
 kotlin {
     explicitApi()
     jvmToolchain(21)
 
     jvm()
 
+    androidTarget {
+        publishLibraryVariants("release")
+        // Match the Android variant's Kotlin bytecode to the Java level set in compileOptions.
+        compilerOptions {
+            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+        }
+    }
+
     @OptIn(ExperimentalWasmDsl::class)
     wasmJs {
         browser()
@@ -72,3 +94,15 @@ kotlin {
         }
     }
 }
+
+android {
+    namespace = "com.github.adriankuta.datastructure.tree.compose"
+    compileSdk = libs.versions.androidCompileSdk.get().toInt()
+    defaultConfig {
+        minSdk = libs.versions.androidMinSdk.get().toInt()
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+}

tree-structure-compose/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/compose/LazyTree.kt

@@ -5,6 +5,8 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.mutableStateMapOf
 import androidx.compose.runtime.remember
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
 import com.github.adriankuta.datastructure.tree.TreeNode
 
 /**
@@ -49,6 +51,35 @@ public fun <T> LazyTree(
     }
 }
 
+/**
+ * Convenience overload of [LazyTree] that renders each node with the built-in [TreeNodeRow], so the
+ * common case is a single call:
+ *
+ * ```
+ * LazyTree(root)
+ * ```
+ *
+ * Use the overload that takes a `nodeContent` lambda when you need full control over a node's look.
+ *
+ * @param root the root of the tree to display.
+ * @param modifier the [Modifier] applied to the underlying [LazyColumn].
+ * @param initiallyExpanded whether nodes start expanded.
+ * @param indent the horizontal indentation applied per depth level.
+ * @param label maps a node's value to the text shown. Defaults to `toString()`.
+ */
+@Composable
+public fun <T> LazyTree(
+    root: TreeNode<T>,
+    modifier: Modifier = Modifier,
+    initiallyExpanded: Boolean = true,
+    indent: Dp = 16.dp,
+    label: (T) -> String = { it.toString() },
+) {
+    LazyTree(root, modifier, initiallyExpanded) { node, depth, expanded, toggle ->
+        TreeNodeRow(node, depth, expanded, toggle, indent = indent, label = label)
+    }
+}
+
 /**
  * Flattens the tree into the list of currently-visible `(node, depth)` pairs in pre-order, skipping
  * the subtrees of collapsed nodes. Iterative, so it is safe on deep trees.

tree-structure-compose/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/compose/TreeNodeRow.kt

@@ -0,0 +1,59 @@
+package com.github.adriankuta.datastructure.tree.compose
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.text.BasicText
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+import com.github.adriankuta.datastructure.tree.TreeNode
+
+/**
+ * A sensible default row for a single node in a [LazyTree]. The whole row is clickable to expand or
+ * collapse, indentation reflects [depth], and a `▾`/`▸` marker precedes non-leaf nodes.
+ *
+ * It is intentionally foundation-only (no Material), so using it does not pull a theming dependency
+ * into your app. For full control over a node's appearance, use the `LazyTree` overload that takes a
+ * `nodeContent` lambda instead.
+ *
+ * ```
+ * LazyTree(root) { node, depth, expanded, toggle ->
+ *     TreeNodeRow(node, depth, expanded, toggle)
+ * }
+ * ```
+ *
+ * @param node the node to render.
+ * @param depth the node's depth in the tree (root = 0), used for indentation.
+ * @param expanded whether the node is currently expanded.
+ * @param toggle flips this node's expansion state; invoked when the row is clicked.
+ * @param modifier the [Modifier] applied to the row.
+ * @param indent the horizontal indentation applied per depth level.
+ * @param label maps the node's value to the text shown. Defaults to `toString()`.
+ */
+@Composable
+public fun <T> TreeNodeRow(
+    node: TreeNode<T>,
+    depth: Int,
+    expanded: Boolean,
+    toggle: () -> Unit,
+    modifier: Modifier = Modifier,
+    indent: Dp = 16.dp,
+    label: (T) -> String = { it.toString() },
+) {
+    val marker = when {
+        node.children.isEmpty() -> ""
+        expanded -> "▾ "
+        else -> "▸ "
+    }
+    Row(
+        modifier = modifier
+            .fillMaxWidth()
+            .clickable(onClick = toggle)
+            .padding(start = indent * depth, top = 8.dp, bottom = 8.dp, end = 8.dp),
+    ) {
+        BasicText(text = marker + label(node.value))
+    }
+}

tree-structure-coroutines/build.gradle.kts

@@ -46,6 +46,19 @@ repositories {
     mavenCentral()
 }
 
+dokka {
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            // Resolve this module's GitHub source path relative to the repo root.
+            localDirectory.set(projectDir.resolve("src"))
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
+}
+
 kotlin {
     explicitApi()
     jvmToolchain(21)

tree-structure-immutable/api/tree-structure-immutable.api

@@ -0,0 +1,25 @@
+public final class com/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode {
+	public fun <init> (Ljava/lang/Object;Lkotlinx/collections/immutable/PersistentList;)V
+	public synthetic fun <init> (Ljava/lang/Object;Lkotlinx/collections/immutable/PersistentList;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun addChild (Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;)Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;
+	public final fun component1 ()Ljava/lang/Object;
+	public final fun component2 ()Lkotlinx/collections/immutable/PersistentList;
+	public final fun copy (Ljava/lang/Object;Lkotlinx/collections/immutable/PersistentList;)Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;
+	public static synthetic fun copy$default (Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;Ljava/lang/Object;Lkotlinx/collections/immutable/PersistentList;ILjava/lang/Object;)Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getChildren ()Lkotlinx/collections/immutable/PersistentList;
+	public final fun getValue ()Ljava/lang/Object;
+	public fun hashCode ()I
+	public final fun mapValues (Lkotlin/jvm/functions/Function1;)Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;
+	public final fun removeChild (Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;)Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNodeKt {
+	public static final fun height (Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;)I
+	public static final fun levelOrder (Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;)Ljava/util/List;
+	public static final fun nodeCount (Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;)I
+	public static final fun postOrder (Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;)Ljava/util/List;
+	public static final fun preOrder (Lcom/github/adriankuta/datastructure/tree/immutable/ImmutableTreeNode;)Ljava/util/List;
+}
+

tree-structure-immutable/build.gradle.kts

@@ -0,0 +1,101 @@
+import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
+
+plugins {
+    alias(libs.plugins.kotlinMultiplatform)
+    alias(libs.plugins.dokka)
+    alias(libs.plugins.mavenPublish)
+    signing
+}
+
+group = "com.github.adriankuta"
+version = rootProject.version
+
+mavenPublishing {
+    publishToMavenCentral(automaticRelease = false)
+    signAllPublications()
+
+    coordinates("com.github.adriankuta", "tree-structure-immutable", version.toString())
+
+    pom {
+        name.set("Tree Data Structure — immutable")
+        description.set("Immutable, persistent tree variant (ImmutableTreeNode with structural sharing) for the tree-structure library.")
+        url.set("https://github.com/AdrianKuta/Tree-Data-Structure")
+        licenses {
+            license {
+                name.set("MIT License")
+                url.set("https://opensource.org/licenses/MIT")
+                distribution.set("repo")
+            }
+        }
+        developers {
+            developer {
+                id.set("AdrianKuta")
+                name.set("Adrian Kuta")
+                email.set("adrian.kuta93@gmail.com")
+            }
+        }
+        scm {
+            url.set("https://github.com/AdrianKuta/Tree-Data-Structure")
+            connection.set("scm:git:https://github.com/AdrianKuta/Tree-Data-Structure.git")
+            developerConnection.set("scm:git:ssh://git@github.com/AdrianKuta/Tree-Data-Structure.git")
+        }
+    }
+}
+
+repositories {
+    mavenCentral()
+}
+
+dokka {
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            // Resolve this module's GitHub source path relative to the repo root.
+            localDirectory.set(projectDir.resolve("src"))
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
+}
+
+kotlin {
+    explicitApi()
+    jvmToolchain(21)
+
+    jvm()
+
+    js(IR) {
+        browser()
+        nodejs()
+    }
+
+    @OptIn(ExperimentalWasmDsl::class)
+    wasmJs {
+        browser()
+        nodejs()
+    }
+
+    iosX64()
+    iosArm64()
+    iosSimulatorArm64()
+
+    val hostOs = System.getProperty("os.name")
+    val isMingwX64 = hostOs.startsWith("Windows")
+    when {
+        hostOs == "Mac OS X" -> macosX64("native")
+        hostOs == "Linux" -> linuxX64("native")
+        isMingwX64 -> mingwX64("native")
+        else -> throw GradleException("Host OS is not supported in Kotlin/Native.")
+    }
+
+    sourceSets {
+        commonMain.dependencies {
+            api(project(":"))
+            implementation(libs.kotlinx.collections.immutable)
+        }
+        commonTest.dependencies {
+            implementation(kotlin("test"))
+        }
+    }
+}

tree-structure-immutable/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/immutable/ImmutableTreeNode.kt

@@ -0,0 +1,147 @@
+package com.github.adriankuta.datastructure.tree.immutable
+
+import kotlinx.collections.immutable.PersistentList
+import kotlinx.collections.immutable.persistentListOf
+import kotlinx.collections.immutable.toPersistentList
+
+/**
+ * A node in an immutable, persistent n-ary tree. Each node holds a [value] and an ordered
+ * [PersistentList] of [children]; nodes never carry a parent back-reference, so a subtree is a
+ * self-contained, acyclic value.
+ *
+ * Every mutating operation ([addChild], [removeChild], [mapValues]) returns a **new** root and
+ * leaves the receiver untouched. Subtrees that are not on the path of the change are reused as the
+ * same instances (structural sharing), so updates are cheap and old roots stay valid.
+ *
+ * Equality is value-based: two nodes are equal when their [value]s and [children] are equal
+ * (a `data class`), independent of identity.
+ *
+ * @param value the value stored in this node.
+ * @param children the ordered, persistent list of child subtrees.
+ */
+public data class ImmutableTreeNode<T>(
+    public val value: T,
+    public val children: PersistentList<ImmutableTreeNode<T>> = persistentListOf(),
+) {
+
+    /**
+     * Returns a new node with [child] appended to this node's [children]. The receiver and every
+     * existing child subtree are reused unchanged (structural sharing).
+     *
+     * @param child the subtree to append.
+     * @return a new [ImmutableTreeNode] with [child] added; the receiver is not modified.
+     */
+    public fun addChild(child: ImmutableTreeNode<T>): ImmutableTreeNode<T> =
+        copy(children = children.add(child))
+
+    /**
+     * Returns a new node with the first occurrence of [child] removed from this node's direct
+     * [children], compared by value-based equality. If [child] is not a direct child, a structurally
+     * equal new node is returned. The receiver is never modified.
+     *
+     * @param child the direct child subtree to remove.
+     * @return a new [ImmutableTreeNode] without [child]; the receiver is not modified.
+     */
+    public fun removeChild(child: ImmutableTreeNode<T>): ImmutableTreeNode<T> =
+        copy(children = children.remove(child))
+
+    /**
+     * Returns a new tree of the same shape with every node's value transformed by [transform].
+     * The receiver is not modified.
+     *
+     * @param transform maps each node's value of type [T] to a value of type [R].
+     * @return a new [ImmutableTreeNode] of type [R] mirroring this tree's structure.
+     */
+    public fun <R> mapValues(transform: (T) -> R): ImmutableTreeNode<R> =
+        ImmutableTreeNode(transform(value), children.map { it.mapValues(transform) }.toPersistentList())
+}
+
+/**
+ * Returns this subtree's nodes in pre-order (the receiver first, then each child subtree in order).
+ * Implemented iteratively, so it is safe on arbitrarily deep trees.
+ *
+ * @return the nodes of this subtree in pre-order, starting with the receiver.
+ */
+public fun <T> ImmutableTreeNode<T>.preOrder(): List<ImmutableTreeNode<T>> {
+    val result = mutableListOf<ImmutableTreeNode<T>>()
+    val stack = ArrayDeque<ImmutableTreeNode<T>>()
+    stack.addLast(this)
+    while (stack.isNotEmpty()) {
+        val node = stack.removeLast()
+        result.add(node)
+        node.children.asReversed().forEach { stack.addLast(it) }
+    }
+    return result
+}
+
+/**
+ * Returns this subtree's nodes in post-order (each child subtree in order, then the receiver last).
+ * Implemented iteratively, so it is safe on arbitrarily deep trees.
+ *
+ * @return the nodes of this subtree in post-order, ending with the receiver.
+ */
+public fun <T> ImmutableTreeNode<T>.postOrder(): List<ImmutableTreeNode<T>> {
+    val result = ArrayDeque<ImmutableTreeNode<T>>()
+    val stack = ArrayDeque<ImmutableTreeNode<T>>()
+    stack.addLast(this)
+    while (stack.isNotEmpty()) {
+        val node = stack.removeLast()
+        result.addFirst(node)
+        node.children.forEach { stack.addLast(it) }
+    }
+    return result.toList()
+}
+
+/**
+ * Returns this subtree's nodes in level-order (breadth-first: the receiver, then its children, then
+ * their children, and so on). Implemented iteratively, so it is safe on arbitrarily deep trees.
+ *
+ * @return the nodes of this subtree in breadth-first order, starting with the receiver.
+ */
+public fun <T> ImmutableTreeNode<T>.levelOrder(): List<ImmutableTreeNode<T>> {
+    val result = mutableListOf<ImmutableTreeNode<T>>()
+    val queue = ArrayDeque<ImmutableTreeNode<T>>()
+    queue.addLast(this)
+    while (queue.isNotEmpty()) {
+        val node = queue.removeFirst()
+        result.add(node)
+        node.children.forEach { queue.addLast(it) }
+    }
+    return result
+}
+
+/**
+ * Counts all descendants of this node; the receiver itself is not counted (matching the core
+ * `TreeNode.nodeCount`). Implemented iteratively, so it is safe on arbitrarily deep trees.
+ *
+ * @return the number of descendant nodes (children and nested children) of this node.
+ */
+public fun <T> ImmutableTreeNode<T>.nodeCount(): Int {
+    var count = 0
+    val stack = ArrayDeque<ImmutableTreeNode<T>>()
+    stack.addAll(children)
+    while (stack.isNotEmpty()) {
+        val node = stack.removeLast()
+        count++
+        stack.addAll(node.children)
+    }
+    return count
+}
+
+/**
+ * Returns the number of edges on the longest path between this node and a descendant leaf (0 for a
+ * leaf). Implemented iteratively, so it is safe on arbitrarily deep trees.
+ *
+ * @return the height of this subtree, measured in edges.
+ */
+public fun <T> ImmutableTreeNode<T>.height(): Int {
+    var maxDepth = 0
+    val stack = ArrayDeque<Pair<ImmutableTreeNode<T>, Int>>()
+    stack.addLast(this to 0)
+    while (stack.isNotEmpty()) {
+        val (node, depthSoFar) = stack.removeLast()
+        if (depthSoFar > maxDepth) maxDepth = depthSoFar
+        node.children.forEach { stack.addLast(it to depthSoFar + 1) }
+    }
+    return maxDepth
+}

tree-structure-immutable/src/commonTest/kotlin/com.github.adriankuta/datastructure/tree/immutable/ImmutableTreeNodeTest.kt

@@ -0,0 +1,135 @@
+package com.github.adriankuta.datastructure.tree.immutable
+
+import kotlinx.collections.immutable.persistentListOf
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertSame
+import kotlin.test.assertTrue
+
+class ImmutableTreeNodeTest {
+
+    // World
+    // ├── North America
+    // │   └── USA
+    // └── Europe
+    //     ├── Poland
+    //     └── Germany
+    private val usa = ImmutableTreeNode("USA")
+    private val northAmerica = ImmutableTreeNode("North America", persistentListOf(usa))
+    private val poland = ImmutableTreeNode("Poland")
+    private val germany = ImmutableTreeNode("Germany")
+    private val europe = ImmutableTreeNode("Europe", persistentListOf(poland, germany))
+    private val world = ImmutableTreeNode("World", persistentListOf(northAmerica, europe))
+
+    @Test
+    fun addChildReturnsNewInstanceAndLeavesOriginalUnchanged() {
+        val asia = ImmutableTreeNode("Asia")
+        val updated = world.addChild(asia)
+
+        assertEquals(3, updated.children.size)
+        assertEquals("Asia", updated.children[2].value)
+
+        // Original is untouched.
+        assertEquals(2, world.children.size)
+        assertFalse(updated === world)
+    }
+
+    @Test
+    fun removeChildReturnsNewInstanceAndLeavesOriginalUnchanged() {
+        val updated = world.removeChild(europe)
+
+        assertEquals(1, updated.children.size)
+        assertEquals("North America", updated.children[0].value)
+
+        // Original is untouched.
+        assertEquals(2, world.children.size)
+        assertFalse(updated === world)
+    }
+
+    @Test
+    fun addChildSharesUnmodifiedSiblingSubtrees() {
+        val asia = ImmutableTreeNode("Asia")
+        val updated = world.addChild(asia)
+
+        // The siblings that are not on the modified path are the SAME instances.
+        assertSame(northAmerica, updated.children[0])
+        assertSame(europe, updated.children[1])
+    }
+
+    @Test
+    fun rebuildingOnlyOnePathSharesTheOtherSubtree() {
+        // Add a child under Europe; North America's subtree should be reused untouched.
+        val spain = ImmutableTreeNode("Spain")
+        val newEurope = europe.addChild(spain)
+        val updated = world.copy(children = world.children.set(1, newEurope))
+
+        assertSame(northAmerica, updated.children[0])
+        assertFalse(updated.children[1] === europe)
+        assertSame(usa, updated.children[0].children[0])
+    }
+
+    @Test
+    fun mapValuesTransformsEveryValueAndKeepsShape() {
+        val lengths = world.mapValues { it.length }
+
+        assertEquals("World".length, lengths.value)
+        assertEquals(2, lengths.children.size)
+        assertEquals("North America".length, lengths.children[0].value)
+        assertEquals("USA".length, lengths.children[0].children[0].value)
+        assertEquals("Germany".length, lengths.children[1].children[1].value)
+    }
+
+    @Test
+    fun preOrderVisitsParentBeforeChildren() {
+        assertEquals(
+            listOf("World", "North America", "USA", "Europe", "Poland", "Germany"),
+            world.preOrder().map { it.value },
+        )
+    }
+
+    @Test
+    fun postOrderVisitsChildrenBeforeParent() {
+        assertEquals(
+            listOf("USA", "North America", "Poland", "Germany", "Europe", "World"),
+            world.postOrder().map { it.value },
+        )
+    }
+
+    @Test
+    fun levelOrderVisitsBreadthFirst() {
+        assertEquals(
+            listOf("World", "North America", "Europe", "USA", "Poland", "Germany"),
+            world.levelOrder().map { it.value },
+        )
+    }
+
+    @Test
+    fun nodeCountExcludesReceiver() {
+        assertEquals(5, world.nodeCount())
+        assertEquals(1, northAmerica.nodeCount())
+        assertEquals(0, usa.nodeCount())
+    }
+
+    @Test
+    fun heightCountsEdgesOnLongestPath() {
+        assertEquals(2, world.height())
+        assertEquals(1, europe.height())
+        assertEquals(0, usa.height())
+    }
+
+    @Test
+    fun equalityIsValueBased() {
+        val sameWorld = ImmutableTreeNode(
+            "World",
+            persistentListOf(
+                ImmutableTreeNode("North America", persistentListOf(ImmutableTreeNode("USA"))),
+                ImmutableTreeNode("Europe", persistentListOf(ImmutableTreeNode("Poland"), ImmutableTreeNode("Germany"))),
+            ),
+        )
+
+        assertEquals(world, sameWorld)
+        assertTrue(world == sameWorld)
+        assertFalse(world === sameWorld)
+    }
+}

tree-structure-serialization/build.gradle.kts

@@ -47,6 +47,19 @@ repositories {
     mavenCentral()
 }
 
+dokka {
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            // Resolve this module's GitHub source path relative to the repo root.
+            localDirectory.set(projectDir.resolve("src"))
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
+}
+
 kotlin {
     explicitApi()
     jvmToolchain(21)