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

package/src/Tuple.ts

@@ -79,9 +79,15 @@ import type { Apply, Lambda } from "./Struct.ts"
 /**
  * Creates a tuple from the provided arguments.
  *
- * - Use instead of `[a, b, c] as const` to get a properly typed tuple
- *   without a manual cast.
- * - Returns the exact tuple type with each element's literal type preserved.
+ * **When to use**
+ *
+ * Use this instead of `[a, b, c] as const` when you want a properly typed tuple
+ * without a manual cast.
+ *
+ * **Details**
+ *
+ * The returned value has the exact tuple type, with each element's literal type
+ * preserved.
  *
  * **Example** (Creating a tuple)
  *
@@ -94,7 +100,6 @@ import type { Apply, Lambda } from "./Struct.ts"
  *
  * @see {@link get} – access a single element by index
  * @see {@link appendElement} – append an element to a tuple
- *
  * @category constructors
  * @since 2.0.0
  */
@@ -105,9 +110,14 @@ type Indices<T extends ReadonlyArray<unknown>> = Exclude<Partial<T>["length"], T
 /**
  * Retrieves the element at the specified index from a tuple.
  *
- * - Use in a pipeline when you need to extract a single element.
- * - The index is constrained to valid tuple positions at the type level.
- * - Does not mutate the input.
+ * **When to use**
+ *
+ * Use this in a pipeline when you need to extract a single element.
+ *
+ * **Details**
+ *
+ * The index is constrained to valid tuple positions at the type level, and the
+ * input tuple is not mutated.
  *
  * **Example** (Extracting an element by index)
  *
@@ -120,7 +130,6 @@ type Indices<T extends ReadonlyArray<unknown>> = Exclude<Partial<T>["length"], T
  *
  * @see {@link make} – create a tuple
  * @see {@link pick} – extract multiple elements into a new tuple
- *
  * @category getters
  * @since 4.0.0
  */
@@ -128,9 +137,14 @@ export const get: {
   /**
    * Retrieves the element at the specified index from a tuple.
    *
-   * - Use in a pipeline when you need to extract a single element.
-   * - The index is constrained to valid tuple positions at the type level.
-   * - Does not mutate the input.
+   * **When to use**
+   *
+   * Use this in a pipeline when you need to extract a single element.
+   *
+   * **Details**
+   *
+   * The index is constrained to valid tuple positions at the type level, and the
+   * input tuple is not mutated.
    *
    * **Example** (Extracting an element by index)
    *
@@ -143,7 +157,6 @@ export const get: {
    *
    * @see {@link make} – create a tuple
    * @see {@link pick} – extract multiple elements into a new tuple
-   *
    * @category getters
    * @since 4.0.0
    */
@@ -151,9 +164,14 @@ export const get: {
   /**
    * Retrieves the element at the specified index from a tuple.
    *
-   * - Use in a pipeline when you need to extract a single element.
-   * - The index is constrained to valid tuple positions at the type level.
-   * - Does not mutate the input.
+   * **When to use**
+   *
+   * Use this in a pipeline when you need to extract a single element.
+   *
+   * **Details**
+   *
+   * The index is constrained to valid tuple positions at the type level, and the
+   * input tuple is not mutated.
    *
    * **Example** (Extracting an element by index)
    *
@@ -166,7 +184,6 @@ export const get: {
    *
    * @see {@link make} – create a tuple
    * @see {@link pick} – extract multiple elements into a new tuple
-   *
    * @category getters
    * @since 4.0.0
    */
@@ -192,9 +209,14 @@ type PickTuple<T extends ReadonlyArray<unknown>, K> = _BuildTuple<T, K>
 /**
  * Creates a new tuple containing only the elements at the specified indices.
  *
- * - Use to select a subset of elements from a tuple by position.
- * - The result order matches the order of the provided indices.
- * - Does not mutate the input; returns a fresh tuple.
+ * **When to use**
+ *
+ * Use this to select a subset of elements from a tuple by position.
+ *
+ * **Details**
+ *
+ * The result order matches the order of the provided indices. The input tuple is
+ * not mutated; a fresh tuple is returned.
  *
  * **Example** (Selecting elements by index)
  *
@@ -207,7 +229,6 @@ type PickTuple<T extends ReadonlyArray<unknown>, K> = _BuildTuple<T, K>
  *
  * @see {@link omit} – the inverse (exclude indices instead)
  * @see {@link get} – extract a single element
- *
  * @category utils
  * @since 4.0.0
  */
@@ -215,9 +236,14 @@ export const pick: {
   /**
    * Creates a new tuple containing only the elements at the specified indices.
    *
-   * - Use to select a subset of elements from a tuple by position.
-   * - The result order matches the order of the provided indices.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **When to use**
+   *
+   * Use this to select a subset of elements from a tuple by position.
+   *
+   * **Details**
+   *
+   * The result order matches the order of the provided indices. The input tuple is
+   * not mutated; a fresh tuple is returned.
    *
    * **Example** (Selecting elements by index)
    *
@@ -230,7 +256,6 @@ export const pick: {
    *
    * @see {@link omit} – the inverse (exclude indices instead)
    * @see {@link get} – extract a single element
-   *
    * @category utils
    * @since 4.0.0
    */
@@ -238,9 +263,14 @@ export const pick: {
   /**
    * Creates a new tuple containing only the elements at the specified indices.
    *
-   * - Use to select a subset of elements from a tuple by position.
-   * - The result order matches the order of the provided indices.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **When to use**
+   *
+   * Use this to select a subset of elements from a tuple by position.
+   *
+   * **Details**
+   *
+   * The result order matches the order of the provided indices. The input tuple is
+   * not mutated; a fresh tuple is returned.
    *
    * **Example** (Selecting elements by index)
    *
@@ -253,7 +283,6 @@ export const pick: {
    *
    * @see {@link omit} – the inverse (exclude indices instead)
    * @see {@link get} – extract a single element
-   *
    * @category utils
    * @since 4.0.0
    */
@@ -273,9 +302,14 @@ type OmitTuple<T extends ReadonlyArray<unknown>, K> = _BuildTuple<T, Exclude<Ind
 /**
  * Creates a new tuple with the elements at the specified indices removed.
  *
- * - Use to drop elements from a tuple by position.
- * - Elements not at the specified indices are kept in their original order.
- * - Does not mutate the input; returns a fresh tuple.
+ * **When to use**
+ *
+ * Use this to drop elements from a tuple by position.
+ *
+ * **Details**
+ *
+ * Elements not at the specified indices are kept in their original order. The
+ * input tuple is not mutated; a fresh tuple is returned.
  *
  * **Example** (Removing elements by index)
  *
@@ -287,7 +321,6 @@ type OmitTuple<T extends ReadonlyArray<unknown>, K> = _BuildTuple<T, Exclude<Ind
  * ```
  *
  * @see {@link pick} – the inverse (keep only specified indices)
- *
  * @category utils
  * @since 4.0.0
  */
@@ -295,9 +328,14 @@ export const omit: {
   /**
    * Creates a new tuple with the elements at the specified indices removed.
    *
-   * - Use to drop elements from a tuple by position.
-   * - Elements not at the specified indices are kept in their original order.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **When to use**
+   *
+   * Use this to drop elements from a tuple by position.
+   *
+   * **Details**
+   *
+   * Elements not at the specified indices are kept in their original order. The
+   * input tuple is not mutated; a fresh tuple is returned.
    *
    * **Example** (Removing elements by index)
    *
@@ -309,7 +347,6 @@ export const omit: {
    * ```
    *
    * @see {@link pick} – the inverse (keep only specified indices)
-   *
    * @category utils
    * @since 4.0.0
    */
@@ -317,9 +354,14 @@ export const omit: {
   /**
    * Creates a new tuple with the elements at the specified indices removed.
    *
-   * - Use to drop elements from a tuple by position.
-   * - Elements not at the specified indices are kept in their original order.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **When to use**
+   *
+   * Use this to drop elements from a tuple by position.
+   *
+   * **Details**
+   *
+   * Elements not at the specified indices are kept in their original order. The
+   * input tuple is not mutated; a fresh tuple is returned.
    *
    * **Example** (Removing elements by index)
    *
@@ -331,7 +373,6 @@ export const omit: {
    * ```
    *
    * @see {@link pick} – the inverse (keep only specified indices)
-   *
    * @category utils
    * @since 4.0.0
    */
@@ -350,8 +391,10 @@ export const omit: {
 /**
  * Appends a single element to the end of a tuple.
  *
- * - The result type is `[...T, E]`, preserving all existing element types.
- * - Does not mutate the input; returns a fresh tuple.
+ * **Details**
+ *
+ * The result type is `[...T, E]`, preserving all existing element types. The
+ * input tuple is not mutated; a fresh tuple is returned.
  *
  * **Example** (Appending an element)
  *
@@ -363,7 +406,6 @@ export const omit: {
  * ```
  *
  * @see {@link appendElements} – append multiple elements (another tuple)
- *
  * @category Concatenating
  * @since 2.0.0
  */
@@ -371,8 +413,10 @@ export const appendElement: {
   /**
    * Appends a single element to the end of a tuple.
    *
-   * - The result type is `[...T, E]`, preserving all existing element types.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **Details**
+   *
+   * The result type is `[...T, E]`, preserving all existing element types. The
+   * input tuple is not mutated; a fresh tuple is returned.
    *
    * **Example** (Appending an element)
    *
@@ -384,7 +428,6 @@ export const appendElement: {
    * ```
    *
    * @see {@link appendElements} – append multiple elements (another tuple)
-   *
    * @category Concatenating
    * @since 2.0.0
    */
@@ -392,8 +435,10 @@ export const appendElement: {
   /**
    * Appends a single element to the end of a tuple.
    *
-   * - The result type is `[...T, E]`, preserving all existing element types.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **Details**
+   *
+   * The result type is `[...T, E]`, preserving all existing element types. The
+   * input tuple is not mutated; a fresh tuple is returned.
    *
    * **Example** (Appending an element)
    *
@@ -405,7 +450,6 @@ export const appendElement: {
    * ```
    *
    * @see {@link appendElements} – append multiple elements (another tuple)
-   *
    * @category Concatenating
    * @since 2.0.0
    */
@@ -415,9 +459,10 @@ export const appendElement: {
 /**
  * Concatenates two tuples into a single tuple.
  *
- * - The result type is `[...T1, ...T2]`, preserving all element types from
- *   both tuples.
- * - Does not mutate either input; returns a fresh tuple.
+ * **Details**
+ *
+ * The result type is `[...T1, ...T2]`, preserving all element types from both
+ * tuples. Neither input tuple is mutated; a fresh tuple is returned.
  *
  * **Example** (Concatenating tuples)
  *
@@ -429,7 +474,6 @@ export const appendElement: {
  * ```
  *
  * @see {@link appendElement} – append a single element
- *
  * @category Concatenating
  * @since 4.0.0
  */
@@ -437,9 +481,10 @@ export const appendElements: {
   /**
    * Concatenates two tuples into a single tuple.
    *
-   * - The result type is `[...T1, ...T2]`, preserving all element types from
-   *   both tuples.
-   * - Does not mutate either input; returns a fresh tuple.
+   * **Details**
+   *
+   * The result type is `[...T1, ...T2]`, preserving all element types from both
+   * tuples. Neither input tuple is mutated; a fresh tuple is returned.
    *
    * **Example** (Concatenating tuples)
    *
@@ -451,7 +496,6 @@ export const appendElements: {
    * ```
    *
    * @see {@link appendElement} – append a single element
-   *
    * @category Concatenating
    * @since 4.0.0
    */
@@ -459,9 +503,10 @@ export const appendElements: {
   /**
    * Concatenates two tuples into a single tuple.
    *
-   * - The result type is `[...T1, ...T2]`, preserving all element types from
-   *   both tuples.
-   * - Does not mutate either input; returns a fresh tuple.
+   * **Details**
+   *
+   * The result type is `[...T1, ...T2]`, preserving all element types from both
+   * tuples. Neither input tuple is mutated; a fresh tuple is returned.
    *
    * **Example** (Concatenating tuples)
    *
@@ -473,7 +518,6 @@ export const appendElements: {
    * ```
    *
    * @see {@link appendElement} – append a single element
-   *
    * @category Concatenating
    * @since 4.0.0
    */
@@ -495,10 +539,14 @@ type Evolved<T, E> = { [I in keyof T]: I extends keyof E ? (E[I] extends (...a:
  * Each function applies to the element at the same position. Positions beyond
  * the array's length are copied unchanged.
  *
- * - Use when you want to update the first N elements while keeping the rest.
- * - Does not mutate the input; returns a fresh tuple.
- * - Each transform function receives the current value and can return a
- *   different type.
+ * **When to use**
+ *
+ * Use this when you want to update the first N elements while keeping the rest.
+ *
+ * **Details**
+ *
+ * Each transform function receives the current value and can return a different
+ * type. The input tuple is not mutated; a fresh tuple is returned.
  *
  * **Example** (Transforming selected elements)
  *
@@ -517,7 +565,6 @@ type Evolved<T, E> = { [I in keyof T]: I extends keyof E ? (E[I] extends (...a:
  *
  * @see {@link map} – apply the same transformation to all elements
  * @see {@link renameIndices} – swap element positions
- *
  * @category mapping
  * @since 4.0.0
  */
@@ -527,10 +574,14 @@ export const evolve: {
    * Each function applies to the element at the same position. Positions beyond
    * the array's length are copied unchanged.
    *
-   * - Use when you want to update the first N elements while keeping the rest.
-   * - Does not mutate the input; returns a fresh tuple.
-   * - Each transform function receives the current value and can return a
-   *   different type.
+   * **When to use**
+   *
+   * Use this when you want to update the first N elements while keeping the rest.
+   *
+   * **Details**
+   *
+   * Each transform function receives the current value and can return a different
+   * type. The input tuple is not mutated; a fresh tuple is returned.
    *
    * **Example** (Transforming selected elements)
    *
@@ -549,7 +600,6 @@ export const evolve: {
    *
    * @see {@link map} – apply the same transformation to all elements
    * @see {@link renameIndices} – swap element positions
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -559,10 +609,14 @@ export const evolve: {
    * Each function applies to the element at the same position. Positions beyond
    * the array's length are copied unchanged.
    *
-   * - Use when you want to update the first N elements while keeping the rest.
-   * - Does not mutate the input; returns a fresh tuple.
-   * - Each transform function receives the current value and can return a
-   *   different type.
+   * **When to use**
+   *
+   * Use this when you want to update the first N elements while keeping the rest.
+   *
+   * **Details**
+   *
+   * Each transform function receives the current value and can return a different
+   * type. The input tuple is not mutated; a fresh tuple is returned.
    *
    * **Example** (Transforming selected elements)
    *
@@ -581,7 +635,6 @@ export const evolve: {
    *
    * @see {@link map} – apply the same transformation to all elements
    * @see {@link renameIndices} – swap element positions
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -598,7 +651,13 @@ export const evolve: {
  * indices. Each position in the array specifies which index to read from
  * (e.g., `["2", "1", "0"]` reverses a 3-element tuple).
  *
- * - Does not mutate the input; returns a fresh tuple.
+ * **Details**
+ *
+ * The input tuple is not mutated; a fresh tuple is returned.
+ *
+ * **Gotchas**
+ *
+ * The mapping uses stringified source indices, not arbitrary names.
  *
  * **Example** (Swapping elements)
  *
@@ -613,7 +672,6 @@ export const evolve: {
  * ```
  *
  * @see {@link evolve} – transform element values instead of positions
- *
  * @category Index utilities
  * @since 4.0.0
  */
@@ -623,7 +681,13 @@ export const renameIndices: {
    * indices. Each position in the array specifies which index to read from
    * (e.g., `["2", "1", "0"]` reverses a 3-element tuple).
    *
-   * - Does not mutate the input; returns a fresh tuple.
+   * **Details**
+   *
+   * The input tuple is not mutated; a fresh tuple is returned.
+   *
+   * **Gotchas**
+   *
+   * The mapping uses stringified source indices, not arbitrary names.
    *
    * **Example** (Swapping elements)
    *
@@ -638,7 +702,6 @@ export const renameIndices: {
    * ```
    *
    * @see {@link evolve} – transform element values instead of positions
-   *
    * @category Index utilities
    * @since 4.0.0
    */
@@ -648,7 +711,13 @@ export const renameIndices: {
    * indices. Each position in the array specifies which index to read from
    * (e.g., `["2", "1", "0"]` reverses a 3-element tuple).
    *
-   * - Does not mutate the input; returns a fresh tuple.
+   * **Details**
+   *
+   * The input tuple is not mutated; a fresh tuple is returned.
+   *
+   * **Gotchas**
+   *
+   * The mapping uses stringified source indices, not arbitrary names.
    *
    * **Example** (Swapping elements)
    *
@@ -663,7 +732,6 @@ export const renameIndices: {
    * ```
    *
    * @see {@link evolve} – transform element values instead of positions
-   *
    * @category Index utilities
    * @since 4.0.0
    */
@@ -681,10 +749,19 @@ export const renameIndices: {
 /**
  * Applies a `Struct.Lambda` transformation to every element in a tuple.
  *
- * - Use when you want to apply the same function to every element.
- * - The lambda must be created with `Struct.lambda` so the compiler can
- *   track the output types per element.
- * - Does not mutate the input; returns a fresh tuple.
+ * **When to use**
+ *
+ * Use this when you want to apply the same transformation to every element.
+ *
+ * **Details**
+ *
+ * The lambda lets the compiler track the output type for each element. The
+ * input tuple is not mutated; a fresh tuple is returned.
+ *
+ * **Gotchas**
+ *
+ * The lambda must be created with `Struct.lambda`; a plain function will not
+ * type-check.
  *
  * **Example** (Wrapping every element in an array)
  *
@@ -704,7 +781,6 @@ export const renameIndices: {
  * @see {@link mapPick} – apply a lambda only to selected indices
  * @see {@link mapOmit} – apply a lambda to all indices except selected ones
  * @see {@link evolve} – apply different functions to different indices
- *
  * @category mapping
  * @since 3.9.0
  */
@@ -712,10 +788,19 @@ export const map: {
   /**
    * Applies a `Struct.Lambda` transformation to every element in a tuple.
    *
-   * - Use when you want to apply the same function to every element.
-   * - The lambda must be created with `Struct.lambda` so the compiler can
-   *   track the output types per element.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **When to use**
+   *
+   * Use this when you want to apply the same transformation to every element.
+   *
+   * **Details**
+   *
+   * The lambda lets the compiler track the output type for each element. The
+   * input tuple is not mutated; a fresh tuple is returned.
+   *
+   * **Gotchas**
+   *
+   * The lambda must be created with `Struct.lambda`; a plain function will not
+   * type-check.
    *
    * **Example** (Wrapping every element in an array)
    *
@@ -735,7 +820,6 @@ export const map: {
    * @see {@link mapPick} – apply a lambda only to selected indices
    * @see {@link mapOmit} – apply a lambda to all indices except selected ones
    * @see {@link evolve} – apply different functions to different indices
-   *
    * @category mapping
    * @since 3.9.0
    */
@@ -745,10 +829,19 @@ export const map: {
   /**
    * Applies a `Struct.Lambda` transformation to every element in a tuple.
    *
-   * - Use when you want to apply the same function to every element.
-   * - The lambda must be created with `Struct.lambda` so the compiler can
-   *   track the output types per element.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **When to use**
+   *
+   * Use this when you want to apply the same transformation to every element.
+   *
+   * **Details**
+   *
+   * The lambda lets the compiler track the output type for each element. The
+   * input tuple is not mutated; a fresh tuple is returned.
+   *
+   * **Gotchas**
+   *
+   * The lambda must be created with `Struct.lambda`; a plain function will not
+   * type-check.
    *
    * **Example** (Wrapping every element in an array)
    *
@@ -768,7 +861,6 @@ export const map: {
    * @see {@link mapPick} – apply a lambda only to selected indices
    * @see {@link mapOmit} – apply a lambda to all indices except selected ones
    * @see {@link evolve} – apply different functions to different indices
-   *
    * @category mapping
    * @since 3.9.0
    */
@@ -784,9 +876,14 @@ export const map: {
  * Applies a `Struct.Lambda` transformation only to the elements at the
  * specified indices; all other elements are copied unchanged.
  *
- * - Use when you want to apply the same transformation to a subset of
- *   positions.
- * - Does not mutate the input; returns a fresh tuple.
+ * **When to use**
+ *
+ * Use this when you want to apply the same transformation to a subset of
+ * positions.
+ *
+ * **Details**
+ *
+ * The input tuple is not mutated; a fresh tuple is returned.
  *
  * **Example** (Wrapping only selected elements in arrays)
  *
@@ -808,7 +905,6 @@ export const map: {
  *
  * @see {@link map} – apply a lambda to all elements
  * @see {@link mapOmit} – apply a lambda to all elements except selected ones
- *
  * @category mapping
  * @since 4.0.0
  */
@@ -817,9 +913,14 @@ export const mapPick: {
    * Applies a `Struct.Lambda` transformation only to the elements at the
    * specified indices; all other elements are copied unchanged.
    *
-   * - Use when you want to apply the same transformation to a subset of
-   *   positions.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **When to use**
+   *
+   * Use this when you want to apply the same transformation to a subset of
+   * positions.
+   *
+   * **Details**
+   *
+   * The input tuple is not mutated; a fresh tuple is returned.
    *
    * **Example** (Wrapping only selected elements in arrays)
    *
@@ -841,7 +942,6 @@ export const mapPick: {
    *
    * @see {@link map} – apply a lambda to all elements
    * @see {@link mapOmit} – apply a lambda to all elements except selected ones
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -852,9 +952,14 @@ export const mapPick: {
    * Applies a `Struct.Lambda` transformation only to the elements at the
    * specified indices; all other elements are copied unchanged.
    *
-   * - Use when you want to apply the same transformation to a subset of
-   *   positions.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **When to use**
+   *
+   * Use this when you want to apply the same transformation to a subset of
+   * positions.
+   *
+   * **Details**
+   *
+   * The input tuple is not mutated; a fresh tuple is returned.
    *
    * **Example** (Wrapping only selected elements in arrays)
    *
@@ -876,7 +981,6 @@ export const mapPick: {
    *
    * @see {@link map} – apply a lambda to all elements
    * @see {@link mapOmit} – apply a lambda to all elements except selected ones
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -897,9 +1001,14 @@ export const mapPick: {
  * Applies a `Struct.Lambda` transformation to all elements except those at the
  * specified indices; the excluded elements are copied unchanged.
  *
- * - Use when most elements should be transformed but a few should be
- *   preserved.
- * - Does not mutate the input; returns a fresh tuple.
+ * **When to use**
+ *
+ * Use this when most elements should be transformed but a few should be
+ * preserved.
+ *
+ * **Details**
+ *
+ * The input tuple is not mutated; a fresh tuple is returned.
  *
  * **Example** (Wrapping all elements except one in arrays)
  *
@@ -921,7 +1030,6 @@ export const mapPick: {
  *
  * @see {@link map} – apply a lambda to all elements
  * @see {@link mapPick} – apply a lambda only to selected indices
- *
  * @category mapping
  * @since 4.0.0
  */
@@ -930,9 +1038,14 @@ export const mapOmit: {
    * Applies a `Struct.Lambda` transformation to all elements except those at the
    * specified indices; the excluded elements are copied unchanged.
    *
-   * - Use when most elements should be transformed but a few should be
-   *   preserved.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **When to use**
+   *
+   * Use this when most elements should be transformed but a few should be
+   * preserved.
+   *
+   * **Details**
+   *
+   * The input tuple is not mutated; a fresh tuple is returned.
    *
    * **Example** (Wrapping all elements except one in arrays)
    *
@@ -954,7 +1067,6 @@ export const mapOmit: {
    *
    * @see {@link map} – apply a lambda to all elements
    * @see {@link mapPick} – apply a lambda only to selected indices
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -965,9 +1077,14 @@ export const mapOmit: {
    * Applies a `Struct.Lambda` transformation to all elements except those at the
    * specified indices; the excluded elements are copied unchanged.
    *
-   * - Use when most elements should be transformed but a few should be
-   *   preserved.
-   * - Does not mutate the input; returns a fresh tuple.
+   * **When to use**
+   *
+   * Use this when most elements should be transformed but a few should be
+   * preserved.
+   *
+   * **Details**
+   *
+   * The input tuple is not mutated; a fresh tuple is returned.
    *
    * **Example** (Wrapping all elements except one in arrays)
    *
@@ -989,7 +1106,6 @@ export const mapOmit: {
    *
    * @see {@link map} – apply a lambda to all elements
    * @see {@link mapPick} – apply a lambda only to selected indices
-   *
    * @category mapping
    * @since 4.0.0
    */
@@ -1011,9 +1127,13 @@ export const mapOmit: {
  * using the provided per-position `Equivalence`s. Two tuples are equivalent
  * when all their corresponding elements are equivalent.
  *
- * Alias of `Equivalence.Tuple`.
+ * **When to use**
+ *
+ * Use this when you need to compare tuples element-by-element.
  *
- * - Use when you need to compare tuples element-by-element.
+ * **Details**
+ *
+ * This is an alias of `Equivalence.Tuple`.
  *
  * **Example** (Comparing tuples for equivalence)
  *
@@ -1030,7 +1150,6 @@ export const mapOmit: {
  * ```
  *
  * @see {@link makeOrder} – create an `Order` for tuples
- *
  * @category Equivalence
  * @since 4.0.0
  */
@@ -1041,9 +1160,13 @@ export const makeEquivalence = Equivalence.Tuple
  * provided per-position `Order`s. Elements are compared left-to-right; the
  * first non-zero comparison determines the result.
  *
- * Alias of `Order.Tuple`.
+ * **When to use**
  *
- * - Use to sort or compare tuples lexicographically by element position.
+ * Use this to sort or compare tuples lexicographically by element position.
+ *
+ * **Details**
+ *
+ * This is an alias of `Order.Tuple`.
  *
  * **Example** (Ordering tuples)
  *
@@ -1057,7 +1180,6 @@ export const makeEquivalence = Equivalence.Tuple
  * ```
  *
  * @see {@link makeEquivalence} – create an `Equivalence` for tuples
- *
  * @category Ordering
  * @since 4.0.0
  */
@@ -1068,11 +1190,18 @@ export {
    * Checks if an array has exactly `N` elements, narrowing the type to a
    * fixed-length tuple.
    *
-   * Re-export of `Predicate.isTupleOf`.
+   * **When to use**
+   *
+   * Use this to guard against unexpected array lengths at runtime.
    *
-   * - Use to guard against unexpected array lengths at runtime.
-   * - Only checks `.length`; does not validate element types.
-   * - Narrows the type to `TupleOf<N, T>` in the truthy branch.
+   * **Details**
+   *
+   * This is a re-export of `Predicate.isTupleOf`. It narrows the type to
+   * `TupleOf<N, T>` in the truthy branch.
+   *
+   * **Gotchas**
+   *
+   * This only checks `.length`; it does not validate element types.
    *
    * **Example** (Checking exact length)
    *
@@ -1087,7 +1216,6 @@ export {
    * ```
    *
    * @see {@link isTupleOfAtLeast} – check for a minimum length
-   *
    * @category guards
    * @since 3.3.0
    */
@@ -1096,11 +1224,19 @@ export {
    * Checks if an array has at least `N` elements, narrowing the type to a
    * tuple with a minimum length.
    *
-   * Re-export of `Predicate.isTupleOfAtLeast`.
+   * **When to use**
+   *
+   * Use this to guard that an array has at least the expected number of
+   * elements.
    *
-   * - Use to guard that an array has at least the expected number of elements.
-   * - Only checks `.length`; does not validate element types.
-   * - Narrows the type to `TupleOfAtLeast<N, T>` in the truthy branch.
+   * **Details**
+   *
+   * This is a re-export of `Predicate.isTupleOfAtLeast`. It narrows the type to
+   * `TupleOfAtLeast<N, T>` in the truthy branch.
+   *
+   * **Gotchas**
+   *
+   * This only checks `.length`; it does not validate element types.
    *
    * **Example** (Checking minimum length)
    *
@@ -1115,7 +1251,6 @@ export {
    * ```
    *
    * @see {@link isTupleOf} – check for an exact length
-   *
    * @category guards
    * @since 3.3.0
    */
@@ -1127,9 +1262,14 @@ export {
  * position. When two tuples are combined, each element is merged using its
  * corresponding combiner.
  *
- * - Use when you need to merge two tuples of the same shape (e.g., summing
- *   counters, concatenating strings).
- * - Does not mutate the inputs; returns a fresh tuple.
+ * **When to use**
+ *
+ * Use this when you need to merge two tuples of the same shape, such as summing
+ * counters or concatenating strings.
+ *
+ * **Details**
+ *
+ * The inputs are not mutated; a fresh tuple is returned.
  *
  * **Example** (Combining tuple elements)
  *
@@ -1146,7 +1286,6 @@ export {
  * ```
  *
  * @see {@link makeReducer} – like `makeCombiner` but with an initial value
- *
  * @category combining
  * @since 4.0.0
  */
@@ -1168,8 +1307,13 @@ export function makeCombiner<A extends ReadonlyArray<unknown>>(
  * `Reducer.initialValue`. When reducing a collection of tuples, each element
  * is combined independently.
  *
- * - Use to fold a collection of tuples into a single summary tuple.
- * - Does not mutate the inputs; returns a fresh tuple.
+ * **When to use**
+ *
+ * Use this to fold a collection of tuples into a single summary tuple.
+ *
+ * **Details**
+ *
+ * The inputs are not mutated; a fresh tuple is returned.
  *
  * **Example** (Reducing a collection of tuples)
  *
@@ -1190,7 +1334,6 @@ export function makeCombiner<A extends ReadonlyArray<unknown>>(
  * ```
  *
  * @see {@link makeCombiner} – like `makeReducer` but without an initial value
- *
  * @category folding
  * @since 4.0.0
  */