diff --git a/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/utils/ListUtils.kt b/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/utils/ListUtils.kt
index d70e2417f..8c1412096 100644
--- a/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/utils/ListUtils.kt
+++ b/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/utils/ListUtils.kt
@@ -22,6 +22,14 @@ package com.vitorpamplona.amethyst.commons.utils
 
 import kotlinx.collections.immutable.ImmutableList
 
+/**
+ * Compares two [ImmutableList] instances by element identity (`===`), not value equality (`==`).
+ *
+ * Returns `true` only when both lists have the same size and each element at the same index
+ * is the exact same object reference.
+ *
+ * Useful for cheap change detection in UI/state pipelines where object identity is meaningful.
+ */
 fun <T> equalImmutableLists(
     list1: ImmutableList<T>,
     list2: ImmutableList<T>,