feat(desktop): unify session experience and stabilize transcript / 统一会话体验并稳定 Transcript 滚动

.github/workflows/ci.yml

@@ -395,6 +395,10 @@ jobs:
           pnpm --dir frontend test:motion-browser
           pnpm --dir frontend test:composer
           pnpm --dir frontend test:todo-visibility
+          pnpm --dir frontend test:app-lifecycle
+          PLAYWRIGHT_BROWSERS_PATH=.pw-browsers pnpm --dir frontend test:app-browser
+          PLAYWRIGHT_BROWSERS_PATH=.pw-browsers pnpm --dir frontend test:app-memory
+          pnpm --dir frontend test:all
           pnpm --dir frontend test:transcript
           xvfb-run -a env REASONIX_TRANSCRIPT_NATIVE_THUMB=1 pnpm --dir frontend test:transcript-browser
           PLAYWRIGHT_BROWSERS_PATH=.pw-browsers pnpm --dir frontend test:transcript-reader-browser

desktop/AGENTS.md

@@ -2,42 +2,124 @@
 
 ## Transcript scroll discipline
 
-The transcript (`frontend/src/components/Transcript.tsx`, react-virtuoso) has
-one structural rule set, earned across #8657/#8688 and the follow-up refactors.
-Keep to it when touching anything that can move the transcript viewport.
+The transcript (`frontend/src/components/Transcript.tsx`) is governed by
+`TimelineProjection` and the generation-aware `TranscriptKernel`. Keep these
+contracts when touching anything that can move the transcript viewport.
 
-- **Single writer**: only the scroll arbiter — `frontend/src/lib/useTranscriptScrollArbiter.ts`
-  and its extracted controllers (`transcriptTailSettle.ts`,
-  `transcriptAnchorCompensation.ts`) — may call
-  `virtuosoRef.current.scrollTo/scrollBy/scrollToIndex`, and raw
-  `scroller.scrollTop` assignments on transcript surfaces are equally
-  off-limits (route through the arbiter's `SCROLL_TO_OFFSET` channel, e.g.
-  owner `"anchor-compensation"` / `"block-window-prepend"`). Everything else
-  (jumps, tail-follow, selection edge scrolls, layout recovery) submits
-  requests to the arbiter. `frontend/scripts/check-single-scroll-writer.mjs`
-  enforces it statically; `lib/transcriptScrollProbe.ts` observes it at
-  runtime. Never add a second writer — extend the arbiter's reducer
-  (`lib/transcriptScrollArbiter.ts`) with an explicit transition instead.
-- **Preemption is explicit**: user intent (wheel/touch/key/pointer), selection,
-  and programmatic writers preempt an in-flight recovery through reducer
-  events that end it in a terminal state (done / cancelled / expired), each
-  reported to `noteTranscriptRecoveryTerminal`. No silent exits.
-- **Native geometry is authoritative**: Virtuoso's `atBottomStateChange` is a
-  delivery signal, not the bottom truth. Derive bottom ownership from the live
-  scroller's `scrollHeight - scrollTop - clientHeight`. Browser clamps may not
-  leave manual reading; only a delivered scroll with explicit reader intent
-  may re-enter tail-follow. Tail-follow persists across later measurements and
-  layout growth until explicit user intent releases it.
-- **No keyed remounts on content patches**: patches flow through `data` only;
-  Virtuoso re-measures mounted rows itself. Remounts happen only on surface
-  switches and blank-watchdog rebuilds, and restore from the measured-size
-  cache (`lib/transcriptMeasuredSizes.ts`) plus a state snapshot
-  (`lib/transcriptStateSnapshot.ts`) instead of static estimates.
+- **Stable identity**: one complete turn is the projection, anchor, and
+  virtualization unit. Block keys come from backend entry/user identity, never
+  array position. Prepend and content patches must not rename mounted blocks.
+- **Stable viewport actions**: controls that can be activated while range or
+  geometry state changes keep the same DOM identity. Visibility is state on a
+  mounted action host; do not conditionally remount it across viewport commits.
+- **Generation fence**: session/surface replacement increments the kernel
+  generation. Every delayed measurement, timer, animation-frame callback, and
+  write request carries that generation; stale work performs zero writes.
+  Async paging owns a source-session request identity; question navigation owns
+  generation plus interaction revision from request through positioned terminal
+  state. Native takeover cancels navigation, not a valid source data load. Old
+  completion/finally callbacks may release only their identical request.
+- **Single writer**: only `frontend/src/lib/transcriptViewportWriter.ts` may
+  mutate the transcript's native scroll position. Full-DOM, TanStack window,
+  Markdown, selection, question navigation, prepend, composer resize, and tail
+  follow all submit transactions to `TranscriptKernel`. The static gate in
+  `frontend/scripts/check-single-scroll-writer.mjs` must reject any bypass.
+- **Scroll provenance**: a physical writer offset remains pending until its
+  matching native `scroll` event is consumed or a different offset proves
+  user movement. Starting a gesture must not relabel a delayed writer event as
+  native input, and top-edge pagination reacts only to native-owned upward
+  movement, never a writer event or a reader moving away from the boundary.
+- **Explicit terminal state**: every transaction ends committed, cancelled, or
+  expired. User input and selection preempt lower-priority work; question jumps
+  outrank display/prepend/restore/resize, which outrank tail follow.
+- **Native geometry is authoritative**: bottom means
+  `scrollHeight - scrollTop - clientHeight <= 4`. TanStack computes prefix
+  sizes and mounted ranges only; its measurement compensation is disabled and
+  its scroll callback must never bypass the writer.
+- **Covered-range commit**: the Window Adapter may paint a TanStack candidate
+  only when it covers the current native viewport. Retain the last covering
+  geometry snapshot when a candidate is stale: mounted items, complete prefix, total extent,
+  and scroll margin are one atomic value and must never come from different
+  measurement generations. If a native jump invalidates both, rebuild once
+  from the prefix-size ledger while preserving every protected block.
+  Spend the bounded mount budget directionally: keep a reverse cushion, then
+  allocate the remaining runway ahead of current native motion so asynchronous
+  WebView scrolling cannot outrun the mounted range. Never exceed the completed
+  block mount cap to hide coverage races. The cap belongs to the whole adapter,
+  not only cold history: resident and protected blocks consume the same budget.
+  Retire measured resident prefixes and trim optional overscan before declaring
+  budget failure. Materialize third-party lazy cache views with `Array.from`;
+  a Proxy over mutable typed-array sizes is not an immutable prefix snapshot.
+  If no candidate, retained snapshot, or ledger reconstruction covers the
+  viewport, fail closed through the shared full-DOM safety renderer before
+  paint; never commit an uncovered range and detect the blank afterward.
+  Measurement-only notifications cannot replace the painted range while
+  native input owns an unchanged viewport. Native viewport geometry is an
+  external store: range renders must use its immutable snapshot so React
+  cannot commit a range calculated before a newer compositor scroll offset.
+  Window items use absolute layout `top`, not transforms that can put range
+  position and native scroll state into independently committed compositor
+  transactions.
+- **Anchor-safe measurement commit**: DOM measurements enter a block-keyed
+  staging ledger before they can change TanStack's prefix sizes. While native
+  input owns reader intent, the entire painted viewport is immutable: both the pre-measurement
+  prefix range and mounted DOM must place a block after the viewport before it
+  becomes a publish boundary. The logical Kernel anchor may only move that
+  boundary later. This prevents stale listeners, underestimated ranges, or
+  lazy blocks from reflowing any content the reader can see. TanStack's
+  `scrollMargin` is measured in the native scroller's coordinate space,
+  including Transcript padding and any prefix. Earlier and visible sizes remain
+  staged during native ownership; only post-viewport overscan may publish.
+  After ownership ends, publish staged DOM sizes under a Kernel logical-anchor
+  restore transaction. Prefix layout and anchor correction must complete in
+  one before-paint commit, cancelling any queued older geometry work.
+  Preserve the first reading anchor, while allowing later
+  blocks to move with actual content growth; freezing every old top would
+  overlap expanded content. Observe mounted absolute blocks as well as the
+  projection root, since local folds do not change the root extent. Tail intent
+  does not refine invisible cold history; its exact geometry belongs to resident DOM. During
+  bounded wheel input, the lazy measurement ledger owns a publish boundary at
+  least the unconsumed pixel-mode native steps plus one viewport ahead
+  of the painted viewport in both prefix and DOM geometry. Retire travel only
+  after physical viewport progress is observed; counting already-consumed
+  travel indefinitely freezes future measurements and builds a release-time
+  geometry debt. Keep the one-viewport reserve throughout the gesture lease. Touch, selection, keyboard jumps, nested handoff
+  without a bounded delta, and native thumb drag are unbounded: every cold
+  measurement remains staged until ownership ends.
+  Publish one immutable Reasonix snapshot, then transfer that exact published
+  batch into TanStack's keyed size cache in the same browser task. Never call
+  TanStack `measure()` for a measurement publish: it clears the keyed cache and
+  rebuilds the protected prefix. Never base correctness on an idle timeout,
+  enable TanStack-owned ResizeObserver publication, or add platform-specific
+  scroll compensation.
+- **Resident active tail**: the active turn and at least the two newest
+  completed turns stay in ordinary DOM. A resident block may enter windowed
+  history only after it is a viewport away and owns no anchor, focus, or
+  selection endpoint. Measure every contiguous leaving prefix into one ledger
+  snapshot before changing the resident boundary; estimated-size migration is
+  forbidden. Stream growth in reader intent performs zero writes.
+- **Bounded safe mode**: two blank/invalid/correction anomalies without an
+  intervening healthy frame in one generation switch that session to full DOM
+  until the next surface generation. Do not add a second rendering stack or a
+  persistent user flag. Normal full, windowed, and safety use one presentation
+  and observer lifecycle. Immediate safety mounts all currently paged blocks
+  with the last trusted cold prefix coordinates, retaining native keyed hosts,
+  focus, selection, and reader offset without a structural write. It stops
+  window eviction; it does not force offscreen history or large bodies to load.
+- **One geometry scheduler**: full/windowed layout, ResizeObserver, surface
+  paint, and auto-fill use cancellable Kernel frames. Observers bind generation
+  at registration and reject queued notifications even after disconnection.
+  Coalesce health validation and correction at one geometry entry; only one
+  clock-owned re-observation may precede the second-fault safety latch.
+- **Systemic fixes**: repair ownership, projection, measurement, or presentation
+  invariants in their common layer. Do not accumulate scenario-specific retry
+  branches, platform compensation, or progressively relaxed acceptance gates.
 - **Deterministic clocks**: new scroll logic must go through the same
-  injectable patterns as the existing code (global `requestAnimationFrame`,
-  `Date.now`, `window.setTimeout`) so the fake-clock harness can drive it —
-  no `performance.now`-only budgets or ad-hoc timers.
+  injectable clock used by `TranscriptKernel` (`requestAnimationFrame`,
+  `Date.now`, timer functions). No real sleeps or hidden retry clocks.
+- **No redundant physical writes**: a transaction whose requested offset has
+  already landed may commit as a no-op, but must not assign `scrollTop` again.
 - **Race tests are mandatory**: any scroll-behavior change ships with a
-  deterministic case in `frontend/src/__tests__/transcript-recovery-race.test.tsx`
-  (JSDOM + fake rAF/clock harness, stubbed `VirtuosoHandle`). Run
-  `pnpm test:transcript` before committing transcript changes.
+  deterministic event sequence in `frontend/src/__tests__/transcript-kernel.test.ts`
+  and, when relevant, a viewport/projection case. Run `pnpm test:transcript`
+  before committing transcript changes.

desktop/cmd/transcript-native-smoke/host_darwin.m

@@ -8,6 +8,8 @@
 #include <math.h>
 #include <unistd.h>
 
+static const int32_t ReasonixFinishWheelDelta = -1440;
+
 @interface ReasonixTranscriptSmokeHost : NSObject <WKNavigationDelegate, WKScriptMessageHandler>
 @property(nonatomic, strong) WKWebView *webView;
 @property(nonatomic, strong) NSWindow *window;
@@ -159,7 +161,7 @@ - (void)userContentController:(WKUserContentController *)controller didReceiveSc
     self.transcriptPoint = NSMakePoint(x, self.webView.isFlipped ? y : NSHeight(self.webView.bounds) - y);
     [self.window makeFirstResponder:self.webView];
     [self ensureInteractionFocus];
-    // The contract waits for settled Virtuoso geometry before posting ready.
+    // The contract waits for settled block-window geometry before posting ready.
     // Re-establish native focus at that boundary instead of relying on the
     // workflow's earlier best-effort app activation.
     dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 200 * NSEC_PER_MSEC), dispatch_get_main_queue(), ^{
@@ -277,7 +279,10 @@ - (void)finishNativeWheelTail {
 - (void)finishWheelBurst:(NSInteger)remaining {
   if (self.done) return;
   if (remaining > 0) {
-    [self dispatchWheelDelta:-120];
+    // The block ledger is taller than the retired row surface. Keep the same
+    // native event/time bound while giving the finishing phase enough physical
+    // wheel travel to reach the measured tail without a JavaScript scroll.
+    [self dispatchWheelDelta:ReasonixFinishWheelDelta];
     self.finishWheelEvents += 1;
     dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 50 * NSEC_PER_MSEC), dispatch_get_main_queue(), ^{
       [self finishWheelBurst:remaining - 1];
@@ -289,7 +294,7 @@ - (void)finishWheelBurst:(NSInteger)remaining {
 
 - (void)sendWheel:(NSTimer *)timer {
   // Sustain small high-resolution trackpad deltas without outrunning
-  // Virtuoso's mount window on a loaded hosted WebView.
+  // the block mount window on a loaded hosted WebView.
   const NSInteger totalTicks = self.localMicro ? 40 : 1200;
   if (self.wheelTick >= totalTicks) {
     [timer invalidate];
@@ -300,7 +305,7 @@ - (void)sendWheel:(NSTimer *)timer {
       });
       return;
     }
-    // Hosted WebKit can coalesce events while Virtuoso commits its last range.
+    // Hosted WebKit can coalesce events while the block window commits its last range.
     // After an idle boundary, keep sending bounded ordinary wheel events until
     // the native extent is stably at the tail. This remains native input; the
     // JavaScript probe only decides when the platform-specific fixture stops.