dsh-smooth-stream 0.4.3 → 0.6.0

package/src/client/teleprompterGlide.ts

@@ -96,11 +96,14 @@ export const FOLLOW_PAINT_GUARD_PX = 1
 export const FOLLOW_STATUS_RUNWAY_PX = 72
 
 /**
- * Duration of the lockstep runway retirement at stream end. The margin and
- * its canceling transform shrink together, so this duration is invisible;
- * it only bounds how long the owned margin lingers.
+ * Duration of completion runway retirement. The final pad is visible motion:
+ * its shrinking floor brings the transcript down to its natural resting
+ * position. 1.5s keeps the default 72px runway at 48px/s (0.8px per 60Hz
+ * frame), matching the configured default reading-follow velocity instead of
+ * the old 160ms / 450px/s staircase that looked like repeated completion
+ * jumps.
  */
-export const FOLLOW_RUNWAY_RETIRE_MS = 160
+export const FOLLOW_RUNWAY_RETIRE_MS = 1500
 
 /** How long a gesture keeps `isUserInteracting` so the next scroll can unpin. */
 export const FOLLOW_GESTURE_MS = 800
@@ -108,6 +111,23 @@ export const FOLLOW_GESTURE_MS = 800
 /** Sub-pixel settle threshold; clearing below this cannot produce a visible rebound. */
 export const FOLLOW_SETTLE_EPSILON_PX = 0.25
 
+/**
+ * How long the completion settle waits for the HOST's completion cascade —
+ * status-row swap, think auto-collapse, metrics-tail mount — to stop moving
+ * the scroll extent before the follower releases the port. Releasing earlier
+ * hands a still-changing layout to the host's hard floor-snap, which paints
+ * each host action as a single-frame slam of the whole transcript.
+ */
+export const FOLLOW_SETTLE_QUIET_MS = 240
+
+/**
+ * Ceiling for the flow's completion pad. The pad backs the floor so the
+ * pinned viewport can follow the reading anchor through host completion
+ * commits (row swaps/insertions); capping it bounds the below-fold blank
+ * space a long conversation accumulates.
+ */
+export const FOLLOW_SETTLE_PAD_CAP_PX = 2 * FOLLOW_STATUS_RUNWAY_PX
+
 /** Retained visual-motion budget for compatibility with diagnostics/tests. */
 export const FOLLOW_CATCHUP_MAX_STEP_PX = 8
 
@@ -119,9 +139,11 @@ export const FOLLOW_CATCHUP_MAX_STEP_PX = 8
  * line glides in (slow start) instead of snapping.
  */
 /**
- * Per-frame bound on the DECAY side of the painted shift only (runway
- * retirement and settle). The growth side is wrap compensation and must stay
- * unlimited — see the clamp site in `applyVisual`.
+ * Per-frame bound on the DECAY side of the painted shift (runway retirement
+ * and settle), widened by any same-frame floor drop so extent collapses are
+ * always fully repainted — see the clamp site in `applyVisual`. The growth
+ * side stays unlimited: it is wrap compensation locked to the same-frame
+ * floor step.
  */
 export const FOLLOW_PAINT_SHIFT_MAX_STEP_PX = 8
 
@@ -393,7 +415,7 @@ function resizeProxyOf(port: HTMLElement): HTMLElement | null {
  * Outermost message surfaces; nested tool rows ride their parent.
  *
  * Another plugin may insert its own element as a flow sibling of the Chat rows
- * (meow-memory's fold bar is one; so is this plugin's own fold summary row).
+ * (meow-memory's fold bar is one).
  * Such a row carries no `data-chat-anchor-key`, so selecting only anchored
  * rows would shift the conversation while leaving the foreign row at its
  * natural offset, letting the shifted rows paint over it. Every direct flow
@@ -612,6 +634,189 @@ const followPaintLimits = new WeakMap<HTMLElement, FollowPaintLimit>()
 const followHadChrome = new WeakSet<HTMLElement>()
 /** Last painted shift per port, to spread a wrap's one-line step over frames. */
 const followLastShiftPx = new WeakMap<HTMLElement, number>()
+/** Last settled floor per port, to size the shift decay bound against extent collapse. */
+const followLastFloorPx = new WeakMap<HTMLElement, number>()
+/**
+ * Screen-space completion anchor per port, SHARED by every follower arm and
+ * the settle loop. Per-arm closures made the guard incoherent across the
+ * completion cascade: block arms hand off leadership mid-turn, each new
+ * settle loop re-seeded its own baseline at the already-jumped position, and
+ * the cascade's one-frame clamp jump painted uncompensated. One baseline per
+ * port also makes concurrent guards idempotent — whoever compensates first
+ * restores the anchor, so the second measure reads ~0 and grants nothing.
+ *
+ * The anchor is the READING surface (the current turn's assistant row), not
+ * the bottom-most shift surface: the cascade mounts/unmounts rows at the
+ * column's bottom (process/tail mount, status swap), which switches
+ * `at(-1)`'s identity mid-guard. Measuring across that switch reads a newly
+ * mounted tail row as a >1000px "content moved down" push and floods the
+ * pad, while the reading surface's real clamp jump goes uncompensated.
+ */
+interface FollowGuardAnchor {
+  readonly element: HTMLElement
+  /** Held viewport top — the position the reader should keep seeing. */
+  readonly top: number
+  /** Flow-child index, to tell an in-place replacement from a new turn. */
+  readonly index: number
+  /** Scroll geometry at store time, to identify an extent-neutral scroll. */
+  readonly scrollTop: number
+  readonly scrollHeight: number
+  /**
+   * Compositor shift and owned pad at store time. The engine moves the
+   * rendered anchor between guard passes through TWO channels — the shift
+   * glide (reveal decay: renderedΔ = −shiftΔ) and the pad retirement (the
+   * floor sinks with the pad and the pin follows: renderedΔ = −padΔ). Only
+   * the delta beyond BOTH is host motion worth compensating.
+   */
+  readonly shift: number
+  readonly pad: number
+}
+const followGuardAnchors = new WeakMap<HTMLElement, FollowGuardAnchor>()
+/**
+ * Ports whose completion settle loop owns the follow. The settle drains the
+ * reveal, retires the pad and guards the cascade; the swap that ends the
+ * turn REMOUNTS the follower arms in the same frame cluster, and a freshly
+ * mounted arm primes with a higher generation and would otherwise steal the
+ * port mid-drain — its observers miss the cascade mutations (armed after
+ * the fact) and its state initialization re-materializes engine space.
+ * Ownership is released only when the settle finishes, the reader gestures,
+ * or a genuinely NEW turn arrives (a user row joined since the handoff).
+ */
+const followCompletionSettle = new WeakSet<HTMLElement>()
+/** User-row count at handoff, for the new-turn check above. */
+const followCompletionSettleRows = new WeakMap<HTMLElement, number>()
+
+/** User rows below the flow, or -1 when the host does not label rows with
+ *  `data-chat-flow-kind` (the engine's own audit benches): the new-turn
+ *  check is unsupported there and ownership guarding must stay OFF. */
+function countUserRows(port: HTMLElement): number {
+  const flow = flowElementOf(port)
+  if (flow === null) return -1
+  let count = 0
+  let sawKind = false
+  for (const child of flow.children) {
+    if (!(child instanceof HTMLElement)) continue
+    const kind = child.getAttribute('data-chat-flow-kind')
+    if (kind !== null) sawKind = true
+    if (kind === 'user') count++
+  }
+  return sawKind ? count : -1
+}
+
+/** True while this port's completion settle owns the follow and no new turn
+ *  has arrived since the handoff. */
+function completionSettleGuardsPort(port: HTMLElement): boolean {
+  if (!followCompletionSettle.has(port)) return false
+  const baseline = followCompletionSettleRows.get(port) ?? -1
+  const current = countUserRows(port)
+  return baseline >= 0 && current >= 0 && current <= baseline
+}
+/**
+ * Ports whose completion settle loop owns the follow. A settle loop drains,
+ * retires the pad and guards the cascade; an arm that primes while this is
+ * set with `active === false` (the settled-side static arm mounting in the
+ * very swap frame) must NOT seize leadership — the swap re-renders the node
+ * view, a fresh arm would otherwise steal the port mid-drain with
+ * `reservePx = ownedBottomSpace` (the pad!), re-materialize an equal runway
+ * through applyVisual, double-count the extent and fight the settle's own
+ * guard for the rest of the window. A streaming arm (active === true, the
+ * next turn) still takes over normally and the settle yields.
+ */
+
+function readingAnchorOf(port: HTMLElement): HTMLElement | null {
+  const flow = flowElementOf(port)
+  if (flow === null) return null
+  let anchor: HTMLElement | null = null
+  for (const child of flow.children) {
+    if (!(child instanceof HTMLElement)) continue
+    if (child.getAttribute('data-chat-flow-kind') === 'assistant' || child.querySelector('[data-variant="think"]') !== null) {
+      anchor = child
+    }
+  }
+  return anchor ?? shiftSurfacesOf(port).at(-1) ?? null
+}
+
+/**
+ * Measure the reading surface's screen delta since the last guard pass.
+ * Returns null when there is nothing comparable yet (first observation), or
+ * when the anchor changed identity in a way that is NOT the in-place
+ * live→settled replacement (a new turn's row joined — nothing jumped,
+ * re-seed). Compensation sites must store the POST-compensation held
+ * position via `holdGuardAnchor`, or the guard would read its own
+ * correction as a fresh jump and oscillate.
+ */
+function measureReadingAnchor(port: HTMLElement): { anchor: HTMLElement; index: number; top: number; delta: number } | null {
+  const anchor = readingAnchorOf(port)
+  if (anchor === null) {
+    followGuardAnchors.delete(port)
+    return null
+  }
+  const rect = anchor.getBoundingClientRect()
+  // Unmeasurable geometry (jsdom's zero rects, a detached row): screen-space
+  // comparison is meaningless — never seed or compensate from it.
+  if (!(rect.width > 0 || rect.height > 0)) return null
+  const top = rect.top
+  const shift = currentShiftOf(anchor)
+  const pad = flowPadOf(port)
+  const scrollTop = port.scrollTop
+  const scrollHeight = port.scrollHeight
+  const flow = flowElementOf(port)
+  const index = flow === null ? -1 : [...flow.children].indexOf(anchor)
+  const stored = followGuardAnchors.get(port)
+  if (stored === undefined) {
+    followGuardAnchors.set(port, { element: anchor, top, index, shift, pad, scrollTop, scrollHeight })
+    return null
+  }
+  // A host bottom-follow write is NOT a layout push. With extent unchanged, a
+  // scrollTop change only moves the whole viewport; granting pad for it would
+  // manufacture blank space and then require a second "retirement" motion.
+  // Rebase both ledgers and let the writer keep its scroll position.
+  if (
+    Math.abs(scrollHeight - stored.scrollHeight) <= 0.5
+    && Math.abs(scrollTop - stored.scrollTop) > 0.5
+  ) {
+    followScrollLedgers.set(port, scrollTop)
+    followGuardAnchors.set(port, { element: anchor, top, index, shift, pad, scrollTop, scrollHeight })
+    return null
+  }
+  // Host-caused motion only: the engine's own shift glide and floor changes
+  // cancel out (renderedΔ = topΔ − shiftΔ + floorΔ).
+  const delta = (top - stored.top) - (shift - stored.shift) + (pad - stored.pad)
+  if (stored.element === anchor) {
+    // Refresh the baseline to the current rendered position on every
+    // measurement: between guard passes the viewport legitimately moves
+    // (streaming pins, reveal glide), and a stale baseline would read the
+    // accumulated motion as one giant host jump at the next commit.
+    followGuardAnchors.set(port, { element: anchor, top, index, shift, pad, scrollTop, scrollHeight })
+    return { anchor, index, top, delta }
+  }
+  // Identity changed. An in-place replacement (same slot, old node detached)
+  // is the live→settled swap: bridge it by holding the reading surface at
+  // its pre-swap viewport position. Anything else (the next turn's row
+  // joining below, a session swap) is new layout — re-seed, never hold.
+  if (!stored.element.isConnected && stored.index === index) {
+    return { anchor, index, top, delta }
+  }
+  followGuardAnchors.set(port, { element: anchor, top, index, shift, pad, scrollTop, scrollHeight })
+  return null
+}
+
+/** Record the position the reader should keep seeing after a correction. */
+function holdGuardAnchor(
+  port: HTMLElement,
+  measured: { anchor: HTMLElement; index: number },
+  heldTop: number,
+): void {
+  followGuardAnchors.set(port, {
+    element: measured.anchor,
+    index: measured.index,
+    top: heldTop,
+    shift: currentShiftOf(measured.anchor),
+    pad: flowPadOf(port),
+    scrollTop: port.scrollTop,
+    scrollHeight: port.scrollHeight,
+  })
+}
 /** Last runway offset seen per port, to rebase the extent when the margin size changes. */
 const followRunwayOffsetHistory = new WeakMap<HTMLElement, number>()
 /** Last observed scroll floor per port, for the slack→overflow runway re-measure. */
@@ -619,6 +824,93 @@ const followFloorHistory = new WeakMap<HTMLElement, number>()
 /** One-shot flag: the transition frame must paint the full runway as baseline. */
 const followSlackTransition = new WeakSet<HTMLElement>()
 
+/**
+ * Bottom padding a completed settle left BELOW the status row. The settle
+ * retires the owned runway by moving it from the status's top margin (the
+ * visible reserve gap) to the flow's bottom padding (space under the chrome):
+ * scroll extent stays constant, so the floor — and therefore the pinned
+ * scrollTop and every content pixel — never moves, while the status glides up
+ * to meet the final line. The pad is reclaimed back into the next stream's
+ * runway by `ensureRunway`, so completions never accumulate dead space.
+ */
+interface FollowSettlePad {
+  readonly element: HTMLElement
+  readonly original: string
+  readonly px: number
+}
+const followSettlePads = new WeakMap<HTMLElement, FollowSettlePad>()
+
+/**
+ * Retired follower space lives as `padding-bottom` on the FLOW element — the
+ * one node the engine already owns styles on (flow-fill min-height) and the
+ * host never rewrites. Host completion commits routinely REPLACE row elements
+ * (live→settled swap re-keys the assistant row, the status row unmounts), and
+ * any engine space written on those rows dies with them, sinking the floor
+ * and slamming the pinned transcript for a frame. The flow survives.
+ */
+function flowPadOf(port: HTMLElement): number {
+  return followSettlePads.get(port)?.px ?? 0
+}
+/**
+ * After a loss is re-opened as pad, a registry entry whose element is no
+ * longer connected claims extent that no longer exists; drop it so the next
+ * `ensureRunway` re-measures fresh instead of double-counting.
+ */
+function pruneDeadRunway(port: HTMLElement): boolean {
+  const runway = followRunways.get(port)
+  if (runway !== undefined && !runway.element.isConnected) {
+    restoreRunway(port)
+    return true
+  }
+  return false
+}
+
+function setFlowPad(port: HTMLElement, px: number): void {
+  const flow = flowElementOf(port)
+  if (flow === null) return
+  const existing = followSettlePads.get(port)
+  const original = existing?.original ?? flow.style.paddingBottom
+  if (px <= FOLLOW_SETTLE_EPSILON_PX) {
+    if (existing !== undefined) {
+      flow.style.paddingBottom = existing.original
+      followSettlePads.delete(port)
+    }
+    return
+  }
+  flow.style.paddingBottom = original === ''
+    ? `${px}px`
+    : `calc(${original} + ${px}px)`
+  followSettlePads.set(port, { element: flow, original, px })
+}
+
+/** Extent the follower owns below the content: the live runway margin plus
+ *  the retired completion pad. At adopt the pad is reclaimed into the fresh
+ *  reservation (same frame, pre-paint), so the floor never steps. */
+function ownedBottomSpaceOf(port: HTMLElement): number {
+  return runwayOffsetOf(port) + flowPadOf(port)
+}
+
+/**
+ * Completion-window diagnostics. Armed when a follower hands off to its
+ * settle loop; every engine decision and every externally-written scroll
+ * position inside the window prints one compact console line, so a live
+ * host session can be diffed against the lab without a debugger.
+ */
+let followTraceUntilMs = 0
+function traceActive(): boolean {
+  // Completion/finalize paths arm short trace windows automatically. Keep the
+  // code path in published bundles, but do not emit console noise unless the
+  // user has explicitly turned on render diagnostics.
+  return debugRuntime.isEnabled() && performance.now() < followTraceUntilMs
+}
+function followTrace(event: string, detail: Record<string, number | string | boolean>): void {
+  if (!traceActive()) return
+  console.log(`[dsh-follow] ${event}`, JSON.stringify(detail))
+}
+function hostShOf(port: HTMLElement): number {
+  return port.scrollHeight
+}
+
 function invalidatePaintLimit(port: HTMLElement): void {
   followPaintLimits.delete(port)
 }
@@ -797,6 +1089,39 @@ function runwayOffsetOf(port: HTMLElement): number {
   return followRunways.get(port)?.offset ?? 0
 }
 
+/**
+ * Move owned runway margin into the persistent flow pad without changing the
+ * scroll extent. Returns the actual layout pixels removed from the margin.
+ */
+function transferRunwayToFlowPad(port: HTMLElement, requestedPx: number): number {
+  const runway = followRunways.get(port)
+  if (runway === undefined || requestedPx <= 0 || !runway.element.isConnected) return 0
+  const nextRequestedPx = Math.max(0, runway.requestedPx - requestedPx)
+  const beforeOffset = runway.offset
+  const beforeHeight = port.scrollHeight
+  runway.element.style[runway.property] = nextRequestedPx <= FOLLOW_SETTLE_EPSILON_PX
+    ? runway.original
+    : runway.original === ''
+      ? `${nextRequestedPx}px`
+      : `calc(${runway.original} + ${nextRequestedPx}px)`
+  const nextOffset = Math.max(0, beforeOffset + port.scrollHeight - beforeHeight)
+  const transferredPx = Math.max(0, beforeOffset - nextOffset)
+  if (nextRequestedPx <= FOLLOW_SETTLE_EPSILON_PX || nextOffset <= FOLLOW_SETTLE_EPSILON_PX) {
+    followRunways.delete(port)
+  } else {
+    followRunways.set(port, {
+      ...runway,
+      offset: nextOffset,
+      requestedPx: nextRequestedPx,
+    })
+  }
+  if (transferredPx > 0) {
+    setFlowPad(port, flowPadOf(port) + transferredPx)
+    invalidatePaintLimit(port)
+  }
+  return transferredPx
+}
+
 /** Available paint room below the last message before fixed conversation chrome. */
 function safeShiftLimit(
   port: HTMLElement,
@@ -850,6 +1175,18 @@ function safeShiftLimit(
 }
 
 function setFollowScrollTop(port: HTMLElement, nextTop: number): void {
+  const ledger = followScrollLedgers.get(port)
+  // Claim before the write so a Host ResizeObserver that runs in the same task
+  // sees the owner instead of racing in with its own bottom-follow.
+  if (port.getAttribute(FOLLOW_OWNED_ATTR) === null) {
+    port.setAttribute(FOLLOW_OWNED_ATTR, 'active')
+  }
+  // Someone else wrote scrollTop since our last write (host floor-snap,
+  // browser clamp, reader): surface it — a fight between the host's own
+  // follow controller and this engine is the completion-jitter suspect.
+  if (ledger !== undefined && traceActive() && Math.abs(port.scrollTop - ledger) > 1) {
+    followTrace('external-scroll', { from: Math.round(port.scrollTop), to: Math.round(nextTop), ledger: Math.round(ledger) })
+  }
   if (Math.abs(port.scrollTop - nextTop) > 0.01) port.scrollTop = nextTop
   followScrollLedgers.set(port, port.scrollTop)
   const ownedTop = String(port.scrollTop)
@@ -866,6 +1203,24 @@ function setFollowScrollTop(port: HTMLElement, nextTop: number): void {
  */
 const followScrollLedgers = new WeakMap<HTMLElement, number>()
 const followActivityAt = new WeakMap<HTMLElement, number>()
+interface FollowScrollOwnership {
+  /** User-row count at handoff; a larger count means a genuinely new turn. */
+  readonly userRows: number
+}
+/**
+ * Scroll ownership must survive follower-arm remounts. Per-closure state let a
+ * new text/tool arm reset the strike counter, so the same host write kept
+ * triggering another engine write and repainting the visible up/down fight.
+ */
+const followHostScrollPorts = new WeakMap<HTMLElement, FollowScrollOwnership>()
+
+/** Clear host ownership only when a new user turn actually starts. */
+function resetHostScrollOwnershipForNewTurn(port: HTMLElement): void {
+  const ownership = followHostScrollPorts.get(port)
+  if (ownership === undefined) return
+  const userRows = countUserRows(port)
+  if (userRows >= 0 && userRows > ownership.userRows) followHostScrollPorts.delete(port)
+}
 
 /** Whether this port was owned recently enough to identify a closing tail row. */
 export function hasRecentConversationFollow(port: HTMLElement, windowMs = 250): boolean {
@@ -894,6 +1249,8 @@ function applyVisual(
   shiftCeilingPx = Number.POSITIVE_INFINITY,
   promoteAtRest = false,
   trajectoryShiftPx?: number,
+  dtMs = 16.7,
+  writeScrollTop = true,
 ): number {
   const surfaces = shiftSurfacesOf(port)
   ensureFlowFillsPort(port)
@@ -917,10 +1274,6 @@ function applyVisual(
       followSlackTransition.add(port)
     }
     if (preFloor !== lastFloorSeen) {
-      // A changed floor means the natural tail geometry may have changed. This
-      // is the infrequent layout-growth boundary; ordinary same-floor reveal
-      // commits continue to use the cached chrome clearance.
-      invalidatePaintLimit(port)
       followFloorHistory.set(port, preFloor)
     }
   }
@@ -947,7 +1300,7 @@ function applyVisual(
   if (port.style.scrollBehavior !== 'auto') port.style.scrollBehavior = 'auto'
   if (floor <= 0) {
     followRunwayOffsetHistory.set(port, 0)
-    setFollowScrollTop(port, 0)
+    if (writeScrollTop) setFollowScrollTop(port, 0)
     followMotionStates.set(port, {
       capacityPx: Number.POSITIVE_INFINITY,
       constrained: false,
@@ -997,23 +1350,60 @@ function applyVisual(
   const idlePromotion = promoteAtRest && motionShift <= 0.01 && availableShift > 0 ? 0.1 : 0
   let shift = Math.max(motionShift, idlePromotion)
   const previousShift = followLastShiftPx.get(port)
-  if (previousShift !== undefined && shift < previousShift - FOLLOW_PAINT_SHIFT_MAX_STEP_PX) {
+  // The per-frame decay bound paces the engine's OWN glide (the margin
+  // transfer retires at well under 8px/frame, so the limiter never binds for
+  // it). It must NOT cap the compensation for a floor the engine did not
+  // choose: the host completion cascade (think auto-collapse, status swap)
+  // collapses the extent tens of px in one frame, scrollTop follows the
+  // floor 1:1, and a decay capped at 8px/frame leaves the unpainted
+  // remainder on screen — the completion 回弹 (visible 14-26px/frame sink).
+  // Widen the bound by the floor's drop so the shift can always repaint what
+  // the extent took away; the retire glide is unaffected because its
+  // motionShift never moves.
+  const previousFloor = followLastFloorPx.get(port)
+  const floorDropPx = Math.max(0, (previousFloor ?? floor) - floor)
+  const maxDecayPx = Math.max(
+    dtMs <= 0
+      ? FOLLOW_PAINT_SHIFT_MAX_STEP_PX
+      : Math.max(1, (FOLLOW_PAINT_SHIFT_MAX_STEP_PX / 16.67) * dtMs),
+    floorDropPx,
+  )
+  followLastFloorPx.set(port, floor)
+  if (previousShift !== undefined && shift < previousShift - maxDecayPx) {
     // Decay-only rate limit. Growth is a WRAP COMPENSATION: the floor already
     // jumped one line in the same layout pass and `scrollTop` followed it, so
     // the matching shift increase cancels that step exactly. Rate-limiting it
     // paints the uncovered remainder as a visible one-frame jump (the
     // "换行 18px 跳变"). Only the decay side — runway retirement and settle —
     // is a real animation and keeps its per-frame bound.
-    shift = previousShift - FOLLOW_PAINT_SHIFT_MAX_STEP_PX
+    shift = previousShift - maxDecayPx
+  }
+  // COMPLETION RISE FUNDING. In the completion window a shift rise is only
+  // invisible when it cancels floor growth the reader actually gets. The
+  // handoff re-opens the runway while the think disclosure is still
+  // collapsing: a same-task paint funded on the measured extent growth
+  // over-covers by whatever the transition retracts before the paint lands —
+  // the drain-onset 回弹. Same-task painters are therefore ceiling-frozen
+  // (see the observer and the handoff below) and this clamp funds the
+  // settle's rAF-frame rise on the growth CONFIRMED since the previous
+  // paint; a completion without a collapse covers the runway in full on the
+  // first frame (the drain contract). The streaming path never enters this
+  // branch — wrap compensation stays unlimited there.
+  if (followCompletionSettle.has(port) && previousShift !== undefined && previousFloor !== undefined) {
+    const confirmedGrowthPx = Math.max(0, floor - previousFloor)
+    if (shift > previousShift + confirmedGrowthPx) shift = previousShift + confirmedGrowthPx
   }
   followLastShiftPx.set(port, shift)
-  const effectiveLag = Math.max(0, motionShift - baselineShift)
+  const requestedShift = trajectoryShiftPx ?? (baselineShift + requestedLag)
+  const effectiveLag = Math.max(0, shift - baselineShift)
   const capacityPx = Math.max(0, limit - baselineShift)
   const effectiveExtent = targetHeight - effectiveLag
-  setFollowScrollTop(port, floor)
+  const isConstrained = requestedShift > availableShift + FOLLOW_SETTLE_EPSILON_PX
+    || (limit <= 0 && requestedShift > baselineShift)
+  if (writeScrollTop) setFollowScrollTop(port, floor)
   followMotionStates.set(port, {
     capacityPx,
-    constrained: requestedLag > effectiveLag + FOLLOW_SETTLE_EPSILON_PX,
+    constrained: isConstrained,
     extent: effectiveExtent,
     lagPx: effectiveLag,
     reservePx: visibleReserve,
@@ -1039,6 +1429,7 @@ function clearVisual(port: HTMLElement): void {
   restoreRunway(port)
   followMotionStates.delete(port)
   followLastShiftPx.delete(port)
+  followLastFloorPx.delete(port)
   invalidatePaintLimit(port)
 }
 
@@ -1050,12 +1441,19 @@ function holdCompositorAtRest(element: HTMLElement): void {
 }
 
 /** Remove equal offsets, land on the floor, then retire the compositor quietly. */
-function finishAtNaturalFloor(port: HTMLElement, retainCompositor = true): void {
+function finishAtNaturalFloor(
+  port: HTMLElement,
+  retainCompositor = true,
+  writeScrollTop = true,
+): void {
+  followCompletionSettle.delete(port)
+  followTraceUntilMs = Math.max(followTraceUntilMs, performance.now() + 10000)
+  followTrace('finish-enter', { sh: hostShOf(port), st: Math.round(port.scrollTop), pad: Math.round(flowPadOf(port)), retain: retainCompositor })
   const surfaces = shiftSurfacesOf(port)
   const status = turnStatusOf(port)
   if (!retainCompositor) {
     restoreRunway(port)
-    settleAtFloor(port)
+    if (writeScrollTop) settleAtFloor(port)
     clearMotion(port)
     followMotionStates.delete(port)
     return
@@ -1063,8 +1461,7 @@ function finishAtNaturalFloor(port: HTMLElement, retainCompositor = true): void
   const promoted = [...surfaces, ...(status === null ? [] : [status])]
     .filter(element => element.style.transform !== '' || element.style.willChange === 'transform')
   const promotedSet = new Set(promoted)
-  restoreRunway(port)
-  settleAtFloor(port)
+  if (writeScrollTop) settleAtFloor(port)
   port.removeAttribute(FOLLOW_OWNED_ATTR)
   port.style.overflowAnchor = ''
   port.style.scrollBehavior = ''
@@ -1101,6 +1498,8 @@ interface FollowLeader {
 /** Only the newest active follower may write one port's shared visual state. */
 const followLeaders = new WeakMap<HTMLElement, FollowLeader>()
 let followGeneration = 0
+/** Ports with a live streaming arm; completion guards must not fight them. */
+const followActivePorts = new WeakSet<HTMLElement>()
 
 /**
  * Own the conversation scrollport's bottom-follow while `active` is true.
@@ -1115,6 +1514,7 @@ let followGeneration = 0
  * @param predictiveRef - Optional live visibility gate for predictive runway.
  * @param entranceExtentRef - Optional measured growth delta for a generic row.
  * @param revealedCharsRef - Committed code-point count for feed-forward phase.
+ * @param controlScroll - When false, leave the scrollport entirely to the Host.
  */
 export function useConversationFollow(
   rootRef: RefObject<HTMLElement | null>,
@@ -1127,6 +1527,7 @@ export function useConversationFollow(
   predictiveRef?: { current: boolean },
   entranceExtentRef?: { current: number | null },
   revealedCharsRef?: { current: number },
+  controlScroll = true,
 ): void {
   const activeRef = useRef(active)
   const entranceRef = useRef(entrance)
@@ -1134,8 +1535,11 @@ export function useConversationFollow(
   entranceRef.current = entrance
   onEntranceSettledRef.current = onEntranceSettled
   activeRef.current = active
+  const controlScrollRef = useRef(controlScroll)
+  controlScrollRef.current = controlScroll
 
   useLayoutEffect(() => {
+    if (!controlScroll) return
     if (!active) return
     const startedAsEntrance = entrance
     const owner = {}
@@ -1154,8 +1558,10 @@ export function useConversationFollow(
     let interactTimer: ReturnType<typeof setTimeout> | null = null
     let port: HTMLElement | null = null
     let resize: ResizeObserver | null = null
+    let mutations: MutationObserver | null = null
     let observedTail: HTMLElement | null = null
     let statusWasPresent: boolean | null = null
+    let lastStatusHeightPx = 0
     let trajectoryPositionPx: number | null = null
     let trajectoryVelocityPxPerMs = 0
     let trajectoryTargetVelocityPxPerMs = 0
@@ -1223,11 +1629,52 @@ export function useConversationFollow(
       if (holding === next && isLeader(next)) return
       holding = next
       const leader = followLeaders.get(next)
-      if (leader === undefined || generation > leader.generation) {
+      if ((leader === undefined || generation > leader.generation) && !completionSettleGuardsPort(next)) {
+        followCompletionSettle.delete(next)
         followLeaders.set(next, { generation, owner })
       }
     }
 
+    const yieldScrollOwnership = (next: HTMLElement, floor: number): void => {
+      if (hostOwnsScroll) return
+      hostOwnsScroll = true
+      followHostScrollPorts.set(next, { userRows: countUserRows(next) })
+      followTrace('yield-scroll', {
+        from: Math.round(next.scrollTop),
+        to: Math.round(floor),
+      })
+      // A host-owned port must be a clean host-owned render. Keeping the
+      // engine's transform/reserve alive lets its decay fight the host's hard
+      // bottom-follow; that is the visible up/down jitter after handoff.
+      clearVisual(next)
+      const naturalFloor = Math.max(0, next.scrollHeight - next.clientHeight)
+      setFollowScrollTop(next, naturalFloor)
+      next.removeAttribute(FOLLOW_OWNED_ATTR)
+      followLeaders.delete(next)
+      releaseRevealScale()
+      debugRuntime.reportFollow(next, null)
+    }
+
+    const detectHostScroll = (next: HTMLElement, floor: number): void => {
+      if (followHostScrollPorts.has(next)) {
+        hostOwnsScroll = true
+        return
+      }
+      const ledger = followScrollLedgers.get(next)
+      if (ledger === undefined || Math.abs(next.scrollTop - ledger) <= 1) return
+      // A write that lands on the current floor has the same semantics as our
+      // own bottom-follow (including a manual jump-to-bottom or a shrink
+      // clamp). Rebase and keep smoothing; treating it as a second writer
+      // would permanently retire the effect for the rest of the turn.
+      if (Math.abs(next.scrollTop - floor) <= 1) {
+        followScrollLedgers.set(next, next.scrollTop)
+        externalScrollStrikes = 0
+        return
+      }
+      externalScrollStrikes += 1
+      if (externalScrollStrikes >= 2) yieldScrollOwnership(next, floor)
+    }
+
     const drop = (next: HTMLElement): void => {
       if (holding === next) holding = null
       if (isLeader(next)) {
@@ -1282,8 +1729,186 @@ export function useConversationFollow(
       }, FOLLOW_GESTURE_MS)
     }
 
+    /**
+     * Last observed scroll extent, shared by the pre-paint correction and the
+     * settle loop so a host layout shrink is re-opened exactly once no matter
+     * which observer sees it first. `-1` until the first owned observation.
+     */
+    let settleRetiring = false
+    // The engine may lead streaming writes, but the host also owns a
+    // bottom-follow controller. Ledger disagreement is harmless once; a
+    // repeated disagreement is proof of a second writer. Hand the scrollport
+    // to that writer immediately: the engine keeps compositor compensation but
+    // never writes scrollTop again. This is the only way to avoid a ping-pong
+    // fight when the host bundle does not consume `data-follow-owned`.
+    let hostOwnsScroll = false
+    let externalScrollStrikes = 0
+    let lastReadingAnchorPullAtMs = Number.NEGATIVE_INFINITY
+    let readingAnchorPullBudgetPx = 0
+    // Set once this closure's completion handoff has armed its settle loop.
+    // Only a handed-off arm's observers may guard a LEADERLESS port: mid-turn
+    // arms that never handed off must keep standing down (entrance/steaming
+    // successors own the port), while a handed-off arm whose settle loop was
+    // killed by leadership churn is the only pre-paint guard left when the
+    // completion cascade lands in the leaderless window.
+    let handedOff = false
+    /**
+     * Bring the reading surface back down toward its held position after an
+     * upward host push (clamp jump, live→settled swap): spend persistent pad
+     * first — lowering the floor lets the pin carry the text back down —
+     * then raise the compositor shift for whatever pad cannot cover, and
+     * rebase the spring extent so the raise survives the next applyVisual
+     * (which otherwise recomputes the shift from lag and undoes it).
+     */
+    const pullReadingAnchorBack = (
+      host: HTMLElement,
+      measured: { anchor: HTMLElement; index: number; top: number; delta: number },
+      trace = false,
+    ): void => {
+      // Experimental no-rebound gate: an upward correction here has repeatedly
+      // over/under-compensated against the settle loop's floor writes. Hold the
+      // new position instead of issuing a reverse correction; the monotone
+      // final retirement remains the only release path.
+      holdGuardAnchor(host, measured, measured.top)
+      return
+      const need = -measured.delta
+      // A large host shrink must not spend its whole pad in one paint. Keep
+      // the screen anchored with an immediate shift, then hand the floor back
+      // at the same bounded rate as the final retirement.
+      const now = performance.now()
+      const elapsedPx = lastReadingAnchorPullAtMs === Number.NEGATIVE_INFINITY
+        ? FOLLOW_PAINT_SHIFT_MAX_STEP_PX
+        : Math.min(24, Math.max(0, now - lastReadingAnchorPullAtMs) * (FOLLOW_PAINT_SHIFT_MAX_STEP_PX / 16.7))
+      readingAnchorPullBudgetPx = Math.min(need, readingAnchorPullBudgetPx + elapsedPx)
+      lastReadingAnchorPullAtMs = now
+      const released = Math.min(flowPadOf(host), readingAnchorPullBudgetPx)
+      readingAnchorPullBudgetPx -= released
+      if (released > FOLLOW_SETTLE_EPSILON_PX) {
+        if (trace) {
+          followTrace('anchor-pull', { screenDelta: Math.round(measured.delta), released: Math.round(released), st: Math.round(host.scrollTop) })
+        }
+        setFlowPad(host, flowPadOf(host) - released)
+        animatedH = Math.max(0, animatedH - released)
+      }
+      const remainder = need - released
+      let raise = 0
+      if (remainder > 0.5) {
+        const surfaces = shiftSurfacesOf(host)
+        const limit = safeShiftLimit(host, surfaces)
+        const current = currentShiftOf(surfaces.at(-1) ?? host)
+        const target = Math.min(current + remainder, Math.max(0, limit - FOLLOW_PAINT_GUARD_PX))
+        raise = target - current
+        if (raise > 0) {
+          for (const surface of surfaces) setShift(surface, current + raise)
+          followLastShiftPx.set(host, current + raise)
+          animatedH = Math.max(0, animatedH - raise)
+        }
+      }
+      holdGuardAnchor(host, measured, measured.top + released + raise)
+    }
+    /**
+     * THE screen-space anchor hold, shared by every entry point: the
+     * structural-observer path (pre-paint cascade correction), the settle
+     * loop's per-frame poll, and the ACTIVE loop's per-frame poll. The
+     * shift-excluded delta filters the engine's own motion (reveal glide,
+     * wrap lockstep) to ~0, so a live poll may compensate safely — which is
+     * what saves the completion swap: the settled-side arm primes in its
+     * layout effect and steals leadership IN the cascade frame, its own
+     * observers miss the mutations (armed after the fact), and only this
+     * poll sees the jump while it can still be corrected before paint.
+     * Returns the measured delta (null when nothing was comparable).
+     */
+    const enforceReadingAnchor = (host: HTMLElement, trace = false): number | null => {
+      const measured = measureReadingAnchor(host)
+      if (measured === null) return null
+      if (measured.delta > 0.5) {
+        if (trace) {
+          followTrace('anchor-hold', { screenDelta: Math.round(measured.delta), st: Math.round(host.scrollTop) })
+        }
+        if (pruneDeadRunway(host)) reservePx = 0
+        holdGuardAnchor(host, measured, measured.top)
+      } else if (measured.delta < -0.5) {
+        if (pruneDeadRunway(host)) reservePx = 0
+        pullReadingAnchorBack(host, measured, trace)
+      } else {
+        holdGuardAnchor(host, measured, measured.top)
+      }
+      return measured.delta
+    }
+    /** Pre-paint correction (observers, commit subscription). */
     const restoreBeforePaint = (): void => {
-      if (!following || port === null || !isLeader(port)) return
+      if (!following || port === null) return
+      if (hostOwnsScroll || followHostScrollPorts.has(port)) {
+        hostOwnsScroll = true
+        followScrollLedgers.set(port, port.scrollTop)
+        return
+      }
+      if (!activeRef.current) {
+        detectHostScroll(port, Math.max(0, port.scrollHeight - port.clientHeight))
+      }
+      // Yield only to a LIVE owner. Block arms hand off leadership mid-turn
+      // and each handoff kills the previous settle loop; the completion
+      // cascade routinely lands in the leaderless window between that death
+      // and the successor's first frame. Standing down whenever leadership is
+      // merely absent left the cascade's clamp jump uncompensated. While
+      // SOMEONE holds the port, the dead observers must not fight the live
+      // guard; while NOBODY does, a handed-off arm's armed observer is the
+      // only guard left, and the shared followGuardAnchors baseline keeps it
+      // idempotent.
+      const leaderless = !isLeader(port)
+      if (!activeRef.current && followActivePorts.has(port)) return
+      if (leaderless && (followLeaders.has(port) || !handedOff)) return
+      // Leaderless window: this arm's closure state froze when its loop died.
+      // Sync to the shared per-port motion ledger the last live loop wrote,
+      // or the applyVisual below would replay stale extent/reserve into the
+      // runway and pad ledgers while compensating the cascade.
+      if (leaderless) {
+        const sharedMotion = followMotionStates.get(port)
+        if (sharedMotion !== undefined) {
+          animatedH = Math.min(port.scrollHeight, Math.max(0, sharedMotion.extent))
+          reservePx = sharedMotion.reservePx
+          velocityPxPerSec = sharedMotion.velocityPxPerSec
+        }
+      }
+      // A host keyed replacement can disconnect the element carrying our
+      // margin before MutationObserver runs. Drop the stale registry entry;
+      // banking it as pad preserves an extent that immediately becomes the
+      // slow retirement rebound. The same-task ensureRunway / applyVisual path
+      // reopens only the runway that is still needed.
+      pruneDeadRunway(port)
+      // HOST COMPLETION COMMITS under the pin must be corrected in THIS
+      // pre-paint task: the settle loop's rAF guard runs after the host's own
+      // follow effects, so a cascade commit (status swap, tail mount) would
+      // otherwise paint one frame pinned to the sunk floor. The screen-space
+      // anchor hold reads the shared per-port baseline (see
+      // followGuardAnchors); it runs for structural commits only and stands
+      // down while this settle's retirement glide runs (that motion is ours).
+      if (!settleRetiring) {
+        const measured = measureReadingAnchor(port)
+        if (measured !== null && measured.delta > 0.5) {
+          if (pruneDeadRunway(port)) reservePx = 0
+          holdGuardAnchor(port, measured, measured.top)
+        } else if (measured !== null && measured.delta < -0.5) {
+          if (pruneDeadRunway(port)) reservePx = 0
+          if (!activeRef.current) {
+            // Completion window: pad first, then the shift raise absorbs
+            // whatever pad cannot cover (the swap jump rides this path).
+            pullReadingAnchorBack(port, measured)
+          } else {
+            // Live streaming: the original semantics — release only what the
+            // pad holds and leave the remainder to the frame loop's own
+            // lockstep. A shift raise here would cancel the reveal glide.
+            const released = Math.min(flowPadOf(port), -measured.delta)
+            if (released > FOLLOW_SETTLE_EPSILON_PX) {
+              setFlowPad(port, flowPadOf(port) - released)
+              animatedH = Math.max(0, animatedH - released)
+            }
+            holdGuardAnchor(port, measured, measured.top + released)
+          }
+        } else if (measured !== null) {
+          holdGuardAnchor(port, measured, measured.top)
+        }
+      }
       // A reveal commit changes the measured tail, not the fixed chrome. Keep
       // the paint-limit TTL intact here; ResizeObserver and viewport/chrome
       // changes invalidate it when the cached geometry is no longer valid.
@@ -1309,12 +1934,23 @@ export function useConversationFollow(
         reservePx,
         velocityPxPerSec,
         tuning.runwayPx,
-        Number.POSITIVE_INFINITY,
+        // COMPLETION RISE FREEZE: this observer runs in the mutation's
+        // microtask, but the paint lands one vsync later — extent a CSS
+        // transition retracts in between makes any rise funded here
+        // over-cover by exactly that retraction (the drain-onset 回弹).
+        // Freeze rises same-task; the settle's rAF frame re-reads the floor
+        // within its own paint tick and funds the confirmed growth there.
+        activeRef.current
+          ? Number.POSITIVE_INFINITY
+          : (followLastShiftPx.get(port) ?? Number.POSITIVE_INFINITY),
         !predictGrowth,
         trajectoryShift,
+        0,
+        activeRef.current && !hostOwnsScroll,
       )
       if (trajectoryShift !== undefined) {
-        trajectoryPositionPx = floor - currentShiftOf(shiftSurfacesOf(port).at(-1) ?? port)
+        const currentShift = followLastShiftPx.get(port) ?? (floor - (trajectoryPositionPx ?? floor))
+        trajectoryPositionPx = floor - currentShift
       }
       updateRevealScale(port, 0, true)
       reportFollow(port, activeRef.current)
@@ -1333,6 +1969,7 @@ export function useConversationFollow(
       if (port !== null) {
         for (const name of GESTURE_EVENTS) port.removeEventListener(name, markGesture)
         resize?.disconnect()
+        mutations?.disconnect()
       }
       unsubscribeCommit?.()
       port = next
@@ -1342,11 +1979,23 @@ export function useConversationFollow(
         port.addEventListener(name, markGesture, { passive: true })
       }
       if (typeof ResizeObserver !== 'undefined') {
-        resize = new ResizeObserver(restoreBeforePaint)
+        resize = new ResizeObserver(() => restoreBeforePaint())
         resize.observe(port)
         const proxy = resizeProxyOf(port)
         if (proxy !== null) resize.observe(proxy)
       }
+      // Completion is chiefly a child-list transaction (status removal,
+      // live-to-settled replacement, tail insertion). Because following
+      // gives the flow a viewport min-height, those mutations can leave the
+      // flow's border box unchanged and never notify ResizeObserver. Observe
+      // the transaction itself so the anchor hold still runs before paint.
+      if (typeof MutationObserver !== 'undefined') {
+        const flow = flowElementOf(port)
+        if (flow !== null) {
+          mutations = new MutationObserver(() => { restoreBeforePaint() })
+          mutations.observe(flow, { childList: true, subtree: true })
+        }
+      }
     }
 
     /**
@@ -1379,6 +2028,10 @@ export function useConversationFollow(
       if (nextPort === null) return
       bindPort(nextPort)
       observeTailSurface()
+      resetHostScrollOwnershipForNewTurn(nextPort)
+      hostOwnsScroll = followHostScrollPorts.has(nextPort)
+      if (activeRef.current) followActivePorts.add(nextPort)
+      else followActivePorts.delete(nextPort)
       // A hidden/unmeasured port has no meaningful floor yet. Keep this owner
       // unprimed and let the already-scheduled RAF initialize it after layout.
       if (nextPort.clientHeight <= 0) return
@@ -1391,6 +2044,15 @@ export function useConversationFollow(
       )
 
       if (!primed) {
+        // A completion settle owns this port (the swap remounted this arm in
+        // the same frame cluster): stay a passive watcher. Taking over here
+        // would zero the pad mid-retirement and re-inherit it as reserve —
+        // double-counting the extent for one giant jump.
+        if (completionSettleGuardsPort(nextPort)) {
+          primed = true
+          following = false
+          return
+        }
         const inherited = nextPort.hasAttribute(FOLLOW_OWNED_ATTR)
           ? followMotionStates.get(nextPort)
           : undefined
@@ -1418,16 +2080,31 @@ export function useConversationFollow(
           // written in the same commit, so this held-and-canceled space
           // never moves a pixel.
           const hasStatus = turnStatusOf(nextPort) !== null
-          reservePx = predictGrowth && (hasStatus || speedCpsRef.current > FOLLOW_RESERVE_MIN_CPS)
-            ? computeFollowReserve(speedCpsRef.current, tuning.runwayPx)
-            : 0
+          // ZERO-DOWNWARD-REBOUND: the reservation must never land below the
+          // margin this port already owns. base = margin − reservation is the
+          // painted shift; a reservation smaller than the owned margin would
+          // repaint the difference as an instant downward step on this arm's
+          // first frame. The margin stays owned (see the growth-only rule in
+          // the frame loop), so the reservation opens at least to match it.
+          reservePx = Math.max(
+            ownedBottomSpaceOf(nextPort),
+            predictGrowth && (hasStatus || speedCpsRef.current > FOLLOW_RESERVE_MIN_CPS)
+              ? computeFollowReserve(speedCpsRef.current, tuning.runwayPx)
+              : 0,
+          )
+          // Adopt-time reclaim, exactly once and in this same pre-paint task:
+          // the previous completion's pad becomes this stream's reserve gap,
+          // so the extent — and the pinned floor — never steps between turns.
+          // A completion settle still owning the port keeps its ledgers: the
+          // swap's remounted arms must not zero the pad mid-retirement.
+          if (!completionSettleGuardsPort(nextPort)) setFlowPad(nextPort, 0)
           statusWasPresent = hasStatus
           velocityPxPerSec = 0
           // The committed row/growth delta has already moved the new floor.
           // Decide ownership from READER INTENT EVIDENCE, not raw lag: an
           // upward move recorded past our own ledger is a pull-up; anything
           // else (content that mounted while the host had not re-pinned yet,
-          // a post-fold clamp, first-frame geometry) must keep following,
+          // a completion clamp, first-frame geometry) must keep following,
           // otherwise the whole stream falls back to the host's hard snap.
           void reportedLag
           // A prior follower's reader-release record outranks ledger
@@ -1453,6 +2130,9 @@ export function useConversationFollow(
               tuning.runwayPx,
               Number.POSITIVE_INFINITY,
               !(predictiveRef?.current ?? predictive),
+              undefined,
+              0,
+              !hostOwnsScroll,
             )
             if (
               predictive
@@ -1525,12 +2205,17 @@ export function useConversationFollow(
         reportFollow(nextPort, activeRef.current)
         return
       }
+      detectHostScroll(nextPort, floor)
+      if (hostOwnsScroll) {
+        followScrollLedgers.set(nextPort, nextPort.scrollTop)
+        reportFollow(nextPort, false)
+        return
+      }
       hold(nextPort)
       if (!isLeader(nextPort)) {
         finishEntrance()
         return
       }
-
       // Runway and an equal transform cancel visually. It is the zero point,
       // not residual motion: decaying below it would scroll past the final
       // resting position and rebound when runway is removed.
@@ -1542,9 +2227,18 @@ export function useConversationFollow(
       // constant. Growing the reservation without the margin would glide the
       // whole column; growing both together is invisible.
       const predictGrowth = predictiveRef?.current ?? predictive
-      const hasStatus = turnStatusOf(nextPort) !== null
+      const statusElement = turnStatusOf(nextPort)
+      const hasStatus = statusElement !== null
+      if (statusElement !== null) lastStatusHeightPx = statusElement.offsetHeight
       const statusJustRemoved = predictGrowth && statusWasPresent === true && !hasStatus
-      if (statusJustRemoved) reservePx = tuning.runwayPx
+      if (statusJustRemoved) {
+        // The dying status row takes its own layout height AND the margin
+        // riding on it out of the scroll extent in one commit. Re-open the
+        // margin on the next surface in the same frame, sized to cover both,
+        // or the floor sinks by that height and the transcript slides down
+        // under the pin before the replacement margin can land.
+        reservePx = Math.max(reservePx, tuning.runwayPx) + lastStatusHeightPx
+      }
       statusWasPresent = hasStatus
       const reserveEnabled = hasStatus
         || statusJustRemoved
@@ -1553,18 +2247,18 @@ export function useConversationFollow(
       const pressureReserveTarget = predictGrowth && reserveEnabled
         ? computeFollowReserve(speedCpsRef.current, tuning.runwayPx)
         : 0
-      // Reveal pressure may open more runway, but a burst gap must not retire
-      // it mid-stream: shrinking the owned margin moves the real floor and
-      // creates the exact 1px back-and-forth motion this module prevents.
-      // Prediction shutdown and an explicit lower debug cap still retire it.
-      const heldReserveTarget = tuning.runwayPx < reservePx
-        ? tuning.runwayPx
-        : Math.max(reservePx, pressureReserveTarget)
-      const effectiveReserveTarget = !predictGrowth
-        ? 0
-        : statusJustRemoved
-          ? tuning.runwayPx
-          : heldReserveTarget
+      // ZERO-DOWNWARD-REBOUND (root cause): while this follower owns the port
+      // it pins scrollTop to the floor, and the floor rides the owned bottom
+      // margin 1:1. Shrinking that margin under the pin clamps scrollTop
+      // downward and slides the whole transcript down — the one motion this
+      // module must never paint; no shift remains to release it because the
+      // reservation already covers the margin (base = margin − reservation
+      // stays flat). An owned margin therefore only GROWS here: prediction
+      // shutdown and reveal-pressure drops freeze it at its current size, and
+      // retirement is deferred to reader handback (a user-driven scroll) or
+      // the next ownership. Growth stays invisible because the reservation
+      // grows in the same frame and the baseline difference never moves.
+      const effectiveReserveTarget = Math.max(reservePx, pressureReserveTarget)
       const reserveStep = 1 - Math.exp(-elapsedMs / tuning.reserveResponseMs)
       reservePx += (effectiveReserveTarget - reservePx) * reserveStep
       if (predictGrowth || runwayOffsetOf(nextPort) > 0.5) {
@@ -1659,9 +2353,16 @@ export function useConversationFollow(
           animatedH = contentHeight - runwayOffset
           velocityPxPerSec = 0
         } else {
-          const minimumLag = predictGrowth ? 0 : Math.max(0, reservePx)
+          // ZERO-DOWNWARD-REBOUND: the reservation is NOT real lag. With the
+          // steady-state tail pin it already rides as baseline-canceled gap
+          // (shift = margin − reservation + reveal lag), so forcing the spring
+          // to stop `reservePx` short of the natural floor — the pre-tail-pin
+          // "hold the reserve as lag" semantic — would double-count it and
+          // repaint the difference as an instant downward step the moment
+          // prediction shuts off. The spring always drains to the natural
+          // floor; the painted shift decays through the rate-limited release.
           animatedH = Math.min(
-            contentHeight - runwayOffset - minimumLag,
+            contentHeight - runwayOffset,
             animatedH + step.advancePx,
           )
           velocityPxPerSec = step.velocityPxPerSec
@@ -1676,12 +2377,38 @@ export function useConversationFollow(
         Number.POSITIVE_INFINITY,
         !predictGrowth,
         trajectoryShift,
+        elapsedMs,
+        !hostOwnsScroll,
       )
       if (trajectoryActive) {
-        trajectoryPositionPx = floorNow - currentShiftOf(shiftSurfacesOf(nextPort).at(-1) ?? nextPort)
+        const currentShift = followLastShiftPx.get(nextPort) ?? (trajectoryShift ?? 0)
+        trajectoryPositionPx = floorNow - currentShift
       }
       updateRevealScale(nextPort, elapsedMs)
       reportFollow(nextPort, true)
+      // Keep the previous painted tail as the completion handoff baseline.
+      // The active loop is the only place that sees the old surface before a
+      // host live->settled replacement disconnects it.
+      // Per-frame anchor hold — completion window only. During live
+      // streaming the lockstep in this very frame's applyVisual already
+      // cancels wraps; a guard running here fights it (its pad/raise writes
+      // shift the next frame's lag bookkeeping) and visibly degrades the
+      // reveal. The completion cascade is different: the settled-side arm
+      // that primes IN the swap frame has active=false from mount, so ITS
+      // first poll runs before paint and compensates the swap jump that the
+      // older arms' observers were too late (or too unprivileged) to fix.
+      // Track the reading surface's rendered position so the completion
+      // guard inherits the exact last-painted baseline (never a stale or
+      // already-jumped one) when the stream hands off. Compensation is NOT
+      // done from this poll (a guard beside the active loop's own lockstep
+      // fights it and degrades the reveal), and a NON-leader arm must not
+      // even refresh the baseline: its measurement would store the very
+      // jump the owning guard is about to correct and neutralize its next
+      // pass.
+      if (isLeader(nextPort)) {
+        if (!activeRef.current) enforceReadingAnchor(nextPort)
+        else measureReadingAnchor(nextPort)
+      }
       const remainingEntranceLag = Math.max(
         0,
         nextPort.scrollHeight - animatedH - runwayOffsetOf(nextPort),
@@ -1695,10 +2422,31 @@ export function useConversationFollow(
     // the previous owner, leaving a large final append at the old scrollTop.
     frame(performance.now())
     return () => {
+      if (!controlScrollRef.current) {
+        cancelAnimationFrame(rafId)
+        if (port !== null) followActivePorts.delete(port)
+        unsubscribeCommit?.()
+        resize?.disconnect()
+        mutations?.disconnect()
+        if (port !== null) {
+          for (const name of GESTURE_EVENTS) port.removeEventListener(name, markGesture)
+        }
+        if (interactTimer !== null) clearTimeout(interactTimer)
+        const disabledHost = rootRef.current?.closest<HTMLElement>('[data-conversation-scroll]') ?? port
+        if (disabledHost !== null) {
+          clearVisual(disabledHost)
+          followLeaders.delete(disabledHost)
+          debugRuntime.reportFollow(disabledHost, null)
+        }
+        releaseRevealScale()
+        return
+      }
       cancelAnimationFrame(rafId)
+      if (port !== null) followActivePorts.delete(port)
       unsubscribeCommit?.()
       if (interactTimer !== null) clearTimeout(interactTimer)
       resize?.disconnect()
+      mutations?.disconnect()
       if (port !== null) {
         for (const name of GESTURE_EVENTS) port.removeEventListener(name, markGesture)
       }
@@ -1740,11 +2488,27 @@ export function useConversationFollow(
       // so treating it as real lag paints a whole runway-height step at the
       // exact moment leadership hands to the draining arm. The settle loop
       // caps animatedH against the shrinking extent directly.
+      // Settle state (declared before the handoff so the completion paths can
+      // measure the extent against it):
+      let settleQuietMs = 0
+      let settleSig = ''
       const lagBeforeCompletionPaint = Math.max(
         0,
         host.scrollHeight - animatedH - runwayOffsetOf(host),
       )
-      if (!activeRef.current && lagBeforeCompletionPaint <= FOLLOW_SLACK_PX) {
+      const currentRunway = runwayOffsetOf(host)
+      const currentShift = Math.abs(currentShiftOf(shiftSurfacesOf(host).at(-1) ?? host))
+      if (
+        !activeRef.current
+        && lagBeforeCompletionPaint <= FOLLOW_SLACK_PX
+        && currentRunway <= FOLLOW_SETTLE_EPSILON_PX
+        && currentShift <= FOLLOW_SETTLE_EPSILON_PX
+        // A live completion pad must retire through the settle's glide first;
+        // fast-finishing here would freeze it in place as visible bottom gap.
+        && flowPadOf(host) <= FOLLOW_SETTLE_EPSILON_PX
+      ) {
+        followTraceUntilMs = Math.max(followTraceUntilMs, performance.now() + 10000)
+        followTrace('fast-gate', { sh: host.scrollHeight, st: Math.round(host.scrollTop), pad: Math.round(flowPadOf(host)) })
         finishAtNaturalFloor(host, !startedAsEntrance)
         followLeaders.delete(host)
         releaseRevealScale()
@@ -1752,9 +2516,33 @@ export function useConversationFollow(
         return
       }
       const completionShift = currentShiftOf(shiftSurfacesOf(host).at(-1) ?? host)
-      const completionShiftCeiling = completionShift > FOLLOW_SETTLE_EPSILON_PX
-        ? completionShift
-        : Number.POSITIVE_INFINITY
+      // Freeze, never raise, in this same-task paint — same race as the
+      // observer above; the settle's first rAF frame funds the re-open.
+      // Entrance handoffs are mount transients with no collapse in flight:
+      // their first cover must paint immediately (the soften contract).
+      const completionShiftCeiling = startedAsEntrance && completionShift <= FOLLOW_SETTLE_EPSILON_PX
+        ? Number.POSITIVE_INFINITY
+        : completionShift
+      if (hostOwnsScroll) {
+        clearVisual(host)
+        setFollowScrollTop(host, Math.max(0, host.scrollHeight - host.clientHeight))
+        host.removeAttribute(FOLLOW_OWNED_ATTR)
+        followLeaders.delete(host)
+        releaseRevealScale()
+        debugRuntime.reportFollow(host, null)
+        return
+      }
+      // The completion commit often REPLACES the last surface (live→settled
+      // swap re-keys the row), and the owned margin written on the old element
+      // dies with it in the same layout pass. Do NOT bank that loss as a flow
+      // pad: the next ensureRunway opens the completion runway in this same
+      // pre-paint task. Converting the dead margin to pad creates a second
+      // owned extent that must later retire as the visible "slow rebound".
+      followTraceUntilMs = performance.now() + 15000
+      if (pruneDeadRunway(host)) {
+        followTrace('cleanup-dead-margin', { sh: host.scrollHeight, st: Math.round(host.scrollTop), pad: Math.round(flowPadOf(host)) })
+        reservePx = 0
+      }
       // The completion handoff keeps at least one real runway open so the
       // final height has reserved paint room to drain through: with zero
       // margin the whole final height lands as shift in ONE paint (offset
@@ -1762,13 +2550,26 @@ export function useConversationFollow(
       // exists to prevent. The draining arm ramps its reserve from here.
       const completionTuning = debugRuntime.activeTuning()
       const previousCompletionRunway = runwayOffsetOf(host)
-      ensureRunway(host, shiftSurfacesOf(host), Math.max(reservePx, completionTuning.runwayPx))
+      // The completion pad already holds retired extent below the fold; the
+      // handoff only opens the runway room the pad does not cover, or the
+      // same pixels are added twice and the restored floor overshoots.
+      ensureRunway(
+        host,
+        shiftSurfacesOf(host),
+        Math.max(reservePx, Math.max(0, completionTuning.runwayPx - flowPadOf(host))),
+      )
       const completionRunway = runwayOffsetOf(host)
+      // The reading anchor's baseline is already live (the active loop
+      // refreshed it every frame, and the guard observers keep it current);
+      // only seed it here when this port somehow has none, so the first
+      // completion commit has a real screen-space baseline to compare
+      // against instead of silently adopting the jumped position.
+      measureReadingAnchor(host)
       // Rebase the spring extent onto the new offset domain before the paint:
       // adding the margin drops targetHeight by the same amount, so animatedH
       // must drop in lockstep or the margin's px release as an instant shift.
       animatedH = Math.max(0, animatedH - (completionRunway - previousCompletionRunway))
-      settleAtFloor(host)
+      if (!hostOwnsScroll) settleAtFloor(host)
       animatedH = applyVisual(
         host,
         animatedH,
@@ -1776,15 +2577,20 @@ export function useConversationFollow(
         velocityPxPerSec,
         completionRunway,
         completionShiftCeiling,
+        false,
+        undefined,
+        0,
+        !hostOwnsScroll,
       )
       reportFollow(host, false)
       const runwayOffset = runwayOffsetOf(host)
       const remainingLag = Math.max(0, host.scrollHeight - animatedH - runwayOffset)
       if (
         remainingLag <= FOLLOW_SETTLE_EPSILON_PX
-        || (!activeRef.current && remainingLag <= FOLLOW_SLACK_PX)
+        && runwayOffset <= FOLLOW_SETTLE_EPSILON_PX
+        && reservePx <= FOLLOW_SETTLE_EPSILON_PX
       ) {
-        finishAtNaturalFloor(host, !startedAsEntrance)
+        finishAtNaturalFloor(host, !startedAsEntrance, !hostOwnsScroll)
         followLeaders.delete(host)
         releaseRevealScale()
         debugRuntime.reportFollow(host, null)
@@ -1796,14 +2602,42 @@ export function useConversationFollow(
       }
       const stopSettleListeners = (): void => {
         for (const name of GESTURE_EVENTS) host.removeEventListener(name, markGesture)
+        resize?.disconnect()
+        mutations?.disconnect()
         if (interactTimer !== null) {
           clearTimeout(interactTimer)
           interactTimer = null
         }
       }
+      // Re-arm pre-paint observation for the whole completion cascade. The
+      // active effect's observers were disconnected above, but status/tail
+      // commits continue while the detached settle loop owns the port.
+      if (typeof ResizeObserver !== 'undefined') {
+        resize = new ResizeObserver(() => restoreBeforePaint())
+        resize.observe(host)
+        const proxy = resizeProxyOf(host)
+        if (proxy !== null) resize.observe(proxy)
+      }
+      if (typeof MutationObserver !== 'undefined') {
+        const flow = flowElementOf(host)
+        if (flow !== null) {
+          mutations = new MutationObserver(() => { restoreBeforePaint() })
+          mutations.observe(flow, { childList: true, subtree: true })
+        }
+      }
+      // From here this closure's observers are the completion guard of last
+      // resort (see `handedOff` above), and this settle OWNS the port until
+      // it finishes.
+      followCompletionSettle.add(host)
+      followCompletionSettleRows.set(host, countUserRows(host))
+      handedOff = true
       let settleLast = performance.now()
-      let settleMarginPx = Math.max(runwayOffsetOf(host), reservePx)
-      let settleMarginRate = settleMarginPx / FOLLOW_RUNWAY_RETIRE_MS
+      // Settle-pad transfer state lives above the completion handoff; the
+      // loop below only drives it frame by frame. `settleRetiring` marks the
+      // final glide: the cascade has quieted, so the pad that kept every host
+      // commit pixel-stable is handed back to the layout at the bounded
+      // settle rate and the pinned viewport glides down to the natural
+      // resting position against the composer.
       const settleFrame = (now: number): void => {
         if (!isLeader(host)) {
           stopSettleListeners()
@@ -1813,6 +2647,7 @@ export function useConversationFollow(
           readerGestureIntent = false
           handBackVisual(host)
           clearVisual(host)
+          followCompletionSettle.delete(host)
           followLeaders.delete(host)
           releaseRevealScale()
           debugRuntime.reportFollow(host, null)
@@ -1822,24 +2657,111 @@ export function useConversationFollow(
         const dt = Math.min(FOLLOW_MAX_FRAME_MS, Math.max(0, now - settleLast))
         const tuning = debugRuntime.activeTuning()
         settleLast = now
-        // Retire the runway in LOCKSTEP with its canceling reserve: the
-        // margin shrinks by exactly the amount the reservation shrinks, so
-        // their baseline difference — and therefore every painted pixel —
-        // stays put while the reserved space closes. Decaying only the
-        // reservation would slide the whole column by the runway height.
-        if (settleMarginPx > 0 && settleMarginRate > 0) {
-          settleMarginPx = Math.max(0, settleMarginPx - settleMarginRate * dt)
-          ensureRunway(host, shiftSurfacesOf(host), settleMarginPx)
-          reservePx = Math.min(reservePx, settleMarginPx)
+        detectHostScroll(host, Math.max(0, host.scrollHeight - host.clientHeight))
+        if (hostOwnsScroll) {
+          clearVisual(host)
+          setFollowScrollTop(host, Math.max(0, host.scrollHeight - host.clientHeight))
+          host.removeAttribute(FOLLOW_OWNED_ATTR)
+          followCompletionSettle.delete(host)
+          followLeaders.delete(host)
+          releaseRevealScale()
+          debugRuntime.reportFollow(host, null)
+          stopSettleListeners()
+          return
+        }
+        // HOST COMPLETION CASCADE: around completion the host swaps the status
+        // row for its process/tail rows, auto-collapses the think disclosure
+        // and mounts the metrics tail — each a same-frame layout shrink under
+        // the pinned floor. Re-open every lost pixel below the last surface
+        // (out of sight; extent, floor and pinned scrollTop restored) and hold
+        // ownership until the cascade has been quiet for
+        // FOLLOW_SETTLE_QUIET_MS, so the host's own floor-snap never paints a
+        // host action as a single-frame slam of the whole transcript.
+        // ANCHOR SCREEN HOLD: the completion cascade moves the reading
+        // anchor's viewport position (status swap, live→settled replacement,
+        // clamp jumps). The reading-surface baseline lives in the shared
+        // followGuardAnchors ledger; the shift-excluded delta filters the
+        // engine's own glide, so the per-frame poll only answers real host
+        // motion. While the pad retires, extent motion is OUR OWN glide —
+        // the hold stands down.
+        const guardDelta = !settleRetiring && !followActivePorts.has(host)
+          ? enforceReadingAnchor(host, true)
+          : null
+        settleQuietMs = !settleRetiring && (guardDelta === null || Math.abs(guardDelta) <= 0.5) ? settleQuietMs + dt : 0
+        // ZERO-DOWNWARD-REBOUND (root cause): scrollTop is pinned to the floor
+        // and the floor rides the owned margin 1:1, so the settle must NOT
+        // shrink the margin — that clamps scrollTop downward with no shift
+        // left to release (the reservation covers the margin, so base = margin
+        // − reservation never moves). Instead the margin MOVES below the
+        // status row: marginTop −δ and marginBottom +δ in the same layout
+        // pass keep the scroll extent constant, so the floor, the pinned
+        // scrollTop and every content pixel stay put while the status glides
+        // up to close the reserve gap — the completion 归位, with zero
+        // downward motion.
+        const settleStatus = turnStatusOf(host)
+        const ownedRunwayPx = runwayOffsetOf(host)
+        if (ownedRunwayPx > FOLLOW_SETTLE_EPSILON_PX) {
+          const requestedTransferPx = settleStatus === null
+            ? ownedRunwayPx
+            : Math.min(
+                reservePx,
+                ((tuning.runwayPx || FOLLOW_STATUS_RUNWAY_PX) / FOLLOW_RUNWAY_RETIRE_MS) * dt,
+              )
+          const transferredPx = transferRunwayToFlowPad(host, requestedTransferPx)
+          // Do not bank a completion pad. The margin release and pad removal
+          // happen in one layout pass, so there is no extra extent to retire
+          // later and no second slow rebound after the cascade quiets.
+          if (transferredPx > 0) setFlowPad(host, Math.max(0, flowPadOf(host) - transferredPx))
+          reservePx = Math.max(0, reservePx - transferredPx)
+          // targetHeight = scrollHeight - runway. The equal margin-to-pad
+          // transfer keeps scrollHeight fixed and lowers runway by δ, so the
+          // logical extent rises by exactly δ (not 2δ). Both this rebase and
+          // applyVisual's offset-history rebase are required: dropping either
+          // one stalls the spring or leaks residual motion into the quiet
+          // window (audit burst-gap/ramp quiescence-move).
+          animatedH += transferredPx
         }
         const runwayOffset = runwayOffsetOf(host)
         const lag = Math.max(0, host.scrollHeight - animatedH - runwayOffset)
-        if (lag <= FOLLOW_SETTLE_EPSILON_PX && settleMarginPx <= FOLLOW_SETTLE_EPSILON_PX) {
+        // PAD RETIREMENT (the final glide of 收尾归位): cascade quiet, drain
+        // closed — the pad that kept every host commit pixel-stable is handed
+        // back to the layout at the bounded settle rate. The floor sinks with
+        // it and the pinned viewport glides down to the natural resting
+        // position against the composer; smooth and rate-limited, never the
+        // single-frame slam the raw host snap paints.
+        if (
+          !settleRetiring
+          && lag <= FOLLOW_SETTLE_EPSILON_PX
+          && reservePx <= FOLLOW_SETTLE_EPSILON_PX
+          && settleQuietMs >= FOLLOW_SETTLE_QUIET_MS
+          && flowPadOf(host) > FOLLOW_SETTLE_EPSILON_PX
+        ) {
+          followTrace('retire-start', { pad: Math.round(flowPadOf(host)), sh: host.scrollHeight, st: Math.round(host.scrollTop) })
+          settleRetiring = true
+        }
+        if (settleRetiring) {
+          const padPx = flowPadOf(host)
+          const retirePx = Math.min(
+            padPx,
+            ((tuning.runwayPx || FOLLOW_STATUS_RUNWAY_PX) / FOLLOW_RUNWAY_RETIRE_MS) * dt,
+          )
+          if (padPx - retirePx <= FOLLOW_SETTLE_EPSILON_PX) {
+            setFlowPad(host, 0)
+            settleRetiring = false
+          } else {
+            setFlowPad(host, padPx - retirePx)
+          }
+        }
+        if (
+          lag <= FOLLOW_SETTLE_EPSILON_PX
+          && (reservePx <= FOLLOW_SETTLE_EPSILON_PX || settleStatus === null)
+          && flowPadOf(host) <= FOLLOW_SETTLE_EPSILON_PX
+          && settleQuietMs >= FOLLOW_SETTLE_QUIET_MS
+        ) {
+          followTrace('finish', { st: Math.round(host.scrollTop), sh: host.scrollHeight, pad: Math.round(flowPadOf(host)) })
           animatedH = host.scrollHeight
-          reservePx = 0
           velocityPxPerSec = 0
-          followRunways.delete(host)
-          finishAtNaturalFloor(host, !startedAsEntrance)
+          finishAtNaturalFloor(host, !startedAsEntrance, !hostOwnsScroll)
           followLeaders.delete(host)
           releaseRevealScale()
           debugRuntime.reportFollow(host, null)
@@ -1856,14 +2778,38 @@ export function useConversationFollow(
           animatedH + step.advancePx,
         )
         velocityPxPerSec = step.velocityPxPerSec
-        settleAtFloor(host)
-        animatedH = applyVisual(host, animatedH, reservePx, velocityPxPerSec, Math.max(settleMarginPx, runwayOffset))
+        if (!hostOwnsScroll) settleAtFloor(host)
+        // Once the host has written, never write scrollTop again. The settle
+        // still computes compositor shifts and rebases the spring; the host
+        // owns the scrollport. A completion commit that GROWS the extent
+        // changes the host floor; the host snaps while applyVisual answers
+        // with the matching shift raise — the same lockstep the active loop
+        // paints for a wrap.
+        animatedH = applyVisual(
+          host,
+          animatedH,
+          reservePx,
+          velocityPxPerSec,
+          runwayOffset,
+          Number.POSITIVE_INFINITY,
+          false,
+          undefined,
+          0,
+          !hostOwnsScroll,
+        )
+        if (traceActive()) {
+          const sig = `${Math.round(host.scrollTop)}|${host.scrollHeight}|${Math.round(flowPadOf(host))}|${Math.round(reservePx)}|${settleRetiring}`
+          if (sig !== settleSig) {
+            followTrace('settle', { st: Math.round(host.scrollTop), sh: host.scrollHeight, pad: Math.round(flowPadOf(host)), reserve: Math.round(reservePx), lag: Math.round(lag * 10) / 10, retiring: settleRetiring })
+            settleSig = sig
+          }
+        }
         reportFollow(host, false)
         requestAnimationFrame(settleFrame)
       }
       requestAnimationFrame(settleFrame)
     }
-  }, [active, rootRef, speedCpsRef, revealScaleRef, predictive, predictiveRef])
+  }, [active, rootRef, speedCpsRef, revealScaleRef, predictive, predictiveRef, controlScroll])
 
   useLayoutEffect(() => {
     const host = rootRef.current?.closest<HTMLElement>('[data-conversation-scroll]') ?? null