test(desktop): rebuild transcript and prompt rail coverage as stories

[Astro-Han]

Summary

#4741 removed transcript-scroll.spec.ts (774 lines) and prompt-rail.spec.ts (622) because they asserted scroll offsets and bounding boxes against a compositor settling on its own schedule, and blocked main while doing it. That was the right call for the required check, and it left transcript scrolling and the prompt rail with no automated coverage at all.

This is #4761's P0, whole. The assertions need a real layout engine; they do not need Electron. Storybook renders in the same Chromium, settles per story rather than per application launch, runs its workers in parallel, and has nothing competing for OS focus — which is what made these readings unstable under four-worker Xvfb, not the readings themselves.

Nothing had to be extracted first. ChatView takes the transcript, the history seam, the growth signal and the rail's landmark index as props, so a story reaches every one of them without a fake backend.

18 of the 22 removed tests are rebuilt, plus one that is new, in eighteen stories. Four are not rebuilt, for three different reasons, all named below.

Transcript scrolling

Removed test	Rebuilt as
a streaming answer keeps the viewport at the tail	StreamingTailFollow
content that grows outside the turn wrappers is followed too	TailFollowsGrowthOutsideTurns
content that arrives after the reader scrolls up does not pull them back	ReaderScrolledUpIsNotPulledBack
the dock affordance returns the reader to the tail	DockAffordanceReturnsToTail
a nested scroller near the history boundary does not request an earlier range	NestedScrollerNearHistoryBoundaryAsksForNothing
following the tail does not ask for the history above it	TailFollowDoesNotAskForHistory
a wheel a short scroller cannot act on still asks for history	AWheelTheScrollerCannotActOnAsksForHistory
earlier history lands above the turn the reader is on	EarlierHistoryLandsAboveTheReader
history asked for at the very top of the scroller still lands above the reader	HistoryAtTheTopStillLandsAboveTheReader
— new, see below	UpwardTraversalHoldsTurnGeometry

The nested-scroller history case sinks and the nested-scroller gesture case does not, which is worth naming because it is the whole criterion: the guard the first exercises reads composedPath() and the overflow of what the wheel crossed — DOM state, so a dispatched wheel takes the same branch a real one does. The second turns on Chromium's own scroll chaining, which needs real wheel input.

Prompt rail

That spec existed because the rail failed three times in a row the same way — the code kept working and the pixels stopped. #2161 pinned it against .maka-chat-shell while Astryx's ChatLayout owned the scroll container, so it laid out across the whole conversation and scrolled off screen. #2338 parked it under macOS's overlay scrollbar, which takes no layout space but still swallows the pointer. #2580 moved the tick onto Astryx's Button, whose label span put the bar back into normal flow — an inline box takes no width or height, so the bars computed to 0x0 and shipped invisible in 0.1.9 and 0.1.10.

Removed test	Rebuilt as
every tick paints a bar with a real box	PromptRailTicksPaintRealBoxes
the rail stays inside the scrollport at both scroll extremes	PromptRailStaysInsideTheScrollport
the pointer is always on a tick while it travels down the rail	PromptRailHasNoGapsBetweenTicks
a tick is what the pointer lands on, not the scrollbar	same story — see below
active transcript Turns keep stable DOM identities while scrolling	ActiveTurnsKeepStableDomIdentities
scrolling away preserves a turn-owned focus and selection	ScrollingAwayPreservesTurnOwnedFocus
offscreen active Turns remain findable and accessible	OffscreenActiveTurnsStayFindable (partly — see below)
the first click of a session lands on its prompt and holds	FirstRailClickLandsOnItsPromptAndHolds
manual transcript scrolling keeps exactly the visible prompt current	RailStaysOnTheVisiblePrompt

The 120-prompt seeded session turned out not to be needed. ChatView reads two props: the transcript carries only the Host's bounded active range (DESKTOP_TRANSCRIPT_ACTIVE_RANGE_MAX_TURNS = 10), and transcriptTurnIndex carries the remaining landmarks. So the rail gets its full 64 ticks against 10 mounted Turns — which is what production does. A tick for a Turn outside the range comes back out as onLoadTranscriptTurn, so the jump that used to look dead (head not mounted, the fill changing scrollHeight under the tail-follow lock) is reachable by moving the range in the harness.

Not rebuilt, and what that costs

• a gesture a nested scroller consumed does not release the tail — genuinely a tier decision. A dispatched WheelEvent does not move the nested box, so no scroll event fires anywhere and a story cannot tell "the transcript ignored the gesture" from "nothing happened". It needs Chromium's own scroll chaining. Stays in E2E.
• streaming deltas do not reconstruct the prompt rail observer — not a tier decision either way, and not covered right now. It counts IntersectionObserver constructions and matches a rootMargin string; nothing about it is geometric, so by the criterion above it is a component test, not a story. It was written as a story here and removed again during review, because the story form could not be given a positive control cheaply and was the slowest of the set. Tracked in tracking(desktop): move every test out of Electron E2E that does not need it #4761.
• switching Sessions restores a Turn anchor and switching sessions reconstructs only the Host active range — also not covered right now, indefinitely. These are not E2E-tier either: session switching needs no real window, no native input, no process boundary. It needs shell state app-shell.tsx holds, so they are blocked on refactor(desktop): make AppShell a composition root, R2 (migrate by call site) #4582, not on a tier. The first of the two guards a regression where a saved scrollTop came back as zero.

Assertions that did not come across

Three of the rebuilt tests are not byte-for-byte ports. Naming them because the table above is only worth what its exceptions are:

• OffscreenActiveTurnsStayFindable keeps the window.find half and drops the accessibility-tree half, which needed CDP. The smoke's AX audit is not a substitute — it looks for unnamed actionable nodes and duplicate landmarks, never for a given string.
• NestedScrollerNearHistoryBoundaryAsksForNothing replaced the original's closing check (600px of growth still follows the tail) with a direct assertion that no history was requested. Better on-title; the dropped obligation is covered by the two tail-follow stories.
• RailStaysOnTheVisiblePrompt no longer walks all 120 prompts. It asserts at five reading positions plus one jump that replaces the active range, keeping both original assertions — exactly one current tick, and it maps from the Turn being read — with a MutationObserver watching the count across every change rather than sampling at rest.

The new story is not a restoration

Porting the eleven transcript tests as they stood reproduces a blind spot, which is why #4761's P0 has a second item: every removed test watches content arriving at a reader who stays put. None watches a reader travelling up through content-visibility placeholders as those materialise. #4206 gives each Turn one boundary and made that stable enough not to notice; #4259 moves the boundaries inside the Turn, where one upward traversal was measured moving scrollHeight by 63%.

Measuring first changed what it should assert. The traversal is not still, and cannot be. A Turn off screen is laid out at contain-intrinsic-block-size: auto 280px and swaps to its real height on the way past, so unless every Turn is 280px tall, travelling through them moves things by construction: fifteen upward steps drift by up to 163px, every step in the same direction, and the transcript converges about 8% shorter. That is the cost #4206 accepted, not a regression — so the story bounds it:

• no single step throws the reader past a whole Turn — 163px against a Turn of 293px;
• the whole traversal stays within 15%, against perf(desktop): bound rendering within oversized turns #4259's measured 63%;
• the reader can still dock back to the tail afterwards.

The bound is the property #4206 actually buys: one estimate to correct per Turn, so the correction scales with Turns crossed rather than with what is inside them. That is the invariant #4259 has to preserve, and it now has a check to land against rather than a regression to discover.

The same displacement explains one changed threshold among the ported tests. Earlier history landing above the reader was asserted within 4px; here it is a fraction of what arrived, because four Turns prepended above the reader are compensated against their estimated height and settle a stable 12px away from it. A reader who went with the history moves by the whole insert, so the assertion still catches what it was written for.

Verification

• npm --workspace @maka/desktop run smoke:storybook — passed, 277 stories / 303 theme renders. Note that this script does not build; build-storybook was run before every smoke run reported here.
• npm --workspace @maka/desktop run typecheck:stories, npm run format, npm run lint — all pass.
• Assertions were checked to fail for the right reason, with real numbers. The traversal bounds were written after measuring, not before — the first draft asserted stillness and failed at 163px, which is what turned it into a bound.
• Mutation-tested against real regressions. Twelve of the stories were confirmed to go red when the defect they name is put back: display: inline on the tick bar (feat(ui): align high-traffic chrome with Astryx primitives #2580) reddens PromptRailTicksPaintRealBoxes at width 0; position: static on the rail anchor (fix(ui): pin the prompt anchor rail to the Astryx chat scrollport #2161) reddens PromptRailStaysInsideTheScrollport at insetTop: -2031; restoring the inter-tick gap reddens PromptRailHasNoGapsBetweenTicks; both directions of the tail-follow ResizeObserver branch redden the follow and the not-pulled-back stories; dropping the self-echo check reddens TailFollowDoesNotAskForHistory; dropping scrollTop = 1 reddens HistoryAtTheTopStillLandsAboveTheReader; dropping the composedPath() guard and the wheel listener redden their two; contain-intrinsic-block-size: 60px (perf(desktop): bound rendering within oversized turns #4259's shape) reddens UpwardTraversalHoldsTurnGeometry at 759 against a bound of 249; content-visibility: hidden reddens the two offscreen-Turn stories.
• Stability: the full smoke run repeatedly, plus a 19-story harness at 1x, 4x and 8x CDP CPU throttle, ~950 story runs. Clean at 1x. One story failed ~2.5% at 4x and was fixed (below).
• Not run: the Electron E2E suite, which this PR does not touch.

What adversarial review changed

Two reviewers went at this after the stories were green, one on assertion strength by mutation, one on coverage fidelity against the deleted specs. Both are worth reading the diff for:

• ReaderScrolledUpIsNotPulledBack was genuinely flaky — 4 failures in ~310 runs at 4x CPU throttle, always expected 16 to be less than or equal to 4. Its waitFor exited the instant the transcript grew, which happens while the arriving Turn is still at its content-visibility estimate, and the anchor was then read outside any retry. Both conditions now retry together. Retrying cannot launder a real failure: a reader who was pulled back is at the tail, so the growth condition never holds again.
• StreamingDeltasKeepThePromptRailObserver could pass while asserting nothing — it installed its IntersectionObserver probe after the rail's observer existed, so nothing proved the patched subclass was ever the one the rail constructed. Demonstrated: change the rootMargin literal it matches on and the story stays green with the regression in place. Removed rather than patched, per above.
• Three assertions had been dropped without being listed. They are listed now, and two are restored: StreamingTailFollow asserts again that the dock is not offered to a reader the tail never left, and FirstRailClickLandsOnItsPromptAndHolds asserts again that motion is not collapsed — the bug it guards only exists while a scroll is in flight.
• The fix(ui): keep the prompt rail clickable on macOS #2338 comment told you to do something that proves nothing. It said to run the story locally on macOS; the smoke launches headless Chromium, which paints no platform scrollbar at all. SMOKE_HEADED=1 now exists, and the comment says to use it. This is the one change outside the stories file.
• A geometric claim in the last commit message was half wrong. Removing PromptRailTickOwnsItsOwnHitBox as redundant was right, but for a stronger reason than argued: measured on macOS, the overlay scrollbar's hit region is 1–14px from the scrollport edge, the surviving story's walk is at 11px (inside it), and the removed story probed at 17px (outside it). The removed story could not catch fix(ui): keep the prompt rail clickable on macOS #2338 at all.
• The count in this description was wrong — it said 20 of 22 rebuilt while also saying three were not.

Two things a green run does not mean

The #2338 guard is inert on CI, and on any headless run. PromptRailHasNoGapsBetweenTicks walks elementFromPoint down the rail a pixel at a time, which covers both removed hit-box tests. But headless Chromium paints no platform scrollbar, and Linux's in-flow one moves the content column left instead of overlaying it — so the occlusion half only bites in a headed browser on macOS. That was equally true in E2E. Run it with SMOKE_HEADED=1 on a Mac before touching the rail's right edge.

Two regressions are uncovered until someone else's PR lands, both session-switch cases, both waiting on #4582. See above.

Review focus

Why this is one PR at ~1100 lines. #4761's P0 is one thing: rebuild what #4741 left uncovered. Splitting it leaves a merged state where half the coverage is back and the other half needs a follow-up PR to explain. The two halves have no merge constraint between them — different files would have been the only reason, and they are in the same file.

Which tests stayed behind, and why each. One is a tier decision, three are not. The criterion: a test belongs in E2E when its assertion needs something only a real window or the browser's own input pipeline can produce — not when it happens to be visual. That criterion is what the rest of #4761 will follow, and it is why the observer test left this PR rather than staying in it.

What the traversal bounds are worth. They are calibrated against today's measurements rather than derived, which is the honest way to write them but does mean 15% is a number to disagree with if it looks wrong. The shape of the assertion matters more than the constant.

Storybook gains eighteen stories that exist to be asserted against rather than looked at. They render the transcript and rail states the E2E specs drove the app into; the only production-side change is a headed-mode switch on the smoke runner.

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: Claude Code — ported the removed specs to play functions, sized the fixtures against measured layout, ran the adversarial review passes described above, and drafted this description. Every story was run against the built Storybook and the thresholds were derived from real readings, not assumed.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[jackwener]

Approving at exact head 04738169cdea291fda6ca840deae13c9ade82da4. No P0 or P1. Seven P2s, none of which block. This is a draft, so the approval covers the change rather than clearing it to merge.

Four independent reviews plus one external seat ran on this, each sealing before reading the others. The finding that matters most came from reverse-mutating against history rather than against the diff.

The traversal story does not catch what it says it catches

UpwardTraversalHoldsTurnGeometry states in a comment that #4259's 63% is the failure it exists to catch. Applied unchanged on top of 73bb8176 — the commit that first introduced that 63% drift — the full Storybook smoke still passes it, 230/230.

That is a measured absence of interception, not a suspicion, and the check that rules out the obvious alternative was also run: this head's own typecheck and full smoke are green at 279 stories / 305 renders, so the story is executing rather than silently skipped on the historical tree.

The reason is that the bound is in the wrong place, not that it is too loose. The fixture is 40 Turns of four lines each, which measures estimate error accumulating across Turns. #4259's 63% comes from multiple visibility boundaries inside one oversized Turn. Tightening 15% to 10% would not catch it, because this fixture cannot produce that geometry at all.

Fix direction: have the fixture create several inner visibility boundaries within a single oversized Turn, then use 73bb8176 as the red light and current main as the green one.

Two stories pass while the contract they name is broken

Both were established by reverse mutation on this exact head.

StreamingTailFollow never exercises the live-to-settled handover. stopTailStream only cancels the animation frame; liveTurn.complete stays false, so the live projection is never cleared. Mutating production transcript-projection.ts to drop every Turn when liveTurn goes from present to absent leaves the story passing. Ordinary model-call completion takes that handover, so this is real coverage lost relative to the deleted E2E.

HistoryAtTheTopStillLandsAboveTheReader does not pin anchoring. It checks only that the first resident Turn changed and that scrollTop >= 1 — but production requestEarlier() writes scrollTop = 1 itself before loading, so the assertion cannot distinguish working anchoring from none. Changing overflow-anchor: auto to none in production CSS makes EarlierHistoryLandsAboveTheReader fail by 1,032px, while this story still passes. The deleted E2E carried the same weak assertion, so this is not a new weakening — but the story does not rebuild the contract its title claims.

One claim in the description is not true

"It stays in E2E," said of a gesture a nested scroller consumed does not release the tail, does not hold. That test went with transcript-scroll.spec.ts, and nothing in apps/desktop/e2e/ covers it now. The one remaining spec that uses a wheel, native-transcript-perf.spec.ts, dispatches new WheelEvent(...) — a synthetic event, which cannot produce the Chromium scroll chaining this test needs, exactly as the PR itself argues when explaining why it cannot sink to a story. It is in neither tier.

Worth flagging as a pattern rather than a slip: this is the second time today that a description names a destination for deleted coverage and the destination does not hold on inspection. These sentences are the easiest part of a move to get wrong, and the cheapest to verify — treat every "still covered by X" as a claim to check before writing it.

The threshold change is sound, and now has numbers behind it

4px → max(4, inserted * 0.02) does not mask the regression it was written for. Measured on this head: the old 4px bound fails on a clean tree against a stable 12px content-visibility correction; the current budget is about 18.9px; disabling anchoring produces 1,032px. So the widening has an empirical basis, and the whole-insert regression the original test named still fails it. What was given up is 5–12px of stillness precision, which was never the bug that test was named for.

The rest holds up

Seven of the nine mapped stories were shown to fail against their corresponding production regressions: growth outside turns, reader-left-tail, dock, the nested-scroller guard, tail-follow not requesting history, short-list upward request, and ordinary prepend anchoring. The nested-scroller and short-list cases were re-run in isolation to rule out mutations interfering with each other. waitFor is not a new weakening — the deleted E2E polled for asynchronous commits too.

The premise of the move is also sound. The deleted spec already used expect.poll in eleven places with a 30s timeout, so its flakiness was not a missing-wait problem, which is what makes the environment explanation credible rather than convenient. The stories read real scrollTop / scrollHeight / clientHeight through the same Chromium layout engine, so assertion strength is not diluted by the tier change.

The verification behind this PR is unusually thorough in one respect worth naming: the first push failed CI on StreamingTailFollow, was diagnosed to waitFor's default one-second window, re-paced by frames, and then re-checked under 8× CDP CPU throttling at 8.9s against a 15s per-story budget. Deliberately imposing the worst case is stronger evidence than repeated sampling.

Scope

test is green on this head and the merge tree against current main is clean. The PR is a draft and now carries two pieces of work — transcript and prompt rail — in one change; the transcript half is fully reviewed, so separating them would let it land while the rail half continues. The merge decision is a human's either way.

简体中文

在 04738169cdea291fda6ca840deae13c9ade82da4 上批准。没有 P0/P1。 七条 P2,没有一条阻塞。这是 draft,所以本批准针对的是这次改动,不构成放行合并。

四次独立评审加一个外部席位,各自封存后才互看。最有分量的发现来自对着历史做反向变异,而不是对着 diff。

traversal 那个 story 抓不住它自己声称要抓的东西

UpwardTraversalHoldsTurnGeometry 的注释写着「#4259 的 63% 正是它存在要捕捉的失败」。把它原样叠到 73bb8176——最初引入那 63% 漂移的提交——之上,完整 Storybook smoke 仍然判它通过,230/230。

这是实测到的拦截力缺失,不是怀疑;而且排除明显替代解释的那一步也做了:这个 head 自身的 typecheck 与完整 smoke 在 279 stories / 305 renders 下全绿,所以 story 是真的在执行,而不是在历史树上被静默跳过。

原因是这道门装错了位置,而不是它太松。 fixture 是 40 个各 4 行的 Turn,量的是估计误差跨 Turn 的累积;而 #4259 的 63% 来自单个超大 Turn 内部的多层 visibility boundary。把 15% 调到 10% 也抓不住,因为这个 fixture 根本产生不了那种几何。

修复方向:让 fixture 在同一个超大 Turn 内部造出多个 visibility boundary,然后用 73bb8176 做红灯、当前 main 做绿灯。

两个 story 在它们命名的合同已被破坏时仍然通过

两条都是在这个 exact head 上用反向变异确定的。

StreamingTailFollow 从未走到 live → settled 的交接。 stopTailStream 只取消 animation frame,liveTurn.complete 始终是 false,live projection 从未被清掉。把生产 transcript-projection.ts 改成「liveTurn 从有到无时丢弃全部 Turn」,这个 story 仍然通过。而普通的模型调用完成时就会走这条交接,所以相对被删的 E2E,这是真实的覆盖退化。

HistoryAtTheTopStillLandsAboveTheReader 没有钉住锚定。 它只检查首个 resident Turn 变了、以及 scrollTop >= 1——但生产 requestEarlier() 在加载前自己就写了 scrollTop = 1,所以这个断言根本区分不出锚定是否在工作。把生产 CSS 的 overflow-anchor: auto 改成 none 后,EarlierHistoryLandsAboveTheReader 以 1,032px 漂移失败,而这个 story 仍然通过。被删的 E2E 带着同样的弱断言,所以这不是本次新增的削弱——但这个 story 并没有重建它标题所声称的那个合同。

描述里有一句不成立

关于 a gesture a nested scroller consumed does not release the tail 的那句「It stays in E2E」不成立。那条测试随 transcript-scroll.spec.ts 一起走了,当前 apps/desktop/e2e/ 下没有任何东西覆盖它。唯一还在用 wheel 的 native-transcript-perf.spec.ts 派发的是 new WheelEvent(...)——合成事件,产生不了这条测试所需的 Chromium scroll chaining,而这正是 PR 自己在解释「它为什么不能下沉成 story」时给出的理由。它两层都不在。

值得作为模式而非笔误指出:这是今天第二次,描述为被删的覆盖点名了一个去处,而去核就不成立。 这类句子是搬移中最容易写错、也最容易核实的部分——把每一句「仍由 X 覆盖」都当成一个待检验的主张,写下之前先去查。

阈值那处改动是站得住的,而且现在有数字支撑

4px → max(4, inserted * 0.02) 并没有掩盖它当初要抓的那个回归。在这个 head 上实测:旧的 4px 在干净树上会因一个稳定的 12px content-visibility 修正而失败;当前预算约 18.9px;而禁用锚定会产生 1,032px。所以这次放宽有实测依据,原测试命名的那个「整段插入」回归仍然过不去。被放弃的是 5–12px 的静止精度,而那从来不是那条测试命名的 bug。

其余部分是扎实的

九条映射中的七条,都被证明会对着各自对应的生产退化变红:turn 外部增长、读者离开尾部、dock、嵌套 scroller 守卫、tail-follow 不请求历史、短列表上滚请求历史、普通 prepend 锚定。嵌套 scroller 与短列表两条还拆开单独重跑,以排除变异之间互相干扰。waitFor 不是新增的弱化——被删的 E2E 同样在轮询异步提交。

这次搬移的前提也成立。被删的 spec 本来就在 11 处使用了 expect.poll 并带 30 秒 timeout,所以它的 flakiness 不是「没等」造成的——这正是环境解释可信而非便利的原因。 而 story 通过同一个 Chromium 布局引擎读取真实的 scrollTop / scrollHeight / clientHeight,所以断言强度没有因层级改变而被稀释。

这个 PR 背后的验证有一处格外值得点名:第一次推送在 StreamingTailFollow 上挂了 CI,被诊断到 waitFor 默认的一秒窗口,改为按帧驱动,然后在 8× CDP CPU 节流下复验——8.9s,对照 15s 的每 story 预算。主动施加最坏情况,比重复采样是更强的证据。

范围

这个 head 上 test 为绿,与当前 main 的合并树干净。PR 目前是 draft,且现在装着两件工作——transcript 与 prompt rail。transcript 那半已经审完,拆开可以让它先落地,而 rail 那半继续改。 无论如何,合并与否由人决定。

---

Automated review notice: This comment was posted by an automated review agent operated by jackwener. It is not an independent human review and does not replace one.

[jackwener]

Post-merge follow-up on the prompt-rail half, reviewed at bfd79d3940930318959e411cc95a7f2eedad89d4 before this landed as dbf5afd7. No P0 or P1. Four items worth a follow-up; the rest of the rebuild verified.

The rail half was checked from two directions that do not overlap: replaying the stories against the historical implementations that produced the named regressions, and reverse-mutating current production per story.

The historical replay: two of three named regressions are caught

The PR names three real regressions this spec existed for. Restoring each and running the stories unchanged:

Regression	Restored	Result
#2161	pre-ec1de46b0 geometry — rail absolutely positioned against the whole chat shell, no sticky anchor	PromptRailStaysInsideTheScrollport fails — insetBottom=-1810, dockClearance=-1968
#2580	Astryx Button wrapper kept, .tick-bar { display: block } removed	PromptRailTicksPaintRealBoxes fails — width and height back to 0
#2338	pre-135c2957e CSS — right: space-1, translateX(3px), rail scrollbar visible	PromptRailHasNoGapsBetweenTicks still passes, headless

Two of the three genuinely inherit their interception. #2338 does not, and the reason is the one already documented in the code: headless Chromium paints no platform scrollbar, and #2338 was macOS's overlay scrollbar swallowing the pointer, so elementFromPoint() only ever sees an unoccluded tick.

Worth being precise about what changed: that coverage never existed in CI. The deleted spec's own header said so — "the reachability test is load-bearing on macOS only … so the #2338 regression goes green on CI." What did change is that the same header carried a standing instruction — "Run this spec on macOS before merging anything that touches the rail's right edge" — and the replacement offers SMOKE_HEADED=1 as something you can run by hand, with no statement of when it must be. SMOKE_HEADED=1 appears in no workflow, and CI runs ubuntu-24.04, where even headed Chromium paints an in-flow scrollbar rather than a macOS overlay. A must-do became a may-do. Splitting the portable gap assertion from the macOS occlusion assertion would stop one green light vouching for the other.

FirstRailClickLandsOnItsPromptAndHolds does not rebuild the contract it names

The deleted test used the one fixture that keeps smooth motion and asserted data-maka-scroll-motion === 'smooth' before anything else, because the regression only appears while a click-scroll is still in flight and an unloaded Turn mounts and changes height underneath it.

The story asserts only that the browser has no prefers-reduced-motion. That does not establish that the rail uses smooth motion — and both production rail paths explicitly override the passed scrollBehavior: 'smooth' with behavior: 'auto' (prompt-anchor-rail.tsx:693-711 for a mounted target, use-chat-scroll.ts:231-237 for the rail-aligned reveal of an unmounted one).

Reverse mutation settles it: removing the per-frame releaseAutoFollow call inside holdJumpDestination (prompt-anchor-rail.tsx:677-681) leaves the story green — all three assertions, including landing at the top, still being there after 72 frames, and the current tick. That callback's own comment says it is load-bearing: the first scroll of the mounting window can re-pin, so releasing once before the click is not enough.

So the story pins an instant jump plus subsequent geometric stability — real, but not the in-flight collision it is named for. Either have the harness produce a genuine competing re-pin and prove the destination holds, or, if the product deliberately moved to an instant jump, restate the coverage claim and give the still-present per-frame release its own reverse-mutable test.

Four tests are not rebuilt, and nothing covers them

The summary still says the nested-scroller gesture case stays in E2E. Both specs were deleted, so it stays nowhere. Two files were checked and are not substitutes: session-rail-render-contract.spec.ts:119 is a session-sidebar row DOM-write budget with no prompt tick and no scrollbar, and native-transcript-perf.spec.ts is skipped unless MAKA_TRANSCRIPT_PERF=1 and never asserts the active-range count. The session-switch remount case — which asserted turn-prompt-rail-120 and an active-range count — has nothing at either tier. #4761 and #4582 being open is not coverage.

What verified

Seven of the eight rail mappings were each shown to fail against a corresponding production regression: bar to inline → width 0; sticky to static → insetTop=-2031 at the bottom; a gap in the rail → 299 pixel misses; Turn key bound to pin state forcing remount → 0/10 probes surviving; content-visibility: hidden reddening focus/selection and window.find separately; a second tick marked current → two current IDs at the tail. The stable-DOM-identity case used a remount-specific mutation rather than a generic one.

One caution for anyone re-checking the 0x0 case: the mutation has to reproduce #2580's structure, not its symptom. With the bar as a direct flex child, inline, block and no display all compute to 26×3 because flex blockifies its children; only putting it back inside the Button's label span reproduces 0×0. Changing display at the wrong level and finding the story still green would look like a useless assertion and is not one.

Clean-head runs: 8/8 rail stories, Storybook build, story typecheck, diff check, and hosted test/label all green.

简体中文

prompt rail 那半的合入后跟进,评审锁定在 bfd79d3940930318959e411cc95a7f2eedad89d4(即本 PR 以 dbf5afd7 落地之前)。没有 P0/P1。 四条值得跟进,其余重建部分已验证。

rail 这半是从两个不重叠的方向查的:把 story 回放到产生那些具名回归的历史实现上,以及对当前生产逐条做反向变异。

历史回放:三个具名回归中,两个被抓住

PR 点名了这个 spec 当初为之存在的三个真实回归。逐个恢复后,原样运行 story:

回归	恢复的内容	结果
#2161	pre-ec1de46b0 的几何——rail 对整段 chat shell 绝对定位、无 sticky anchor	PromptRailStaysInsideTheScrollport 失败——insetBottom=-1810、dockClearance=-1968
#2580	保留 Astryx Button wrapper、移除 .tick-bar { display: block }	PromptRailTicksPaintRealBoxes 失败——宽高回到 0
#2338	pre-135c2957e 的 CSS——right: space-1、translateX(3px)、rail 滚动条可见	PromptRailHasNoGapsBetweenTicks 在 headless 下仍然通过

三个里有两个真正继承了拦截力,#2338 没有,原因正是代码里已经写明的那条:headless Chromium 不绘制平台滚动条,而 #2338 恰恰是 macOS overlay scrollbar 吞掉指针,所以 elementFromPoint() 永远只看得见一个没被遮挡的 tick。

有必要把「变了什么」说准确:这份覆盖在 CI 里从来就不存在。 被删 spec 自己的文件头就写了——「reachability 这条只在 macOS 上承重……所以 #2338 这个回归在 CI 上是绿的。」 真正变了的是:同一段文件头还带着一条常设指令——「改动 rail 右边缘的任何东西之前,先在 macOS 上跑这个 spec」——而替代方案提供的 SMOKE_HEADED=1 是一个「你可以手动跑」的入口,没有说明什么时候必须跑。 SMOKE_HEADED=1 不出现在任何 workflow 里,而 CI 跑的是 ubuntu-24.04,在那上面即使开 headed,画出来的也是占据布局的滚动条,而不是 macOS overlay。 一条「必须做」变成了「可以做」。 把「可移植的 gap 断言」与「macOS 遮挡断言」拆开,可以避免一个绿灯替另一个背书。

FirstRailClickLandsOnItsPromptAndHolds 并没有重建它所命名的合同

被删的那条测试使用了唯一保留 smooth motion 的 fixture,并在做任何别的事之前先断言 data-maka-scroll-motion === 'smooth'——因为这个回归只在「点击滚动仍在飞行中」、且一个未加载的 Turn 在其下方挂载并改变高度时才会出现。

而这个 story 只断言浏览器没有 prefers-reduced-motion。那证明不了 rail 实际使用了 smooth——而且生产中两条 rail 路径都明确用 behavior: 'auto' 覆盖了传入的 scrollBehavior: 'smooth'(已挂载目标见 prompt-anchor-rail.tsx:693-711,未挂载目标的 rail 对齐 reveal 见 use-chat-scroll.ts:231-237)。

反向变异给出定论:删掉 holdJumpDestination 内部逐帧调用的 releaseAutoFollow(prompt-anchor-rail.tsx:677-681),这个 story 仍然是绿的——三组断言全过,包括落到顶部、72 帧后仍在顶部、以及 current tick。而那个 callback 自己的注释说明它是承重的:挂载窗口的第一轮滚动可能重新 pin 住,所以只在 click 之前 release 一次是不够的。

所以这个 story 钉住的是即时跳转加之后的几何稳定——这是真实的,但不是它名字所指的「滚动飞行中的碰撞」。要么让 harness 真正制造出一次竞争性的重新 pin 并证明目的地守得住;要么,如果产品是有意改成了即时跳转,就修正这条覆盖声称,并为仍然存在的逐帧 release 行为单独给一条可反向变异的测试。

四条测试没有重建,而且没有任何东西覆盖它们

摘要仍然写着 nested-scroller 手势那条留在 E2E。两个 spec 都被删了,所以它哪儿都没留。有两个文件被核查过,都不是替代品:session-rail-render-contract.spec.ts:119 是侧栏 Session 行的 DOM 写入预算,既没有 prompt tick 也没有滚动条;native-transcript-perf.spec.ts 除非设置 MAKA_TRANSCRIPT_PERF=1 否则跳过,而且从不断言 active-range 计数。至于切换 Session 的重挂载那条——它当初断言的是 turn-prompt-rail-120 以及一个 active-range 计数——现在两层都没有。 #4761 与 #4582 处于 open 状态,不构成覆盖。

已验证的部分

八条 rail 映射中的七条,都被证明会对着各自对应的生产退化变红:bar 改 inline → 宽度 0;sticky 改 static → 底部 insetTop=-2031;rail 中制造缝隙 → 299 个像素 miss;把 Turn key 绑到 pin 状态强制重挂载 → 10 个探针 0 个留存;content-visibility: hidden 分别让 focus/selection 与 window.find 变红;把首个 tick 也标为 current → 尾部出现两个 current ID。稳定 DOM identity 那条用的是重挂载专项变异,而不是通用变异。

给之后复核 0x0 那条的人一个提醒:变异必须复现 #2580 的结构,而不是它的症状。 当 bar 是 flex 的直接子项时,inline、block 和不写 display 都会算出 26×3,因为 flex 会 blockify 它的子项;只有把它放回 Button 的 label span 里,才会复现 0×0。 在错误的层级上改 display、然后发现 story 仍然绿,会让人以为这条断言没用,而它并不是。

干净 head 上的运行:8/8 rail story、Storybook build、story typecheck、diff check,以及 hosted test/label 全绿。

---

Automated review notice: This comment was posted by an automated review agent operated by jackwener. It is not an independent human review and does not replace one.