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

package/dist/Tuple.d.ts

@@ -77,9 +77,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)
  *
@@ -92,7 +98,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
  */
@@ -101,9 +106,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)
  *
@@ -116,7 +126,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
  */
@@ -124,9 +133,14 @@ export declare 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)
      *
@@ -139,7 +153,6 @@ export declare const get: {
      *
      * @see {@link make} – create a tuple
      * @see {@link pick} – extract multiple elements into a new tuple
-     *
      * @category getters
      * @since 4.0.0
      */
@@ -147,9 +160,14 @@ export declare 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)
      *
@@ -162,7 +180,6 @@ export declare const get: {
      *
      * @see {@link make} – create a tuple
      * @see {@link pick} – extract multiple elements into a new tuple
-     *
      * @category getters
      * @since 4.0.0
      */
@@ -176,9 +193,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)
  *
@@ -191,7 +213,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
  */
@@ -199,9 +220,14 @@ export declare 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)
      *
@@ -214,7 +240,6 @@ export declare const pick: {
      *
      * @see {@link omit} – the inverse (exclude indices instead)
      * @see {@link get} – extract a single element
-     *
      * @category utils
      * @since 4.0.0
      */
@@ -222,9 +247,14 @@ export declare 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)
      *
@@ -237,7 +267,6 @@ export declare const pick: {
      *
      * @see {@link omit} – the inverse (exclude indices instead)
      * @see {@link get} – extract a single element
-     *
      * @category utils
      * @since 4.0.0
      */
@@ -247,9 +276,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)
  *
@@ -261,7 +295,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
  */
@@ -269,9 +302,14 @@ export declare 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)
      *
@@ -283,7 +321,6 @@ export declare const omit: {
      * ```
      *
      * @see {@link pick} – the inverse (keep only specified indices)
-     *
      * @category utils
      * @since 4.0.0
      */
@@ -291,9 +328,14 @@ export declare 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)
      *
@@ -305,7 +347,6 @@ export declare const omit: {
      * ```
      *
      * @see {@link pick} – the inverse (keep only specified indices)
-     *
      * @category utils
      * @since 4.0.0
      */
@@ -314,8 +355,10 @@ export declare 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)
  *
@@ -327,7 +370,6 @@ export declare const omit: {
  * ```
  *
  * @see {@link appendElements} – append multiple elements (another tuple)
- *
  * @category Concatenating
  * @since 2.0.0
  */
@@ -335,8 +377,10 @@ export declare 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)
      *
@@ -348,7 +392,6 @@ export declare const appendElement: {
      * ```
      *
      * @see {@link appendElements} – append multiple elements (another tuple)
-     *
      * @category Concatenating
      * @since 2.0.0
      */
@@ -356,8 +399,10 @@ export declare 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)
      *
@@ -369,7 +414,6 @@ export declare const appendElement: {
      * ```
      *
      * @see {@link appendElements} – append multiple elements (another tuple)
-     *
      * @category Concatenating
      * @since 2.0.0
      */
@@ -378,9 +422,10 @@ export declare 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)
  *
@@ -392,7 +437,6 @@ export declare const appendElement: {
  * ```
  *
  * @see {@link appendElement} – append a single element
- *
  * @category Concatenating
  * @since 4.0.0
  */
@@ -400,9 +444,10 @@ export declare 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)
      *
@@ -414,7 +459,6 @@ export declare const appendElements: {
      * ```
      *
      * @see {@link appendElement} – append a single element
-     *
      * @category Concatenating
      * @since 4.0.0
      */
@@ -422,9 +466,10 @@ export declare 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)
      *
@@ -436,7 +481,6 @@ export declare const appendElements: {
      * ```
      *
      * @see {@link appendElement} – append a single element
-     *
      * @category Concatenating
      * @since 4.0.0
      */
@@ -453,10 +497,14 @@ type Evolved<T, E> = {
  * 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)
  *
@@ -475,7 +523,6 @@ type Evolved<T, E> = {
  *
  * @see {@link map} – apply the same transformation to all elements
  * @see {@link renameIndices} – swap element positions
- *
  * @category mapping
  * @since 4.0.0
  */
@@ -485,10 +532,14 @@ export declare 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)
      *
@@ -507,7 +558,6 @@ export declare const evolve: {
      *
      * @see {@link map} – apply the same transformation to all elements
      * @see {@link renameIndices} – swap element positions
-     *
      * @category mapping
      * @since 4.0.0
      */
@@ -517,10 +567,14 @@ export declare 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)
      *
@@ -539,7 +593,6 @@ export declare const evolve: {
      *
      * @see {@link map} – apply the same transformation to all elements
      * @see {@link renameIndices} – swap element positions
-     *
      * @category mapping
      * @since 4.0.0
      */
@@ -550,7 +603,13 @@ export declare 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)
  *
@@ -565,7 +624,6 @@ export declare const evolve: {
  * ```
  *
  * @see {@link evolve} – transform element values instead of positions
- *
  * @category Index utilities
  * @since 4.0.0
  */
@@ -575,7 +633,13 @@ export declare 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)
      *
@@ -590,7 +654,6 @@ export declare const renameIndices: {
      * ```
      *
      * @see {@link evolve} – transform element values instead of positions
-     *
      * @category Index utilities
      * @since 4.0.0
      */
@@ -604,7 +667,13 @@ export declare 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)
      *
@@ -619,7 +688,6 @@ export declare const renameIndices: {
      * ```
      *
      * @see {@link evolve} – transform element values instead of positions
-     *
      * @category Index utilities
      * @since 4.0.0
      */
@@ -632,10 +700,19 @@ export declare 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)
  *
@@ -655,7 +732,6 @@ export declare 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
  */
@@ -663,10 +739,19 @@ export declare 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)
      *
@@ -686,7 +771,6 @@ export declare 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
      */
@@ -696,10 +780,19 @@ export declare 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)
      *
@@ -719,7 +812,6 @@ export declare 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
      */
@@ -731,9 +823,14 @@ export declare 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)
  *
@@ -755,7 +852,6 @@ export declare 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
  */
@@ -764,9 +860,14 @@ export declare 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)
      *
@@ -788,7 +889,6 @@ export declare 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
      */
@@ -799,9 +899,14 @@ export declare 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)
      *
@@ -823,7 +928,6 @@ export declare 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
      */
@@ -835,9 +939,14 @@ export declare 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)
  *
@@ -859,7 +968,6 @@ export declare 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
  */
@@ -868,9 +976,14 @@ export declare 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)
      *
@@ -892,7 +1005,6 @@ export declare 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
      */
@@ -903,9 +1015,14 @@ export declare 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)
      *
@@ -927,7 +1044,6 @@ export declare 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
      */
@@ -940,9 +1056,13 @@ export declare 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)
  *
@@ -959,7 +1079,6 @@ export declare const mapOmit: {
  * ```
  *
  * @see {@link makeOrder} – create an `Order` for tuples
- *
  * @category Equivalence
  * @since 4.0.0
  */
@@ -969,9 +1088,13 @@ export declare const makeEquivalence: typeof 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)
  *
@@ -985,7 +1108,6 @@ export declare const makeEquivalence: typeof Equivalence.Tuple;
  * ```
  *
  * @see {@link makeEquivalence} – create an `Equivalence` for tuples
- *
  * @category Ordering
  * @since 4.0.0
  */
@@ -995,11 +1117,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)
  *
@@ -1014,7 +1143,6 @@ export {
  * ```
  *
  * @see {@link isTupleOfAtLeast} – check for a minimum length
- *
  * @category guards
  * @since 3.3.0
  */
@@ -1023,11 +1151,19 @@ isTupleOf,
  * 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)
  *
@@ -1042,7 +1178,6 @@ isTupleOf,
  * ```
  *
  * @see {@link isTupleOf} – check for an exact length
- *
  * @category guards
  * @since 3.3.0
  */
@@ -1052,9 +1187,14 @@ isTupleOfAtLeast } from "./Predicate.ts";
  * 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)
  *
@@ -1071,7 +1211,6 @@ isTupleOfAtLeast } from "./Predicate.ts";
  * ```
  *
  * @see {@link makeReducer} – like `makeCombiner` but with an initial value
- *
  * @category combining
  * @since 4.0.0
  */
@@ -1084,8 +1223,13 @@ export declare function makeCombiner<A extends ReadonlyArray<unknown>>(combiners
  * `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)
  *
@@ -1106,7 +1250,6 @@ export declare function makeCombiner<A extends ReadonlyArray<unknown>>(combiners
  * ```
  *
  * @see {@link makeCombiner} – like `makeReducer` but without an initial value
- *
  * @category folding
  * @since 4.0.0
  */