Answers Eva's leg question (thread 0a496379): are the felt −240-class media
reflow snaps on scroll-up momentum-class (killed by w4a-gate-1), walk-blind
(RO-path, a separate leg), or SHRINK-class (needs Max's pre-realization band)?
Adds a committed media corpus + classifier so the answer is reproducible from
the tip on a fresh build, mirroring the jitter/fast-classify arm.
Corpus (e2eBridge `mediaCorpusBody`, channel `media-corpus`, 400 rows, 8 kinds).
Row-height error is MEDIA reserve-vs-true mismatch, not text mis-estimation,
from three in-source-verified divergence sources:
- Link-preview cards reserved flat at PREVIEW_CARD=70 but rendered taller (GROW).
- Width-clamp images: CORRECT dims, but the estimator hardcodes MEDIA_MAX_WIDTH=384
while render clamps to max-w-[min(24rem,100%)]; in a column < 384px the render is
width-limited shorter than reserved (SHRINK, no lying dim, no decode timing).
- Dim-mismatch images in BOTH directions: overstate height (SHRINK) and understate
(GROW), so the corpus CAN produce SHRINK — the GROW-dominant prediction is
falsifiable, not baked in.
No dim-less band: that path is pinned to a fixed 256px box (reserve==mount) and
provably cannot reflow. Images use a tiny inline PNG data-URL so they realize
without network. (Eva verified the mechanism chain independently in mainbase
2cc0eb53.)
Fixture (upscroll-media.perf.ts) clones the fast classifier verbatim — probeLen
append-count join, SKIP/GROW/SHRINK/UNATTRIBUTED discriminator, dev, ±2-frame
firedNear admission — and only:
- navigates to channel-media-corpus, then narrows the viewport to 450px so the
timeline column lands below 384px; asserts the measured media-container width
is < 384 so the width-clamp SHRINK source provably bites (else it fails loudly);
- adds a MEDIA-REFLOW CENSUS: for every above-anchor reflow (|signedShift|>3px),
whether it landed on a tracked in-band row and the worst (most-backward) rowMove
across it, collapsing a persistent gate-held reflow's per-rAF re-measure into one
run so a stuck 198px GROW isn't inflated into hundreds;
- asserts MEDIA LIVENESS (>=1 in-band reflow) so a zero-reversal result cannot be
a dead corpus; drops the fast arm's decomposition self-test (that re-proves the
gate mechanism the jitter arm already ratifies — off-charter here).
Result, fresh w4a-gate-1 build, BOTH engines, reproducible from this tip:
- Chromium: 0 reversals. 9 reflow runs (5 in-band), 7 GROW / 2 SHRINK. Every
in-band reflow worstRowMove >= 0 — incl. a persistent +198 GROW held 170 frames
at rowMove 0.0.
- WebKit: 0 reversals. 8 reflow runs (4 in-band), 6 GROW / 2 SHRINK. GROW runs
gate-SKIPed to rowMove 0.0; SHRINK runs (−14.5) fired-and-corrected to +0.5
(forward).
CLASSIFICATION: the media reserve-vs-true reflows are momentum/absorbed-class —
the landed w4a-gate-1 fix + correction eat them; not one renders a felt backward
snap on either engine. NOT walk-blind, NOT needing Max's pre-realization band.
Neither Dawn's GROW-likely nor Eva's SHRINK-likely prediction "wins" in the felt
sense: both classes fire, both are absorbed.
HONESTY BOUND: this is a deterministic proxy for media reflow, not a claim to
reproduce Tyler's exact frames. His live trackpad still owns acceptance; #1662
stays draft.
Co-authored-by: Tyler Longwell <tlongwell@block.xyz>
Signed-off-by: Tyler Longwell <tlongwell@block.xyz>
The mid-history correction's momentum-skip gate keyed on the raw
`scrollTop` delta since baseline. On WebKit, momentum is coalesced into
`scrollTop` on the compositor's own async clock, so a frame that PAINTED
still can read a large raw delta and wrongly skip a genuine above-anchor
reflow — the reversal survivor bin (the 204px-class lurch of #1662).
Rekey the gate onto the RENDERED scroll — the painted wheel motion this
frame — `renderedScroll = aboveShift - ΔtopOffset`: the anchor's painted
on-screen move with the reflow's own push removed, both terms read from
the painted DOM (getBoundingClientRect), not the possibly-ahead
`scrollTop`. A rendered-still frame now reads ~0 and the reflow is
corrected instead of dropped.
Because the gate now needs `aboveShift` to decide, the band walk runs
before the gate. To keep "under-correcting is invisible; the next quiet
frame catches up," `sumAboveAnchorShift` no longer refreshes the height
cache inline — it STAGES the refresh and returns `{ aboveShift, commit }`.
The caller applies `commit()` only past the gate, so a momentum skip
leaves the cache for the next frame; a kept correction refreshes it as
one indivisible pass (the "second observer no-ops" invariant is intact).
Arbiter contract, fresh w4a-gate-1 build, both engines:
- raf-correction HARD gate: Chromium 0 reversals, rAF fires 0 / RO 21
(RO sole writer); WebKit 2 reversals max 14.5px (<=34 quantum floor),
rAF fires 24 / RO no-op (residual 0.0). Ratified invariants hold.
- slow-scroll: 0 reversals both engines (felt low-velocity regime clean).
- fast-classify DECOMPOSITION self-test (WebKit): pure-reflow attempts
median |signedShift|=18.5 but median |renderedScroll|=0.0 — the reflow
does NOT leak into the gated quantity, and 19/28 fire. Pure-scroll
|renderedScroll| runs up to 28. The decomposition is proven, not
asserted. Guarded WebKit-only: on Chromium the rAF is the passive loser
observer (RO corrects first), so renderedScroll there tracks signedShift
by construction — characterized, not asserted.
KNOWN RESIDUAL (surfaced, not hidden): 2 WebKit survivors remain, but
they are a DIFFERENT class — signedShift=0.0 (the band walk sees no
above-anchor reflow) while the row still lurches 14.5px. The momentum-gate
survivors the rekey targeted are gone; these are cross-check/null-target
skips where the reflow is invisible to the band walk. Separate diagnosis.
Diagnostic-only `renderedScroll` is threaded through the shared result
type + emitted on the rAF probe so the fixture can prove the
decomposition; stripped/gated before merge per the file-size exit
condition. Raises the useAnchoredScroll.ts size exception 1180->1210 to
cover the arm (biome reflows the 4-prop returns); flagged in the override
comment for Eva as heavy-for-a-diagnostic.
Co-authored-by: Tyler Longwell <tlongwell@block.xyz>
Signed-off-by: Tyler Longwell <tlongwell@block.xyz>
Adds the discriminator Sami specced (thread 5b46582e): the escape counter is
pure rendered rowMove and residual is |aboveShift|, so neither can recover the
grow-vs-shrink topology that decides the fix. Thread signed aboveShift (rAF path)
/ signed drift (RO path) through the correction probe as a diagnostic-only
'signedShift' field alongside wouldFire; production behavior unchanged.
The slow-scroll classifier joins each reversal to the correction attempt(s) in
its frame window (append-count join, order-robust across the two rAF loops) and
classifies: SKIP (gate/xcheck suppressed the write -> uncorrected reflow),
GROW (fired, signedShift>0 -> write is the felt snap, absorption's topology),
SHRINK (fired, signedShift<0 -> reflow renders it pre-write, only smaller
per-frame realization helps). Bumps ANCHOR_BUILD_STAMP to w4a-classifier-1 so the
stale-dist guard rejects any bundle missing signedShift.
Co-authored-by: Tyler Longwell <tlongwell@block.xyz>
Signed-off-by: Tyler Longwell <tlongwell@block.xyz>
Realizing upscroll made the reading row jump down then snap back — a
reversal frame pair, most visible on WebKit where the ResizeObserver for
a content-visibility realization delivers one frame LATE (paint N, RO
N+1). This lands design-of-record (c): a single ungated RO mid-history
corrector plus a per-rAF sampler, coordinating ONLY through a shared
row-height cache — no engine branch. The on-time observer per engine is
the sole writer:
- Chromium: the RO delivers pre-paint, so the ungated RO corrects at N
(by the anchor's own measured drift) and refreshes the cache; the
rAF then sees residual ~0 and no-ops.
- WebKit: the RO is late, so the rAF (whose synchronous
getBoundingClientRect forces this frame's layout) corrects at N; the
late RO no-ops against the rAF-refreshed cache.
The RO path is deliberately UNGATED by the rAF path's observed/above
agreement cross-check: that gate suppresses the rAF band walk's
straddler-miscount fabrication, a risk the RO does not have (its entries
are ground truth for which rows resized). Applying the gate to the RO
strangled the on-time Chromium observer and regressed it to 16
reversals. Straddler safety on the RO path comes instead from the
safe-margin reading anchor (snapshotReadingAnchor +
READING_ANCHOR_SAFE_MARGIN_PX), which sits a notch below the realization
band so a row realizing across the fold is above the anchor and summed
into the drift correctly — documented as a load-bearing invariant at the
site so a later refactor cannot strip it thinking the `changed` trigger
covers straddlers (it does not; the margin does).
Own red/green E2E fixture (upscroll-raf-correction.perf.ts), verified on
both Playwright engines against a stamped build:
Chromium 0 reversals max 0.0px RO 21 rAF 0
WebKit 2 reversals max 14.5px rAF 24 RO 0 (residual 0.0)
Asserts are a layered stack so a vacuous pass cannot slip through: a
build-stamp stale-`dist` guard, LIVENESS (some correction fired),
PRIMARY correctness (reversals <= 4, maxReversalPx <= 34, engine-
agnostic), and per-engine MECHANISM in both directions (chromium
roFires>0 && rafFires===0; webkit rafFires>0 && maxRoResidual<=0.5).
Layering self-test confirmed: disabling the ungated-RO write flips
PRIMARY red at 16 while LIVENESS stays green.
The hook is the sole cross-engine reading-anchor scroll writer and its
correctness lives in the per-site provenance comments, so it crossed the
1000-line file-size limit (888 at HEAD); added a documented, narrowly-
scoped override queued to split the mid-history corrector into a sibling.
Co-authored-by: Tyler Longwell <tlongwell@block.xyz>
Signed-off-by: Tyler Longwell <tlongwell@block.xyz>
The prior fallback fired `scrollTo(currentScrollTop + aboveShift)` whenever
the baseline-relative position diff read 0 and `|aboveShift| > 0.5`. On WebKit
that condition is not specific to a real reflow: the per-rAF baseline is
captured post-realization, so `baseline` and `current` straddle the SAME side
of the reflow (dTop=dScroll=0) on EVERY frame, and `aboveShift` — summed from
the RO entries — can be nonzero on a frame where the anchor never moved,
because a row straddling the anchor boundary is miscounted. The fallback then
fabricated a downward shove: the "Shape B" slow-trackpad lurch
(`e=0, rowMove=+35..41px, dScroll=0`) — firing the correction WAS the visible
jump.
Add a second, baseline-timing-independent signal and fire only when the two
instruments agree. Carry the anchor snapshot from the PREVIOUS rAF tick
(`prevReadingAnchorRef`), which — unlike the same-frame baseline — was captured
before this frame's realization and so spans the reflow. Its document-position
shift `observedShift = (scrollTop+topOffset) − prev(scrollTop+topOffset)` is
scroll-invariant (user scroll moves scrollTop and topOffset equal-and-opposite),
so it isolates the reflow alone (Eva's probe `e`, from one coherent snapshot;
Quinn's scroll-isolated `R_obs`). Fire only when `prev.id === baseline.id` AND
`|aboveShift − observedShift| ≤ 0.5`, and correct by `observedShift` (never raw
screen motion — that would refold the user's scroll into the pin).
Agreement is the classifier boundary. Two-population split of fallback frames
on the WebKit slow-trackpad probe:
population | aboveShift vs observedShift | old writer | gated writer
-------------------|-----------------------------|--------------|-------------
real reflow | agree (Δ ≤ 0.5px) | corrects OK | corrects OK
straddler miscount | disagree (Δ = row height) | fabricates | suppressed
| | +35..41 shove| (no write)
Suppressing the miscount branch removes the fabricated shoves without touching
the frames where the RO sum is genuine.
Validated (each run x2, stable):
- Shape-B fabricated `e=0` shoves: eliminated (was the dominant felt defect)
- Chromium slow-trackpad: 0 escapes, sync 0.00, felt 0.00 (no regression)
- WebKit felt/wheel gate: 0.91px peak (<< 2px threshold), was 0.00 pre-gate —
the 0.91 is the frame-late CV-realization flash the miscount was masking
- WebKit slow-trackpad escapes: 67 -> 54
- 2167/2167 unit tests, tsc, biome clean
Residual (54 escapes) is a different phenomenon with a different owner: ~15
self-correcting frame-late flashes + ~12 multi-frame-blind under-corrections,
both rooted in WebKit delivering the CV-realization RO callback one frame after
the realization paints (documented in
RESEARCH/WEBKIT_RO_REALIZATION_FRAME_LATE_W1.md; overturns W4a doc lines 96-98,
which assumed the RO write is same-frame-visible on WebKit). That is a W4a
architecture item (Quinn owns direction; Max's W2 pre-realization band is the
A/B candidate), not a W1 branch-logic defect.
Co-authored-by: Dawn <dawn@sprout-oss.stage.blox.sqprod.co>
Co-authored-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
The upscroll compensation writer diffed the reading anchor's document
position against a per-rAF baseline. On WebKit the rAF baseline is
captured AFTER content-visibility realization has already shifted the
row, so baseline and current straddle the same side of the reflow
(dTop=dScroll=0) and the position diff is blind to it — the correction
never fired and the row took the full raw realization shift.
Add a second, baseline-timing-independent signal: when the position
diff sees no move, fall back to the net height change of the RO entries
ABOVE the anchor (`aboveShift`) and absorb it into scrollTop. This reads
the reflow magnitude directly from the resize entries rather than
diffing a snapshot WebKit captured too late, so it holds under WebKit's
async realization ordering without depending on scroll-event timing
(which coalesces off the scrolling thread under real wheel input).
Validated (each run x2, stable):
- WebKit felt/wheel (real input): 0.00px peak deviation (was ~200px)
- Chromium felt + sync: 0.00px, no regression
- 8/8 unit tests, tsc, biome clean
The WebKit synchronous-actuation gate still reads ~44px peak; that is an
`el.scrollTop=x`-vs-CV-realization artifact of the imperative test path,
not felt jitter — the felt-mode (wheel) gate under design supersedes it.
Co-authored-by: Dawn <dawn@sprout-oss.stage.blox.sqprod.co>
Co-authored-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
The RO compensation callback re-snapshotted `readingAnchorRef` right
after its `scrollTo`, but the per-rAF loop is documented as the single
writer of that ref and re-snapshots from live geometry next frame
(~16ms), already reflecting the correction. The extra write made the
"single writer" invariant false for no behavioral gain and cost one
`snapshotReadingAnchor` row-walk per correction. Remove it so the
invariant holds literally.
No behavior change: the next rAF re-baselines regardless. Unit tests
(computeAnchorCorrection sign + invariance) unaffected, 8/8 green.
Follow-up to Quinn's W1 cross-review (hole #2).
Co-authored-by: Dawn (sprout agent) <c6237ef84fa537c78dcee78efd2d4e59f728859c7f194da42ac51ededfa0be05@sprout-oss.stage.blox.sqprod.co>
Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
The T2 realization-compensation writer in useAnchoredScroll.ts was
near-perfect on Chromium and near-ineffective on WebKit (39 felt lurches
up to 204px per 30-swipe momentum pass). Root cause: the reading-anchor
baseline was snapshotted in the scroll handler, on the assumption that
scroll fires before ResizeObserver in the same frame. That holds on
Chromium; WebKit dispatches scroll asynchronously off its scrolling
thread and coalesces it, so under momentum the RO consumed a stale
snapshot and the drift measurement folded the user's own wheel delta
into the correction — the writer fought the wheel.
Make the path independent of scroll-event timing:
- Baseline the reading anchor per-rAF (single writer, module rAF loop),
not per-scroll-event. rAF runs before layout/RO on every engine, so
the baseline is the freshest pre-reflow read cross-engine.
- Compute the correction scroll-invariantly from the anchor row's
document position (scrollTop + topOffset), which changes only when
content above reflows — isolating the layout shift from user scroll.
Extracted as computeAnchorCorrection(), unit-tested for sign and
invariance.
- Write an absolute scrollTop target from this frame's own late reads,
not scrollBy against a possibly-stale offset (blunts the write-race).
- Staleness is a first-class SKIP: if scroll moved more than
COMPENSATION_SCROLL_SKIP_PX since baseline, momentum is in flight and
the reads may straddle a compositor commit — skip and let the next
quiet frame catch it. Under-correcting is invisible; fighting the
wheel is the lurch.
- Derive at-bottom vs mid-history from synchronous geometry
(isAtBottomNow) in both the rAF sampler and the RO callback, never
from the scroll-maintained anchorRef, so the branch and the baseline
can't disagree under momentum.
- Pick the reading anchor a safe margin below the fold
(READING_ANCHOR_SAFE_MARGIN_PX) so it never sits inside the
realization band it's meant to measure against.
Co-authored-by: Dawn (sprout agent) <c6237ef84fa537c78dcee78efd2d4e59f728859c7f194da42ac51ededfa0be05@sprout-oss.stage.blox.sqprod.co>
Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Two of the deferred scroll-jitter seams, on top of the integrated fix train
(T1.1 gate -> T2 writer -> T3 estimator @ 1fa4551a):
- columnWidthPx: measure the timeline row column once (useElementWidth) and
thread it into timelineRowReserveStyle so row-height reserves use the real
wrap width instead of the 64-char fallback. Pre-measure zero passes undefined
to preserve the estimator's own fallback rather than tripping its min-chars
floor. On jitter-corpus this shrinks estimate-error R from 75 -> 55 peak
(better reserves = smaller realized-vs-reserved delta) while the motion gate
stays GREEN 0.00/0.00 -- R moves only in the estimator lane, the gate only in
the writer lane, cross-lane invariant intact.
- Wren #4 anchor-contract guard: a companion perf test that reads the PRODUCTION
computed overflow-anchor on the real conversation scroller (no test override)
and asserts it resolves to none. The jitter gate forces the property for its
measurement; this proves the shipped stylesheet actually ships it, so a
regression that hands correction back to Chromium's native anchoring (masking
a WKWebView-only on-device break) fails loudly.
The onRealizedHeight seam is intentionally NOT wired: T4 ground truth
(RESEARCH/GUI_SCROLL_RECLAIM_T4.md) shows the upscroll path is append-only with
no unmount, so it needs no JS height cache; a per-event-id cache is only the
deferred, narrowly-scoped T4b for the head-refetch case. Adding an unused
callback now would be dead abstraction.
Validation:
- pnpm --dir desktop typecheck: clean
- biome check on both changed files: clean
- rowHeightEstimate.test.mjs 16/16, useAnchoredScroll.test.mjs 2/2
- perf: upscroll-jitter GREEN 0.00/0.00 (R 55), anchor-contract PASS
Co-authored-by: Tyler Longwell <tlongwell@block.xyz>
Signed-off-by: Tyler Longwell <tlongwell@block.xyz>
Scrolling UP a fully-loaded channel was subtly jumpy while scrolling down
was smooth. Root cause (Eva's H1): rows above the opening viewport have
never painted, so they sit at their `contain-intrinsic-size` reserve under
`content-visibility: auto`. Scrolling up, each row realizes at its true
height the instant it enters the realization band; the delta (true -
reserve) shifts content above the reading row. On shipped WKWebView there
is no `overflow-anchor` to correct it, so every realization lands raw on
the reading position — one lurch per row.
The fix makes the conversation scroller own its reading position through a
single same-frame compensation writer:
- Snapshot the reading anchor (first fully-visible row + its top offset) on
every scroll event, before the ResizeObserver fires. The RO runs after
layout and before paint, so the "before" position can only come from the
last scroll event — never from inside the RO callback.
- Observe each `.timeline-row-cv` row (CV realization is a resize of the
row's own box and does not surface as an ancestor resize in Blink), seeded
at observe time with the browser's current layout height read from
`contain-intrinsic-block-size` — the reserve for an unpainted row. Seeding
from the reserve is what turns the first realization into a measurable
`realized - reserve` delta instead of an unmeasurable first sighting.
- On a real height change, re-pin the reading anchor to its saved offset
with a same-frame `scrollBy(drift)`. A single measured correction: the
layout engine already summed the above-anchor deltas into the row's top,
and rows resizing below the anchor don't move it, so they're excluded for
free. Re-baseline after the correction.
- Force `overflow-anchor: none` on the scroller so the writer is the single
scroll authority on every engine — Chromium's native anchoring can't
double-correct behind the writer's back, and WKWebView has none anyway.
This also aligns CI (Chromium) with macOS (WKWebView), which ran different
scroll contracts — how the jitter shipped unseen.
Verified against the committed T1.1 gate (upscroll-jitter.perf.ts) on
jitter-corpus cold-load, sync fixed-step actuation, overflow-anchor forced
off: RED without this writer (peak-dev 46 / rms 23), GREEN with it (peak-dev
0.00 / rms 0.00, reproducible), and the non-gating wheel felt-mode pass also
0.00/0.00. The non-gating estimate-error R diagnostic stays at 75 (T3's lane;
this writer compensates motion, it does not shrink the reserve error).
Co-authored-by: Tyler Longwell <tlongwell@block.xyz>
Signed-off-by: Tyler Longwell <tlongwell@block.xyz>
Tyler's report: scrolling UP a fully-loaded channel is subtly jumpy;
DOWN is smooth. Root cause (Eva H1 + L-C): rows above the opening
viewport have never painted, so under content-visibility:auto they sit
at estimateRowHeight()'s contain-intrinsic-size reserve (60px,
utilities.css:17). Scrolling up, each realizes at its true height; the
reserve-vs-true delta shifts the reading position. Shipped WKWebView has
no overflow-anchor, so it corrects nothing — every delta lands raw.
This adds a deterministic gate that is RED at tip 77bd0e70 and that the
converged owned-compensation fix (overflow-anchor:none + same-frame
scrollBy(realized-reserved)) turns green:
- e2eBridge: a dedicated `jitter-corpus` mock channel (400 structurally
heterogeneous rows — headings/lists/blockquotes/code fences/long prose
whose true height estimateRowHeight is known to miss), its own channel
so the uniform deep-history seed the load-older specs use is untouched.
- upscroll-jitter.perf.ts: forces overflow-anchor:none on the scroller
(mirrors shipped WKWebView; logs CSS.supports per engine), then wheels
up in notches tracking a row held INSIDE the viewport (SAFE_MARGIN band
from both edges, re-picked each step, scored only if the same id stayed
in-band before+after). Residual = row's visual delta-top minus the
scroll delta: 0 == smooth. Gate is peak <=2px, rms <=0.6px.
Validity: within a single cold run the already-realized rows read
residual 0.0 exactly while realizing rows drift -27..-75px — an artifact
would drift on both. Negative sign shows the estimator over-reserves.
At tip: peak 75px, rms 40px over 23 steps → RED. A correct fill of
scrollTop absorbs the drift into the scroll delta, driving residual->0.
Co-authored-by: Tyler Longwell <tlongwell@block.xyz>
Signed-off-by: Tyler Longwell <tlongwell@block.xyz>
