feat: Implement keyboard navigation for desktop layout items with occlusion and Z-order awareness.

frontend/src/desktop/DesktopWorkspace.tsx

@@ -206,20 +206,125 @@ const DesktopWorkspaceContent: React.FC<DesktopWorkspaceProps> = ({
 
   useEffect(() => {
     const handleWindowKeyDown = (e: KeyboardEvent) => {
+      // Space preview logic
       if (e.code === 'Space' && selectedDocumentIds.length > 0) {
-        // Preview the last selected document
         const lastId = selectedDocumentIds[selectedDocumentIds.length - 1];
         const doc = items.find(i => String(i.id) === lastId);
         if (doc) {
           e.preventDefault();
           openPreview(doc);
+          return;
+        }
+      }
+
+      // Navigation logic
+      if (['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(e.key)) {
+        e.preventDefault();
+
+        const layoutItems = Array.from(layoutStore.items.values()) as LayoutCard[];
+        if (layoutItems.length === 0) return;
+
+        let activeCard = null;
+        if (selectedDocumentIds.length > 0) {
+          // Use the last selected item as the anchor
+          const lastId = selectedDocumentIds[selectedDocumentIds.length - 1];
+          activeCard = layoutStore.items.get(lastId);
+        }
+
+        // If no selection or active card not found, select the top-most item
+        if (!activeCard) {
+          const topMost = layoutItems.reduce((prev, current) => (prev.z > current.z ? prev : current));
+          handleSelectionChange([topMost.id]);
+          return;
+        }
+
+        const cx = activeCard.centerX;
+        const cy = activeCard.centerY;
+
+        let bestCandidate = null;
+        let minScore = Infinity;
+
+        for (const candidate of layoutItems) {
+          if (candidate.id === activeCard.id) continue;
+
+          const dx = candidate.centerX - cx;
+          const dy = candidate.centerY - cy;
+
+          let valid = false;
+          let primaryDist = 0;
+          let offAxisDist = 0;
+
+          switch (e.key) {
+            case 'ArrowRight':
+              if (dx > 0 && dx > Math.abs(dy)) {
+                valid = true;
+                primaryDist = dx;
+                offAxisDist = Math.abs(dy);
+              }
+              break;
+            case 'ArrowLeft':
+              if (dx < 0 && -dx > Math.abs(dy)) {
+                valid = true;
+                primaryDist = -dx;
+                offAxisDist = Math.abs(dy);
+              }
+              break;
+            case 'ArrowDown':
+              if (dy > 0 && dy > Math.abs(dx)) {
+                valid = true;
+                primaryDist = dy;
+                offAxisDist = Math.abs(dx);
+              }
+              break;
+            case 'ArrowUp':
+              if (dy < 0 && -dy > Math.abs(dx)) {
+                valid = true;
+                primaryDist = -dy;
+                offAxisDist = Math.abs(dx);
+              }
+              break;
+          }
+
+          if (valid) {
+            // Weighted score: favor items closer in the primary direction, penalize off-axis
+            // We use a multiplier for off-axis distance to prefer "straighter" lines
+            // Reduced off-axis weight to favor directional distance (grid-like behavior)
+            let score = primaryDist + (offAxisDist * 0.2);
+
+            // Z-Order Bonus: Subtract a small value based on Z-index to favor higher items
+            // Assuming max Z is around 10000, 0.1 gives a max bonus of 1000, which is significant but less than primary distance usually
+            score -= (candidate.z * 0.05);
+
+            // Obstruction Penalty: Check if the candidate is obstructed
+            // If less than 5% is visible, treat as obstructed
+            if (candidate.getVisibleFraction() < 0.05) {
+              score += 5000; // Huge penalty for obstructed items
+            }
+
+            if (score < minScore) {
+              minScore = score;
+              bestCandidate = candidate;
+            }
+          }
+        }
+
+        if (bestCandidate) {
+          if (e.shiftKey) {
+            // Additive selection
+            const newSelection = new Set(selectedDocumentIds);
+            newSelection.add(bestCandidate.id);
+            handleSelectionChange(Array.from(newSelection));
+          } else {
+            // Replace selection
+            handleSelectionChange([bestCandidate.id]);
+          }
         }
       }
     };
 
     window.addEventListener('keydown', handleWindowKeyDown);
     return () => window.removeEventListener('keydown', handleWindowKeyDown);
-  }, [selectedDocumentIds, items, openPreview]);
+  }, [selectedDocumentIds, items, openPreview, layoutStore, handleSelectionChange]);
 
   return (
     <>