@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/motion-probe.ts

@@ -0,0 +1,653 @@
+// F312.1 — the in-page motion probe.
+//
+// THE PROBE IS THE GROUND TRUTH; the video is the illustration. That ordering is
+// the whole point of F312 and it is the lesson of the night that produced it: I
+// diagnosed a scroll bug from source three times, each diagnosis internally
+// consistent and mutation-proven, and three of them made the product worse. What
+// none of them had was a measurement of the thing being complained about.
+//
+// The complaint is never "the view moved". It is "the view moved AND I DID NOT DO
+// IT". So the probe records both halves — the position, and when a real human
+// input last happened — because only the pair can tell a defect from normal use.
+
+/** One reading of the scroller, taken inside the page. */
+export interface MotionSample {
+  /** ms since the probe started. */
+  t: number;
+  /** scrollTop at that instant. */
+  top: number;
+  /** scrollHeight — a jump with a height change is content arriving, not a jump. */
+  height: number;
+  /** F312.7 — the viewport height, so `height - client` gives the MAXIMUM scrollTop.
+   *  Without it a move cannot be told apart from the browser CLAMPING scrollTop
+   *  after the content above shrank, which is a completely different cause with a
+   *  completely different fix. */
+  client: number;
+  /** How many rows are rendered; distinguishes a re-render from a scroll. */
+  rows: number;
+  /** The first row whose bottom clears the viewport top — "what he is looking at". */
+  firstRow: string | null;
+  /** F312.14 — WHERE that row sits, in px from the viewport top. Together with
+   *  `firstRow` this is what the eye actually sees; `top` alone is not. */
+  firstRowY: number;
+  /** F312.15 — every row currently on screen, with its offset. The FIRST row can
+   *  differ between two samples while the reader's own message has not moved, so
+   *  the comparison needs a row that exists in both. */
+  visible: { id: string | null; y: number }[];
+  /** F312.23 — THE READER'S OWN ROW, which is the only one the question is about.
+   *
+   *  `firstRow` is whatever the render window happens to start with and changes
+   *  identity on every prepend. The app remembers his place in localStorage under
+   *  `chat-anchor:<edge>:<channel>`; the probe reads the same key, so this costs
+   *  the product nothing and exposes nothing new on `window`.
+   *
+   *  `anchorY - anchorWant` is the whole question in one number: 0 means his row
+   *  did not move, whatever `top` did. It is the measurement `visibleShift` cannot
+   *  make, because that one needs a row present in BOTH samples and a jump larger
+   *  than the viewport guarantees there is none — blind exactly where it matters. */
+  anchorId: string | null;
+  /** Where his row actually sits, in px from the scroller's top. */
+  anchorY: number | null;
+  /** Where the app PROMISED to hold it — the stored `offset`. */
+  anchorWant: number | null;
+  /** `held` his row is rendered · `bottom` he is parked at the live end ·
+   *  `not-rendered` he has a place, it is outside the window · `none` no key.
+   *  `bottom` is deliberately NOT `none`: being at the live end IS a remembered
+   *  place, and collapsing the two would report "nothing to hold" for a reader
+   *  who has one. */
+  anchorState: 'held' | 'bottom' | 'not-rendered' | 'none';
+  /** ms since the last input that CAN legitimately move the view — a wheel, a
+   *  touch, an arrow/page key. */
+  sinceInput: number | null;
+  /** F312.5 — ms since the last KEYSTROKE into a field. Deliberately separate:
+   *  typing is input, and typing must NEVER move the view. Folding it into
+   *  `sinceInput` made the detector blind to the worst version of this defect —
+   *  the one where he is mid-sentence in a table cell and the ground moves. */
+  sinceTyping: number | null;
+  /** ms since the driver last acted, or null. Its own actions are not defects. */
+  sinceDriver: number | null;
+}
+
+/** A move nobody asked for. */
+export interface MotionFinding {
+  t: number;
+  from: number;
+  to: number;
+  /** Signed: negative means he was carried BACKWARDS, which is the worse direction. */
+  delta: number;
+  firstRowBefore: string | null;
+  firstRowAfter: string | null;
+  /** F312.23 — HOW FAR HIS OWN ROW SAT FROM WHERE THE APP PROMISED TO HOLD IT,
+   *  before and after. `null` when the anchor is not readable at that instant
+   *  (parked at the live end, outside the render window, or no key).
+   *
+   *  This is the measure `visibleShift` cannot make. That one needs a row present
+   *  in BOTH samples, so a jump larger than the viewport leaves it null — blind
+   *  exactly where the move is biggest. This one is per-sample and independent of
+   *  the pair, so a 1852px change in `top` with `anchorDrift` steady at 0 is
+   *  compensation that kept him still, and the same change with `anchorDrift`
+   *  jumping is a move. The recording that motivated this could not tell them
+   *  apart, and two opposite fixes both looked justified. */
+  anchorDriftBefore: number | null;
+  anchorDriftAfter: number | null;
+  /** Which of the four anchor states each sample was in, so a `null` drift is
+   *  never mistaken for "measured, and it was fine". */
+  anchorStateBefore: MotionSample['anchorState'];
+  anchorStateAfter: MotionSample['anchorState'];
+  /** F312.24 — DID THE VIEW MOVE, OR THE LAYOUT?
+   *
+   *  The spread (`max − min`) of how far each row present in BOTH samples moved.
+   *  Near 0 means every shared row travelled the same distance — the layout is
+   *  rigid and the VIEW scrolled. Large means they moved by different amounts, so
+   *  content between them changed height and the LAYOUT moved under him.
+   *
+   *  `null` with fewer than TWO shared rows, never 0: one row cannot tell the two
+   *  cases apart, and 0 would read as "the layout was rigid".
+   *
+   *  `visibleShift` asks how far the picture moved using ONE shared row; this
+   *  asks a different question of the same data and needs two. Both are reported,
+   *  because a ±24px jitter has the same `visibleShift` whichever mechanism
+   *  produced it, and the two need opposite fixes. */
+  layoutSpread: number | null;
+  /** True when the rendered row count changed too — content arrived, so the move
+   *  may be a consequence rather than a cause. Reported, never used to hide it. */
+  contentChanged: boolean;
+  /** F312.5 — he was TYPING when it happened. Not a separate defect: the same
+   *  move, in the circumstance where it costs the most. */
+  whileTyping: boolean;
+  /**
+   * F312.6 — WHY this move is (or is not) counted, and how long since his last
+   * scroll. Nothing is discarded any more.
+   *
+   * Christian's third case: "jeg scroller op for lige at læse noget og vupti så
+   * er den hoppet et nyt sted hen". That move lands SHORTLY AFTER his scroll —
+   * inside the momentum grace — so the first version dropped it silently. A
+   * dropped observation cannot be reviewed, and this is the same lesson as
+   * everything else tonight: classify, never discard.
+   */
+  cause: 'none' | 'his-scroll' | 'driver';
+  /** ms since his last scroll-intent at the moment of the move; null = never. */
+  sinceInput: number | null;
+  /**
+   * F312.7 — WAS IT A CLAMP? The content above shrank far enough that the old
+   * scrollTop no longer existed, and the browser pulled it down to the new
+   * maximum. That is a different defect with a different fix from "something
+   * called scrollTo", and the two are indistinguishable without this.
+   *
+   * True when the move was BACKWARDS onto the new maximum from a position that
+   * the shrink had just made impossible. A forward move is never a clamp, and
+   * neither is a backwards one from a position still inside the new range.
+   */
+  clamped: boolean;
+  /** scrollHeight − clientHeight, before and after. */
+  maxBefore: number;
+  maxAfter: number;
+  /**
+   * F312.14 — HOW FAR THE PICTURE MOVED, which is a different number from `delta`.
+   *
+   * Same row still at the top, same offset → 0: the reader saw nothing, however
+   * far scrollTop travelled. That is the normal case for an anchor holding a
+   * message steady while content is inserted above it, and calling it movement
+   * points the next fix at the one mechanism that is working.
+   *
+   * null when the top row CHANGED — then the picture certainly moved, and by more
+   * than a pixel count can express, so no number is offered rather than a
+   * misleading one.
+   */
+  visibleShift: number | null;
+  /** F312.15 — how many rows were rendered either side. A top row that changed
+   *  because rows were REMOVED above is the render window dropping the message
+   *  under the reader; one that changed with the count steady is something
+   *  scrolling him. Same symptom, opposite fix. */
+  rowsBefore: number;
+  rowsAfter: number;
+  /** Where the top row sat, either side — so a null visibleShift still shows its
+   *  working rather than only its verdict. */
+  firstRowYBefore: number;
+  firstRowYAfter: number;
+}
+
+export interface ProbeConfig {
+  /** CSS selector of the scroller. Omitted, the probe picks the tallest scrollable. */
+  selector?: string;
+  /** Sampling interval in ms. 50 = 20 Hz: fast enough to catch one flush, slow
+   *  enough that the probe is not itself the jank it is measuring. */
+  intervalMs?: number;
+  /** A row's stable identity attribute. */
+  rowAttr?: string;
+}
+
+/**
+ * The script injected into the page. Written as a string-returning function so it
+ * can be handed to `page.evaluate` without a bundler, and so the browser half is
+ * readable next to the Node half that interprets it.
+ *
+ * READ-ONLY. It attaches passive listeners and reads geometry; it never writes
+ * style, never scrolls, never forces a layout beyond the rect reads the sampling
+ * already needs. A probe that changes what it measures is worse than no probe.
+ */
+export function probeSource(cfg: ProbeConfig = {}): string {
+  const interval = cfg.intervalMs ?? 50;
+  const rowAttr = cfg.rowAttr ?? 'data-ev-uuid';
+  const sel = cfg.selector ? JSON.stringify(cfg.selector) : 'null';
+  return `(() => {
+  const SEL = ${sel};
+  const ROW = ${JSON.stringify(rowAttr)};
+  const pick = () => {
+    if (SEL) return document.querySelector(SEL);
+    // The tallest thing that can actually scroll. Deliberately not "the first
+    // overflow:auto": a page has several, and the one the human is reading is the
+    // one with content to spare.
+    let best = null, bestOver = 0;
+    for (const el of document.querySelectorAll('*')) {
+      const over = el.scrollHeight - el.clientHeight;
+      if (over > bestOver && el.clientHeight > 200) { best = el; bestOver = over; }
+    }
+    return best;
+  };
+  let el = pick();
+  const state = {
+    started: performance.now(),
+    lastInput: null,
+    lastTyping: null,
+    lastDriver: null,
+    samples: [],
+    selector: el ? (el.getAttribute('data-testid') ? '[data-testid="' + el.getAttribute('data-testid') + '"]' : el.tagName.toLowerCase()) : null,
+    error: el ? null : 'no scrollable element found',
+  };
+  window.__lensMotion = state;
+  // A DRIVER action stamps this; the Node half then knows the move was ours.
+  window.__lensDriverActed = () => { state.lastDriver = performance.now(); };
+  if (!el) return 'no-scroller';
+  // Passive + capture: we must not delay or alter the very interaction we measure.
+  // F312.5 — TWO CLOCKS, and the split is the whole correction.
+  //
+  // A wheel, a touch or an arrow key is a request to MOVE THE VIEW, so a move
+  // right after one is his and not a defect. A character typed into a field is
+  // input that must move NOTHING. Counting it as scroll-intent meant that while
+  // he was typing — continuously, one keystroke every ~150ms — every single move
+  // fell inside the grace window and the detector reported nothing at all. It was
+  // blind in exactly the case he described: "jeg kan ikke stå og svare på en
+  // tekst i et felt på en tabel uden at den rykker væk fra mig".
+  const NAV_KEYS = new Set(['ArrowUp','ArrowDown','PageUp','PageDown','Home','End',' ','Spacebar']);
+  const markScroll = () => { state.lastInput = performance.now(); };
+  const markType = () => { state.lastTyping = performance.now(); };
+  for (const ev of ['wheel', 'touchstart', 'touchmove', 'pointerdown'])
+    window.addEventListener(ev, markScroll, { capture: true, passive: true });
+  window.addEventListener('keydown', (e) => {
+    // A navigation key IN a text field still moves the caret, not the page — but
+    // outside one it scrolls. Editable target decides, which is the same question
+    // the browser itself asks.
+    const t = e.target;
+    const editable = t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.isContentEditable);
+    if (NAV_KEYS.has(e.key) && !editable) markScroll();
+    else markType();
+  }, { capture: true, passive: true });
+  // F312.14 — WHAT THE EYE SEES, not what scrollTop says.
+  //
+  // These are not the same quantity, and conflating them makes the probe report
+  // the CORRECT behaviour as a defect. When content is inserted above the
+  // viewport, holding the reader's message still REQUIRES scrollTop to change by
+  // exactly the inserted height — the number moves so that the picture does not.
+  // Measured 6 Sept: a run flagged eight 'prepend-hold' moves of −92px to −456px,
+  // every one of them the anchor doing its job.
+  //
+  // So the probe also records WHERE the first visible row sits. Same row at the
+  // same offset = the reader saw nothing move, whatever scrollTop did.
+  // F312.23 — read the reader's OWN remembered place out of the app's storage.
+  // Several channels can each have a key; the right one is the channel currently
+  // rendered, so the uuid must be present in the DOM. Picking the first key would
+  // silently report ANOTHER conversation's row and look exactly like working.
+  const anchorAt = () => {
+    let sawBottom = false;
+    let sawPlace = false;
+    try {
+      for (let i = 0; i < localStorage.length; i++) {
+        const k = localStorage.key(i);
+        if (!k || k.indexOf('chat-anchor:') !== 0) continue;
+        let v = null;
+        try { v = JSON.parse(localStorage.getItem(k)); } catch (e) { continue; }
+        if (!v) continue;
+        if (v.bottom) { sawBottom = true; continue; }
+        if (!v.uuid) continue;
+        sawPlace = true;
+        const row = el.querySelector('[' + ROW + '="' + (window.CSS && CSS.escape ? CSS.escape(v.uuid) : v.uuid) + '"]');
+        if (!row) continue;
+        return {
+          id: v.uuid,
+          y: Math.round(row.getBoundingClientRect().top - el.getBoundingClientRect().top),
+          want: typeof v.offset === 'number' ? -Math.round(v.offset) : 0,
+          state: 'held',
+        };
+      }
+    } catch (e) { /* storage can throw in a private context; report none */ }
+    if (sawPlace) return { id: null, y: null, want: null, state: 'not-rendered' };
+    if (sawBottom) return { id: null, y: null, want: null, state: 'bottom' };
+    return { id: null, y: null, want: null, state: 'none' };
+  };
+  const firstRowAt = () => {
+    const top = el.getBoundingClientRect().top;
+    const bottom = top + el.clientHeight;
+    const rows = el.querySelectorAll('[' + ROW + ']');
+    // F312.15 — record SEVERAL visible rows, not only the first.
+    //
+    // Comparing "the first visible row before" against "the first visible row
+    // after" answers a different question from the one being asked. Those can be
+    // two different messages while the one the reader is actually looking at has
+    // not moved a pixel — a message above it merely grew into view. The honest
+    // measure is: take a row present in BOTH samples and ask where it went.
+    const vis = [];
+    let first = { id: null, y: 0 };
+    for (let i = 0; i < rows.length; i++) {
+      const b = rows[i].getBoundingClientRect();
+      if (b.bottom <= top + 4) continue;
+      if (b.top >= bottom) break;
+      const id = rows[i].getAttribute(ROW);
+      const y = Math.round(b.top - top);
+      if (first.id === null) first = { id: id, y: y };
+      if (vis.length < 8) vis.push({ id: id, y: y });
+    }
+    return { id: first.id, y: first.y, vis: vis };
+  };
+  // F312.16 — WHEN DID IT LAND? A marker planted in the fed message is looked for
+  // on every tick, and the first tick that sees it is its arrival. Paired with the
+  // send time on the Node side this gives the end-to-end latency of the live
+  // stream — and, more to the point here, a defensible answer to "was the surface
+  // exercised by REAL agent output, or only by its own echo?".
+  const seen = {};
+  window.__lensMarkers = seen;
+  const scanMarkers = (nowMs) => {
+    const t = el.textContent || '';
+    let i = t.indexOf('LENSPROBE-');
+    while (i !== -1) {
+      const m = t.slice(i, i + 24).split(/[^A-Za-z0-9-]/)[0];
+      if (m && seen[m] === undefined) seen[m] = Math.round(nowMs - state.started);
+      i = t.indexOf('LENSPROBE-', i + 10);
+    }
+  };
+  const tick = () => {
+    // F312.22 — RE-RESOLVE A REPLACED SCROLLER.
+    //
+    // The probe held the element it found at start. A tab switch REPLACES that
+    // node, so from that moment the probe was measuring a detached element:
+    // scrollHeight 0, no samples, and the return — the thing being measured —
+    // was invisible. Measured 6 Sept on the first tab-switch run that actually
+    // ran: heightEnd 0, and nothing recorded after the switch.
+    //
+    // Only when the node has genuinely left the document. A live element is
+    // never swapped, so this cannot make the probe follow the wrong scroller
+    // mid-measurement; and if the re-pick finds nothing, the old reference is
+    // kept rather than replaced with null, so a transient re-render does not
+    // blind the run.
+    if (el && !el.isConnected) {
+      const again = pick();
+      if (again) el = again;
+    }
+    const now = performance.now();
+    scanMarkers(now);
+    const fr = firstRowAt();
+    const an = anchorAt();
+    state.samples.push({
+      t: Math.round(now - state.started),
+      top: Math.round(el.scrollTop),
+      height: Math.round(el.scrollHeight),
+      client: Math.round(el.clientHeight),
+      rows: el.querySelectorAll('[' + ROW + ']').length,
+      firstRow: fr.id,
+      firstRowY: fr.y,
+      visible: fr.vis,
+      anchorId: an.id,
+      anchorY: an.y,
+      anchorWant: an.want,
+      anchorState: an.state,
+      sinceInput: state.lastInput == null ? null : Math.round(now - state.lastInput),
+      sinceTyping: state.lastTyping == null ? null : Math.round(now - state.lastTyping),
+      sinceDriver: state.lastDriver == null ? null : Math.round(now - state.lastDriver),
+    });
+  };
+  tick();
+  state.timer = setInterval(tick, ${interval});
+  return 'ok';
+})()`;
+}
+
+/** Read the samples back out. */
+export const PROBE_READ = `(() => {
+  const s = window.__lensMotion;
+  if (!s) return { error: 'probe never started', samples: [] };
+  if (s.timer) clearInterval(s.timer);
+  // F312.12 — bring the page's own scroll ledger back, REBASED onto the probe's
+  // clock so an entry can be lined up with the millisecond of a finding. Absent
+  // on a surface that does not keep one; that is reported as an empty list, never
+  // as a failure, since most surfaces have nothing to declare.
+  // Entries from BEFORE the probe started keep a negative t rather than being
+  // dropped: a scroll the page performed while it was loading is still evidence,
+  // and silently discarding it makes an empty ledger ambiguous between "nothing
+  // wrote" and "everything wrote too early to count".
+  const ledger = Array.isArray(window.__chatScrollLog)
+    ? window.__chatScrollLog.map((n) => ({ ...n, t: Math.round(n.t - s.started) }))
+    : null;
+  // null = the surface keeps NO ledger (the property was never created).
+  // [] = it keeps one and nothing wrote to it. Those are different answers and
+  // collapsing them is how a broken read looks like a clean result.
+  return {
+    error: s.error,
+    selector: s.selector,
+    samples: s.samples,
+    ledger,
+    markers: window.__lensMarkers || {},
+  };
+})()`;
+
+/** F312.12 — one entry from the page's own scroll ledger, on the probe's clock. */
+export interface ScrollNote {
+  t: number;
+  why: string;
+  from: number;
+  to: number;
+  force: boolean;
+  refused?: string;
+}
+
+export interface FindOptions {
+  /** A move smaller than this is noise — sub-pixel settling, a scrollbar, a font. */
+  minDeltaPx?: number;
+  /**
+   * How long after a real input a move is still HIS. Momentum on a trackpad keeps
+   * moving the page for a while after the last wheel event, and reporting that as
+   * a defect would bury the real ones.
+   */
+  inputGraceMs?: number;
+  /** The same grace for the driver's own actions. */
+  driverGraceMs?: number;
+}
+
+/**
+ * Moves that no input preceded.
+ *
+ * THE NEGATIVE CONTROL IS BUILT IN, not bolted on: a move within `inputGraceMs`
+ * of a human input, or `driverGraceMs` of our own driving, is NOT a finding. A
+ * detector that reports every move reports itself, and would have "found" a bug
+ * in every recording ever made — the most expensive kind of green.
+ */
+/** F312.23 — how far his row is from where the app said it would hold it.
+ *
+ *  `null` whenever the anchor is not readable, and that is not the same as 0: a
+ *  reader at the live end, or one whose message is outside the render window, has
+ *  a place we simply cannot see this instant. Returning 0 there would report "his
+ *  row did not move" for a row nobody looked at. */
+export function anchorDrift(s: MotionSample): number | null {
+  if (s.anchorState !== 'held') return null;
+  if (s.anchorY == null || s.anchorWant == null) return null;
+  return s.anchorY - s.anchorWant;
+}
+
+export function findUncausedMoves(samples: MotionSample[], opts: FindOptions = {}): MotionFinding[] {
+  const minDelta = opts.minDeltaPx ?? 24;
+  const inputGrace = opts.inputGraceMs ?? 700;
+  const driverGrace = opts.driverGraceMs ?? 900;
+  const out: MotionFinding[] = [];
+  for (let i = 1; i < samples.length; i++) {
+    const a = samples[i - 1]!;
+    const b = samples[i]!;
+    const delta = b.top - a.top;
+    if (Math.abs(delta) < minDelta) continue;
+    // CLASSIFIED, NOT DROPPED (F312.6). His finger and ours are still not
+    // defects — but they are RECORDED as such, so "he had just stopped
+    // scrolling" is visible instead of invisible.
+    //
+    // NOTE what does not appear here: `sinceTyping`. Typing is not a reason to
+    // move the view, so it can never excuse one — it only makes the move worse,
+    // which `whileTyping` records.
+    const cause: MotionFinding['cause'] =
+      b.sinceDriver != null && b.sinceDriver <= driverGrace
+        ? 'driver'
+        : b.sinceInput != null && b.sinceInput <= inputGrace
+          ? 'his-scroll'
+          : 'none';
+    out.push({
+      cause,
+      sinceInput: b.sinceInput,
+      t: b.t,
+      from: a.top,
+      to: b.top,
+      delta,
+      firstRowBefore: a.firstRow,
+      firstRowAfter: b.firstRow,
+      anchorDriftBefore: anchorDrift(a),
+      anchorDriftAfter: anchorDrift(b),
+      anchorStateBefore: a.anchorState,
+      anchorStateAfter: b.anchorState,
+      contentChanged: a.rows !== b.rows || a.height !== b.height,
+      whileTyping: b.sinceTyping != null && b.sinceTyping <= 1500,
+      maxBefore: a.height - a.client,
+      maxAfter: b.height - b.client,
+      visibleShift: sharedShift(a, b),
+      layoutSpread: layoutSpread(a, b),
+      rowsBefore: a.rows,
+      rowsAfter: b.rows,
+      firstRowYBefore: a.firstRowY,
+      firstRowYAfter: b.firstRowY,
+      // A CLAMP is the browser having nowhere to put you: the content above
+      // shrank, so the position you were at STOPPED EXISTING and you were pushed
+      // back to the new bottom. That means it is necessarily BACKWARDS and it
+      // requires `from` to be past the new maximum.
+      //
+      // The first version only asked "did the max fall, and are you at it now?",
+      // which is true of ANY move that lands at the bottom. Measured 6 Sept: a
+      // +5806px yank from a reading position down to the bottom — the single
+      // worst finding in the run — was labelled a clamp while the maximum had
+      // moved 31px. A clamp cannot account for more travel than the maximum lost,
+      // and calling a forced scroll a clamp points the next diagnosis at the
+      // wrong mechanism entirely.
+      clamped: a.top > b.height - b.client && b.top >= b.height - b.client - 2 && delta < 0,
+    });
+  }
+  return out;
+}
+
+/**
+ * F312.15 — HOW FAR THE PICTURE MOVED, measured on a row that is on screen in
+ * BOTH samples.
+ *
+ * The first version compared the top row's identity, and answered "unknown"
+ * whenever it changed. That is too pessimistic in the exact case that matters:
+ * a message ABOVE the one being read can grow into view, making it the new top
+ * row, while the message under the reader's eye has not moved at all. Measured 6
+ * Sept — the anchor holding a message steady was reported as an unknown-sized
+ * jump nine times.
+ *
+ * So: find a row present on screen in both, and report where it went. Null only
+ * when they share NO row, which genuinely means the reader is looking at
+ * different content and no pixel count would describe it.
+ */
+/** F312.24 — how much the shared rows DISAGREE about how far they moved.
+ *
+ *  A pure scroll moves every row by the same amount, so the spread is 0. Content
+ *  above one of them growing moves them by different amounts, and the spread is
+ *  that growth. It is the one number that separates "the view moved" from "the
+ *  ground moved", and the drift column cannot: both produce the same drift.
+ *
+ *  Fewer than two shared rows is `null`. Returning 0 there would assert rigidity
+ *  from a sample that cannot see it. */
+export function layoutSpread(a: MotionSample, b: MotionSample): number | null {
+  const before = new Map<string, number>();
+  for (const v of a.visible) if (v.id) before.set(v.id, v.y);
+  const shifts: number[] = [];
+  for (const v of b.visible) {
+    if (!v.id) continue;
+    const y = before.get(v.id);
+    if (y == null) continue;
+    shifts.push(v.y - y);
+  }
+  if (shifts.length < 2) return null;
+  return Math.round(Math.max(...shifts) - Math.min(...shifts));
+}
+
+export function sharedShift(a: MotionSample, b: MotionSample): number | null {
+  const after = new Map<string, number>();
+  for (const r of b.visible ?? []) if (r.id != null) after.set(r.id, r.y);
+  for (const r of a.visible ?? []) {
+    if (r.id == null) continue;
+    const y = after.get(r.id);
+    if (y != null) return y - r.y;
+  }
+  return null;
+}
+
+/** The moves nobody caused. Still reported — classify, never discard (F312.6). */
+export function uncaused(findings: MotionFinding[]): MotionFinding[] {
+  return findings.filter((f) => f.cause === 'none');
+}
+
+/**
+ * F312.19 — WHAT A DEFECT ACTUALLY IS: nobody caused it AND the reader could see
+ * it.
+ *
+ * Raised by the trail session from a real run of ours. Two findings, both
+ * `cause: 'none'`, both scrollTop −92px — and both with `visible_shift` 0 and the
+ * top row at the same offset before and after. Content above the reading position
+ * had shrunk and the browser adjusted scrollTop to match. That is scroll
+ * anchoring doing its job perfectly, reported as a defect.
+ *
+ * Their sentence is the specification: the complaint is "the picture moved and I
+ * did not do it" — and there, the picture did not move. Two false ones a minute
+ * in an ordinary chat would drown the real one.
+ *
+ * `null` COUNTS AS VISIBLE, and that asymmetry is the load-bearing part: null
+ * means the two samples shared no row at all, so the reader is looking at
+ * different content and the move was as visible as a move can be. Treating an
+ * unknown as "not seen" would hide the largest jumps this tool exists to catch.
+ */
+export function defects(findings: MotionFinding[], minVisiblePx = 8): MotionFinding[] {
+  return findings.filter(
+    (f) => f.cause === 'none' && (f.visibleShift === null || Math.abs(f.visibleShift) > minVisiblePx),
+  );
+}
+
+/**
+ * F312.8 — WAS THE THING EVEN EXERCISED?
+ *
+ * Measured the hard way: two identical 120s recordings of the same build gave 4
+ * findings and then 0. Nothing was fixed in between — the second window simply
+ * had less arriving in the stream. A zero from a quiet window is indistinguishable
+ * from a zero from a fixed product, and reporting the first as the second is the
+ * false green this whole feature exists to prevent.
+ *
+ * So a run reports how much the surface actually CHANGED. A zero with no content
+ * events is "not exercised"; a zero with forty is a result.
+ */
+export interface Exercise {
+  /** Samples where the row count or the height changed — i.e. content arrived. */
+  contentEvents: number;
+  rowsStart: number;
+  rowsEnd: number;
+  heightStart: number;
+  heightEnd: number;
+  /** The honest verdict on whether a zero means anything. */
+  exercised: boolean;
+}
+
+export function measureExercise(samples: MotionSample[]): Exercise {
+  if (samples.length === 0)
+    return { contentEvents: 0, rowsStart: 0, rowsEnd: 0, heightStart: 0, heightEnd: 0, exercised: false };
+  let events = 0;
+  for (let i = 1; i < samples.length; i++) {
+    const a = samples[i - 1]!;
+    const b = samples[i]!;
+    if (a.rows !== b.rows || a.height !== b.height) events++;
+  }
+  const first = samples[0]!;
+  const last = samples[samples.length - 1]!;
+  return {
+    contentEvents: events,
+    rowsStart: first.rows,
+    rowsEnd: last.rows,
+    heightStart: first.height,
+    heightEnd: last.height,
+    // Deliberately strict, but on the RIGHT quantity. The first version required
+    // the row count to GROW — measured wrong: the render window drops old
+    // messages as new ones arrive, so a busy 120s window ended with FEWER rows
+    // (123 → 121) and the run reported itself as not exercised while 13 content
+    // events and 900px of growth had gone past. Height is the honest signal;
+    // rows are a window, not a total.
+    exercised: events >= 10 && last.height !== first.height,
+  };
+}
+
+/** Worst first — and BACKWARDS beats forwards at equal size, because being carried
+ *  into the past is the complaint that started this. An uncaused move always
+ *  outranks one he or the driver caused; the caused ones stay in the list so a
+ *  "vupti, den hoppede" right after a scroll is READABLE rather than dropped. */
+export function rankFindings(findings: MotionFinding[]): MotionFinding[] {
+  return [...findings].sort((x, y) => {
+    const own = (f: MotionFinding) => (f.cause === 'none' ? 1 : 0);
+    if (own(y) !== own(x)) return own(y) - own(x);
+    // Worst first: moving the ground while he is MID-SENTENCE beats everything.
+    const typing = (f: MotionFinding) => (f.whileTyping ? 1 : 0);
+    if (typing(y) !== typing(x)) return typing(y) - typing(x);
+    const back = (f: MotionFinding) => (f.delta < 0 ? 1 : 0);
+    if (back(y) !== back(x)) return back(y) - back(x);
+    return Math.abs(y.delta) - Math.abs(x.delta);
+  });
+}