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.
fix: raise Gradle daemon heap/Metaspace for the Android (AGP) build
2026-06-19 19:00:14 +02:00 · 2026-06-08 21:58:23 +02:00 · 2026-06-08 21:58:23 +02:00 · 2026-06-08 19:43:05 +00:00 · 2026-06-08 13:59:16 +02:00 · 2026-06-08 13:29:30 +02:00
36 changed files with 2373 additions and 26 deletions
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -26,6 +26,8 @@ jobs:
        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
--- a/.github/workflows/publishRelease.yml
+++ b/.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
--- a/.github/workflows/test.yml
+++ b/.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
--- a/.gitignore
+++ b/.gitignore
@@ -19,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/
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,43 @@ 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
@@ -76,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
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ usually a better fit.

 ## Features

- Kotlin Multiplatform: JVM, JS, Wasm, iOS, and a native host target.
+- 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`.
@@ -30,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") // latest version is on the badge above
+    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"
+    implementation "com.github.adriankuta:tree-structure:4.2.0"
 }
 ```

@@ -46,7 +46,7 @@ Maven:
 <dependency>
  <groupId>com.github.adriankuta</groupId>
  <artifactId>tree-structure</artifactId>
-  <version>4.0.0</version>
+  <version>4.2.0</version>
 </dependency>
 ```

@@ -160,7 +160,7 @@ that depends on the core.
 `@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(root.toDto())
@@ -172,7 +172,7 @@ val restored = Json.decodeFromString<TreeNodeDto<String>>(json).toTreeNode()
 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) }
@@ -181,12 +181,23 @@ root.asFlow(TreeNodeIterators.LevelOrder).map { it.value }

 ### 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:
+A `LazyTree` composable for Compose Multiplatform (JVM/desktop, Android, iOS, Wasm). Only the visible
+nodes are composed.

 ```kotlin
-implementation("com.github.adriankuta:tree-structure-compose:4.0.0")
+implementation("com.github.adriankuta:tree-structure-compose:4.2.0")
 ```
+
+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
+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)) {
@@ -196,6 +207,34 @@ LazyTree(root) { node, depth, expanded, toggle ->
 }
 ```

+A runnable Android demo lives in the [`samples-android`](samples-android) module.
+
+### Immutable (`tree-structure-immutable`)
+
+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`.
+
+```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
+
+bigger.preOrder().forEach { println(it.value) } // pre/post/level-order, nodeCount(), height()
+```
+
+## 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
--- a/api/android/tree-structure.api
+++ b/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;
--- a/api/jvm/tree-structure.api
+++ b/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;
+}
+
--- a/build.gradle.kts
+++ b/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,13 @@ 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 {
@@ -66,6 +78,7 @@ dependencies {
    dokka(project(":tree-structure-serialization"))
    dokka(project(":tree-structure-coroutines"))
    dokka(project(":tree-structure-compose"))
+    dokka(project(":tree-structure-immutable"))
 }

 dokka {
@@ -88,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()
@@ -120,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
+    }
+}
--- a/gradle.properties
+++ b/gradle.properties
@@ -2,3 +2,9 @@ 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
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -1,16 +1,24 @@
 [versions]
 kotlin = "2.1.0"
+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" }
--- a/gradle/wrapper/gradle-wrapper.properties
+++ b/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
--- a/samples-android/build.gradle.kts
+++ b/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)
+}
--- a/samples-android/src/main/AndroidManifest.xml
+++ b/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>
--- a/samples-android/src/main/kotlin/com/github/adriankuta/treestructure/sample/MainActivity.kt
+++ b/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 = {},
+        )
+    }
+}
--- a/samples/build.gradle.kts
+++ b/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()
+}
--- a/samples/src/main/kotlin/com/github/adriankuta/samples/Samples.kt
+++ b/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())
+}
--- a/samples/src/test/kotlin/com/github/adriankuta/samples/SamplesTest.kt
+++ b/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")
+    }
+}
--- a/settings.gradle.kts
+++ b/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")
--- a/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/TreeNode.kt
+++ b/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.
--- a/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/TreeNodePrettyPrintExt.kt
+++ b/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,
+            )
+        }
+    }
+}
--- a/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/TreeNodeQueryExt.kt
+++ b/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 }
--- a/src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodeMutationTest.kt
+++ b/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)
+    }
+}
--- a/src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodePrettyPrintTest.kt
+++ b/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" },
+        )
+    }
+}
--- a/src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodePropertyTest.kt
+++ b/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")
+}
--- a/src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodeQueryTest.kt
+++ b/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))
+    }
+}
--- a/tree-structure-compose/api/android/tree-structure-compose.api
+++ b/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
+}
+
--- a/tree-structure-compose/api/jvm/tree-structure-compose.api
+++ b/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
+}
+
--- a/tree-structure-compose/api/tree-structure-compose.api
+++ b/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
-}
-
--- a/tree-structure-compose/build.gradle.kts
+++ b/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)
@@ -68,6 +69,14 @@ kotlin {

    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()
@@ -85,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
+    }
+}
--- a/tree-structure-compose/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/compose/LazyTree.kt
+++ b/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.
--- a/tree-structure-compose/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/compose/TreeNodeRow.kt
+++ b/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))
+    }
+}
--- a/tree-structure-immutable/api/tree-structure-immutable.api
+++ b/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;
+}
+
--- a/tree-structure-immutable/build.gradle.kts
+++ b/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"))
+        }
+    }
+}
--- a/tree-structure-immutable/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/immutable/ImmutableTreeNode.kt
+++ b/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
+}
--- a/tree-structure-immutable/src/commonTest/kotlin/com.github.adriankuta/datastructure/tree/immutable/ImmutableTreeNodeTest.kt
+++ b/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)
+    }
+}
Author	SHA1	Message	Date
Adrian Kuta	0fe6535258	Release 4.2.0 Some checks failed Test / JVM / JS / Wasm / Native / Android + API check (push) Has been cancelled Details Test / iOS (push) Has been cancelled Details - 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.	2026-06-08 21:58:23 +02:00
Adrian Kuta	28c1690f96	fix: raise Gradle daemon heap/Metaspace for the Android (AGP) build The Android target added in #48 brought AGP onto the build's classpath without setting org.gradle.jvmargs, so the Gradle daemon ran on its defaults (512m heap / 384m Metaspace). AGP loads enough classes that, combined with the KMP matrix, binary-compatibility-validator, Kover and Dokka in a single build, the daemon exhausts Metaspace and is killed mid-build (GC thrashing / out of Metaspace). The 'JVM / JS / Wasm / Native / Android + API check' job therefore failed deterministically on master, and the publish job builds the same targets. Set org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g. Verified with a cold full-matrix build locally.	2026-06-08 21:58:23 +02:00
Adrian Kuta	dc59476b10	feat: add Android target and default TreeNodeRow to tree-structure-compose (#39 ) (#48 ) Add the `android` target to the Compose Multiplatform library and a sensible default renderer, so the largest Compose audience is a first-class consumer. - Core `tree-structure` and `tree-structure-compose` now build and publish an `-android` variant (compileSdk 35, minSdk 21). The core needs it too: its inline `tree { }` DSL is built per target, and Android consumers (JVM 11/17) cannot inline a JVM-21 build. - `TreeNodeRow`: a foundation-only default node row (clickable, indented, with a `▾`/`▸` marker, no Material dependency), plus a no-content `LazyTree(root, label = …)` overload that uses it. The existing lambda overload is unchanged. - New `samples` Android app module demonstrating `LazyTree` + `@Preview` (not published; excluded from API validation). - Toolchain: Gradle wrapper 8.5 -> 8.10.2, Android Gradle Plugin 8.7.2. - binary-compatibility-validator now emits per-target dumps (api/jvm, api/android) for the two multi-JVM-target modules; CI assembles the Android outputs.	2026-06-08 19:43:05 +00:00
Adrian Kuta	1fce412815	feat: add runnable :samples module (#47 ) Some checks failed Test / JVM / JS / Wasm / Native + API check (push) Has been cancelled Details Test / iOS (push) Has been cancelled Details * build: scaffold :samples module (issue #37) * feat: add runnable, verified examples to :samples (issue #37) * ci,docs: run :samples in CI and document ./gradlew :samples:run (issue #37)	2026-06-08 13:59:16 +02:00
Adrian Kuta	2671c46f96	test: property-based tests for traversal & structural invariants (#38 ) (#46 ) Add TreeNodePropertyTest: 23 properties checked over many seeded, randomly generated trees instead of fixed examples. Covers the invariants from #38 — all three orders visit the same node set with matching cardinality; pre/post emit each subtree as a contiguous block; level-order is depth-monotonic; child.depth == parent.depth + 1 (cross-checked against an independent BFS level walk); nodeCount stays consistent across attach/detach, remove/insert and clear; and every traversal terminates and is correctly ordered on deep (5k-node chain) and wide (5k-child) trees. Also pins parent/child pointer consistency, ancestor/leaf/sibling correctness, deepCopy/mapValues shape preservation, and lca/distance/pathBetween. The generator builds trees by uniform random attachment (iterative, so it is stack-safe and free of left-heavy skew). Failures print the seed, so any case reproduces. No new dependency — the suite is pure commonTest and runs on every target (JVM/JS/Wasm/Native).	2026-06-08 13:29:30 +02:00
Adrian Kuta	f1e9a7bb54	chore: gitignore local superpowers working docs (docs/superpowers/)	2026-06-08 08:55:04 +02:00
Adrian Kuta	a7d5de1bba	docs: remove design spec accidentally committed in v4.1.1 release	2026-06-08 08:53:12 +02:00
Adrian Kuta	160d7c8059	Release 4.1.1: publish on macOS to restore Apple/iOS artifacts	2026-06-08 08:37:35 +02:00
Adrian Kuta	f60a5c4a86	Release 4.1.0: structural mutations, query algorithms, customizable prettyString, immutable module Some checks failed Test / JVM / JS / Wasm / Native + API check (push) Has been cancelled Details Test / iOS (push) Has been cancelled Details	2026-06-07 23:31:15 +02:00
Adrian Kuta	0b8429c859	ci: cache Gradle, harden permissions, fix test triggers (#45 ) - Add gradle/actions/setup-gradle caching to all three workflows - test.yml: trigger on pull_request + push to master (was branches-ignore: master), so PRs from forks are covered and master is verified after merge; add least-privilege permissions and PR-only concurrency - publishRelease.yml: drop unused 'secrets: inherit' and the dead SNAPSHOT env var (Gradle reads the snapshot project property, not a plain env var); add contents: read permissions; fix the misleading Maven Central comment (upload only stages on Central Portal, the final Publish is manual) - docs.yml: add Gradle caching	2026-06-07 23:25:55 +02:00
Adrian Kuta	f47fb091ec	feat: add tree-structure-immutable module (persistent ImmutableTreeNode) (#33 ) (#44 )	2026-06-07 22:40:41 +02:00
Adrian Kuta	6758a68522	feat: add customizable prettyString with renderer and connector styles (#36 ) (#43 )	2026-06-07 22:38:30 +02:00
Adrian Kuta	30b2709803	feat: add tree query algorithms (lowestCommonAncestor/distance/pathBetween/contains) (#35 ) (#42 )	2026-06-07 22:36:48 +02:00
Adrian Kuta	06eae4841e	feat: add structural mutation helpers (insert/move/replace/sort children) (#34 ) (#41 )	2026-06-07 22:35:04 +02:00