Merge main into kanban-scaling

Resolves merge conflicts while preserving:
- Kanban scaling improvements (window sizing, bounce prevention, debouncing)
- Main's sidebar refactoring into hooks
- Main's openInEditor functionality for VS Code integration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

apps/ui/src/components/layout/sidebar/hooks/index.ts

@@ -0,0 +1,12 @@
+export { useThemePreview } from './use-theme-preview';
+export { useSidebarAutoCollapse } from './use-sidebar-auto-collapse';
+export { useDragAndDrop } from './use-drag-and-drop';
+export { useRunningAgents } from './use-running-agents';
+export { useTrashOperations } from './use-trash-operations';
+export { useProjectPicker } from './use-project-picker';
+export { useSpecRegeneration } from './use-spec-regeneration';
+export { useNavigation } from './use-navigation';
+export { useProjectCreation } from './use-project-creation';
+export { useSetupDialog } from './use-setup-dialog';
+export { useTrashDialog } from './use-trash-dialog';
+export { useProjectTheme } from './use-project-theme';

apps/ui/src/components/layout/sidebar/hooks/use-drag-and-drop.ts

@@ -0,0 +1,41 @@
+import { useCallback } from 'react';
+import { useSensors, useSensor, PointerSensor, type DragEndEvent } from '@dnd-kit/core';
+import type { Project } from '@/lib/electron';
+
+interface UseDragAndDropProps {
+  projects: Project[];
+  reorderProjects: (oldIndex: number, newIndex: number) => void;
+}
+
+export function useDragAndDrop({ projects, reorderProjects }: UseDragAndDropProps) {
+  // Sensors for drag-and-drop
+  const sensors = useSensors(
+    useSensor(PointerSensor, {
+      activationConstraint: {
+        distance: 5, // Small distance to start drag
+      },
+    })
+  );
+
+  // Handle drag end for reordering projects
+  const handleDragEnd = useCallback(
+    (event: DragEndEvent) => {
+      const { active, over } = event;
+
+      if (over && active.id !== over.id) {
+        const oldIndex = projects.findIndex((p) => p.id === active.id);
+        const newIndex = projects.findIndex((p) => p.id === over.id);
+
+        if (oldIndex !== -1 && newIndex !== -1) {
+          reorderProjects(oldIndex, newIndex);
+        }
+      }
+    },
+    [projects, reorderProjects]
+  );
+
+  return {
+    sensors,
+    handleDragEnd,
+  };
+}

apps/ui/src/components/layout/sidebar/hooks/use-navigation.ts

@@ -0,0 +1,211 @@
+import { useMemo } from 'react';
+import type { NavigateOptions } from '@tanstack/react-router';
+import { FileText, LayoutGrid, Bot, BookOpen, UserCircle, Terminal } from 'lucide-react';
+import type { NavSection, NavItem } from '../types';
+import type { KeyboardShortcut } from '@/hooks/use-keyboard-shortcuts';
+import type { Project } from '@/lib/electron';
+
+interface UseNavigationProps {
+  shortcuts: {
+    toggleSidebar: string;
+    openProject: string;
+    projectPicker: string;
+    cyclePrevProject: string;
+    cycleNextProject: string;
+    spec: string;
+    context: string;
+    profiles: string;
+    board: string;
+    agent: string;
+    terminal: string;
+    settings: string;
+  };
+  hideSpecEditor: boolean;
+  hideContext: boolean;
+  hideTerminal: boolean;
+  hideAiProfiles: boolean;
+  currentProject: Project | null;
+  projects: Project[];
+  projectHistory: string[];
+  navigate: (opts: NavigateOptions) => void;
+  toggleSidebar: () => void;
+  handleOpenFolder: () => void;
+  setIsProjectPickerOpen: (value: boolean | ((prev: boolean) => boolean)) => void;
+  cyclePrevProject: () => void;
+  cycleNextProject: () => void;
+}
+
+export function useNavigation({
+  shortcuts,
+  hideSpecEditor,
+  hideContext,
+  hideTerminal,
+  hideAiProfiles,
+  currentProject,
+  projects,
+  projectHistory,
+  navigate,
+  toggleSidebar,
+  handleOpenFolder,
+  setIsProjectPickerOpen,
+  cyclePrevProject,
+  cycleNextProject,
+}: UseNavigationProps) {
+  // Build navigation sections
+  const navSections: NavSection[] = useMemo(() => {
+    const allToolsItems: NavItem[] = [
+      {
+        id: 'spec',
+        label: 'Spec Editor',
+        icon: FileText,
+        shortcut: shortcuts.spec,
+      },
+      {
+        id: 'context',
+        label: 'Context',
+        icon: BookOpen,
+        shortcut: shortcuts.context,
+      },
+      {
+        id: 'profiles',
+        label: 'AI Profiles',
+        icon: UserCircle,
+        shortcut: shortcuts.profiles,
+      },
+    ];
+
+    // Filter out hidden items
+    const visibleToolsItems = allToolsItems.filter((item) => {
+      if (item.id === 'spec' && hideSpecEditor) {
+        return false;
+      }
+      if (item.id === 'context' && hideContext) {
+        return false;
+      }
+      if (item.id === 'profiles' && hideAiProfiles) {
+        return false;
+      }
+      return true;
+    });
+
+    // Build project items - Terminal is conditionally included
+    const projectItems: NavItem[] = [
+      {
+        id: 'board',
+        label: 'Kanban Board',
+        icon: LayoutGrid,
+        shortcut: shortcuts.board,
+      },
+      {
+        id: 'agent',
+        label: 'Agent Runner',
+        icon: Bot,
+        shortcut: shortcuts.agent,
+      },
+    ];
+
+    // Add Terminal to Project section if not hidden
+    if (!hideTerminal) {
+      projectItems.push({
+        id: 'terminal',
+        label: 'Terminal',
+        icon: Terminal,
+        shortcut: shortcuts.terminal,
+      });
+    }
+
+    return [
+      {
+        label: 'Project',
+        items: projectItems,
+      },
+      {
+        label: 'Tools',
+        items: visibleToolsItems,
+      },
+    ];
+  }, [shortcuts, hideSpecEditor, hideContext, hideTerminal, hideAiProfiles]);
+
+  // Build keyboard shortcuts for navigation
+  const navigationShortcuts: KeyboardShortcut[] = useMemo(() => {
+    const shortcutsList: KeyboardShortcut[] = [];
+
+    // Sidebar toggle shortcut - always available
+    shortcutsList.push({
+      key: shortcuts.toggleSidebar,
+      action: () => toggleSidebar(),
+      description: 'Toggle sidebar',
+    });
+
+    // Open project shortcut - opens the folder selection dialog directly
+    shortcutsList.push({
+      key: shortcuts.openProject,
+      action: () => handleOpenFolder(),
+      description: 'Open folder selection dialog',
+    });
+
+    // Project picker shortcut - only when we have projects
+    if (projects.length > 0) {
+      shortcutsList.push({
+        key: shortcuts.projectPicker,
+        action: () => setIsProjectPickerOpen((prev) => !prev),
+        description: 'Toggle project picker',
+      });
+    }
+
+    // Project cycling shortcuts - only when we have project history
+    if (projectHistory.length > 1) {
+      shortcutsList.push({
+        key: shortcuts.cyclePrevProject,
+        action: () => cyclePrevProject(),
+        description: 'Cycle to previous project (MRU)',
+      });
+      shortcutsList.push({
+        key: shortcuts.cycleNextProject,
+        action: () => cycleNextProject(),
+        description: 'Cycle to next project (LRU)',
+      });
+    }
+
+    // Only enable nav shortcuts if there's a current project
+    if (currentProject) {
+      navSections.forEach((section) => {
+        section.items.forEach((item) => {
+          if (item.shortcut) {
+            shortcutsList.push({
+              key: item.shortcut,
+              action: () => navigate({ to: `/${item.id}` as const }),
+              description: `Navigate to ${item.label}`,
+            });
+          }
+        });
+      });
+
+      // Add settings shortcut
+      shortcutsList.push({
+        key: shortcuts.settings,
+        action: () => navigate({ to: '/settings' }),
+        description: 'Navigate to Settings',
+      });
+    }
+
+    return shortcutsList;
+  }, [
+    shortcuts,
+    currentProject,
+    navigate,
+    toggleSidebar,
+    projects.length,
+    handleOpenFolder,
+    projectHistory.length,
+    cyclePrevProject,
+    cycleNextProject,
+    navSections,
+    setIsProjectPickerOpen,
+  ]);
+
+  return {
+    navSections,
+    navigationShortcuts,
+  };
+}

apps/ui/src/components/layout/sidebar/hooks/use-project-creation.ts

@@ -0,0 +1,279 @@
+import { useState, useCallback } from 'react';
+import { getElectronAPI } from '@/lib/electron';
+import { initializeProject } from '@/lib/project-init';
+import { toast } from 'sonner';
+import type { StarterTemplate } from '@/lib/templates';
+import type { ThemeMode } from '@/store/app-store';
+import type { TrashedProject, Project } from '@/lib/electron';
+
+interface UseProjectCreationProps {
+  trashedProjects: TrashedProject[];
+  currentProject: Project | null;
+  globalTheme: ThemeMode;
+  upsertAndSetCurrentProject: (path: string, name: string, theme: ThemeMode) => Project;
+}
+
+export function useProjectCreation({
+  trashedProjects,
+  currentProject,
+  globalTheme,
+  upsertAndSetCurrentProject,
+}: UseProjectCreationProps) {
+  // Modal state
+  const [showNewProjectModal, setShowNewProjectModal] = useState(false);
+  const [isCreatingProject, setIsCreatingProject] = useState(false);
+
+  // Onboarding state
+  const [showOnboardingDialog, setShowOnboardingDialog] = useState(false);
+  const [newProjectName, setNewProjectName] = useState('');
+  const [newProjectPath, setNewProjectPath] = useState('');
+
+  /**
+   * Common logic for all project creation flows
+   */
+  const finalizeProjectCreation = useCallback(
+    async (projectPath: string, projectName: string) => {
+      try {
+        // Initialize .automaker directory structure
+        await initializeProject(projectPath);
+
+        // Write initial app_spec.txt with proper XML structure
+        // Note: Must follow XML format as defined in apps/server/src/lib/app-spec-format.ts
+        const api = getElectronAPI();
+        await api.fs.writeFile(
+          `${projectPath}/.automaker/app_spec.txt`,
+          `<project_specification>
+  <project_name>${projectName}</project_name>
+
+  <overview>
+    Describe your project here. This file will be analyzed by an AI agent
+    to understand your project structure and tech stack.
+  </overview>
+
+  <technology_stack>
+    <!-- The AI agent will fill this in after analyzing your project -->
+  </technology_stack>
+
+  <core_capabilities>
+    <!-- List core features and capabilities -->
+  </core_capabilities>
+
+  <implemented_features>
+    <!-- The AI agent will populate this based on code analysis -->
+  </implemented_features>
+</project_specification>`
+        );
+
+        // Determine theme: try trashed project theme, then current project theme, then global
+        const trashedProject = trashedProjects.find((p) => p.path === projectPath);
+        const effectiveTheme =
+          (trashedProject?.theme as ThemeMode | undefined) ||
+          (currentProject?.theme as ThemeMode | undefined) ||
+          globalTheme;
+
+        upsertAndSetCurrentProject(projectPath, projectName, effectiveTheme);
+
+        setShowNewProjectModal(false);
+
+        // Show onboarding dialog for new project
+        setNewProjectName(projectName);
+        setNewProjectPath(projectPath);
+        setShowOnboardingDialog(true);
+
+        toast.success('Project created successfully');
+      } catch (error) {
+        console.error('[ProjectCreation] Failed to finalize project:', error);
+        toast.error('Failed to initialize project', {
+          description: error instanceof Error ? error.message : 'Unknown error',
+        });
+        throw error;
+      }
+    },
+    [trashedProjects, currentProject, globalTheme, upsertAndSetCurrentProject]
+  );
+
+  /**
+   * Create a blank project with .automaker structure
+   */
+  const handleCreateBlankProject = useCallback(
+    async (projectName: string, parentDir: string) => {
+      setIsCreatingProject(true);
+      try {
+        const api = getElectronAPI();
+        const projectPath = `${parentDir}/${projectName}`;
+
+        // Create project directory
+        await api.fs.createFolder(projectPath);
+
+        // Finalize project setup
+        await finalizeProjectCreation(projectPath, projectName);
+      } catch (error) {
+        console.error('[ProjectCreation] Failed to create blank project:', error);
+        toast.error('Failed to create project', {
+          description: error instanceof Error ? error.message : 'Unknown error',
+        });
+      } finally {
+        setIsCreatingProject(false);
+      }
+    },
+    [finalizeProjectCreation]
+  );
+
+  /**
+   * Create project from a starter template
+   */
+  const handleCreateFromTemplate = useCallback(
+    async (template: StarterTemplate, projectName: string, parentDir: string) => {
+      setIsCreatingProject(true);
+      try {
+        const api = getElectronAPI();
+        const projectPath = `${parentDir}/${projectName}`;
+
+        // Clone template repository
+        await api.git.clone(template.githubUrl, projectPath);
+
+        // Initialize .automaker directory structure
+        await initializeProject(projectPath);
+
+        // Write app_spec.txt with template-specific info
+        await api.fs.writeFile(
+          `${projectPath}/.automaker/app_spec.txt`,
+          `<project_specification>
+  <project_name>${projectName}</project_name>
+
+  <overview>
+    This project was created from the "${template.name}" starter template.
+    ${template.description}
+  </overview>
+
+  <technology_stack>
+    ${template.techStack.map((tech) => `<technology>${tech}</technology>`).join('\n    ')}
+  </technology_stack>
+
+  <core_capabilities>
+    ${template.features.map((feature) => `<capability>${feature}</capability>`).join('\n    ')}
+  </core_capabilities>
+
+  <implemented_features>
+    <!-- The AI agent will populate this based on code analysis -->
+  </implemented_features>
+</project_specification>`
+        );
+
+        // Determine theme
+        const trashedProject = trashedProjects.find((p) => p.path === projectPath);
+        const effectiveTheme =
+          (trashedProject?.theme as ThemeMode | undefined) ||
+          (currentProject?.theme as ThemeMode | undefined) ||
+          globalTheme;
+
+        upsertAndSetCurrentProject(projectPath, projectName, effectiveTheme);
+        setShowNewProjectModal(false);
+        setNewProjectName(projectName);
+        setNewProjectPath(projectPath);
+        setShowOnboardingDialog(true);
+
+        toast.success('Project created from template', {
+          description: `Created ${projectName} from ${template.name}`,
+        });
+      } catch (error) {
+        console.error('[ProjectCreation] Failed to create from template:', error);
+        toast.error('Failed to create project from template', {
+          description: error instanceof Error ? error.message : 'Unknown error',
+        });
+      } finally {
+        setIsCreatingProject(false);
+      }
+    },
+    [trashedProjects, currentProject, globalTheme, upsertAndSetCurrentProject]
+  );
+
+  /**
+   * Create project from a custom GitHub URL
+   */
+  const handleCreateFromCustomUrl = useCallback(
+    async (repoUrl: string, projectName: string, parentDir: string) => {
+      setIsCreatingProject(true);
+      try {
+        const api = getElectronAPI();
+        const projectPath = `${parentDir}/${projectName}`;
+
+        // Clone custom repository
+        await api.git.clone(repoUrl, projectPath);
+
+        // Initialize .automaker directory structure
+        await initializeProject(projectPath);
+
+        // Write app_spec.txt with custom URL info
+        await api.fs.writeFile(
+          `${projectPath}/.automaker/app_spec.txt`,
+          `<project_specification>
+  <project_name>${projectName}</project_name>
+
+  <overview>
+    This project was cloned from ${repoUrl}.
+    The AI agent will analyze the project structure.
+  </overview>
+
+  <technology_stack>
+    <!-- The AI agent will fill this in after analyzing your project -->
+  </technology_stack>
+
+  <core_capabilities>
+    <!-- List core features and capabilities -->
+  </core_capabilities>
+
+  <implemented_features>
+    <!-- The AI agent will populate this based on code analysis -->
+  </implemented_features>
+</project_specification>`
+        );
+
+        // Determine theme
+        const trashedProject = trashedProjects.find((p) => p.path === projectPath);
+        const effectiveTheme =
+          (trashedProject?.theme as ThemeMode | undefined) ||
+          (currentProject?.theme as ThemeMode | undefined) ||
+          globalTheme;
+
+        upsertAndSetCurrentProject(projectPath, projectName, effectiveTheme);
+        setShowNewProjectModal(false);
+        setNewProjectName(projectName);
+        setNewProjectPath(projectPath);
+        setShowOnboardingDialog(true);
+
+        toast.success('Project created from repository', {
+          description: `Created ${projectName} from ${repoUrl}`,
+        });
+      } catch (error) {
+        console.error('[ProjectCreation] Failed to create from custom URL:', error);
+        toast.error('Failed to create project from URL', {
+          description: error instanceof Error ? error.message : 'Unknown error',
+        });
+      } finally {
+        setIsCreatingProject(false);
+      }
+    },
+    [trashedProjects, currentProject, globalTheme, upsertAndSetCurrentProject]
+  );
+
+  return {
+    // Modal state
+    showNewProjectModal,
+    setShowNewProjectModal,
+    isCreatingProject,
+
+    // Onboarding state
+    showOnboardingDialog,
+    setShowOnboardingDialog,
+    newProjectName,
+    setNewProjectName,
+    newProjectPath,
+    setNewProjectPath,
+
+    // Handlers
+    handleCreateBlankProject,
+    handleCreateFromTemplate,
+    handleCreateFromCustomUrl,
+  };
+}

apps/ui/src/components/layout/sidebar/hooks/use-project-picker.ts

@@ -0,0 +1,105 @@
+import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
+import type { Project } from '@/lib/electron';
+
+interface UseProjectPickerProps {
+  projects: Project[];
+  isProjectPickerOpen: boolean;
+  setIsProjectPickerOpen: (value: boolean | ((prev: boolean) => boolean)) => void;
+  setCurrentProject: (project: Project) => void;
+}
+
+export function useProjectPicker({
+  projects,
+  isProjectPickerOpen,
+  setIsProjectPickerOpen,
+  setCurrentProject,
+}: UseProjectPickerProps) {
+  const [projectSearchQuery, setProjectSearchQuery] = useState('');
+  const [selectedProjectIndex, setSelectedProjectIndex] = useState(0);
+  const projectSearchInputRef = useRef<HTMLInputElement>(null);
+
+  // Filtered projects based on search query
+  const filteredProjects = useMemo(() => {
+    if (!projectSearchQuery.trim()) {
+      return projects;
+    }
+    const query = projectSearchQuery.toLowerCase();
+    return projects.filter((project) => project.name.toLowerCase().includes(query));
+  }, [projects, projectSearchQuery]);
+
+  // Reset selection when filtered results change
+  useEffect(() => {
+    setSelectedProjectIndex(0);
+  }, [filteredProjects.length, projectSearchQuery]);
+
+  // Reset search query when dropdown closes
+  useEffect(() => {
+    if (!isProjectPickerOpen) {
+      setProjectSearchQuery('');
+      setSelectedProjectIndex(0);
+    }
+  }, [isProjectPickerOpen]);
+
+  // Focus the search input when dropdown opens
+  useEffect(() => {
+    if (isProjectPickerOpen) {
+      // Small delay to ensure the dropdown is rendered
+      setTimeout(() => {
+        projectSearchInputRef.current?.focus();
+      }, 0);
+    }
+  }, [isProjectPickerOpen]);
+
+  // Handle selecting the currently highlighted project
+  const selectHighlightedProject = useCallback(() => {
+    if (filteredProjects.length > 0 && selectedProjectIndex < filteredProjects.length) {
+      setCurrentProject(filteredProjects[selectedProjectIndex]);
+      setIsProjectPickerOpen(false);
+    }
+  }, [filteredProjects, selectedProjectIndex, setCurrentProject, setIsProjectPickerOpen]);
+
+  // Handle keyboard events when project picker is open
+  useEffect(() => {
+    if (!isProjectPickerOpen) return;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        setIsProjectPickerOpen(false);
+      } else if (event.key === 'Enter') {
+        event.preventDefault();
+        selectHighlightedProject();
+      } else if (event.key === 'ArrowDown') {
+        event.preventDefault();
+        setSelectedProjectIndex((prev) => (prev < filteredProjects.length - 1 ? prev + 1 : prev));
+      } else if (event.key === 'ArrowUp') {
+        event.preventDefault();
+        setSelectedProjectIndex((prev) => (prev > 0 ? prev - 1 : prev));
+      } else if (event.key.toLowerCase() === 'p' && !event.metaKey && !event.ctrlKey) {
+        // Toggle off when P is pressed (not with modifiers) while dropdown is open
+        // Only if not typing in the search input
+        if (document.activeElement !== projectSearchInputRef.current) {
+          event.preventDefault();
+          setIsProjectPickerOpen(false);
+        }
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [
+    isProjectPickerOpen,
+    selectHighlightedProject,
+    filteredProjects.length,
+    setIsProjectPickerOpen,
+  ]);
+
+  return {
+    projectSearchQuery,
+    setProjectSearchQuery,
+    selectedProjectIndex,
+    setSelectedProjectIndex,
+    projectSearchInputRef,
+    filteredProjects,
+    selectHighlightedProject,
+  };
+}

apps/ui/src/components/layout/sidebar/hooks/use-project-theme.ts

@@ -0,0 +1,25 @@
+import { useAppStore } from '@/store/app-store';
+import { useThemePreview } from './use-theme-preview';
+
+/**
+ * Hook that manages project theme state and preview handlers
+ */
+export function useProjectTheme() {
+  // Get theme-related values from store
+  const { theme: globalTheme, setTheme, setProjectTheme, setPreviewTheme } = useAppStore();
+
+  // Get debounced preview handlers
+  const { handlePreviewEnter, handlePreviewLeave } = useThemePreview({ setPreviewTheme });
+
+  return {
+    // Theme state
+    globalTheme,
+    setTheme,
+    setProjectTheme,
+    setPreviewTheme,
+
+    // Preview handlers
+    handlePreviewEnter,
+    handlePreviewLeave,
+  };
+}

apps/ui/src/components/layout/sidebar/hooks/use-running-agents.ts

@@ -0,0 +1,53 @@
+import { useState, useEffect, useCallback } from 'react';
+import { getElectronAPI } from '@/lib/electron';
+
+export function useRunningAgents() {
+  const [runningAgentsCount, setRunningAgentsCount] = useState(0);
+
+  // Fetch running agents count function - used for initial load and event-driven updates
+  const fetchRunningAgentsCount = useCallback(async () => {
+    try {
+      const api = getElectronAPI();
+      if (api.runningAgents) {
+        const result = await api.runningAgents.getAll();
+        if (result.success && result.runningAgents) {
+          setRunningAgentsCount(result.runningAgents.length);
+        }
+      }
+    } catch (error) {
+      console.error('[Sidebar] Error fetching running agents count:', error);
+    }
+  }, []);
+
+  // Subscribe to auto-mode events to update running agents count in real-time
+  useEffect(() => {
+    const api = getElectronAPI();
+    if (!api.autoMode) {
+      // If autoMode is not available, still fetch initial count
+      fetchRunningAgentsCount();
+      return;
+    }
+
+    // Initial fetch on mount
+    fetchRunningAgentsCount();
+
+    const unsubscribe = api.autoMode.onEvent((event) => {
+      // When a feature starts, completes, or errors, refresh the count
+      if (
+        event.type === 'auto_mode_feature_complete' ||
+        event.type === 'auto_mode_error' ||
+        event.type === 'auto_mode_feature_start'
+      ) {
+        fetchRunningAgentsCount();
+      }
+    });
+
+    return () => {
+      unsubscribe();
+    };
+  }, [fetchRunningAgentsCount]);
+
+  return {
+    runningAgentsCount,
+  };
+}

apps/ui/src/components/layout/sidebar/hooks/use-setup-dialog.ts

@@ -0,0 +1,147 @@
+import { useState, useCallback } from 'react';
+import { getElectronAPI } from '@/lib/electron';
+import { toast } from 'sonner';
+import type { FeatureCount } from '@/components/views/spec-view/types';
+
+interface UseSetupDialogProps {
+  setSpecCreatingForProject: (path: string | null) => void;
+  newProjectPath: string;
+  setNewProjectName: (name: string) => void;
+  setNewProjectPath: (path: string) => void;
+  setShowOnboardingDialog: (show: boolean) => void;
+}
+
+export function useSetupDialog({
+  setSpecCreatingForProject,
+  newProjectPath,
+  setNewProjectName,
+  setNewProjectPath,
+  setShowOnboardingDialog,
+}: UseSetupDialogProps) {
+  // Setup dialog state
+  const [showSetupDialog, setShowSetupDialog] = useState(false);
+  const [setupProjectPath, setSetupProjectPath] = useState('');
+  const [projectOverview, setProjectOverview] = useState('');
+  const [generateFeatures, setGenerateFeatures] = useState(true);
+  const [analyzeProject, setAnalyzeProject] = useState(true);
+  const [featureCount, setFeatureCount] = useState<FeatureCount>(50);
+
+  /**
+   * Handle creating initial spec for new project
+   */
+  const handleCreateInitialSpec = useCallback(async () => {
+    if (!setupProjectPath || !projectOverview.trim()) return;
+
+    // Set store state immediately so the loader shows up right away
+    setSpecCreatingForProject(setupProjectPath);
+    setShowSetupDialog(false);
+
+    try {
+      const api = getElectronAPI();
+      if (!api.specRegeneration) {
+        toast.error('Spec regeneration not available');
+        setSpecCreatingForProject(null);
+        return;
+      }
+
+      const result = await api.specRegeneration.create(
+        setupProjectPath,
+        projectOverview.trim(),
+        generateFeatures,
+        analyzeProject,
+        generateFeatures ? featureCount : undefined // only pass maxFeatures if generating features
+      );
+
+      if (!result.success) {
+        console.error('[SetupDialog] Failed to start spec creation:', result.error);
+        setSpecCreatingForProject(null);
+        toast.error('Failed to create specification', {
+          description: result.error,
+        });
+      } else {
+        // Show processing toast to inform user
+        toast.info('Generating app specification...', {
+          description: "This may take a minute. You'll be notified when complete.",
+        });
+      }
+      // If successful, we'll wait for the events to update the state
+    } catch (error) {
+      console.error('[SetupDialog] Failed to create spec:', error);
+      setSpecCreatingForProject(null);
+      toast.error('Failed to create specification', {
+        description: error instanceof Error ? error.message : 'Unknown error',
+      });
+    }
+  }, [
+    setupProjectPath,
+    projectOverview,
+    generateFeatures,
+    analyzeProject,
+    featureCount,
+    setSpecCreatingForProject,
+  ]);
+
+  /**
+   * Handle skipping setup
+   */
+  const handleSkipSetup = useCallback(() => {
+    setShowSetupDialog(false);
+    setProjectOverview('');
+    setSetupProjectPath('');
+
+    // Clear onboarding state if we came from onboarding
+    if (newProjectPath) {
+      setNewProjectName('');
+      setNewProjectPath('');
+    }
+
+    toast.info('Setup skipped', {
+      description: 'You can set up your app_spec.txt later from the Spec view.',
+    });
+  }, [newProjectPath, setNewProjectName, setNewProjectPath]);
+
+  /**
+   * Handle onboarding dialog - generate spec
+   */
+  const handleOnboardingGenerateSpec = useCallback(() => {
+    setShowOnboardingDialog(false);
+    // Navigate to the setup dialog flow
+    setSetupProjectPath(newProjectPath);
+    setProjectOverview('');
+    setShowSetupDialog(true);
+  }, [newProjectPath, setShowOnboardingDialog]);
+
+  /**
+   * Handle onboarding dialog - skip
+   */
+  const handleOnboardingSkip = useCallback(() => {
+    setShowOnboardingDialog(false);
+    setNewProjectName('');
+    setNewProjectPath('');
+    toast.info('You can generate your app_spec.txt anytime from the Spec view', {
+      description: 'Your project is ready to use!',
+    });
+  }, [setShowOnboardingDialog, setNewProjectName, setNewProjectPath]);
+
+  return {
+    // State
+    showSetupDialog,
+    setShowSetupDialog,
+    setupProjectPath,
+    setSetupProjectPath,
+    projectOverview,
+    setProjectOverview,
+    generateFeatures,
+    setGenerateFeatures,
+    analyzeProject,
+    setAnalyzeProject,
+    featureCount,
+    setFeatureCount,
+
+    // Handlers
+    handleCreateInitialSpec,
+    handleSkipSetup,
+    handleOnboardingGenerateSpec,
+    handleOnboardingSkip,
+  };
+}

apps/ui/src/components/layout/sidebar/hooks/use-sidebar-auto-collapse.ts

@@ -0,0 +1,48 @@
+import { useEffect, useRef } from 'react';
+
+interface UseSidebarAutoCollapseProps {
+  sidebarOpen: boolean;
+  toggleSidebar: () => void;
+}
+
+export function useSidebarAutoCollapse({
+  sidebarOpen,
+  toggleSidebar,
+}: UseSidebarAutoCollapseProps) {
+  const isMountedRef = useRef(false);
+
+  // Auto-collapse sidebar on small screens
+  useEffect(() => {
+    const mediaQuery = window.matchMedia('(max-width: 1024px)'); // lg breakpoint
+
+    const handleResize = () => {
+      if (mediaQuery.matches && sidebarOpen) {
+        // Auto-collapse on small screens
+        toggleSidebar();
+      }
+    };
+
+    // Check on mount only
+    if (!isMountedRef.current) {
+      isMountedRef.current = true;
+      handleResize();
+    }
+
+    // Listen for changes
+    mediaQuery.addEventListener('change', handleResize);
+    return () => mediaQuery.removeEventListener('change', handleResize);
+  }, [sidebarOpen, toggleSidebar]);
+
+  // Update Electron window minWidth when sidebar state changes
+  // This ensures the window can't be resized smaller than what the kanban board needs
+  useEffect(() => {
+    const electronAPI = (
+      window as unknown as {
+        electronAPI?: { updateMinWidth?: (expanded: boolean) => Promise<void> };
+      }
+    ).electronAPI;
+    if (electronAPI?.updateMinWidth) {
+      electronAPI.updateMinWidth(sidebarOpen);
+    }
+  }, [sidebarOpen]);
+}

apps/ui/src/components/layout/sidebar/hooks/use-spec-regeneration.ts

@@ -0,0 +1,78 @@
+import { useEffect } from 'react';
+import { toast } from 'sonner';
+import { getElectronAPI } from '@/lib/electron';
+import type { SpecRegenerationEvent } from '@/types/electron';
+
+interface UseSpecRegenerationProps {
+  creatingSpecProjectPath: string | null;
+  setupProjectPath: string;
+  setSpecCreatingForProject: (path: string | null) => void;
+  setShowSetupDialog: (show: boolean) => void;
+  setProjectOverview: (overview: string) => void;
+  setSetupProjectPath: (path: string) => void;
+  setNewProjectName: (name: string) => void;
+  setNewProjectPath: (path: string) => void;
+}
+
+export function useSpecRegeneration({
+  creatingSpecProjectPath,
+  setupProjectPath,
+  setSpecCreatingForProject,
+  setShowSetupDialog,
+  setProjectOverview,
+  setSetupProjectPath,
+  setNewProjectName,
+  setNewProjectPath,
+}: UseSpecRegenerationProps) {
+  // Subscribe to spec regeneration events
+  useEffect(() => {
+    const api = getElectronAPI();
+    if (!api.specRegeneration) return;
+
+    const unsubscribe = api.specRegeneration.onEvent((event: SpecRegenerationEvent) => {
+      console.log(
+        '[Sidebar] Spec regeneration event:',
+        event.type,
+        'for project:',
+        event.projectPath
+      );
+
+      // Only handle events for the project we're currently setting up
+      if (event.projectPath !== creatingSpecProjectPath && event.projectPath !== setupProjectPath) {
+        console.log('[Sidebar] Ignoring event - not for project being set up');
+        return;
+      }
+
+      if (event.type === 'spec_regeneration_complete') {
+        setSpecCreatingForProject(null);
+        setShowSetupDialog(false);
+        setProjectOverview('');
+        setSetupProjectPath('');
+        // Clear onboarding state if we came from onboarding
+        setNewProjectName('');
+        setNewProjectPath('');
+        toast.success('App specification created', {
+          description: 'Your project is now set up and ready to go!',
+        });
+      } else if (event.type === 'spec_regeneration_error') {
+        setSpecCreatingForProject(null);
+        toast.error('Failed to create specification', {
+          description: event.error,
+        });
+      }
+    });
+
+    return () => {
+      unsubscribe();
+    };
+  }, [
+    creatingSpecProjectPath,
+    setupProjectPath,
+    setSpecCreatingForProject,
+    setShowSetupDialog,
+    setProjectOverview,
+    setSetupProjectPath,
+    setNewProjectName,
+    setNewProjectPath,
+  ]);
+}

apps/ui/src/components/layout/sidebar/hooks/use-theme-preview.ts

@@ -0,0 +1,53 @@
+import { useRef, useCallback, useEffect } from 'react';
+import type { ThemeMode } from '@/store/app-store';
+
+interface UseThemePreviewProps {
+  setPreviewTheme: (theme: ThemeMode | null) => void;
+}
+
+export function useThemePreview({ setPreviewTheme }: UseThemePreviewProps) {
+  // Debounced preview theme handlers to prevent excessive re-renders
+  const previewTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const handlePreviewEnter = useCallback(
+    (value: string) => {
+      // Clear any pending timeout
+      if (previewTimeoutRef.current) {
+        clearTimeout(previewTimeoutRef.current);
+      }
+      // Small delay to debounce rapid hover changes
+      previewTimeoutRef.current = setTimeout(() => {
+        setPreviewTheme(value as ThemeMode);
+      }, 16); // ~1 frame delay
+    },
+    [setPreviewTheme]
+  );
+
+  const handlePreviewLeave = useCallback(
+    (e: React.PointerEvent) => {
+      const relatedTarget = e.relatedTarget as HTMLElement;
+      if (!relatedTarget?.closest('[data-testid^="project-theme-"]')) {
+        // Clear any pending timeout
+        if (previewTimeoutRef.current) {
+          clearTimeout(previewTimeoutRef.current);
+        }
+        setPreviewTheme(null);
+      }
+    },
+    [setPreviewTheme]
+  );
+
+  // Cleanup timeout on unmount
+  useEffect(() => {
+    return () => {
+      if (previewTimeoutRef.current) {
+        clearTimeout(previewTimeoutRef.current);
+      }
+    };
+  }, []);
+
+  return {
+    handlePreviewEnter,
+    handlePreviewLeave,
+  };
+}

apps/ui/src/components/layout/sidebar/hooks/use-trash-dialog.ts

@@ -0,0 +1,40 @@
+import { useState } from 'react';
+import { useTrashOperations } from './use-trash-operations';
+import type { TrashedProject } from '@/lib/electron';
+
+interface UseTrashDialogProps {
+  restoreTrashedProject: (projectId: string) => void;
+  deleteTrashedProject: (projectId: string) => void;
+  emptyTrash: () => void;
+  trashedProjects: TrashedProject[];
+}
+
+/**
+ * Hook that combines trash operations with dialog state management
+ */
+export function useTrashDialog({
+  restoreTrashedProject,
+  deleteTrashedProject,
+  emptyTrash,
+  trashedProjects,
+}: UseTrashDialogProps) {
+  // Dialog state
+  const [showTrashDialog, setShowTrashDialog] = useState(false);
+
+  // Reuse existing trash operations logic
+  const trashOperations = useTrashOperations({
+    restoreTrashedProject,
+    deleteTrashedProject,
+    emptyTrash,
+    trashedProjects,
+  });
+
+  return {
+    // Dialog state
+    showTrashDialog,
+    setShowTrashDialog,
+
+    // Trash operations (spread from existing hook)
+    ...trashOperations,
+  };
+}

apps/ui/src/components/layout/sidebar/hooks/use-trash-operations.ts

@@ -0,0 +1,92 @@
+import { useState, useCallback } from 'react';
+import { toast } from 'sonner';
+import { getElectronAPI, type TrashedProject } from '@/lib/electron';
+
+interface UseTrashOperationsProps {
+  restoreTrashedProject: (projectId: string) => void;
+  deleteTrashedProject: (projectId: string) => void;
+  emptyTrash: () => void;
+  trashedProjects: TrashedProject[];
+}
+
+export function useTrashOperations({
+  restoreTrashedProject,
+  deleteTrashedProject,
+  emptyTrash,
+  trashedProjects,
+}: UseTrashOperationsProps) {
+  const [activeTrashId, setActiveTrashId] = useState<string | null>(null);
+  const [isEmptyingTrash, setIsEmptyingTrash] = useState(false);
+
+  const handleRestoreProject = useCallback(
+    (projectId: string) => {
+      restoreTrashedProject(projectId);
+      toast.success('Project restored', {
+        description: 'Added back to your project list.',
+      });
+    },
+    [restoreTrashedProject]
+  );
+
+  const handleDeleteProjectFromDisk = useCallback(
+    async (trashedProject: TrashedProject) => {
+      const confirmed = window.confirm(
+        `Delete "${trashedProject.name}" from disk?\nThis sends the folder to your system Trash.`
+      );
+      if (!confirmed) return;
+
+      setActiveTrashId(trashedProject.id);
+      try {
+        const api = getElectronAPI();
+        if (!api.trashItem) {
+          throw new Error('System Trash is not available in this build.');
+        }
+
+        const result = await api.trashItem(trashedProject.path);
+        if (!result.success) {
+          throw new Error(result.error || 'Failed to delete project folder');
+        }
+
+        deleteTrashedProject(trashedProject.id);
+        toast.success('Project folder sent to system Trash', {
+          description: trashedProject.path,
+        });
+      } catch (error) {
+        console.error('[Sidebar] Failed to delete project from disk:', error);
+        toast.error('Failed to delete project folder', {
+          description: error instanceof Error ? error.message : 'Unknown error',
+        });
+      } finally {
+        setActiveTrashId(null);
+      }
+    },
+    [deleteTrashedProject]
+  );
+
+  const handleEmptyTrash = useCallback(() => {
+    if (trashedProjects.length === 0) {
+      return;
+    }
+
+    const confirmed = window.confirm(
+      'Clear all projects from recycle bin? This does not delete folders from disk.'
+    );
+    if (!confirmed) return;
+
+    setIsEmptyingTrash(true);
+    try {
+      emptyTrash();
+      toast.success('Recycle bin cleared');
+    } finally {
+      setIsEmptyingTrash(false);
+    }
+  }, [emptyTrash, trashedProjects.length]);
+
+  return {
+    activeTrashId,
+    isEmptyingTrash,
+    handleRestoreProject,
+    handleDeleteProjectFromDisk,
+    handleEmptyTrash,
+  };
+}