fix: detect and correct stale Yoga layout in cursor positioning across rounds

During the render phase, getComputedLayout() returns the layout from the
previous Yoga commit. When the transcript area grows (e.g. after an
assistant response), the input box moves down but the render-phase cursor
computation uses the old position, placing the cursor one line too high.

Fix: add a post-commit useEffect that recomputes the cursor position with
fresh Yoga layout, compares against the render-phase value stored in
lastPosRef, and triggers a corrective re-render when they differ. The
comparison guarantees at most one extra render per layout change.

Also refactored: extracted computeAbsolutePosition() helper, moved
position computation from useEffect to render phase (eliminating the
one-frame cursor visibility delay), and replaced setImmediate with
setTimeout(0) + counter dedup to survive React re-render cycles.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: jimgqyu

packages/tui/src/compat/cursor-hooks.ts

@@ -27,19 +27,16 @@
  * ### How the ink v7 fix works
  * - `useCursor()` returns `{ setCursorPosition }` which integrates with
  *   ink's log-update cursor state.
- * - `useInsertionEffect` propagates the position to the context BEFORE
- *   `onRender`, so `buildCursorSuffix` emits the correct CSI as part of
- *   the output frame.
- * - Ink's `buildReturnToBottomPrefix` correctly returns the cursor to the
- *   bottom before erasing because `cursorWasShown` is tracked accurately.
- *
- * Trade-off: coordinates are computed in useEffect (runs after
- * useInsertionEffect), causing a 1-frame lag.  This is acceptable because
- * IME composition text position is read by the terminal once composition
- * starts, at which point the cursor has been positioned for many frames.
+ * - The cursor position is computed during the render phase (via direct
+ *   computation in the hook body, not in useEffect).  This runs BEFORE
+ *   useCursor's useInsertionEffect, so positionRef.current is set before
+ *   ink propagates it to the log-update context.
+ * - On the first render, the Yoga node ref may not be available yet
+ *   (the ref callback fires after render).  A setTimeout(0) correction
+ *   with counter-based dedup handles this case robustly.
  */
 
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { useCursor } from 'ink';
 
 /**
@@ -60,6 +57,35 @@ export interface DeclaredCursorHandle {
   setPosition(row: number, col: number): void;
 }
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk up the Yoga layout tree and compute the element's absolute
+ * position in terminal cells (0-indexed from the ink output origin).
+ */
+function computeAbsolutePosition(el: any): { absTop: number; absLeft: number } | null {
+  if (!el?.yogaNode) return null;
+
+  try {
+    let node = el.yogaNode;
+    let absTop = 0;
+    let absLeft = 0;
+
+    while (node) {
+      const layout = node.getComputedLayout();
+      absTop += layout.top;
+      absLeft += layout.left;
+      node = node.getParent?.() ?? null;
+    }
+
+    return { absTop, absLeft };
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // useDeclaredCursor
 // ---------------------------------------------------------------------------
@@ -72,12 +98,12 @@ export interface DeclaredCursorHandle {
  *
  * On each render the hook:
  *   1. Captures the Box DOM element via the ref callback.
- *   2. In a post-render useEffect, walks up the Yoga node tree to compute
- *      the element's absolute position in terminal cells (0-indexed from
- *      the ink output origin).
+ *   2. During the render phase, walks up the Yoga node tree to compute
+ *      the element's absolute position in terminal cells.
  *   3. Adds the (line, column) offset from the cursor layout.
- *   4. Calls ink's `setCursorPosition({ x, y })` so ink's log-update
- *      includes the correct cursor suffix in the NEXT render frame.
+ *   4. Calls ink's `setCursorPosition` to write to the position ref,
+ *      so that useCursor's useInsertionEffect propagates it to log-update
+ *      in the same frame.
  *
  * The cursor is always positioned at the computed coordinates — we never
  * hide it via `setCursorPosition(undefined)`.  The TextInput's nativeCursor
@@ -98,60 +124,176 @@ export function useDeclaredCursor(
   const { setCursorPosition } = useCursor();
 
   // Track whether we have emitted the blink-enable sequence.
-  // \x1b[?12h is a DEC private mode that persists across cursor hide/show
-  // cycles, so we only need to emit it once per mount.
   const blinkEmittedRef = useRef(false);
 
+  // ── Counter-based dedup for first-frame Yoga layout correction ──────
+  // The ref callback fires AFTER the first render.  On the first render,
+  // elRef.current is null, so we can't compute the cursor position during
+  // the render phase.  After the ref callback fires, the component won't
+  // necessarily re-render (unless something else triggers it).
+  //
+  // We use a `refReady` state flag + setTimeout(0) correction to ensure
+  // the cursor is positioned as soon as possible:
+  //   1. Ref callback fires → setRefReady(true) → triggers re-render
+  //   2. On the re-render, position is computed during render phase
+  //   3. setTimeout(0) acts as a safety net for cases where Yoga hasn't
+  //      settled by the first re-render after ref callback
+  //
+  // Counter dedup: if multiple setTimeout callbacks are scheduled before
+  // the timer phase, only the latest one takes effect.
+  const correctionCounterRef = useRef(0);
+  const [refReady, setRefReady] = useState(false);
+
+  // ── Stale Yoga layout correction ─────────────────────────────────────
+  // During the render phase, getComputedLayout() returns the layout from
+  // the PREVIOUS Yoga commit — not the layout that will be produced by the
+  // CURRENT commit.  When content above the input box grows (e.g. after an
+  // assistant response), the input element's absolute position changes but
+  // the render-phase computation uses the old (higher) position.
+  //
+  // The post-commit useEffect below detects this discrepancy:
+  //   1. Render phase computes position from stale Yoga → stores in lastPosRef
+  //   2. useInsertionEffect propagates stale position to log-update
+  //   3. Post-commit: Yoga layout is now fresh → recompute position
+  //   4. If position differs from lastPosRef → setCursorPosition + force re-render
+  //   5. Re-render: render phase uses fresh Yoga → position matches → stable
+  //
+  // The lastPosRef comparison prevents infinite re-render loops.
+  const lastPosRef = useRef<{ x: number; y: number } | null>(null);
+  const [, setCorrectionTick] = useState(0);
+
+  // ── Compute cursor position during render phase ────────────────────
+  // This is called during the render, BEFORE useCursor's useInsertionEffect
+  // runs.  The setCursorPosition call only writes to a ref (positionRef),
+  // so it's safe to call during render — no state changes, no side effects.
+  //
+  // On the first render, elRef.current is null because the ref callback
+  // hasn't fired yet.  On subsequent renders (after the ref callback),
+  // elRef.current is set and we can compute the position immediately.
+  //
+  // NOTE: getComputedLayout() returns the layout from the PREVIOUS Yoga
+  // commit.  When the input box moves (e.g. after assistant output grows),
+  // this computation produces a stale position.  The post-commit useEffect
+  // below detects the discrepancy and triggers a correction re-render.
+  const el = elRef.current;
+  if (el?.yogaNode) {
+    const pos = computeAbsolutePosition(el);
+    if (pos) {
+      const opts = optsRef.current;
+      const x = pos.absLeft + (opts?.column ?? 0);
+      const y = pos.absTop + (opts?.line ?? 0);
+
+      // Store for post-commit comparison (detects stale Yoga layout).
+      lastPosRef.current = { x, y };
+
+      // Write to ink's positionRef synchronously during render.
+      // useCursor's useInsertionEffect will read this and propagate
+      // it to the log-update cursor context in the same frame.
+      setCursorPosition({ x, y });
+
+      // Enable cursor blinking on the first successful position computation.
+      if (!blinkEmittedRef.current && process.stdout.isTTY) {
+        process.stdout.write('\x1b[?12h');
+        blinkEmittedRef.current = true;
+      }
+    }
+  }
+
+  // ── First-frame Yoga layout correction via setTimeout ──────────────
+  // Schedule a correction after the current render cycle completes.
+  // Uses setTimeout(0) instead of setImmediate because:
+  //   - setImmediate callbacks live in the check phase and can be canceled
+  //     by clearImmediate() in useEffect cleanup during React re-renders
+  //   - setTimeout(0) fires in the timer phase and survives React's
+  //     effect cleanup cycle
+  //
+  // The correction callback re-computes the position using the latest
+  // Yoga layout and the latest cursor opts.  Counter dedup ensures only
+  // the latest scheduled correction actually takes effect.
   useEffect(() => {
     const opts = optsRef.current;
     if (!process.stdout.isTTY) return;
 
-    // Enable cursor blinking on the first successful render frame.
-    // Ink v7's buildCursorSuffix only emits \x1b[?25h (DECTCEM show cursor),
-    // never a blink sequence.  ?12h is the DEC "Start Blinking Cursor" mode
-    // and is widely supported (xterm, iTerm2, Windows Terminal).  Terminals
-    // that ignore ?12h (kitty, Alacritty) control blinking via user config.
-    if (!blinkEmittedRef.current) {
-      process.stdout.write('\x1b[?12h');
-      blinkEmittedRef.current = true;
-    }
+    const correctionId = ++correctionCounterRef.current;
 
-    const el = elRef.current;
-    if (!el?.yogaNode) return;
+    const timerId = setTimeout(() => {
+      // Only the latest correction takes effect
+      if (correctionId !== correctionCounterRef.current) return;
 
-    try {
-      // Walk up the Yoga layout tree, summing top / left offsets to
-      // compute the element's absolute position in terminal cells.
-      let node = el.yogaNode;
-      let absTop = 0;
-      let absLeft = 0;
-
-      while (node) {
-        const layout = node.getComputedLayout();
-        absTop += layout.top;
-        absLeft += layout.left;
-        node = node.getParent?.() ?? null;
-      }
+      const el2 = elRef.current;
+      const pos = computeAbsolutePosition(el2);
+      if (!pos) return;
 
-      // Ink's CursorPosition is 0-indexed from the ink output origin.
-      // absTop/absLeft from the root Yoga node ARE the ink-relative
-      // offsets (the Yoga root represents the entire ink output).
-      // The +1 on y accounts for the terminal row offset between the
-      // Yoga layout origin and the first ink-rendered row.
+      const latestOpts = optsRef.current;
       setCursorPosition({
-        x: absLeft + (opts?.column ?? 0),
-        y: absTop + (opts?.line ?? 0) + 1,
+        x: pos.absLeft + (latestOpts?.column ?? 0),
+        y: pos.absTop + (latestOpts?.line ?? 0),
       });
-    } catch {
-      // Yoga layout not yet computed — silently skip this frame.
-      // The next render will retry once Yoga has calculated positions.
+
+      // Also trigger a re-render so useInsertionEffect propagates the
+      // position to log-update on the next frame.
+      if (!refReady) {
+        setRefReady(true);
+      }
+    }, 0);
+
+    // NOTE: Intentionally NOT canceling the timeout in cleanup.
+    // The counter dedup mechanism above handles stale corrections.
+    // Canceling in cleanup would reintroduce the same bug
+    // (setImmediate + clearImmediate being defeated by re-renders).
+  });
+
+  // ── Post-commit stale Yoga layout correction ──────────────────────
+  // This useEffect (no deps) runs after EVERY commit with fresh Yoga layout.
+  // It detects when the input element's absolute position changed between the
+  // previous and current Yoga commits — a scenario the render phase cannot
+  // detect because getComputedLayout() returns stale (pre-commit) values.
+  //
+  // Flow when layout changes:
+  //   1. Render phase: lastPosRef = stalePos, setCursorPosition(stalePos)
+  //   2. useInsertionEffect propagates stalePos to log-update → wrong cursor
+  //   3. Post-commit useEffect: Yoga fresh → compute freshPos
+  //   4. freshPos !== lastPosRef → setCursorPosition(freshPos) + setCorrectionTick
+  //   5. Next render: render phase uses fresh Yoga → freshPos === lastPosRef
+  //   6. useInsertionEffect propagates freshPos → correct cursor
+  //   7. Post-commit useEffect: freshPos === lastPosRef → no-op → stable
+  //
+  // Counter state (correctionTick) is used instead of a boolean flag because
+  // React may batch multiple setState(false) calls and skip the re-render.
+  // An incrementing counter guarantees each correction triggers a distinct
+  // state transition.
+  useEffect(() => {
+    const el = elRef.current;
+    if (!el?.yogaNode) return;
+
+    const pos = computeAbsolutePosition(el);
+    if (!pos) return;
+
+    const opts = optsRef.current;
+    const x = pos.absLeft + (opts?.column ?? 0);
+    const y = pos.absTop + (opts?.line ?? 0);
+
+    const last = lastPosRef.current;
+    if (!last || last.x !== x || last.y !== y) {
+      // Yoga layout shifted post-commit — update cursor ref and force
+      // a re-render so useCursor's useInsertionEffect propagates the
+      // corrected position to log-update.
+      setCursorPosition({ x, y });
+      setCorrectionTick((t) => t + 1);
     }
   });
 
-  // Ref-setter callback — captures the Box element for the effect above.
-  return useCallback((el: any) => {
+  // ── Ref callback ──────────────────────────────────────────────────
+  // Triggers a re-render (via refReady state) when the ref is first set,
+  // so the render-phase position computation can run with the Yoga node.
+  const boxRefCallback = useCallback((el: any) => {
     elRef.current = el;
-  }, []);
+    if (el && !refReady) {
+      setRefReady(true);
+    }
+  }, [refReady]);
+
+  return boxRefCallback;
 }
 
 // ---------------------------------------------------------------------------