@adecore/agents-react 0.21.1 → 0.21.2

package/src/chat/ui/Composer.tsx

@@ -98,8 +98,7 @@ const PROMPT_HISTORY = 50;
 // Commands the composer handles itself; the CLI's own ones are sent through as text.
 const LOCAL_COMMANDS = ['model', 'compact', 'clear'];
 
-/* Files and paths dropped on the card become attachments and chips there. CodeMirror would paste a
-   file's text, or the drag's own text, at the drop point on top of that. */
+/* The card turns dropped files and paths into attachments and chips; CodeMirror would also paste their text at the drop point. */
 const LEAVE_DROPS_TO_THE_CARD = EditorView.domEventHandlers({
     drop: (event) => event.dataTransfer !== null && (event.dataTransfer.types.includes('Files') || carriesMentions(event.dataTransfer.types))
 });
@@ -158,6 +157,20 @@ function hintedPlaceholder(lead: string, joiner: string, hints: ReadonlyArray<{
     return root;
 }
 
+function sendLabelKey(busy: boolean, canSteer: boolean, delivery: 'queue' | 'steer'): string {
+    if (!busy) {
+        return 'composer.send';
+    }
+    if (!canSteer) {
+        return 'composer.queueButton';
+    }
+    return delivery === 'steer' ? 'composer.steerButton' : 'composer.queueWithSteerButton';
+}
+
+function sameQuery(left: MentionQuery | null, right: MentionQuery | null): boolean {
+    return left?.start === right?.start && left?.query === right?.query;
+}
+
 function splitPath(path: string): { name: string; dir: string } {
     const slash = path.lastIndexOf('/');
     return slash < 0 ? { name: path, dir: '' } : { name: path.slice(slash + 1), dir: path.slice(0, slash) };
@@ -196,7 +209,6 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
     const providers = useProviders((s) => s.providers);
     const { approvals, questions } = usePendingRequests(chatId);
     const order = useChatRow(chatId, (row) => row?.order);
-    // The structure, which a delta leaves alone. The prompts and the requests are items of their own.
     const items = useChatRow(chatId, (row) => row?.structure);
     const chats = chatHost().useReferableChats();
     const placeholderLead = chatHost().useComposerPlaceholder(scope.id, chatId);
@@ -208,7 +220,7 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
     const capabilities = provider?.capabilities;
     const compaction = capabilities?.compaction;
     const dismissedTurnId = useResumeCompactionDismissal(chatId);
-    /* The cheap half of the offer, so a chat that can never make one keeps no timer. */
+    // The cheap half of the offer, so a chat that can never make one keeps no timer.
     const couldOfferCompaction = compaction !== undefined && compaction !== 'none' && info.usage.contextTokens >= RESUME_COMPACTION_TOKENS;
     const now = useNow(60_000, couldOfferCompaction);
     const compactionOffer = !couldOfferCompaction
@@ -228,13 +240,9 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
     const quote = draft.quote;
     // The CLI announces its session on the first message, so anything before that is still a blank chat.
     const started = info.agentSessionId !== null || info.usage.turns > 0;
-    /*
-     * A chat that has started keeps its provider (the CLI holds the thread), and one opened for a
-     * named CLI was never going to change it. Either way the models stay switchable. The CLI takes
-     * the new one on the restart the next send does anyway. With one provider in the list the
-     * picker drops its group headers on its own, so it reads as that CLI's own catalog.
-     */
     const accountChoice = useAccountChoice(info.provider, info.account);
+    // A chat that has started keeps its provider (the CLI holds the thread), and so does one opened for a
+    // named CLI; its models stay switchable, since the CLI takes a new one on the restart the next send does.
     const pickable =
         started || providerFixed
             ? providers.filter((entry) => entry.kind === info.provider)
@@ -284,11 +292,11 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
         }
         let stale = false;
         const search = (): void => {
-            const search = chatHost().searchFiles;
-            if (search === null) {
+            const searchFiles = chatHost().searchFiles;
+            if (searchFiles === null) {
                 return;
             }
-            search(scope.id, info.cwd, mention.query, MENTION_RESULTS)
+            searchFiles(scope.id, info.cwd, mention.query, MENTION_RESULTS)
                 .then((files) => {
                     if (!stale) {
                         setSearched({ query: mention.query, files });
@@ -394,15 +402,28 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
         inputRef.current?.focus();
     };
 
-    const configure = (patch: { selection?: ModelSelection; runtimeMode?: RuntimeMode; account?: string }): void => {
+    const showError = (error: unknown): void => {
+        setNotice(error instanceof Error ? error.message : String(error));
+    };
+
+    /* One configuration at a time; a second pick while one is on its way is dropped. */
+    const runConfiguration = (work: () => Promise<void>): void => {
         if (configuring.current) {
             return;
         }
         configuring.current = true;
         setConfigurationPending(true);
-        void actions
-            .configure(chatId, patch)
-            .then(() => {
+        void work()
+            .catch(showError)
+            .finally(() => {
+                configuring.current = false;
+                setConfigurationPending(false);
+            });
+    };
+
+    const configure = (patch: { selection?: ModelSelection; runtimeMode?: RuntimeMode; account?: string }): void => {
+        runConfiguration(() =>
+            actions.configure(chatId, patch).then(() => {
                 if (patch.selection) {
                     rememberChatSelection(info.provider, patch.selection);
                 }
@@ -413,11 +434,7 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
                     rememberChatAccount(scope.id, info.provider, patch.account);
                 }
             })
-            .catch((error: unknown) => setNotice(error instanceof Error ? error.message : String(error)))
-            .finally(() => {
-                configuring.current = false;
-                setConfigurationPending(false);
-            });
+        );
     };
 
     const chooseAccount = (account: string): void => configure({ account });
@@ -426,18 +443,7 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
     const chooseModel = (provider: AgentKind, slug: string): void => {
         const selection: ModelSelection = { model: slug, options: {} };
         if (provider !== info.provider) {
-            if (configuring.current) {
-                return;
-            }
-            configuring.current = true;
-            setConfigurationPending(true);
-            void onRetarget(provider, selection)
-                .then(() => rememberChatSelection(provider, selection))
-                .catch((error: unknown) => setNotice(error instanceof Error ? error.message : String(error)))
-                .finally(() => {
-                    configuring.current = false;
-                    setConfigurationPending(false);
-                });
+            runConfiguration(() => onRetarget(provider, selection).then(() => rememberChatSelection(provider, selection)));
             return;
         }
         configure({ selection });
@@ -445,14 +451,10 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
 
     const stop = (shiftKey: boolean): void => {
         if (composerStopOf(shiftKey) === 'turn') {
-            void actions.stopTurn(chatId, false).catch((error: unknown) => setNotice(error instanceof Error ? error.message : String(error)));
+            void actions.stopTurn(chatId, false).catch(showError);
             return;
         }
-        chatHost().confirm.stopSubagents(
-            scope.id,
-            chatId,
-            () => void actions.stopTurn(chatId, true).catch((error: unknown) => setNotice(error instanceof Error ? error.message : String(error)))
-        );
+        chatHost().confirm.stopSubagents(scope.id, chatId, () => void actions.stopTurn(chatId, true).catch(showError));
     };
 
     /* The host decides whether a turn is in the way; only its refusal asks the person first. */
@@ -493,18 +495,16 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
         }
     };
 
-    const same = (a: MentionQuery | null, b: MentionQuery | null): boolean => a?.start === b?.start && a?.query === b?.query;
-
     /* Which picker the caret opens: `@` for a file, `$` for a skill, or neither. In code a sigil is just text. */
     const trackTriggers = (value: string, selection: TextRange, state: EditorState): void => {
         const empty = selection.from === selection.to;
         const tree = empty ? (ensureSyntaxTree(state, selection.from, 50) ?? syntaxTree(state)) : null;
         const caret = tree !== null && !inCode(tree, value, selection.from) ? selection.from : null;
         const skill = caret === null ? null : findSkillQuery(value, caret);
-        setSkillQuery((current) => (same(current, skill) ? current : skill));
+        setSkillQuery((current) => (sameQuery(current, skill) ? current : skill));
         // A CLI that does not expand `@path` gets the text as it is, so the picker stays out of the way.
         const next = caret === null || capabilities?.mentions === false ? null : findMentionQuery(value, caret);
-        setMention((current) => (same(current, next) ? current : next));
+        setMention((current) => (sameQuery(current, next) ? current : next));
     };
 
     // The inserted text reaches the editor with the render it causes, so the caret waits a frame for it.
@@ -558,8 +558,7 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
         moveCaret(result.caret);
     };
 
-    /* Paths dragged in from a list of files. There is no mention query to insert into, so they land
-       at the end of the prompt and join the draft's mentions, which is what `chat.send` carries. */
+    /* Paths dragged in from a list of files. With no mention query to insert into, they land at the end of the prompt. */
     const addMentions = (paths: string[]): void => {
         const fresh = paths.filter((path) => path !== '');
         if (fresh.length === 0 || capabilities?.mentions === false) {
@@ -752,6 +751,19 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
         return true;
     };
 
+    /* The arrows walk an open picker round; true when the key was one of them. */
+    const moveInMenu = (key: string, count: number): boolean => {
+        if (key === 'ArrowDown') {
+            setMenuIndex((i) => (i + 1) % count);
+            return true;
+        }
+        if (key === 'ArrowUp') {
+            setMenuIndex((i) => (i - 1 + count) % count);
+            return true;
+        }
+        return false;
+    };
+
     /* Runs before the editor's own keymap; true means the key is handled and its default prevented. */
     const onKeyDown = (e: KeyboardEvent, view: EditorView): boolean => {
         // Shift with the paste shortcut pastes a large text inline after all; any other key forgets it.
@@ -766,8 +778,7 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
             setText('', [], []);
             return true;
         }
-        // The composer keeps the keyboard while you type, but the shortcuts that move between views,
-        // panels and the palette stay the app's, untouched: Mod+Shift+Enter would otherwise send as well.
+        // The app's own shortcuts stay the app's while you type: Mod+Shift+Enter would otherwise send as well.
         if (chatHost().isAppShortcut(e)) {
             return false;
         }
@@ -785,12 +796,7 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
             return true;
         }
         if (commandMenuOpen) {
-            if (e.key === 'ArrowDown') {
-                setMenuIndex((i) => (i + 1) % commands.length);
-                return true;
-            }
-            if (e.key === 'ArrowUp') {
-                setMenuIndex((i) => (i - 1 + commands.length) % commands.length);
+            if (moveInMenu(e.key, commands.length)) {
                 return true;
             }
             if (e.key === 'Tab') {
@@ -804,12 +810,7 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
             }
         }
         if (skillMenuOpen) {
-            if (e.key === 'ArrowDown') {
-                setMenuIndex((i) => (i + 1) % skillMatches.length);
-                return true;
-            }
-            if (e.key === 'ArrowUp') {
-                setMenuIndex((i) => (i - 1 + skillMatches.length) % skillMatches.length);
+            if (moveInMenu(e.key, skillMatches.length)) {
                 return true;
             }
             if (e.key === 'Tab' || e.key === 'Enter') {
@@ -818,12 +819,7 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
             }
         }
         if (mentionMenuOpen && mentionCount > 0) {
-            if (e.key === 'ArrowDown') {
-                setMenuIndex((i) => (i + 1) % mentionCount);
-                return true;
-            }
-            if (e.key === 'ArrowUp') {
-                setMenuIndex((i) => (i - 1 + mentionCount) % mentionCount);
+            if (moveInMenu(e.key, mentionCount)) {
                 return true;
             }
             if (e.key === 'Tab' || e.key === 'Enter') {
@@ -946,9 +942,8 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
 
     return (
         <div className="chat-composer-content pointer-events-none relative z-10 w-full">
-            {/* Only while there is something below the fold. It sits over the composer rather than
-                in the thread, because the composer is the one thing whose height it always clears. */}
-            {/* A read-only composer sits under something that stands in the thread's place, whose end is not this one. */}
+            {/* Over the composer rather than in the thread, since the composer's height is the one it always clears.
+                A read-only composer sits under something that stands in the thread's place, whose end is not this one. */}
             {!atEnd && !readOnly && (
                 <div className="absolute inset-x-0 bottom-full mb-2 flex justify-center">
                     <Tooltip label={t('composer.jumpToEnd')} name>
@@ -969,8 +964,7 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
                         ? 'border-accent bg-[color-mix(in_srgb,var(--accent-soft)_60%,var(--surface-raised))]'
                         : 'border-border bg-[color-mix(in_srgb,var(--surface-raised)_92%,transparent)]'
                 )}
-                /* The whole card takes a dropped file as a mention, so a layout around it that takes drops
-                   of its own leaves it alone. */
+                /* The whole card takes a dropped file, so a layout around it that takes drops of its own leaves it alone. */
                 data-takes-drop="all"
                 onDragOver={(e) => {
                     if (writable && (e.dataTransfer.types.includes('Files') || carriesMentions(e.dataTransfer.types))) {
@@ -1300,21 +1294,7 @@ export function Composer({ chatId, info, focused, answerPromptsElsewhere, disabl
                                 </Tooltip>
                             )}
                             {(!busy || !isEmptyDraft(draft)) && (
-                                <Tooltip
-                                    label={
-                                        busy
-                                            ? t(
-                                                  canSteer
-                                                      ? sendDelivery === 'steer'
-                                                          ? 'composer.steerButton'
-                                                          : 'composer.queueWithSteerButton'
-                                                      : 'composer.queueButton'
-                                              )
-                                            : t('composer.send')
-                                    }
-                                    kbd={KEY_SHORTCUTS.modEnter}
-                                    name
-                                >
+                                <Tooltip label={t(sendLabelKey(busy, canSteer, sendDelivery))} kbd={KEY_SHORTCUTS.modEnter} name>
                                     <button
                                         className="flex h-9 w-9 shrink-0 items-center justify-center rounded-full bg-accent text-accent-text hover:brightness-90 disabled:opacity-50 disabled:hover:brightness-100"
                                         disabled={isEmptyDraft(draft) || !writable || guard.tooLong}

package/src/chat/ui/Markdown.tsx

@@ -67,17 +67,14 @@ function languageOf(className: string | undefined): string {
 const INLINE_CODE = 'rounded-sm bg-surface-sunken px-1 py-px font-mono text-code';
 
 /*
- * A path an agent wrote down, opened in the preview panel. It keeps the shape of the code chip it
- * would otherwise be, so a sentence full of them does not start dancing; only the color says it can
- * be clicked. `data-file-path` is what the thread's own right-click menu reads, so a link answers to
- * both ways of opening it.
+ * A path an agent wrote down. It keeps the shape of the code chip it would otherwise be, so a sentence
+ * full of them does not shift; `data-file-path` is what the thread's right-click menu reads.
  */
 function FileLink({ target, className, children }: { target: FileRef; className?: string; children: ReactNode }) {
     const cwd = useFileLinkCwd();
     const scopeId = useFileLinkScopeId();
     return (
-        // `select-text` because a thread is copied as often as it is clicked, and a button is not
-        // selectable on its own.
+        // A button is not selectable on its own, and a thread is copied as often as it is clicked.
         <button
             type="button"
             className={clsx('cursor-pointer select-text', className)}
@@ -108,8 +105,10 @@ function InlineCode({ text }: { text: string }) {
     );
 }
 
-/* The path a link target spells, with the one scheme that still means a file on the host's machine
-   taken off. A href nobody encoded is left as it is, since decoding throws on a stray percent. */
+/*
+ * The path a link target spells, without the one scheme that still means a file on the host's machine.
+ * A href nobody encoded is left as it is, since decoding throws on a stray percent.
+ */
 function hrefPath(href: string): string {
     const bare = href.replace(/^file:\/\//, '');
     try {
@@ -129,6 +128,10 @@ function MarkdownLink({ href, children }: { href?: string; children?: ReactNode
             </FileLink>
         );
     }
+    return <ExternalLink href={href}>{children}</ExternalLink>;
+}
+
+function ExternalLink({ href, children }: { href?: string; children?: ReactNode }) {
     return (
         <a href={href} target="_blank" rel="noreferrer">
             {children}
@@ -173,13 +176,7 @@ const plainComponents = {
             </MarkdownCode>
         );
     },
-    a({ href, children }: { href?: string; children?: ReactNode }) {
-        return (
-            <a href={href} target="_blank" rel="noreferrer">
-                {children}
-            </a>
-        );
-    }
+    a: ExternalLink
 };
 
 // A reply sits under the heading of its message, an `h3`, so its own headings start one level below
@@ -271,8 +268,7 @@ const MESSAGE_PLUGINS = [remarkGfm, remarkHtmlAsText, remarkBreaks];
 const FADE_PLUGINS = [rehypeFadeWords];
 const NO_PLUGINS: typeof FADE_PLUGINS = [];
 
-/* One block of a reply. It renders no element of its own, so prose still sees the paragraphs as
-   direct children and keeps its first and last margins. */
+/* One block of a reply. It renders no element of its own, so prose keeps its first and last margins. */
 const ReplyBlock = memo(function ReplyBlock({ text, fade, open, reply }: { text: string; fade: boolean; open: boolean; reply?: ShellCodeBlockReply }) {
     return (
         // A context rather than a second set of components. A component that changed would mount the

package/src/chat/ui/Pickers.tsx

@@ -43,11 +43,9 @@ interface ModelPickerProps {
 }
 
 /*
- * Which model answers: the provider's mark plus the model's short name
- * as the trigger, a search field over the popup, one group per provider and the legacy models
- * behind an expander. Before the first message the list carries every installed CLI, so picking
- * another provider's model is also how a chat picks its provider. A chat bound to one CLI passes
- * only that CLI, which drops the group headers and leaves its own catalog to choose from.
+ * Which model answers: a search field over one group per provider, with the legacy models behind an
+ * expander. Before the first message the list carries every installed CLI, so picking another
+ * provider's model is also how a chat picks its provider; with one CLI the group headers drop.
  */
 export function ModelPicker({
     providers,
@@ -224,10 +222,8 @@ export function ModelPicker({
 }
 
 /*
- * Prompts put aside with Cmd+S. The shelf is the whole app's, not this chat's. On a canvas a
- * stashed prompt usually moves to another node, which is the reason to put it away in the first
- * place. Restoring drops the text, the mentions and the skills into this composer; the files a
- * draft held are named on the row but not kept, because their bytes never go to storage.
+ * Prompts put aside with Cmd+S, on a shelf the whole app shares, since a stashed prompt usually moves
+ * to another chat. A draft's files are named on the row but not kept: their bytes never go to storage.
  */
 export function StashPicker({ onRestore }: { onRestore(prompt: StashedPrompt): void }) {
     const { t } = useTranslation('agent-chat');

package/src/chat/ui/QuoteButton.tsx

@@ -21,9 +21,8 @@ function lastLineOf(range: Range): DOMRect | null {
 }
 
 /*
- * A button under a selection in an answer that hands it to the composer. Quoting on the selection
- * alone grew the composer while the person was still selecting, which moved the thread under the
- * pointer. It only shows once the pointer is up, so a drag never has it jump along.
+ * A button under a selection in an answer that hands it to the composer. It shows once the pointer is
+ * up: quoting on the selection alone grew the composer mid-drag and moved the thread under the pointer.
  */
 export function QuoteButton({
     thread,

package/src/chat/ui/RunSettings.tsx

@@ -103,6 +103,13 @@ function modelValue(provider: AgentKind, slug: string): string {
     return `${provider}/${slug}`;
 }
 
+/* Each provider's current or legacy models; a provider with none of them is left out. */
+function modelGroupsOf(providers: ProviderInfo[], legacy: boolean): Array<{ entry: ProviderInfo; models: ModelInfo[] }> {
+    return providers
+        .map((entry) => ({ entry, models: entry.models.filter((row) => (row.legacy === true) === legacy) }))
+        .filter((group) => group.models.length > 0);
+}
+
 /*
  * Everything that decides how the next turn runs, behind one pill: the model, its own knobs and the
  * permission mode. Model and effective permissions stay visible as the composer narrows.
@@ -142,8 +149,8 @@ export function RunSettings({
         summary.push({ id: CONTEXT_OPTION, label: formatTokens(usage.contextWindow ?? 0), ring: true });
     }
     const grouped = providers.length > 1;
-    const live = providers.map((entry) => ({ entry, models: entry.models.filter((row) => !row.legacy) })).filter((group) => group.models.length > 0);
-    const legacy = providers.map((entry) => ({ entry, models: entry.models.filter((row) => row.legacy) })).filter((group) => group.models.length > 0);
+    const live = modelGroupsOf(providers, false);
+    const legacy = modelGroupsOf(providers, true);
     const chosenLegacy = owner?.models.find((row) => row.legacy && row.slug === selection.model);
     const chosenModel = modelValue(provider, selection.model);
     const shownMode = effectiveRuntimeMode ?? runtimeMode;

package/src/chat/ui/Scrubber.tsx

@@ -70,9 +70,8 @@ const NOTHING_FOUND: readonly boolean[] = [];
 
 /*
  * The strip at the left edge of a chat view: a tick per message of the person, per wake by tasks and
- * per other message with a bookmark, the ones on screen bright and the rest dimmed, a bookmark in the accent, growing only under the pointer. A single hover card follows the pointer along the strip, anchored at the tick
- * it points at, so a thousand ticks are a thousand spans and not a thousand popups. While a find is
- * open, a short mark at the strip's right edge stands beside every tick with a hit under it.
+ * per other bookmarked message, the ones on screen bright. One hover card follows the pointer, so a
+ * thousand ticks are a thousand spans and not a thousand popups. An open find marks every tick it hits.
  */
 export const Scrubber = memo(function Scrubber({
     ticks,

package/src/chat/ui/SubagentControls.tsx

@@ -8,9 +8,7 @@ import { Icon, IconButton } from '@adecore/ui';
 
 const CRUMB_LINK = 'truncate text-text-muted hover:text-text';
 
-/*
- * The chat's own title where the bar draws it. While a sub-agent stands in the chat's place it is the first crumb of the way down, so pressing it goes back to the main agent.
- */
+/* The chat's own title in the bar; while a sub-agent stands in the chat's place, pressing it goes back to the main agent. */
 export function SubagentTitleCrumb({ chatId, className, children }: { chatId: string; className?: string; children: ReactNode }) {
     const { trail, show } = useSubagentTrail(chatId);
     if (trail.length === 0) {

package/src/chat/ui/SubagentTimeline.tsx

@@ -136,8 +136,7 @@ export function SubagentTimeline({ chatId, toolUseId }: { chatId: string; toolUs
                                 loadEarlier();
                             }}
                         >
-                            {/* The same menu the chat's own thread has; this transcript is read-only, so the chat
-                    it belongs to is not passed on and the fork item stays out. */}
+                            {/* The chat's own menu; this transcript is read-only, so no chat is passed and the fork item stays out. */}
                             <ContextMenu.Root>
                                 <ContextMenu.Trigger
                                     ref={threadRef}

package/src/chat/ui/Timeline.tsx

@@ -1,6 +1,6 @@
-import { type CSSProperties, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { type CSSProperties, type RefObject, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { useTranslation } from 'react-i18next';
-import { useVirtualizer } from '@tanstack/react-virtual';
+import { useVirtualizer, type Virtualizer } from '@tanstack/react-virtual';
 import clsx from 'clsx';
 import { LoaderCircle } from 'lucide-react';
 import type { ChatBookmark } from '@adecore/agent-contracts';
@@ -67,6 +67,12 @@ import { ContextMenu, EmptyState, ErrorBoundary, Icon, SectionLabel } from '@ade
 
 const ESTIMATED_ROW_PX = 56;
 
+/* A jump puts its row at the top and stops following the end, so the reader stays where they landed. */
+function showRowAtTop(virtualizer: Virtualizer<HTMLDivElement, Element>, followRef: RefObject<boolean>, index: number): void {
+    followRef.current = false;
+    virtualizer.scrollToIndex(index, { align: 'start' });
+}
+
 /*
  * A thread before its first message: which model answers, what the lines into this node let it read,
  * and the folder it works in, so a first question can lean on all three.
@@ -288,7 +294,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
         [chatId]
     );
 
-    // The client does not run the React Compiler, so its memoization rule has nothing to break here.
+    // Nothing here builds with the React Compiler, so its memoization rule has nothing to break.
     // oxlint-disable-next-line react/incompatible-library
     const virtualizer = useVirtualizer({
         count: rows.length,
@@ -307,11 +313,9 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
     });
     const tail = lastReplyLength ?? rows.length;
     /*
-     * The rows are measured as they render, so the end of the list moves while it is drawn: a diff
-     * that highlights, an image that loads, a tool row that grows a line of output. `scrollToIndex`
-     * aims at where the row was when it was asked, which is what left the thread short of the end.
-     * The scroller's own bottom is a fact rather than an estimate, and the total size changing is
-     * what says a row was measured again, so this runs for every one of those.
+     * Rows are measured as they render, so the end moves while it is drawn (a diff that highlights, an
+     * image that loads). `scrollToIndex` aims at where a row was when asked and fell short; the
+     * scroller's own bottom is a fact, and a new total size says a row was measured again.
      */
     const totalSize = virtualizer.getTotalSize();
     useLayoutEffect(() => {
@@ -361,8 +365,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
 
     /*
      * Where each message starts, from the virtualizer's measurements (an estimate for a row it never
-     * drew), so reading the scroll position costs no layout. The virtualizer renders this component on
-     * every scroll already.
+     * drew), so reading the scroll position costs no layout.
      */
     const measurements = virtualizer.measurementsCache;
     const starts = ticks.map((tick) => measurements[tick.rowIndex]?.start ?? tick.rowIndex * ESTIMATED_ROW_PX);
@@ -418,8 +421,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
             setSeeking({ itemId: tick.bookmark.itemId, key: keyOf(chatId) });
             return;
         }
-        followRef.current = false;
-        virtualizer.scrollToIndex(tick.rowIndex, { align: 'start' });
+        showRowAtTop(virtualizer, followRef, tick.rowIndex);
     };
 
     useLayoutEffect(() => {
@@ -439,8 +441,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
             } else {
                 setSeeking(null);
                 if (jump.kind === 'row') {
-                    followRef.current = false;
-                    virtualizer.scrollToIndex(jump.index, { align: 'start' });
+                    showRowAtTop(virtualizer, followRef, jump.index);
                     setLanding({ target: seeking.block, key: seeking.key });
                 }
             }
@@ -449,8 +450,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
         const index = rows.findIndex((row) => row.id === seeking.itemId);
         if (index !== -1) {
             setSeeking(null);
-            followRef.current = false;
-            virtualizer.scrollToIndex(index, { align: 'start' });
+            showRowAtTop(virtualizer, followRef, index);
             return;
         }
         const item = items?.[seeking.itemId];
@@ -505,8 +505,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
         const found = changes !== -1 ? changes : rows.findIndex((row) => row.id === opening?.id || row.id === `start-${turnId}` || row.id === `fold-${turnId}`);
         if (found !== -1) {
             setRevealing(null);
-            followRef.current = false;
-            virtualizer.scrollToIndex(found, { align: 'start' });
+            showRowAtTop(virtualizer, followRef, found);
             useTimelineFlash.getState().flash(keyOf(chatId), rows[found]!.id, changes !== -1);
             return;
         }
@@ -564,8 +563,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
             return;
         }
         subagents.add(found.branch.id);
-        followRef.current = false;
-        virtualizer.scrollToIndex(found.index, { align: 'start' });
+        showRowAtTop(virtualizer, followRef, found.index);
     };
 
     return (

package/src/chat/ui/TimelineMenu.tsx

@@ -11,11 +11,7 @@ import { useChatRow } from '../../state/chats';
 import { openFileLink, useFileLinkCwd, useFileLinkScopeId } from './file-links';
 import { ContextMenu, copyText, DisabledReason, EDIT_SHORTCUTS, Icon, Kbd, selectAllWithin } from '@adecore/ui';
 
-/*
- * The menu behind a right-click in a thread. Copy is the reason it exists. Everything in a thread
- * is text a person may want out of it, and a whole message, a code block or the markdown an answer
- * was written in are each a different amount of that.
- */
+/* The menu behind a right-click in a thread, mostly for copying: a whole message, a code block or an answer's markdown. */
 export function TimelineMenuPopup({
     target,
     thread,
@@ -88,10 +84,8 @@ export function TimelineMenuPopup({
 }
 
 /*
- * Place a bookmark on a message, or rename and remove the one it has: the same rows from the thread
- * and from the strip beside it. `onName` runs when a row opens the name field, which sits on the
- * bookmark's line over the message and so has to be on screen; the strip scrolls there, the thread
- * was clicked on it.
+ * Place a bookmark on a message, or rename and remove the one it has, from the thread and from the strip.
+ * `onName` runs when a row opens the name field, which sits over the message and so has to be on screen.
  */
 export function BookmarkMenuItems({ chatId, itemId, onName }: { chatId: string; itemId: string; onName?: () => void }) {
     const { t } = useTranslation('agent-chat');

package/src/chat/ui/UnifiedDiff.tsx

@@ -7,9 +7,8 @@ import { useDiffTheme } from './diff-theme';
 import { fullFileDiff, type DiffContents } from './full-diff';
 
 /*
- * A patch the CLI reported itself (Codex writes unified diffs). The renderer needs a file header
- * to know what it is looking at, and a CLI that only sends hunks gets one from the path we know.
- * A diff without hunks at all is shown as its own lines, so nothing is ever swallowed.
+ * A patch the CLI reported itself. The renderer needs a file header, which a CLI that only sends hunks
+ * gets from the path we know; a diff without hunks is shown as its own lines, so nothing is swallowed.
  */
 function asPatch(change: ChatFileChange): string | null {
     if (!/^@@/m.test(change.diff)) {
@@ -23,8 +22,7 @@ function asPatch(change: ChatFileChange): string | null {
     return `--- ${from}\n+++ ${to}\n${change.diff}`;
 }
 
-/* Lets a diff with a view of its own run to the bottom of it, so the scrollbar of a short one sits
-   there instead of under its last line; the lines themselves keep their height. */
+/* Lets a diff with a view of its own run to its bottom, so a short one's scrollbar sits there and not under its last line. */
 const FILL_CSS = `
 :host { display: flex; flex-direction: column; flex-grow: 1; }
 pre { flex-grow: 1; align-content: start; }