@oar-sh/oar 0.9.10 → 0.9.12

package/server/public/app/transcript-jump-bottom-view.mjs

@@ -3,15 +3,24 @@
 // Decisions live in transcript-jump-bottom.mjs; this module reads the
 // scroller and the rows and applies them.
 //
+// The transcript moves by itself in two cases only: the reader is at the
+// end, or the reader has just sent something. Both are asked here, before
+// the row is put on the page: followsTranscriptEnd() by every live update,
+// ownSendFollows() by the reader's own sends. "At the end" is one margin
+// everywhere (resolveNearBottomThresholdPx). An update that is not followed
+// leaves the transcript where it is; what it added marks the button.
+//
 // Following the end has no state of its own: every live update asks
-// isMessagesAtBottom() before it appends and scrolls. When the composer grows
+// followsTranscriptEnd() before it appends and scrolls. When the composer grows
 // (the background-task panel appears or opens, a banner, a taller draft) the
 // transcript shrinks from below, scrollTop stays and no scroll event fires,
 // so the reader is left that many pixels above the end and the next update
-// stops following. The ResizeObserver here puts them back before paint.
+// stops following. The ResizeObserver here puts them back before paint, and
+// an update that lands before its round still follows (a reply streaming in
+// right after the panel grew).
 
 import { currentConvId, isMessagesNearBottom, scrollBottom } from './store.js';
-import { isConversationWindowAtTail } from './conversation-view.js';
+import { getHeldBackLiveRowCount, isConversationWindowAtTail, releaseReadingAnchorHold } from './conversation-view.js';
 import { disarmThinkingFollow, getThinkingFollowMode, syncThinkingFollowButtons } from './thinking-follow.js';
 import { resolveNearBottomThresholdPx } from './transcript-viewport-anchor.mjs';
 import {
@@ -20,8 +29,10 @@ import {
   shouldHoldFocusOnJump,
 } from './composer-keyboard.mjs';
 import {
+  isScrollOnSendEnabled,
+  followsEndThroughResize,
   isNearBottom,
-  jumpBadgeText,
+  jumpButtonPresentation,
   jumpScrollBehavior,
   nextJumpButtonState,
   shouldRepinOnResize,
@@ -30,7 +41,10 @@ import {
 
 // The final snap of a smooth jump where the browser has no scrollend event.
 const SMOOTH_JUMP_FALLBACK_MS = 900;
-const BUTTON_LABEL = 'Jump to the latest message';
+// A card that waits for the reader: a question or an approval, or a board
+// whose actions are still open.
+const WAITING_CARD_SELECTOR = '.relay-question-container, .relay-board-inline .relay-board-actions';
+const STATUS_ID = 'jump-to-bottom-status';
 
 let initialized = false;
 let state = null;
@@ -43,6 +57,15 @@ let observedClientHeight = null;
 let jump = null;
 let updateScheduled = false;
 let loadConversationEnd = null;
+// Counts the times the reader left the end: a scroll that took the position
+// up and away from it, whatever caused it (a wheel, a drag, a key with the
+// focus anywhere, the scrollbar). An input that moves nothing is none: a
+// wheel notch at the end, a key typed into a card. What scrolls to the end on
+// the reader's behalf after their own send checks that this has not happened
+// since.
+let readerMoveEpoch = 0;
+let lastScrollTop = 0;
+const endLeftListeners = new Set();
 
 function scroller() {
   return document.getElementById('messages');
@@ -58,7 +81,6 @@ function rowKeys(el) {
     if (!node.classList?.contains('msg')) continue;
     const key = transcriptRowKey({
       messageId: node.dataset.messageId,
-      exchangePromptId: node.dataset.agentExchangePromptId,
       live: node.id === 'thinking-indicator',
     });
     if (key) keys.push(key);
@@ -66,42 +88,81 @@ function rowKeys(el) {
   return keys;
 }
 
-function render(visible, count) {
+// Whether a waiting card lies wholly below what the reader sees.
+function questionWaitingBelow(el) {
+  const bottom = el.getBoundingClientRect().bottom;
+  for (const card of el.querySelectorAll(WAITING_CARD_SELECTOR)) {
+    if (card.getBoundingClientRect().top >= bottom) return true;
+  }
+  return false;
+}
+
+// What a screen reader hears when the button changes its state: the button's
+// own label is only read once it has the focus.
+function statusRegion(button) {
+  let region = document.getElementById(STATUS_ID);
+  if (region || !button?.parentNode) return region;
+  region = document.createElement('div');
+  region.id = STATUS_ID;
+  region.setAttribute('role', 'status');
+  region.setAttribute('aria-live', 'polite');
+  region.style.cssText = 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip-path:inset(50%);white-space:nowrap;border:0;';
+  button.parentNode.insertBefore(region, button.nextSibling);
+  return region;
+}
+
+function render(next) {
   const button = document.getElementById('jump-to-bottom-btn');
   if (!button) return;
-  button.classList.toggle('visible', visible);
+  const shown = jumpButtonPresentation(next || {});
+  button.classList.toggle('visible', next?.visible === true);
+  if (button.dataset.state !== shown.state) button.dataset.state = shown.state;
   const badge = button.querySelector('.jump-to-bottom-badge');
-  const text = visible ? jumpBadgeText(count) : '';
   if (badge) {
-    badge.textContent = text;
-    badge.hidden = !text;
+    if (badge.textContent !== shown.badge) badge.textContent = shown.badge;
+    badge.classList.toggle('jump-to-bottom-badge-dot', shown.dot);
+    badge.hidden = !shown.badge && !shown.dot;
+  }
+  if (button.getAttribute('aria-label') !== shown.label) {
+    button.setAttribute('aria-label', shown.label);
+    button.title = shown.label;
   }
-  const label = text ? `${BUTTON_LABEL} (${count} new)` : BUTTON_LABEL;
-  if (button.getAttribute('aria-label') !== label) button.setAttribute('aria-label', label);
+  const region = statusRegion(button);
+  if (region && region.textContent !== shown.announcement) region.textContent = shown.announcement;
 }
 
-function update() {
-  updateScheduled = false;
-  const el = scroller();
-  if (!el) return;
+function syncStateConversation() {
   const conversationId = String(currentConvId || '').trim();
   if (conversationId !== stateConversationId) {
     state = null;
     stateConversationId = conversationId;
   }
+  return conversationId;
+}
+
+function update() {
+  updateScheduled = false;
+  const el = scroller();
+  if (!el) return;
+  const conversationId = syncStateConversation();
   if (!conversationId || jump) {
-    render(false, 0);
+    render(null);
     return;
   }
+  notePositionAfterContentChange(el);
   const distance = distanceFromBottom(el);
   const nearBottomPx = resolveNearBottomThresholdPx(el.clientHeight);
+  const away = !isNearBottom(distance, nearBottomPx);
   state = nextJumpButtonState(state, {
     distance,
     clientHeight: el.clientHeight,
     nearBottomPx,
-    rowKeys: isNearBottom(distance, nearBottomPx) ? [] : rowKeys(el),
+    rowKeys: away ? rowKeys(el) : [],
+    question: away && questionWaitingBelow(el),
+    windowAtTail: isConversationWindowAtTail(),
+    waiting: getHeldBackLiveRowCount(),
   });
-  render(state.visible, state.count);
+  render(state);
 }
 
 function scheduleUpdate() {
@@ -110,6 +171,120 @@ function scheduleUpdate() {
   requestAnimationFrame(update);
 }
 
+/** A card or a board was put on the page, or taken off it. */
+export function refreshJumpButton() {
+  scheduleUpdate();
+}
+
+/**
+ * `listener` runs when a reader who followed the end is found away from it
+ * without having scrolled: content landed that was not followed. Whoever
+ * keeps "at the end" from the last scroll event lets go of it then.
+ */
+export function onTranscriptEndLeft(listener) {
+  if (typeof listener === 'function') endLeftListeners.add(listener);
+}
+
+/**
+ * Asked by every live update before it changes the transcript: true when
+ * the reader is at the end and the update scrolls with it. Otherwise the
+ * transcript stays where it is. Only a question: what was really added says
+ * so itself (a row is counted, anything else calls noteTranscriptNews()).
+ */
+export function followsTranscriptEnd() {
+  // The bottom of a window that ends above the conversation's end is not the
+  // end: nothing live is drawn there, and nothing scrolls to it.
+  if (!isConversationWindowAtTail()) return false;
+  const el = scroller();
+  const height = jump ? null : observedClientHeight;
+  return followsEndThroughResize({
+    nearBottomNow: isMessagesNearBottom(),
+    clientHeight: el?.clientHeight,
+    observedClientHeight: height,
+    distanceAtObservedHeight: el && height !== null ? Math.max(0, el.scrollHeight - height - el.scrollTop) : null,
+    nearBottomPxAtObservedHeight: height !== null ? resolveNearBottomThresholdPx(height) : 0,
+  });
+}
+
+/**
+ * Something landed below a reader who is not at the end and added no row to
+ * count (a reply growing in its bubble, a thought, a tool line): the button
+ * says that there is news until the reader is at the end again.
+ */
+export function noteTranscriptNews() {
+  const el = scroller();
+  if (!el || !syncStateConversation()) return;
+  state = {
+    visible: state?.visible === true,
+    baseline: Array.isArray(state?.baseline) ? state.baseline : rowKeys(el),
+    count: state?.count || 0,
+    unseen: true,
+    question: state?.question === true,
+  };
+  scheduleUpdate();
+}
+
+/**
+ * The reader sends something themselves (the composer, a steer, Resend, an
+ * answer on a card, a board's action): taken at that moment, before anything
+ * is awaited. Nothing a relay or an agent puts into the conversation comes
+ * here.
+ */
+export function beginOwnSend() {
+  return { conversationId: String(currentConvId || '').trim(), epoch: readerMoveEpoch, follows: false };
+}
+
+/**
+ * A send from the new-chat screen has no conversation; the relay's answer
+ * creates it. Named here once it is on screen, so the send goes on in it and
+ * in no other.
+ */
+export function nameOwnSendConversation(send, conversationId) {
+  if (send && !send.conversationId) send.conversationId = String(conversationId || '').trim();
+}
+
+// The send is still the last thing the reader did to this conversation's
+// position: it is on screen, and they have not scrolled away since.
+function ownSendHolds(send) {
+  return !!send
+    && send.conversationId === String(currentConvId || '').trim()
+    && send.epoch === readerMoveEpoch;
+}
+
+/**
+ * Whether what the send puts on the page is followed to the end; asked
+ * before each row and each step. A reader who is at the end is followed like
+ * with anything else, whatever became of the send. The send adds one right
+ * to that: while it holds, it takes the reader to the end from wherever they
+ * are (unless that is switched off in the settings) and keeps them there
+ * through the layout that follows it. Once the reader has scrolled away, or
+ * another conversation is on screen, that right is gone.
+ */
+export function ownSendFollows(send) {
+  const atEnd = isMessagesNearBottom();
+  if (!ownSendHolds(send)) return atEnd;
+  send.follows = send.follows || atEnd || isScrollOnSendEnabled();
+  return send.follows;
+}
+
+/**
+ * To the end after the reader's own send, and again through the layout that
+ * follows it (the bubble's separator, a picture that loads, the composer
+ * shrinking back): each step asks again.
+ */
+export function scrollAfterOwnSend(send) {
+  const step = () => {
+    if (!ownSendFollows(send)) return;
+    // A place held while images load would take this scroll for the reader's
+    // and let go only then; the send moves the reader, so it lets go first.
+    releaseReadingAnchorHold();
+    scrollBottom();
+  };
+  step();
+  requestAnimationFrame(step);
+  setTimeout(step, 120);
+}
+
 // A scroll event is dispatched a frame after the scroll, before that frame's
 // ResizeObserver round: when the composer grew in between, the transcript
 // has already shrunk, and the reader would read as having left the end. So
@@ -122,6 +297,18 @@ function notePosition(el) {
   pinnedScrollTop = el.scrollTop;
 }
 
+// The content changed without a scroll event. A reader who followed the end
+// and is away from it now was not followed (rows landed while they held a
+// selection, a card grew): a later resize must not take them to the end.
+function notePositionAfterContentChange(el) {
+  const followed = pinned;
+  notePosition(el);
+  if (!followed || pinned) return;
+  for (const listener of endLeftListeners) {
+    try { listener(); } catch {}
+  }
+}
+
 function endJump() {
   if (!jump) return;
   jump.cleanup();
@@ -166,26 +353,33 @@ function prefersReducedMotion() {
   try { return window.matchMedia('(prefers-reduced-motion: reduce)').matches; } catch { return false; }
 }
 
+/**
+ * Takes the reader to the end. From a window that ends above the
+ * conversation's end, the end is loaded first: the promise settles once it
+ * is on the page (or the load failed), which an own send from such a window
+ * waits for.
+ */
 export function jumpTranscriptToBottom() {
   const el = scroller();
-  if (!el) return;
-  // The end wins over a followed section of the live bubble.
+  if (!el) return Promise.resolve();
+  // The end wins over a place held while images load, as over a followed
+  // section of the live bubble.
+  releaseReadingAnchorHold();
   if (getThinkingFollowMode()) {
     disarmThinkingFollow();
     syncThinkingFollowButtons(document, null);
   }
   state = null;
-  render(false, 0);
+  render(null);
   // A window in the middle of the history (a search result, a pin) ends
   // above the conversation's end: the end is loaded instead.
   if (loadConversationEnd && !isConversationWindowAtTail()) {
     endJump();
     jump = { cleanup() {} };
-    void Promise.resolve()
+    return Promise.resolve()
       .then(() => loadConversationEnd())
       .catch(() => {})
       .finally(finishJump);
-    return;
   }
   const behavior = jumpScrollBehavior({
     distance: distanceFromBottom(el),
@@ -194,16 +388,22 @@ export function jumpTranscriptToBottom() {
   });
   if (behavior === 'smooth') startSmoothJump(el);
   else finishJump();
+  return Promise.resolve();
 }
 
 function handleScroll() {
   const el = scroller();
   if (!el) return;
+  const movedUp = el.scrollTop < lastScrollTop - 1;
+  lastScrollTop = el.scrollTop;
   if (jump) {
     if (distanceFromBottom(el) <= 1) finishJump();
     return;
   }
   notePosition(el);
+  // `pinned` is "at the end" as of this scroll. A clamp (the page got
+  // shorter) also takes scrollTop down, and ends at the end.
+  if (movedUp && !pinned) readerMoveEpoch += 1;
   scheduleUpdate();
 }
 
@@ -267,6 +467,7 @@ export function initTranscriptJumpToBottom({ loadEnd } = {}) {
   const button = document.getElementById('jump-to-bottom-btn');
   if (!el || !button) return;
   initialized = true;
+  lastScrollTop = el.scrollTop;
   pinnedScrollTop = el.scrollTop;
   observedClientHeight = el.clientHeight;
   button.addEventListener('click', (event) => {
@@ -280,8 +481,11 @@ export function initTranscriptJumpToBottom({ loadEnd } = {}) {
   window.visualViewport?.addEventListener?.('resize', noteViewport, { passive: true });
   window.addEventListener('resize', noteViewport, { passive: true });
   el.addEventListener('scroll', handleScroll, { passive: true });
+  // The whole subtree: the button shows at any distance once something new
+  // is below, so it also has to go when the end comes back to the reader
+  // without a scroll (the live bubble folding its thoughts, a row shrinking).
   if (typeof MutationObserver === 'function') {
-    new MutationObserver(scheduleUpdate).observe(el, { childList: true });
+    new MutationObserver(scheduleUpdate).observe(el, { childList: true, subtree: true, characterData: true });
   }
   if (typeof ResizeObserver === 'function') {
     new ResizeObserver(handleResize).observe(el);

package/server/public/app/transcript-jump-bottom.mjs

@@ -1,11 +1,16 @@
 // The transcript's jump-to-bottom button, without the DOM: when it shows,
-// what its badge counts, how far a click scrolls smoothly, and whether a
-// resize of the transcript re-pins a reader who was following the end.
+// which of its three states it is in (plain, something new below, a question
+// waits below), what its badge counts, how far a click scrolls smoothly, and
+// whether a resize of the transcript re-pins a reader who was following the
+// end.
 // transcript-jump-bottom-view.mjs reads the scroller and the rows and applies
 // what this module decides.
 //
 // "At the bottom" is the composer's near-bottom rule (isMessagesNearBottom,
 // resolveNearBottomThresholdPx); the caller passes its threshold in.
+//
+// Also here: the setting that decides whether the reader's own send jumps to
+// the end.
 
 /** The button fades in once the reader is this many screens above the end. */
 export const JUMP_BUTTON_SHOW_SCREENS = 1;
@@ -14,15 +19,11 @@ export const JUMP_SMOOTH_MAX_SCREENS = 3;
 export const JUMP_BADGE_MAX = 99;
 
 /**
- * One key per row the reader sees. Every row of a folded agent exchange
- * (its prompt, its replies, its live bubble) carries the prompt's id, so the
- * fold counts once however many of its rows are on the page. The live
- * bubble of a turn outside a fold has the prompt's id as its message id, so
- * it gets a key of its own.
+ * One key per row the reader sees. The live bubble of a turn has the
+ * prompt's id as its message id, so it gets a key of its own. A folded agent
+ * prompt is a row like any other: its reply shows below it and counts too.
  */
-export function transcriptRowKey({ messageId = '', exchangePromptId = '', live = false } = {}) {
-  const fold = String(exchangePromptId || '').trim();
-  if (fold) return `fold:${fold}`;
+export function transcriptRowKey({ messageId = '', live = false } = {}) {
   const id = String(messageId || '').trim();
   if (!id) return '';
   return live ? `live:${id}` : `msg:${id}`;
@@ -57,20 +58,105 @@ export function isNearBottom(distance, nearBottomPx) {
 /**
  * The button's next state from the scroller's geometry. At the bottom it
  * hides and forgets the baseline. Away from it, the rows on the page when the
- * reader left are the baseline the badge counts from; the button shows from
- * one screen above the end and, once shown, stays until the bottom.
+ * reader left are the baseline the badge counts from; the plain button shows
+ * from one screen above the end and, once shown, stays until the bottom.
+ *
+ * The transcript does not move under a reader who is away from the end, so
+ * the button is how they learn of what landed there, at any distance:
+ * `unseen` is a live update that was not followed (it holds until the
+ * bottom: a reply growing in its bubble adds no row to count), `question` a
+ * card waiting for an answer below the viewport (as it is now: answered
+ * elsewhere, it is gone).
  */
-export function nextJumpButtonState(previous, { distance, clientHeight, nearBottomPx, rowKeys = [] } = {}) {
-  if (isNearBottom(distance, nearBottomPx)) return { visible: false, baseline: null, count: 0 };
-  const baseline = Array.isArray(previous?.baseline) ? previous.baseline : rowKeys.slice();
+export function nextJumpButtonState(previous, {
+  distance,
+  clientHeight,
+  nearBottomPx,
+  rowKeys = [],
+  unseen = false,
+  question = false,
+  windowAtTail = true,
+  waiting = 0,
+} = {}) {
+  // Live rows held back for a window that ends above the conversation's end
+  // (transcript-island.mjs): the bottom of the page is not the end, so the
+  // button stays while they wait.
+  const waitingNow = windowAtTail ? 0 : Math.max(0, Math.trunc(Number(waiting) || 0));
+  if (isNearBottom(distance, nearBottomPx) && !waitingNow) {
+    return { visible: false, baseline: null, count: 0, unseen: false, question: false, waiting: 0 };
+  }
+  // Below such a window the rows put on the page are the newer pages, older
+  // than anything live: they are not counted, and the baseline is taken once
+  // the window meets the end.
+  const baseline = !windowAtTail ? null : (Array.isArray(previous?.baseline) ? previous.baseline : rowKeys.slice());
   const screens = Number(clientHeight) > 0 ? Number(distance) / Number(clientHeight) : 0;
+  const count = windowAtTail ? countNewRows(baseline, rowKeys) : 0;
+  const unseenNow = previous?.unseen === true || unseen === true;
+  const questionNow = question === true;
   return {
-    visible: previous?.visible === true || screens >= JUMP_BUTTON_SHOW_SCREENS,
+    visible: previous?.visible === true || screens >= JUMP_BUTTON_SHOW_SCREENS || count > 0 || waitingNow > 0 || unseenNow || questionNow,
     baseline,
-    count: countNewRows(baseline, rowKeys),
+    count,
+    unseen: unseenNow,
+    question: questionNow,
+    waiting: waitingNow,
   };
 }
 
+export const JUMP_BUTTON_LABEL = 'Jump to the latest message';
+export const JUMP_BUTTON_QUESTION_LABEL = 'A question is waiting for your answer. Jump to it';
+export const JUMP_QUESTION_BADGE = '?';
+
+/**
+ * How the rows held back for a window above the end show on the badge:
+ * 'count' adds them to the count, 'dot' draws the dot of news without a row.
+ */
+export const HELD_BACK_ROWS_BADGE = 'count';
+
+/**
+ * How a state looks and reads. `state` is 'plain', 'new' or 'question'; a
+ * waiting question wins over news. `badge` is the count, '?' for a question,
+ * or empty: with `dot`, an empty badge is drawn as a dot (news without a row
+ * to count). `waiting` rows are held back below the page
+ * (HELD_BACK_ROWS_BADGE). `announcement` is what a screen reader is told
+ * when the state is entered; the label alone is only read when the button is
+ * focused.
+ */
+export function jumpButtonPresentation({ visible = false, count = 0, unseen = false, question = false, waiting = 0 } = {}, { heldBackRowsBadge = HELD_BACK_ROWS_BADGE } = {}) {
+  if (!visible) return { state: 'plain', label: JUMP_BUTTON_LABEL, badge: '', dot: false, announcement: '' };
+  if (question) {
+    return {
+      state: 'question',
+      label: JUMP_BUTTON_QUESTION_LABEL,
+      badge: JUMP_QUESTION_BADGE,
+      dot: false,
+      announcement: 'A question is waiting for your answer below.',
+    };
+  }
+  const held = Math.max(0, Math.trunc(Number(waiting) || 0));
+  const counted = Math.max(0, Math.trunc(Number(count) || 0)) + (heldBackRowsBadge === 'count' ? held : 0);
+  const badge = jumpBadgeText(counted);
+  if (badge) {
+    return {
+      state: 'new',
+      label: `${JUMP_BUTTON_LABEL} (${counted} new)`,
+      badge,
+      dot: false,
+      announcement: 'New messages below.',
+    };
+  }
+  if (unseen || held > 0) {
+    return {
+      state: 'new',
+      label: `${JUMP_BUTTON_LABEL} (new below)`,
+      badge: '',
+      dot: true,
+      announcement: 'New messages below.',
+    };
+  }
+  return { state: 'plain', label: JUMP_BUTTON_LABEL, badge: '', dot: false, announcement: '' };
+}
+
 /** 'smooth' up to JUMP_SMOOTH_MAX_SCREENS above the end, else 'instant'. */
 export function jumpScrollBehavior({ distance, clientHeight, reducedMotion = false } = {}) {
   if (reducedMotion) return 'instant';
@@ -88,12 +174,74 @@ export function jumpBadgeText(count) {
 /**
  * Whether a resize of the transcript (the composer or the background-task
  * panel growing under it) re-pins it to the end. The scroller shrinking from
- * below keeps scrollTop and fires no scroll event, so a reader who was
- * following is still described by the last scroll: `pinned` and the
- * scrollTop it was taken at. Once scrollTop has moved since (a restore, a
- * clamp, the browser's anchoring), the geometry as it is now decides.
+ * below keeps scrollTop and fires no scroll event, so the reader is still
+ * described by the last note of their position: `pinned` (they followed the
+ * end, by a scroll event or when the content last changed) and the scrollTop
+ * it was taken at. While scrollTop is that one, the note alone decides: a
+ * reader who was not at the end is never taken there by a resize. Once
+ * scrollTop has moved since (a restore, a clamp, the browser's anchoring),
+ * the note is stale and the geometry as it is now decides.
  */
 export function shouldRepinOnResize({ pinned, pinnedScrollTop, scrollTop, nearBottomNow }) {
-  if (pinned && Number(scrollTop) === Number(pinnedScrollTop)) return true;
+  if (Number(scrollTop) === Number(pinnedScrollTop)) return pinned === true;
   return nearBottomNow === true;
 }
+
+/**
+ * Whether a live update follows the end. A reader at the end now is
+ * followed. So is one the re-pin above is on its way to: the transcript
+ * shrank from below (`clientHeight` under the height the last
+ * ResizeObserver round saw) and at that height the reader is at the end.
+ * An update that lands between the shrink and that round would otherwise
+ * find them the panel's height above the end, stay put, and leave them
+ * there. The geometry decides, not the last note of the position: a scroll
+ * to the end (the update before) is noted only by its scroll event a frame
+ * later, and the shrink and this update can both land before it.
+ */
+export function followsEndThroughResize({ nearBottomNow, clientHeight, observedClientHeight, distanceAtObservedHeight, nearBottomPxAtObservedHeight }) {
+  if (nearBottomNow === true) return true;
+  if (!(Number(clientHeight) < Number(observedClientHeight))) return false;
+  return isNearBottom(distanceAtObservedHeight, nearBottomPxAtObservedHeight);
+}
+
+// "Jump to the end when I send a message" (Settings › General). A setting of
+// this browser, kept in localStorage like the theme. On unless switched off:
+// with it off, the reader's own send follows the same rule as everything
+// else and only scrolls a transcript that is at its end already. The
+// document and the storage are passed in by the tests.
+
+export const SCROLL_ON_SEND_STORAGE_KEY = 'copilot_scroll_on_send';
+export const SCROLL_ON_SEND_TOGGLE_ID = 'scroll-on-send-toggle';
+
+/** Anything but an explicit off is on: a missing or damaged value included. */
+export function parseScrollOnSendSetting(stored) {
+  const value = String(stored ?? '').trim().toLowerCase();
+  if (!value) return true;
+  return value !== '0' && value !== 'false';
+}
+
+export function serializeScrollOnSendSetting(enabled) {
+  return enabled ? '1' : '0';
+}
+
+function storage() {
+  try { return globalThis.localStorage || null; } catch { return null; }
+}
+
+export function isScrollOnSendEnabled(store = storage()) {
+  try {
+    return parseScrollOnSendSetting(store?.getItem(SCROLL_ON_SEND_STORAGE_KEY));
+  } catch {
+    return true;
+  }
+}
+
+export function syncScrollOnSendToggle(doc = globalThis.document, store = storage()) {
+  const checkbox = doc?.getElementById?.(SCROLL_ON_SEND_TOGGLE_ID);
+  if (checkbox) checkbox.checked = isScrollOnSendEnabled(store);
+}
+
+export function updateScrollOnSendSetting(enabled, { doc = globalThis.document, store = storage() } = {}) {
+  try { store?.setItem(SCROLL_ON_SEND_STORAGE_KEY, serializeScrollOnSendSetting(!!enabled)); } catch {}
+  syncScrollOnSendToggle(doc, store);
+}