# apps/web/src/hooks
dir: apps/web/src/hooks

index: apps/web/src/hooks/.pi-map.index.md

## role
A collection of custom React hooks that encapsulate domain-specific business logic, API interactions, and UI state management for a cloud workspace/terminal IDE web application.
## files
- use-async-data.ts | A custom React hook that manages asynchronous data fetching with loading, error, and success states. | exp: func:useAsyncData(fetcher: () => Promise<T>, deps: React.DependencyList) → UseAsyncDataResult<T>, call:useState, call:useCallback, call:setStatus, call:setError, call:fetcher, call:setData, call:load, call:useEffect | dep: react
- use-auto-hide.ts | React hook that automatically hides UI elements after a period of inactivity, with manual controls to show/hide/toggle visibility. | exp: func:useAutoHide(options: AutoHideOptions), call:useState, call:useRef, call:Date.now, call:useCallback, call:setIsVisible, call:clearTimeout, call:setTimeout, call:hide, call:show, call:useEffect | dep: react
- use-config-profiles.ts | React custom hook for managing configuration profiles with CRUD operations, profile inclusion with cycle detection, drag-and-drop reordering, and form state management. | exp: useConfigProfiles | dep: react, ../utils/errors, ../api/config-profiles, ../api/projects, ../api/tool-types, ../types
- use-events.test.ts | Tests a React hook that manages Server-Sent Events (SSE) connections with automatic reconnection, backoff, and error handling | dep: vitest, @testing-library/react, ./use-events, ../api/events, use-events hook, ../api/events module
- use-events.ts | Manages a Server-Sent Events (SSE) connection with exponential backoff reconnection, lifecycle event listening, and authentication redirect handling in a React hook. | exp: UseEventsReturn, func:useEvents() → UseEventsReturn, call:useState, call:useRef, call:useCallback, call:clearTimeout, call:createEventSource, call:setConnected, call:setError, call:setReconnectCount, call:JSON.parse, call:setEvents, call:es.addEventListener, call:es.close, call:Math.min, call:Math.pow, call:Math.random, call:setTimeout, call:probeEventStreamStatus, call:window.location.assign, call:connect, call:useEffect, call:esRef.current.close | dep: react, ../api/events, ../types/events
- use-git-repo.ts | A React custom hook that centralizes git repository operations including branch management, status tracking, commit history, and remote actions for a given project/repo ID pair. | exp: GitStatus, UseGitRepoResult, func:useGitRepo(projectId: string | undefined, repoId: string | undefined) → UseGitRepoResult, call:useState, call:useCallback, call:setLoading, call:setError, call:fn, call:extractError, call:withLoading, call:listRepositoryBranches, call:setBranches, call:data.branches.map, call:setDefaultBranch, call:getRepositoryStatus, call:setStatus, call:getRepositoryHistory, call:setHistory, call:getCommitDetail, call:setCommitDetail, call:commitChanges, call:refreshStatus, call:pushRepository, call:pullRepository, call:fetchRepository, call:checkoutBranch, call:refreshBranches, call:createBranch, call:deleteBranch, call:mergeBranches, call:refreshHistory, call:useEffect, raise:err | dep: react, ../api/git-repositories
- use-instance-actions.ts | A React custom hook that manages instance actions (start, stop, delete, rename, recreate tunnel, open) with loading states and dirty delete handling. | exp: func:useInstanceActions(options: UseInstanceActionsOptions) → UseInstanceActionsReturn, call:useSessions, call:useState, call:useCallback, call:openSession, call:setLoadingSessionId, call:startInstance, call:onRefresh, call:stopInstance, call:deleteInstance, call:setDirtyDeleteSession, call:setDirtyDeleteFiles, call:removeSession, call:recreateInstanceTunnel, call:alert, call:newName.trim, call:renameInstance | dep: react, ../api/sessions, ../state/sessions, ../utils/open-session
- use-mobile-viewport.ts | Custom React hook that returns a boolean indicating whether the viewport width is below a mobile breakpoint (768px) | exp: func:useMobileViewport(), call:useState, call:useEffect, call:setIsMobile, call:window.addEventListener, call:window.removeEventListener | dep: react
- use-notifications.test.tsx | Tests a React hook for managing notifications with optimistic updates, polling, and error handling. | dep: vitest, @testing-library/react, ./use-notifications, ../state/notifications, ../api/notifications, use-notifications, NotificationProvider, notifications API
- use-notifications.ts | Custom React hook that provides access to notification context with runtime validation that it's used within a provider | exp: func:useNotifications(), call:useContext, raise:Error | dep: react, ../state/notifications
- use-projects.ts | Custom React hook that manages project CRUD operations, workspace synchronization, and UI state for a project management interface | exp: useProjects | dep: react, ../api/projects, ../api/workspaces, ./use-async-data, ../types
- use-special-keys.ts | Provides ANSI escape sequences and modifier key mappings for terminal special key handling in a React hook or terminal emulator. | exp: SpecialKey, ModifierKey, func:getSequenceWithModifier(key: SpecialKey, activeModifier: ModifierKey | null) → { sequence: string; clearModifier: boolean } | null, call:char.toLowerCase, func:applyModifierToChar(char: string, modifier: ModifierKey) → string | null, call:char.toLowerCase
- use-ssh-keys.ts | React custom hook that manages SSH key CRUD operations, cryptographic signing/verification, and clipboard functionality with async state handling. | exp: useSSHKeys | dep: react, ../api/ssh-keys, ./use-async-data
- use-start-tool.ts | React hook that manages the state and API calls for creating and starting a tool instance on a workspace. | exp: UseStartToolResult, func:useStartTool() → UseStartToolResult, call:useState, call:useCallback, call:setStarting, call:setError, call:createInstance, call:startInstance | dep: react, ../api/sessions, ../types/workspace
- use-terminal-page.ts | Custom React hook that orchestrates terminal page state, session management, keyboard shortcuts, mobile UX, and fullscreen behavior for a multi-session terminal interface. | exp: useTerminalPage | dep: react, react-router-dom, ../components/features/terminal/terminal, ../components/features/terminal/terminal-session-tabs, ./use-mobile-viewport, ./use-auto-hide, ./use-virtual-keyboard, ./use-terminal-sessions, ../api/terminal, ./use-special-keys, use-mobile-viewport, use-auto-hide, use-virtual-keyboard, use-terminal-sessions, use-special-keys, terminal, terminal-session-tabs, sessions API
- use-terminal-sessions.ts | Custom React hook that manages terminal session state (CRUD operations, active session tracking, loading/error handling) for a given instance. | exp: UseTerminalSessionsResult, func:useTerminalSessions(instanceId: string) → UseTerminalSessionsResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listTerminalSessions, call:setSessions, call:setActiveSessionId, call:createTerminalSession, call:closeTerminalSession, call:prev.filter, call:renameTerminalSession, call:prev.map, call:resetTerminalSession, call:loadSessions, call:useEffect | dep: react, ../api/terminal
- use-theme.ts | React hook that fetches user theme preference on mount and applies it to the document root element | exp: func:useTheme(), call:useEffect, call:getUserConfig, call:document.documentElement.removeAttribute, call:document.documentElement.setAttribute | dep: react, ../api/settings
- use-tool-workshop.ts | A React custom hook that manages state and operations for a tool workshop UI, including CRUD operations for tool types and tool definitions with form handling and validation. | exp: useToolWorkshop | dep: react, ../utils/errors, ../api/tool-types, ../api/tool-definitions, ../components/features/tool-workshop/ToolTypeEditorPanel
- use-virtual-keyboard.ts | A React hook that detects and tracks virtual keyboard state (open/closed, height, viewport height) on mobile devices using Visual Viewport API with fallback for older browsers. | exp: func:useVirtualKeyboard(), call:useState, call:useCallback, call:setState, call:useEffect, call:visualViewport.addEventListener, call:window.addEventListener, call:updateKeyboardState, call:visualViewport.removeEventListener, call:window.removeEventListener | dep: react
- use-workspace-actions.ts | Provides a React hook that wraps workspace CRUD API operations with loading state management and user confirmation dialogs for destructive/conflicting actions. | exp: UseWorkspaceActionsResult, func:useWorkspaceActions() → UseWorkspaceActionsResult, call:useState, call:useCallback, call:createWorkspace, call:setLoadingId, call:deleteWorkspace, call:onRefresh, call:window.confirm, call:instances.map((i) => `- ${i.name}`).join, call:syncWorkspace, call:updateWorkspace, raise:err | dep: react, ../api/workspaces, ../types/workspace
- use-workspace-files.ts | React custom hook that manages workspace file operations including listing, loading, saving, and navigating files. | exp: UseWorkspaceFilesResult, func:useWorkspaceFiles(workspaceId: string) → UseWorkspaceFilesResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listWorkspaceFiles, call:setEntries, call:setCurrentPath, call:setContent, call:getWorkspaceFileContent, call:saveWorkspaceFile, call:refresh, call:useEffect | dep: react, ../api/workspace-files
- use-workspace-git.ts | Provides a React custom hook that encapsulates workspace Git operations including status, branches, history, and actions like commit/push/pull/checkout. | exp: UseWorkspaceGitResult, func:useWorkspaceGit(workspaceId: string) → UseWorkspaceGitResult, call:useState, call:useCallback, call:setLoading, call:setError, call:Promise.all, call:getGitStatus, call:getGitBranches, call:getGitHistory, call:setStatus, call:setBranches, call:setCurrentBranch, call:setHistory, call:gitCommit, call:refresh, call:gitPush, call:gitPull, call:gitFetch, call:gitCheckout, call:useEffect | dep: react, ../api/workspace-git
- use-workspace-instances.ts | React hook that manages workspace instance state with CRUD operations for listing, refreshing, and creating tool instances within a workspace. | exp: UseWorkspaceInstancesResult, func:useWorkspaceInstances(workspaceId: string) → UseWorkspaceInstancesResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listWorkspaceInstances, call:setInstances, call:createWorkspaceInstance, call:refresh, call:useEffect | dep: react, ../api/workspace-instances, ../api/sessions
- use-workspaces.ts | Custom React hook that fetches and manages workspace data with loading and error states | exp: UseWorkspacesResult, func:useWorkspaces(projectId: string, repoId: string) → UseWorkspacesResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listWorkspaces, call:listAllWorkspaces, call:setWorkspaces, call:useEffect, call:refresh | dep: react, ../api/workspaces, ../types/workspace
## arch
Layered custom hook architecture following React patterns—composing useState/useEffect for async operations, context integration, optimistic updates, polling, and mobile-responsive behaviors; each hook typically isolates a single domain concern (workspaces, terminals, git, notifications, etc.) with consistent loading/error state patterns.
## tags
call:set, call:use, workspace, react, state, terminal, api, callback
## symbols
- useAsyncData
- useAutoHide
- useEvents
- useGitRepo
- useInstanceActions
- useMobileViewport
- useNotifications
- getSequenceWithModifier
## workflows
- change hooks behavior
  read: use-async-data.ts, use-auto-hide.ts, use-config-profiles.ts
- update hooks tests
  read: use-events.test.ts, use-notifications.test.tsx
- change hooks config
  read: use-config-profiles.ts
## dirty
-
