@gkucmierz/utils 5.0.0 → 5.4.0

package/src/developer-utils/quorum.mjs

@@ -0,0 +1,345 @@
+/**
+ * @module developer-utils
+ */
+
+import { is } from './type.mjs';
+
+/**
+ * Default required agreeing datapoints ($K = 4$) in a standard $4\text{-of-}5$ quorum check.
+ * @type {number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfQBEBRAMQEF0AZAFQIGkEBfBAMxijAQCIABAOYBrAK4BjMCACmMAF4B6EXBAAbAM48A3MGAYc+YuSp1G2oA|▶ Try it live in Instacode}
+ */
+export const QUORUM_DEFAULT_K = 4;
+
+/**
+ * Default total independent sources ($N = 5$) in a standard $4\text{-of-}5$ quorum check.
+ * @type {number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfQBEBRAMQEF0AZAFQIDkEBfBAMxijAQCIABAOYBrAK4BjMCACmMAF4B6EXBAAbAM48A3MGAYc+YuSp1G2oA|▶ Try it live in Instacode}
+ */
+export const QUORUM_DEFAULT_N = 5;
+
+/**
+ * Default maximum relative error threshold ($0.01\% = 0.0001 = 1\text{ bp}$) for two datapoints
+ * to be considered equal in a quorum evaluation.
+ * @type {number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfTwEEANA7AUQBliAVASQDVKDLtscEBfBAMxhQwCAEQABAOYBrAK4BjMCACmMAF4B6GXBAAbAM4iA3MGAYc+ImQo16zVu07ZjQA|▶ Try it live in Instacode}
+ */
+export const QUORUM_MAX_RELATIVE_ERROR = 0.0001;
+
+/**
+ * Default maximum relative error expressed in percent ($0.01\%$).
+ * @type {number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfTwEEANA7AUQBliAVASQDVKDLtscCAFAYToQBfBADMYUMAgBEAAQDmAawCuAYzAgApjABeAeiVwQAGwDOUgNzBgGHPiJkKNes1btO2Hv0tA|▶ Try it live in Instacode}
+ */
+export const QUORUM_MAX_RELATIVE_ERROR_PCT = 0.01;
+
+/**
+ * Safe denominator floor near zero to avoid division by zero when comparing $0$ vs $0$.
+ * @type {number}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfQC0BRbTAgMQBlMcCSAFAZQElaA5BAXwQDMYUMAgBEAAQDmAawCuAYzAgApjABeAehlwQAGwDOIgNzBgGHPmJkKNOtgYt2mDsaA|▶ Try it live in Instacode}
+ */
+export const QUORUM_ZERO_FLOOR_EPSILON = 1e-9;
+
+/**
+ * Frozen SSoT configuration object for $K\text{-of-}N$ quorum evaluation.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IIoFUDyAldBZAfQGFMA5AMQEkBxBAXwQDMYowEAiAAQHMBrAVwDGYEAFMYALwD0-OCAA2AZ3YBuYMAw58xMlWpqgA|▶ Try it live in Instacode}
+ */
+export const QUORUM_CONFIG = Object.freeze({
+  DEFAULT_K: QUORUM_DEFAULT_K,
+  DEFAULT_N: QUORUM_DEFAULT_N,
+  MAX_RELATIVE_ERROR: QUORUM_MAX_RELATIVE_ERROR,
+  MAX_RELATIVE_ERROR_PCT: QUORUM_MAX_RELATIVE_ERROR_PCT,
+  ZERO_FLOOR_EPSILON: QUORUM_ZERO_FLOOR_EPSILON
+});
+
+const isFiniteScalar = (v) => is(v, Number) && Number.isFinite(v);
+
+const isNumericVector = (v) =>
+  is(v, Array) && v.length > 0 && v.every((item) => isFiniteScalar(item));
+
+const cleanFloat = (val) => Number(Number(val).toFixed(10));
+
+/**
+ * Computes the symmetric relative error between two numbers or two equal-length numeric vectors:
+ * $$\delta_{\text{rel}}(a, b) = \frac{|a - b|}{\max(|a|, |b|, \varepsilon_{\text{floor}})}$$
+ *
+ * For vectors $\mathbf{a}, \mathbf{b} \in \mathbb{R}^D$, returns the worst-case component-wise
+ * relative error $\max_{d} \delta_{\text{rel}}(a_d, b_d)$.
+ *
+ * @param {number|number[]} a - First value or numeric vector.
+ * @param {number|number[]} b - Second value or numeric vector.
+ * @param {Object} [options={}] - Options object.
+ * @param {number} [options.zeroFloor=1e-9] - Denominator floor when both values are near zero.
+ * @returns {number} Relative error in $[0, \infty)$ (`0.0001` corresponds to `0.01%`).
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMZUgVzgUwEo4A2AhnCAG44CiMMsCAvggGZ1gIBEAAgOYDWmVGBA4YALwD02EIQDOHANzBg6LLgIkylGnRhKgA|▶ Try it live in Instacode}
+ */
+export const computeRelativeError = (
+  a,
+  b,
+  { zeroFloor = QUORUM_ZERO_FLOOR_EPSILON } = {}
+) => {
+  const safeFloor = isFiniteScalar(zeroFloor) && zeroFloor > 0 ? zeroFloor : QUORUM_ZERO_FLOOR_EPSILON;
+
+  if (isFiniteScalar(a) && isFiniteScalar(b)) {
+    if (a === b) return 0;
+    const denom = Math.max(Math.abs(a), Math.abs(b), safeFloor);
+    return Math.abs(a - b) / denom;
+  }
+
+  if (isNumericVector(a) && isNumericVector(b) && a.length === b.length) {
+    let maxErr = 0;
+    for (let i = 0; i < a.length; i++) {
+      const err = computeRelativeError(a[i], b[i], { zeroFloor: safeFloor });
+      if (err > maxErr) maxErr = err;
+    }
+    return maxErr;
+  }
+
+  return Infinity;
+};
+
+/**
+ * Checks whether two datapoints (`a` and `b`) are equal within the maximum relative error
+ * threshold (default `0.01%`, i.e. `maxRelativeError = 0.0001`).
+ *
+ * @param {number|number[]} a - First datapoint.
+ * @param {number|number[]} b - Second datapoint.
+ * @param {Object} [options={}] - Options object.
+ * @param {number} [options.maxRelativeError=0.0001] - Maximum allowed relative error (`0.0001` = `0.01%`).
+ * @param {number} [options.zeroFloor=1e-9] - Denominator floor near zero.
+ * @returns {boolean} True if and only if relative error $\le \text{maxRelativeError}$.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4JAZwIoFdZbAUQEcsBDAGwQF8EAzGKMBAIgAEBzAaywGMwQBTGAC8A9FjggyaJgG5goTDhh4ipMnKA|▶ Try it live in Instacode}
+ */
+export const isQuorumEqual = (
+  a,
+  b,
+  {
+    maxRelativeError = QUORUM_MAX_RELATIVE_ERROR,
+    zeroFloor = QUORUM_ZERO_FLOOR_EPSILON
+  } = {}
+) => {
+  const safeMax = isFiniteScalar(maxRelativeError) && maxRelativeError >= 0
+    ? maxRelativeError
+    : QUORUM_MAX_RELATIVE_ERROR;
+  return computeRelativeError(a, b, { zeroFloor }) <= safeMax + 1e-15;
+};
+
+const computeClusterMedianScalar = (values) => {
+  const sorted = [...values].sort((x, y) => x - y);
+  const mid = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 1) {
+    return sorted[mid];
+  }
+  return cleanFloat((sorted[mid - 1] + sorted[mid]) / 2);
+};
+
+const computeClusterConsensusValue = (values) => {
+  if (values.length === 0) return null;
+  if (isFiniteScalar(values[0])) {
+    return computeClusterMedianScalar(values);
+  }
+  if (isNumericVector(values[0])) {
+    const dim = values[0].length;
+    const out = new Array(dim);
+    for (let d = 0; d < dim; d++) {
+      out[d] = computeClusterMedianScalar(values.map((v) => v[d]));
+    }
+    return out;
+  }
+  return null;
+};
+
+/**
+ * Evaluates a $K\text{-of-}N$ (default $4\text{-of-}5$) quorum across a set of datapoints.
+ *
+ * **Strict Equality-Clique Specification:**
+ * - Two datapoints $v_i, v_j$ are considered equal iff $\delta_{\text{rel}}(v_i, v_j) \le \text{maxRelativeError}$ (default `0.01%` = `0.0001`).
+ * - A subset of datapoints forms an agreeing cluster (clique) $C$ iff **every pair** $i, j \in C$
+ *   is mutually equal within `maxRelativeError` ($\max_{i,j \in C} \delta_{\text{rel}}(v_i, v_j) \le \text{maxRelativeError}$).
+ * - `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 {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$).
+ * @param {number} [options.maxRelativeError=0.0001] - Maximum relative error tolerance (`0.0001` = `0.01%`).
+ * @param {number} [options.zeroFloor=1e-9] - Denominator floor near zero.
+ * @param {boolean} [options.strictN=false] - When `true`, requires `datapoints.length === n` in addition to $|C^*| \ge k$.
+ * @returns {Object} Quorum evaluation result with `success`, `consensusValue`, `maxRelativeError`, `agreeingSources`, and `outliers`.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IKYDcCGAbArpuVARV1lzAQF8EAzGKCgIgAEBzAa1wGMwRUYAXgHpccENgDOjANzBgGHPkIkyYWUA|▶ Try it live in Instacode}
+ */
+export const evaluateQuorum = (
+  datapoints = [],
+  {
+    k = QUORUM_DEFAULT_K,
+    n = QUORUM_DEFAULT_N,
+    maxRelativeError = QUORUM_MAX_RELATIVE_ERROR,
+    zeroFloor = QUORUM_ZERO_FLOOR_EPSILON,
+    strictN = false
+  } = {}
+) => {
+  const requiredK = Math.max(1, Math.floor(Number(k) || QUORUM_DEFAULT_K));
+  const expectedN = Math.max(requiredK, Math.floor(Number(n) || QUORUM_DEFAULT_N));
+  const safeMaxRelErr =
+    isFiniteScalar(maxRelativeError) && maxRelativeError >= 0
+      ? maxRelativeError
+      : QUORUM_MAX_RELATIVE_ERROR;
+
+  const list = is(datapoints, Array) ? datapoints : [];
+  const valid = [];
+
+  for (let idx = 0; idx < list.length; idx++) {
+    const item = list[idx];
+    const isEntryObj = is(item, Object) && !is(item, Array) && item !== null && 'value' in item;
+    const rawVal = isEntryObj ? item.value : item;
+    const source = isEntryObj && is(item.source || item.id, String)
+      ? String(item.source || item.id)
+      : `source-${idx + 1}`;
+
+    if (isFiniteScalar(rawVal) || isNumericVector(rawVal)) {
+      valid.push({
+        index: idx,
+        source,
+        value: isNumericVector(rawVal) ? [...rawVal] : rawVal
+      });
+    }
+  }
+
+  const m = valid.length;
+  const distMatrix = Array.from({ length: m }, () => new Array(m).fill(0));
+  const adjMatrix = Array.from({ length: m }, () => new Array(m).fill(false));
+
+  for (let i = 0; i < m; i++) {
+    adjMatrix[i][i] = true;
+    for (let j = i + 1; j < m; j++) {
+      const d = computeRelativeError(valid[i].value, valid[j].value, { zeroFloor });
+      distMatrix[i][j] = d;
+      distMatrix[j][i] = d;
+      const eq = d <= safeMaxRelErr + 1e-15;
+      adjMatrix[i][j] = eq;
+      adjMatrix[j][i] = eq;
+    }
+  }
+
+  // Exact maximum clique search (with min internal spread tie-breaker)
+  let bestClique = [];
+  let bestSpread = Infinity;
+
+  const computeCliqueSpread = (clique) => {
+    let maxD = 0;
+    for (let a = 0; a < clique.length; a++) {
+      for (let b = a + 1; b < clique.length; b++) {
+        const d = distMatrix[clique[a]][clique[b]];
+        if (d > maxD) maxD = d;
+      }
+    }
+    return maxD;
+  };
+
+  const searchClique = (startIdx, currentClique) => {
+    if (currentClique.length + (m - startIdx) < bestClique.length) {
+      return;
+    }
+
+    if (currentClique.length > 0) {
+      const spread = computeCliqueSpread(currentClique);
+      if (
+        currentClique.length > bestClique.length ||
+        (currentClique.length === bestClique.length && spread < bestSpread - 1e-15)
+      ) {
+        bestClique = [...currentClique];
+        bestSpread = spread;
+      }
+    }
+
+    for (let next = startIdx; next < m; next++) {
+      let compatible = true;
+      for (let c = 0; c < currentClique.length; c++) {
+        if (!adjMatrix[currentClique[c]][next]) {
+          compatible = false;
+          break;
+        }
+      }
+      if (compatible) {
+        currentClique.push(next);
+        searchClique(next + 1, currentClique);
+        currentClique.pop();
+      }
+    }
+  };
+
+  if (m > 0) {
+    searchClique(0, []);
+  } else {
+    bestSpread = 0;
+  }
+
+  const agreeingEntries = bestClique.map((idx) => valid[idx]);
+  const agreeingValues = agreeingEntries.map((e) => e.value);
+  const agreeingCount = agreeingEntries.length;
+  const nConditionMet = strictN ? list.length === expectedN && m === expectedN : true;
+  const success = Boolean(nConditionMet && agreeingCount >= requiredK);
+  const consensusValue = success ? computeClusterConsensusValue(agreeingValues) : null;
+  const referenceValue = consensusValue !== null
+    ? consensusValue
+    : computeClusterConsensusValue(agreeingValues);
+
+  const bestSet = new Set(bestClique);
+  const outliers = [];
+  for (let i = 0; i < m; i++) {
+    if (!bestSet.has(i)) {
+      const relErr = referenceValue !== null
+        ? computeRelativeError(valid[i].value, referenceValue, { zeroFloor })
+        : Infinity;
+      outliers.push({
+        index: valid[i].index,
+        source: valid[i].source,
+        value: valid[i].value,
+        relativeError: Number.isFinite(relErr) ? cleanFloat(relErr) : Infinity,
+        relativeErrorPct: Number.isFinite(relErr) ? Number((relErr * 100).toFixed(6)) : Infinity
+      });
+    }
+  }
+
+  const safeSpread = Number.isFinite(bestSpread) ? cleanFloat(bestSpread) : 0;
+
+  return {
+    success,
+    quorumReached: success,
+    status: success
+      ? agreeingCount >= expectedN
+        ? 'OK_UNANIMOUS'
+        : 'OK_QUORUM'
+      : 'REJECTED_NO_QUORUM',
+    consensusValue,
+    agreeingCount,
+    requiredK,
+    expectedN,
+    sampleCount: m,
+    maxRelativeError: safeSpread,
+    maxRelativeErrorPct: Number((safeSpread * 100).toFixed(6)),
+    thresholdRelativeError: safeMaxRelErr,
+    thresholdRelativeErrorPct: Number((safeMaxRelErr * 100).toFixed(4)),
+    agreeingIndices: agreeingEntries.map((e) => e.index),
+    agreeingSources: agreeingEntries.map((e) => e.source),
+    agreeingValues,
+    outliers
+  };
+};
+
+/**
+ * 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 {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}
+ */
+export const evaluateQuorum4of5 = (datapoints = [], options = {}) =>
+  evaluateQuorum(datapoints, {
+    ...options,
+    k: QUORUM_DEFAULT_K,
+    n: QUORUM_DEFAULT_N
+  });

package/src/developer-utils/type.mjs

@@ -21,6 +21,10 @@ export class Type {
   static OBJECT = 'object';
   static ARRAY = 'array';
   static FUNCTION = 'function';
+  static ASYNC_FUNCTION = 'asyncfunction';
+  static GENERATOR_FUNCTION = 'generatorfunction';
+  static ASYNC_GENERATOR_FUNCTION = 'asyncgeneratorfunction';
+  static CALLABLE = 'callable';
 
   // 3. Standard Built-ins
   static DATE = 'date';
@@ -56,6 +60,9 @@ export class Type {
     if (Array.isArray(expected)) {
       return expected.some(exp => Type.is(val, exp));
     }
+    if (expected === Type.CALLABLE || expected === 'callable') {
+      return Type.isCallable(val);
+    }
     if (typeof expected === 'function') {
       if (expected === Number) return typeof val === 'number' && !Number.isNaN(val);
       if (expected === Boolean) return typeof val === 'boolean' || val instanceof Boolean;
@@ -70,6 +77,16 @@ export class Type {
     return Type.of(val) === expected;
   }
 
+  /**
+   * Checks if a value is callable (regular function, async function, or generator).
+   * @param {*} val - Value to check.
+   * @returns {boolean} True if the value is any callable function.
+   */
+  static isCallable(val) {
+    const t = Type.of(val);
+    return t === 'function' || t === 'asyncfunction' || t === 'generatorfunction' || t === 'asyncgeneratorfunction';
+  }
+
   /**
    * Compares whether two values have the exact same canonical type.
    * Safely prevents JavaScript traps like typeof NaN === typeof 42 or typeof null === typeof {}.
@@ -109,3 +126,10 @@ export const of = Type.of;
  */
 export const same = Type.same;
 
+/**
+ * Checks if a value is callable (regular function, async function, or generator).
+ * @see {@link Type.isCallable}
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4JAZwMIEMA2OsBGOApggL4IBmMUYCARAAIDmA1gK4DGYIxMAXgHp2cEDjT0A3MFCZc+IsWlA|▶ Try it live in Instacode}
+ */
+export const isCallable = Type.isCallable;
+

package/src/geometry/math3d.mjs

@@ -70,3 +70,167 @@ export const getRotationMatrixFromVectors = (u, v) => {
   return axisAngleToMatrix4(axis, angle);
 };
 
+export const normalizeQuat = (q) => {
+  const len = Math.hypot(q.w, q.x, q.y, q.z);
+  if (len === 0) return { w: 1, x: 0, y: 0, z: 0 };
+  return {
+    w: q.w / len,
+    x: q.x / len,
+    y: q.y / len,
+    z: q.z / len
+  };
+};
+
+export const axisAngleToQuat = (axis, angle) => {
+  const [x, y, z] = normalize(axis);
+  const half = angle * 0.5;
+  const s = Math.sin(half);
+  return normalizeQuat({
+    w: Math.cos(half),
+    x: x * s,
+    y: y * s,
+    z: z * s
+  });
+};
+
+export const multiplyQuat = (a, b) => ({
+  w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,
+  x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
+  y: a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+  z: a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w
+});
+
+export const rotateVecByQuat = (v, q) => {
+  const [vx, vy, vz] = v;
+  const { w, x, y, z } = q;
+  const tx = 2 * (y * vz - z * vy);
+  const ty = 2 * (z * vx - x * vz);
+  const tz = 2 * (x * vy - y * vx);
+  return [
+    vx + w * tx + (y * tz - z * ty),
+    vy + w * ty + (z * tx - x * tz),
+    vz + w * tz + (x * ty - y * tx)
+  ];
+};
+
+export const matToQuat = (m) => {
+  const trace = m[0] + m[5] + m[10];
+  let w, x, y, z;
+  if (trace > 0) {
+    const s = 0.5 / Math.sqrt(trace + 1);
+    w = 0.25 / s;
+    x = (m[6] - m[9]) * s;
+    y = (m[8] - m[2]) * s;
+    z = (m[1] - m[4]) * s;
+  } else if (m[0] > m[5] && m[0] > m[10]) {
+    const s = 2 * Math.sqrt(1 + m[0] - m[5] - m[10]);
+    w = (m[6] - m[9]) / s;
+    x = 0.25 * s;
+    y = (m[4] + m[1]) / s;
+    z = (m[8] + m[2]) / s;
+  } else if (m[5] > m[10]) {
+    const s = 2 * Math.sqrt(1 + m[5] - m[0] - m[10]);
+    w = (m[8] - m[2]) / s;
+    x = (m[4] + m[1]) / s;
+    y = 0.25 * s;
+    z = (m[6] + m[9]) / s;
+  } else {
+    const s = 2 * Math.sqrt(1 + m[10] - m[0] - m[5]);
+    w = (m[1] - m[4]) / s;
+    x = (m[8] + m[2]) / s;
+    y = (m[6] + m[9]) / s;
+    z = 0.25 * s;
+  }
+  return normalizeQuat({ w, x, y, z });
+};
+
+export const quatToMat = (q) => {
+  const { w, x, y, z } = normalizeQuat(q);
+  const xx = x * x, yy = y * y, zz = z * z;
+  const xy = x * y, xz = x * z, yz = y * z;
+  const wx = w * x, wy = w * y, wz = w * z;
+  return [
+    1 - 2 * (yy + zz), 2 * (xy + wz), 2 * (xz - wy), 0,
+    2 * (xy - wz), 1 - 2 * (xx + zz), 2 * (yz + wx), 0,
+    2 * (xz + wy), 2 * (yz - wx), 1 - 2 * (xx + yy), 0,
+    0, 0, 0, 1
+  ];
+};
+
+export const slerp = (q1, q2, t) => {
+  let dot = q1.w * q2.w + q1.x * q2.x + q1.y * q2.y + q1.z * q2.z;
+  let q2n = q2;
+  if (dot < 0) {
+    q2n = { w: -q2.w, x: -q2.x, y: -q2.y, z: -q2.z };
+    dot = -dot;
+  }
+  if (dot > 0.9995) {
+    return normalizeQuat({
+      w: q1.w + t * (q2n.w - q1.w),
+      x: q1.x + t * (q2n.x - q1.x),
+      y: q1.y + t * (q2n.y - q1.y),
+      z: q1.z + t * (q2n.z - q1.z)
+    });
+  }
+  const theta = Math.acos(Math.max(-1, Math.min(1, dot)));
+  const sinTheta = Math.sin(theta);
+  const a = Math.sin((1 - t) * theta) / sinTheta;
+  const b = Math.sin(t * theta) / sinTheta;
+  return {
+    w: a * q1.w + b * q2n.w,
+    x: a * q1.x + b * q2n.x,
+    y: a * q1.y + b * q2n.y,
+    z: a * q1.z + b * q2n.z
+  };
+};
+
+export const matToEulerYXZ = (m) => {
+  if (!m || m.length < 16) return { pitch: 0, yaw: 0, roll: 0 };
+  const m11 = m[0], m13 = m[8];
+  const m21 = m[1], m22 = m[5], m23 = m[9];
+  const m31 = m[2], m33 = m[10];
+
+  const clamp = (v) => Math.max(-1, Math.min(1, v));
+  const x = Math.asin(-clamp(m23));
+  let y, z;
+  if (Math.abs(m23) < 0.9999999) {
+    y = Math.atan2(m13, m33);
+    z = Math.atan2(m21, m22);
+  } else {
+    y = Math.atan2(-m31, m11);
+    z = 0;
+  }
+  const radToDeg = 180 / Math.PI;
+  return {
+    pitch: x * radToDeg,
+    yaw: y * radToDeg,
+    roll: z * radToDeg
+  };
+};
+
+export const eulerYXZToQuat = (pitchDeg, yawDeg, rollDeg) => {
+  const degToRad = Math.PI / 180;
+  const hx = (pitchDeg * degToRad) * 0.5;
+  const hy = (yawDeg * degToRad) * 0.5;
+  const hz = (rollDeg * degToRad) * 0.5;
+
+  const c1 = Math.cos(hx), s1 = Math.sin(hx);
+  const c2 = Math.cos(hy), s2 = Math.sin(hy);
+  const c3 = Math.cos(hz), s3 = Math.sin(hz);
+
+  return normalizeQuat({
+    w: c1 * c2 * c3 + s1 * s2 * s3,
+    x: s1 * c2 * c3 + c1 * s2 * s3,
+    y: c1 * s2 * c3 - s1 * c2 * s3,
+    z: c1 * c2 * s3 - s1 * s2 * c3
+  });
+};
+
+export const applyScreenDragQuat = (currentQuat, dx, dy, sensitivity = 0.007) => {
+  const qY = axisAngleToQuat([0, 1, 0], dx * sensitivity);
+  const qX = axisAngleToQuat([1, 0, 0], dy * sensitivity);
+  const qDelta = multiplyQuat(qX, qY);
+  return normalizeQuat(multiplyQuat(qDelta, currentQuat));
+};
+
+