Publish API reference (Dokka HTML) to GitHub Pages (#32) (#40)

* docs: design spec for Dokka HTML API reference on GitHub Pages (#32)

* docs: implementation plan for Dokka API reference on GitHub Pages (#32)

* build: migrate Dokka 1.9.20 -> 2.2.0 (DGP v2) (#32)

* docs: aggregate all modules into one Dokka HTML site with source links (#32)

* docs: add Dokka source links to serialization/coroutines/compose modules (#32)

* ci: add docs workflow to deploy Dokka HTML to GitHub Pages (#32)

* docs: link the published API reference from the README (#32)

.github/workflows/docs.yml

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

.gitignore

@@ -1,5 +1,6 @@
 *.iml
 .gradle
+/.kotlin/
 /local.properties
 /.idea/caches
 /.idea/libraries

CHANGELOG.md

@@ -6,6 +6,38 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+### Changed
+- Rewrote the README for clarity: one consistent example tree, task-oriented sections
+  (building, traversal, navigation, functional, utilities, mutating), per-module usage, and a
+  condensed maintainer "Releasing" section.
+
+## [4.0.0]
+
+A breaking release that cleans up the core API and enforces an explicit public surface.
+
+### Changed (breaking)
+- `TreeNode.treeIterator` is now a read-only `val` (set it via the constructor). Use
+  `iterator(order)` or `asSequence(order)` to traverse in a different order per call.
+- `removeChild(child)` now only removes a **direct** child of the receiver (previously it removed
+  the node from its actual parent regardless). Use `child.detach()` to unhook a node from wherever
+  it lives.
+- `addChild(child)` now throws `TreeNodeException` if `child` already has a parent or if the
+  attachment would create a cycle. Call `detach()` first to move a node.
+- `clear()` no longer detaches the receiver from its own parent; it only removes its descendants.
+- `path(descendant)` now returns `List<TreeNode<T>>?` (`null` when `descendant` is the root or not a
+  descendant) instead of throwing `TreeNodeException`.
+
+### Added
+- `TreeNode.detach()` — removes a node from its parent.
+- `TreeNode.iterator(order)` — a one-shot iterator in a specific order.
+- Strict `explicitApi()` mode across all modules.
+- New `tree-structure-compose` module: a `LazyTree` composable for Compose Multiplatform.
+
+### Migration
+- `node.treeIterator = PostOrder; for (n in node) { … }` → `for (n in node.asSequence(PostOrder)) { … }`
+- `root.removeChild(deepNode)` → `deepNode.detach()`
+- `try { node.path(x) } catch (e: TreeNodeException) { … }` → `node.path(x)?.let { … }`
+
 ## [3.4.0]
 
 ### Added
@@ -44,7 +76,8 @@ All notable changes to this project are documented here. The format is based on
 ## [3.1.3]
 - iOS targets and Maven Central (Sonatype Central Portal) publishing.
 
-[Unreleased]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v3.4.0...HEAD
+[Unreleased]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v4.0.0...HEAD
+[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
 [3.1.4]: https://github.com/AdrianKuta/Tree-Data-Structure/releases/tag/v3.1.4

README.md

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

api/tree-structure.api

@@ -13,6 +13,7 @@ public class com/github/adriankuta/datastructure/tree/TreeNode : com/github/adri
 	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;
@@ -20,11 +21,11 @@ public class com/github/adriankuta/datastructure/tree/TreeNode : com/github/adri
 	public final fun height ()I
 	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 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 setTreeIterator (Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;)V
 	public fun toString ()Ljava/lang/String;
 }
 

build.gradle.kts

@@ -11,7 +11,7 @@ plugins {
 
 val PUBLISH_GROUP_ID = "com.github.adriankuta"
 val PUBLISH_ARTIFACT_ID = "tree-structure"    // base artifact; KMP will add -jvm, -ios*, etc.
-val PUBLISH_VERSION = "3.4.0"
+val PUBLISH_VERSION = "4.0.0"
 
 val snapshot: String? by project
 
@@ -59,7 +59,31 @@ repositories {
     mavenCentral()
 }
 
+dependencies {
+    // Include this module's own docs in the aggregation — DGP v2 requires the
+    // aggregating project to list itself explicitly.
+    dokka(project(":"))
+    dokka(project(":tree-structure-serialization"))
+    dokka(project(":tree-structure-coroutines"))
+    dokka(project(":tree-structure-compose"))
+}
+
+dokka {
+    moduleName.set("Tree Data Structure")
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            localDirectory.set(projectDir.resolve("src"))
+            // For the root project projectDir == rootDir, so `module` is "" and links resolve to /blob/master/src.
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
+}
+
 kotlin {
+    explicitApi()
     jvmToolchain(21)
 
     jvm()

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

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

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

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

gradle.properties

@@ -1 +1,4 @@
 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

gradle/libs.versions.toml

@@ -1,11 +1,12 @@
 [versions]
 kotlin = "2.1.0"
-dokka = "1.9.20"
+dokka = "2.2.0"
 mavenPublish = "0.34.0"
 binaryCompatibilityValidator = "0.16.3"
 kover = "0.8.3"
 coroutines = "1.9.0"
 kotlinxSerialization = "1.7.3"
+composeMultiplatform = "1.7.3"
 
 [plugins]
 kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
@@ -14,6 +15,8 @@ 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" }
 kover = { id = "org.jetbrains.kotlinx.kover", version.ref = "kover" }
+composeMultiplatform = { id = "org.jetbrains.compose", version.ref = "composeMultiplatform" }
+composeCompiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
 
 [libraries]
 kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }

settings.gradle.kts

@@ -2,3 +2,4 @@ rootProject.name = "tree-structure"
 
 include(":tree-structure-serialization")
 include(":tree-structure-coroutines")
+include(":tree-structure-compose")

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

@@ -2,7 +2,7 @@ package com.github.adriankuta.datastructure.tree
 
 import kotlin.jvm.JvmSynthetic
 
-interface ChildDeclarationInterface<T> {
+public interface ChildDeclarationInterface<T> {
 
     /**
      * This method is used to easily create child in node.
@@ -20,5 +20,5 @@ interface ChildDeclarationInterface<T> {
      * @return New created TreeNode.
      */
     @JvmSynthetic
-    fun child(value: T, childDeclaration: ChildDeclaration<T>? = null): TreeNode<T>
+    public fun child(value: T, childDeclaration: ChildDeclaration<T>? = null): TreeNode<T>
 }

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

@@ -27,14 +27,14 @@ import kotlin.jvm.JvmSynthetic
  * @param treeIterator the default traversal order used by [iterator]. Prefer the
  *   `asSequence(order)` / `preOrderSequence()` extensions to choose an order without mutating state.
  */
-open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOrder) : Iterable<TreeNode<T>>, ChildDeclarationInterface<T> {
+public open class TreeNode<T>(public val value: T, public val treeIterator: TreeNodeIterators = PreOrder) : Iterable<TreeNode<T>>, ChildDeclarationInterface<T> {
 
     private var _parent: TreeNode<T>? = null
 
     /**
      * The converse notion of a child, an immediate ancestor.
      */
-    val parent: TreeNode<T>?
+    public val parent: TreeNode<T>?
         get() = _parent
 
     private val _children = mutableListOf<TreeNode<T>>()
@@ -42,28 +42,60 @@ open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOr
     /**
      * A group of nodes with the same parent.
      */
-    val children: List<TreeNode<T>>
+    public val children: List<TreeNode<T>>
         get() = _children
 
     /**
      * Checks whether the current tree node is the root of the tree
      * @return `true` if the current tree node is root of the tree, `false` otherwise.
      */
-    val isRoot: Boolean
+    public val isRoot: Boolean
         get() = _parent == null
 
     /**
-     * Add new child to current node or root.
+     * Adds [child] as a direct child of this node.
      *
-     * @param child A node which will be directly connected to current node.
+     * @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 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).
      */
-    fun addChild(child: TreeNode<T>) {
+    public fun addChild(child: TreeNode<T>) {
+        if (child._parent != null) {
+            throw TreeNodeException("$child already has a parent; call detach() before re-attaching it.")
+        }
+        if (child === this) {
+            throw TreeNodeException("Adding $child here would create a cycle.")
+        }
+        // Only a node that already has its own subtree can contain `this` and thus form a cycle.
+        // Skipping this walk for leaves keeps building deep trees O(n) instead of O(n²).
+        if (child._children.isNotEmpty()) {
+            var ancestor: TreeNode<T>? = _parent
+            while (ancestor != null) {
+                if (ancestor === child) {
+                    throw TreeNodeException("Adding $child here would create a cycle.")
+                }
+                ancestor = ancestor._parent
+            }
+        }
         child._parent = this
         _children.add(child)
     }
 
+    /**
+     * Detaches this node from its parent, removing it from the parent's [children].
+     *
+     * @return `true` if this node was attached and is now detached; `false` if it was already a root.
+     */
+    public fun detach(): Boolean {
+        val currentParent = _parent ?: return false
+        currentParent._children.remove(this)
+        _parent = null
+        return true
+    }
+
     @JvmSynthetic
-    override fun child(value: T, childDeclaration: ChildDeclaration<T>?): TreeNode<T> {
+    public override fun child(value: T, childDeclaration: ChildDeclaration<T>?): TreeNode<T> {
         val newChild = TreeNode(value)
         newChild._parent = this
         if (childDeclaration != null)
@@ -73,21 +105,24 @@ open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOr
     }
 
     /**
-     * Removes a single instance of the specified node from this tree, if it is present.
+     * Removes [child] from this node's direct [children], if present.
      *
-     * @return `true` if the node has been successfully removed; `false` if it was not present in the tree.
+     * This only removes a *direct* child of the receiver; it does not reach into other nodes. To
+     * remove a node from wherever it currently lives, call [detach] on it instead.
+     *
+     * @return `true` if [child] was a direct child and has been removed; `false` otherwise.
      */
-    fun removeChild(child: TreeNode<T>): Boolean {
-        val removed = child._parent?._children?.remove(child)
-        child._parent = null
-        return removed ?: false
+    public fun removeChild(child: TreeNode<T>): Boolean {
+        val removed = _children.remove(child)
+        if (removed) child._parent = null
+        return removed
     }
 
     /**
      * This function go through tree and counts children. Root element is not counted.
      * @return All child and nested child count.
      */
-    fun nodeCount(): Int {
+    public fun nodeCount(): Int {
         var count = 0
         val stack = ArrayDeque<TreeNode<T>>()
         stack.addAll(_children)
@@ -102,7 +137,7 @@ open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOr
     /**
      * @return The number of edges on the longest path between current node and a descendant leaf.
      */
-    fun height(): Int {
+    public fun height(): Int {
         var maxDepth = 0
         val stack = ArrayDeque<Pair<TreeNode<T>, Int>>()
         stack.addLast(this to 0)
@@ -118,7 +153,7 @@ open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOr
      * Distance is the number of edges along the shortest path between two nodes.
      * @return The distance between current node and the root.
      */
-    fun depth(): Int {
+    public fun depth(): Int {
         var depth = 0
         var tempParent = parent
 
@@ -130,53 +165,52 @@ open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOr
     }
 
     /**
-     * Returns the collection of nodes, which connect the current node
-     * with its descendants
+     * Returns the chain of nodes from [descendant] up to and including this node, or `null` if
+     * [descendant] is not a strict descendant of this node.
      *
-     * @param descendant the bottom child node for which the path is calculated
-     * @return collection of nodes, which connect the current node with its descendants
-     * @throws TreeNodeException exception that may be thrown in case if the
-     *                           current node does not have such descendant or if the
-     *                           specified tree node is root
+     * @param descendant the node to walk up from.
+     * @return the path `[descendant, …, this]`, or `null` if [descendant] is the root or is not
+     *   located in this node's subtree.
      */
-    @Throws(TreeNodeException::class)
-    fun path(descendant: TreeNode<T>): List<TreeNode<T>> {
-
+    public fun path(descendant: TreeNode<T>): List<TreeNode<T>>? {
+        if (descendant.isRoot) return null
         val path = mutableListOf<TreeNode<T>>()
         var node = descendant
         path.add(node)
         while (!node.isRoot) {
             node = node.parent!!
             path.add(node)
-            if (node == this)
-                return path
+            if (node == this) return path
         }
-        throw TreeNodeException("The specified tree node $descendant is not the descendant of tree node $this")
+        return null
     }
 
     /**
-     * Remove all children from root and every node in tree.
+     * Removes every descendant of this node. Afterwards [children] is empty and all former
+     * descendants are detached (their parent is `null`). This node itself stays attached to its own
+     * parent.
      */
-    fun clear() {
-        val all = ArrayDeque<TreeNode<T>>()
+    public fun clear() {
+        val descendants = ArrayDeque<TreeNode<T>>()
         val stack = ArrayDeque<TreeNode<T>>()
-        stack.addLast(this)
+        stack.addAll(_children)
         while (stack.isNotEmpty()) {
             val node = stack.removeLast()
-            all.addLast(node)
+            descendants.addLast(node)
             stack.addAll(node._children)
         }
-        all.forEach { node ->
+        descendants.forEach { node ->
             node._parent = null
             node._children.clear()
         }
+        _children.clear()
     }
 
-    override fun toString(): String {
+    public override fun toString(): String {
         return value.toString()
     }
 
-    fun prettyString(): String {
+    public fun prettyString(): String {
         val stringBuilder = StringBuilder()
         print(stringBuilder, "", "")
         return stringBuilder.toString()
@@ -198,9 +232,14 @@ open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOr
     }
 
     /**
-     * You can change default iterator by changing [treeIterator] property.
+     * Returns an iterator over this node and its descendants using the default [treeIterator] order.
+     * Use [iterator] with an explicit order, or the `asSequence(order)` extension, to traverse in a
+     * different order without changing this node's default.
      */
-    override fun iterator(): Iterator<TreeNode<T>> = when (treeIterator) {
+    public override fun iterator(): Iterator<TreeNode<T>> = iterator(treeIterator)
+
+    /** Returns an iterator over this node and its descendants in the given [order]. */
+    public fun iterator(order: TreeNodeIterators): Iterator<TreeNode<T>> = when (order) {
         PreOrder -> PreOrderTreeIterator(this)
         PostOrder -> PostOrderTreeIterator(this)
         LevelOrder -> LevelOrderTreeIterator(this)

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

@@ -3,7 +3,7 @@ package com.github.adriankuta.datastructure.tree
 import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
 import kotlin.jvm.JvmSynthetic
 
-typealias ChildDeclaration<T> = ChildDeclarationInterface<T>.() -> Unit
+public typealias ChildDeclaration<T> = ChildDeclarationInterface<T>.() -> Unit
 
 /**
  * This method can be used to initialize new tree.
@@ -14,7 +14,7 @@ typealias ChildDeclaration<T> = ChildDeclarationInterface<T>.() -> Unit
  * @see [ChildDeclarationInterface.child]
  */
 @JvmSynthetic
-inline fun <reified T> tree(
+public inline fun <reified T> tree(
     root: T,
     defaultIterator: TreeNodeIterators = TreeNodeIterators.PreOrder,
     childDeclaration: ChildDeclaration<T>

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

@@ -1,34 +1,34 @@
 package com.github.adriankuta.datastructure.tree
 
 /** Returns the first node (pre-order) whose value matches [predicate], or `null`. Short-circuits. */
-fun <T> TreeNode<T>.findNode(predicate: (T) -> Boolean): TreeNode<T>? =
+public fun <T> TreeNode<T>.findNode(predicate: (T) -> Boolean): TreeNode<T>? =
     preOrderSequence().firstOrNull { predicate(it.value) }
 
 /** All nodes (pre-order) whose value matches [predicate]. */
-fun <T> TreeNode<T>.filterNodes(predicate: (T) -> Boolean): List<TreeNode<T>> =
+public fun <T> TreeNode<T>.filterNodes(predicate: (T) -> Boolean): List<TreeNode<T>> =
     preOrderSequence().filter { predicate(it.value) }.toList()
 
 /** `true` if any node's value matches [predicate]. Short-circuits. */
-fun <T> TreeNode<T>.anyNode(predicate: (T) -> Boolean): Boolean =
+public fun <T> TreeNode<T>.anyNode(predicate: (T) -> Boolean): Boolean =
     preOrderSequence().any { predicate(it.value) }
 
 /** `true` if every node's value matches [predicate]. Short-circuits. */
-fun <T> TreeNode<T>.allNodes(predicate: (T) -> Boolean): Boolean =
+public fun <T> TreeNode<T>.allNodes(predicate: (T) -> Boolean): Boolean =
     preOrderSequence().all { predicate(it.value) }
 
 /** Counts nodes whose value matches [predicate]. */
-fun <T> TreeNode<T>.countNodes(predicate: (T) -> Boolean): Int =
+public fun <T> TreeNode<T>.countNodes(predicate: (T) -> Boolean): Int =
     preOrderSequence().count { predicate(it.value) }
 
 /** Folds [operation] over all nodes in pre-order, starting from [initial]. */
-fun <T, R> TreeNode<T>.foldNodes(initial: R, operation: (acc: R, node: TreeNode<T>) -> R): R =
+public fun <T, R> TreeNode<T>.foldNodes(initial: R, operation: (acc: R, node: TreeNode<T>) -> R): R =
     preOrderSequence().fold(initial) { acc, node -> operation(acc, node) }
 
 /**
  * Returns a new tree with the same shape whose values are produced by [transform]. The original is
  * left untouched. Stack-safe (iterative), so it handles arbitrarily deep trees.
  */
-fun <T, R> TreeNode<T>.mapValues(transform: (T) -> R): TreeNode<R> {
+public fun <T, R> TreeNode<T>.mapValues(transform: (T) -> R): TreeNode<R> {
     val newRoot = TreeNode(transform(value), treeIterator)
     val stack = ArrayDeque<Pair<TreeNode<T>, TreeNode<R>>>()
     stack.addLast(this to newRoot)
@@ -44,13 +44,13 @@ fun <T, R> TreeNode<T>.mapValues(transform: (T) -> R): TreeNode<R> {
 }
 
 /** Returns an independent deep copy of this subtree (same values, same shape, new nodes). */
-fun <T> TreeNode<T>.deepCopy(): TreeNode<T> = mapValues { it }
+public fun <T> TreeNode<T>.deepCopy(): TreeNode<T> = mapValues { it }
 
 /**
  * Structural equality: `true` when [other] holds the same values in the same shape. Unlike
  * [TreeNode]'s reference equality, this compares the entire subtree. Stack-safe.
  */
-fun <T> TreeNode<T>.structurallyEquals(other: TreeNode<T>): Boolean {
+public fun <T> TreeNode<T>.structurallyEquals(other: TreeNode<T>): Boolean {
     val stack = ArrayDeque<Pair<TreeNode<T>, TreeNode<T>>>()
     stack.addLast(this to other)
     while (stack.isNotEmpty()) {

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

@@ -1,13 +1,13 @@
 package com.github.adriankuta.datastructure.tree
 
 /** `true` when this node has no children. */
-val <T> TreeNode<T>.isLeaf: Boolean get() = children.isEmpty()
+public val <T> TreeNode<T>.isLeaf: Boolean get() = children.isEmpty()
 
 /** The number of direct children of this node. */
-val <T> TreeNode<T>.degree: Int get() = children.size
+public val <T> TreeNode<T>.degree: Int get() = children.size
 
 /** Walks up the parent chain and returns the topmost ancestor (the tree root). */
-fun <T> TreeNode<T>.root(): TreeNode<T> {
+public fun <T> TreeNode<T>.root(): TreeNode<T> {
     var node = this
     var parent = node.parent
     while (parent != null) {
@@ -18,7 +18,7 @@ fun <T> TreeNode<T>.root(): TreeNode<T> {
 }
 
 /** The chain of ancestors from the immediate [parent] up to (and including) the root. */
-fun <T> TreeNode<T>.ancestors(): List<TreeNode<T>> {
+public fun <T> TreeNode<T>.ancestors(): List<TreeNode<T>> {
     val result = mutableListOf<TreeNode<T>>()
     var parent = this.parent
     while (parent != null) {
@@ -29,13 +29,13 @@ fun <T> TreeNode<T>.ancestors(): List<TreeNode<T>> {
 }
 
 /** The other children of this node's parent (excludes this node). Empty for the root. */
-fun <T> TreeNode<T>.siblings(): List<TreeNode<T>> =
+public fun <T> TreeNode<T>.siblings(): List<TreeNode<T>> =
     parent?.children?.filter { it !== this } ?: emptyList()
 
 /** All leaf nodes in this subtree, in pre-order. */
-fun <T> TreeNode<T>.leaves(): List<TreeNode<T>> =
+public fun <T> TreeNode<T>.leaves(): List<TreeNode<T>> =
     preOrderSequence().filter { it.isLeaf }.toList()
 
 /** All nodes in this subtree except this node, in pre-order. */
-fun <T> TreeNode<T>.descendants(): List<TreeNode<T>> =
+public fun <T> TreeNode<T>.descendants(): List<TreeNode<T>> =
     preOrderSequence().filter { it !== this }.toList()

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

@@ -10,7 +10,7 @@ import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
  * traversal up front. Pairs with the Kotlin stdlib, e.g.
  * `root.asSequence().map { it.value }.firstOrNull { it == target }`.
  */
-fun <T> TreeNode<T>.asSequence(
+public fun <T> TreeNode<T>.asSequence(
     order: TreeNodeIterators = TreeNodeIterators.PreOrder,
 ): Sequence<TreeNode<T>> {
     val self = this
@@ -22,10 +22,10 @@ fun <T> TreeNode<T>.asSequence(
 }
 
 /** Lazy pre-order traversal as a [Sequence]. */
-fun <T> TreeNode<T>.preOrderSequence(): Sequence<TreeNode<T>> = asSequence(TreeNodeIterators.PreOrder)
+public fun <T> TreeNode<T>.preOrderSequence(): Sequence<TreeNode<T>> = asSequence(TreeNodeIterators.PreOrder)
 
 /** Lazy post-order traversal as a [Sequence]. */
-fun <T> TreeNode<T>.postOrderSequence(): Sequence<TreeNode<T>> = asSequence(TreeNodeIterators.PostOrder)
+public fun <T> TreeNode<T>.postOrderSequence(): Sequence<TreeNode<T>> = asSequence(TreeNodeIterators.PostOrder)
 
 /** Lazy level-order (breadth-first) traversal as a [Sequence]. */
-fun <T> TreeNode<T>.levelOrderSequence(): Sequence<TreeNode<T>> = asSequence(TreeNodeIterators.LevelOrder)
+public fun <T> TreeNode<T>.levelOrderSequence(): Sequence<TreeNode<T>> = asSequence(TreeNodeIterators.LevelOrder)

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/exceptions/TreeNodeException.kt

@@ -2,5 +2,5 @@ package com.github.adriankuta.datastructure.tree.exceptions
 
 import kotlin.jvm.JvmOverloads
 
-class TreeNodeException @JvmOverloads constructor(message: String? = null, cause: Throwable? = null) :
+public class TreeNodeException @JvmOverloads constructor(message: String? = null, cause: Throwable? = null) :
     RuntimeException(message, cause)

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/iterators/LevelOrderTreeIterator.kt

@@ -20,7 +20,7 @@ import com.github.adriankuta.datastructure.tree.TreeNode
  * Output: 1 2 3 4 5 6 7 8 9 10 11 12 13
  * ```
  */
-class LevelOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
+public class LevelOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
 
     private val stack = ArrayDeque<TreeNode<T>>()
 
@@ -28,9 +28,9 @@ class LevelOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
         stack.addLast(root)
     }
 
-    override fun hasNext(): Boolean = stack.isNotEmpty()
+    public override fun hasNext(): Boolean = stack.isNotEmpty()
 
-    override fun next(): TreeNode<T> {
+    public override fun next(): TreeNode<T> {
         val node =  stack.removeFirst()
         node.children
             .forEach { stack.addLast(it) }

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/iterators/PostOrderTreeIterator.kt

@@ -20,7 +20,7 @@ import com.github.adriankuta.datastructure.tree.TreeNode
  * Output: 10 5 11 12 13 6 2 3 7 8 9 4 1
  * ```
  */
-class PostOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
+public class PostOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
 
     private val result = ArrayDeque<TreeNode<T>>()
 
@@ -37,7 +37,7 @@ class PostOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
         }
     }
 
-    override fun hasNext(): Boolean = result.isNotEmpty()
+    public override fun hasNext(): Boolean = result.isNotEmpty()
 
-    override fun next(): TreeNode<T> = result.removeFirst()
+    public override fun next(): TreeNode<T> = result.removeFirst()
 }

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/iterators/PreOrderTreeIterator.kt

@@ -20,7 +20,7 @@ import com.github.adriankuta.datastructure.tree.TreeNode
  * Output: 1 2 5 10 6 11 12 13 3 4 7 8 9
  * ```
  */
-class PreOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
+public class PreOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
 
     private val stack = ArrayDeque<TreeNode<T>>()
 
@@ -28,9 +28,9 @@ class PreOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
         stack.addLast(root)
     }
 
-    override fun hasNext(): Boolean = stack.isNotEmpty()
+    public override fun hasNext(): Boolean = stack.isNotEmpty()
 
-    override fun next(): TreeNode<T> {
+    public override fun next(): TreeNode<T> {
         val node = stack.removeLast()
         node.children
             .asReversed()

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/iterators/TreeNodeIterators.kt

@@ -5,7 +5,7 @@ package com.github.adriankuta.datastructure.tree.iterators
  * @see PostOrder
  * @see LevelOrder
  */
-enum class TreeNodeIterators {
+public enum class TreeNodeIterators {
     /**
      * Tree is iterated by using `Pre-order Traversal Algorithm"
      * The pre-order traversal is a topologically sorted one,

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

@@ -37,13 +37,11 @@ class TreeNodeStackSafetyTest {
 
     @Test
     fun postOrderIterationDoesNotOverflowOnDeepTree() {
-        val tree = deepChain().apply { treeIterator = TreeNodeIterators.PostOrder }
-        assertEquals(depth + 1, tree.toList().size)
+        assertEquals(depth + 1, deepChain().asSequence(TreeNodeIterators.PostOrder).count())
     }
 
     @Test
     fun preOrderIterationDoesNotOverflowOnDeepTree() {
-        val tree = deepChain().apply { treeIterator = TreeNodeIterators.PreOrder }
-        assertEquals(depth + 1, tree.toList().size)
+        assertEquals(depth + 1, deepChain().asSequence(TreeNodeIterators.PreOrder).count())
     }
 }

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

@@ -51,7 +51,7 @@ class TreeNodeTest {
         )
 
         root.removeChild(curdNode)
-        root.removeChild(gingerTeaNode)
+        gingerTeaNode.detach()
         assertEquals(
             "Root\n" +
                     "└── Beverages\n" +

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

@@ -1,10 +1,9 @@
 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.assertEquals
-import kotlin.test.assertFailsWith
+import kotlin.test.assertNull
 
 class TreeNodeUtilitiesTest {
 
@@ -43,12 +42,12 @@ class TreeNodeUtilitiesTest {
     }
 
     @Test
-    fun pathThrowsWhenNotADescendant() {
-        assertFailsWith<TreeNodeException> { root.path(TreeNode(99)) }
+    fun pathReturnsNullWhenNotADescendant() {
+        assertNull(root.path(TreeNode(99)))
     }
 
     @Test
-    fun pathThrowsWhenDescendantIsRootItself() {
-        assertFailsWith<TreeNodeException> { root.path(root) }
+    fun pathReturnsNullWhenDescendantIsRootItself() {
+        assertNull(root.path(root))
     }
 }

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

@@ -0,0 +1,105 @@
+package com.github.adriankuta.datastructure.tree
+
+import com.github.adriankuta.datastructure.tree.exceptions.TreeNodeException
+import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
+import kotlin.test.Test
+import kotlin.test.assertContentEquals
+import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+import kotlin.test.assertFalse
+import kotlin.test.assertNull
+import kotlin.test.assertSame
+import kotlin.test.assertTrue
+
+class TreeNodeV4Test {
+
+    @Test
+    fun addChildRejectsNodeThatAlreadyHasAParent() {
+        val a = TreeNode("a")
+        val b = TreeNode("b")
+        a.addChild(b)
+
+        val other = TreeNode("other")
+        assertFailsWith<TreeNodeException> { other.addChild(b) }
+    }
+
+    @Test
+    fun addChildRejectsCycles() {
+        val root = TreeNode("root")
+        val child = TreeNode("child")
+        root.addChild(child)
+
+        // Attaching an ancestor under its own descendant would create a cycle.
+        assertFailsWith<TreeNodeException> { child.addChild(root) }
+        // Attaching a node under itself is also a cycle.
+        assertFailsWith<TreeNodeException> { root.addChild(root) }
+    }
+
+    @Test
+    fun detachRemovesFromParent() {
+        val root = TreeNode("root")
+        val child = TreeNode("child")
+        root.addChild(child)
+
+        assertTrue(child.detach())
+        assertNull(child.parent)
+        assertContentEquals(emptyList(), root.children)
+        // Detached node can now be re-attached elsewhere.
+        val newParent = TreeNode("newParent")
+        newParent.addChild(child)
+        assertSame(newParent, child.parent)
+    }
+
+    @Test
+    fun detachOnRootReturnsFalse() {
+        assertFalse(TreeNode("root").detach())
+    }
+
+    @Test
+    fun removeChildOnlyRemovesDirectChildren() {
+        val root = TreeNode("root")
+        val parent = TreeNode("parent")
+        val grandchild = TreeNode("grandchild")
+        root.addChild(parent)
+        parent.addChild(grandchild)
+
+        // grandchild is not a direct child of root -> no-op, returns false.
+        assertFalse(root.removeChild(grandchild))
+        assertSame(parent, grandchild.parent)
+
+        // direct child removal works.
+        assertTrue(parent.removeChild(grandchild))
+        assertNull(grandchild.parent)
+    }
+
+    @Test
+    fun clearOnNonRootKeepsItAttachedToItsParent() {
+        val root = TreeNode("root")
+        val branch = TreeNode("branch")
+        val leaf = TreeNode("leaf")
+        root.addChild(branch)
+        branch.addChild(leaf)
+
+        branch.clear()
+
+        assertContentEquals(emptyList(), branch.children)
+        assertSame(root, branch.parent)          // branch stays attached to root
+        assertContentEquals(listOf(branch), root.children)
+        assertNull(leaf.parent)                  // former descendant is detached
+    }
+
+    @Test
+    fun iteratorAcceptsExplicitOrderWithoutMutatingDefault() {
+        val tree = tree(1) {
+            child(2) { child(4) }
+            child(3)
+        }
+
+        val postOrder = tree.iterator(TreeNodeIterators.PostOrder).asSequence().map { it.value }.toList()
+        assertContentEquals(listOf(4, 2, 3, 1), postOrder)
+
+        // Default order is unchanged (PreOrder).
+        assertEquals(TreeNodeIterators.PreOrder, tree.treeIterator)
+        assertContentEquals(listOf(1, 2, 4, 3), tree.map { it.value })
+    }
+}

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

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

tree-structure-compose/build.gradle.kts

@@ -0,0 +1,87 @@
+import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
+
+plugins {
+    alias(libs.plugins.kotlinMultiplatform)
+    alias(libs.plugins.composeMultiplatform)
+    alias(libs.plugins.composeCompiler)
+    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-compose", version.toString())
+
+    pom {
+        name.set("Tree Data Structure — Compose Multiplatform")
+        description.set("A LazyTree composable (expand/collapse, lazy rendering) 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()
+    google()
+}
+
+dokka {
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            // Resolve this module's GitHub source path relative to the repo root.
+            localDirectory.set(projectDir.resolve("src"))
+            val module = projectDir.relativeTo(rootDir).invariantSeparatorsPath
+            val prefix = if (module.isEmpty()) "" else "$module/"
+            remoteUrl("https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/${prefix}src")
+            remoteLineSuffix.set("#L")
+        }
+    }
+}
+
+kotlin {
+    explicitApi()
+    jvmToolchain(21)
+
+    jvm()
+
+    @OptIn(ExperimentalWasmDsl::class)
+    wasmJs {
+        browser()
+    }
+
+    iosX64()
+    iosArm64()
+    iosSimulatorArm64()
+
+    sourceSets {
+        commonMain.dependencies {
+            api(project(":"))
+            implementation(compose.runtime)
+            implementation(compose.foundation)
+        }
+    }
+}

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

@@ -0,0 +1,71 @@
+package com.github.adriankuta.datastructure.tree.compose
+
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.mutableStateMapOf
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import com.github.adriankuta.datastructure.tree.TreeNode
+
+/**
+ * A lazily-rendered, expand/collapse tree for Compose Multiplatform. Only the currently-visible
+ * nodes are composed, so it scales to large trees. Expansion state is remembered internally, keyed
+ * by node identity.
+ *
+ * ```
+ * LazyTree(root) { node, depth, expanded, toggle ->
+ *     Row(Modifier.padding(start = (depth * 16).dp).clickable(onClick = toggle)) {
+ *         if (!node.isLeaf) Text(if (expanded) "▾" else "▸")
+ *         Text(node.value.toString())
+ *     }
+ * }
+ * ```
+ *
+ * @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 nodeContent renders a single node. Receives the node, its depth (root = 0), whether it is
+ *   expanded, and a `toggle` callback that flips this node's expansion state.
+ */
+@Composable
+public fun <T> LazyTree(
+    root: TreeNode<T>,
+    modifier: Modifier = Modifier,
+    initiallyExpanded: Boolean = true,
+    nodeContent: @Composable (node: TreeNode<T>, depth: Int, expanded: Boolean, toggle: () -> Unit) -> Unit,
+) {
+    val expansion = remember(root) { mutableStateMapOf<TreeNode<T>, Boolean>() }
+    val isExpanded: (TreeNode<T>) -> Boolean = { node -> expansion[node] ?: initiallyExpanded }
+
+    val visible = flattenVisible(root, isExpanded)
+
+    LazyColumn(modifier = modifier) {
+        items(visible.size) { index ->
+            val (node, depth) = visible[index]
+            nodeContent(node, depth, isExpanded(node)) {
+                expansion[node] = !isExpanded(node)
+            }
+        }
+    }
+}
+
+/**
+ * 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.
+ */
+private fun <T> flattenVisible(
+    root: TreeNode<T>,
+    isExpanded: (TreeNode<T>) -> Boolean,
+): List<Pair<TreeNode<T>, Int>> {
+    val result = mutableListOf<Pair<TreeNode<T>, Int>>()
+    val stack = ArrayDeque<Pair<TreeNode<T>, Int>>()
+    stack.addLast(root to 0)
+    while (stack.isNotEmpty()) {
+        val (node, depth) = stack.removeLast()
+        result.add(node to depth)
+        if (isExpanded(node)) {
+            node.children.asReversed().forEach { child -> stack.addLast(child to depth + 1) }
+        }
+    }
+    return result
+}

tree-structure-coroutines/build.gradle.kts

@@ -46,7 +46,21 @@ 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()

tree-structure-serialization/build.gradle.kts

@@ -47,7 +47,21 @@ 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()

tree-structure-serialization/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/serialization/TreeNodeDto.kt

@@ -14,8 +14,8 @@ import kotlinx.serialization.Serializable
  */
 @Serializable
 public data class TreeNodeDto<T>(
-    val value: T,
-    val children: List<TreeNodeDto<T>> = emptyList(),
+    public val value: T,
+    public val children: List<TreeNodeDto<T>> = emptyList(),
 )
 
 /** Converts this subtree into a serializable [TreeNodeDto], preserving values and shape. */