@gkucmierz/utils 5.4.0 → 5.4.2

package/main.mjs

@@ -38,6 +38,9 @@ import {
 import {
   consumeIteratorNonBlocking
 } from './src/developer-utils/consume-iterator.mjs'
+import {
+  EASING_PRESETS, createInterruptibleEase, estimateEasingParams, fitEasing, solveBezier
+} from './src/developer-utils/easing-matcher.mjs'
 import {
   
 } from './src/developer-utils/get-type.mjs'
@@ -169,6 +172,7 @@ export * from './src/data-structures/heap.mjs';
 export * from './src/data-structures/list-node.mjs';
 export * from './src/developer-utils/binary-search.mjs';
 export * from './src/developer-utils/consume-iterator.mjs';
+export * from './src/developer-utils/easing-matcher.mjs';
 export * from './src/developer-utils/get-type.mjs';
 export * from './src/developer-utils/grid-navigation.mjs';
 export * from './src/developer-utils/measure-performance.mjs';
@@ -210,5 +214,5 @@ export * from './src/string-arrays/parse-heading.mjs';
 export * from './src/string-arrays/slugify.mjs';
 
 export default [
-  createLangtonsAnt, createUnlimitedGrid, combinations, combinationsIterator, bin2gray, gray2bin, nChooseK, permutations, permutationsIterator, ConflatingQueue, SetCnt, Stack, Trie, Heap, ListNode, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, detectGridColumns, navigateGrid, measurePerformance, memoize, naturalSearch, QUORUM_CONFIG, QUORUM_DEFAULT_K, QUORUM_DEFAULT_N, QUORUM_MAX_RELATIVE_ERROR, QUORUM_MAX_RELATIVE_ERROR_PCT, QUORUM_ZERO_FLOOR_EPSILON, computeRelativeError, evaluateQuorum, evaluateQuorum4of5, isQuorumEqual, randNormal, array2range, range2array, setSafeInterval, Type, Types, is, isCallable, of, same, barycentricCoordinates, applyScreenDragQuat, axisAngleToMatrix4, axisAngleToQuat, crossProduct, dotProduct, eulerYXZToQuat, getRotationMatrixFromVectors, matToEulerYXZ, matToQuat, multiplyMatrix4, multiplyQuat, normalize, normalizeQuat, projectToTrackball, quatToMat, rotateVecByQuat, slerp, matrixAsArray, OrthoSet, containsPoint1D, containsPointNd, diffBox, diffRange, formatRange, measureBox, measureRange, mutualBox, mutualRange, parseRange, range, sharedMeasureNd, sumBox, sumRange, xorBox, xorRange, egcd, factors, factorsBI, gcd, gcdBI, lcm, lcmBI, lucasLehmerBI, mobius, mobiusBI, mod, modBI, phi, phiBI, powMod, powModBI, tonelliShanksBI, nelderMead, particleSwarmOptimization, simulatedAnnealing, goldenRatio, goldenRatioBI, goldenRatioStr, gpn, gpnBI, heronsFormula, heronsFormulaBI, squareRoot, squareRootBI, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, chunks, chunksAsyncIterator, chunksIterator, copyCase, formatBigNumber, formatBigNumberBI, wrapFn, parseHeading, slugify
+  createLangtonsAnt, createUnlimitedGrid, combinations, combinationsIterator, bin2gray, gray2bin, nChooseK, permutations, permutationsIterator, ConflatingQueue, SetCnt, Stack, Trie, Heap, ListNode, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, EASING_PRESETS, createInterruptibleEase, estimateEasingParams, fitEasing, solveBezier, detectGridColumns, navigateGrid, measurePerformance, memoize, naturalSearch, QUORUM_CONFIG, QUORUM_DEFAULT_K, QUORUM_DEFAULT_N, QUORUM_MAX_RELATIVE_ERROR, QUORUM_MAX_RELATIVE_ERROR_PCT, QUORUM_ZERO_FLOOR_EPSILON, computeRelativeError, evaluateQuorum, evaluateQuorum4of5, isQuorumEqual, randNormal, array2range, range2array, setSafeInterval, Type, Types, is, isCallable, of, same, barycentricCoordinates, applyScreenDragQuat, axisAngleToMatrix4, axisAngleToQuat, crossProduct, dotProduct, eulerYXZToQuat, getRotationMatrixFromVectors, matToEulerYXZ, matToQuat, multiplyMatrix4, multiplyQuat, normalize, normalizeQuat, projectToTrackball, quatToMat, rotateVecByQuat, slerp, matrixAsArray, OrthoSet, containsPoint1D, containsPointNd, diffBox, diffRange, formatRange, measureBox, measureRange, mutualBox, mutualRange, parseRange, range, sharedMeasureNd, sumBox, sumRange, xorBox, xorRange, egcd, factors, factorsBI, gcd, gcdBI, lcm, lcmBI, lucasLehmerBI, mobius, mobiusBI, mod, modBI, phi, phiBI, powMod, powModBI, tonelliShanksBI, nelderMead, particleSwarmOptimization, simulatedAnnealing, goldenRatio, goldenRatioBI, goldenRatioStr, gpn, gpnBI, heronsFormula, heronsFormulaBI, squareRoot, squareRootBI, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, chunks, chunksAsyncIterator, chunksIterator, copyCase, formatBigNumber, formatBigNumberBI, wrapFn, parseHeading, slugify
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkucmierz/utils",
-  "version": "5.4.0",
+  "version": "5.4.2",
   "type": "module",
   "description": "Usefull functions for solving programming tasks",
   "keywords": [
@@ -70,6 +70,7 @@
     "test": "jasmine",
     "watch": "nodemon --exec 'npm test'",
     "docs": "npm run docs:build; npm run docs:open",
+    "build": "npm run build:main",
     "build:main": "node scripts/generate_main.mjs && node scripts/generate_instacode_links.mjs",
     "docs:build": "jsdoc -c jsdoc.json && cp -r docs/@gkucmierz/utils/*/* docs/ && rm -rf docs/@gkucmierz",
     "docs:open": "open docs/index.html",
@@ -83,6 +84,9 @@
   "homepage": "https://gitea.7u.pl/gkucmierz/utils",
   "author": "Grzegorz Kućmierz",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "docdash": "^2.0.2",

package/src/developer-utils/easing-matcher.mjs

@@ -0,0 +1,227 @@
+import { is } from './type.mjs';
+
+const normalizeEasingSamples = samples => {
+  if (!is(samples, Array) || samples.length < 2) return null;
+  const first = samples[0];
+  if (!first) return null;
+
+  // Cumulative { t, y } mode when neither dt/diffT nor dy/diff are present
+  const isCumulative =
+    first.t !== undefined &&
+    first.y !== undefined &&
+    first.dt === undefined &&
+    first.diffT === undefined &&
+    first.dy === undefined &&
+    first.diff === undefined;
+
+  if (isCumulative) {
+    const t0 = samples[0].t < 0 ? samples[0].t : 0;
+    const y0 = samples[0].y < 0 ? samples[0].y : 0;
+    const spanT = samples[samples.length - 1].t - t0;
+    const spanY = samples[samples.length - 1].y - y0;
+    if (!spanT || !spanY) return null;
+    return samples.map(s => ({
+      t: (s.t - t0) / spanT,
+      y: (s.y - y0) / spanY
+    }));
+  }
+
+  let sumT = 0;
+  let sumY = 0;
+  const pts = samples.map(s => {
+    const dt = s.dt !== undefined ? s.dt : (s.diffT || 0);
+    const dy = s.dy !== undefined ? s.dy : (s.diff || 0);
+    sumT += dt;
+    sumY += dy;
+    return { t: sumT, y: sumY };
+  });
+  if (!sumT || !sumY) return null;
+  return pts.map(p => ({ t: p.t / sumT, y: p.y / sumY }));
+};
+
+/**
+ * Solves Cubic Bezier curve for given control points using Newton-Raphson iteration
+ * with bisection fallback for steep/flat segments.
+ * @param {number} p1x
+ * @param {number} p1y
+ * @param {number} p2x
+ * @param {number} p2y
+ * @returns {function(number): number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IM5QDYDcCmAhHALxBxgQF8EAzGKMBAIgAEBzAawFcBjMEmQgPQc4IDKgYBuYMHTZ8RPlKA|▶ Try it live in Instacode}
+ */
+export const solveBezier = (p1x, p1y, p2x, p2y) => t => {
+  if (t <= 0) return 0;
+  if (t >= 1) return 1;
+  if (p1x === p1y && p2x === p2y) return t;
+
+  const cx = 3 * p1x;
+  const bx = 3 * (p2x - p1x) - cx;
+  const ax = 1 - cx - bx;
+  const cy = 3 * p1y;
+  const by = 3 * (p2y - p1y) - cy;
+  const ay = 1 - cy - by;
+
+  const sampleX = u => ((ax * u + bx) * u + cx) * u;
+  const sampleDerivX = u => (3 * ax * u + 2 * bx) * u + cx;
+  const sampleY = u => ((ay * u + by) * u + cy) * u;
+
+  let u = t;
+  for (let i = 0; i < 8; i++) {
+    const xErr = sampleX(u) - t;
+    if (Math.abs(xErr) < 1e-6) return sampleY(u);
+    const d = sampleDerivX(u);
+    if (Math.abs(d) < 1e-6) break;
+    u -= xErr / d;
+  }
+
+  // Bisection fallback when derivative is near zero or Newton steps out of [0, 1]
+  let lo = 0;
+  let hi = 1;
+  u = Math.max(0, Math.min(1, t));
+  for (let i = 0; i < 12; i++) {
+    const x = sampleX(u);
+    if (Math.abs(x - t) < 1e-6) break;
+    if (t > x) lo = u;
+    else hi = u;
+    u = 0.5 * (lo + hi);
+  }
+  return sampleY(u);
+};
+
+/**
+ * Standard CSS easing presets and Chromium quintic deceleration curve.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IKIEEDKBJAcgcQH0AFAJVU1QBVMEBfBAMxijAQCIABAcwGsBXAMZgQAUxgAvAPT84IADYBndgG5gwDDgIlylGmqA|▶ Try it live in Instacode}
+ */
+export const EASING_PRESETS = Object.freeze({
+  'ease-in-out': solveBezier(0.42, 0, 0.58, 1.0),
+  'ease-out': solveBezier(0, 0, 0.58, 1.0),
+  'ease': solveBezier(0.25, 0.1, 0.25, 1.0),
+  'linear': t => t,
+  'ease-in': solveBezier(0.42, 0, 1.0, 1.0),
+  'quint-out': t => 1 - Math.pow(1 - t, 5),
+});
+
+/**
+ * Matches telemetry samples against standard CSS easing presets.
+ * Supports both frame delta samples ({ dy, dt } / { diff, diffT }) and cumulative points ({ t, y }).
+ * Returns sorted list of preset matches with RMSE and percentage score.
+ * @param {Array<Object>} samples
+ * @returns {Array<{ name: string, match: number, rmse: number }>}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IGYjgUQIYGcQB2A5ggL5oxRgIBEAAkQNYCuAxmCAKYwBeA9MzggANrhoBuYMHRY8hIpKA|▶ Try it live in Instacode}
+ */
+export function fitEasing(samples) {
+  const norm = normalizeEasingSamples(samples);
+  if (!norm) return [];
+
+  return Object.entries(EASING_PRESETS).map(([name, fn]) => {
+    const err = norm.reduce((acc, p) => acc + Math.pow(p.y - fn(p.t), 2), 0);
+    const rmse = Math.sqrt(err / norm.length);
+    const match = Math.max(0, Math.min(100, Math.round((1 - rmse * 2) * 1000) / 10));
+    return { name, match, rmse: Math.round(rmse * 1000) / 1000 };
+  }).sort((a, b) => b.match - a.match || a.rmse - b.rmse);
+}
+
+/**
+ * Estimates optimal cubic-bezier control points and asymmetry metrics for raw telemetry samples.
+ * Uses a 2-stage coarse-to-fine search over (x1, y1, x2, y2) in [0, 1]^4.
+ * @param {Array<Object>} samples
+ * @returns {?{ asymmetryRatio: number, midpointT: number, cssBezier: string, controlPoints: Array<number>, matchPercentage: number, evaluate: function(number): number }}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IKYGc7gIZ1QUW3RADsBzABWxmzHQQF8EAzGKMBAIgAEyBrAK4BjMCFQwAXgHoBWADbpOAbmDAMWMLgJFSlarXQqgA|▶ Try it live in Instacode}
+ */
+export function estimateEasingParams(samples) {
+  if (!is(samples, Array) || samples.length < 3) return null;
+  const norm = normalizeEasingSamples(samples);
+  if (!norm) return null;
+
+  const midPoint = norm.find(p => p.y >= 0.5) || { t: 0.5 };
+  const asymmetry = Math.round(((1 - midPoint.t) / (midPoint.t || 1e-4)) * 10) / 10;
+
+  const evalRmse = (x1, y1, x2, y2) => {
+    const fn = solveBezier(x1, y1, x2, y2);
+    let err = 0;
+    for (let i = 0; i < norm.length; i++) {
+      const d = norm[i].y - fn(norm[i].t);
+      err += d * d;
+    }
+    return Math.sqrt(err / norm.length);
+  };
+
+  let best = { rmse: evalRmse(0.25, 0.1, 0.25, 1.0), x1: 0.25, y1: 0.1, x2: 0.25, y2: 1.0 };
+
+  // Seed with known CSS presets first
+  const presetSeeds = [
+    [0.25, 0.1, 0.25, 1.0],
+    [0.42, 0.0, 0.58, 1.0],
+    [0.0, 0.0, 0.58, 1.0],
+    [0.42, 0.0, 1.0, 1.0],
+    [0.25, 0.25, 0.75, 0.75],
+    [0.22, 1.0, 0.36, 1.0]
+  ];
+  for (const [x1, y1, x2, y2] of presetSeeds) {
+    const rmse = evalRmse(x1, y1, x2, y2);
+    if (rmse < best.rmse) best = { rmse, x1, y1, x2, y2 };
+  }
+
+  // Stage 1: Coarse grid over (x1, y1, x2, y2)
+  for (let x1 = 0.05; x1 <= 0.65; x1 += 0.15) {
+    for (let y1 = 0.0; y1 <= 1.0; y1 += 0.2) {
+      for (let x2 = 0.15; x2 <= 0.95; x2 += 0.2) {
+        for (let y2 = 0.6; y2 <= 1.0; y2 += 0.2) {
+          const rmse = evalRmse(x1, y1, x2, y2);
+          if (rmse < best.rmse) best = { rmse, x1, y1, x2, y2 };
+        }
+      }
+    }
+  }
+
+  // Stage 2: Local coordinate refinement around best candidate
+  for (const step of [0.05, 0.02]) {
+    let improved = true;
+    while (improved) {
+      improved = false;
+      const coords = ['x1', 'y1', 'x2', 'y2'];
+      for (const key of coords) {
+        for (const dir of [-step, step]) {
+          const cand = { ...best, [key]: Math.max(0, Math.min(1, best[key] + dir)) };
+          const rmse = evalRmse(cand.x1, cand.y1, cand.x2, cand.y2);
+          if (rmse + 1e-6 < best.rmse) {
+            best = { rmse, x1: cand.x1, y1: cand.y1, x2: cand.x2, y2: cand.y2 };
+            improved = true;
+          }
+        }
+      }
+    }
+  }
+
+  const rx1 = Number(best.x1.toFixed(2));
+  const ry1 = Number(best.y1.toFixed(2));
+  const rx2 = Number(best.x2.toFixed(2));
+  const ry2 = Number(best.y2.toFixed(2));
+  const match = Math.max(0, Math.min(100, Math.round((1 - best.rmse * 2) * 1000) / 10));
+  const cssBezier = `cubic-bezier(${rx1.toFixed(2)}, ${ry1.toFixed(2)}, ${rx2.toFixed(2)}, ${ry2.toFixed(2)})`;
+
+  return {
+    asymmetryRatio: asymmetry,
+    midpointT: Math.round(midPoint.t * 100) / 100,
+    cssBezier,
+    controlPoints: [rx1, ry1, rx2, ry2],
+    matchPercentage: match,
+    evaluate: solveBezier(rx1, ry1, rx2, ry2)
+  };
+}
+
+/**
+ * Creates interruptible easing curve preserving kinetic momentum (C1 continuous).
+ * @param {number} vCurr Current velocity in pixels/second
+ * @param {number} targetDist Remaining distance to target in pixels
+ * @param {number} duration Total duration in milliseconds
+ * @returns {function(number): number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMYwKYEM4YJIB2uMMArhHCAEYA2GAolgM4YIC+CAZjFGAgEQABAOYBrUqjAgMMAF4B6UpRpN+AbmDB02XIWJkK1OoxYagA|▶ Try it live in Instacode}
+ */
+export function createInterruptibleEase(vCurr, targetDist, duration) {
+  if (!targetDist || duration <= 0) return t => t;
+  const slope = (vCurr * (duration / 1000)) / targetDist;
+  const p1x = 0.25;
+  const p1y = Math.min(1.0, Math.max(0, slope * p1x));
+  return solveBezier(p1x, p1y, 0.25, 1.0);
+}

package/src/developer-utils/grid-navigation.mjs

@@ -2,9 +2,65 @@
  * @module developer-utils
  */
 
+/**
+ * Builds a 2D occupancy matrix `rows[r][c] = itemIndex` (or `-1` for empty gap)
+ * when `spanLastRow` or `colSpans` is enabled.
+ *
+ * @param {number} totalItems
+ * @param {number} cols
+ * @param {Object} opts
+ * @returns {{ matrix: number[][], itemPos: Array<{ row: number, cols: number[] }> }}
+ */
+const buildSpannedGridMatrix = (totalItems, cols, opts = {}) => {
+  const spanLastRow = Boolean(opts.spanLastRow);
+  const colSpans = opts.colSpans || null;
+  const matrix = [];
+  const itemPos = Array.from({ length: totalItems }, () => ({ row: 0, cols: [] }));
+
+  let curRow = new Array(cols).fill(-1);
+  let c = 0;
+
+  for (let i = 0; i < totalItems; i += 1) {
+    let span = 1;
+    if (colSpans) {
+      const rawSpan = Array.isArray(colSpans) ? colSpans[i] : colSpans[i];
+      if (Number.isFinite(Number(rawSpan)) && Number(rawSpan) >= 1) {
+        span = Math.min(cols, Math.floor(Number(rawSpan)));
+      }
+    }
+    if (c + span > cols) {
+      matrix.push(curRow);
+      curRow = new Array(cols).fill(-1);
+      c = 0;
+    }
+    if (spanLastRow && i === totalItems - 1 && c < cols) {
+      span = cols - c;
+    }
+    const rowIdx = matrix.length;
+    itemPos[i].row = rowIdx;
+    for (let k = 0; k < span && c < cols; k += 1) {
+      curRow[c] = i;
+      itemPos[i].cols.push(c);
+      c += 1;
+    }
+    if (c >= cols) {
+      matrix.push(curRow);
+      curRow = new Array(cols).fill(-1);
+      c = 0;
+    }
+  }
+
+  if (c > 0) {
+    matrix.push(curRow);
+  }
+
+  return { matrix, itemPos };
+};
+
 /**
  * Resolves the next 0-based index when navigating a 2D grid (matrix) that may contain
- * trailing gaps in its last row (`totalItems` not divisible by `columns`).
+ * trailing gaps in its last row (`totalItems` not divisible by `columns`) or spanned cells
+ * (`spanLastRow: true` / `colSpans` / `preferredCol`).
  *
  * Pure mathematical/index function — completely independent of the DOM.
  *
@@ -13,6 +69,9 @@
  * - `wrapHoriz` / `wrapHorizontal` (boolean, optional): overrides `wrap` for horizontal movement (`left` / `right`).
  * - `wrapVert` / `wrapVertical` (boolean, optional): overrides `wrap` for vertical movement (`up` / `down`).
  * - `rowStrict` (boolean, default `false`): when `true`, horizontal movement wraps/clamps strictly within the current row instead of reading order.
+ * - `spanLastRow` (boolean, default `false`): when `true`, the final item (`totalItems - 1`) spans all remaining columns in the last row (e.g. a 2x3 grid where row 2 has a full-width card `[4, 4]`).
+ * - `colSpans` (number[]|Object, optional): explicit column span per item index (`>= 1`).
+ * - `preferredCol` (number, optional): preferred column index (`0 <= preferredCol < columns`) preserved when stepping vertically out of a multi-column spanned item.
  *
  * When `columns === 1` (single-column layout), `right` behaves identically to `down`
  * and `left` behaves identically to `up`.
@@ -60,6 +119,7 @@ export const navigateGrid = (
         ? opts.wrapVert
         : baseWrap;
   const rowStrict = Boolean(opts.rowStrict);
+  const hasSpans = Boolean(opts.spanLastRow || opts.colSpans);
 
   const row = Math.floor(cur / cols);
   const col = cur % cols;
@@ -91,6 +151,26 @@ export const navigateGrid = (
   // Horizontal movement (left / right)
   if (deltaH !== 0) {
     if (rowStrict) {
+      if (hasSpans && cols > 1) {
+        const { matrix, itemPos } = buildSpannedGridMatrix(totalItems, cols, opts);
+        const curRowIdx = itemPos[cur]?.row ?? 0;
+        const rowItems = [];
+        for (const cellItem of matrix[curRowIdx] || []) {
+          if (cellItem >= 0 && !rowItems.includes(cellItem)) {
+            rowItems.push(cellItem);
+          }
+        }
+        const posInRow = rowItems.indexOf(cur);
+        if (posInRow < 0 || rowItems.length <= 0) return cur;
+        const nextPos = posInRow + deltaH;
+        if (nextPos >= 0 && nextPos < rowItems.length) {
+          return rowItems[nextPos];
+        }
+        if (wrapHoriz) {
+          return rowItems[((nextPos % rowItems.length) + rowItems.length) % rowItems.length];
+        }
+        return cur;
+      }
       const rowStart = row * cols;
       const rowLen = Math.min(cols, totalItems - rowStart);
       if (rowLen <= 0) return cur;
@@ -114,6 +194,42 @@ export const navigateGrid = (
     return cur;
   }
 
+  // Vertical movement (up / down) when spanned cells are configured
+  if (hasSpans && cols > 1) {
+    const { matrix, itemPos } = buildSpannedGridMatrix(totalItems, cols, opts);
+    const curInfo = itemPos[cur] || { row: 0, cols: [0] };
+    const occupiedCols = curInfo.cols.length > 0 ? curInfo.cols : [0];
+    let targetCol = occupiedCols[0];
+    if (occupiedCols.length > 1 && Number.isFinite(Number(opts.preferredCol))) {
+      const pref = Math.max(0, Math.min(cols - 1, Math.floor(Number(opts.preferredCol))));
+      if (occupiedCols.includes(pref)) {
+        targetCol = pref;
+      }
+    }
+
+    const validRowsForCol = [];
+    for (let r = 0; r < matrix.length; r += 1) {
+      if (matrix[r][targetCol] >= 0) {
+        validRowsForCol.push(r);
+      }
+    }
+    if (validRowsForCol.length === 0) return cur;
+
+    const curRowPos = validRowsForCol.indexOf(curInfo.row);
+    const baseRowPos = curRowPos >= 0 ? curRowPos : 0;
+    const nextRowPos = baseRowPos + deltaV;
+    if (nextRowPos >= 0 && nextRowPos < validRowsForCol.length) {
+      return matrix[validRowsForCol[nextRowPos]][targetCol];
+    }
+    if (wrapVert) {
+      const wrappedPos =
+        ((nextRowPos % validRowsForCol.length) + validRowsForCol.length) %
+        validRowsForCol.length;
+      return matrix[validRowsForCol[wrappedPos]][targetCol];
+    }
+    return cur;
+  }
+
   // Vertical movement (up / down) along column `col` (handling incomplete last row gaps)
   const colRows = col < totalItems ? Math.floor((totalItems - 1 - col) / cols) + 1 : 0;
   if (colRows <= 0) return cur;

package/src/developer-utils/quorum.mjs

@@ -159,7 +159,7 @@ const computeClusterConsensusValue = (values) => {
  * - `success: true` is returned **if and only if** the largest mutually-equal clique $C^*$ has size $|C^*| \ge K$
  *   (e.g., at least $4$ out of $5$ datapoints are mutually equal within $0.01\%$).
  *
- * @param {Array<number|number[]|{source?: string, id?: string, value: number|number[]}>} datapoints - Input datapoints.
+ * @param {Array<(number|Array<number>|Object)>} datapoints - Input datapoints.
  * @param {Object} [options={}] - Quorum configuration options.
  * @param {number} [options.k=4] - Minimum number of mutually-equal datapoints required for success ($K$).
  * @param {number} [options.n=5] - Expected total number of independent sources ($N$).
@@ -332,7 +332,7 @@ export const evaluateQuorum = (
  * Convenience helper for the standard $4\text{-of-}5$ quorum check with $0.01\%$ (`0.0001`)
  * maximum relative error tolerance.
  *
- * @param {Array<number|number[]|{source?: string, id?: string, value: number|number[]}>} datapoints - 5 source datapoints.
+ * @param {Array<(number|Array<number>|Object)>} datapoints - 5 source datapoints.
  * @param {Object} [options={}] - Optional overrides (`maxRelativeError`, `strictN`, `zeroFloor`).
  * @returns {Object} Quorum evaluation result.
  * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IKYDcCGAbArpuVARV1lzABYoAzAVgQF8FqYowEAiAAQHMBrXAGMwIVDABeAelxwQ2AM4cA3MGAYc+QiTKUatFUA|▶ Try it live in Instacode}