refactor(ui): make the transcript the only writer of its scroll position

apps/desktop/e2e/prompt-rail.spec.ts

@@ -252,8 +252,9 @@ test('the first click of a session lands on its prompt and holds', async ({
   expect((await landing())?.offset).toBeLessThan(24);
   expect((await landing())?.tickIsCurrent).toBe(true);
 
-  // And stays: the fill runs on idle callbacks after the jump, so a jump that
-  // only wins the first frame reads as landing and then sliding away.
+  // And stays: turns keep resolving their content and remeasuring after the
+  // jump, so a jump that only wins the first frame reads as landing and then
+  // sliding away.
   await page.waitForTimeout(1_200);
   const settled = await landing();
   expect(settled?.offset).toBeGreaterThan(-24);
@@ -265,7 +266,7 @@ test('long transcripts keep a bounded mounted turn window', async ({
   promptRailWindow: page,
 }) => {
   const count = async () => page.locator('[data-virtual-turn-id]').count();
-  await page.locator('[data-chat-scroll-container="true"][data-turn-window="ready"]').waitFor();
+  await page.locator('[data-virtual-turn-id]').first().waitFor();
   await loadPromptRailBeyondVirtualWindow(page);
   expect(await page.evaluate(() => {
     const transcript = document.querySelector<HTMLElement>('.maka-chat-message-list');
@@ -288,8 +289,8 @@ test('long transcripts keep a bounded mounted turn window', async ({
 test('evicting a turn-owned sibling interaction hands focus back to the transcript', async ({
   promptRailWindow: page,
 }) => {
-  const scroller = page.locator('[data-chat-scroll-container="true"][data-turn-window="ready"]');
-  await scroller.waitFor();
+  const scroller = page.locator('[data-chat-scroll-container="true"]');
+  await page.locator('[data-virtual-turn-id]').first().waitFor();
   await loadPromptRailBeyondVirtualWindow(page);
   await scrollTranscriptTo(page, 'bottom');
   await expect(page.locator('[data-virtual-turn-id="turn-prompt-rail-120"]')).toHaveCount(1);

apps/desktop/src/renderer/app-shell.tsx

@@ -426,6 +426,11 @@ function AppShellContent({
   const [newTaskPermissionChoice, setNewTaskPermissionChoice, clearNewTaskPermissionChoice] =
     useNewTaskChoice<ChatDefaultPermissionMode>(currentNewTaskDraftKey);
   const [historyLoadPendingSessionId, setHistoryLoadPendingSessionId] = useState<string>();
+  // The state above is what the transcript renders; this is what the guard
+  // reads. A scroller can ask twice in one task — two scroll events before
+  // React has re-rendered anything — and a state read is still the old value
+  // for both of them.
+  const historyLoadPendingRef = useRef(false);
   const [transcriptTurnIndex, setTranscriptTurnIndex] = useState<{
     sessionId: string;
     throughSequence: number | null;
@@ -2580,7 +2585,8 @@ function AppShellContent({
   async function loadTranscriptHistory(target: 'earlier' | 'latest') {
     const controller = transcriptRangeRef.current;
     const sessionId = activeId;
-    if (!controller || !sessionId || historyLoadPendingSessionId) return;
+    if (!controller || !sessionId || historyLoadPendingRef.current) return;
+    historyLoadPendingRef.current = true;
     setHistoryLoadPendingSessionId(sessionId);
     try {
       if (target === 'earlier') {
@@ -2605,6 +2611,7 @@ function AppShellContent({
         ),
       );
     } finally {
+      historyLoadPendingRef.current = false;
       setHistoryLoadPendingSessionId((current) => current === sessionId ? undefined : current);
     }
   }
@@ -2843,9 +2850,11 @@ function AppShellContent({
                 )
               ) : (
               <ChatSurfaceLayout
-                // Reset conversation-owned scroll state without remounting the
-                // composer: its contenteditable DOM carries the live draft.
-                conversationKey={activeId}
+                // ChatView positions this transcript: switching conversations,
+                // following the tail and the moves the reader asks for are one
+                // authority there, and the composer never remounts for any of
+                // them — its contenteditable DOM carries the live draft.
+                scrollOwner="host"
                 scrollToBottomLabel={
                   desktopConversationCopy.actions.scrollMainToBottom
                 }

apps/desktop/src/renderer/chat-message-surface.tsx

@@ -245,7 +245,6 @@ export function ChatMessageSurface({
         deepResearchRun={deepResearchRun}
         emptyOverride={emptyOverride}
         hasOlderHistory={hasOlderHistory}
-        historyLoadPending={historyLoadPending}
         onLoadEarlierHistory={onLoadEarlierHistory}
         returnToLatest={hasNewerHistory ? {
           title: transcriptCopy.partialHistoryTitle,

apps/desktop/src/renderer/features/workbar/tools/side-chat/quote-companion-panel.tsx

@@ -205,7 +205,7 @@ export function QuoteCompanionPanel(props: {
       data-preparing={companion.preparing || undefined}
     >
       <ChatSurfaceLayout
-        conversationKey={companion.companionSession?.id ?? props.sourceSession?.id}
+        scrollOwner="host"
         scrollToBottomLabel={copy.scrollToBottom}
         composer={
           <>

apps/desktop/src/renderer/styles/chat-message.css

@@ -42,6 +42,16 @@
   width: 100%;
 }
 
+/* Inserting earlier turns above the reader must not move what they are
+   reading. The browser's scroll anchoring does exactly that, so state the
+   dependency on the scroller that runs it rather than inheriting the `auto`
+   default: Maka reads no geometry and restores no position of its own. The
+   one case anchoring declines is a scroller sitting at zero, compensated in
+   useChatScroll after the turns land. */
+[data-chat-scroll-container='true'] {
+  overflow-anchor: auto;
+}
+
 .maka-turn-virtual-item {
   display: flex;
   width: 100%;

apps/desktop/src/renderer/workhub-surface.tsx

@@ -363,7 +363,6 @@ export function WorkHubSurface(props: {
   return (
     <ChatSurfaceLayout
       className="workhub-surface"
-      conversationKey="workhub"
       composer={(
         <Composer
           draftKey="workhub"
@@ -473,7 +472,6 @@ export function WorkHubCoordinationStatus(props: {
   return (
     <ChatSurfaceLayout
       className="workhub-surface"
-      conversationKey="workhub-coordination-status"
       composer={(
         <Composer
           draftKey="workhub"

apps/desktop/stories/app-shell.stories.tsx

@@ -456,6 +456,7 @@ function ComposedShell(props: {
             (<div className="maka-detail-with-artifacts">
               <div className="mainColumn">
               <ChatSurfaceLayout
+                scrollOwner="host"
                 composer={
                   <Composer
                     {...baseComposerProps}

apps/desktop/stories/onboarding.stories.tsx

@@ -85,7 +85,7 @@ function DetailPane(props: { children?: ReactNode }) {
       >
         <div className="maka-detail-with-artifacts">
           <div className="mainColumn" data-home-surface="true">
-            <ChatSurfaceLayout composer={null}>
+            <ChatSurfaceLayout scrollOwner="host" composer={null}>
               <ChatView messages={[]} scrollBehavior="smooth" onNew={() => undefined} emptyOverride={emptyOverride} />
             </ChatSurfaceLayout>
           </div>

docs/astryx-surface-file-inventory.md

@@ -5,7 +5,7 @@ Each row is one on-disk product surface file. Regenerated inventory must stay in
 
 Wiki bar: Design Conventions · API Use-the-System · Theming · Container Padding.
 
-**Totals:** 221 files — blocker 0, polish 1, aligned 220.
+**Totals:** 222 files — blocker 0, polish 1, aligned 221.
 
 ## Exclusions (explicit)
 
@@ -244,6 +244,7 @@ Wiki bar: Design Conventions · API Use-the-System · Theming · Container Paddi
 | `packages/ui/src/tool-activity/diff-code-preview.tsx` | ui-composition | none | aligned — no raw controls; no Astryx JSX usage | aligned |
 | `packages/ui/src/tool-activity/tool-code-block.tsx` | ui-composition | none | aligned — no raw controls; no Astryx JSX usage | aligned |
 | `packages/ui/src/tool-activity/tool-result-preview.tsx` | ui-composition | Button | aligned — uses Astryx (Button) | aligned |
+| `packages/ui/src/transcript-scroll-authority.tsx` | ui-composition | none | aligned — no raw controls; no Astryx JSX usage | aligned |
 | `packages/ui/src/ui.tsx` | ui-composition | none | aligned — no raw controls; no Astryx JSX usage | aligned |
 | `packages/ui/src/user-question-prompt.tsx` | ui-composition | Button, TextInput | aligned — uses Astryx (Button, TextInput) | aligned |
 | `packages/ui/src/workspace-picker.tsx` | ui-composition | none | aligned — no raw controls; no Astryx JSX usage | aligned |

docs/astryx-surface-file-inventory.paths

@@ -216,6 +216,7 @@ packages/ui/src/tool-activity/agent-preview.tsx
 packages/ui/src/tool-activity/diff-code-preview.tsx
 packages/ui/src/tool-activity/tool-code-block.tsx
 packages/ui/src/tool-activity/tool-result-preview.tsx
+packages/ui/src/transcript-scroll-authority.tsx
 packages/ui/src/ui.tsx
 packages/ui/src/user-question-prompt.tsx
 packages/ui/src/workspace-picker.tsx