feat(desktop): preserve transcript continuity across bounded ranges

[Sun-GLiang]

Summary

Rebuilds transcript partial-history handling on current main around the existing bounded-range seams.

• Render an in-flow gap row only at an actual older or newer boundary.
• Load older, newer, and latest ranges through the existing transcript range controller.
• Keep the resident transcript as one contiguous bounded window.
• Keep the existing transcript scroll authority as the only scroll writer.
• Clear the historical reading anchor when an explicit newer or latest navigation supersedes it, so restoration cannot pull the range backward again.
• Consume a search jump after it successfully lands, so later range paging cannot be pulled back by stale search-restore intent.
• Preserve focus on an activating gap button across its temporary disabled loading state without stealing focus after the reader moves elsewhere or changing the visible position.

This intentionally does not add a position index, storage table, cursor protocol, compatibility-epoch change, alternate pager, or second scroll authority.

Fixes #4123

Current status

Ready for maintainer review. The rebuild and local verification are complete, and CI is green on the current head.

Verification

Current head: 0e1d09e9cd0da48f86208fa7f20c0c5c4778a1cd

• Before the focus fix, the newer-gap button lost focus 10/10 times when shared loading temporarily disabled it.
• After the fix, the Electron older → newer → latest path passed 10/10 with two workers. It asserts retained focus, no more than 4px viewport displacement, and arrival at the real latest Turn.
• Clean UI build and suite — 383/383 passed.
• Targeted gap, scroll-authority, and chat-scroll tests — 24/24 passed.
• npm --workspace @maka/desktop run build:with-deps
• npm --workspace @maka/desktop run check:architecture — 101 checks passed plus architecture-ledger validation.
• npm run typecheck, npm run lint, npm run format:check, and git diff --check passed.
• CI test — passed in 12m13s on the updated head.

Review focus

• Gap placement for latest, historical, intermediate, and live-overlay ranges
• Reuse of the existing loadBefore, loadAround, loadLatest, reading-anchor, and scroll-authority seams
• Explicit newer/latest navigation superseding stale historical restoration intent
• One-shot search restore after a successful jump
• Focus recovery only for the activating gap button, with preventScroll and no focus stealing
• Preservation of a single contiguous resident range and a single transcript scroll writer
• No storage, Runtime Host protocol, compatibility-epoch, or design-document changes

AI use

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

Codex rebuilt the implementation from current main, added tests, and reviewed the diff against the corrected issue and repository standards.

Checklist

• Tests cover the behavioral change
• Targeted local build, typecheck, architecture, E2E, formatting, and test verification complete
• CI complete

Does this PR entail a change in behavior?

• Yes — partial transcript boundaries are represented and loadable in-flow
• No

[Astro-Han]

Thanks for the work, and I owe you an apology: I left you hanging after asking you to pause #4258 and #4295 on Aug 31, so you had to build against the outdated issue text. That is entirely on me.

I have corrected #4123. Most of this PR's 6.7k lines trace back to two incorrect assumptions in the original issue:

• Separated ranges can appear adjacent: They cannot. #evictToBudget only trims from the ends and #acceptRange throws on internal sequence gaps, so the resident durable window stays contiguous; only the two boundaries need markers.
• Identity and paging state do not cross the preload boundary: They already do (identity, durableThrough, hasOlder, hasNewer, loadBefore, and loadAround).

The position-index chain (sqlite-session-turn-positions.ts, session-transcript-position-pager.ts, transcript-signed-cursor.ts, the new operation, and the 109→110 epoch bump) is therefore unnecessary. What is left is small: project generic rows, render a boundary gap row, and page via existing loadBefore / loadAround.

Two scroll-layer issues to note regardless of scope:

1. recordProgrammaticScroll introduces a second time-window authority (160ms) alongside transcript-scroll-authority (which deliberately refuses to infer intent from timing; see header). Its wheel, pointerdown, touchstart, and keydown listeners also break nested scrollers because wheel bubbles.
2. root.scrollTop += displacement in restorePagingAnchor adds a second writer of scrollTop. "One writer" is an explicit acceptance criterion of that authority, not a style preference — a second writer is the exact bug class bug(ui): upward scroll can snap back to the live tail during geometry changes #4269 turned out to be.

Landing order: #4793 (pin owns scroll anchoring) then #4259 (containment CSS) must land first. Both touch the same scroller, and #4259 already conflicts with this branch.

Next steps: A rebase will not fix this, as the shape follows issue text I got wrong. The corrected #4123 is now specific enough to build against directly: generic rows, a gap row, and existing pagers — no new persistence, no epoch bump. If you would rather not redo it after two false starts, let me know and I will take it over. Either way, I will review follow-ups within a day, not a week.

[Astro-Han]

Thanks for substantially simplifying this! My earlier comments about the timer/extra scroll writer and waiting for #4793 no longer apply; #4793 is closed, and I don't see a reason to require #4259 first.

One remaining P2 at 7fdc015: clicking the newer gap records a reading anchor, but only latest clears it. If loadAround evicts that anchor, restoreRange can load the old range again. Please let explicit newer navigation supersede the stale restore intent at the existing navigation seam, and cover that the page stays advanced. This is a source-level finding; I haven't reproduced it in Electron.

AI-assisted review with Codex.

[Sun-GLiang]

@Astro-Han Fixed in b93cefee6.

I reproduced the behavior in the Electron E2E: after explicit newer navigation, the newer range appeared briefly, then restoreRange restored the stale reading anchor and the older boundary disappeared again.

The fix stays at the existing loadTranscriptHistory navigation seam: explicit newer and latest navigation now clear the reading anchor, while earlier paging preserves it (source).

The existing bounded-history E2E now waits across rendered frames after clicking the newer gap and verifies that both boundaries remain present, so the page stays advanced (regression). The added assertion fails before the fix and passes after it.

Local verification passed: Desktop build, typecheck, 2163 Desktop tests, 101 architecture checks, and the targeted Electron E2E.

[Astro-Han]

Thanks for reproducing and fixing this! At e5365d2e, clearing the stale anchor at the existing navigation seam addresses my P2, and the Electron regression covers the page staying advanced. I found no new P0–P2 code issues; CI is green.

One final integration check: #4831 has since changed the scroll authority on main. Please rebase onto that baseline and verify older → newer → latest again, including focus and visible position. No further redesign is requested.

AI-assisted source review with Codex; I haven't independently rerun Electron.

[Sun-GLiang]

@Astro-Han Integrated the #4831 baseline in 6ef0e5ab1 and reran the older → newer → latest Electron path.

The added integration assertions exposed one focus issue: before the fix, the newer-gap button lost focus 10/10 times when the shared pending state temporarily rendered it disabled. 0e1d09e9c now restores focus only when that button initiated the load and focus still rests on the document body; it uses preventScroll, and does not reclaim focus after the reader moves to another control.

Verification after the fix:

• Electron bounded-history path: 10/10 passed with two workers. It now asserts the newer-gap button remains focused, its viewport position moves no more than 4px, and navigation still reaches the real latest Turn.
• Clean UI build and suite: 383/383 passed.
• Targeted gap, scroll-authority, and chat-scroll tests: 24/24 passed.
• Renderer architecture: 101/101 passed.
• npm run typecheck, npm run lint, npm run format:check, and git diff --check passed.
• CI test: passed in 12m13s on the updated head.

[Astro-Han]

Reviewed current head 0e1d09e9cd0da48f86208fa7f20c0c5c4778a1cd (OPEN). No P0–P1; one P2 and two P3s below. This is a user-facing feature; merging is a human decision regardless.

What it does, honestly this time

Previously, scrolling into a history range with unloaded messages showed a banner at the top of the session ("you are viewing history, jump to latest") — but the missing range is below, so the banner's position had nothing to do with the fact it described. Now gaps render where they actually are: "earlier messages above" and "newer messages below" gap rows inside the transcript list, via a pure projection (transcript-row-projection.ts:47-53). Notably the "newer" gap goes before the currently active/streaming turn (falling back to append only when activeTurnId is missing), so the live reply stays at the bottom instead of looking like history. The old "jump to latest" ability moved onto the existing scroll-to-bottom button (app-shell.tsx:2859) — a more intuitive home.

P2 — "scroll to bottom" is wired via click interception, not a prop

packages/ui/src/chat-surface-layout.tsx:87-95 wraps in a display: contents div with onClickCapture invoking the callback, instead of giving TranscriptScrollButton an onActivate-style prop. Please add the prop and drop the wrapper div.

P3 — both gap rows share one pending flag and spin together

In chat-view.tsx, both directions read isPending={props.historyLoadPending === true} — pressing "load earlier" also spins the untouched "load newer" button. Focus is not stolen (verified in component logic), so this is purely visual; split pending by direction to fix.

P3 — scroll-to-bottom still runs a pending state when already at the bottom

Pressing it while already at the latest position still goes through pending. Cosmetic; consider short-circuiting.

What I could not judge

Whether the design-system Button disables while isLoading was inferred from a11y-test behavior, not read from source (package not installed locally) — affects only the P3 severity above.

---

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

简体中文

本条结论全部来自 @Opus-Qronos-AstroHan 的审查。我自己没有读这份 diff；我核的是当前 head 有没有漂移。当前 head 是 0e1d09e，未关闭。把位置不对的提示改成了缺口行，P2 是滚动到底部用点击拦截接的，建议改 prop，另两条 P3 是视觉问题。功能类合并由人类拍板。