diff --git a/src/Collection.php b/src/Collection.php
index 216bb3f..87a3ca4 100644
--- a/src/Collection.php
+++ b/src/Collection.php
@@ -190,6 +190,7 @@ public function count(): int;
 	 * Returns the number of elements matching the predicate.
 	 *
 	 * @param Closure(E, int):bool $predicate
+	 * @return int<0, max>
 	 */
 	public function countWhere(Closure $predicate): int;
 
diff --git a/src/List/ListInterface.php b/src/List/ListInterface.php
index e02a18e..6053e65 100644
--- a/src/List/ListInterface.php
+++ b/src/List/ListInterface.php
@@ -42,6 +42,16 @@ public function get(int $index);
 	 */
 	public function getOrNull(int $index): mixed;
 
+	/**
+	 * Returns the element at the specified index, or throws if out of bounds.
+	 * Alias of get() for array access syntax `$list[0]`.
+	 *
+	 * @param int $offset
+	 * @return E
+	 * @throws IndexOutOfBoundsException
+	 */
+	public function offsetGet(mixed $offset): mixed;
+
 	/**
 	 * Returns the element at the specified index, or the default value if out of bounds.
 	 *
diff --git a/src/Map/Map.php b/src/Map/Map.php
index 82c96a7..26691c1 100644
--- a/src/Map/Map.php
+++ b/src/Map/Map.php
@@ -79,6 +79,16 @@ interface Map extends IteratorAggregate, Countable, ArrayAccess, JsonSerializabl
 	 */
 	public function get(string|int|bool|float|object $key);
 
+	/**
+	 * Retrieves the value associated with the given key, or throws if absent.
+	 * Alias of get() for array access syntax `$map['key']`.
+	 *
+	 * @param K $offset
+	 * @return V
+	 * @throws NoSuchElementException
+	 */
+	public function offsetGet(mixed $offset): mixed;
+
 	/**
 	 * Retrieves the value associated with the given key.
 	 * Returns null if the key does not exist in the map.
@@ -163,6 +173,7 @@ public function count(): int;
 	 * Returns the number of entries matching the predicate.
 	 *
 	 * @param Closure(V, K):bool $predicate
+	 * @return int<0, max>
 	 */
 	public function countWhere(Closure $predicate): int;
 
diff --git a/tests/Type/Collection/AccessTypeTest.php b/tests/Type/Collection/AccessTypeTest.php
new file mode 100644
index 0000000..9fd4771
--- /dev/null
+++ b/tests/Type/Collection/AccessTypeTest.php
@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<int> $c */
+$c = listOf([1, 2, 3]);
+
+assertType('int', $c->first());
+assertType('int|null', $c->firstOrNull());
+assertType('int', $c->last());
+assertType('int|null', $c->lastOrNull());
+assertType('int', $c->single());
+assertType('int|null', $c->singleOrNull());
+assertType('int|null', $c->find(fn (int $x): bool => $x > 0));
+assertType('int|null', $c->findLast(fn (int $x): bool => $x > 0));
+assertType('int', $c->expect(fn (int $x): bool => $x > 0));
+assertType('int', $c->expectLast(fn (int $x): bool => $x > 0));
+assertType('int', $c->random());
+assertType('int|null', $c->randomOrNull());
diff --git a/tests/Type/Collection/AggregationTypeTest.php b/tests/Type/Collection/AggregationTypeTest.php
new file mode 100644
index 0000000..20b9c6b
--- /dev/null
+++ b/tests/Type/Collection/AggregationTypeTest.php
@@ -0,0 +1,42 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<int> $c */
+$c = listOf([1, 2, 3]);
+
+// fold: return type follows the initial accumulator type R.
+assertType('int', $c->fold(0, fn (int $acc, int $x): int => $acc + $x));
+assertType('string', $c->fold('', fn (string $acc, int $x): string => $acc . $x));
+
+assertType('int', $c->reduce(fn (int $acc, int $x): int => $acc + $x));
+assertType('int|null', $c->reduceOrNull(fn (int $acc, int $x): int => $acc + $x));
+
+// min/max return the element type E (declared `: mixed`), not a fixed scalar.
+assertType('int', $c->min());
+assertType('int|null', $c->minOrNull());
+assertType('int', $c->max());
+assertType('int|null', $c->maxOrNull());
+
+// sum: a collection of ints sums to an int.
+assertType('int', listOf([1, 2, 3])->sum());
+
+// As soon as a float is involved, the sum widens back to int|float.
+assertType('float|int', listOf([1.0, 2.0])->sum());
+assertType('float|int', listOf([1, 2.0])->sum());
+
+// With a selector declared to return int, the sum narrows to int.
+assertType('int', listOf([1, 2, 3])->sum(fn (int $x): int => $x * 2));
+// Any other selector return type (float, or an un-inferrable/mixed one) stays int|float.
+assertType('float|int', listOf([1, 2, 3])->sum(fn (int $x): float => $x / 2));
diff --git a/tests/Type/Collection/ConversionTypeTest.php b/tests/Type/Collection/ConversionTypeTest.php
new file mode 100644
index 0000000..fb4f0f3
--- /dev/null
+++ b/tests/Type/Collection/ConversionTypeTest.php
@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<string> $c */
+$c = listOf(['a', 'b', 'c']);
+
+// toMap: value defaults to the element type unless a value transform is given.
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, string>',
+	$c->toMap(fn (string $x): string => $x),
+);
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, bool>',
+	$c->toMap(fn (string $x): string => $x, fn (string $x): bool => $x !== ''),
+);
+
+assertType('Noctud\Collection\List\ImmutableList<string>', $c->toList());
+assertType('Noctud\Collection\Set\ImmutableSet<string>', $c->toSet());
+assertType('list<string>', $c->toArray());
+assertType('Noctud\Collection\MutableCollection<string>', $c->toMutable());
+assertType('Noctud\Collection\ImmutableCollection<string>', $c->toImmutable());
+assertType('Noctud\Collection\Collection<string>', $c->forEach(fn (string $x): null => null));
diff --git a/tests/Type/Collection/OrderingTypeTest.php b/tests/Type/Collection/OrderingTypeTest.php
new file mode 100644
index 0000000..f704593
--- /dev/null
+++ b/tests/Type/Collection/OrderingTypeTest.php
@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<int> $c */
+$c = listOf([1, 2, 3]);
+
+assertType('Noctud\Collection\Collection<int>', $c->sorted());
+assertType('Noctud\Collection\Collection<int>', $c->sortedDesc());
+assertType('Noctud\Collection\Collection<int>', $c->sortedBy(fn (int $x): int => $x));
+assertType('Noctud\Collection\Collection<int>', $c->sortedByDesc(fn (int $x): int => $x));
+assertType('Noctud\Collection\Collection<int>', $c->sortedWith(fn (int $a, int $b): int => $a <=> $b));
+assertType('Noctud\Collection\Collection<int>', $c->reversed());
+assertType('Noctud\Collection\Collection<int>', $c->shuffled());
diff --git a/tests/Type/Collection/QueryTypeTest.php b/tests/Type/Collection/QueryTypeTest.php
new file mode 100644
index 0000000..01ab485
--- /dev/null
+++ b/tests/Type/Collection/QueryTypeTest.php
@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<string> $c */
+$c = listOf(['a', 'b', 'c']);
+
+// countWhere() pins the declared @return int<0, max>.
+// count() itself is native-typed (`: int`, no PHPDoc) and needs no type test.
+assertType('int<0, max>', $c->countWhere(fn (string $x): bool => $x !== ''));
+
+// countBy: the key selector's return becomes the map key, values are the counts.
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, int>',
+	$c->countBy(fn (string $x): string => $x),
+);
diff --git a/tests/Type/Collection/TransformTypeTest.php b/tests/Type/Collection/TransformTypeTest.php
new file mode 100644
index 0000000..1a581a8
--- /dev/null
+++ b/tests/Type/Collection/TransformTypeTest.php
@@ -0,0 +1,68 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use stdClass;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<string> $c */
+$c = listOf(['a', 'b', 'c']);
+
+// Filtering preserves the element type.
+assertType('Noctud\Collection\Collection<string>', $c->filter(fn (string $x): bool => $x !== ''));
+assertType('Noctud\Collection\Collection<string>', $c->filterNotNull());
+assertType('Noctud\Collection\Collection<stdClass>', $c->filterInstanceOf(stdClass::class));
+
+/** @var Collection<string|null> $nullable */
+$nullable = listOf(['a', null]);
+assertType('Noctud\Collection\Collection<string>', $nullable->filterNotNull());
+
+// Mapping changes the element type.
+assertType('Noctud\Collection\Collection<int>', $c->map(fn (string $x): int => (int) $x));
+assertType('Noctud\Collection\Collection<int>', $c->mapNotNull(fn (string $x): ?int => $x !== '' ? 1 : null));
+assertType('Noctud\Collection\Collection<int>', $c->flatMap(fn (string $x): array => [(int) $x]));
+assertType('Noctud\Collection\Collection<mixed>', $c->flatten());
+
+// Slicing preserves the element type.
+assertType('Noctud\Collection\Collection<string>', $c->takeFirst(2));
+assertType('Noctud\Collection\Collection<string>', $c->dropFirst(2));
+assertType('Noctud\Collection\Collection<string>', $c->takeLast(2));
+assertType('Noctud\Collection\Collection<string>', $c->dropLast(2));
+assertType('Noctud\Collection\Collection<string>', $c->takeWhile(fn (string $x): bool => $x !== ''));
+assertType('Noctud\Collection\Collection<string>', $c->dropWhile(fn (string $x): bool => $x !== ''));
+assertType('Noctud\Collection\Collection<string>', $c->takeLastWhile(fn (string $x): bool => $x !== ''));
+assertType('Noctud\Collection\Collection<string>', $c->dropLastWhile(fn (string $x): bool => $x !== ''));
+assertType('Noctud\Collection\Collection<string>', $c->distinct());
+assertType('Noctud\Collection\Collection<string>', $c->distinctBy(fn (string $x): int => (int) $x));
+
+// Grouping into lists of lists.
+assertType('Noctud\Collection\List\ListInterface<Noctud\Collection\List\ListInterface<string>>', $c->chunked(2));
+assertType('Noctud\Collection\List\ListInterface<Noctud\Collection\List\ListInterface<string>>', $c->windowed(2));
+assertType('Noctud\Collection\List\ListInterface<array{string, int}>', $c->zip([1, 2]));
+assertType('Noctud\Collection\List\ListInterface<array{string, string}>', $c->zipWithNext());
+assertType('array{Noctud\Collection\List\ImmutableList<mixed>, Noctud\Collection\List\ImmutableList<mixed>}', $c->unzip());
+assertType('array{Noctud\Collection\Collection<string>, Noctud\Collection\Collection<string>}', $c->partition(fn (string $x): bool => $x !== ''));
+
+// groupBy is conditional on the value transform.
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, Noctud\Collection\Collection<string>>',
+	$c->groupBy(fn (string $x): string => $x),
+);
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, Noctud\Collection\List\ImmutableList<int>>',
+	$c->groupBy(fn (string $x): string => $x, fn (string $x): int => (int) $x),
+);
+
+// Set operations.
+assertType('Noctud\Collection\Set\Set<string>', $c->intersect(['a', 'b']));
+assertType('Noctud\Collection\Set\Set<string>', $c->union(['a', 'b']));
+assertType('Noctud\Collection\Set\Set<string>', $c->subtract(['a', 'b']));
diff --git a/tests/Type/CollectionSumTypeTest.php b/tests/Type/CollectionSumTypeTest.php
deleted file mode 100644
index 645a5b7..0000000
--- a/tests/Type/CollectionSumTypeTest.php
+++ /dev/null
@@ -1,25 +0,0 @@
-<?php
-
-/**
- * This file is part of the Noctud Collection.
- * Copyright (c) Noctud.dev
- */
-
-declare(strict_types=1);
-
-namespace Noctud\Collection\Tests\Type;
-
-use function Noctud\Collection\listOf;
-use function PHPStan\Testing\assertType;
-
-// A collection of ints sums to an int.
-assertType('int', listOf([1, 2, 3])->sum());
-
-// As soon as a float is involved, the sum widens back to int|float.
-assertType('float|int', listOf([1.0, 2.0])->sum());
-assertType('float|int', listOf([1, 2.0])->sum());
-
-// With a selector declared to return int, the sum narrows to int.
-assertType('int', listOf([1, 2, 3])->sum(fn (int $x): int => $x * 2));
-// Any other selector return type (float, or an un-inferrable/mixed one) stays int|float.
-assertType('float|int', listOf([1, 2, 3])->sum(fn (int $x): float => $x / 2));
diff --git a/tests/Type/FilterNotNullTypeTest.php b/tests/Type/FilterNotNullTypeTest.php
deleted file mode 100644
index 9b3b8f1..0000000
--- a/tests/Type/FilterNotNullTypeTest.php
+++ /dev/null
@@ -1,38 +0,0 @@
-<?php
-
-/**
- * This file is part of the Noctud Collection.
- * Copyright (c) Noctud.dev
- */
-
-declare(strict_types=1);
-
-namespace Noctud\Collection\Tests\Type;
-
-use Noctud\Collection\Collection;
-
-use function Noctud\Collection\listOf;
-use function Noctud\Collection\mutableListOf;
-use function Noctud\Collection\mutableSetOf;
-use function Noctud\Collection\mutableStringMapOf;
-use function Noctud\Collection\setOf;
-use function Noctud\Collection\stringMapOf;
-use function PHPStan\Testing\assertType;
-
-// filterNotNull() removes null from the element type (issue #16).
-assertType('Noctud\Collection\List\ImmutableList<int>', listOf([1, null])->filterNotNull());
-assertType('Noctud\Collection\List\ImmutableList<int>', mutableListOf([1, null])->filterNotNull());
-assertType('Noctud\Collection\Set\ImmutableSet<int>', setOf([1, null])->filterNotNull());
-assertType('Noctud\Collection\Set\ImmutableSet<int>', mutableSetOf([1, null])->filterNotNull());
-
-// Also through the base Collection interface.
-/** @var Collection<string|null> $c */
-$c = listOf(['a', null]);
-assertType('Noctud\Collection\Collection<string>', $c->filterNotNull());
-
-// A collection without null keeps its element type unchanged.
-assertType('Noctud\Collection\List\ImmutableList<int>', listOf([1, 2])->filterNotNull());
-
-// filterValuesNotNull() removes null from the value type, keys are preserved.
-assertType('Noctud\Collection\Map\ImmutableMap<string, int>', stringMapOf(['a' => 1, 'b' => null])->filterValuesNotNull());
-assertType('Noctud\Collection\Map\ImmutableMap<string, int>', mutableStringMapOf(['a' => 1, 'b' => null])->filterValuesNotNull());
diff --git a/tests/Type/FunctionsTypeTest.php b/tests/Type/FunctionsTypeTest.php
new file mode 100644
index 0000000..aa8175d
--- /dev/null
+++ b/tests/Type/FunctionsTypeTest.php
@@ -0,0 +1,46 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type;
+
+use function Noctud\Collection\intMapOf;
+use function Noctud\Collection\listOf;
+use function Noctud\Collection\mapOf;
+use function Noctud\Collection\mapOfPairs;
+use function Noctud\Collection\mutableIntMapOf;
+use function Noctud\Collection\mutableListOf;
+use function Noctud\Collection\mutableMapOf;
+use function Noctud\Collection\mutableMapOfPairs;
+use function Noctud\Collection\mutableSetOf;
+use function Noctud\Collection\mutableStringMapOf;
+use function Noctud\Collection\setOf;
+use function Noctud\Collection\stringMapOf;
+use function PHPStan\Testing\assertType;
+
+// Lists
+assertType('Noctud\Collection\List\ImmutableList<string>', listOf(['a', 'b']));
+assertType('Noctud\Collection\List\MutableList<int>', mutableListOf([1, 2]));
+
+// Sets
+assertType('Noctud\Collection\Set\ImmutableSet<string>', setOf(['a', 'b']));
+assertType('Noctud\Collection\Set\MutableSet<int>', mutableSetOf([1, 2]));
+
+// Hash maps (assoc + pairs)
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', mapOf(['a' => 1, 'b' => 2]));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', mapOfPairs([['a', 1], ['b', 2]]));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', mutableMapOf(['a' => 1]));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', mutableMapOfPairs([['a', 1]]));
+
+// String maps
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', stringMapOf(['a' => 1]));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', mutableStringMapOf(['a' => 1]));
+
+// Int maps
+assertType('Noctud\Collection\Map\ImmutableMap<int, string>', intMapOf([1 => 'a']));
+assertType('Noctud\Collection\Map\MutableMap<int, string>', mutableIntMapOf([1 => 'a']));
diff --git a/tests/Type/List/AccessTypeTest.php b/tests/Type/List/AccessTypeTest.php
new file mode 100644
index 0000000..afe7d2f
--- /dev/null
+++ b/tests/Type/List/AccessTypeTest.php
@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\List;
+
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+$list = listOf([1, 2, 3]);
+
+assertType('int', $list->get(0));
+assertType('int|null', $list->getOrNull(0));
+assertType("'x'|int", $list->getOrDefault(0, 'x'));
+assertType("'x'|int", $list->getOrCompute(0, fn (): string => 'x'));
+assertType('Noctud\Collection\List\ImmutableList<int>', $list->slice(0, 2));
+
+// Array access via [] returns the element (offsetGet throws on a missing index).
+assertType('int', $list[0]);
+
+// toIndexedMap: value defaults to the element type unless a transform is given.
+assertType('Noctud\Collection\Map\ImmutableMap<int, int>', $list->toIndexedMap());
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<int, bool>',
+	$list->toIndexedMap(fn (int $x): bool => $x > 0),
+);
diff --git a/tests/Type/List/MutationTypeTest.php b/tests/Type/List/MutationTypeTest.php
new file mode 100644
index 0000000..403ade2
--- /dev/null
+++ b/tests/Type/List/MutationTypeTest.php
@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\List;
+
+use function Noctud\Collection\listOf;
+use function Noctud\Collection\mutableListOf;
+use function PHPStan\Testing\assertType;
+
+$imm = listOf([1, 2, 3]);
+
+// Immutable mutators WIDEN the element type.
+assertType('Noctud\Collection\List\ImmutableList<int|string>', $imm->add('x'));
+assertType('Noctud\Collection\List\ImmutableList<int|string>', $imm->addFirst('x'));
+assertType('Noctud\Collection\List\ImmutableList<int|string>', $imm->addAll(['x']));
+assertType('Noctud\Collection\List\ImmutableList<int|string>', $imm->set(0, 'x'));
+
+// Removals keep the element type.
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->removeEvery(1));
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->removeAt(0));
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->removeIf(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->removeAll([1]));
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->removeElement(1));
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->removeFirst());
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->removeLast());
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->retainAll([1]));
+
+// Mutable mutators are STRICT (@param E) and return the same MutableList.
+$mut = mutableListOf([1, 2, 3]);
+assertType('Noctud\Collection\List\MutableList<int>', $mut->add(4));
+assertType('Noctud\Collection\List\MutableList<int>', $mut->addFirst(0));
+assertType('Noctud\Collection\List\MutableList<int>', $mut->addAll([4, 5]));
+assertType('Noctud\Collection\List\MutableList<int>', $mut->set(0, 9));
+assertType('Noctud\Collection\List\MutableList<int>', $mut->removeEvery(1));
+assertType('Noctud\Collection\List\MutableList<int>', $mut->removeAt(0));
+assertType('Noctud\Collection\List\MutableList<int>', $mut->removeIf(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\List\MutableList<int>', $mut->clear());
+assertType('Noctud\Collection\List\MutableList<int>', $mut->sort());
+assertType('Noctud\Collection\List\MutableList<int>', $mut->sortBy(fn (int $x): int => $x));
+assertType('Noctud\Collection\List\MutableList<int>', $mut->sortWith(fn (int $a, int $b): int => $a <=> $b));
+assertType('Noctud\Collection\List\MutableList<int>', $mut->reverse());
+assertType('Noctud\Collection\List\MutableList<int>', $mut->shuffle());
diff --git a/tests/Type/List/NarrowingTypeTest.php b/tests/Type/List/NarrowingTypeTest.php
new file mode 100644
index 0000000..1f5babe
--- /dev/null
+++ b/tests/Type/List/NarrowingTypeTest.php
@@ -0,0 +1,60 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\List;
+
+use Noctud\Collection\List\ListInterface;
+use stdClass;
+use function Noctud\Collection\listOf;
+use function Noctud\Collection\mutableListOf;
+use function PHPStan\Testing\assertType;
+
+$imm = listOf([1, 2, 3]);
+
+// Shape-preserving transforms narrow back to ImmutableList.
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->filter(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->filterNotNull());
+assertType('Noctud\Collection\List\ImmutableList<int>', listOf([1, null])->filterNotNull());
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->takeFirst(2));
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->dropLast(1));
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->takeWhile(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->distinct());
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->distinctBy(fn (int $x): int => $x));
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->sorted());
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->sortedBy(fn (int $x): int => $x));
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->reversed());
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->shuffled());
+assertType('Noctud\Collection\List\ImmutableList<int>', $imm->slice(0, 2));
+assertType(
+	'array{Noctud\Collection\List\ImmutableList<int>, Noctud\Collection\List\ImmutableList<int>}',
+	$imm->partition(fn (int $x): bool => $x > 0),
+);
+
+// Type-changing transforms move to the new element type but stay ImmutableList.
+assertType('Noctud\Collection\List\ImmutableList<bool>', $imm->map(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\List\ImmutableList<stdClass>', $imm->filterInstanceOf(stdClass::class));
+
+// chunked/windowed always produce a list of lists. They return the base ListInterface even
+// on an ImmutableList: ListInterface's element type is invariant, so narrowing the nested
+// type would break variance in the shared trait — and ListInterface<...> is already correct.
+assertType('Noctud\Collection\List\ListInterface<Noctud\Collection\List\ListInterface<int>>', $imm->chunked(2));
+
+// A mutable list's transforms produce a fresh immutable list.
+$mut = mutableListOf([1, 2, 3]);
+assertType('Noctud\Collection\List\ImmutableList<int>', $mut->filter(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\List\ImmutableList<bool>', $mut->map(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\List\ImmutableList<int>', $mut->sorted());
+assertType('Noctud\Collection\List\ImmutableList<int>', mutableListOf([1, null])->filterNotNull());
+
+// The base ListInterface contract keeps everything at the ListInterface level.
+/** @var ListInterface<int> $list */
+$list = listOf([1, 2, 3]);
+assertType('Noctud\Collection\List\ListInterface<int>', $list->filter(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\List\ListInterface<bool>', $list->map(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\List\ListInterface<int>', $list->sorted());
diff --git a/tests/Type/Map/AccessTypeTest.php b/tests/Type/Map/AccessTypeTest.php
new file mode 100644
index 0000000..a404e6e
--- /dev/null
+++ b/tests/Type/Map/AccessTypeTest.php
@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Map;
+
+use function Noctud\Collection\mapOf;
+use function PHPStan\Testing\assertType;
+
+$map = mapOf(['a' => 1, 'b' => 2]);
+
+assertType('int', $map->get('a'));
+assertType('int|null', $map->getOrNull('a'));
+assertType("'x'|int", $map->getOrDefault('a', 'x'));
+assertType("'x'|int", $map->getOrCompute('a', fn (): string => 'x'));
+// Array access via [] returns the value (offsetGet throws on a missing key).
+assertType('int', $map['a']);
+
+// Virtual property hooks expose the key/value/entry views.
+assertType('Noctud\Collection\Set\Set<string>', $map->keys);
+assertType('Noctud\Collection\Collection<int>', $map->values);
+assertType('Noctud\Collection\Set\Set<Noctud\Collection\Map\MapEntry<string, int>>', $map->entries);
diff --git a/tests/Type/Map/ConversionTypeTest.php b/tests/Type/Map/ConversionTypeTest.php
new file mode 100644
index 0000000..b051cd5
--- /dev/null
+++ b/tests/Type/Map/ConversionTypeTest.php
@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Map;
+
+use stdClass;
+use function Noctud\Collection\intMapOf;
+use function Noctud\Collection\listOf;
+use function Noctud\Collection\mapOf;
+use function PHPStan\Testing\assertType;
+
+$map = mapOf(['a' => 1, 'b' => 2]);
+
+// toArray is conditional: a string|int key stays a native array key.
+assertType('array<string, int>', $map->toArray());
+assertType('array<int, string>', intMapOf([1 => 'a', 2 => 'b'])->toArray());
+// Non-array-key keys (e.g. objects) fall back to a value-typed array.
+assertType('array<string>', listOf(['a'])->toMap(fn (string $i): stdClass => new stdClass())->toArray());
+
+// map/mapNotNull/flatMap flatten the map down to an immutable list.
+assertType('Noctud\Collection\List\ImmutableList<bool>', $map->map(fn (int $v, string $k): bool => $v > 0));
+assertType('Noctud\Collection\List\ImmutableList<bool>', $map->mapNotNull(fn (int $v, string $k): ?bool => $v > 0 ? true : null));
+assertType('Noctud\Collection\List\ImmutableList<int>', $map->flatMap(fn (int $v, string $k): array => [$v]));
+
+assertType('list<array{string, int}>', $map->toPairs());
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $map->toMutable());
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->toImmutable());
+
+// forEach variants return the map unchanged.
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->forEach(fn (int $v, string $k): null => null));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->forEachKey(fn (string $k): null => null));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->forEachValue(fn (int $v): null => null));
diff --git a/tests/Type/Map/EntryTypeTest.php b/tests/Type/Map/EntryTypeTest.php
new file mode 100644
index 0000000..301d86a
--- /dev/null
+++ b/tests/Type/Map/EntryTypeTest.php
@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Map;
+
+use function Noctud\Collection\mapOf;
+use function PHPStan\Testing\assertType;
+
+$map = mapOf(['a' => 1, 'b' => 2]);
+
+// The entries view of a map is a set of MapEntry.
+assertType('Noctud\Collection\Set\Set<Noctud\Collection\Map\MapEntry<string, int>>', $map->entries);
+assertType('Noctud\Collection\Map\MapEntry<string, int>|null', $map->entries->firstOrNull());
+
+// MapEntry exposes key/value through virtual property hooks (generic K/V, not the
+// declared `string|int|bool|float|object`/`mixed`).
+$entry = $map->entries->firstOrNull();
+if ($entry !== null) {
+	assertType('string', $entry->key);
+	assertType('int', $entry->value);
+}
diff --git a/tests/Type/Map/FactoryTypeTest.php b/tests/Type/Map/FactoryTypeTest.php
new file mode 100644
index 0000000..ee28cb0
--- /dev/null
+++ b/tests/Type/Map/FactoryTypeTest.php
@@ -0,0 +1,20 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Map;
+
+use Noctud\Collection\Map\HashMap\ImmutableHashMap;
+use Noctud\Collection\Map\HashMap\MutableHashMap;
+use function PHPStan\Testing\assertType;
+
+// Static factories infer key/value types from the given data.
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', ImmutableHashMap::of(['a' => 1, 'b' => 2]));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', ImmutableHashMap::ofPairs([['a', 1], ['b', 2]]));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', MutableHashMap::of(['a' => 1, 'b' => 2]));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', MutableHashMap::ofPairs([['a', 1], ['b', 2]]));
diff --git a/tests/Type/Map/MutationTypeTest.php b/tests/Type/Map/MutationTypeTest.php
new file mode 100644
index 0000000..512a33e
--- /dev/null
+++ b/tests/Type/Map/MutationTypeTest.php
@@ -0,0 +1,54 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Map;
+
+use function Noctud\Collection\mapOf;
+use function Noctud\Collection\mutableMapOf;
+use function PHPStan\Testing\assertType;
+
+$imm = mapOf(['a' => 1, 'b' => 2]);
+
+// Clean int/bool values derived from the map itself, to observe widening.
+$anInt = $imm->get('a');
+$aBool = $imm->isEmpty();
+
+// Immutable put/putFirst/putIfAbsent WIDEN both key and value types.
+assertType('Noctud\Collection\Map\ImmutableMap<int|string, bool|int>', $imm->put($anInt, $aBool));
+assertType('Noctud\Collection\Map\ImmutableMap<int|string, bool|int>', $imm->putIfAbsent($anInt, $aBool));
+assertType('Noctud\Collection\Map\ImmutableMap<int|string, bool|int>', $imm->putFirst($anInt, $aBool));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $imm->putAll(['c' => 3]));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $imm->putAllPairs([['c', 3]]));
+
+// Removals keep both key and value types.
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $imm->remove('a'));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $imm->removeFirst());
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $imm->removeLast());
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $imm->removeIf(fn (int $v, string $k): bool => $v > 0));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $imm->removeIfKey(fn (string $k): bool => $k !== ''));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $imm->removeIfValue(fn (int $v): bool => $v > 0));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $imm->removeNullValues());
+
+// Mutable put/remove are STRICT and return the same MutableMap.
+$mut = mutableMapOf(['a' => 1]);
+assertType('int', $mut->getOrPut('a', fn (): int => 0));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->put('b', 2));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->putIfAbsent('c', 3));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->putFirst('z', 0));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->putAll(['d' => 4]));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->remove('a'));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->clear());
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->sortByKey());
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->sortByValue());
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->sortBy(fn (int $v, string $k): int => $v));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->sortWithKey(fn (string $a, string $b): int => $a <=> $b));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->sortWithValue(fn (int $a, int $b): int => $a <=> $b));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->sortWith(fn ($a, $b): int => 0));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->reverse());
+assertType('Noctud\Collection\Map\MutableMap<string, int>', $mut->shuffle());
diff --git a/tests/Type/Map/NarrowingTypeTest.php b/tests/Type/Map/NarrowingTypeTest.php
new file mode 100644
index 0000000..e76027a
--- /dev/null
+++ b/tests/Type/Map/NarrowingTypeTest.php
@@ -0,0 +1,70 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Map;
+
+use stdClass;
+use function Noctud\Collection\mapOf;
+use function Noctud\Collection\mutableStringMapOf;
+use function Noctud\Collection\stringMapOf;
+use function PHPStan\Testing\assertType;
+
+$map = mapOf(['a' => 1, 'b' => 2]);
+
+// Filtering preserves both key and value types and narrows back to ImmutableMap.
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->filter(fn (int $v, string $k): bool => $v > 0));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->filterKeys(fn (string $k): bool => $k !== ''));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->filterValues(fn (int $v): bool => $v > 0));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->filterValuesNotNull());
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', stringMapOf(['a' => 1, 'b' => null])->filterValuesNotNull());
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', mutableStringMapOf(['a' => 1, 'b' => null])->filterValuesNotNull());
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, stdClass>',
+	$map->filterValuesInstanceOf(stdClass::class),
+);
+
+// mapKeys changes the key type; mapValues changes the value type.
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<int, int>',
+	$map->mapKeys(fn (int $v, string $k): int => $v),
+);
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, bool>',
+	$map->mapValues(fn (int $v, string $k): bool => $v > 0),
+);
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, bool>',
+	$map->mapValuesNotNull(fn (int $v, string $k): ?bool => $v > 0 ? true : null),
+);
+
+// flip swaps keys and values.
+assertType('Noctud\Collection\Map\ImmutableMap<int, string>', $map->flip());
+
+// Ordering keeps the key/value types.
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->sortedByKey());
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->sortedByKeyDesc());
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->sortedByValue());
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->sortedByValueDesc());
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->sortedBy(fn (int $v, string $k): int => $v));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->sortedByDesc(fn (int $v, string $k): int => $v));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->sortedWithKey(fn (string $a, string $b): int => $a <=> $b));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->sortedWithValue(fn (int $a, int $b): int => $a <=> $b));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->sortedWith(fn ($a, $b): int => 0));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->reversed());
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->shuffled());
+
+// Slicing keeps the key/value types.
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->takeFirst(1));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->takeLast(1));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->dropFirst(1));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->dropLast(1));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->takeWhile(fn (int $v, string $k): bool => $v > 0));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->dropWhile(fn (int $v, string $k): bool => $v > 0));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->takeLastWhile(fn (int $v, string $k): bool => $v > 0));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', $map->dropLastWhile(fn (int $v, string $k): bool => $v > 0));
diff --git a/tests/Type/Map/QueryTypeTest.php b/tests/Type/Map/QueryTypeTest.php
new file mode 100644
index 0000000..d05183d
--- /dev/null
+++ b/tests/Type/Map/QueryTypeTest.php
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Map;
+
+use function Noctud\Collection\mapOf;
+use function PHPStan\Testing\assertType;
+
+$map = mapOf(['a' => 1, 'b' => 2]);
+
+// countWhere() pins the declared @return int<0, max>.
+// count() itself is native-typed (`: int`, no PHPDoc) and needs no type test.
+assertType('int<0, max>', $map->countWhere(fn (int $v, string $k): bool => $v > 0));
diff --git a/tests/Type/MapToArrayTypeTest.php b/tests/Type/MapToArrayTypeTest.php
deleted file mode 100644
index 4b9cbc5..0000000
--- a/tests/Type/MapToArrayTypeTest.php
+++ /dev/null
@@ -1,33 +0,0 @@
-<?php
-
-/**
- * This file is part of the Noctud Collection.
- * Copyright (c) Noctud.dev
- */
-
-declare(strict_types=1);
-
-namespace Noctud\Collection\Tests\Type;
-
-use stdClass;
-use function Noctud\Collection\listOf;
-use function PHPStan\Testing\assertType;
-
-assertType(
-	'array<string, string>',
-	listOf(['a', 'b', 'c'])->toMap(fn (string $i) => $i)->toArray(),
-);
-assertType(
-	'array<int, string>',
-	listOf(['a', 'b'])->toMap(fn (string $i): int => 0)->toArray(),
-);
-
-assertType(
-	'array<int, int>',
-	listOf(['a', 'b'])->toMap(fn (string $i): int => 0, fn (string $i): int => 1)->toArray(),
-);
-
-assertType(
-	'array<string>',
-	listOf(['a'])->toMap(fn (string $i) => new stdClass())->toArray(),
-);
diff --git a/tests/Type/Set/MutationTypeTest.php b/tests/Type/Set/MutationTypeTest.php
new file mode 100644
index 0000000..7ec039a
--- /dev/null
+++ b/tests/Type/Set/MutationTypeTest.php
@@ -0,0 +1,43 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Set;
+
+use function Noctud\Collection\mutableSetOf;
+use function Noctud\Collection\setOf;
+use function PHPStan\Testing\assertType;
+
+$imm = setOf([1, 2, 3]);
+
+// Immutable mutators WIDEN the element type.
+assertType('Noctud\Collection\Set\ImmutableSet<int|string>', $imm->add('x'));
+assertType('Noctud\Collection\Set\ImmutableSet<int|string>', $imm->addFirst('x'));
+assertType('Noctud\Collection\Set\ImmutableSet<int|string>', $imm->addAll(['x']));
+
+// Removals keep the element type.
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->removeIf(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->removeAll([1]));
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->removeElement(1));
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->removeFirst());
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->removeLast());
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->retainAll([1]));
+
+// Mutable mutators are STRICT (@param E) and return the same MutableSet.
+$mut = mutableSetOf([1, 2, 3]);
+assertType('Noctud\Collection\Set\MutableSet<int>', $mut->add(4));
+assertType('Noctud\Collection\Set\MutableSet<int>', $mut->addFirst(0));
+assertType('Noctud\Collection\Set\MutableSet<int>', $mut->addAll([4, 5]));
+assertType('Noctud\Collection\Set\MutableSet<int>', $mut->removeElement(1));
+assertType('Noctud\Collection\Set\MutableSet<int>', $mut->removeIf(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\Set\MutableSet<int>', $mut->clear());
+assertType('Noctud\Collection\Set\MutableSet<int>', $mut->sort());
+assertType('Noctud\Collection\Set\MutableSet<int>', $mut->sortBy(fn (int $x): int => $x));
+assertType('Noctud\Collection\Set\MutableSet<int>', $mut->sortWith(fn (int $a, int $b): int => $a <=> $b));
+assertType('Noctud\Collection\Set\MutableSet<int>', $mut->reverse());
+assertType('Noctud\Collection\Set\MutableSet<int>', $mut->shuffle());
diff --git a/tests/Type/Set/NarrowingTypeTest.php b/tests/Type/Set/NarrowingTypeTest.php
new file mode 100644
index 0000000..dfbe0a0
--- /dev/null
+++ b/tests/Type/Set/NarrowingTypeTest.php
@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Set;
+
+use Noctud\Collection\Set\Set;
+use stdClass;
+use function Noctud\Collection\mutableSetOf;
+use function Noctud\Collection\setOf;
+use function PHPStan\Testing\assertType;
+
+$imm = setOf([1, 2, 3]);
+
+// Shape-preserving transforms narrow back to ImmutableSet.
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->filter(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->filterNotNull());
+assertType('Noctud\Collection\Set\ImmutableSet<int>', setOf([1, null])->filterNotNull());
+assertType('Noctud\Collection\Set\ImmutableSet<int>', mutableSetOf([1, null])->filterNotNull());
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->takeFirst(2));
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->distinct());
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->sorted());
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->reversed());
+assertType('Noctud\Collection\Set\Set<int>', $imm->intersect([1, 2]));
+assertType('Noctud\Collection\Set\Set<int>', $imm->union([1, 2]));
+assertType('Noctud\Collection\Set\Set<int>', $imm->subtract([1, 2]));
+assertType('Noctud\Collection\Set\ImmutableSet<int>', $imm->toImmutable());
+assertType(
+	'array{Noctud\Collection\Set\ImmutableSet<int>, Noctud\Collection\Set\ImmutableSet<int>}',
+	$imm->partition(fn (int $x): bool => $x > 0),
+);
+
+// Type-changing transforms move to the new element type but stay ImmutableSet.
+assertType('Noctud\Collection\Set\ImmutableSet<bool>', $imm->map(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\Set\ImmutableSet<stdClass>', $imm->filterInstanceOf(stdClass::class));
+
+// The base Set contract keeps everything at the Set interface level.
+/** @var Set<int> $set */
+$set = setOf([1, 2, 3]);
+assertType('Noctud\Collection\Set\Set<int>', $set->filter(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\Set\Set<bool>', $set->map(fn (int $x): bool => $x > 0));
+assertType('Noctud\Collection\Set\Set<int>', $set->sorted());