feat: refactor navigation to use visual rows

Author: justin-schroeder

src/DmuxApp.tsx

@@ -60,7 +60,10 @@ import UpdatingIndicator from "./components/indicators/UpdatingIndicator.js"
 import FooterHelp from "./components/ui/FooterHelp.js"
 import TmuxHooksPromptDialog from "./components/dialogs/TmuxHooksPromptDialog.js"
 import { PaneEventService } from "./services/PaneEventService.js"
-import { buildProjectActionLayout } from "./utils/projectActions.js"
+import {
+  buildProjectActionLayout,
+  buildVisualNavigationRows,
+} from "./utils/projectActions.js"
 
 const DmuxApp: React.FC<DmuxAppProps> = ({
   panesFile,
@@ -409,12 +412,17 @@ const DmuxApp: React.FC<DmuxAppProps> = ({
     () => buildProjectActionLayout(panes, sessionProjectRoot, projectName),
     [panes, sessionProjectRoot, projectName]
   )
+  const navigationRows = useMemo(
+    () => isLoading
+      ? projectActionLayout.groups.flatMap((group) =>
+          group.panes.map((entry) => [entry.index])
+        )
+      : buildVisualNavigationRows(projectActionLayout),
+    [isLoading, projectActionLayout]
+  )
 
   // Navigation logic moved to hook
-  const { getCardGridPosition, findCardInDirection } = useNavigation(
-    terminalWidth,
-    isLoading ? panes.length : projectActionLayout.totalItems
-  )
+  const { getCardGridPosition, findCardInDirection } = useNavigation(navigationRows)
 
   // findCardInDirection provided by useNavigation
 
@@ -892,9 +900,8 @@ const DmuxApp: React.FC<DmuxAppProps> = ({
         toastQueuePosition={toastQueuePosition}
         gridInfo={(() => {
           if (!process.env.DEBUG_DMUX) return undefined
-          const cols = Math.max(1, Math.floor(terminalWidth / 37))
-          const totalCards = isLoading ? panes.length : projectActionLayout.totalItems
-          const rows = Math.ceil(totalCards / cols)
+          const rows = navigationRows.length
+          const cols = Math.max(1, ...navigationRows.map((row) => row.length))
           const pos = getCardGridPosition(selectedIndex)
           return `Grid: ${cols} cols × ${rows} rows | Selected: row ${pos.row}, col ${pos.col} | Terminal: ${terminalWidth}w`
         })()}

src/hooks/useNavigation.ts

@@ -1,60 +1,59 @@
 import { useMemo } from 'react';
 
-export default function useNavigation(terminalWidth: number, totalItems: number) {
-  const cardWidth = 35 + 2; // Card width + gap
-  const cardsPerRow = Math.max(1, Math.floor(terminalWidth / cardWidth));
+export default function useNavigation(navigationRows: number[][]) {
+  const indexToPosition = useMemo(() => {
+    const map = new Map<number, { row: number; col: number }>();
+    navigationRows.forEach((rowItems, row) => {
+      rowItems.forEach((itemIndex, col) => {
+        map.set(itemIndex, { row, col });
+      });
+    });
+    return map;
+  }, [navigationRows]);
 
   const getCardGridPosition = useMemo(() => {
     return (index: number): { row: number; col: number } => {
-      const row = Math.floor(index / cardsPerRow);
-      const col = index % cardsPerRow;
-      return { row, col };
+      return indexToPosition.get(index) || { row: 0, col: 0 };
     };
-  }, [cardsPerRow]);
+  }, [indexToPosition]);
 
   const findCardInDirection = useMemo(() => {
     return (currentIndex: number, direction: 'up' | 'down' | 'left' | 'right'): number | null => {
-      const currentPos = getCardGridPosition(currentIndex);
-      let targetIndex: number | null = null;
+      const currentPos = indexToPosition.get(currentIndex);
+      if (!currentPos) return null;
 
       switch (direction) {
         case 'up':
-          if (currentPos.row > 0) {
-            targetIndex = (currentPos.row - 1) * cardsPerRow + currentPos.col;
-            if (targetIndex >= totalItems) {
-              targetIndex = Math.min((currentPos.row - 1) * cardsPerRow + cardsPerRow - 1, totalItems - 1);
-            }
+          if (currentPos.row > 0 && navigationRows[currentPos.row - 1]) {
+            const targetRow = navigationRows[currentPos.row - 1];
+            const targetCol = Math.min(currentPos.col, targetRow.length - 1);
+            return targetRow[targetCol] ?? null;
           }
           break;
         case 'down':
-          targetIndex = (currentPos.row + 1) * cardsPerRow + currentPos.col;
-          if (targetIndex >= totalItems) {
-            if (currentIndex < totalItems - 1) targetIndex = totalItems - 1; else targetIndex = null;
+          if (currentPos.row < navigationRows.length - 1 && navigationRows[currentPos.row + 1]) {
+            const targetRow = navigationRows[currentPos.row + 1];
+            const targetCol = Math.min(currentPos.col, targetRow.length - 1);
+            return targetRow[targetCol] ?? null;
           }
           break;
         case 'left':
           if (currentPos.col > 0) {
-            targetIndex = currentIndex - 1;
-          } else if (currentPos.row > 0) {
-            targetIndex = currentPos.row * cardsPerRow - 1;
-            if (targetIndex >= totalItems) targetIndex = totalItems - 1;
+            const row = navigationRows[currentPos.row];
+            return row?.[currentPos.col - 1] ?? null;
           }
           break;
         case 'right':
-          if (currentPos.col < cardsPerRow - 1 && currentIndex < totalItems - 1) {
-            targetIndex = currentIndex + 1;
-          } else if ((currentPos.row + 1) * cardsPerRow < totalItems) {
-            targetIndex = (currentPos.row + 1) * cardsPerRow;
+          if (navigationRows[currentPos.row] && currentPos.col < navigationRows[currentPos.row].length - 1) {
+            const row = navigationRows[currentPos.row];
+            return row?.[currentPos.col + 1] ?? null;
           }
           break;
       }
 
-      if (targetIndex !== null && targetIndex >= 0 && targetIndex < totalItems) {
-        return targetIndex;
-      }
       return null;
     };
-  }, [cardsPerRow, totalItems, getCardGridPosition]);
+  }, [indexToPosition, navigationRows]);
 
   return { getCardGridPosition, findCardInDirection };
 }

src/utils/projectActions.ts

@@ -94,3 +94,58 @@ export function getProjectActionByIndex(
 ): ProjectActionItem | undefined {
   return actionItems.find((item) => item.index === index);
 }
+
+/**
+ * Build visual navigation rows in rendered order.
+ *
+ * Each inner array represents one visible row of selectable cards/buttons.
+ * This is the canonical source for arrow-key navigation.
+ */
+export function buildVisualNavigationRows(
+  layout: ProjectActionLayout
+): number[][] {
+  const rows: number[][] = [];
+  const actionByProject = new Map<
+    string,
+    { newAgent?: ProjectActionItem; terminal?: ProjectActionItem }
+  >();
+
+  for (const action of layout.actionItems) {
+    const entry = actionByProject.get(action.projectRoot) || {};
+    if (action.kind === 'new-agent') {
+      entry.newAgent = action;
+    } else {
+      entry.terminal = action;
+    }
+    actionByProject.set(action.projectRoot, entry);
+  }
+
+  if (!layout.multiProjectMode) {
+    for (const group of layout.groups) {
+      for (const entry of group.panes) {
+        rows.push([entry.index]);
+      }
+    }
+
+    const first = layout.actionItems[0];
+    const second = layout.actionItems[1];
+    if (first && second) {
+      rows.push([first.index, second.index]);
+    }
+
+    return rows;
+  }
+
+  for (const group of layout.groups) {
+    for (const entry of group.panes) {
+      rows.push([entry.index]);
+    }
+
+    const actions = actionByProject.get(group.projectRoot);
+    if (actions?.newAgent && actions.terminal) {
+      rows.push([actions.newAgent.index, actions.terminal.index]);
+    }
+  }
+
+  return rows;
+}