waggle-os/docs/production-readiness/03C-UI_QUALITY.md

Phase 3C: UI & Frontend Code Quality Audit

Auditor: Senior Engineer Code Review (automated) Date: 2026-03-20 Scope: app/src/ (Tauri desktop app) + packages/ui/src/ (shared React component library) Mode: READ-ONLY

---

Summary Counts

Metric	Count
Total any type usages	20 (11 in app/src, 9 in packages/ui/src)
Total inline styles	29 (13 in app/src, 16 in packages/ui/src)
Error boundaries	0
Effects without cleanup (where cleanup is needed)	5
React.memo usage	0
React.lazy / code splitting	0
ESLint rule suppressions	5
Dead/orphaned files	5
Duplicate SSE connections	2 (same endpoint)

---

Findings

CQ-001: Zero Error Boundaries

• Severity: CRITICAL
• Package: app + @waggle/ui
• File: app/src/App.tsx (entire tree)
• Issue: No ErrorBoundary or componentDidCatch exists anywhere in the app or UI library. The entire component tree is unwrapped. A single uncaught render error in any view (Chat, Cockpit, Memory, Capabilities, MissionControl, Settings) will crash the entire application to a white screen.
• Impact: In production, any rendering error (bad API response shape, undefined property access in JSX) will take down the whole desktop app. Users lose all context with no recovery path.
• Fix: Add error boundaries at the view level (wrapping each <ChatView>, <CockpitView>, etc.) and at the root level in App(). Each boundary should render a fallback UI with a "Retry" button.

CQ-002: Duplicate SSE Connections to Same Endpoint

• Severity: HIGH
• Package: @waggle/ui
• File: packages/ui/src/hooks/useNotifications.ts:46, packages/ui/src/hooks/useSubAgentStatus.ts:55
• Issue: Both useNotifications and useSubAgentStatus open independent EventSource connections to the exact same endpoint (/api/notifications/stream). This doubles the number of persistent HTTP connections per client.
• Impact: Wastes server resources (2x SSE connections per client). Under load or on constrained networks, this halves available connections. Browser SSE connection limits (6 per domain in some browsers) are consumed faster.
• Fix: Create a single shared SSE connection hook (e.g., useSSEStream) that multiplexes events to multiple subscribers. Both useNotifications and useSubAgentStatus should subscribe to the shared connection.

CQ-003: No Code Splitting or Lazy Loading

• Severity: HIGH
• Package: app
• File: app/src/App.tsx, app/vite.config.ts
• Issue: All 7 views (Chat, Memory, Events, Capabilities, Cockpit, MissionControl, Settings) are eagerly imported. No React.lazy() or Suspense is used anywhere. The Vite config has no manualChunks configuration in rollupOptions. The CapabilitiesView alone is 1227 lines. CockpitView imports 10 sub-components eagerly.
• Impact: The initial bundle includes all views and their dependencies, increasing initial load time. Views like MissionControl and Capabilities that users may rarely visit are loaded upfront.
• Fix: Wrap non-default views with React.lazy() + Suspense. Add manualChunks to vite.config.ts to split vendor code (marked, DOMPurify) from app code. At minimum, lazy-load Capabilities, MissionControl, Cockpit, and Settings views.

CQ-004: Monolithic App Component (~1300 lines, 30+ useState calls)

• Severity: HIGH
• Package: app
• File: app/src/App.tsx:87-1290
• Issue: WaggleApp is a single component with ~30 useState hooks, ~15 useEffect hooks, and ~20 useCallback hooks. It manages team messages, notifications, toasts, agent status, offline status, personas, workspace context, file drops, approval gates, slash commands, keyboard shortcuts, tab management, sessions, memory, events, and more -- all in one function body.
• Impact: Any state change triggers reconciliation of the entire component. Difficult to test individual concerns. High cognitive load for maintenance. Makes it impossible to optimize re-renders without major refactoring.
• Fix: Extract logical domains into custom hooks or sub-providers: useTeamState(), useAgentStatus(), useOfflineStatus(), useSlashCommands(), useFileHandling(). Consider a state management solution (Zustand is lightweight and fits) to share state without prop drilling through the 1300-line component.

CQ-005: Zero React.memo Usage Across Entire Codebase

• Severity: MEDIUM
• Package: app + @waggle/ui
• File: all components
• Issue: Not a single component uses React.memo(). Given the monolithic WaggleApp component, every state change (e.g., toast notification, agent token count update from polling) causes React to re-render and diff the entire component tree including ChatView, ContextPanel, AppSidebar, StatusBar, and all their children.
• Impact: Unnecessary re-renders on every 15s offline poll, 30s agent status poll, 30s team message poll, and every SSE notification. On complex views (Capabilities with 100+ packages, Memory with frames, Chat with long message lists), this causes visible jank.
• Fix: Apply React.memo() to leaf components that receive stable props: ToolCard, ChatMessage, SessionCard, AgentFleetCard, ToastItem, StatusBar. The ChatView and ContextPanel are also good candidates since they receive many callbacks wrapped in useCallback.

CQ-006: Unsafe as any Casts for Team Adapter Methods

• Severity: HIGH
• Package: app
• File: app/src/App.tsx:910, 916, 921, 926
• Issue: Team-related adapter methods are called via (adapter as any).getTeamStatus(), (adapter as any).connectTeam(), (adapter as any).disconnectTeam(), and (adapter as any).listTeams(). These methods are not on the WaggleService type interface but are called through an any cast with no runtime type checking.
• Impact: If the adapter implementation changes or these methods are removed, TypeScript won't catch it. Runtime errors will be silently swallowed (caught by empty catches). The team connection feature could silently break without any indication.
• Fix: Add getTeamStatus, connectTeam, disconnectTeam, and listTeams to the WaggleService interface (or a TeamService extension interface) so TypeScript can verify the contract. If these are optional features, use a type guard or feature-detection pattern instead of as any.

CQ-007: Dead Code — Orphaned Legacy Components

• Severity: MEDIUM
• Package: app
• File: app/src/components/chat/ChatView.tsx, app/src/hooks/useChat.ts, app/src/hooks/useSidecar.ts, app/src/components/layout/Sidebar.tsx, app/src/components/layout/TitleBar.tsx, app/src/components/onboarding/OnboardingWizard.tsx
• Issue: Multiple files are never imported by the active application:
  • app/src/components/chat/ChatView.tsx — legacy chat view (replaced by app/src/views/ChatView.tsx which uses @waggle/ui)
  • app/src/hooks/useChat.ts — legacy chat hook using old ipc.sendMessage() (only imported by the orphaned ChatView above)
  • app/src/hooks/useSidecar.ts — legacy service connection hook (replaced by ServiceProvider)
  • app/src/components/layout/Sidebar.tsx — legacy sidebar (replaced by AppSidebar)
  • app/src/components/layout/TitleBar.tsx — legacy title bar
  • app/src/components/onboarding/OnboardingWizard.tsx — legacy onboarding (replaced by @waggle/ui's OnboardingWizard)
  • app/src/components/settings/SettingsPanel.tsx — legacy settings (M1-era, uses old ipc API; the active SettingsView imports from @waggle/ui)
• Impact: Increases bundle size, confuses developers about which components are canonical, and the dead ipc-based code references API patterns that no longer exist. The legacy SettingsPanel stores API keys in plaintext via /api/settings instead of the vault.
• Fix: Delete the 7 orphaned files. They are M1/M2-era relics superseded by the @waggle/ui component library.

CQ-008: useTeamActivity Fetcher Not Stable — Causes Re-renders

• Severity: MEDIUM
• Package: @waggle/ui
• File: packages/ui/src/hooks/useTeamActivity.ts:31-49
• Issue: fetchActivity is defined as a plain async function inside the component body (not wrapped in useCallback). It is then called inside a useEffect that lists [baseUrl, teamId, limit] as dependencies, but the function itself is recreated on every render. The effect works because it captures the function by closure, but the fetchActivity function returned as refresh from the hook will be a new reference on every render, causing re-renders in any consumer that uses it in a dependency array.
• Impact: Any component using the refresh callback in a dependency array or passing it as a prop will re-render on every cycle. Minor performance issue but indicates a pattern inconsistency.
• Fix: Wrap fetchActivity in useCallback with [baseUrl, teamId, limit] as dependencies, matching the pattern used in useTeamPresence.

CQ-009: Missing Race Condition Guard in useChat History Load

• Severity: MEDIUM
• Package: @waggle/ui
• File: packages/ui/src/hooks/useChat.ts:151-178
• Issue: When session/workspace changes, the effect loads history via service.getHistory(). While abortRef.current = true is set at the top of the effect to abort in-flight streams, the history load itself is not guarded by a cancellation flag. If a user rapidly switches sessions, completed history loads from a prior session could overwrite messages for the current session.
• Impact: When rapidly switching between sessions, messages from the wrong session could briefly appear, creating confusion. The setMessages call at line 162 could apply stale data.
• Fix: Add a cancelled flag (like useMemory does) and check it before calling setMessages in the .then() callback. Return a cleanup function that sets cancelled = true.

CQ-010: ESLint Exhaustive-Deps Suppressions Hiding Bugs

• Severity: MEDIUM
• Package: app + @waggle/ui
• File: app/src/App.tsx:402, app/src/App.tsx:774, packages/ui/src/hooks/useWorkspaces.ts:60, packages/ui/src/hooks/useSessions.ts:76
• Issue: Five eslint-disable-line react-hooks/exhaustive-deps comments suppress dependency warnings. Notable cases:
  • App.tsx:402 — checkPending effect has empty deps [] but references setMessages and SERVER_BASE. While setMessages is stable (from useState), the pattern hides the dependency on SERVER_BASE.
  • App.tsx:774 — Keyboard handler effect is missing handleNewTab from dependencies. If handleNewTab changes (e.g., new workspace selected), the keyboard shortcut will use stale data.
  • useWorkspaces.ts:60 — Missing activeId dependency. Intentional (to avoid re-fetching when active changes) but the lint suppression hides the rationale.
• Impact: Stale closures in keyboard handlers and startup effects. The keyboard shortcut handler (Cmd+T for new tab) may operate on a stale workspace reference.
• Fix: For App.tsx:774, add handleNewTab to the dependency array. For App.tsx:402, the empty deps are intentional (run once on mount) but should use a ref for SERVER_BASE or document the intentionality with a comment. For useWorkspaces.ts:60, document why activeId is excluded.

CQ-011: setTimeout Without Cleanup in SettingsPanel and ChatMessage

• Severity: LOW
• Package: app + @waggle/ui
• File: app/src/components/settings/SettingsPanel.tsx:25, packages/ui/src/components/chat/ChatMessage.tsx:136
• Issue: Both files use setTimeout outside of useEffect, meaning there is no cleanup mechanism:
  • SettingsPanel.tsx:25: setTimeout(() => setSaved(false), 2000) — called in an event handler, not in an effect. If the component unmounts within 2 seconds (user navigates away), React will warn about updating state on an unmounted component.
  • ChatMessage.tsx:136: setTimeout(() => setCopied(false), 1500) — same pattern in a click handler.
• Impact: React "Can't perform a React state update on an unmounted component" warnings in the console. Not a memory leak per se, but indicates sloppy lifecycle management. In production with React strict mode, this produces visible console noise.
• Fix: Use a ref to track mounted state, or use useEffect with cleanup for timer-based state resets. Alternatively, use a custom useTimeout hook that auto-cleans up.

CQ-012: Tauri Event Listener Cleanup Race Condition

• Severity: MEDIUM
• Package: app
• File: app/src/App.tsx:214-265
• Issue: The Tauri event listeners are registered asynchronously inside an IIFE within useEffect. The cleanup function listeners.forEach(unlisten => unlisten()) runs synchronously when the component unmounts. However, if the component unmounts before the await listen(...) calls complete, the listeners will be pushed to the listeners array after cleanup has already run, leaving dangling event listeners.
• Impact: If the component unmounts and remounts quickly (e.g., during hot reload or React strict mode double-render), Tauri event listeners may accumulate. The waggle://quit listener could fire multiple times. In production with stable mounts this is unlikely, but it is architecturally unsound.
• Fix: Add a cancelled flag. Check cancelled before pushing to listeners. In the cleanup, both set cancelled = true and iterate existing listeners. Alternatively, use an AbortController pattern.

CQ-013: useActiveWorkspace Hook Exported But Never Used

• Severity: LOW
• Package: @waggle/ui
• File: packages/ui/src/hooks/useActiveWorkspace.ts
• Issue: This hook is exported from packages/ui/src/index.ts but never imported by any consumer. The app/src/App.tsx manages active workspace state directly via useWorkspaces which returns activeWorkspace and setActiveWorkspace.
• Impact: Dead code in the published package. Increases bundle size marginally and adds confusion about which hook to use for workspace selection.
• Fix: Either remove the hook and its export, or refactor App.tsx to use it (consolidating workspace selection logic).

CQ-014: SessionList Debounce Timer Not Cleaned Up on Unmount

• Severity: LOW
• Package: @waggle/ui
• File: packages/ui/src/components/sessions/SessionList.tsx:42-53
• Issue: The debounceRef stores a setTimeout reference for search debouncing. While individual timeouts are cleared when new input arrives (line 47), there is no useEffect cleanup to clear the pending timeout if the component unmounts while a search is pending.
• Impact: If the user types a search query and immediately switches views (unmounting SessionList), the debounced onSearch callback will fire after unmount, potentially causing a state update on an unmounted component.
• Fix: Add a useEffect(() => () => { if (debounceRef.current) clearTimeout(debounceRef.current); }, []) cleanup.

CQ-015: Inline Styles for Dynamic CSS Variables

• Severity: LOW
• Package: app + @waggle/ui
• File: app/src/App.tsx:1106, app/src/providers/ServiceProvider.tsx:60-107, packages/ui/src/components/chat/ToolCard.tsx:270, packages/ui/src/components/ToastContainer.tsx:60-62
• Issue: 29 inline style={} usages across the codebase. Most are in ServiceProvider.tsx (loading/error screens use pure inline styles instead of Tailwind classes). The ToolCard uses inline styles for transition animations. ToastContainer uses inline styles for dynamic border colors.
• Impact: Inline styles bypass the Tailwind design system, create inconsistent styling patterns, and cannot be easily themed. The ServiceProvider loading/error screens look visually disconnected from the rest of the app.
• Fix: Replace inline styles with Tailwind classes where possible. For dynamic values (workspace hue, toast border color), use CSS custom properties set via style combined with Tailwind classes that reference them. The ServiceProvider loading/error screens should use the same Tailwind classes as the rest of the app.

CQ-016: err: any Catches Instead of unknown

• Severity: LOW
• Package: app + @waggle/ui
• File: app/src/providers/ServiceProvider.tsx:46, packages/ui/src/components/settings/TeamSection.tsx:42,55, packages/ui/src/components/onboarding/steps/ReadyStep.tsx:102,136
• Issue: Five catch clauses use catch (err: any) instead of catch (err: unknown) with proper type narrowing. This bypasses TypeScript's strict checking within the catch block.
• Impact: Minor type safety gap. Any property access on err is unchecked, so accessing err.message on a non-Error throw would silently produce undefined instead of failing at compile time.
• Fix: Change to catch (err: unknown) and use err instanceof Error ? err.message : String(err) pattern (already used elsewhere in the codebase).

CQ-017: Module-Level Singleton State Outside React

• Severity: LOW
• Package: app + @waggle/ui
• File: app/src/App.tsx:61-62, packages/ui/src/hooks/useSubAgentStatus.ts:37, packages/ui/src/hooks/useChat.ts:29
• Issue: Three module-level singletons exist:
  • adapter (App.tsx:62) — single LocalAdapter instance created at module load time
  • dismissedPatterns (useSubAgentStatus.ts:37) — Set<string> shared across all hook instances
  • messageIdCounter (useChat.ts:29) — global counter for message IDs
• Impact: In testing or SSR contexts, these singletons persist across renders/tests. The dismissedPatterns set grows unboundedly throughout the app's lifetime (minor memory concern). The adapter being module-level means it cannot be reconfigured without a page reload.
• Fix: For adapter, this is acceptable for a desktop app (single instance). For dismissedPatterns, consider a WeakMap or periodic cleanup. For messageIdCounter, the pattern is safe but could use crypto.randomUUID() for test isolation.

CQ-018: CapabilitiesView is 1227 Lines — Needs Decomposition

• Severity: MEDIUM
• Package: app
• File: app/src/views/CapabilitiesView.tsx (1227 lines)
• Issue: This single component contains the Packs tab, Marketplace tab (with search/filter/sort), Individual Skills tab (with create-skill form), all the fetching logic, install/uninstall handlers, bulk install progress tracking, and community pack management. It has 20+ useState calls, 10+ useCallback hooks, and embeds the entire Create Skill form inline.
• Impact: Difficult to test individual features. Very high cognitive load. Any change to marketplace search risks breaking pack install logic. The component cannot be code-split below the view level.
• Fix: Extract into sub-components: PacksTab, MarketplaceTab, SkillsTab, CreateSkillForm. Extract data-fetching into custom hooks: useCapabilityPacks(), useMarketplace(), useCommunityPacks().

CQ-019: Notifications Converted to Toasts Without Deduplication

• Severity: LOW
• Package: app
• File: app/src/App.tsx:195-208
• Issue: The effect that converts notifications to toasts uses notifications.length === 0 as a guard and always takes notifications[0] (the latest). However, the notifications array from useNotifications accumulates up to 50 items. If the notifications state reference changes (even without new items), the effect could fire again and create a duplicate toast from the same notification.
• Impact: Potential duplicate toasts if the notifications array reference changes without content changes. The Math.random() in the toast ID prevents deduplication.
• Fix: Track the last-processed notification timestamp or ID in a ref. Only create a toast if the latest notification is newer than the last-processed one.

CQ-020: fetchActivity in useTeamActivity Causes Re-render Loop Risk

• Severity: LOW
• Package: @waggle/ui
• File: packages/ui/src/hooks/useTeamActivity.ts:51-53
• Issue: The useEffect at line 51 has [baseUrl, teamId, limit] in its dependency array, but it calls fetchActivity() which is a plain function (not memoized). ESLint would flag fetchActivity as a missing dependency, but the lint rule isn't running. The function works correctly because it captures baseUrl, teamId, limit from closure, but the pattern is fragile and inconsistent with other hooks that use useCallback for fetch functions.
• Impact: Functional but violates the established pattern. If someone adds fetchActivity to the dependency array (following the pattern from useTeamPresence), it would cause an infinite re-render loop since fetchActivity is recreated every render.
• Fix: Wrap fetchActivity in useCallback with [baseUrl, teamId, limit] dependencies and add it to the effect's dependency array.

---

Overall Frontend Quality Assessment

Strengths

1. TypeScript strict mode is ON in both app/tsconfig.json and packages/ui/tsconfig.json. The strict: true, noUnusedLocals: true, and noUnusedParameters: true flags are all enabled. This is excellent.

2. Effect cleanup is generally well-handled. Most setInterval, addEventListener, and EventSource usages have proper cleanup in their useEffect return functions. The useTeamPresence, useNotifications, useSubAgentStatus, useSessions, useMemory, useWorkspaces, and keyboard handler effects all clean up correctly.

3. Hooks extract testable pure functions. useChat exports processStreamEvent(), useMemory exports executeMemorySearch(), useKnowledgeGraph extracts toKGData(). This pattern enables unit testing without React.

4. useCallback usage is thorough. The codebase uses useCallback extensively for event handlers passed as props — ~72 occurrences across app/src alone. This prevents unnecessary re-renders in child components (though the benefit is limited without React.memo).

5. Race condition guards exist in key hooks. useMemory, useSessions, useWorkspaces, and ServiceProvider all use cancelled flags to prevent state updates after unmount.

6. Accessibility basics are present. ARIA roles (role="tablist", role="tab", aria-selected, role="dialog", aria-modal, role="listbox", role="option") are used in Modal, CommandPalette, CapabilitiesView tabs, and similar interactive components.

7. Key props on lists are correct. All .map() calls that render JSX use appropriate key props (workspace IDs, session IDs, pack slugs, package IDs, etc.). No index-only keys on dynamic lists.

8. Sanitization is present. Markdown rendering in ChatMessage uses DOMPurify.sanitize() on the output of marked.parse(), preventing XSS through user/agent messages.

Weaknesses

1. No error boundaries — the single most critical gap. A rendering error anywhere crashes the entire app.

2. No React.memo — combined with the monolithic App component, this means every poll interval (15s, 30s) and every SSE event causes a full tree reconciliation.

3. No code splitting — all views are eagerly loaded. For a desktop app this is less critical than web, but it still impacts cold start time.

4. State management is all local — 30+ useState calls in one component with prop drilling through 5 levels. No state management library or context splitting.

5. Dead code accumulation — 7 orphaned files from earlier milestones remain in the tree.

Risk Rating

Category	Rating
Crash resilience	POOR (no error boundaries)
Performance	FAIR (no memoization, no splitting, but app is desktop-bound)
Type safety	GOOD (strict mode, limited any usage)
Memory leak risk	GOOD (cleanup patterns are solid)
Maintainability	FAIR (monolithic App, large views, but hooks are well-structured)
Security (XSS)	GOOD (DOMPurify in place)

Overall: FAIR — The codebase has solid foundations (TypeScript strict, effect cleanup, sanitization) but lacks production hardening (error boundaries, performance optimization, code splitting). The most urgent fix is adding error boundaries to prevent white-screen crashes.