mixdog 1.4.1 → 1.4.3

package/src/tui/app/use-pasted-buffers.mjs

@@ -48,31 +48,39 @@ function usePastedBufferSlice({ toEntry, formatRef }) {
     setBuffers(next);
   }, []);
 
-  const register = useCallback((input) => {
-    const id = nextIdRef.current;
-    const entry = toEntry(input, id);
-    if (!entry) return '';
-    nextIdRef.current = id + 1;
-    buffersRef.current = { ...buffersRef.current, [id]: entry };
-    setBuffers(buffersRef.current);
-    return formatRef(entry);
-  }, []);
+  const register = useCallback(
+    (input) => {
+      const id = nextIdRef.current;
+      const entry = toEntry(input, id);
+      if (!entry) return '';
+      nextIdRef.current = id + 1;
+      buffersRef.current = { ...buffersRef.current, [id]: entry };
+      setBuffers(buffersRef.current);
+      return formatRef(entry);
+    },
+    [toEntry, formatRef]
+  );
 
   return { buffersRef, nextIdRef, install, clearSnapshot, register };
 }
 
+// Module-level slice specs keep toEntry/formatRef identities stable, so
+// `register` is created once per mount.
+const IMAGE_SLICE = {
+  toEntry: (image, id) => (image?.type === 'image' && image.content ? { ...image, id } : null),
+  formatRef: (entry) => formatImageRef(entry.id),
+};
+const TEXT_SLICE = {
+  toEntry: (text, id) => {
+    const value = String(text ?? '');
+    return value ? { id, text: value } : null;
+  },
+  formatRef: (entry) => formatPastedTextRef(entry.id, entry.text),
+};
+
 export function usePastedBuffers() {
-  const images = usePastedBufferSlice({
-    toEntry: (image, id) => (image?.type === 'image' && image.content ? { ...image, id } : null),
-    formatRef: (entry) => formatImageRef(entry.id),
-  });
-  const texts = usePastedBufferSlice({
-    toEntry: (text, id) => {
-      const value = String(text ?? '');
-      return value ? { id, text: value } : null;
-    },
-    formatRef: (entry) => formatPastedTextRef(entry.id, entry.text),
-  });
+  const images = usePastedBufferSlice(IMAGE_SLICE);
+  const texts = usePastedBufferSlice(TEXT_SLICE);
 
   return {
     pastedImagesRef: images.buffersRef,

package/src/tui/app/use-prompt-draft-flow.mjs

@@ -65,6 +65,13 @@ export function usePromptDraftFlow({
       showPromptHint,
       slashDismissedFor,
       syncPromptLayoutRows,
+      promptHistoryDraftChangeRef,
+      promptHistoryNavRef,
+      setPromptDraft,
+      setPromptDraftOverride,
+      promptHintActiveRef,
+      promptHintTimerRef,
+      setSlashDismissedFor,
     ]
   );
 

package/src/tui/app/use-prompt-layout-rows.mjs

@@ -21,11 +21,11 @@ export function usePromptLayoutRows({
       const nextRows = promptContentRows(text, promptContentColumns);
       setPromptLayoutRows((prev) => (prev === nextRows ? prev : nextRows));
     },
-    [promptContentColumns]
+    [promptContentColumns, promptLayoutValueRef, setPromptLayoutRows]
   );
   useEffect(() => {
     syncPromptLayoutRows(promptLayoutValueRef.current);
-  }, [syncPromptLayoutRows]);
+  }, [syncPromptLayoutRows, promptLayoutValueRef]);
   useEffect(() => {
     const kind = String(settingsPrompt?.kind || '');
     if (!CORE_MULTILINE_TEXT_ENTRY_KINDS.has(kind)) {
@@ -34,6 +34,6 @@ export function usePromptLayoutRows({
     }
     const cols = Math.max(1, frameColumns - 4 - stringWidth('Sentence > '));
     setTextEntryLayoutRows(textEntryReservedRows(settingsPrompt?.initialValue, cols, 8));
-  }, [settingsPrompt?.kind, settingsPrompt?.initialValue, frameColumns]);
+  }, [settingsPrompt?.kind, settingsPrompt?.initialValue, frameColumns, setTextEntryLayoutRows]);
   return syncPromptLayoutRows;
 }

package/src/tui/app/use-prompt-queue-history.mjs

@@ -53,7 +53,7 @@ export function usePromptQueueHistory({
         exit();
       });
     }, 60);
-  }, [store, exit]);
+  }, [store, exit, exitRequestedRef, setExiting]);
 
   const restoreQueuedToPrompt = useCallback(
     (options = {}) =>
@@ -74,6 +74,7 @@ export function usePromptQueueHistory({
       store,
       state?.queued,
       promptDraft,
+      promptValueRef,
       showPromptHint,
       clearPromptHint,
       installPastedImages,
@@ -85,8 +86,8 @@ export function usePromptQueueHistory({
 
   const recentPromptHistory = useMemo(() => {
     // The engine maintains this list incrementally (rebuilt only when a user
-    // item is appended or the transcript is bulk-swapped), so App no longer
-    // rescans all items on every transcript change. Fall back to a local scan
+    // item is appended or the transcript is bulk-swapped), so App does not
+    // rescan all items on every transcript change. Fall back to a local scan
     // only if the engine did not publish it (older snapshot).
     if (Array.isArray(state.promptHistoryList)) return state.promptHistoryList;
     return scanPromptHistory(Array.isArray(state.items) ? state.items : []);
@@ -94,7 +95,7 @@ export function usePromptQueueHistory({
 
   const resetPromptHistoryNav = useCallback(() => {
     promptHistoryNavRef.current = { active: false, index: -1, seed: '', lastValue: '' };
-  }, []);
+  }, [promptHistoryNavRef]);
 
   return { requestExit, restoreQueuedToPrompt, recentPromptHistory, resetPromptHistoryNav };
 }

package/src/tui/app/use-selection-focus.mjs

@@ -31,7 +31,7 @@ export function useSelectionFocusMove({
       const shiftedRect = dragRef.current.rect;
       return { anchor: shiftedRect ? { x: shiftedRect.x1, y: shiftedRect.y1 } : null };
     },
-    [scrollTranscriptRows]
+    [dragRef, scrollTargetRef, scrollTranscriptRows]
   );
 
   const moveSelectionFocus = useCallback(
@@ -120,7 +120,16 @@ export function useSelectionFocusMove({
       dragNow.last = { x: col, y: row };
       return true;
     },
-    [applySelectionRect, statusBandRows, transcriptViewportRows, selectionMaxColAtRow, scrollFocusPastEdge]
+    [
+      dragRef,
+      scrollTargetRef,
+      transcriptBottomSlackRowsRef,
+      applySelectionRect,
+      statusBandRows,
+      transcriptViewportRows,
+      selectionMaxColAtRow,
+      scrollFocusPastEdge,
+    ]
   );
 
   return moveSelectionFocus;

package/src/tui/app/use-selection-geometry.mjs

@@ -22,13 +22,16 @@ export function useSelectionGeometry({
   transcriptViewportRef,
   dragRef,
 }) {
-  const selectionPointAtCurrentScroll = useCallback((point, pointScroll = 0) => {
-    if (!point) return null;
-    return {
-      x: point.x,
-      y: point.y + (Number(scrollTargetRef.current) || 0) - (Number(pointScroll) || 0),
-    };
-  }, []);
+  const selectionPointAtCurrentScroll = useCallback(
+    (point, pointScroll = 0) => {
+      if (!point) return null;
+      return {
+        x: point.x,
+        y: point.y + (Number(scrollTargetRef.current) || 0) - (Number(pointScroll) || 0),
+      };
+    },
+    [scrollTargetRef]
+  );
 
   // Grow a word/line multi-click selection from its anchor span out to the
   // word/line under the cursor. Shared by the mouse handler (motion/release)
@@ -68,9 +71,15 @@ export function useSelectionGeometry({
     [store, frameColumns, selectionPointAtCurrentScroll]
   );
 
-  const transcriptViewportRows = useCallback(() => transcriptViewportRowRange(transcriptViewportRef.current), []);
+  const transcriptViewportRows = useCallback(
+    () => transcriptViewportRowRange(transcriptViewportRef.current),
+    [transcriptViewportRef]
+  );
 
-  const statusBandRows = useCallback(() => statusBandRowRange(frameRowsRef.current, statuslineBandRows), []);
+  const statusBandRows = useCallback(
+    () => statusBandRowRange(frameRowsRef.current, statuslineBandRows),
+    [frameRowsRef, statuslineBandRows]
+  );
 
   const selectionMaxColAtRow = useCallback(
     (row) => {

package/src/tui/app/use-selection-paint.mjs

@@ -54,12 +54,12 @@ export function useSelectionPaint({
       .catch(() => {
         /* best-effort capture: Ctrl+C falls back to the render-time text */
       });
-  }, [store]);
+  }, [store, selectionTextRef]);
 
   // Clip band + theming: use-selection-paint/selection-clip.mjs.
   const selectionClip = useCallback(
     () => selectionClipBand({ dragRef, frameRowsRef, transcriptViewportRef, statuslineBandRows }),
-    [statuslineBandRows]
+    [dragRef, frameRowsRef, transcriptViewportRef, statuslineBandRows]
   );
 
   const withSelectionClip = useCallback(
@@ -98,7 +98,7 @@ export function useSelectionPaint({
       cancelPendingSelectionPaint();
       paintSelectionRect(clippedRect, { rememberText: true });
     },
-    [paintSelectionRect, withSelectionClip, clearStitchBuffer, cancelPendingSelectionPaint]
+    [dragRef, selectionTextRef, paintSelectionRect, withSelectionClip, clearStitchBuffer, cancelPendingSelectionPaint]
   );
 
   const applySelectionRectThrottled = useCallback(
@@ -111,7 +111,7 @@ export function useSelectionPaint({
         cancelPending: cancelPendingSelectionPaint,
       });
     },
-    [paintSelectionRect, withSelectionClip, cancelPendingSelectionPaint]
+    [dragRef, paintSelectionRect, withSelectionClip, cancelPendingSelectionPaint]
   );
 
   return {

package/src/tui/app/use-selection-stitch.mjs

@@ -64,7 +64,7 @@ export function useSelectionStitchBuffer({ store, dragRef, scrollTargetRef }) {
       if (!Array.isArray(rows)) return;
       storeStitchRows(stitchBufferRef.current, rows, stitchHarvestScrollRef.current);
     }, 0);
-  }, [store]);
+  }, [store, dragRef, scrollTargetRef]);
 
   // Synchronous sibling: snapshot the rows CURRENTLY under the selection
   // immediately, keyed by the given (pre-scroll) offset. Called right before
@@ -80,7 +80,7 @@ export function useSelectionStitchBuffer({ store, dragRef, scrollTargetRef }) {
       if (!Array.isArray(rows)) return;
       storeStitchRows(stitchBufferRef.current, rows, Number(scroll) || 0);
     },
-    [store]
+    [store, dragRef]
   );
 
   // Map the CURRENT rect + current scrollTarget onto the content-key range and
@@ -122,7 +122,7 @@ export function useSelectionStitchBuffer({ store, dragRef, scrollTargetRef }) {
     }
     const text = logical.map((l) => l.replace(/\s+$/u, '')).join('\n');
     return text.trim() ? { text, complete } : empty;
-  }, []);
+  }, [dragRef, scrollTargetRef]);
 
   return { clearStitchBuffer, harvestStitchRowsSoon, harvestStitchRowsNow, getStitchedSelectionText };
 }

package/src/tui/app/use-slash-palette.mjs

@@ -0,0 +1,62 @@
+/*
+ * app/use-slash-palette.mjs — the slash / `$skill` palette above the prompt.
+ *
+ * useSlashPaletteState owns the selection index, the dismissed-draft marker
+ * and the live open/count ref the mouse handler reads; it is declared early
+ * because the mouse and draft hooks need the setters. useSlashPalette derives
+ * the palette for this render from the prompt and the surfaces that suppress
+ * it, publishes it to that ref, and keeps the index inside the list.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { deriveSlashPalette } from './slash-palette.mjs';
+import { skillMentionQuery, useSkillMentionSkills } from './skill-mention-palette.mjs';
+
+export function useSlashPaletteState() {
+  const [slashIndex, setSlashIndex] = useState(0);
+  const [slashDismissedFor, setSlashDismissedFor] = useState('');
+  const slashPaletteRef = useRef({ open: false, count: 0 });
+  return { slashIndex, setSlashIndex, slashDismissedFor, setSlashDismissedFor, slashPaletteRef };
+}
+
+export function useSlashPalette({
+  store,
+  slashPaletteRef,
+  setSlashIndex,
+  slashDismissedFor,
+  promptDraft,
+  promptCaret,
+  providerPrompt,
+  settingsPrompt,
+  toolApproval,
+  contextPanel,
+  usagePanel,
+  picker,
+  exiting,
+  commandBusy,
+}) {
+  const mentionSkills = useSkillMentionSkills(store, skillMentionQuery(promptDraft, promptCaret) !== null);
+  const palette = deriveSlashPalette({
+    providerPrompt,
+    settingsPrompt,
+    toolApproval,
+    contextPanel,
+    usagePanel,
+    picker,
+    exiting,
+    commandBusy,
+    promptDraft,
+    slashDismissedFor,
+    skills: mentionSkills,
+    promptCaret,
+  });
+  const { activeSlashQuery, slashCommands, slashPaletteOpen } = palette;
+  slashPaletteRef.current = { open: slashPaletteOpen, count: slashCommands.length };
+
+  // A query change re-clamps even when the list length stays the same.
+  // biome-ignore lint/correctness/useExhaustiveDependencies(activeSlashQuery): query-change re-clamp trigger
+  useEffect(() => {
+    setSlashIndex((index) => Math.min(index, Math.max(0, slashCommands.length - 1)));
+  }, [slashCommands.length, activeSlashQuery, setSlashIndex]);
+
+  return palette;
+}

package/src/tui/app/use-terminal-chrome.mjs

@@ -47,7 +47,7 @@ export function useTerminalChrome({ stdout, isRawModeSupported, setResizeState }
       if (trailing) clearTimeout(trailing);
       stdout.off('resize', onResize);
     };
-  }, [stdout]);
+  }, [stdout, setResizeState]);
 
   // Enable extended keyboard reporting (kitty + xterm modifyOtherKeys)
   // SYNCHRONOUSLY, ONCE, with NO query/round-trip. ink
@@ -61,7 +61,7 @@ export function useTerminalChrome({ stdout, isRawModeSupported, setResizeState }
   // \x1b[27;5;13~ (or kitty \x1b[13;5u) instead of a bare \r — fixing the old
   // "first Ctrl+Enter submits, second works" race. Teardown lives in index.jsx's
   // restoreTerminal(). The empty dep array makes this run exactly once on mount.
-  // eslint-disable-next-line react-hooks/exhaustive-deps
+  // biome-ignore lint/correctness/useExhaustiveDependencies: one-shot mount enable; teardown is owned by restoreTerminal()
   useEffect(() => {
     if (!isRawModeSupported || !stdout?.write) return;
     if (!supportsExtendedKeys()) return;

package/src/tui/app/use-transcript-activity.mjs

@@ -59,7 +59,7 @@ export function useTranscriptActivity({ state }) {
   // the StatusLine effect only re-fires when the numbers actually change.
   const activeToolsSignature = useMemo(() => {
     // The engine maintains this signature incrementally (updated on tool
-    // start/early-complete/result/turn-end), so App no longer scans every
+    // start/early-complete/result/turn-end), so App does not scan every
     // transcript item on each change. Prefer it; fall back to the local scan
     // only when the engine did not publish it (older snapshot).
     if (state.activeToolSummary !== undefined) return state.activeToolSummary || '';
@@ -105,38 +105,53 @@ export function useTranscriptActivity({ state }) {
   // StatusLine only reads a small stats subset; engine clones the full stats
   // object on many updates. Memoize by field value so identical usage keeps
   // the same object reference and React.memo / effect deps stay quiet.
-  const statuslineStats = useMemo(() => {
-    const s = state.stats || {};
-    return {
-      currentContextSource: s.currentContextSource ?? null,
-      currentEstimatedContextTokens: s.currentEstimatedContextTokens ?? 0,
-      currentContextTokens: s.currentContextTokens ?? null,
-      contextTokens: s.contextTokens ?? 0,
-      latestPromptTokens: s.latestPromptTokens ?? 0,
-      latestInputTokens: s.latestInputTokens ?? 0,
-      latestCachedTokens: s.latestCachedTokens ?? 0,
-      latestCacheWriteTokens: s.latestCacheWriteTokens ?? 0,
-      inputTokens: s.inputTokens ?? 0,
-      cachedTokens: s.cachedTokens ?? 0,
-      cacheWriteTokens: s.cacheWriteTokens ?? 0,
-      promptTokens: s.promptTokens ?? 0,
-      turns: s.turns ?? 0,
-    };
-  }, [
-    state.stats?.currentContextSource,
-    state.stats?.currentEstimatedContextTokens,
-    state.stats?.currentContextTokens,
-    state.stats?.contextTokens,
-    state.stats?.latestPromptTokens,
-    state.stats?.latestInputTokens,
-    state.stats?.latestCachedTokens,
-    state.stats?.latestCacheWriteTokens,
-    state.stats?.inputTokens,
-    state.stats?.cachedTokens,
-    state.stats?.cacheWriteTokens,
-    state.stats?.promptTokens,
-    state.stats?.turns,
-  ]);
+  const {
+    currentContextSource,
+    currentEstimatedContextTokens,
+    currentContextTokens,
+    contextTokens,
+    latestPromptTokens,
+    latestInputTokens,
+    latestCachedTokens,
+    latestCacheWriteTokens,
+    inputTokens,
+    cachedTokens,
+    cacheWriteTokens,
+    promptTokens,
+    turns,
+  } = state.stats || {};
+  const statuslineStats = useMemo(
+    () => ({
+      currentContextSource: currentContextSource ?? null,
+      currentEstimatedContextTokens: currentEstimatedContextTokens ?? 0,
+      currentContextTokens: currentContextTokens ?? null,
+      contextTokens: contextTokens ?? 0,
+      latestPromptTokens: latestPromptTokens ?? 0,
+      latestInputTokens: latestInputTokens ?? 0,
+      latestCachedTokens: latestCachedTokens ?? 0,
+      latestCacheWriteTokens: latestCacheWriteTokens ?? 0,
+      inputTokens: inputTokens ?? 0,
+      cachedTokens: cachedTokens ?? 0,
+      cacheWriteTokens: cacheWriteTokens ?? 0,
+      promptTokens: promptTokens ?? 0,
+      turns: turns ?? 0,
+    }),
+    [
+      currentContextSource,
+      currentEstimatedContextTokens,
+      currentContextTokens,
+      contextTokens,
+      latestPromptTokens,
+      latestInputTokens,
+      latestCachedTokens,
+      latestCacheWriteTokens,
+      inputTokens,
+      cachedTokens,
+      cacheWriteTokens,
+      promptTokens,
+      turns,
+    ]
+  );
 
   return { agentRevision, activeTools, statuslineStats };
 }

package/src/tui/app/use-transcript-follow.mjs

@@ -44,11 +44,11 @@ export function useTranscriptFollow({
       setScrollOffset(Math.max(0, Math.round(scrollPositionRef.current)));
     }, 16);
     scrollAnimationRef.current.unref?.();
-  }, [stopSmoothScroll]);
+  }, [scrollPositionRef, scrollTargetRef, followingRef, setScrollOffset, stopSmoothScroll]);
 
   const cancelTranscriptFollow = useCallback(() => {
     followingRef.current = false;
-  }, []);
+  }, [followingRef]);
 
   const resetTranscriptScroll = useCallback(() => {
     stopSmoothScroll();
@@ -65,7 +65,15 @@ export function useTranscriptFollow({
     // and every new row piled up below the fold.
     followingRef.current = true;
     setScrollOffset(0);
-  }, [stopSmoothScroll]);
+  }, [
+    scrollPositionRef,
+    scrollTargetRef,
+    followingRef,
+    transcriptAnchorRef,
+    transcriptAnchorDirtyRef,
+    setScrollOffset,
+    stopSmoothScroll,
+  ]);
 
   const armTranscriptFollow = useCallback(() => {
     // Do not mutate scrollOffset here. During prompt submit the transcript rows
@@ -78,7 +86,7 @@ export function useTranscriptFollow({
     pendingReadbackRowsRef.current = 0;
     followingRef.current = true;
     stopSmoothScroll();
-  }, [stopSmoothScroll]);
+  }, [followingRef, transcriptAnchorRef, transcriptAnchorDirtyRef, stopSmoothScroll]);
 
   return {
     pendingReadbackRowsRef,

package/src/tui/app/use-transcript-scroll.mjs

@@ -141,7 +141,7 @@ export function useTranscriptScroll({
     if (!anchor) return;
     transcriptAnchorRef.current = anchor;
     transcriptAnchorDirtyRef.current = false;
-  }, []);
+  }, [transcriptGeomRef, scrollTargetRef, transcriptAnchorRef, transcriptAnchorDirtyRef]);
 
   // A manual scroll moves the reading position. Capture the new anchor
   // SYNCHRONOUSLY from the latest published geometry so the very next render
@@ -149,20 +149,23 @@ export function useTranscriptScroll({
   // streaming growth could lurch the view. Only at the true bottom drop the
   // anchor so the bottom-follow path owns the viewport again: a positive
   // wheel offset is an explicit reading position, even inside the old slack.
-  const captureReadingAnchor = useCallback((target) => {
-    if (target === 0) {
-      transcriptAnchorRef.current = null;
-      transcriptAnchorDirtyRef.current = false;
-      return;
-    }
-    const anchor = readingAnchorAt(transcriptGeomRef.current || {}, target);
-    if (anchor) {
-      transcriptAnchorRef.current = anchor;
-      transcriptAnchorDirtyRef.current = false;
-    } else {
-      transcriptAnchorDirtyRef.current = true;
-    }
-  }, []);
+  const captureReadingAnchor = useCallback(
+    (target) => {
+      if (target === 0) {
+        transcriptAnchorRef.current = null;
+        transcriptAnchorDirtyRef.current = false;
+        return;
+      }
+      const anchor = readingAnchorAt(transcriptGeomRef.current || {}, target);
+      if (anchor) {
+        transcriptAnchorRef.current = anchor;
+        transcriptAnchorDirtyRef.current = false;
+      } else {
+        transcriptAnchorDirtyRef.current = true;
+      }
+    },
+    [transcriptGeomRef, transcriptAnchorRef, transcriptAnchorDirtyRef]
+  );
 
   // Scrolling past the oldest/newest loaded edge pages transcript history
   // instead of moving the target. Returns true when the edge owned the
@@ -190,7 +193,15 @@ export function useTranscriptScroll({
       }
       return true;
     },
-    [store, captureRestoreAnchor, stopSmoothScroll, cancelTranscriptFollow]
+    [
+      store,
+      scrollTargetRef,
+      scrollPositionRef,
+      setScrollOffset,
+      captureRestoreAnchor,
+      stopSmoothScroll,
+      cancelTranscriptFollow,
+    ]
   );
 
   // Keep a live selection on its content after the viewport moved. An active
@@ -229,7 +240,14 @@ export function useTranscriptScroll({
       // (Ctrl+C after scrolling then copied just that fragment).
       paintSelectionRect(clippedRect, { rememberText: false });
     },
-    [buildSpanRect, selectionPointAtCurrentScroll, withSelectionClip, cancelPendingSelectionPaint, paintSelectionRect]
+    [
+      dragRef,
+      buildSpanRect,
+      selectionPointAtCurrentScroll,
+      withSelectionClip,
+      cancelPendingSelectionPaint,
+      paintSelectionRect,
+    ]
   );
 
   const scrollTranscriptRows = useCallback(
@@ -294,6 +312,17 @@ export function useTranscriptScroll({
       setScrollOffset(Math.round(target));
     },
     [
+      maxScrollRowsRef,
+      transcriptGeomRef,
+      scrollTargetRef,
+      scrollPositionRef,
+      pendingReadbackRowsRef,
+      dragRef,
+      transcriptAnchorRef,
+      transcriptAnchorDirtyRef,
+      followingRef,
+      selectionLayoutRef,
+      setScrollOffset,
       pageTranscriptHistory,
       captureReadingAnchor,
       rebuildSelectionAfterScroll,

package/src/tui/app/use-transcript-swap-reset.mjs

@@ -0,0 +1,27 @@
+/*
+ * app/use-transcript-swap-reset.mjs — returns the viewport to the live tail
+ * when the transcript items are bulk-swapped.
+ *
+ * Item-count changes never infer follow permission from scrollTarget=0. A
+ * first read-back input can be waiting one frame for committed row geometry;
+ * only prompt submit, session reset, or an explicit return to bottom arms
+ * follow. Pure streaming height growth is handled in the row-delta effect.
+ */
+import { useLayoutEffect } from 'react';
+import { transcriptSwapReturnsToTail } from './transcript-window.mjs';
+
+export function useTranscriptSwapReset({ items, lastItemsCountRef, lastFirstItemIdRef, resetTranscriptScroll }) {
+  useLayoutEffect(() => {
+    const count = items.length;
+    const previousCount = lastItemsCountRef.current;
+    lastItemsCountRef.current = count;
+    const firstId = count > 0 ? (items[0]?.id ?? null) : null;
+    const previousFirstId = lastFirstItemIdRef.current;
+    lastFirstItemIdRef.current = firstId;
+    // A bulk swap (compaction included) is an explicit return to the tail: the
+    // rows the reader was anchored to no longer exist.
+    if (transcriptSwapReturnsToTail({ count, previousCount, firstId, previousFirstId })) {
+      resetTranscriptScroll();
+    }
+  }, [items, lastItemsCountRef, lastFirstItemIdRef, resetTranscriptScroll]);
+}