effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/Array.ts

@@ -103,6 +103,8 @@ import type { NoInfer, TupleOf } from "./Types.ts"
 /**
  * Reference to the global `Array` constructor.
  *
+ * **When to use**
+ *
  * Use this when you need the native `Array` constructor while the `Array`
  * namespace is in scope (e.g. `Array.Array.isArray`, `Array.Array.from`).
  *
@@ -133,6 +135,8 @@ export interface ReadonlyArrayTypeLambda extends TypeLambda {
 /**
  * A readonly array guaranteed to have at least one element.
  *
+ * **When to use**
+ *
  * Use this type when you need to ensure non-emptiness at the type level while
  * preventing mutation. Many Array module functions accept or return this type.
  *
@@ -156,6 +160,8 @@ export type NonEmptyReadonlyArray<A> = readonly [A, ...Array<A>]
 /**
  * A mutable array guaranteed to have at least one element.
  *
+ * **Details**
+ *
  * This is the mutable counterpart of {@link NonEmptyReadonlyArray}. Most Array
  * module functions return `NonEmptyArray` when the result is guaranteed
  * non-empty.
@@ -180,6 +186,8 @@ export type NonEmptyArray<A> = [A, ...Array<A>]
 /**
  * Creates a `NonEmptyArray` from one or more elements.
  *
+ * **When to use**
+ *
  * - Use when you have literal values and want a typed non-empty array.
  * - The element type is inferred as the union of all arguments.
  * - Always returns a `NonEmptyArray` since at least one argument is required.
@@ -206,6 +214,8 @@ export const make = <Elements extends NonEmptyArray<unknown>>(
 /**
  * Creates a new `Array` of the specified length with all slots uninitialized.
  *
+ * **When to use**
+ *
  * - Use when you need a pre-sized array and will fill it imperatively.
  * - Elements are typed as `A | undefined` since slots are empty.
  * - Prefer {@link makeBy} when you can compute each element from its index.
@@ -229,6 +239,8 @@ export const allocate = <A = never>(n: number): Array<A | undefined> => new Arra
 /**
  * Creates a `NonEmptyArray` of length `n` where element `i` is computed by `f(i)`.
  *
+ * **When to use**
+ *
  * - Use when you need an array whose values depend on the index.
  * - `n` is normalized to an integer >= 1 — always returns at least one element.
  * - Dual: `Array.makeBy(5, f)` or `pipe(5, Array.makeBy(f))`.
@@ -252,6 +264,8 @@ export const makeBy: {
   /**
    * Creates a `NonEmptyArray` of length `n` where element `i` is computed by `f(i)`.
    *
+   * **When to use**
+   *
    * - Use when you need an array whose values depend on the index.
    * - `n` is normalized to an integer >= 1 — always returns at least one element.
    * - Dual: `Array.makeBy(5, f)` or `pipe(5, Array.makeBy(f))`.
@@ -275,6 +289,8 @@ export const makeBy: {
   /**
    * Creates a `NonEmptyArray` of length `n` where element `i` is computed by `f(i)`.
    *
+   * **When to use**
+   *
    * - Use when you need an array whose values depend on the index.
    * - `n` is normalized to an integer >= 1 — always returns at least one element.
    * - Dual: `Array.makeBy(5, f)` or `pipe(5, Array.makeBy(f))`.
@@ -308,6 +324,8 @@ export const makeBy: {
  * Creates a `NonEmptyArray` containing a range of integers, inclusive on both
  * ends.
  *
+ * **When to use**
+ *
  * - Use when you need a sequence of consecutive integers.
  * - If `start > end`, returns `[start]`.
  * - Always returns a `NonEmptyArray`.
@@ -332,6 +350,8 @@ export const range = (start: number, end: number): NonEmptyArray<number> =>
 /**
  * Creates a `NonEmptyArray` containing a value repeated `n` times.
  *
+ * **When to use**
+ *
  * - Use when you need multiple copies of the same value.
  * - `n` is normalized to an integer >= 1 — always returns at least one element.
  * - Dual: `Array.replicate("a", 3)` or `pipe("a", Array.replicate(3))`.
@@ -354,6 +374,8 @@ export const replicate: {
   /**
    * Creates a `NonEmptyArray` containing a value repeated `n` times.
    *
+   * **When to use**
+   *
    * - Use when you need multiple copies of the same value.
    * - `n` is normalized to an integer >= 1 — always returns at least one element.
    * - Dual: `Array.replicate("a", 3)` or `pipe("a", Array.replicate(3))`.
@@ -376,6 +398,8 @@ export const replicate: {
   /**
    * Creates a `NonEmptyArray` containing a value repeated `n` times.
    *
+   * **When to use**
+   *
    * - Use when you need multiple copies of the same value.
    * - `n` is normalized to an integer >= 1 — always returns at least one element.
    * - Dual: `Array.replicate("a", 3)` or `pipe("a", Array.replicate(3))`.
@@ -400,6 +424,8 @@ export const replicate: {
 /**
  * Converts an `Iterable` to an `Array`.
  *
+ * **Details**
+ *
  * - If the input is already an array, returns it **by reference** (no copy).
  * - Otherwise, creates a new array from the iterable.
  * - Use {@link copy} if you need a fresh array even when the input is already
@@ -426,6 +452,8 @@ export const fromIterable = <A>(collection: Iterable<A>): Array<A> =>
 /**
  * Normalizes a value that is either a single element or an array into an array.
  *
+ * **Details**
+ *
  * - If the input is already an array, returns it by reference.
  * - If the input is a single value, wraps it in a one-element array.
  * - Useful for APIs that accept `A | Array<A>`.
@@ -450,6 +478,8 @@ export const ensure = <A>(self: ReadonlyArray<A> | A): Array<A> => Array.isArray
 /**
  * Converts a record into an array of `[key, value]` tuples.
  *
+ * **Details**
+ *
  * - Key order follows `Object.entries` semantics.
  * - Returns an empty array for an empty record.
  *
@@ -489,6 +519,8 @@ export const fromOption: <A>(self: Option.Option<A>) => Array<A> = Option.toArra
 /**
  * Pattern-matches on an array, handling empty and non-empty cases separately.
  *
+ * **When to use**
+ *
  * - Use when you need to branch on whether an array has elements.
  * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
  * - Dual: data-first or data-last.
@@ -516,6 +548,8 @@ export const match: {
   /**
    * Pattern-matches on an array, handling empty and non-empty cases separately.
    *
+   * **When to use**
+   *
    * - Use when you need to branch on whether an array has elements.
    * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
    * - Dual: data-first or data-last.
@@ -548,6 +582,8 @@ export const match: {
   /**
    * Pattern-matches on an array, handling empty and non-empty cases separately.
    *
+   * **When to use**
+   *
    * - Use when you need to branch on whether an array has elements.
    * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
    * - Dual: data-first or data-last.
@@ -590,6 +626,8 @@ export const match: {
  * Pattern-matches on an array from the left, providing the first element and
  * the remaining elements separately.
  *
+ * **Details**
+ *
  * - `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
  * - Use when you want to process the first element differently from the rest.
  *
@@ -617,6 +655,8 @@ export const matchLeft: {
    * Pattern-matches on an array from the left, providing the first element and
    * the remaining elements separately.
    *
+   * **Details**
+   *
    * - `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
    * - Use when you want to process the first element differently from the rest.
    *
@@ -649,6 +689,8 @@ export const matchLeft: {
    * Pattern-matches on an array from the left, providing the first element and
    * the remaining elements separately.
    *
+   * **Details**
+   *
    * - `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
    * - Use when you want to process the first element differently from the rest.
    *
@@ -690,6 +732,8 @@ export const matchLeft: {
  * Pattern-matches on an array from the right, providing all elements except the
  * last and the last element separately.
  *
+ * **Details**
+ *
  * - `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
  * - Use when you want to process the last element differently from the rest.
  *
@@ -717,6 +761,8 @@ export const matchRight: {
    * Pattern-matches on an array from the right, providing all elements except the
    * last and the last element separately.
    *
+   * **Details**
+   *
    * - `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
    * - Use when you want to process the last element differently from the rest.
    *
@@ -749,6 +795,8 @@ export const matchRight: {
    * Pattern-matches on an array from the right, providing all elements except the
    * last and the last element separately.
    *
+   * **Details**
+   *
    * - `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
    * - Use when you want to process the last element differently from the rest.
    *
@@ -792,6 +840,8 @@ export const matchRight: {
 /**
  * Adds a single element to the front of an iterable, returning a `NonEmptyArray`.
  *
+ * **Details**
+ *
  * - Always returns a non-empty array.
  * - Does not mutate the input.
  *
@@ -814,6 +864,8 @@ export const prepend: {
   /**
    * Adds a single element to the front of an iterable, returning a `NonEmptyArray`.
    *
+   * **Details**
+   *
    * - Always returns a non-empty array.
    * - Does not mutate the input.
    *
@@ -836,6 +888,8 @@ export const prepend: {
   /**
    * Adds a single element to the front of an iterable, returning a `NonEmptyArray`.
    *
+   * **Details**
+   *
    * - Always returns a non-empty array.
    * - Does not mutate the input.
    *
@@ -860,6 +914,8 @@ export const prepend: {
 /**
  * Prepends all elements from a prefix iterable to the front of an array.
  *
+ * **Details**
+ *
  * - If either input is non-empty, the result is a `NonEmptyArray`.
  * - Does not mutate the input.
  *
@@ -882,6 +938,8 @@ export const prependAll: {
   /**
    * Prepends all elements from a prefix iterable to the front of an array.
    *
+   * **Details**
+   *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
    * - Does not mutate the input.
    *
@@ -904,6 +962,8 @@ export const prependAll: {
   /**
    * Prepends all elements from a prefix iterable to the front of an array.
    *
+   * **Details**
+   *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
    * - Does not mutate the input.
    *
@@ -926,6 +986,8 @@ export const prependAll: {
   /**
    * Prepends all elements from a prefix iterable to the front of an array.
    *
+   * **Details**
+   *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
    * - Does not mutate the input.
    *
@@ -948,6 +1010,8 @@ export const prependAll: {
   /**
    * Prepends all elements from a prefix iterable to the front of an array.
    *
+   * **Details**
+   *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
    * - Does not mutate the input.
    *
@@ -975,6 +1039,8 @@ export const prependAll: {
 /**
  * Adds a single element to the end of an iterable, returning a `NonEmptyArray`.
  *
+ * **Details**
+ *
  * - Always returns a non-empty array.
  * - Does not mutate the input.
  *
@@ -997,6 +1063,8 @@ export const append: {
   /**
    * Adds a single element to the end of an iterable, returning a `NonEmptyArray`.
    *
+   * **Details**
+   *
    * - Always returns a non-empty array.
    * - Does not mutate the input.
    *
@@ -1019,6 +1087,8 @@ export const append: {
   /**
    * Adds a single element to the end of an iterable, returning a `NonEmptyArray`.
    *
+   * **Details**
+   *
    * - Always returns a non-empty array.
    * - Does not mutate the input.
    *
@@ -1043,6 +1113,8 @@ export const append: {
 /**
  * Concatenates two iterables into a single array.
  *
+ * **Details**
+ *
  * - If either input is non-empty, the result is a `NonEmptyArray`.
  * - Does not mutate the inputs.
  *
@@ -1065,6 +1137,8 @@ export const appendAll: {
   /**
    * Concatenates two iterables into a single array.
    *
+   * **Details**
+   *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
    * - Does not mutate the inputs.
    *
@@ -1087,6 +1161,8 @@ export const appendAll: {
   /**
    * Concatenates two iterables into a single array.
    *
+   * **Details**
+   *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
    * - Does not mutate the inputs.
    *
@@ -1109,6 +1185,8 @@ export const appendAll: {
   /**
    * Concatenates two iterables into a single array.
    *
+   * **Details**
+   *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
    * - Does not mutate the inputs.
    *
@@ -1131,6 +1209,8 @@ export const appendAll: {
   /**
    * Concatenates two iterables into a single array.
    *
+   * **Details**
+   *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
    * - Does not mutate the inputs.
    *
@@ -1158,6 +1238,8 @@ export const appendAll: {
 /**
  * Left-to-right fold that keeps every intermediate accumulator value.
  *
+ * **Details**
+ *
  * - The output length is `input.length + 1` (starts with the initial value).
  * - Always returns a `NonEmptyArray` because the initial value is included.
  * - Use {@link reduce} if you only need the final accumulated value.
@@ -1181,6 +1263,8 @@ export const scan: {
   /**
    * Left-to-right fold that keeps every intermediate accumulator value.
    *
+   * **Details**
+   *
    * - The output length is `input.length + 1` (starts with the initial value).
    * - Always returns a `NonEmptyArray` because the initial value is included.
    * - Use {@link reduce} if you only need the final accumulated value.
@@ -1204,6 +1288,8 @@ export const scan: {
   /**
    * Left-to-right fold that keeps every intermediate accumulator value.
    *
+   * **Details**
+   *
    * - The output length is `input.length + 1` (starts with the initial value).
    * - Always returns a `NonEmptyArray` because the initial value is included.
    * - Use {@link reduce} if you only need the final accumulated value.
@@ -1237,6 +1323,8 @@ export const scan: {
 /**
  * Right-to-left fold that keeps every intermediate accumulator value.
  *
+ * **Details**
+ *
  * - The output length is `input.length + 1` (ends with the initial value).
  * - Always returns a `NonEmptyArray`.
  *
@@ -1259,6 +1347,8 @@ export const scanRight: {
   /**
    * Right-to-left fold that keeps every intermediate accumulator value.
    *
+   * **Details**
+   *
    * - The output length is `input.length + 1` (ends with the initial value).
    * - Always returns a `NonEmptyArray`.
    *
@@ -1281,6 +1371,8 @@ export const scanRight: {
   /**
    * Right-to-left fold that keeps every intermediate accumulator value.
    *
+   * **Details**
+   *
    * - The output length is `input.length + 1` (ends with the initial value).
    * - Always returns a `NonEmptyArray`.
    *
@@ -1313,6 +1405,8 @@ export const scanRight: {
 /**
  * Tests whether a value is an `Array`.
  *
+ * **Details**
+ *
  * - Acts as a type guard narrowing the input to `Array<unknown>`.
  * - Delegates to `globalThis.Array.isArray`.
  *
@@ -1335,6 +1429,8 @@ export const isArray: {
   /**
    * Tests whether a value is an `Array`.
    *
+   * **Details**
+   *
    * - Acts as a type guard narrowing the input to `Array<unknown>`.
    * - Delegates to `globalThis.Array.isArray`.
    *
@@ -1357,6 +1453,8 @@ export const isArray: {
   /**
    * Tests whether a value is an `Array`.
    *
+   * **Details**
+   *
    * - Acts as a type guard narrowing the input to `Array<unknown>`.
    * - Delegates to `globalThis.Array.isArray`.
    *
@@ -1488,6 +1586,8 @@ const clamp = <A>(i: number, as: ReadonlyArray<A>): number => Math.floor(Math.mi
  * Safely reads an element at the given index, returning `Option.some` or
  * `Option.none` if the index is out of bounds.
  *
+ * **Details**
+ *
  * - The index is floored to an integer.
  * - Never throws.
  *
@@ -1512,6 +1612,8 @@ export const get: {
    * Safely reads an element at the given index, returning `Option.some` or
    * `Option.none` if the index is out of bounds.
    *
+   * **Details**
+   *
    * - The index is floored to an integer.
    * - Never throws.
    *
@@ -1536,6 +1638,8 @@ export const get: {
    * Safely reads an element at the given index, returning `Option.some` or
    * `Option.none` if the index is out of bounds.
    *
+   * **Details**
+   *
    * - The index is floored to an integer.
    * - Never throws.
    *
@@ -1564,6 +1668,8 @@ export const get: {
 /**
  * Reads an element at the given index, throwing if the index is out of bounds.
  *
+ * **Details**
+ *
  * - Throws an `Error` with the message `"Index out of bounds: <i>"`.
  * - Prefer {@link get} for safe access.
  *
@@ -1585,6 +1691,8 @@ export const getUnsafe: {
   /**
    * Reads an element at the given index, throwing if the index is out of bounds.
    *
+   * **Details**
+   *
    * - Throws an `Error` with the message `"Index out of bounds: <i>"`.
    * - Prefer {@link get} for safe access.
    *
@@ -1606,6 +1714,8 @@ export const getUnsafe: {
   /**
    * Reads an element at the given index, throwing if the index is out of bounds.
    *
+   * **Details**
+   *
    * - Throws an `Error` with the message `"Index out of bounds: <i>"`.
    * - Prefer {@link get} for safe access.
    *
@@ -1635,6 +1745,8 @@ export const getUnsafe: {
 /**
  * Splits a non-empty array into its first element and the remaining elements.
  *
+ * **Details**
+ *
  * - Returns a tuple `[head, tail]`.
  * - Requires a `NonEmptyReadonlyArray`.
  *
@@ -1662,6 +1774,8 @@ export const unprepend = <A>(
  * Splits a non-empty array into all elements except the last, and the last
  * element.
  *
+ * **Details**
+ *
  * - Returns a tuple `[init, last]`.
  * - Requires a `NonEmptyReadonlyArray`.
  *
@@ -1769,6 +1883,8 @@ export const lastNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): A => self[self.
 /**
  * Returns all elements except the first, wrapped in an `Option`.
  *
+ * **Details**
+ *
  * - Allocates a new array via `slice(1)`.
  * - Returns `Option.none()` for empty inputs.
  *
@@ -1814,6 +1930,8 @@ export const tailNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): Array<A> => sel
 /**
  * Returns all elements except the last, wrapped in an `Option`.
  *
+ * **Details**
+ *
  * - Allocates a new array via `slice(0, -1)`.
  * - Returns `Option.none()` for empty inputs.
  *
@@ -1859,6 +1977,8 @@ export const initNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): Array<A> => sel
 /**
  * Keeps the first `n` elements, creating a new array.
  *
+ * **Details**
+ *
  * - `n` is clamped to `[0, length]`.
  * - Returns an empty array when `n <= 0`.
  *
@@ -1881,6 +2001,8 @@ export const take: {
   /**
    * Keeps the first `n` elements, creating a new array.
    *
+   * **Details**
+   *
    * - `n` is clamped to `[0, length]`.
    * - Returns an empty array when `n <= 0`.
    *
@@ -1903,6 +2025,8 @@ export const take: {
   /**
    * Keeps the first `n` elements, creating a new array.
    *
+   * **Details**
+   *
    * - `n` is clamped to `[0, length]`.
    * - Returns an empty array when `n <= 0`.
    *
@@ -1930,6 +2054,8 @@ export const take: {
 /**
  * Keeps the last `n` elements, creating a new array.
  *
+ * **Details**
+ *
  * - `n` is clamped to `[0, length]`.
  * - Returns an empty array when `n <= 0`.
  *
@@ -1951,6 +2077,8 @@ export const takeRight: {
   /**
    * Keeps the last `n` elements, creating a new array.
    *
+   * **Details**
+   *
    * - `n` is clamped to `[0, length]`.
    * - Returns an empty array when `n <= 0`.
    *
@@ -1972,6 +2100,8 @@ export const takeRight: {
   /**
    * Keeps the last `n` elements, creating a new array.
    *
+   * **Details**
+   *
    * - `n` is clamped to `[0, length]`.
    * - Returns an empty array when `n <= 0`.
    *
@@ -2000,6 +2130,8 @@ export const takeRight: {
  * Takes elements from the start while the predicate holds, stopping at the
  * first element that fails.
  *
+ * **Details**
+ *
  * - Supports refinements for type narrowing.
  * - The predicate receives `(element, index)`.
  *
@@ -2023,6 +2155,8 @@ export const takeWhile: {
    * Takes elements from the start while the predicate holds, stopping at the
    * first element that fails.
    *
+   * **Details**
+   *
    * - Supports refinements for type narrowing.
    * - The predicate receives `(element, index)`.
    *
@@ -2046,6 +2180,8 @@ export const takeWhile: {
    * Takes elements from the start while the predicate holds, stopping at the
    * first element that fails.
    *
+   * **Details**
+   *
    * - Supports refinements for type narrowing.
    * - The predicate receives `(element, index)`.
    *
@@ -2069,6 +2205,8 @@ export const takeWhile: {
    * Takes elements from the start while the predicate holds, stopping at the
    * first element that fails.
    *
+   * **Details**
+   *
    * - Supports refinements for type narrowing.
    * - The predicate receives `(element, index)`.
    *
@@ -2092,6 +2230,8 @@ export const takeWhile: {
    * Takes elements from the start while the predicate holds, stopping at the
    * first element that fails.
    *
+   * **Details**
+   *
    * - Supports refinements for type narrowing.
    * - The predicate receives `(element, index)`.
    *
@@ -2127,6 +2267,8 @@ export const takeWhile: {
 /**
  * Takes elements from the start while a `Filter` succeeds, collecting transformed values.
  *
+ * **Details**
+ *
  * - The filter receives `(element, index)`.
  * - Stops at the first filter failure.
  *
@@ -2137,6 +2279,8 @@ export const takeWhileFilter: {
   /**
    * Takes elements from the start while a `Filter` succeeds, collecting transformed values.
    *
+   * **Details**
+   *
    * - The filter receives `(element, index)`.
    * - Stops at the first filter failure.
    *
@@ -2147,6 +2291,8 @@ export const takeWhileFilter: {
   /**
    * Takes elements from the start while a `Filter` succeeds, collecting transformed values.
    *
+   * **Details**
+   *
    * - The filter receives `(element, index)`.
    * - Stops at the first filter failure.
    *
@@ -2186,6 +2332,8 @@ const spanIndex = <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean
  * Splits an iterable into two arrays: the longest prefix where the predicate
  * holds, and the remaining elements.
  *
+ * **Details**
+ *
  * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
  *   (single pass).
  * - Supports refinements for type narrowing of the prefix.
@@ -2210,6 +2358,8 @@ export const span: {
    * Splits an iterable into two arrays: the longest prefix where the predicate
    * holds, and the remaining elements.
    *
+   * **Details**
+   *
    * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
    *   (single pass).
    * - Supports refinements for type narrowing of the prefix.
@@ -2234,6 +2384,8 @@ export const span: {
    * Splits an iterable into two arrays: the longest prefix where the predicate
    * holds, and the remaining elements.
    *
+   * **Details**
+   *
    * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
    *   (single pass).
    * - Supports refinements for type narrowing of the prefix.
@@ -2258,6 +2410,8 @@ export const span: {
    * Splits an iterable into two arrays: the longest prefix where the predicate
    * holds, and the remaining elements.
    *
+   * **Details**
+   *
    * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
    *   (single pass).
    * - Supports refinements for type narrowing of the prefix.
@@ -2282,6 +2436,8 @@ export const span: {
    * Splits an iterable into two arrays: the longest prefix where the predicate
    * holds, and the remaining elements.
    *
+   * **Details**
+   *
    * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
    *   (single pass).
    * - Supports refinements for type narrowing of the prefix.
@@ -2313,6 +2469,8 @@ export const span: {
 /**
  * Removes the first `n` elements, creating a new array.
  *
+ * **Details**
+ *
  * - `n` is clamped to `[0, length]`.
  * - Returns a copy of the full array when `n <= 0`.
  *
@@ -2335,6 +2493,8 @@ export const drop: {
   /**
    * Removes the first `n` elements, creating a new array.
    *
+   * **Details**
+   *
    * - `n` is clamped to `[0, length]`.
    * - Returns a copy of the full array when `n <= 0`.
    *
@@ -2357,6 +2517,8 @@ export const drop: {
   /**
    * Removes the first `n` elements, creating a new array.
    *
+   * **Details**
+   *
    * - `n` is clamped to `[0, length]`.
    * - Returns a copy of the full array when `n <= 0`.
    *
@@ -2384,6 +2546,8 @@ export const drop: {
 /**
  * Removes the last `n` elements, creating a new array.
  *
+ * **Details**
+ *
  * - `n` is clamped to `[0, length]`.
  *
  * **Example** (Dropping from the end)
@@ -2404,6 +2568,8 @@ export const dropRight: {
   /**
    * Removes the last `n` elements, creating a new array.
    *
+   * **Details**
+   *
    * - `n` is clamped to `[0, length]`.
    *
    * **Example** (Dropping from the end)
@@ -2424,6 +2590,8 @@ export const dropRight: {
   /**
    * Removes the last `n` elements, creating a new array.
    *
+   * **Details**
+   *
    * - `n` is clamped to `[0, length]`.
    *
    * **Example** (Dropping from the end)
@@ -2449,6 +2617,8 @@ export const dropRight: {
 /**
  * Drops elements from the start while the predicate holds, returning the rest.
  *
+ * **Details**
+ *
  * - The predicate receives `(element, index)`.
  *
  * **Example** (Dropping while condition holds)
@@ -2469,6 +2639,8 @@ export const dropWhile: {
   /**
    * Drops elements from the start while the predicate holds, returning the rest.
    *
+   * **Details**
+   *
    * - The predicate receives `(element, index)`.
    *
    * **Example** (Dropping while condition holds)
@@ -2489,6 +2661,8 @@ export const dropWhile: {
   /**
    * Drops elements from the start while the predicate holds, returning the rest.
    *
+   * **Details**
+   *
    * - The predicate receives `(element, index)`.
    *
    * **Example** (Dropping while condition holds)
@@ -2521,6 +2695,8 @@ export const dropWhile: {
 /**
  * Drops elements from the start while a `Filter` succeeds.
  *
+ * **Details**
+ *
  * - The filter receives `(element, index)`.
  * - Returns the remaining original elements after the first filter failure.
  *
@@ -2531,6 +2707,8 @@ export const dropWhileFilter: {
   /**
    * Drops elements from the start while a `Filter` succeeds.
    *
+   * **Details**
+   *
    * - The filter receives `(element, index)`.
    * - Returns the remaining original elements after the first filter failure.
    *
@@ -2541,6 +2719,8 @@ export const dropWhileFilter: {
   /**
    * Drops elements from the start while a `Filter` succeeds.
    *
+   * **Details**
+   *
    * - The filter receives `(element, index)`.
    * - Returns the remaining original elements after the first filter failure.
    *
@@ -2702,6 +2882,8 @@ export const findLastIndex: {
  * Returns the first element matching a predicate, refinement, or mapping
  * function, wrapped in `Option`.
  *
+ * **Details**
+ *
  * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
  *   `(a, i) => Option<B>` for simultaneous find-and-transform.
  * - Returns `Option.none()` if no element matches.
@@ -2726,6 +2908,8 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
    *   `(a, i) => Option<B>` for simultaneous find-and-transform.
    * - Returns `Option.none()` if no element matches.
@@ -2750,6 +2934,8 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
    *   `(a, i) => Option<B>` for simultaneous find-and-transform.
    * - Returns `Option.none()` if no element matches.
@@ -2774,6 +2960,8 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
    *   `(a, i) => Option<B>` for simultaneous find-and-transform.
    * - Returns `Option.none()` if no element matches.
@@ -2798,6 +2986,8 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
    *   `(a, i) => Option<B>` for simultaneous find-and-transform.
    * - Returns `Option.none()` if no element matches.
@@ -2822,6 +3012,8 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
    *   `(a, i) => Option<B>` for simultaneous find-and-transform.
    * - Returns `Option.none()` if no element matches.
@@ -2846,6 +3038,8 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
    *   `(a, i) => Option<B>` for simultaneous find-and-transform.
    * - Returns `Option.none()` if no element matches.
@@ -2872,6 +3066,8 @@ export const findFirst: {
  * Returns the first selected value together with its index, wrapped in an
  * `Option`.
  *
+ * **Details**
+ *
  * Accepts a predicate, a refinement, or a function returning `Option`. For an
  * `Option`-returning function, returns `[mappedValue, index]` for the first
  * `Some`, or `Option.none()` if no element is selected.
@@ -2895,6 +3091,8 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **Details**
+   *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
    * `Option`-returning function, returns `[mappedValue, index]` for the first
    * `Some`, or `Option.none()` if no element is selected.
@@ -2918,6 +3116,8 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **Details**
+   *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
    * `Option`-returning function, returns `[mappedValue, index]` for the first
    * `Some`, or `Option.none()` if no element is selected.
@@ -2941,6 +3141,8 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **Details**
+   *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
    * `Option`-returning function, returns `[mappedValue, index]` for the first
    * `Some`, or `Option.none()` if no element is selected.
@@ -2964,6 +3166,8 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **Details**
+   *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
    * `Option`-returning function, returns `[mappedValue, index]` for the first
    * `Some`, or `Option.none()` if no element is selected.
@@ -2987,6 +3191,8 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **Details**
+   *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
    * `Option`-returning function, returns `[mappedValue, index]` for the first
    * `Some`, or `Option.none()` if no element is selected.
@@ -3010,6 +3216,8 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **Details**
+   *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
    * `Option`-returning function, returns `[mappedValue, index]` for the first
    * `Some`, or `Option.none()` if no element is selected.
@@ -3057,6 +3265,8 @@ export const findFirstWithIndex: {
  * Returns the last element matching a predicate, refinement, or mapping
  * function, wrapped in `Option`.
  *
+ * **Details**
+ *
  * - Searches from the end of the array.
  * - Returns `Option.none()` if no element matches.
  *
@@ -3079,6 +3289,8 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Searches from the end of the array.
    * - Returns `Option.none()` if no element matches.
    *
@@ -3101,6 +3313,8 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Searches from the end of the array.
    * - Returns `Option.none()` if no element matches.
    *
@@ -3123,6 +3337,8 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Searches from the end of the array.
    * - Returns `Option.none()` if no element matches.
    *
@@ -3145,6 +3361,8 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Searches from the end of the array.
    * - Returns `Option.none()` if no element matches.
    *
@@ -3167,6 +3385,8 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Searches from the end of the array.
    * - Returns `Option.none()` if no element matches.
    *
@@ -3189,6 +3409,8 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **Details**
+   *
    * - Searches from the end of the array.
    * - Returns `Option.none()` if no element matches.
    *
@@ -3235,6 +3457,8 @@ export const findLast: {
  * Inserts an element at the specified index, returning a new `NonEmptyArray`
  * wrapped in an `Option`.
  *
+ * **Details**
+ *
  * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
  * - Does not mutate the input.
  *
@@ -3257,6 +3481,8 @@ export const insertAt: {
    * Inserts an element at the specified index, returning a new `NonEmptyArray`
    * wrapped in an `Option`.
    *
+   * **Details**
+   *
    * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
    * - Does not mutate the input.
    *
@@ -3279,6 +3505,8 @@ export const insertAt: {
    * Inserts an element at the specified index, returning a new `NonEmptyArray`
    * wrapped in an `Option`.
    *
+   * **Details**
+   *
    * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
    * - Does not mutate the input.
    *
@@ -3310,6 +3538,8 @@ export const insertAt: {
  * Replaces the element at the specified index with a new value, returning the
  * updated array in `Option.some`.
  *
+ * **Details**
+ *
  * - Returns `Option.none()` when the index is out of bounds.
  * - Does not mutate the input.
  *
@@ -3332,6 +3562,8 @@ export const replace: {
    * Replaces the element at the specified index with a new value, returning the
    * updated array in `Option.some`.
    *
+   * **Details**
+   *
    * - Returns `Option.none()` when the index is out of bounds.
    * - Does not mutate the input.
    *
@@ -3356,6 +3588,8 @@ export const replace: {
    * Replaces the element at the specified index with a new value, returning the
    * updated array in `Option.some`.
    *
+   * **Details**
+   *
    * - Returns `Option.none()` when the index is out of bounds.
    * - Does not mutate the input.
    *
@@ -3383,6 +3617,8 @@ export const replace: {
  * Applies a function to the element at the specified index, returning the
  * updated array in `Option.some`.
  *
+ * **Details**
+ *
  * - Returns `Option.none()` when the index is out of bounds.
  * - Does not mutate the input.
  *
@@ -3407,6 +3643,8 @@ export const modify: {
    * Applies a function to the element at the specified index, returning the
    * updated array in `Option.some`.
    *
+   * **Details**
+   *
    * - Returns `Option.none()` when the index is out of bounds.
    * - Does not mutate the input.
    *
@@ -3431,6 +3669,8 @@ export const modify: {
    * Applies a function to the element at the specified index, returning the
    * updated array in `Option.some`.
    *
+   * **Details**
+   *
    * - Returns `Option.none()` when the index is out of bounds.
    * - Does not mutate the input.
    *
@@ -3466,6 +3706,8 @@ export const modify: {
  * Removes the element at the specified index, returning a new array. If the
  * index is out of bounds, returns a copy of the original.
  *
+ * **Details**
+ *
  * - Does not mutate the input.
  *
  * **Example** (Removing an element)
@@ -3488,6 +3730,8 @@ export const remove: {
    * Removes the element at the specified index, returning a new array. If the
    * index is out of bounds, returns a copy of the original.
    *
+   * **Details**
+   *
    * - Does not mutate the input.
    *
    * **Example** (Removing an element)
@@ -3510,6 +3754,8 @@ export const remove: {
    * Removes the element at the specified index, returning a new array. If the
    * index is out of bounds, returns a copy of the original.
    *
+   * **Details**
+   *
    * - Does not mutate the input.
    *
    * **Example** (Removing an element)
@@ -3540,6 +3786,8 @@ export const remove: {
 /**
  * Reverses an iterable into a new array.
  *
+ * **Details**
+ *
  * - Does not mutate the input.
  * - Preserves `NonEmptyArray` in the return type.
  *
@@ -3562,6 +3810,8 @@ export const reverse = <S extends Iterable<any>>(
 /**
  * Sorts an array by the given `Order`, returning a new array.
  *
+ * **Details**
+ *
  * - Does not mutate the input.
  * - Preserves `NonEmptyArray` in the return type.
  * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
@@ -3585,6 +3835,8 @@ export const sort: {
   /**
    * Sorts an array by the given `Order`, returning a new array.
    *
+   * **Details**
+   *
    * - Does not mutate the input.
    * - Preserves `NonEmptyArray` in the return type.
    * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
@@ -3608,6 +3860,8 @@ export const sort: {
   /**
    * Sorts an array by the given `Order`, returning a new array.
    *
+   * **Details**
+   *
    * - Does not mutate the input.
    * - Preserves `NonEmptyArray` in the return type.
    * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
@@ -3631,6 +3885,8 @@ export const sort: {
   /**
    * Sorts an array by the given `Order`, returning a new array.
    *
+   * **Details**
+   *
    * - Does not mutate the input.
    * - Preserves `NonEmptyArray` in the return type.
    * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
@@ -3661,6 +3917,8 @@ export const sort: {
  * Sorts an array by a derived key using a mapping function and an `Order` for
  * that key.
  *
+ * **Details**
+ *
  * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
  * - Does not mutate the input.
  *
@@ -3684,6 +3942,8 @@ export const sortWith: {
    * Sorts an array by a derived key using a mapping function and an `Order` for
    * that key.
    *
+   * **Details**
+   *
    * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
    * - Does not mutate the input.
    *
@@ -3707,6 +3967,8 @@ export const sortWith: {
    * Sorts an array by a derived key using a mapping function and an `Order` for
    * that key.
    *
+   * **Details**
+   *
    * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
    * - Does not mutate the input.
    *
@@ -3730,6 +3992,8 @@ export const sortWith: {
    * Sorts an array by a derived key using a mapping function and an `Order` for
    * that key.
    *
+   * **Details**
+   *
    * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
    * - Does not mutate the input.
    *
@@ -3759,6 +4023,8 @@ export const sortWith: {
  * Sorts an array by multiple `Order`s applied in sequence: the first order is
  * used first; ties are broken by the second order, and so on.
  *
+ * **Details**
+ *
  * - Data-last only (returns a function).
  * - Preserves `NonEmptyArray` in the return type.
  *
@@ -3809,6 +4075,8 @@ export const sortBy = <S extends Iterable<any>>(
  * Pairs elements from two iterables by position. If the iterables differ in
  * length, the extra elements from the longer one are discarded.
  *
+ * **Details**
+ *
  * - Returns `NonEmptyArray` when both inputs are non-empty.
  *
  * **Example** (Zipping two arrays)
@@ -3830,6 +4098,8 @@ export const zip: {
    * Pairs elements from two iterables by position. If the iterables differ in
    * length, the extra elements from the longer one are discarded.
    *
+   * **Details**
+   *
    * - Returns `NonEmptyArray` when both inputs are non-empty.
    *
    * **Example** (Zipping two arrays)
@@ -3851,6 +4121,8 @@ export const zip: {
    * Pairs elements from two iterables by position. If the iterables differ in
    * length, the extra elements from the longer one are discarded.
    *
+   * **Details**
+   *
    * - Returns `NonEmptyArray` when both inputs are non-empty.
    *
    * **Example** (Zipping two arrays)
@@ -3872,6 +4144,8 @@ export const zip: {
    * Pairs elements from two iterables by position. If the iterables differ in
    * length, the extra elements from the longer one are discarded.
    *
+   * **Details**
+   *
    * - Returns `NonEmptyArray` when both inputs are non-empty.
    *
    * **Example** (Zipping two arrays)
@@ -3893,6 +4167,8 @@ export const zip: {
    * Pairs elements from two iterables by position. If the iterables differ in
    * length, the extra elements from the longer one are discarded.
    *
+   * **Details**
+   *
    * - Returns `NonEmptyArray` when both inputs are non-empty.
    *
    * **Example** (Zipping two arrays)
@@ -4060,6 +4336,8 @@ export const unzip: <S extends Iterable<readonly [any, any]>>(
 /**
  * Places a separator element between every pair of elements.
  *
+ * **Details**
+ *
  * - Preserves `NonEmptyArray` in the return type.
  * - An empty input produces an empty result.
  *
@@ -4080,6 +4358,8 @@ export const intersperse: {
   /**
    * Places a separator element between every pair of elements.
    *
+   * **Details**
+   *
    * - Preserves `NonEmptyArray` in the return type.
    * - An empty input produces an empty result.
    *
@@ -4100,6 +4380,8 @@ export const intersperse: {
   /**
    * Places a separator element between every pair of elements.
    *
+   * **Details**
+   *
    * - Preserves `NonEmptyArray` in the return type.
    * - An empty input produces an empty result.
    *
@@ -4120,6 +4402,8 @@ export const intersperse: {
   /**
    * Places a separator element between every pair of elements.
    *
+   * **Details**
+   *
    * - Preserves `NonEmptyArray` in the return type.
    * - An empty input produces an empty result.
    *
@@ -4403,6 +4687,8 @@ export const setLastNonEmpty: {
  * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
  * rotates left.
  *
+ * **Details**
+ *
  * - `n` is rounded to the nearest integer before rotating.
  * - Preserves `NonEmptyArray` in the return type.
  * - Returns a copy for empty arrays or when the normalized rotation is `0`.
@@ -4423,6 +4709,8 @@ export const rotate: {
    * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
    * rotates left.
    *
+   * **Details**
+   *
    * - `n` is rounded to the nearest integer before rotating.
    * - Preserves `NonEmptyArray` in the return type.
    * - Returns a copy for empty arrays or when the normalized rotation is `0`.
@@ -4443,6 +4731,8 @@ export const rotate: {
    * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
    * rotates left.
    *
+   * **Details**
+   *
    * - `n` is rounded to the nearest integer before rotating.
    * - Preserves `NonEmptyArray` in the return type.
    * - Returns a copy for empty arrays or when the normalized rotation is `0`.
@@ -4463,6 +4753,8 @@ export const rotate: {
    * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
    * rotates left.
    *
+   * **Details**
+   *
    * - `n` is rounded to the nearest integer before rotating.
    * - Preserves `NonEmptyArray` in the return type.
    * - Returns a copy for empty arrays or when the normalized rotation is `0`.
@@ -4587,6 +4879,8 @@ export const contains: {
  * Repeatedly applies a function that consumes a prefix of the array and
  * produces a value plus the remaining elements, collecting the values.
  *
+ * **Details**
+ *
  * - The function receives a `NonEmptyReadonlyArray` and returns
  *   `[value, rest]`.
  * - Continues until the remaining array is empty.
@@ -4615,6 +4909,8 @@ export const chop: {
    * Repeatedly applies a function that consumes a prefix of the array and
    * produces a value plus the remaining elements, collecting the values.
    *
+   * **Details**
+   *
    * - The function receives a `NonEmptyReadonlyArray` and returns
    *   `[value, rest]`.
    * - Continues until the remaining array is empty.
@@ -4645,6 +4941,8 @@ export const chop: {
    * Repeatedly applies a function that consumes a prefix of the array and
    * produces a value plus the remaining elements, collecting the values.
    *
+   * **Details**
+   *
    * - The function receives a `NonEmptyReadonlyArray` and returns
    *   `[value, rest]`.
    * - Continues until the remaining array is empty.
@@ -4676,6 +4974,8 @@ export const chop: {
    * Repeatedly applies a function that consumes a prefix of the array and
    * produces a value plus the remaining elements, collecting the values.
    *
+   * **Details**
+   *
    * - The function receives a `NonEmptyReadonlyArray` and returns
    *   `[value, rest]`.
    * - Continues until the remaining array is empty.
@@ -4725,6 +5025,8 @@ export const chop: {
 /**
  * Splits an iterable into two arrays at the given index.
  *
+ * **Details**
+ *
  * - `n` can be `0` (all elements in the second array).
  * - `n` is floored to an integer.
  *
@@ -4746,6 +5048,8 @@ export const splitAt: {
   /**
    * Splits an iterable into two arrays at the given index.
    *
+   * **Details**
+   *
    * - `n` can be `0` (all elements in the second array).
    * - `n` is floored to an integer.
    *
@@ -4767,6 +5071,8 @@ export const splitAt: {
   /**
    * Splits an iterable into two arrays at the given index.
    *
+   * **Details**
+   *
    * - `n` can be `0` (all elements in the second array).
    * - `n` is floored to an integer.
    *
@@ -4864,6 +5170,8 @@ export const splitAtNonEmpty: {
 /**
  * Splits an iterable into `n` roughly equal-sized chunks.
  *
+ * **Details**
+ *
  * - Uses `chunksOf(ceil(length / n))` internally.
  * - The last chunk may be shorter.
  *
@@ -4884,6 +5192,8 @@ export const split: {
   /**
    * Splits an iterable into `n` roughly equal-sized chunks.
    *
+   * **Details**
+   *
    * - Uses `chunksOf(ceil(length / n))` internally.
    * - The last chunk may be shorter.
    *
@@ -4904,6 +5214,8 @@ export const split: {
   /**
    * Splits an iterable into `n` roughly equal-sized chunks.
    *
+   * **Details**
+   *
    * - Uses `chunksOf(ceil(length / n))` internally.
    * - The last chunk may be shorter.
    *
@@ -4992,6 +5304,8 @@ export const splitWhere: {
 /**
  * Creates a shallow copy of an array.
  *
+ * **Details**
+ *
  * - Preserves `NonEmptyArray` in the return type.
  * - Useful when you need a distinct reference (e.g. before mutating).
  *
@@ -5015,6 +5329,8 @@ export const copy: {
   /**
    * Creates a shallow copy of an array.
    *
+   * **Details**
+   *
    * - Preserves `NonEmptyArray` in the return type.
    * - Useful when you need a distinct reference (e.g. before mutating).
    *
@@ -5038,6 +5354,8 @@ export const copy: {
   /**
    * Creates a shallow copy of an array.
    *
+   * **Details**
+   *
    * - Preserves `NonEmptyArray` in the return type.
    * - Useful when you need a distinct reference (e.g. before mutating).
    *
@@ -5064,6 +5382,8 @@ export const copy: {
  * Pads or truncates an array to exactly `n` elements, filling with `fill`
  * if the array is shorter, or slicing if longer.
  *
+ * **Details**
+ *
  * - Returns an empty array when `n <= 0`.
  *
  * **Example** (Padding an array)
@@ -5085,6 +5405,8 @@ export const pad: {
    * Pads or truncates an array to exactly `n` elements, filling with `fill`
    * if the array is shorter, or slicing if longer.
    *
+   * **Details**
+   *
    * - Returns an empty array when `n <= 0`.
    *
    * **Example** (Padding an array)
@@ -5108,6 +5430,8 @@ export const pad: {
    * Pads or truncates an array to exactly `n` elements, filling with `fill`
    * if the array is shorter, or slicing if longer.
    *
+   * **Details**
+   *
    * - Returns an empty array when `n <= 0`.
    *
    * **Example** (Padding an array)
@@ -5139,6 +5463,8 @@ export const pad: {
  * Splits an iterable into chunks of length `n`. The last chunk may be shorter
  * if `n` does not evenly divide the length.
  *
+ * **Details**
+ *
  * - `chunksOf(n)([])` is `[]`, not `[[]]`.
  * - Each chunk is a `NonEmptyArray`.
  * - Preserves `NonEmptyArray` in the outer return type.
@@ -5162,6 +5488,8 @@ export const chunksOf: {
    * Splits an iterable into chunks of length `n`. The last chunk may be shorter
    * if `n` does not evenly divide the length.
    *
+   * **Details**
+   *
    * - `chunksOf(n)([])` is `[]`, not `[[]]`.
    * - Each chunk is a `NonEmptyArray`.
    * - Preserves `NonEmptyArray` in the outer return type.
@@ -5187,6 +5515,8 @@ export const chunksOf: {
    * Splits an iterable into chunks of length `n`. The last chunk may be shorter
    * if `n` does not evenly divide the length.
    *
+   * **Details**
+   *
    * - `chunksOf(n)([])` is `[]`, not `[[]]`.
    * - Each chunk is a `NonEmptyArray`.
    * - Preserves `NonEmptyArray` in the outer return type.
@@ -5210,6 +5540,8 @@ export const chunksOf: {
    * Splits an iterable into chunks of length `n`. The last chunk may be shorter
    * if `n` does not evenly divide the length.
    *
+   * **Details**
+   *
    * - `chunksOf(n)([])` is `[]`, not `[[]]`.
    * - Each chunk is a `NonEmptyArray`.
    * - Preserves `NonEmptyArray` in the outer return type.
@@ -5240,6 +5572,8 @@ export const chunksOf: {
 /**
  * Creates overlapping sliding windows of size `n`.
  *
+ * **Details**
+ *
  * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
  * - Each window is a tuple of exactly `n` elements.
  *
@@ -5261,6 +5595,8 @@ export const window: {
   /**
    * Creates overlapping sliding windows of size `n`.
    *
+   * **Details**
+   *
    * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
    * - Each window is a tuple of exactly `n` elements.
    *
@@ -5282,6 +5618,8 @@ export const window: {
   /**
    * Creates overlapping sliding windows of size `n`.
    *
+   * **Details**
+   *
    * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
    * - Each window is a tuple of exactly `n` elements.
    *
@@ -5314,6 +5652,8 @@ export const window: {
 /**
  * Groups consecutive equal elements using a custom equivalence function.
  *
+ * **Details**
+ *
  * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
  * - Requires a `NonEmptyReadonlyArray`.
  *
@@ -5336,6 +5676,8 @@ export const groupWith: {
   /**
    * Groups consecutive equal elements using a custom equivalence function.
    *
+   * **Details**
+   *
    * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
    * - Requires a `NonEmptyReadonlyArray`.
    *
@@ -5358,6 +5700,8 @@ export const groupWith: {
   /**
    * Groups consecutive equal elements using a custom equivalence function.
    *
+   * **Details**
+   *
    * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
    * - Requires a `NonEmptyReadonlyArray`.
    *
@@ -5402,6 +5746,8 @@ export const groupWith: {
 /**
  * Groups consecutive equal elements using `Equal.equivalence()`.
  *
+ * **Details**
+ *
  * - Only groups **adjacent** elements.
  *
  * **Example** (Grouping adjacent equal elements)
@@ -5426,6 +5772,8 @@ export const group: <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<NonEmpt
  * Groups elements into a record by a key-returning function. Each key maps
  * to a `NonEmptyArray` of elements that produced that key.
  *
+ * **Details**
+ *
  * - Unlike {@link group}/{@link groupWith}, elements do not need to be
  *   adjacent to be grouped together.
  * - Key function must return a `string` or `symbol`.
@@ -5457,6 +5805,8 @@ export const groupBy: {
    * Groups elements into a record by a key-returning function. Each key maps
    * to a `NonEmptyArray` of elements that produced that key.
    *
+   * **Details**
+   *
    * - Unlike {@link group}/{@link groupWith}, elements do not need to be
    *   adjacent to be grouped together.
    * - Key function must return a `string` or `symbol`.
@@ -5488,6 +5838,8 @@ export const groupBy: {
    * Groups elements into a record by a key-returning function. Each key maps
    * to a `NonEmptyArray` of elements that produced that key.
    *
+   * **Details**
+   *
    * - Unlike {@link group}/{@link groupWith}, elements do not need to be
    *   adjacent to be grouped together.
    * - Key function must return a `string` or `symbol`.
@@ -6140,6 +6492,8 @@ export declare namespace ReadonlyArray {
 /**
  * Transforms each element using a function, returning a new array.
  *
+ * **Details**
+ *
  * - The function receives `(element, index)`.
  * - Preserves `NonEmptyArray` in the return type.
  *
@@ -6160,6 +6514,8 @@ export const map: {
   /**
    * Transforms each element using a function, returning a new array.
    *
+   * **Details**
+   *
    * - The function receives `(element, index)`.
    * - Preserves `NonEmptyArray` in the return type.
    *
@@ -6180,6 +6536,8 @@ export const map: {
   /**
    * Transforms each element using a function, returning a new array.
    *
+   * **Details**
+   *
    * - The function receives `(element, index)`.
    * - Preserves `NonEmptyArray` in the return type.
    *
@@ -6202,6 +6560,8 @@ export const map: {
 /**
  * Maps each element to an array and flattens the results into a single array.
  *
+ * **Details**
+ *
  * - The function receives `(element, index)`.
  * - Returns `NonEmptyArray` when both input and mapped arrays are non-empty.
  *
@@ -6223,6 +6583,8 @@ export const flatMap: {
   /**
    * Maps each element to an array and flattens the results into a single array.
    *
+   * **Details**
+   *
    * - The function receives `(element, index)`.
    * - Returns `NonEmptyArray` when both input and mapped arrays are non-empty.
    *
@@ -6244,6 +6606,8 @@ export const flatMap: {
   /**
    * Maps each element to an array and flattens the results into a single array.
    *
+   * **Details**
+   *
    * - The function receives `(element, index)`.
    * - Returns `NonEmptyArray` when both input and mapped arrays are non-empty.
    *
@@ -6268,6 +6632,8 @@ export const flatMap: {
   /**
    * Maps each element to an array and flattens the results into a single array.
    *
+   * **Details**
+   *
    * - The function receives `(element, index)`.
    * - Returns `NonEmptyArray` when both input and mapped arrays are non-empty.
    *
@@ -6419,6 +6785,8 @@ export const getSuccesses = <T extends Iterable<Result.Result<any, any>>>(
 /**
  * Keeps transformed values for elements where a `Filter` succeeds.
  *
+ * **Details**
+ *
  * - The filter receives `(element, index)`.
  * - Failures are discarded.
  *
@@ -6440,6 +6808,8 @@ export const filterMap: {
   /**
    * Keeps transformed values for elements where a `Filter` succeeds.
    *
+   * **Details**
+   *
    * - The filter receives `(element, index)`.
    * - Failures are discarded.
    *
@@ -6461,6 +6831,8 @@ export const filterMap: {
   /**
    * Keeps transformed values for elements where a `Filter` succeeds.
    *
+   * **Details**
+   *
    * - The filter receives `(element, index)`.
    * - Failures are discarded.
    *
@@ -6494,6 +6866,8 @@ export const filterMap: {
 /**
  * Keeps only elements satisfying a predicate (or refinement).
  *
+ * **Details**
+ *
  * - The predicate receives `(element, index)`.
  * - Supports refinements for type narrowing.
  *
@@ -6514,6 +6888,8 @@ export const filter: {
   /**
    * Keeps only elements satisfying a predicate (or refinement).
    *
+   * **Details**
+   *
    * - The predicate receives `(element, index)`.
    * - Supports refinements for type narrowing.
    *
@@ -6534,6 +6910,8 @@ export const filter: {
   /**
    * Keeps only elements satisfying a predicate (or refinement).
    *
+   * **Details**
+   *
    * - The predicate receives `(element, index)`.
    * - Supports refinements for type narrowing.
    *
@@ -6554,6 +6932,8 @@ export const filter: {
   /**
    * Keeps only elements satisfying a predicate (or refinement).
    *
+   * **Details**
+   *
    * - The predicate receives `(element, index)`.
    * - Supports refinements for type narrowing.
    *
@@ -6574,6 +6954,8 @@ export const filter: {
   /**
    * Keeps only elements satisfying a predicate (or refinement).
    *
+   * **Details**
+   *
    * - The predicate receives `(element, index)`.
    * - Supports refinements for type narrowing.
    *
@@ -6608,6 +6990,8 @@ export const filter: {
 /**
  * Splits an iterable using a `Filter` into failures and successes.
  *
+ * **Details**
+ *
  * - Returns `[excluded, satisfying]`.
  * - The filter receives `(element, index)`.
  *
@@ -6632,6 +7016,8 @@ export const partition: {
   /**
    * Splits an iterable using a `Filter` into failures and successes.
    *
+   * **Details**
+   *
    * - Returns `[excluded, satisfying]`.
    * - The filter receives `(element, index)`.
    *
@@ -6656,6 +7042,8 @@ export const partition: {
   /**
    * Splits an iterable using a `Filter` into failures and successes.
    *
+   * **Details**
+   *
    * - Returns `[excluded, satisfying]`.
    * - The filter receives `(element, index)`.
    *
@@ -6701,6 +7089,8 @@ export const partition: {
 /**
  * Separates an iterable of `Result`s into failure values and success values.
  *
+ * **Details**
+ *
  * - Returns `[failures, successes]`.
  * - Equivalent to `partition(identity)`.
  *
@@ -6732,6 +7122,8 @@ export const separate: <T extends Iterable<Result.Result<any, any>>>(
 /**
  * Folds an iterable from left to right into a single value.
  *
+ * **Details**
+ *
  * - The function receives `(accumulator, element, index)`.
  *
  * **Example** (Summing an array)
@@ -6752,6 +7144,8 @@ export const reduce: {
   /**
    * Folds an iterable from left to right into a single value.
    *
+   * **Details**
+   *
    * - The function receives `(accumulator, element, index)`.
    *
    * **Example** (Summing an array)
@@ -6772,6 +7166,8 @@ export const reduce: {
   /**
    * Folds an iterable from left to right into a single value.
    *
+   * **Details**
+   *
    * - The function receives `(accumulator, element, index)`.
    *
    * **Example** (Summing an array)
@@ -6798,6 +7194,8 @@ export const reduce: {
 /**
  * Folds an iterable from right to left into a single value.
  *
+ * **Details**
+ *
  * - The function receives `(accumulator, element, index)`.
  *
  * **Example** (Right-to-left fold)
@@ -6818,6 +7216,8 @@ export const reduceRight: {
   /**
    * Folds an iterable from right to left into a single value.
    *
+   * **Details**
+   *
    * - The function receives `(accumulator, element, index)`.
    *
    * **Example** (Right-to-left fold)
@@ -6838,6 +7238,8 @@ export const reduceRight: {
   /**
    * Folds an iterable from right to left into a single value.
    *
+   * **Details**
+   *
    * - The function receives `(accumulator, element, index)`.
    *
    * **Example** (Right-to-left fold)
@@ -7244,6 +7646,8 @@ export const some: {
  * Applies a function to each suffix of the array (starting from each index),
  * collecting the results.
  *
+ * **Details**
+ *
  * - For index `i`, the function receives `self.slice(i)`.
  *
  * **Example** (Suffix lengths)
@@ -7262,6 +7666,8 @@ export const extend: {
    * Applies a function to each suffix of the array (starting from each index),
    * collecting the results.
    *
+   * **Details**
+   *
    * - For index `i`, the function receives `self.slice(i)`.
    *
    * **Example** (Suffix lengths)
@@ -7280,6 +7686,8 @@ export const extend: {
    * Applies a function to each suffix of the array (starting from each index),
    * collecting the results.
    *
+   * **Details**
+   *
    * - For index `i`, the function receives `self.slice(i)`.
    *
    * **Example** (Suffix lengths)
@@ -7668,6 +8076,8 @@ export const dedupe = <S extends Iterable<any>>(
 /**
  * Removes consecutive duplicate elements using a custom equivalence.
  *
+ * **Details**
+ *
  * - Non-adjacent duplicates are preserved.
  *
  * **Example** (Deduplicating adjacent elements)
@@ -7689,6 +8099,8 @@ export const dedupeAdjacentWith: {
   /**
    * Removes consecutive duplicate elements using a custom equivalence.
    *
+   * **Details**
+   *
    * - Non-adjacent duplicates are preserved.
    *
    * **Example** (Deduplicating adjacent elements)
@@ -7710,6 +8122,8 @@ export const dedupeAdjacentWith: {
   /**
    * Removes consecutive duplicate elements using a custom equivalence.
    *
+   * **Details**
+   *
    * - Non-adjacent duplicates are preserved.
    *
    * **Example** (Deduplicating adjacent elements)
@@ -7815,6 +8229,8 @@ export const join: {
 /**
  * Maps over an array while threading an accumulator through each step, returning both the final state and the mapped array.
  *
+ * **Details**
+ *
  * - Combines `map` and `reduce` in a single pass.
  * - The callback receives the current state, element, and index, and returns `[nextState, mappedValue]`.
  * - Returns `[finalState, mappedArray]`.
@@ -7839,6 +8255,8 @@ export const mapAccum: {
   /**
    * Maps over an array while threading an accumulator through each step, returning both the final state and the mapped array.
    *
+   * **Details**
+   *
    * - Combines `map` and `reduce` in a single pass.
    * - The callback receives the current state, element, and index, and returns `[nextState, mappedValue]`.
    * - Returns `[finalState, mappedArray]`.
@@ -7863,6 +8281,8 @@ export const mapAccum: {
   /**
    * Maps over an array while threading an accumulator through each step, returning both the final state and the mapped array.
    *
+   * **Details**
+   *
    * - Combines `map` and `reduce` in a single pass.
    * - The callback receives the current state, element, and index, and returns `[nextState, mappedValue]`.
    * - Returns `[finalState, mappedArray]`.
@@ -7907,6 +8327,8 @@ export const mapAccum: {
 /**
  * Computes the cartesian product of two arrays, applying a combiner to each pair.
  *
+ * **Details**
+ *
  * - Produces every combination of an element from `self` with an element from `that`.
  * - Result length is `self.length * that.length`.
  * - Order: iterates `that` for each element of `self`.
@@ -7929,6 +8351,8 @@ export const cartesianWith: {
   /**
    * Computes the cartesian product of two arrays, applying a combiner to each pair.
    *
+   * **Details**
+   *
    * - Produces every combination of an element from `self` with an element from `that`.
    * - Result length is `self.length * that.length`.
    * - Order: iterates `that` for each element of `self`.
@@ -7951,6 +8375,8 @@ export const cartesianWith: {
   /**
    * Computes the cartesian product of two arrays, applying a combiner to each pair.
    *
+   * **Details**
+   *
    * - Produces every combination of an element from `self` with an element from `that`.
    * - Result length is `self.length * that.length`.
    * - Order: iterates `that` for each element of `self`.
@@ -7979,6 +8405,8 @@ export const cartesianWith: {
 /**
  * Computes the cartesian product of two arrays, returning all pairs as tuples.
  *
+ * **Details**
+ *
  * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
  * - Result length is `self.length * that.length`.
  *
@@ -8000,6 +8428,8 @@ export const cartesian: {
   /**
    * Computes the cartesian product of two arrays, returning all pairs as tuples.
    *
+   * **Details**
+   *
    * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
    * - Result length is `self.length * that.length`.
    *
@@ -8021,6 +8451,8 @@ export const cartesian: {
   /**
    * Computes the cartesian product of two arrays, returning all pairs as tuples.
    *
+   * **Details**
+   *
    * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
    * - Result length is `self.length * that.length`.
    *
@@ -8051,6 +8483,8 @@ export const cartesian: {
 /**
  * Starting point for the "do simulation" — an array comprehension pattern.
  *
+ * **When to use**
+ *
  * - Begin a pipeline with `Do`, then use {@link bind} to introduce array variables and {@link let_ let} for plain values.
  * - Each `bind` produces the cartesian product of all bound variables (like nested loops).
  * - Use `filter` and `map` in the pipeline to add conditions and transformations.
@@ -8082,6 +8516,8 @@ export const Do: ReadonlyArray<{}> = of({})
 /**
  * Introduces a new array variable into a do-notation scope, producing the cartesian product with all previous bindings.
  *
+ * **Details**
+ *
  * - Each `bind` call adds a named property to the accumulated object.
  * - The callback receives the current scope and must return an array.
  * - Equivalent to `flatMap` + merging the new value into the scope object.
@@ -8111,6 +8547,8 @@ export const bind: {
   /**
    * Introduces a new array variable into a do-notation scope, producing the cartesian product with all previous bindings.
    *
+   * **Details**
+   *
    * - Each `bind` call adds a named property to the accumulated object.
    * - The callback receives the current scope and must return an array.
    * - Equivalent to `flatMap` + merging the new value into the scope object.
@@ -8142,6 +8580,8 @@ export const bind: {
   /**
    * Introduces a new array variable into a do-notation scope, producing the cartesian product with all previous bindings.
    *
+   * **Details**
+   *
    * - Each `bind` call adds a named property to the accumulated object.
    * - The callback receives the current scope and must return an array.
    * - Equivalent to `flatMap` + merging the new value into the scope object.
@@ -8177,6 +8617,8 @@ export const bind: {
 /**
  * Names the elements of an array by wrapping each in an object with the given key, starting a do-notation scope.
  *
+ * **Details**
+ *
  * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
  * - Alternative to starting with `Do` + `bind`; useful when you already have an array.
  *
@@ -8202,6 +8644,8 @@ export const bindTo: {
   /**
    * Names the elements of an array by wrapping each in an object with the given key, starting a do-notation scope.
    *
+   * **Details**
+   *
    * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
    * - Alternative to starting with `Do` + `bind`; useful when you already have an array.
    *
@@ -8227,6 +8671,8 @@ export const bindTo: {
   /**
    * Names the elements of an array by wrapping each in an object with the given key, starting a do-notation scope.
    *
+   * **Details**
+   *
    * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
    * - Alternative to starting with `Do` + `bind`; useful when you already have an array.
    *
@@ -8267,6 +8713,8 @@ export {
   /**
    * Adds a computed plain value to the do-notation scope without introducing a new array dimension.
    *
+   * **Details**
+   *
    * - Unlike {@link bind}, the callback returns a single value (not an array), so no cartesian product occurs.
    * - Useful for derived or intermediate values that depend on previously bound variables.
    *
@@ -8322,6 +8770,8 @@ export function makeReducerConcat<A>(): Reducer.Reducer<Array<A>> {
 /**
  * Counts the elements in an iterable that satisfy a predicate.
  *
+ * **Details**
+ *
  * - The predicate receives both the element and its index.
  * - Returns `0` for an empty iterable.
  *
@@ -8343,6 +8793,8 @@ export const countBy: {
   /**
    * Counts the elements in an iterable that satisfy a predicate.
    *
+   * **Details**
+   *
    * - The predicate receives both the element and its index.
    * - Returns `0` for an empty iterable.
    *
@@ -8364,6 +8816,8 @@ export const countBy: {
   /**
    * Counts the elements in an iterable that satisfy a predicate.
    *
+   * **Details**
+   *
    * - The predicate receives both the element and its index.
    * - Returns `0` for an empty iterable.
    *