@treelocator/runtime 0.3.2 → 0.4.0

package/dist/dejitter/recorder.js

@@ -0,0 +1,908 @@
+// @ts-nocheck
+/**
+ * Dejitter — Animation frame recorder & jank detector (vendored)
+ *
+ * Ported from dejitter/recorder.js as an ES module factory.
+ * Records every rAF at full speed, then downsamples intelligently on getData().
+ */
+
+export function createDejitterRecorder() {
+  const DEFAULT_CONFIG = {
+    selector: '*',
+    props: ['opacity', 'transform'],
+    sampleRate: 15,
+    maxDuration: 10000,
+    minTextLength: 0,
+    mutations: false,
+    idleTimeout: 2000,
+    thresholds: {
+      jitter: {
+        minDeviation: 1,
+        maxDuration: 1000,
+        highSeverity: 20,
+        medSeverity: 5
+      },
+      shiver: {
+        minReversals: 5,
+        minDensity: 0.3,
+        highDensity: 0.7,
+        medDensity: 0.5,
+        minDelta: 0.01
+      },
+      jump: {
+        medianMultiplier: 10,
+        minAbsolute: 50,
+        highMultiplier: 50,
+        medMultiplier: 20
+      },
+      stutter: {
+        velocityRatio: 0.3,
+        maxFrames: 3,
+        minVelocity: 0.5
+      },
+      stuck: {
+        minStillFrames: 3,
+        maxDelta: 0.5,
+        minSurroundingVelocity: 1,
+        highDuration: 500,
+        medDuration: 200
+      },
+      outlier: {
+        ratioThreshold: 3
+      }
+    }
+  };
+  let config = {
+    ...DEFAULT_CONFIG
+  };
+  let recording = false;
+  let startTime = 0;
+  let rafId = null;
+  let stopTimer = null;
+  let mutationObserver = null;
+  let onStopCallbacks = [];
+  let lastSeen = new Map();
+  let rawFrames = [];
+  let lastChangeTime = 0;
+  let hasSeenChange = false;
+  let mutations = [];
+  let nextElemId = 0;
+  function elemId(el) {
+    if (!el.__dj_id) {
+      el.__dj_id = `e${nextElemId++}`;
+      el.__dj_label = {
+        tag: el.tagName.toLowerCase(),
+        cls: (typeof el.className === 'string' ? el.className : '').slice(0, 80),
+        text: (el.textContent || '').trim().slice(0, 60)
+      };
+    }
+    return el.__dj_id;
+  }
+  function readProps(el) {
+    const out = {};
+    const computed = getComputedStyle(el);
+    for (const p of config.props) {
+      if (p === 'boundingRect') {
+        const r = el.getBoundingClientRect();
+        out['rect.x'] = Math.round(r.x);
+        out['rect.y'] = Math.round(r.y);
+        out['rect.w'] = Math.round(r.width);
+        out['rect.h'] = Math.round(r.height);
+      } else if (p === 'scroll') {
+        out['scrollTop'] = Math.round(el.scrollTop);
+        out['scrollHeight'] = Math.round(el.scrollHeight);
+      } else if (p === 'textContent') {
+        out['textLen'] = (el.textContent || '').length;
+      } else {
+        out[p] = computed.getPropertyValue(p);
+      }
+    }
+    return out;
+  }
+  function computeDelta(id, current) {
+    const prev = lastSeen.get(id);
+    if (!prev) {
+      lastSeen.set(id, {
+        ...current
+      });
+      return current;
+    }
+    const delta = {};
+    let changed = false;
+    for (const [k, v] of Object.entries(current)) {
+      if (prev[k] !== v) {
+        delta[k] = v;
+        prev[k] = v;
+        changed = true;
+      }
+    }
+    return changed ? delta : null;
+  }
+  function sampleAll() {
+    const t = Math.round(performance.now() - startTime);
+    const elements = document.querySelectorAll(config.selector);
+    const frameDelta = [];
+    elements.forEach(el => {
+      if (config.minTextLength > 0) {
+        if ((el.textContent || '').trim().length < config.minTextLength) return;
+      }
+      const id = elemId(el);
+      const current = readProps(el);
+      const delta = computeDelta(id, current);
+      if (delta) {
+        frameDelta.push({
+          id,
+          ...delta
+        });
+      }
+    });
+    if (frameDelta.length > 0) {
+      rawFrames.push({
+        t,
+        changes: frameDelta
+      });
+      if (rawFrames.length > 1) hasSeenChange = true;
+      lastChangeTime = performance.now();
+    }
+  }
+  function loop() {
+    if (!recording) return;
+    if (config.idleTimeout > 0 && hasSeenChange) {
+      if (performance.now() - lastChangeTime >= config.idleTimeout) {
+        api.stop();
+        return;
+      }
+    }
+    sampleAll();
+    rafId = requestAnimationFrame(loop);
+  }
+  function startMutationObserver() {
+    if (!config.mutations) return;
+    mutationObserver = new MutationObserver(muts => {
+      if (!recording) return;
+      const t = Math.round(performance.now() - startTime);
+      lastChangeTime = performance.now();
+      hasSeenChange = true;
+      for (const m of muts) {
+        if (m.type === 'childList') {
+          for (const node of m.addedNodes) {
+            if (node.nodeType === 3) {
+              const text = node.textContent?.trim();
+              if (text) mutations.push({
+                t,
+                type: 'text+',
+                text: text.slice(0, 120),
+                parent: m.target.tagName?.toLowerCase()
+              });
+            } else if (node.nodeType === 1) {
+              const text = (node.textContent || '').trim().slice(0, 80);
+              mutations.push({
+                t,
+                type: 'node+',
+                tag: node.tagName.toLowerCase(),
+                text
+              });
+            }
+          }
+          for (const node of m.removedNodes) {
+            if (node.nodeType === 1) {
+              mutations.push({
+                t,
+                type: 'node-',
+                tag: node.tagName.toLowerCase(),
+                text: (node.textContent || '').trim().slice(0, 40)
+              });
+            }
+          }
+        } else if (m.type === 'characterData') {
+          const text = m.target.textContent?.trim();
+          if (text) mutations.push({
+            t,
+            type: 'text~',
+            text: text.slice(0, 120),
+            parent: m.target.parentElement?.tagName?.toLowerCase()
+          });
+        }
+      }
+    });
+    mutationObserver.observe(document.body, {
+      childList: true,
+      subtree: true,
+      characterData: true
+    });
+  }
+
+  // --- Downsampling ---
+
+  function downsample() {
+    if (rawFrames.length === 0) return [];
+    const duration = rawFrames[rawFrames.length - 1].t;
+    const targetFrames = Math.max(1, Math.round(duration / 1000 * config.sampleRate));
+    const changeIndex = new Map();
+    for (let fi = 0; fi < rawFrames.length; fi++) {
+      const frame = rawFrames[fi];
+      for (const change of frame.changes) {
+        const {
+          id,
+          ...props
+        } = change;
+        for (const [prop, value] of Object.entries(props)) {
+          const key = `${id}.${prop}`;
+          if (!changeIndex.has(key)) changeIndex.set(key, []);
+          changeIndex.get(key).push({
+            frameIdx: fi,
+            t: frame.t,
+            value
+          });
+        }
+      }
+    }
+    const outputEvents = [];
+    for (const [key, changes] of changeIndex.entries()) {
+      const dotIdx = key.indexOf('.');
+      const id = key.slice(0, dotIdx);
+      const prop = key.slice(dotIdx + 1);
+      if (changes.length === 0) continue;
+      if (changes.length <= targetFrames) {
+        for (const c of changes) {
+          outputEvents.push({
+            t: c.t,
+            id,
+            prop,
+            value: c.value
+          });
+        }
+      } else {
+        for (let i = 0; i < targetFrames; i++) {
+          const srcIdx = Math.round(i / (targetFrames - 1) * (changes.length - 1));
+          const c = changes[srcIdx];
+          outputEvents.push({
+            t: c.t,
+            id,
+            prop,
+            value: c.value
+          });
+        }
+      }
+    }
+    outputEvents.sort((a, b) => a.t - b.t);
+    const frames = [];
+    let currentFrame = null;
+    for (const evt of outputEvents) {
+      if (!currentFrame || currentFrame.t !== evt.t) {
+        currentFrame = {
+          t: evt.t,
+          changes: []
+        };
+        frames.push(currentFrame);
+      }
+      let elemChange = currentFrame.changes.find(c => c.id === evt.id);
+      if (!elemChange) {
+        elemChange = {
+          id: evt.id
+        };
+        currentFrame.changes.push(elemChange);
+      }
+      elemChange[evt.prop] = evt.value;
+    }
+    return frames;
+  }
+  function buildElementMap() {
+    const elements = {};
+    const seenIds = new Set();
+    for (const f of rawFrames) {
+      for (const c of f.changes) seenIds.add(c.id);
+    }
+    document.querySelectorAll('*').forEach(el => {
+      if (el.__dj_id && seenIds.has(el.__dj_id)) {
+        elements[el.__dj_id] = el.__dj_label || {
+          tag: el.tagName.toLowerCase(),
+          text: (el.textContent || '').trim().slice(0, 60)
+        };
+      }
+    });
+    return elements;
+  }
+  function buildPropStats() {
+    const stats = {};
+    const duration = rawFrames.length ? rawFrames[rawFrames.length - 1].t : 0;
+    const targetFrames = Math.max(1, Math.round(duration / 1000 * config.sampleRate));
+    for (const f of rawFrames) {
+      for (const change of f.changes) {
+        const {
+          id,
+          ...props
+        } = change;
+        for (const prop of Object.keys(props)) {
+          const key = `${id}.${prop}`;
+          if (!stats[key]) stats[key] = {
+            elem: id,
+            prop,
+            raw: 0
+          };
+          stats[key].raw++;
+        }
+      }
+    }
+    for (const s of Object.values(stats)) {
+      if (s.raw === 0) {
+        s.mode = 'dropped';
+        s.output = 0;
+      } else if (s.raw <= targetFrames) {
+        s.mode = 'anomaly';
+        s.output = s.raw;
+      } else {
+        s.mode = 'sampled';
+        s.output = targetFrames;
+      }
+    }
+    return {
+      targetFrames,
+      props: Object.values(stats)
+    };
+  }
+
+  // --- Analysis ---
+
+  function getTimeline(eId, prop) {
+    const timeline = [];
+    for (const frame of rawFrames) {
+      for (const c of frame.changes) {
+        if (c.id === eId && c[prop] !== undefined) {
+          timeline.push({
+            t: frame.t,
+            value: c[prop]
+          });
+        }
+      }
+    }
+    return timeline;
+  }
+  function extractNumeric(value) {
+    if (value === 'none' || value === '' || value === 'auto') return 0;
+    const matrixMatch = String(value).match(/^matrix\(([^)]+)\)$/);
+    if (matrixMatch) {
+      const parts = matrixMatch[1].split(',').map(Number);
+      const tx = parts[4] || 0;
+      const ty = parts[5] || 0;
+      return Math.abs(tx) > Math.abs(ty) ? tx : ty;
+    }
+    const num = parseFloat(value);
+    return isNaN(num) ? null : num;
+  }
+  function detectBounce(timeline) {
+    if (timeline.length < 3) return null;
+    const first = timeline[0].value;
+    const last = timeline[timeline.length - 1].value;
+    if (first !== last) return null;
+    const firstNum = extractNumeric(first);
+    if (firstNum === null) return null;
+    let peakDeviation = 0;
+    let peakT = 0;
+    let peakValue = first;
+    for (const {
+      t,
+      value
+    } of timeline) {
+      const num = extractNumeric(value);
+      if (num === null) continue;
+      const deviation = Math.abs(num - firstNum);
+      if (deviation > peakDeviation) {
+        peakDeviation = deviation;
+        peakT = t;
+        peakValue = value;
+      }
+    }
+    if (peakDeviation === 0) return null;
+    return {
+      restValue: first,
+      peak: peakValue,
+      peakDeviation: Math.round(peakDeviation * 10) / 10,
+      peakT,
+      startT: timeline[0].t,
+      endT: timeline[timeline.length - 1].t,
+      duration: timeline[timeline.length - 1].t - timeline[0].t
+    };
+  }
+  function detectOutliers(propStats) {
+    const byElem = {};
+    for (const p of propStats.props) {
+      if (!byElem[p.elem]) byElem[p.elem] = [];
+      byElem[p.elem].push(p);
+    }
+    const outliers = [];
+    for (const [, props] of Object.entries(byElem)) {
+      if (props.length < 2) continue;
+      const counts = props.map(p => p.raw).sort((a, b) => a - b);
+      const median = counts[Math.floor(counts.length / 2)];
+      for (const p of props) {
+        if (p.raw <= 1) continue;
+        const ratio = median > 0 ? p.raw / median : p.raw;
+        const rt = config.thresholds.outlier.ratioThreshold;
+        const isOutlier = (ratio > rt || ratio < 1 / rt) && p.raw !== counts[counts.length - 1] && p.raw !== counts[0];
+        if (isOutlier) {
+          outliers.push({
+            ...p,
+            median,
+            ratio: Math.round(ratio * 10) / 10
+          });
+        }
+      }
+    }
+    return outliers;
+  }
+  function makeFinding(type, severity, elem, elemLabel, prop, description, extra) {
+    return {
+      type,
+      severity,
+      elem,
+      elemLabel,
+      prop,
+      description,
+      ...extra
+    };
+  }
+  function countReversals(numeric) {
+    let reversals = 0;
+    for (let i = 2; i < numeric.length; i++) {
+      const d1 = numeric[i - 1].val - numeric[i - 2].val;
+      const d2 = numeric[i].val - numeric[i - 1].val;
+      if (Math.abs(d1) > config.thresholds.shiver.minDelta && Math.abs(d2) > config.thresholds.shiver.minDelta && d1 * d2 < 0) {
+        reversals++;
+      }
+    }
+    return reversals;
+  }
+  function detectOutlierFindings(propStats, elements) {
+    const findings = [];
+    const outliers = detectOutliers(propStats);
+    for (const outlier of outliers) {
+      const timeline = getTimeline(outlier.elem, outlier.prop);
+      const bounce = detectBounce(timeline);
+      const label = elements[outlier.elem];
+      if (bounce) {
+        const jt = config.thresholds.jitter;
+        findings.push(makeFinding('jitter', bounce.peakDeviation > jt.highSeverity ? 'high' : bounce.peakDeviation > jt.medSeverity ? 'medium' : 'low', outlier.elem, label, outlier.prop, `${outlier.prop} bounces from ${bounce.restValue} to ${bounce.peak} and back over ${bounce.duration}ms at t=${bounce.startT}ms`, {
+          rawChanges: outlier.raw,
+          medianForElement: outlier.median,
+          bounce,
+          timeline
+        }));
+      } else {
+        findings.push(makeFinding('outlier', 'info', outlier.elem, label, outlier.prop, `${outlier.prop} changed ${outlier.raw}x while sibling props median is ${outlier.median}x`, {
+          rawChanges: outlier.raw,
+          medianForElement: outlier.median,
+          timeline
+        }));
+      }
+    }
+    for (const p of propStats.props) {
+      if (p.raw < 3) continue;
+      if (findings.some(f => f.elem === p.elem && f.prop === p.prop)) continue;
+      const timeline = getTimeline(p.elem, p.prop);
+      const bounce = detectBounce(timeline);
+      const jt = config.thresholds.jitter;
+      if (bounce && bounce.peakDeviation > jt.minDeviation && bounce.duration < jt.maxDuration) {
+        const isFlicker = p.prop === 'opacity';
+        findings.push(makeFinding(isFlicker ? 'flicker' : 'jitter', bounce.peakDeviation > jt.highSeverity ? 'high' : bounce.peakDeviation > jt.medSeverity ? 'medium' : 'low', p.elem, elements[p.elem], p.prop, `${p.prop} bounces from ${bounce.restValue} to ${bounce.peak} and back over ${bounce.duration}ms at t=${bounce.startT}ms`, {
+          rawChanges: p.raw,
+          bounce,
+          timeline
+        }));
+      }
+    }
+    return findings;
+  }
+  function detectShiverFindings(propStats, elements, existingFindings) {
+    const findings = [];
+    for (const p of propStats.props) {
+      if (p.raw < 10) continue;
+      if (existingFindings.some(f => f.elem === p.elem && f.prop === p.prop)) continue;
+      const timeline = getTimeline(p.elem, p.prop);
+      if (timeline.length < 10) continue;
+      const numeric = [];
+      for (const {
+        t,
+        value
+      } of timeline) {
+        const n = extractNumeric(value);
+        if (n !== null) numeric.push({
+          t,
+          val: n
+        });
+      }
+      if (numeric.length < 10) continue;
+      const reversals = countReversals(numeric);
+      const reversalDensity = reversals / (numeric.length - 2);
+      const st = config.thresholds.shiver;
+      if (reversalDensity > st.minDensity && reversals >= st.minReversals) {
+        const uniqueVals = [...new Set(numeric.map(n => Math.round(n.val * 10) / 10))];
+        const isTwoValueFight = uniqueVals.length <= 4;
+        const vals = numeric.map(n => n.val);
+        const amplitude = Math.round((Math.max(...vals) - Math.min(...vals)) * 10) / 10;
+        const hz = Math.round(reversals / ((numeric[numeric.length - 1].t - numeric[0].t) / 1000) * 10) / 10;
+        findings.push(makeFinding('shiver', reversalDensity > st.highDensity ? 'high' : reversalDensity > st.medDensity ? 'medium' : 'low', p.elem, elements[p.elem], p.prop, isTwoValueFight ? `${p.prop} oscillates between ${Math.min(...vals)} and ${Math.max(...vals)} at ${hz}Hz — two forces fighting (${Math.round(reversalDensity * 100)}% frames reverse)` : `${p.prop} shivers with ${reversals} direction reversals across ${numeric.length} frames (${Math.round(reversalDensity * 100)}% reversal rate, amplitude ${amplitude}, ${hz}Hz)`, {
+          rawChanges: p.raw,
+          shiver: {
+            reversals,
+            totalFrames: numeric.length,
+            reversalDensity: Math.round(reversalDensity * 1000) / 1000,
+            amplitude,
+            hz,
+            range: [Math.min(...vals), Math.max(...vals)],
+            uniqueValues: uniqueVals.length,
+            isTwoValueFight,
+            durationMs: Math.round(numeric[numeric.length - 1].t - numeric[0].t)
+          }
+        }));
+      }
+    }
+    return findings;
+  }
+  function detectJumpFindings(propStats, elements, existingFindings) {
+    const findings = [];
+    for (const p of propStats.props) {
+      if (p.raw < 3) continue;
+      if (existingFindings.some(f => f.elem === p.elem && f.prop === p.prop)) continue;
+      const timeline = getTimeline(p.elem, p.prop);
+      if (timeline.length < 3) continue;
+      const deltas = [];
+      for (let i = 1; i < timeline.length; i++) {
+        const prev = extractNumeric(timeline[i - 1].value);
+        const curr = extractNumeric(timeline[i].value);
+        if (prev === null || curr === null) continue;
+        deltas.push({
+          t: timeline[i].t,
+          delta: Math.abs(curr - prev),
+          from: timeline[i - 1].value,
+          to: timeline[i].value
+        });
+      }
+      if (deltas.length < 3) continue;
+      const sortedDeltas = deltas.map(d => d.delta).sort((a, b) => a - b);
+      const medianDelta = sortedDeltas[Math.floor(sortedDeltas.length / 2)];
+      if (medianDelta === 0) continue;
+      const jmpT = config.thresholds.jump;
+      for (const d of deltas) {
+        if (d.delta > medianDelta * jmpT.medianMultiplier && d.delta > jmpT.minAbsolute) {
+          findings.push(makeFinding('jump', d.delta > medianDelta * jmpT.highMultiplier ? 'high' : d.delta > medianDelta * jmpT.medMultiplier ? 'medium' : 'low', p.elem, elements[p.elem], p.prop, `${p.prop} jumps from ${d.from} to ${d.to} at t=${d.t}ms (${Math.round(d.delta)}px, typical step is ${Math.round(medianDelta * 10) / 10}px)`, {
+            rawChanges: p.raw,
+            jump: {
+              t: d.t,
+              from: d.from,
+              to: d.to,
+              magnitude: Math.round(d.delta),
+              medianDelta: Math.round(medianDelta * 10) / 10,
+              ratio: Math.round(d.delta / medianDelta)
+            }
+          }));
+        }
+      }
+    }
+    return findings;
+  }
+  function detectStutterFindings(propStats, elements, existingFindings) {
+    const findings = [];
+    const st = config.thresholds.stutter;
+    for (const p of propStats.props) {
+      if (p.raw < 6) continue;
+      if (existingFindings.some(f => f.elem === p.elem && f.prop === p.prop)) continue;
+      const timeline = getTimeline(p.elem, p.prop);
+      if (timeline.length < 6) continue;
+      const numeric = [];
+      for (const {
+        t,
+        value
+      } of timeline) {
+        const n = extractNumeric(value);
+        if (n !== null) numeric.push({
+          t,
+          val: n
+        });
+      }
+      if (numeric.length < 6) continue;
+      const deltas = [];
+      for (let i = 1; i < numeric.length; i++) {
+        deltas.push(numeric[i].val - numeric[i - 1].val);
+      }
+      const windowSize = 5;
+      let i = 0;
+      while (i < deltas.length) {
+        const winStart = Math.max(0, i - windowSize);
+        if (i - winStart < 2) {
+          i++;
+          continue;
+        }
+        let sum = 0;
+        for (let w = winStart; w < i; w++) sum += deltas[w];
+        const dominantDir = Math.sign(sum);
+        if (dominantDir === 0) {
+          i++;
+          continue;
+        }
+        if (deltas[i] !== 0 && Math.sign(deltas[i]) !== dominantDir) {
+          const reversalStart = i;
+          let reversalEnd = i;
+          while (reversalEnd + 1 < deltas.length && reversalEnd - reversalStart + 1 < st.maxFrames && deltas[reversalEnd + 1] !== 0 && Math.sign(deltas[reversalEnd + 1]) !== dominantDir) {
+            reversalEnd++;
+          }
+          const afterIdx = reversalEnd + 1;
+          if (afterIdx >= deltas.length || Math.sign(deltas[afterIdx]) !== dominantDir) {
+            i = reversalEnd + 1;
+            continue;
+          }
+          let reversalMag = 0;
+          for (let r = reversalStart; r <= reversalEnd; r++) {
+            reversalMag += Math.abs(deltas[r]);
+          }
+          const localStart = Math.max(0, reversalStart - windowSize);
+          const localEnd = Math.min(deltas.length - 1, reversalEnd + windowSize);
+          let localSum = 0;
+          let localCount = 0;
+          for (let l = localStart; l <= localEnd; l++) {
+            if (l >= reversalStart && l <= reversalEnd) continue;
+            localSum += Math.abs(deltas[l]);
+            localCount++;
+          }
+          const localVelocity = localCount > 0 ? localSum / localCount : 0;
+          if (localVelocity >= st.minVelocity) {
+            const ratio = reversalMag / localVelocity;
+            if (ratio >= st.velocityRatio) {
+              const reversalFrameCount = reversalEnd - reversalStart + 1;
+              const severity = ratio >= 1.0 ? 'high' : ratio >= 0.5 ? 'medium' : 'low';
+              const t = numeric[reversalStart + 1].t;
+              findings.push(makeFinding('stutter', severity, p.elem, elements[p.elem], p.prop, `${p.prop} reverses for ${reversalFrameCount} frame${reversalFrameCount > 1 ? 's' : ''} at t=${t}ms during smooth motion (reversal ${Math.round(reversalMag * 10) / 10}px vs local velocity ${Math.round(localVelocity * 10) / 10}px/frame, ratio ${Math.round(ratio * 100) / 100})`, {
+                rawChanges: p.raw,
+                stutter: {
+                  t,
+                  reversalFrames: reversalFrameCount,
+                  reversalMagnitude: Math.round(reversalMag * 10) / 10,
+                  localVelocity: Math.round(localVelocity * 10) / 10,
+                  ratio: Math.round(ratio * 100) / 100,
+                  dominantDirection: dominantDir > 0 ? 'increasing' : 'decreasing'
+                }
+              }));
+            }
+          }
+          i = reversalEnd + 1;
+        } else {
+          i++;
+        }
+      }
+    }
+    return findings;
+  }
+  function detectStuckFindings(propStats, elements, existingFindings) {
+    const findings = [];
+    const sk = config.thresholds.stuck;
+    for (const p of propStats.props) {
+      if (p.raw < 6) continue;
+      if (existingFindings.some(f => f.elem === p.elem && f.prop === p.prop)) continue;
+      const timeline = getTimeline(p.elem, p.prop);
+      if (timeline.length < 6) continue;
+      const numeric = [];
+      for (const {
+        t,
+        value
+      } of timeline) {
+        const n = extractNumeric(value);
+        if (n !== null) numeric.push({
+          t,
+          val: n
+        });
+      }
+      if (numeric.length < 6) continue;
+      const deltas = [];
+      for (let i = 1; i < numeric.length; i++) {
+        deltas.push(Math.abs(numeric[i].val - numeric[i - 1].val));
+      }
+      let i = 0;
+      while (i < deltas.length) {
+        if (deltas[i] > sk.maxDelta) {
+          i++;
+          continue;
+        }
+        const runStart = i;
+        while (i < deltas.length && deltas[i] <= sk.maxDelta) i++;
+        const runEnd = i - 1;
+        const stillCount = runEnd - runStart + 1;
+        if (stillCount < sk.minStillFrames) continue;
+        const windowSize = 5;
+        let surroundingSum = 0;
+        let surroundingCount = 0;
+        const beforeStart = Math.max(0, runStart - windowSize);
+        for (let b = beforeStart; b < runStart; b++) {
+          surroundingSum += deltas[b];
+          surroundingCount++;
+        }
+        const afterEnd = Math.min(deltas.length - 1, runEnd + windowSize);
+        for (let a = runEnd + 1; a <= afterEnd; a++) {
+          surroundingSum += deltas[a];
+          surroundingCount++;
+        }
+        if (surroundingCount === 0) continue;
+        const meanSurroundingVelocity = surroundingSum / surroundingCount;
+        if (meanSurroundingVelocity < sk.minSurroundingVelocity) continue;
+        const tStart = numeric[runStart].t;
+        const tEnd = numeric[runEnd + 1].t;
+        const duration = Math.round(tEnd - tStart);
+        const severity = duration >= sk.highDuration ? 'high' : duration >= sk.medDuration ? 'medium' : 'low';
+        findings.push(makeFinding('stuck', severity, p.elem, elements[p.elem], p.prop, `${p.prop} stalls for ${stillCount} frames (${duration}ms) at t=${Math.round(tStart)}ms while surrounding motion averages ${Math.round(meanSurroundingVelocity * 10) / 10}px/frame`, {
+          rawChanges: p.raw,
+          stuck: {
+            t: Math.round(tStart),
+            duration,
+            stillFrames: stillCount,
+            meanSurroundingVelocity: Math.round(meanSurroundingVelocity * 10) / 10,
+            stuckValue: numeric[runStart].val
+          }
+        }));
+      }
+    }
+    return findings;
+  }
+  function deduplicateShivers(findings) {
+    const shiverFindings = findings.filter(f => f.type === 'shiver');
+    const otherFindings = findings.filter(f => f.type !== 'shiver');
+    const shiverGroups = new Map();
+    for (const f of shiverFindings) {
+      const key = `${f.prop}|${f.shiver.hz}|${f.shiver.isTwoValueFight}`;
+      if (!shiverGroups.has(key)) shiverGroups.set(key, []);
+      shiverGroups.get(key).push(f);
+    }
+    const deduped = [];
+    for (const group of shiverGroups.values()) {
+      if (group.length === 1) {
+        deduped.push(group[0]);
+      } else {
+        group.sort((a, b) => b.shiver.amplitude - a.shiver.amplitude);
+        const rep = {
+          ...group[0]
+        };
+        rep.affectedElements = group.length;
+        rep.description += ` (affects ${group.length} elements)`;
+        deduped.push(rep);
+      }
+    }
+    return [...otherFindings, ...deduped];
+  }
+  function analyzeFindings() {
+    const propStats = buildPropStats();
+    const elements = buildElementMap();
+    let findings = detectOutlierFindings(propStats, elements);
+    findings = findings.concat(detectShiverFindings(propStats, elements, findings));
+    findings = findings.concat(detectJumpFindings(propStats, elements, findings));
+    findings = findings.concat(detectStutterFindings(propStats, elements, findings));
+    findings = findings.concat(detectStuckFindings(propStats, elements, findings));
+    findings = deduplicateShivers(findings);
+    const sevOrder = {
+      high: 0,
+      medium: 1,
+      low: 2,
+      info: 3
+    };
+    findings.sort((a, b) => sevOrder[a.severity] - sevOrder[b.severity]);
+    return findings;
+  }
+
+  // --- Public API ---
+
+  const api = {
+    configure(opts = {}) {
+      const {
+        thresholds: userThresholds,
+        ...rest
+      } = opts;
+      config = {
+        ...DEFAULT_CONFIG,
+        ...rest
+      };
+      if (userThresholds) {
+        config.thresholds = {
+          ...DEFAULT_CONFIG.thresholds
+        };
+        for (const key of Object.keys(userThresholds)) {
+          if (DEFAULT_CONFIG.thresholds[key]) {
+            config.thresholds[key] = {
+              ...DEFAULT_CONFIG.thresholds[key],
+              ...userThresholds[key]
+            };
+          }
+        }
+      }
+      return config;
+    },
+    start() {
+      rawFrames = [];
+      mutations = [];
+      lastSeen = new Map();
+      nextElemId = 0;
+      recording = true;
+      startTime = performance.now();
+      lastChangeTime = performance.now();
+      hasSeenChange = false;
+      onStopCallbacks = [];
+      startMutationObserver();
+      rafId = requestAnimationFrame(loop);
+      if (config.maxDuration > 0) {
+        stopTimer = setTimeout(() => api.stop(), config.maxDuration);
+      }
+      const elemCount = document.querySelectorAll(config.selector).length;
+      return `Recording ${elemCount} elements (outputRate=${config.sampleRate}/s, max=${config.maxDuration}ms, idle=${config.idleTimeout}ms, props=[${config.props}], mutations=${config.mutations})`;
+    },
+    stop() {
+      recording = false;
+      if (rafId) cancelAnimationFrame(rafId);
+      if (stopTimer) clearTimeout(stopTimer);
+      mutationObserver?.disconnect();
+      const msg = `Stopped. ${rawFrames.length} raw frames, ${mutations.length} mutation events.`;
+      for (const cb of onStopCallbacks) {
+        try {
+          cb();
+        } catch (e) {
+          console.error('[dejitter] onStop callback error:', e);
+        }
+      }
+      return msg;
+    },
+    onStop(callback) {
+      onStopCallbacks.push(callback);
+    },
+    getData() {
+      const samples = downsample();
+      const elements = buildElementMap();
+      const propStats = buildPropStats();
+      return {
+        config: {
+          ...config
+        },
+        duration: rawFrames.length ? rawFrames[rawFrames.length - 1].t : 0,
+        rawFrameCount: rawFrames.length,
+        outputFrameCount: samples.length,
+        mutationEvents: mutations.length,
+        propStats,
+        elements,
+        samples,
+        mutations
+      };
+    },
+    summary(json) {
+      const propStats = buildPropStats();
+      const elements = buildElementMap();
+      const byMode = {
+        anomaly: 0,
+        sampled: 0,
+        dropped: 0
+      };
+      for (const p of propStats.props) {
+        byMode[p.mode] = (byMode[p.mode] || 0) + 1;
+      }
+      const data = {
+        duration: rawFrames.length ? rawFrames[rawFrames.length - 1].t : 0,
+        rawFrameCount: rawFrames.length,
+        targetOutputFrames: propStats.targetFrames,
+        mutationEvents: mutations.length,
+        elementsTracked: Object.keys(elements).length,
+        propBreakdown: byMode
+      };
+      return json ? data : JSON.stringify(data, null, 2);
+    },
+    findings(json) {
+      const data = analyzeFindings().map(({
+        timeline,
+        ...rest
+      }) => rest);
+      return json ? data : JSON.stringify(data, null, 2);
+    },
+    getRaw() {
+      return {
+        rawFrames,
+        mutations
+      };
+    },
+    toJSON() {
+      return JSON.stringify(api.getData(), null, 2);
+    }
+  };
+  return api;
+}