Release 4.1.1: publish on macOS to restore Apple/iOS artifacts

docs/superpowers/specs/2026-06-07-tree-enhancements-design.md

@@ -0,0 +1,77 @@
+# Design — four additive enhancements to `tree-structure` (target 4.1.0)
+
+Date: 2026-06-07. Source issues: #34, #35, #36, #33. Integration: **four separate PRs**,
+one per issue (`Closes #NN`), matching the repo's per-issue PR convention (#32).
+
+## Shared rules (every issue)
+
+- `explicitApi()` is on everywhere → every new public declaration is `public` with KDoc.
+- New tests live in `commonTest`, use `kotlin("test")`, and mirror the existing test style
+  (`TreeNodeV4Test.kt`, `TreeNodeNavigationTest.kt`, …).
+- Add a bullet to `CHANGELOG.md` under `## [Unreleased]` → `### Added` (do **not** bump
+  `PUBLISH_VERSION`; releases are a separate manual step).
+- Regenerate the binary-compatibility baseline with `./gradlew apiDump`; verify with `apiCheck`.
+- Do not modify the core public surface in a breaking way — these are additive only.
+
+## #34 — Structural mutation helpers → **members on `TreeNode`**
+
+Members (not extensions) because they need the private `_children`/`_parent` and the cycle/parent
+validation.
+
+- Extract the existing inline validation from `addChild` into a private
+  `validateAttachable(child)` and reuse it.
+- `insertChild(index: Int, child)` — validated insert at index (bounds `0.._children.size`).
+- `removeChildAt(index: Int): TreeNode<T>` — remove and return the detached child.
+- `replaceChild(index: Int, child): TreeNode<T>` — swap, return the old (now detached) child.
+- `moveChild(child, toIndex): Boolean` — reorder an existing direct child; no re-parent/cycle
+  check needed (it is already a child); `false` if `child` is not a direct child.
+- `addChildren(vararg children)` — validated append of several (per-child `addChild` semantics).
+- `sortChildren(comparator: Comparator<TreeNode<T>>)` — stable in-place reorder.
+
+## #35 — Query algorithms → **extensions** in new `TreeNodeQueryExt.kt`
+
+Built on the public API (`ancestors()`, `parent`, `depth()`, sequences). Return `null` when the
+two nodes are unrelated (different trees).
+
+- `lowestCommonAncestor(other): TreeNode<T>?` — deepest common node; includes self/other as
+  candidates (`LCA(a, a) == a`, `LCA(a, descendantOfA) == a`).
+- `distance(other): Int?` — `depth(this) + depth(other) - 2 * depth(lca)`.
+- `pathBetween(other): List<TreeNode<T>>?` — `[this … lca … other]`.
+- `contains(value): Boolean` — value search over the subtree, including the receiver.
+
+Document complexity (parent-walk based; O(depth) for LCA/distance, O(n) for `contains`).
+
+## #36 — Customizable `prettyString()` → **extension** in new `TreeNodePrettyPrintExt.kt`
+
+- `data class TreeConnectors(branch, lastBranch, vertical, empty)` with a `companion`:
+  `Default` (current Unicode box-drawing) and `Ascii`.
+- `fun TreeNode<T>.prettyString(connectors = TreeConnectors.Default,
+  render: (value: T, depth: Int, isLast: Boolean) -> String = { v, _, _ -> v.toString() }): String`.
+- The no-arg member `prettyString()` is unchanged; member resolution wins for `node.prettyString()`,
+  so existing behaviour and output are byte-for-byte identical.
+
+## #33 — Immutable variant → **new module `:tree-structure-immutable`**
+
+Largest item; fully isolated from the other three except for `settings.gradle.kts`,
+`libs.versions.toml`, the root `build.gradle.kts` Dokka aggregation block, and `CHANGELOG.md`.
+
+- `settings.gradle.kts`: `include(":tree-structure-immutable")`.
+- New `build.gradle.kts` mirroring the serialization module's KMP target matrix; deps
+  `api(project(":"))` + `kotlinx-collections-immutable`.
+- `libs.versions.toml`: add `kotlinx-collections-immutable` (a recent stable, e.g. 0.3.8) and
+  wire it.
+- Root `build.gradle.kts`: add `dokka(project(":tree-structure-immutable"))` to the aggregation.
+- `ImmutableTreeNode<T>` backed by `persistentListOf` children; `addChild` / `removeChild` /
+  `mapValues` return a new root with unchanged subtrees structurally shared. Mirror pre/post/
+  level-order traversal helpers.
+- Its own `tree-structure-immutable/api/` baseline via `apiDump`.
+
+## Orchestration
+
+- Four git worktrees off `origin/master`, one branch each (`feat/...`), for full isolation — no
+  collisions on `TreeNode.kt`, `api/*.api`, or `CHANGELOG.md`.
+- A workflow pipelines each issue: implement (code + KDoc + tests + CHANGELOG + `apiDump`) and
+  verify locally (`jvmTest` + `apiCheck`), then an adversarial reviewer checks issue-conformance,
+  test quality, invariants, explicit API, `.api` freshness, and that it builds. Local checks are
+  JVM-only for speed; CI validates the full KMP matrix on each PR.
+- Then push each passing branch and open a PR (`Closes #NN`); remove the worktrees afterward.