From 93a09e1978def3c428389411a74c2f7783a24839 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 20:47:48 +0530
Subject: [PATCH 01/27] refactor(layout): remove Inbox component and integrate
 NotificationsDropdown

- Eliminated the Inbox component and its related logic from FreeLayoutDataProvider and LayoutDataProvider.
- Introduced NotificationsDropdown to handle notifications in the sidebar and mobile sidebar.
- Updated Sidebar and LayoutShell components to accommodate the new notifications structure, enhancing user experience and code clarity.
---
 .../providers/FreeLayoutDataProvider.tsx      |  30 +-
 .../layout/providers/LayoutDataProvider.tsx   |  57 +--
 .../layout/ui/icon-rail/IconRail.tsx          |   9 +
 .../layout/ui/shell/LayoutShell.tsx           | 112 +-----
 .../layout/ui/sidebar/MobileSidebar.tsx       |  11 +
 .../ui/sidebar/NotificationsDropdown.tsx      | 378 ++++++++++++++++++
 .../components/layout/ui/sidebar/Sidebar.tsx  |  36 +-
 .../layout/ui/sidebar/SidebarUserProfile.tsx  |   4 +
 .../components/layout/ui/sidebar/index.ts     |   2 +-
 9 files changed, 420 insertions(+), 219 deletions(-)
 create mode 100644 surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx

diff --git a/surfsense_web/components/layout/providers/FreeLayoutDataProvider.tsx b/surfsense_web/components/layout/providers/FreeLayoutDataProvider.tsx
index 3a74d77b9..059872bac 100644
--- a/surfsense_web/components/layout/providers/FreeLayoutDataProvider.tsx
+++ b/surfsense_web/components/layout/providers/FreeLayoutDataProvider.tsx
@@ -1,14 +1,13 @@
 "use client";
 
-import { Inbox } from "lucide-react";
 import { useRouter } from "next/navigation";
 import type { ReactNode } from "react";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { useAnonymousMode } from "@/contexts/anonymous-mode";
 import { useLoginGate } from "@/contexts/login-gate";
 import { useAnnouncements } from "@/hooks/use-announcements";
 import { anonymousChatApiService } from "@/lib/apis/anonymous-chat-api.service";
-import type { ChatItem, NavItem, PageUsage, Workspace } from "../types/layout.types";
+import type { ChatItem, PageUsage, Workspace } from "../types/layout.types";
 import { LayoutShell } from "../ui/shell";
 
 interface FreeLayoutDataProviderProps {
@@ -47,34 +46,12 @@ export function FreeLayoutDataProvider({ children }: FreeLayoutDataProviderProps
 
 	const gatedAction = useCallback((feature: string) => () => gate(feature), [gate]);
 
-	const navItems: NavItem[] = useMemo(
-		() =>
-			(
-				[
-					{
-						title: "Inbox",
-						url: "#inbox",
-						icon: Inbox,
-						isActive: false,
-					},
-				] as (NavItem | null)[]
-			).filter((item): item is NavItem => item !== null),
-		[]
-	);
-
 	const pageUsage: PageUsage | undefined = quota
 		? { pagesUsed: quota.used, pagesLimit: quota.limit }
 		: undefined;
 
 	const handleChatSelect = useCallback((_chat: ChatItem) => gate("view chat history"), [gate]);
 
-	const handleNavItemClick = useCallback(
-		(item: NavItem) => {
-			if (item.title === "Inbox") gate("use the inbox");
-		},
-		[gate]
-	);
-
 	const handleAnnouncements = useCallback(() => gate("see what's new"), [gate]);
 
 	const handleWorkspaceSelect = useCallback((_id: number) => gate("switch workspaces"), [gate]);
@@ -87,8 +64,7 @@ export function FreeLayoutDataProvider({ children }: FreeLayoutDataProviderProps
 			onWorkspaceSettings={gatedAction("workspace settings")}
 			onAddWorkspace={gatedAction("create workspaces")}
 			workspace={GUEST_SPACE}
-			navItems={navItems}
-			onNavItemClick={handleNavItemClick}
+			navItems={[]}
 			chats={[]}
 			activeChatId={null}
 			onNewChat={resetChat}
diff --git a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
index 639965d38..bac179816 100644
--- a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
+++ b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
@@ -2,7 +2,7 @@
 
 import { useQuery } from "@tanstack/react-query";
 import { useAtom, useAtomValue, useSetAtom } from "jotai";
-import { AlarmClock, AlertTriangle, Boxes, Inbox, SquareTerminal } from "lucide-react";
+import { AlarmClock, AlertTriangle, Boxes, SquareTerminal } from "lucide-react";
 import { useParams, usePathname, useRouter } from "next/navigation";
 import { useTranslations } from "next-intl";
 import { useTheme } from "next-themes";
@@ -60,17 +60,6 @@ interface LayoutDataProviderProps {
 	children: React.ReactNode;
 }
 
-/**
- * Format count for display: shows numbers up to 999, then "1k+", "2k+", etc.
- */
-function formatInboxCount(count: number): string {
-	if (count <= 999) {
-		return count.toString();
-	}
-	const thousands = Math.floor(count / 1000);
-	return `${thousands}k+`;
-}
-
 export function LayoutDataProvider({ workspaceId, children }: LayoutDataProviderProps) {
 	const t = useTranslations("dashboard");
 	const tCommon = useTranslations("common");
@@ -125,12 +114,6 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 		enabled: !!workspaceId,
 	});
 
-	// Unified slide-out panel state (only one can be open at a time)
-	type SlideoutPanel = "inbox" | null;
-	const [activeSlideoutPanel, setActiveSlideoutPanel] = useState<SlideoutPanel>(null);
-
-	const isInboxSidebarOpen = activeSlideoutPanel === "inbox";
-
 	// Search space dialog state
 	const [isCreateWorkspaceDialogOpen, setIsCreateWorkspaceDialogOpen] = useState(false);
 
@@ -228,17 +211,6 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 	const [isDeletingWorkspace, setIsDeletingWorkspace] = useState(false);
 	const [isLeavingWorkspace, setIsLeavingWorkspace] = useState(false);
 
-	// Reset transient slide-out panels when switching workspaces.
-	// Tabs intentionally persist across spaces — opening tabs from multiple
-	// workspaces is a supported flow (browser-tab semantics).
-	const prevWorkspaceIdRef = useRef(workspaceId);
-	useEffect(() => {
-		if (prevWorkspaceIdRef.current !== workspaceId) {
-			prevWorkspaceIdRef.current = workspaceId;
-			setActiveSlideoutPanel(null);
-		}
-	}, [workspaceId]);
-
 	const workspaces: Workspace[] = useMemo(() => {
 		if (!workspacesData || !Array.isArray(workspacesData)) return [];
 		return workspacesData.map((space) => ({
@@ -318,9 +290,9 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 	}, [threadsData, workspaceId]);
 
 	// Navigation items
-	// Inbox, Automations, and Artifacts are rendered explicitly below "New chat"
-	// in the sidebar (also surfaced in the icon rail's collapsed mode via this
-	// list). Documents is embedded below Recents; announcements live in the avatar dropdown.
+	// Automations and Artifacts are rendered explicitly below "New chat"
+	// in the sidebar. Documents is embedded below Recents; notifications and
+	// announcements live in the avatar rail/dropdown.
 	const isAutomationsActive = pathname?.includes("/automations") === true;
 	const isArtifactsActive = pathname?.endsWith("/artifacts") === true;
 	const isPlaygroundRoute = pathname?.includes("/playground") === true;
@@ -328,13 +300,6 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 		() =>
 			(
 				[
-					{
-						title: "Inbox",
-						url: "#inbox",
-						icon: Inbox,
-						isActive: isInboxSidebarOpen,
-						badge: totalUnreadCount > 0 ? formatInboxCount(totalUnreadCount) : undefined,
-					},
 					{
 						title: "Automations",
 						url: `/dashboard/${workspaceId}/automations`,
@@ -358,8 +323,6 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 				] as (NavItem | null)[]
 			).filter((item): item is NavItem => item !== null),
 		[
-			isInboxSidebarOpen,
-			totalUnreadCount,
 			workspaceId,
 			isAutomationsActive,
 			isArtifactsActive,
@@ -503,10 +466,6 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 
 	const handleNavItemClick = useCallback(
 		(item: NavItem) => {
-			if (item.url === "#inbox") {
-				setActiveSlideoutPanel((prev) => (prev === "inbox" ? null : "inbox"));
-				return;
-			}
 			// Desktop: Playground is a persistent toggle, not a plain link — it just
 			// opens the second-level sidebar (which holds the whole API playground)
 			// and only closes on a second click, never navigating away from the
@@ -518,7 +477,7 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 			}
 			router.push(item.url);
 		},
-		[router, setPlaygroundSidebarOpen, setActiveSlideoutPanel, isMobile]
+		[router, setPlaygroundSidebarOpen, isMobile]
 	);
 
 	const handleNewChat = useCallback(() => {
@@ -688,7 +647,6 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 	const isPlaygroundPage = pathname?.includes("/playground") === true;
 	const isAllChatsPage = pathname?.endsWith("/chats") === true;
 	const handleViewAllChats = useCallback(() => {
-		setActiveSlideoutPanel(null);
 		router.push(
 			isAllChatsPage ? `/dashboard/${workspaceId}/new-chat` : `/dashboard/${workspaceId}/chats`
 		);
@@ -764,10 +722,7 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 								: undefined
 				}
 				isLoadingChats={isLoadingThreads}
-				activeSlideoutPanel={activeSlideoutPanel}
-				onSlideoutPanelChange={setActiveSlideoutPanel}
-				inbox={{
-					isOpen: isInboxSidebarOpen,
+				notifications={{
 					totalUnreadCount,
 					comments: {
 						items: commentsInbox.inboxItems,
diff --git a/surfsense_web/components/layout/ui/icon-rail/IconRail.tsx b/surfsense_web/components/layout/ui/icon-rail/IconRail.tsx
index 5170fa770..1f700c89f 100644
--- a/surfsense_web/components/layout/ui/icon-rail/IconRail.tsx
+++ b/surfsense_web/components/layout/ui/icon-rail/IconRail.tsx
@@ -6,6 +6,10 @@ import { ScrollArea } from "@/components/ui/scroll-area";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import { cn } from "@/lib/utils";
 import type { NavItem, User, Workspace } from "../../types/layout.types";
+import {
+	NotificationsDropdown,
+	type NotificationsDropdownData,
+} from "../sidebar/NotificationsDropdown";
 import { SidebarUserProfile } from "../sidebar/SidebarUserProfile";
 import { WorkspaceAvatar } from "./WorkspaceAvatar";
 
@@ -24,6 +28,7 @@ interface IconRailProps {
 	onUserSettings?: () => void;
 	onAnnouncements?: () => void;
 	announcementUnreadCount?: number;
+	notifications?: NotificationsDropdownData;
 	onLogout?: () => void;
 	theme?: string;
 	setTheme?: (theme: "light" | "dark" | "system") => void;
@@ -45,6 +50,7 @@ export function IconRail({
 	onUserSettings,
 	onAnnouncements,
 	announcementUnreadCount = 0,
+	notifications,
 	onLogout,
 	theme,
 	setTheme,
@@ -145,6 +151,9 @@ export function IconRail({
 				isCollapsed
 				theme={theme}
 				setTheme={setTheme}
+				topContent={
+					notifications ? <NotificationsDropdown notifications={notifications} /> : undefined
+				}
 			/>
 		</div>
 	);
diff --git a/surfsense_web/components/layout/ui/shell/LayoutShell.tsx b/surfsense_web/components/layout/ui/shell/LayoutShell.tsx
index 7adad0cc3..00e606024 100644
--- a/surfsense_web/components/layout/ui/shell/LayoutShell.tsx
+++ b/surfsense_web/components/layout/ui/shell/LayoutShell.tsx
@@ -1,14 +1,12 @@
 "use client";
 
 import { useAtomValue } from "jotai";
-import { AnimatePresence, motion } from "motion/react";
 import dynamic from "next/dynamic";
-import { useCallback, useMemo, useState } from "react";
+import { useMemo, useState } from "react";
 import { activeTabAtom, type Tab } from "@/atoms/tabs/tabs.atom";
 import { Logo } from "@/components/Logo";
 import { Spinner } from "@/components/ui/spinner";
 import { TooltipProvider } from "@/components/ui/tooltip";
-import type { InboxItem } from "@/hooks/use-inbox";
 import { useIsMobile } from "@/hooks/use-mobile";
 import { useElectronAPI } from "@/hooks/use-platform";
 import { cn } from "@/lib/utils";
@@ -27,14 +25,13 @@ import {
 	RightPanelToggleButton,
 } from "../right-panel/RightPanel";
 import {
-	InboxSidebarContent,
 	MobileSidebar,
 	MobileSidebarTrigger,
 	PlaygroundSidebar,
 	Sidebar,
 	SidebarCollapseButton,
 } from "../sidebar";
-import { SidebarSlideOutPanel } from "../sidebar/SidebarSlideOutPanel";
+import type { NotificationsDropdownData } from "../sidebar/NotificationsDropdown";
 import { TabBar } from "../tabs/TabBar";
 import { WorkspacePanel } from "./WorkspacePanel";
 
@@ -80,28 +77,6 @@ function MacDesktopTitleBar({
 	);
 }
 
-// Per-tab data source
-interface TabDataSource {
-	items: InboxItem[];
-	unreadCount: number;
-	loading: boolean;
-	loadingMore: boolean;
-	hasMore: boolean;
-	loadMore: () => void;
-	markAsRead: (id: number) => Promise<boolean>;
-	markAllAsRead: () => Promise<boolean>;
-}
-
-export type ActiveSlideoutPanel = "inbox" | null;
-
-// Inbox-related props — per-tab data sources with independent loading/pagination
-interface InboxProps {
-	isOpen: boolean;
-	totalUnreadCount: number;
-	comments: TabDataSource;
-	status: TabDataSource;
-}
-
 interface LayoutShellProps {
 	workspaces: Workspace[];
 	activeWorkspaceId: number | null;
@@ -140,11 +115,7 @@ interface LayoutShellProps {
 	workspacePanelContentClassName?: string;
 	children: React.ReactNode;
 	className?: string;
-	// Unified slide-out panel state
-	activeSlideoutPanel?: ActiveSlideoutPanel;
-	onSlideoutPanelChange?: (panel: ActiveSlideoutPanel) => void;
-	// Inbox props
-	inbox?: InboxProps;
+	notifications?: NotificationsDropdownData;
 	isLoadingChats?: boolean;
 	onTabSwitch?: (tab: Tab) => void;
 	onTabPrefetch?: (tab: Tab) => void;
@@ -245,9 +216,7 @@ export function LayoutShell({
 	workspacePanelContentClassName,
 	children,
 	className,
-	activeSlideoutPanel = null,
-	onSlideoutPanelChange,
-	inbox,
+	notifications,
 	isLoadingChats = false,
 	onTabSwitch,
 	onTabPrefetch,
@@ -269,17 +238,6 @@ export function LayoutShell({
 		[isCollapsed, setIsCollapsed, toggleCollapsed]
 	);
 
-	const closeSlideout = useCallback(
-		(open: boolean) => {
-			if (!open) onSlideoutPanelChange?.(null);
-		},
-		[onSlideoutPanelChange]
-	);
-
-	const anySlideOutOpen = activeSlideoutPanel !== null;
-
-	const panelAriaLabel = activeSlideoutPanel === "inbox" ? "Inbox" : "Panel";
-
 	// Mobile layout
 	if (isMobile) {
 		return (
@@ -316,6 +274,7 @@ export function LayoutShell({
 							onUserSettings={onUserSettings}
 							onAnnouncements={onAnnouncements}
 							announcementUnreadCount={announcementUnreadCount}
+							notifications={notifications}
 							onLogout={onLogout}
 							pageUsage={pageUsage}
 							theme={theme}
@@ -335,34 +294,6 @@ export function LayoutShell({
 								{children}
 							</main>
 						)}
-
-						{/* Mobile unified slide-out panel */}
-						<SidebarSlideOutPanel
-							open={anySlideOutOpen}
-							onOpenChange={closeSlideout}
-							ariaLabel={panelAriaLabel}
-						>
-							<AnimatePresence mode="popLayout" initial={false}>
-								{activeSlideoutPanel === "inbox" && inbox && (
-									<motion.div
-										key="inbox"
-										className="h-full flex flex-col"
-										initial={{ opacity: 0 }}
-										animate={{ opacity: 1 }}
-										exit={{ opacity: 0 }}
-										transition={{ duration: 0.15 }}
-									>
-										<InboxSidebarContent
-											onOpenChange={(open) => closeSlideout(open)}
-											comments={inbox.comments}
-											status={inbox.status}
-											totalUnreadCount={inbox.totalUnreadCount}
-											onCloseMobileSidebar={() => setMobileMenuOpen(false)}
-										/>
-									</motion.div>
-								)}
-							</AnimatePresence>
-						</SidebarSlideOutPanel>
 					</div>
 				</TooltipProvider>
 			</SidebarProvider>
@@ -400,6 +331,7 @@ export function LayoutShell({
 								onUserSettings={onUserSettings}
 								onAnnouncements={onAnnouncements}
 								announcementUnreadCount={announcementUnreadCount}
+								notifications={notifications}
 								onLogout={onLogout}
 								theme={theme}
 								setTheme={setTheme}
@@ -425,10 +357,7 @@ export function LayoutShell({
 							className={cn(
 								"relative hidden md:flex shrink-0 z-20 -mr-2 bg-panel",
 								isMacDesktop
-									? cn(
-											"border-t border-r",
-											!showPlaygroundSidebar && "rounded-tl-xl border-l"
-										)
+									? cn("border-t border-r", !showPlaygroundSidebar && "rounded-tl-xl border-l")
 									: "border-r"
 							)}
 						>
@@ -491,33 +420,6 @@ export function LayoutShell({
 									)}
 								/>
 							)}
-
-							{/* Unified slide-out panel — shell stays open, content cross-fades */}
-							<SidebarSlideOutPanel
-								open={anySlideOutOpen}
-								onOpenChange={closeSlideout}
-								ariaLabel={panelAriaLabel}
-							>
-								<AnimatePresence mode="popLayout" initial={false}>
-									{activeSlideoutPanel === "inbox" && inbox && (
-										<motion.div
-											key="inbox"
-											className="h-full flex flex-col"
-											initial={{ opacity: 0 }}
-											animate={{ opacity: 1 }}
-											exit={{ opacity: 0 }}
-											transition={{ duration: 0.15 }}
-										>
-											<InboxSidebarContent
-												onOpenChange={(open) => closeSlideout(open)}
-												comments={inbox.comments}
-												status={inbox.status}
-												totalUnreadCount={inbox.totalUnreadCount}
-											/>
-										</motion.div>
-									)}
-								</AnimatePresence>
-							</SidebarSlideOutPanel>
 						</div>
 
 						<DesktopWorkspaceRegion>
diff --git a/surfsense_web/components/layout/ui/sidebar/MobileSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/MobileSidebar.tsx
index f9901d7cb..94fe2d413 100644
--- a/surfsense_web/components/layout/ui/sidebar/MobileSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/MobileSidebar.tsx
@@ -6,6 +6,7 @@ import { ScrollArea } from "@/components/ui/scroll-area";
 import { Sheet, SheetContent, SheetTitle } from "@/components/ui/sheet";
 import type { ChatItem, NavItem, PageUsage, User, Workspace } from "../../types/layout.types";
 import { WorkspaceAvatar } from "../icon-rail/WorkspaceAvatar";
+import { NotificationsDropdown, type NotificationsDropdownData } from "./NotificationsDropdown";
 import { Sidebar } from "./Sidebar";
 import { SidebarUserProfile } from "./SidebarUserProfile";
 
@@ -35,6 +36,7 @@ interface MobileSidebarProps {
 	onUserSettings?: () => void;
 	onAnnouncements?: () => void;
 	announcementUnreadCount?: number;
+	notifications?: NotificationsDropdownData;
 	onLogout?: () => void;
 	pageUsage?: PageUsage;
 	theme?: string;
@@ -83,6 +85,7 @@ export function MobileSidebar({
 	onUserSettings,
 	onAnnouncements,
 	announcementUnreadCount = 0,
+	notifications,
 	onLogout,
 	pageUsage,
 	theme,
@@ -161,6 +164,14 @@ export function MobileSidebar({
 						isCollapsed
 						theme={theme}
 						setTheme={setTheme}
+						topContent={
+							notifications ? (
+								<NotificationsDropdown
+									notifications={notifications}
+									onCloseMobileSidebar={() => onOpenChange(false)}
+								/>
+							) : undefined
+						}
 					/>
 				</div>
 
diff --git a/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
new file mode 100644
index 000000000..e432e077a
--- /dev/null
+++ b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
@@ -0,0 +1,378 @@
+"use client";
+
+import { useAtom } from "jotai";
+import { Bell } from "lucide-react";
+import { useRouter } from "next/navigation";
+import { useCallback, useMemo, useState } from "react";
+import { setTargetCommentIdAtom } from "@/atoms/chat/current-thread.atom";
+import { Button } from "@/components/ui/button";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { Skeleton } from "@/components/ui/skeleton";
+import { Spinner } from "@/components/ui/spinner";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import {
+	isCommentReplyMetadata,
+	isInsufficientCreditsMetadata,
+	isNewMentionMetadata,
+} from "@/contracts/types/inbox.types";
+import type { InboxItem } from "@/hooks/use-inbox";
+import { cn } from "@/lib/utils";
+
+export interface NotificationsDataSource {
+	items: InboxItem[];
+	unreadCount: number;
+	loading: boolean;
+	loadingMore?: boolean;
+	hasMore?: boolean;
+	loadMore?: () => void;
+	markAsRead: (id: number) => Promise<boolean>;
+	markAllAsRead: () => Promise<boolean>;
+}
+
+export interface NotificationsDropdownData {
+	totalUnreadCount: number;
+	comments: NotificationsDataSource;
+	status: NotificationsDataSource;
+}
+
+interface NotificationsDropdownProps {
+	notifications: NotificationsDropdownData;
+	onCloseMobileSidebar?: () => void;
+}
+
+type NotificationFilter = "mentions" | "status" | null;
+
+function formatNotificationCount(count: number): string {
+	if (count <= 999) {
+		return count.toString();
+	}
+	const thousands = Math.floor(count / 1000);
+	return `${thousands}k+`;
+}
+
+function formatTime(dateString: string): string {
+	try {
+		const date = new Date(dateString);
+		const now = new Date();
+		const diffMs = now.getTime() - date.getTime();
+		const diffMins = Math.floor(diffMs / (1000 * 60));
+		const diffHours = Math.floor(diffMs / (1000 * 60 * 60));
+		const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+
+		if (diffMins < 1) return "now";
+		if (diffMins < 60) return `${diffMins}m ago`;
+		if (diffHours < 24) return `${diffHours}h ago`;
+		if (diffDays < 7) return `${diffDays}d ago`;
+		return `${Math.floor(diffDays / 7)}w ago`;
+	} catch {
+		return "now";
+	}
+}
+
+function isCommentNotification(item: InboxItem): boolean {
+	return item.type === "new_mention" || item.type === "comment_reply";
+}
+
+export function NotificationsDropdown({
+	notifications,
+	onCloseMobileSidebar,
+}: NotificationsDropdownProps) {
+	const router = useRouter();
+	const [, setTargetCommentId] = useAtom(setTargetCommentIdAtom);
+	const [open, setOpen] = useState(false);
+	const [activeFilter, setActiveFilter] = useState<NotificationFilter>(null);
+	const [markingAsReadId, setMarkingAsReadId] = useState<number | null>(null);
+	const [markingAllAsRead, setMarkingAllAsRead] = useState(false);
+
+	const unreadLabel = formatNotificationCount(notifications.totalUnreadCount);
+	const visibleUnreadCount =
+		activeFilter === "mentions"
+			? notifications.comments.unreadCount
+			: activeFilter === "status"
+				? notifications.status.unreadCount
+				: notifications.totalUnreadCount;
+	const visibleUnreadLabel = formatNotificationCount(visibleUnreadCount);
+	const isLoading =
+		activeFilter === "mentions"
+			? notifications.comments.loading
+			: activeFilter === "status"
+				? notifications.status.loading
+				: notifications.comments.loading || notifications.status.loading;
+	const items = useMemo(() => {
+		const sourceItems =
+			activeFilter === "mentions"
+				? notifications.comments.items
+				: activeFilter === "status"
+					? notifications.status.items
+					: [...notifications.comments.items, ...notifications.status.items];
+
+		return sourceItems
+			.toSorted((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())
+			.slice(0, 8);
+	}, [activeFilter, notifications.comments.items, notifications.status.items]);
+
+	const markItemAsRead = useCallback(
+		async (item: InboxItem) => {
+			if (item.read) return;
+			setMarkingAsReadId(item.id);
+			try {
+				await (isCommentNotification(item)
+					? notifications.comments.markAsRead(item.id)
+					: notifications.status.markAsRead(item.id));
+			} finally {
+				setMarkingAsReadId(null);
+			}
+		},
+		[notifications.comments, notifications.status]
+	);
+
+	const handleItemClick = useCallback(
+		async (item: InboxItem) => {
+			await markItemAsRead(item);
+
+			if (item.type === "new_mention" && isNewMentionMetadata(item.metadata)) {
+				const threadId = item.metadata.thread_id;
+				const commentId = item.metadata.comment_id;
+				if (item.workspace_id && threadId) {
+					if (commentId) setTargetCommentId(commentId);
+					setOpen(false);
+					onCloseMobileSidebar?.();
+					router.push(
+						commentId
+							? `/dashboard/${item.workspace_id}/new-chat/${threadId}?commentId=${commentId}`
+							: `/dashboard/${item.workspace_id}/new-chat/${threadId}`
+					);
+				}
+				return;
+			}
+
+			if (item.type === "comment_reply" && isCommentReplyMetadata(item.metadata)) {
+				const threadId = item.metadata.thread_id;
+				const replyId = item.metadata.reply_id;
+				if (item.workspace_id && threadId) {
+					if (replyId) setTargetCommentId(replyId);
+					setOpen(false);
+					onCloseMobileSidebar?.();
+					router.push(
+						replyId
+							? `/dashboard/${item.workspace_id}/new-chat/${threadId}?commentId=${replyId}`
+							: `/dashboard/${item.workspace_id}/new-chat/${threadId}`
+					);
+				}
+				return;
+			}
+
+			if (item.type === "insufficient_credits" && isInsufficientCreditsMetadata(item.metadata)) {
+				if (item.metadata.action_url) {
+					setOpen(false);
+					onCloseMobileSidebar?.();
+					router.push(item.metadata.action_url);
+				}
+			}
+		},
+		[markItemAsRead, onCloseMobileSidebar, router, setTargetCommentId]
+	);
+
+	const handleMarkAllAsRead = useCallback(async () => {
+		if (visibleUnreadCount === 0 || markingAllAsRead) return;
+		setMarkingAllAsRead(true);
+		try {
+			if (activeFilter === "mentions") {
+				await notifications.comments.markAllAsRead();
+			} else if (activeFilter === "status") {
+				await notifications.status.markAllAsRead();
+			} else {
+				await Promise.all([
+					notifications.comments.markAllAsRead(),
+					notifications.status.markAllAsRead(),
+				]);
+			}
+		} finally {
+			setMarkingAllAsRead(false);
+		}
+	}, [activeFilter, markingAllAsRead, notifications, visibleUnreadCount]);
+
+	const handleFilterClick = useCallback((filter: Exclude<NotificationFilter, null>) => {
+		setActiveFilter((current) => (current === filter ? null : filter));
+	}, []);
+
+	const emptyStateCopy =
+		activeFilter === "mentions"
+			? {
+					title: "No mentions",
+					description: "Mentions and replies will appear here.",
+				}
+			: activeFilter === "status"
+				? {
+						title: "No status updates",
+						description: "Connector and document updates will appear here.",
+					}
+				: {
+						title: "No notifications",
+						description: "Mentions, replies, and status updates will appear here.",
+					};
+
+	return (
+		<Popover open={open} onOpenChange={setOpen}>
+			<Tooltip>
+				<TooltipTrigger asChild>
+					<PopoverTrigger asChild>
+						<Button
+							type="button"
+							variant="ghost"
+							size="icon"
+							aria-label={
+								notifications.totalUnreadCount > 0
+									? `Notifications, ${unreadLabel} unread`
+									: "Notifications"
+							}
+							className={cn(
+								"relative h-10 w-10 rounded-lg text-muted-foreground hover:bg-accent hover:text-accent-foreground",
+								open && "bg-accent text-accent-foreground"
+							)}
+						>
+							<Bell className="h-4 w-4" />
+							{notifications.totalUnreadCount > 0 ? (
+								<span className="absolute right-1 top-1 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-destructive px-1 text-[10px] font-semibold leading-none text-destructive-foreground">
+									{unreadLabel}
+								</span>
+							) : null}
+						</Button>
+					</PopoverTrigger>
+				</TooltipTrigger>
+				<TooltipContent side="right" sideOffset={8}>
+					Notifications
+				</TooltipContent>
+			</Tooltip>
+			<PopoverContent
+				side="right"
+				align="end"
+				sideOffset={10}
+				className="z-80 flex max-h-[min(520px,calc(100vh-2rem))] w-[360px] flex-col overflow-hidden rounded-xl border bg-popover p-0 text-popover-foreground shadow-lg"
+			>
+				<div className="flex shrink-0 items-center justify-between gap-3 border-b px-4 py-3">
+					<div className="min-w-0">
+						<h2 className="text-base font-semibold">Notifications</h2>
+						<p className="text-xs text-muted-foreground">
+							{visibleUnreadCount > 0 ? `${visibleUnreadLabel} unread` : "You're all caught up"}
+						</p>
+					</div>
+					<Button
+						type="button"
+						variant="ghost"
+						size="sm"
+						onClick={handleMarkAllAsRead}
+						disabled={visibleUnreadCount === 0 || markingAllAsRead}
+						className="h-8 shrink-0 gap-1.5 px-2 text-xs text-muted-foreground hover:text-accent-foreground"
+					>
+						{markingAllAsRead ? <Spinner size="xs" /> : null}
+						Mark all read
+					</Button>
+				</div>
+
+				<div className="flex shrink-0 items-center gap-2 border-b px-3 py-2">
+					<Button
+						type="button"
+						variant="ghost"
+						size="sm"
+						aria-pressed={activeFilter === "mentions"}
+						onClick={() => handleFilterClick("mentions")}
+						className={cn(
+							"h-7 rounded-full px-2.5 text-xs text-muted-foreground",
+							activeFilter === "mentions" && "bg-accent text-accent-foreground"
+						)}
+					>
+						Mentions
+						{notifications.comments.unreadCount > 0 ? (
+							<span className="ml-1 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-primary/15 px-1 text-[10px] font-medium text-primary">
+								{formatNotificationCount(notifications.comments.unreadCount)}
+							</span>
+						) : null}
+					</Button>
+					<Button
+						type="button"
+						variant="ghost"
+						size="sm"
+						aria-pressed={activeFilter === "status"}
+						onClick={() => handleFilterClick("status")}
+						className={cn(
+							"h-7 rounded-full px-2.5 text-xs text-muted-foreground",
+							activeFilter === "status" && "bg-accent text-accent-foreground"
+						)}
+					>
+						Status
+						{notifications.status.unreadCount > 0 ? (
+							<span className="ml-1 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-primary/15 px-1 text-[10px] font-medium text-primary">
+								{formatNotificationCount(notifications.status.unreadCount)}
+							</span>
+						) : null}
+					</Button>
+				</div>
+
+				<div className="min-h-0 flex-1 overflow-y-auto p-2">
+					{isLoading ? (
+						<div className="space-y-1">
+							{[82, 64, 74].map((width) => (
+								<div key={width} className="flex h-[72px] items-center rounded-lg px-2 py-2">
+									<div className="min-w-0 flex-1 space-y-2">
+										<Skeleton className="h-3 rounded" style={{ width: `${width}%` }} />
+										<Skeleton className="h-2.5 w-1/2 rounded" />
+									</div>
+								</div>
+							))}
+						</div>
+					) : items.length > 0 ? (
+						<div className="space-y-1">
+							{items.map((item) => {
+								const isMarkingAsRead = markingAsReadId === item.id;
+								return (
+									<Button
+										key={item.id}
+										type="button"
+										variant="ghost"
+										disabled={isMarkingAsRead}
+										onClick={() => handleItemClick(item)}
+										className={cn(
+											"group h-auto w-full justify-start rounded-lg px-2 py-2 text-left",
+											"hover:bg-accent hover:text-accent-foreground",
+											!item.read && "bg-accent/40"
+										)}
+										style={{ contentVisibility: "auto", containIntrinsicSize: "0 72px" }}
+									>
+										<div className="min-w-0 flex-1">
+											<div className="flex min-w-0 items-start gap-2">
+												<p
+													className={cn(
+														"line-clamp-1 flex-1 text-sm font-medium",
+														!item.read && "font-semibold"
+													)}
+												>
+													{item.title}
+												</p>
+												{!item.read ? (
+													<span className="mt-1.5 h-1.5 w-1.5 shrink-0 rounded-full bg-primary" />
+												) : null}
+											</div>
+											<p className="mt-0.5 line-clamp-2 text-xs font-normal text-muted-foreground group-hover:text-accent-foreground/80">
+												{item.message}
+											</p>
+											<p className="mt-1 text-[11px] font-normal text-muted-foreground/70">
+												{formatTime(item.created_at)}
+											</p>
+										</div>
+										{isMarkingAsRead ? <Spinner size="xs" className="shrink-0" /> : null}
+									</Button>
+								);
+							})}
+						</div>
+					) : (
+						<div className="flex flex-col items-center justify-center px-6 py-10 text-center">
+							<p className="text-sm font-medium">{emptyStateCopy.title}</p>
+							<p className="mt-1 text-xs text-muted-foreground">{emptyStateCopy.description}</p>
+						</div>
+					)}
+				</div>
+			</PopoverContent>
+		</Popover>
+	);
+}
diff --git a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
index 35746acf1..28264a77f 100644
--- a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
@@ -46,21 +46,6 @@ function ChatListSkeletonRows() {
 	);
 }
 
-function CollapsedInboxIcon({ item }: { item: NavItem }) {
-	const Icon = item.icon;
-
-	return (
-		<span className="relative flex h-3.5 w-3.5 items-center justify-center">
-			<Icon className="h-3.5 w-3.5" />
-			{typeof item.badge === "string" ? (
-				<span className="absolute right-0 top-0 flex min-w-3.5 -translate-y-1/2 translate-x-1/2 items-center justify-center rounded-full bg-destructive px-1 text-[9px] font-medium leading-3 text-destructive-foreground">
-					{item.badge}
-				</span>
-			) : null}
-		</span>
-	);
-}
-
 interface SidebarProps {
 	workspace: Workspace | null;
 	isCollapsed?: boolean;
@@ -138,10 +123,9 @@ export function Sidebar({
 	const [openDropdownChatId, setOpenDropdownChatId] = useState<number | null>(null);
 	const [isSidebarNavScrolled, setIsSidebarNavScrolled] = useState(false);
 
-	// Inbox, Automations, and Artifacts are rendered explicitly right below
+	// Automations, Artifacts, and Playground are rendered explicitly right below
 	// New Chat. Pull them out of the nav items list so they don't also appear
 	// in the bottom NavSection. Documents is embedded below Recents.
-	const inboxItem = useMemo(() => navItems.find((item) => item.url === "#inbox"), [navItems]);
 	const automationsItem = useMemo(
 		() => navItems.find((item) => item.url.endsWith("/automations")),
 		[navItems]
@@ -158,7 +142,6 @@ export function Sidebar({
 		() =>
 			navItems.filter(
 				(item) =>
-					item.url !== "#inbox" &&
 					!item.url.endsWith("/automations") &&
 					!item.url.endsWith("/artifacts") &&
 					!item.url.endsWith("/playground")
@@ -235,23 +218,6 @@ export function Sidebar({
 				onScroll={(event) => setIsSidebarNavScrolled(event.currentTarget.scrollTop > 0)}
 			>
 				<div className="flex flex-col gap-0.5 pt-0.5 pb-1.5">
-					{inboxItem && (
-						<SidebarButton
-							icon={inboxItem.icon}
-							label={inboxItem.title}
-							onClick={() => onNavItemClick?.(inboxItem)}
-							isCollapsed={isCollapsed}
-							isActive={inboxItem.isActive}
-							badge={inboxItem.badge}
-							collapsedIconNode={<CollapsedInboxIcon item={inboxItem} />}
-							tooltipContent={isCollapsed ? inboxItem.title : undefined}
-							buttonProps={
-								{
-									"data-joyride": "inbox-sidebar",
-								} as React.ButtonHTMLAttributes<HTMLButtonElement>
-							}
-						/>
-					)}
 					{automationsItem && (
 						<SidebarButton
 							icon={automationsItem.icon}
diff --git a/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx b/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
index ea93ce4d0..0fc9b769b 100644
--- a/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
@@ -16,6 +16,7 @@ import {
 } from "lucide-react";
 import Image from "next/image";
 import { useTranslations } from "next-intl";
+import type React from "react";
 import { useState } from "react";
 import { Button } from "@/components/ui/button";
 import {
@@ -72,6 +73,7 @@ interface SidebarUserProfileProps {
 	isCollapsed?: boolean;
 	theme?: string;
 	setTheme?: (theme: "light" | "dark" | "system") => void;
+	topContent?: React.ReactNode;
 }
 
 function formatAnnouncementCount(count: number): string {
@@ -134,6 +136,7 @@ export function SidebarUserProfile({
 	isCollapsed = false,
 	theme,
 	setTheme,
+	topContent,
 }: SidebarUserProfileProps) {
 	const t = useTranslations("sidebar");
 	const { locale, setLocale } = useLocaleContext();
@@ -171,6 +174,7 @@ export function SidebarUserProfile({
 		return (
 			<div className="w-full border-t px-1.5 py-2">
 				<div className="flex flex-col items-center gap-2">
+					{topContent}
 					{showDownloadCta && (
 						<Tooltip>
 							<TooltipTrigger asChild>
diff --git a/surfsense_web/components/layout/ui/sidebar/index.ts b/surfsense_web/components/layout/ui/sidebar/index.ts
index d1a1f85e5..b74e31b53 100644
--- a/surfsense_web/components/layout/ui/sidebar/index.ts
+++ b/surfsense_web/components/layout/ui/sidebar/index.ts
@@ -2,9 +2,9 @@ export { AllChatsWorkspaceContent } from "./AllChatsSidebar";
 export { ChatListItem } from "./ChatListItem";
 export { CreditBalanceDisplay } from "./CreditBalanceDisplay";
 export { DocumentsSidebar } from "./DocumentsSidebar";
-export { InboxSidebar, InboxSidebarContent } from "./InboxSidebar";
 export { MobileSidebar, MobileSidebarTrigger } from "./MobileSidebar";
 export { NavSection } from "./NavSection";
+export { NotificationsDropdown } from "./NotificationsDropdown";
 export { PlaygroundSidebar } from "./PlaygroundSidebar";
 export { Sidebar } from "./Sidebar";
 export { SidebarCollapseButton } from "./SidebarCollapseButton";

From 469d7b10a6c7eca3180dbe37aaa4144f58110766 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 20:48:03 +0530
Subject: [PATCH 02/27] refactor(sidebar): remove InboxSidebar and
 SidebarSlideOutPanel components

- Deleted InboxSidebar and SidebarSlideOutPanel components to streamline the sidebar structure.
- This change simplifies the layout and prepares for future enhancements in notification handling.
---
 .../layout/ui/sidebar/InboxSidebar.tsx        | 1082 -----------------
 .../ui/sidebar/SidebarSlideOutPanel.tsx       |  115 --
 2 files changed, 1197 deletions(-)
 delete mode 100644 surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx
 delete mode 100644 surfsense_web/components/layout/ui/sidebar/SidebarSlideOutPanel.tsx

diff --git a/surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx
deleted file mode 100644
index 7cf909112..000000000
--- a/surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx
+++ /dev/null
@@ -1,1082 +0,0 @@
-"use client";
-
-import { useQuery } from "@tanstack/react-query";
-import { useAtom } from "jotai";
-import {
-	AlertCircle,
-	AlertTriangle,
-	BellDot,
-	Check,
-	CheckCheck,
-	CheckCircle2,
-	ChevronLeft,
-	History,
-	Inbox,
-	LayoutGrid,
-	ListFilter,
-	MessageCircleReply,
-	Search,
-	X,
-} from "lucide-react";
-import { useParams, useRouter } from "next/navigation";
-import { useTranslations } from "next-intl";
-import { useCallback, useDeferredValue, useEffect, useMemo, useRef, useState } from "react";
-import { setTargetCommentIdAtom } from "@/atoms/chat/current-thread.atom";
-import { Tabs, TabsList, TabsTrigger } from "@/components/ui/animated-tabs";
-import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
-import { Button } from "@/components/ui/button";
-import {
-	Drawer,
-	DrawerContent,
-	DrawerHandle,
-	DrawerHeader,
-	DrawerTitle,
-} from "@/components/ui/drawer";
-import {
-	DropdownMenu,
-	DropdownMenuContent,
-	DropdownMenuItem,
-	DropdownMenuLabel,
-	DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
-import { Input } from "@/components/ui/input";
-import { Skeleton } from "@/components/ui/skeleton";
-import { Spinner } from "@/components/ui/spinner";
-import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
-import { getConnectorIcon } from "@/contracts/enums/connectorIcons";
-import {
-	isCommentReplyMetadata,
-	isConnectorIndexingMetadata,
-	isDocumentProcessingMetadata,
-	isInsufficientCreditsMetadata,
-	isNewMentionMetadata,
-} from "@/contracts/types/inbox.types";
-import { useDebouncedValue } from "@/hooks/use-debounced-value";
-import type { InboxItem } from "@/hooks/use-inbox";
-import { useMediaQuery } from "@/hooks/use-media-query";
-import { notificationsApiService } from "@/lib/apis/notifications-api.service";
-import { convertRenderedToDisplay } from "@/lib/comments/utils";
-import { getDocumentTypeLabel } from "@/lib/documents/document-type-labels";
-import { cacheKeys } from "@/lib/query-client/cache-keys";
-import { getWorkspaceIdNumber } from "@/lib/route-params";
-import { cn } from "@/lib/utils";
-import { SidebarSlideOutPanel } from "./SidebarSlideOutPanel";
-
-function getInitials(name: string | null | undefined, email: string | null | undefined): string {
-	if (name) {
-		return name
-			.split(" ")
-			.map((n) => n[0])
-			.join("")
-			.toUpperCase()
-			.slice(0, 2);
-	}
-	if (email) {
-		const localPart = email.split("@")[0];
-		return localPart.slice(0, 2).toUpperCase();
-	}
-	return "U";
-}
-
-function formatInboxCount(count: number): string {
-	if (count <= 999) {
-		return count.toString();
-	}
-	const thousands = Math.floor(count / 1000);
-	return `${thousands}k+`;
-}
-
-function getConnectorTypeDisplayName(connectorType: string): string {
-	const displayNames: Record<string, string> = {
-		GITHUB_CONNECTOR: "GitHub",
-		GOOGLE_CALENDAR_CONNECTOR: "Google Calendar",
-		GOOGLE_GMAIL_CONNECTOR: "Gmail",
-		GOOGLE_DRIVE_CONNECTOR: "Google Drive",
-		COMPOSIO_GOOGLE_DRIVE_CONNECTOR: "Composio Google Drive",
-		COMPOSIO_GMAIL_CONNECTOR: "Composio Gmail",
-		COMPOSIO_GOOGLE_CALENDAR_CONNECTOR: "Composio Google Calendar",
-		LINEAR_CONNECTOR: "Linear",
-		NOTION_CONNECTOR: "Notion",
-		SLACK_CONNECTOR: "Slack",
-		TEAMS_CONNECTOR: "Microsoft Teams",
-		DISCORD_CONNECTOR: "Discord",
-		JIRA_CONNECTOR: "Jira",
-		CONFLUENCE_CONNECTOR: "Confluence",
-		BOOKSTACK_CONNECTOR: "BookStack",
-		CLICKUP_CONNECTOR: "ClickUp",
-		AIRTABLE_CONNECTOR: "Airtable",
-		LUMA_CONNECTOR: "Luma",
-		ELASTICSEARCH_CONNECTOR: "Elasticsearch",
-		WEBCRAWLER_CONNECTOR: "Web Crawler",
-		YOUTUBE_CONNECTOR: "YouTube",
-		CIRCLEBACK_CONNECTOR: "Circleback",
-		MCP_CONNECTOR: "MCP",
-		OBSIDIAN_CONNECTOR: "Obsidian",
-		ONEDRIVE_CONNECTOR: "OneDrive",
-		DROPBOX_CONNECTOR: "Dropbox",
-		TAVILY_API: "Tavily",
-		SEARXNG_API: "SearXNG",
-		LINKUP_API: "Linkup",
-		BAIDU_SEARCH_API: "Baidu",
-	};
-
-	return (
-		displayNames[connectorType] ||
-		connectorType
-			.replace(/_/g, " ")
-			.replace(/CONNECTOR|API/gi, "")
-			.trim()
-	);
-}
-
-type InboxTab = "comments" | "status";
-type InboxFilter = "all" | "unread" | "errors";
-
-interface TabDataSource {
-	items: InboxItem[];
-	unreadCount: number;
-	loading: boolean;
-	loadingMore: boolean;
-	hasMore: boolean;
-	loadMore: () => void;
-	markAsRead: (id: number) => Promise<boolean>;
-	markAllAsRead: () => Promise<boolean>;
-}
-
-export interface InboxSidebarContentProps {
-	onOpenChange: (open: boolean) => void;
-	comments: TabDataSource;
-	status: TabDataSource;
-	totalUnreadCount: number;
-	onCloseMobileSidebar?: () => void;
-}
-
-interface InboxSidebarProps extends InboxSidebarContentProps {
-	open: boolean;
-}
-
-export function InboxSidebarContent({
-	onOpenChange,
-	comments,
-	status,
-	totalUnreadCount,
-	onCloseMobileSidebar,
-}: InboxSidebarContentProps) {
-	const t = useTranslations("sidebar");
-	const router = useRouter();
-	const params = useParams();
-	const isMobile = !useMediaQuery("(min-width: 640px)");
-	const workspaceId = getWorkspaceIdNumber(params) ?? null;
-
-	const [, setTargetCommentId] = useAtom(setTargetCommentIdAtom);
-
-	const [searchQuery, setSearchQuery] = useState("");
-	const debouncedSearch = useDebouncedValue(searchQuery, 300);
-	const isSearchMode = !!debouncedSearch.trim();
-	const [activeTab, setActiveTab] = useState<InboxTab>("comments");
-	const [activeFilter, setActiveFilter] = useState<InboxFilter>("all");
-	const [selectedSource, setSelectedSource] = useState<string | null>(null);
-	const [mounted, setMounted] = useState(false);
-	const [openDropdown, setOpenDropdown] = useState<"filter" | null>(null);
-	const [connectorScrollPos, setConnectorScrollPos] = useState<"top" | "middle" | "bottom">("top");
-	const connectorRafRef = useRef<number | null>(null);
-	const handleConnectorScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
-		const el = e.currentTarget;
-		if (connectorRafRef.current) return;
-		connectorRafRef.current = requestAnimationFrame(() => {
-			const atTop = el.scrollTop <= 2;
-			const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= 2;
-			setConnectorScrollPos(atTop ? "top" : atBottom ? "bottom" : "middle");
-			connectorRafRef.current = null;
-		});
-	}, []);
-	useEffect(
-		() => () => {
-			if (connectorRafRef.current) cancelAnimationFrame(connectorRafRef.current);
-		},
-		[]
-	);
-	const [filterDrawerOpen, setFilterDrawerOpen] = useState(false);
-	const [markingAsReadId, setMarkingAsReadId] = useState<number | null>(null);
-
-	const prefetchTriggerRef = useRef<HTMLDivElement>(null);
-
-	// Server-side search query
-	const searchTypeFilter = activeTab === "comments" ? ("new_mention" as const) : undefined;
-	const { data: searchResponse, isLoading: isSearchLoading } = useQuery({
-		queryKey: cacheKeys.notifications.search(workspaceId, debouncedSearch.trim(), activeTab),
-		queryFn: () =>
-			notificationsApiService.getNotifications({
-				queryParams: {
-					workspace_id: workspaceId ?? undefined,
-					type: searchTypeFilter,
-					search: debouncedSearch.trim(),
-					limit: 50,
-				},
-			}),
-		staleTime: 30 * 1000,
-		enabled: isSearchMode,
-	});
-
-	useEffect(() => {
-		setMounted(true);
-	}, []);
-
-	useEffect(() => {
-		if (!isMobile) return;
-		const originalOverflow = document.body.style.overflow;
-		document.body.style.overflow = "hidden";
-		return () => {
-			document.body.style.overflow = originalOverflow;
-		};
-	}, [isMobile]);
-
-	useEffect(() => {
-		if (activeTab !== "status") {
-			setSelectedSource(null);
-		}
-	}, [activeTab]);
-
-	// Active tab's data source — fully independent loading, pagination, and counts
-	const activeSource = activeTab === "comments" ? comments : status;
-
-	// Fetch source types for the status tab filter
-	const { data: sourceTypesData } = useQuery({
-		queryKey: cacheKeys.notifications.sourceTypes(workspaceId),
-		queryFn: () => notificationsApiService.getSourceTypes(workspaceId ?? undefined),
-		staleTime: 60 * 1000,
-		enabled: activeTab === "status",
-	});
-
-	const statusSourceOptions = useMemo(() => {
-		if (!sourceTypesData?.sources) return [];
-
-		return sourceTypesData.sources.map((source) => ({
-			key: source.key,
-			type: source.type,
-			category: source.category,
-			displayName:
-				source.category === "connector"
-					? getConnectorTypeDisplayName(source.type)
-					: getDocumentTypeLabel(source.type),
-		}));
-	}, [sourceTypesData]);
-
-	// Client-side filter: source type
-	const matchesSourceFilter = useCallback(
-		(item: InboxItem): boolean => {
-			if (!selectedSource) return true;
-			if (selectedSource.startsWith("connector:")) {
-				const connectorType = selectedSource.slice("connector:".length);
-				return (
-					item.type === "connector_indexing" &&
-					isConnectorIndexingMetadata(item.metadata) &&
-					item.metadata.connector_type === connectorType
-				);
-			}
-			if (selectedSource.startsWith("doctype:")) {
-				const docType = selectedSource.slice("doctype:".length);
-				return (
-					item.type === "document_processing" &&
-					isDocumentProcessingMetadata(item.metadata) &&
-					item.metadata.document_type === docType
-				);
-			}
-			return true;
-		},
-		[selectedSource]
-	);
-
-	// Client-side filter: unread / errors
-	const matchesActiveFilter = useCallback(
-		(item: InboxItem): boolean => {
-			if (activeFilter === "unread") return !item.read;
-			if (activeFilter === "errors") {
-				if (item.type === "insufficient_credits") return true;
-				const meta = item.metadata as Record<string, unknown> | undefined;
-				return typeof meta?.status === "string" && meta.status === "failed";
-			}
-			return true;
-		},
-		[activeFilter]
-	);
-
-	// Defer non-urgent list updates so the search input stays responsive.
-	// The deferred snapshot lags one render behind the live value intentionally.
-	const deferredTabItems = useDeferredValue(activeSource.items);
-	const deferredSearchItems = useDeferredValue(searchResponse?.items ?? []);
-
-	// Two data paths: search mode (API) or default (per-tab data source)
-	const filteredItems = useMemo(() => {
-		const tabItems: InboxItem[] = isSearchMode ? deferredSearchItems : deferredTabItems;
-
-		let result = tabItems;
-		if (activeFilter !== "all") {
-			result = result.filter(matchesActiveFilter);
-		}
-		if (activeTab === "status" && selectedSource) {
-			result = result.filter(matchesSourceFilter);
-		}
-
-		return result;
-	}, [
-		isSearchMode,
-		deferredSearchItems,
-		deferredTabItems,
-		activeTab,
-		activeFilter,
-		selectedSource,
-		matchesActiveFilter,
-		matchesSourceFilter,
-	]);
-
-	// Infinite scroll — uses active tab's pagination
-	useEffect(() => {
-		if (!activeSource.hasMore || activeSource.loadingMore || isSearchMode) return;
-
-		const observer = new IntersectionObserver(
-			(entries) => {
-				if (entries[0]?.isIntersecting) {
-					activeSource.loadMore();
-				}
-			},
-			{
-				root: null,
-				rootMargin: "100px",
-				threshold: 0,
-			}
-		);
-
-		if (prefetchTriggerRef.current) {
-			observer.observe(prefetchTriggerRef.current);
-		}
-
-		return () => observer.disconnect();
-	}, [activeSource.hasMore, activeSource.loadingMore, activeSource.loadMore, isSearchMode]);
-
-	const handleItemClick = useCallback(
-		async (item: InboxItem) => {
-			if (!item.read) {
-				setMarkingAsReadId(item.id);
-				await activeSource.markAsRead(item.id);
-				setMarkingAsReadId(null);
-			}
-
-			if (item.type === "new_mention") {
-				if (isNewMentionMetadata(item.metadata)) {
-					const workspaceId = item.workspace_id;
-					const threadId = item.metadata.thread_id;
-					const commentId = item.metadata.comment_id;
-
-					if (workspaceId && threadId) {
-						if (commentId) {
-							setTargetCommentId(commentId);
-						}
-						const url = commentId
-							? `/dashboard/${workspaceId}/new-chat/${threadId}?commentId=${commentId}`
-							: `/dashboard/${workspaceId}/new-chat/${threadId}`;
-						onOpenChange(false);
-						onCloseMobileSidebar?.();
-						router.push(url);
-					}
-				}
-			} else if (item.type === "comment_reply") {
-				if (isCommentReplyMetadata(item.metadata)) {
-					const workspaceId = item.workspace_id;
-					const threadId = item.metadata.thread_id;
-					const replyId = item.metadata.reply_id;
-
-					if (workspaceId && threadId) {
-						if (replyId) {
-							setTargetCommentId(replyId);
-						}
-						const url = replyId
-							? `/dashboard/${workspaceId}/new-chat/${threadId}?commentId=${replyId}`
-							: `/dashboard/${workspaceId}/new-chat/${threadId}`;
-						onOpenChange(false);
-						onCloseMobileSidebar?.();
-						router.push(url);
-					}
-				}
-			} else if (item.type === "insufficient_credits") {
-				if (isInsufficientCreditsMetadata(item.metadata)) {
-					const actionUrl = item.metadata.action_url;
-					if (actionUrl) {
-						onOpenChange(false);
-						onCloseMobileSidebar?.();
-						router.push(actionUrl);
-					}
-				}
-			}
-		},
-		[activeSource.markAsRead, router, onOpenChange, onCloseMobileSidebar, setTargetCommentId]
-	);
-
-	const handleMarkAllAsRead = useCallback(async () => {
-		await Promise.all([comments.markAllAsRead(), status.markAllAsRead()]);
-	}, [comments.markAllAsRead, status.markAllAsRead]);
-
-	const handleClearSearch = useCallback(() => {
-		setSearchQuery("");
-	}, []);
-
-	const formatTime = (dateString: string) => {
-		try {
-			const date = new Date(dateString);
-			const now = new Date();
-			const diffMs = now.getTime() - date.getTime();
-			const diffMins = Math.floor(diffMs / (1000 * 60));
-			const diffHours = Math.floor(diffMs / (1000 * 60 * 60));
-			const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
-
-			if (diffMins < 1) return "now";
-			if (diffMins < 60) return `${diffMins}m`;
-			if (diffHours < 24) return `${diffHours}h`;
-			if (diffDays < 7) return `${diffDays}d`;
-			return `${Math.floor(diffDays / 7)}w`;
-		} catch {
-			return "now";
-		}
-	};
-
-	const getStatusIcon = (item: InboxItem) => {
-		if (item.type === "new_mention" || item.type === "comment_reply") {
-			const metadata =
-				item.type === "new_mention"
-					? isNewMentionMetadata(item.metadata)
-						? item.metadata
-						: null
-					: isCommentReplyMetadata(item.metadata)
-						? item.metadata
-						: null;
-
-			if (metadata) {
-				return (
-					<Avatar className="h-8 w-8">
-						{metadata.author_avatar_url && (
-							<AvatarImage src={metadata.author_avatar_url} alt={metadata.author_name || "User"} />
-						)}
-						<AvatarFallback className="text-[10px] bg-primary/10 text-primary">
-							{getInitials(metadata.author_name, metadata.author_email)}
-						</AvatarFallback>
-					</Avatar>
-				);
-			}
-			return (
-				<Avatar className="h-8 w-8">
-					<AvatarFallback className="text-[10px] bg-primary/10 text-primary">
-						{getInitials(null, null)}
-					</AvatarFallback>
-				</Avatar>
-			);
-		}
-
-		if (item.type === "insufficient_credits") {
-			return (
-				<div className="h-8 w-8 flex items-center justify-center rounded-full bg-amber-500/10">
-					<AlertTriangle className="h-4 w-4 text-amber-500" />
-				</div>
-			);
-		}
-
-		const metadata = item.metadata as Record<string, unknown>;
-		const status = typeof metadata?.status === "string" ? metadata.status : undefined;
-
-		switch (status) {
-			case "in_progress":
-				return (
-					<div className="h-8 w-8 flex items-center justify-center rounded-full bg-muted">
-						<Spinner size="sm" className="text-foreground" />
-					</div>
-				);
-			case "completed":
-				return (
-					<div className="h-8 w-8 flex items-center justify-center rounded-full bg-green-500/10">
-						<CheckCircle2 className="h-4 w-4 text-green-500" />
-					</div>
-				);
-			case "failed":
-				return (
-					<div className="h-8 w-8 flex items-center justify-center rounded-full bg-red-500/10">
-						<AlertCircle className="h-4 w-4 text-red-500" />
-					</div>
-				);
-			default:
-				return (
-					<div className="h-8 w-8 flex items-center justify-center rounded-full bg-muted">
-						<History className="h-4 w-4 text-muted-foreground" />
-					</div>
-				);
-		}
-	};
-
-	const getEmptyStateMessage = () => {
-		if (activeTab === "comments") {
-			return {
-				title: t("no_comments") || "No comments",
-				hint: t("no_comments_hint") || "You'll see mentions and replies here",
-			};
-		}
-		return {
-			title: t("no_status_updates") || "No status updates",
-			hint: t("no_status_updates_hint") || "Document and connector updates will appear here",
-		};
-	};
-
-	if (!mounted) return null;
-
-	const isLoading = isSearchMode ? isSearchLoading : activeSource.loading;
-
-	return (
-		<>
-			<div className="shrink-0 p-3 pb-1.5 space-y-2">
-				<div className="flex items-center justify-between">
-					<div className="flex items-center gap-2">
-						{isMobile && (
-							<Button
-								variant="ghost"
-								size="icon"
-								className="h-8 w-8 rounded-full text-muted-foreground hover:text-accent-foreground"
-								onClick={() => onOpenChange(false)}
-							>
-								<ChevronLeft className="h-4 w-4" />
-								<span className="sr-only">{t("close") || "Close"}</span>
-							</Button>
-						)}
-						<h2 className="text-lg font-semibold">{t("inbox") || "Inbox"}</h2>
-					</div>
-					<div className="flex items-center gap-1">
-						{isMobile ? (
-							<>
-								<Button
-									variant="ghost"
-									size="icon"
-									className="h-7 w-7 rounded-full"
-									onClick={() => setFilterDrawerOpen(true)}
-								>
-									<ListFilter className="h-4 w-4 text-muted-foreground" />
-									<span className="sr-only">{t("filter") || "Filter"}</span>
-								</Button>
-								<Drawer
-									open={filterDrawerOpen}
-									onOpenChange={setFilterDrawerOpen}
-									shouldScaleBackground={false}
-								>
-									<DrawerContent
-										className="max-h-[70vh] z-80 bg-popover text-popover-foreground"
-										overlayClassName="z-80"
-									>
-										<DrawerHandle />
-										<DrawerHeader className="px-4 pb-3 pt-2">
-											<DrawerTitle className="flex items-center gap-2 text-base font-semibold">
-												<ListFilter className="size-5" />
-												{t("filter") || "Filter"}
-											</DrawerTitle>
-										</DrawerHeader>
-										<div className="flex-1 overflow-y-auto p-4 space-y-4">
-											<div className="space-y-2">
-												<p className="text-xs text-muted-foreground/80 font-medium px-1">
-													{t("filter") || "Filter"}
-												</p>
-												<div className="space-y-1">
-													<Button
-														type="button"
-														variant="ghost"
-														onClick={() => {
-															setActiveFilter("all");
-															setFilterDrawerOpen(false);
-														}}
-														className={cn(
-															"h-auto w-full justify-between rounded-lg px-3 py-2.5 text-sm transition-colors",
-															activeFilter === "all"
-																? "bg-primary/10 text-primary"
-																: "hover:bg-muted"
-														)}
-													>
-														<span className="flex items-center gap-2">
-															<Inbox className="h-4 w-4" />
-															<span>{t("all") || "All"}</span>
-														</span>
-														{activeFilter === "all" && <Check className="h-4 w-4" />}
-													</Button>
-													<Button
-														type="button"
-														variant="ghost"
-														onClick={() => {
-															setActiveFilter("unread");
-															setFilterDrawerOpen(false);
-														}}
-														className={cn(
-															"h-auto w-full justify-between rounded-lg px-3 py-2.5 text-sm transition-colors",
-															activeFilter === "unread"
-																? "bg-primary/10 text-primary"
-																: "hover:bg-muted"
-														)}
-													>
-														<span className="flex items-center gap-2">
-															<BellDot className="h-4 w-4" />
-															<span>{t("unread") || "Unread"}</span>
-														</span>
-														{activeFilter === "unread" && <Check className="h-4 w-4" />}
-													</Button>
-													{activeTab === "status" && (
-														<Button
-															type="button"
-															variant="ghost"
-															onClick={() => {
-																setActiveFilter("errors");
-																setFilterDrawerOpen(false);
-															}}
-															className={cn(
-																"h-auto w-full justify-between rounded-lg px-3 py-2.5 text-sm transition-colors",
-																activeFilter === "errors"
-																	? "bg-primary/10 text-primary"
-																	: "hover:bg-muted"
-															)}
-														>
-															<span className="flex items-center gap-2">
-																<AlertCircle className="h-4 w-4" />
-																<span>{t("errors_only") || "Errors only"}</span>
-															</span>
-															{activeFilter === "errors" && <Check className="h-4 w-4" />}
-														</Button>
-													)}
-												</div>
-											</div>
-											{activeTab === "status" && statusSourceOptions.length > 0 && (
-												<div className="space-y-2">
-													<p className="text-xs text-muted-foreground/80 font-medium px-1">
-														{t("sources") || "Sources"}
-													</p>
-													<div className="space-y-1">
-														<Button
-															type="button"
-															variant="ghost"
-															onClick={() => {
-																setSelectedSource(null);
-																setFilterDrawerOpen(false);
-															}}
-															className={cn(
-																"h-auto w-full justify-between rounded-lg px-3 py-2.5 text-sm transition-colors",
-																selectedSource === null
-																	? "bg-primary/10 text-primary"
-																	: "hover:bg-muted"
-															)}
-														>
-															<span className="flex items-center gap-2">
-																<LayoutGrid className="h-4 w-4" />
-																<span>{t("all_sources") || "All sources"}</span>
-															</span>
-															{selectedSource === null && <Check className="h-4 w-4" />}
-														</Button>
-														{statusSourceOptions.map((source) => (
-															<Button
-																key={source.key}
-																type="button"
-																variant="ghost"
-																onClick={() => {
-																	setSelectedSource(source.key);
-																	setFilterDrawerOpen(false);
-																}}
-																className={cn(
-																	"h-auto w-full justify-between rounded-lg px-3 py-2.5 text-sm transition-colors",
-																	selectedSource === source.key
-																		? "bg-primary/10 text-primary"
-																		: "hover:bg-muted"
-																)}
-															>
-																<span className="flex items-center gap-2">
-																	{getConnectorIcon(source.type, "h-4 w-4")}
-																	<span>{source.displayName}</span>
-																</span>
-																{selectedSource === source.key && <Check className="h-4 w-4" />}
-															</Button>
-														))}
-													</div>
-												</div>
-											)}
-										</div>
-									</DrawerContent>
-								</Drawer>
-							</>
-						) : (
-							<DropdownMenu
-								open={openDropdown === "filter"}
-								onOpenChange={(isOpen) => setOpenDropdown(isOpen ? "filter" : null)}
-							>
-								<Tooltip>
-									<TooltipTrigger asChild>
-										<DropdownMenuTrigger asChild>
-											<Button variant="ghost" size="icon" className="h-7 w-7 rounded-full">
-												<ListFilter className="h-4 w-4 text-muted-foreground" />
-												<span className="sr-only">{t("filter") || "Filter"}</span>
-											</Button>
-										</DropdownMenuTrigger>
-									</TooltipTrigger>
-									<TooltipContent className="z-80">{t("filter") || "Filter"}</TooltipContent>
-								</Tooltip>
-								<DropdownMenuContent
-									align="end"
-									className={cn(
-										"z-80 select-none max-h-[60vh] overflow-hidden flex flex-col",
-										activeTab === "status" ? "w-52" : "w-44"
-									)}
-								>
-									<DropdownMenuLabel className="text-xs text-muted-foreground/80 font-normal">
-										{t("filter") || "Filter"}
-									</DropdownMenuLabel>
-									<DropdownMenuItem
-										onClick={() => setActiveFilter("all")}
-										className="flex items-center justify-between"
-									>
-										<span className="flex items-center gap-2">
-											<Inbox className="h-4 w-4" />
-											<span>{t("all") || "All"}</span>
-										</span>
-										{activeFilter === "all" && <Check className="h-4 w-4" />}
-									</DropdownMenuItem>
-									<DropdownMenuItem
-										onClick={() => setActiveFilter("unread")}
-										className="flex items-center justify-between"
-									>
-										<span className="flex items-center gap-2">
-											<BellDot className="h-4 w-4" />
-											<span>{t("unread") || "Unread"}</span>
-										</span>
-										{activeFilter === "unread" && <Check className="h-4 w-4" />}
-									</DropdownMenuItem>
-									{activeTab === "status" && (
-										<DropdownMenuItem
-											onClick={() => setActiveFilter("errors")}
-											className="flex items-center justify-between"
-										>
-											<span className="flex items-center gap-2">
-												<AlertCircle className="h-4 w-4" />
-												<span>{t("errors_only") || "Errors only"}</span>
-											</span>
-											{activeFilter === "errors" && <Check className="h-4 w-4" />}
-										</DropdownMenuItem>
-									)}
-									{activeTab === "status" && statusSourceOptions.length > 0 && (
-										<>
-											<DropdownMenuLabel className="text-xs text-muted-foreground/80 font-normal mt-2">
-												{t("sources") || "Sources"}
-											</DropdownMenuLabel>
-											<div
-												className="relative max-h-[30vh] overflow-y-auto overflow-x-hidden -mb-1"
-												onScroll={handleConnectorScroll}
-												style={{
-													maskImage: `linear-gradient(to bottom, ${connectorScrollPos === "top" ? "black" : "transparent"}, black 16px, black calc(100% - 16px), ${connectorScrollPos === "bottom" ? "black" : "transparent"})`,
-													WebkitMaskImage: `linear-gradient(to bottom, ${connectorScrollPos === "top" ? "black" : "transparent"}, black 16px, black calc(100% - 16px), ${connectorScrollPos === "bottom" ? "black" : "transparent"})`,
-												}}
-											>
-												<DropdownMenuItem
-													onClick={() => setSelectedSource(null)}
-													className="flex items-center justify-between"
-												>
-													<span className="flex items-center gap-2">
-														<LayoutGrid className="h-4 w-4" />
-														<span>{t("all_sources") || "All sources"}</span>
-													</span>
-													{selectedSource === null && <Check className="h-4 w-4" />}
-												</DropdownMenuItem>
-												{statusSourceOptions.map((source) => (
-													<DropdownMenuItem
-														key={source.key}
-														onClick={() => setSelectedSource(source.key)}
-														className="flex items-center justify-between"
-													>
-														<span className="flex items-center gap-2">
-															{getConnectorIcon(source.type, "h-4 w-4")}
-															<span>{source.displayName}</span>
-														</span>
-														{selectedSource === source.key && <Check className="h-4 w-4" />}
-													</DropdownMenuItem>
-												))}
-											</div>
-										</>
-									)}
-								</DropdownMenuContent>
-							</DropdownMenu>
-						)}
-						<Tooltip>
-							<TooltipTrigger asChild>
-								<Button
-									variant="ghost"
-									size="icon"
-									className="h-7 w-7 rounded-full"
-									onClick={handleMarkAllAsRead}
-									disabled={totalUnreadCount === 0}
-								>
-									<CheckCheck className="h-4 w-4 text-muted-foreground" />
-									<span className="sr-only">{t("mark_all_read") || "Mark all as read"}</span>
-								</Button>
-							</TooltipTrigger>
-							<TooltipContent className="z-80">
-								{t("mark_all_read") || "Mark all as read"}
-							</TooltipContent>
-						</Tooltip>
-					</div>
-				</div>
-
-				<div className="relative">
-					<Search className="absolute left-2.5 top-1/2 -translate-y-1/2 h-3.5 w-3.5 text-muted-foreground" />
-					<Input
-						type="text"
-						placeholder={t("search_inbox") || "Search inbox"}
-						value={searchQuery}
-						onChange={(e) => setSearchQuery(e.target.value)}
-						className="h-8 border-0 bg-muted pl-8 pr-7 text-sm shadow-none"
-					/>
-					{searchQuery && (
-						<Button
-							variant="ghost"
-							size="icon"
-							className="absolute right-1 top-1/2 h-5 w-5 -translate-y-1/2 rounded-sm text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
-							onClick={handleClearSearch}
-						>
-							<X className="h-3.5 w-3.5" />
-							<span className="sr-only">{t("clear_search") || "Clear search"}</span>
-						</Button>
-					)}
-				</div>
-			</div>
-
-			<Tabs
-				value={activeTab}
-				onValueChange={(value) => {
-					const tab = value as InboxTab;
-					setActiveTab(tab);
-					if (tab !== "status" && activeFilter === "errors") {
-						setActiveFilter("all");
-					}
-				}}
-				className="shrink-0 mx-3 mt-1.5"
-			>
-				<TabsList stretch showBottomBorder size="sm">
-					<TabsTrigger value="comments">
-						<span className="inline-flex items-center gap-1.5">
-							<MessageCircleReply className="h-3.5 w-3.5" />
-							<span>{t("comments") || "Comments"}</span>
-							<span className="inline-flex h-4.5 min-w-4.5 items-center justify-center rounded-full bg-primary/20 px-1 text-[10px] font-medium text-muted-foreground">
-								{formatInboxCount(comments.unreadCount)}
-							</span>
-						</span>
-					</TabsTrigger>
-					<TabsTrigger value="status">
-						<span className="inline-flex items-center gap-1.5">
-							<History className="h-3.5 w-3.5" />
-							<span>{t("status") || "Status"}</span>
-							<span className="inline-flex h-4.5 min-w-4.5 items-center justify-center rounded-full bg-primary/20 px-1 text-[10px] font-medium text-muted-foreground">
-								{formatInboxCount(status.unreadCount)}
-							</span>
-						</span>
-					</TabsTrigger>
-				</TabsList>
-			</Tabs>
-
-			<div className="flex-1 overflow-y-auto overflow-x-hidden p-2">
-				{isLoading ? (
-					<div className="space-y-2">
-						{activeTab === "comments"
-							? [85, 60, 90, 70, 50, 75].map((titleWidth) => (
-									<div
-										key={`skeleton-comment-${titleWidth}`}
-										className="flex items-center gap-3 rounded-lg px-3 py-3 h-[80px]"
-									>
-										<Skeleton className="h-8 w-8 rounded-full shrink-0" />
-										<div className="flex-1 min-w-0 space-y-2">
-											<Skeleton className="h-3 rounded" style={{ width: `${titleWidth}%` }} />
-											<Skeleton className="h-2.5 w-[70%] rounded" />
-										</div>
-										<Skeleton className="h-3 w-6 shrink-0 rounded" />
-									</div>
-								))
-							: [75, 90, 55, 80, 65, 85].map((titleWidth) => (
-									<div
-										key={`skeleton-status-${titleWidth}`}
-										className="flex items-center gap-3 rounded-lg px-3 py-3 h-[80px]"
-									>
-										<Skeleton className="h-8 w-8 rounded-full shrink-0" />
-										<div className="flex-1 min-w-0 space-y-2">
-											<Skeleton className="h-3 rounded" style={{ width: `${titleWidth}%` }} />
-											<Skeleton className="h-2.5 w-[60%] rounded" />
-										</div>
-										<div className="flex items-center gap-1.5 shrink-0">
-											<Skeleton className="h-3 w-6 rounded" />
-											<Skeleton className="h-2 w-2 rounded-full" />
-										</div>
-									</div>
-								))}
-					</div>
-				) : filteredItems.length > 0 ? (
-					<div className="space-y-2">
-						{filteredItems.map((item, index) => {
-							const isMarkingAsRead = markingAsReadId === item.id;
-							const isPrefetchTrigger =
-								!isSearchMode && activeSource.hasMore && index === filteredItems.length - 5;
-
-							return (
-								<div
-									key={item.id}
-									ref={isPrefetchTrigger ? prefetchTriggerRef : undefined}
-									className={cn(
-										"group flex items-center gap-3 rounded-lg px-3 py-3 text-sm h-[80px] overflow-hidden",
-										"hover:bg-accent hover:text-accent-foreground",
-										"transition-colors cursor-pointer",
-										isMarkingAsRead && "opacity-50 pointer-events-none"
-									)}
-									style={{ contentVisibility: "auto", containIntrinsicSize: "0 80px" }}
-								>
-									{activeTab === "status" ? (
-										<Tooltip delayDuration={600}>
-											<TooltipTrigger asChild>
-												<Button
-													type="button"
-													variant="ghost"
-													onClick={() => handleItemClick(item)}
-													disabled={isMarkingAsRead}
-													className="h-auto flex-1 justify-start gap-3 overflow-hidden bg-transparent p-0 text-left hover:bg-transparent"
-												>
-													<div className="shrink-0">{getStatusIcon(item)}</div>
-													<div className="flex-1 min-w-0 overflow-hidden">
-														<p
-															className={cn(
-																"text-xs font-medium line-clamp-2",
-																!item.read && "font-semibold"
-															)}
-														>
-															{item.title}
-														</p>
-														<p className="text-[11px] text-muted-foreground line-clamp-2 mt-0.5">
-															{convertRenderedToDisplay(item.message)}
-														</p>
-													</div>
-												</Button>
-											</TooltipTrigger>
-											<TooltipContent side="bottom" align="start" className="max-w-[250px]">
-												<p className="font-medium">{item.title}</p>
-												<p className="text-muted-foreground mt-1">
-													{convertRenderedToDisplay(item.message)}
-												</p>
-											</TooltipContent>
-										</Tooltip>
-									) : (
-										<Button
-											type="button"
-											variant="ghost"
-											onClick={() => handleItemClick(item)}
-											disabled={isMarkingAsRead}
-											className="h-auto flex-1 justify-start gap-3 overflow-hidden bg-transparent p-0 text-left hover:bg-transparent"
-										>
-											<div className="shrink-0">{getStatusIcon(item)}</div>
-											<div className="flex-1 min-w-0 overflow-hidden">
-												<p
-													className={cn(
-														"text-xs font-medium line-clamp-2",
-														!item.read && "font-semibold"
-													)}
-												>
-													{item.title}
-												</p>
-												<p className="text-[11px] text-muted-foreground line-clamp-2 mt-0.5">
-													{convertRenderedToDisplay(item.message)}
-												</p>
-											</div>
-										</Button>
-									)}
-
-									<div className="flex items-center justify-end gap-1.5 shrink-0 w-10">
-										<span className="text-[10px] text-muted-foreground">
-											{formatTime(item.created_at)}
-										</span>
-										{!item.read && <span className="h-2 w-2 rounded-full bg-blue-500 shrink-0" />}
-									</div>
-								</div>
-							);
-						})}
-						{!isSearchMode && filteredItems.length < 5 && activeSource.hasMore && (
-							<div ref={prefetchTriggerRef} className="h-1" />
-						)}
-						{activeSource.loadingMore &&
-							(activeTab === "comments"
-								? [80, 60, 90].map((titleWidth) => (
-										<div
-											key={`loading-more-comment-${titleWidth}`}
-											className="flex items-center gap-3 rounded-lg px-3 py-3 h-[80px]"
-										>
-											<Skeleton className="h-8 w-8 rounded-full shrink-0" />
-											<div className="flex-1 min-w-0 space-y-2">
-												<Skeleton className="h-3 rounded" style={{ width: `${titleWidth}%` }} />
-												<Skeleton className="h-2.5 w-[70%] rounded" />
-											</div>
-											<Skeleton className="h-3 w-6 shrink-0 rounded" />
-										</div>
-									))
-								: [70, 85, 55].map((titleWidth) => (
-										<div
-											key={`loading-more-status-${titleWidth}`}
-											className="flex items-center gap-3 rounded-lg px-3 py-3 h-[80px]"
-										>
-											<Skeleton className="h-8 w-8 rounded-full shrink-0" />
-											<div className="flex-1 min-w-0 space-y-2">
-												<Skeleton className="h-3 rounded" style={{ width: `${titleWidth}%` }} />
-												<Skeleton className="h-2.5 w-[60%] rounded" />
-											</div>
-											<div className="flex items-center gap-1.5 shrink-0">
-												<Skeleton className="h-3 w-6 rounded" />
-												<Skeleton className="h-2 w-2 rounded-full" />
-											</div>
-										</div>
-									)))}
-					</div>
-				) : isSearchMode ? (
-					<div className="text-center py-8">
-						<Search className="mx-auto mb-2.5 h-10 w-10 text-muted-foreground" />
-						<p className="text-xs text-muted-foreground">
-							{t("no_results_found") || "No results found"}
-						</p>
-						<p className="mt-1 text-[11px] text-muted-foreground/70">
-							{t("try_different_search") || "Try a different search term"}
-						</p>
-					</div>
-				) : (
-					<div className="text-center py-8">
-						{activeTab === "comments" ? (
-							<MessageCircleReply className="mx-auto mb-2.5 h-10 w-10 text-muted-foreground" />
-						) : (
-							<History className="mx-auto mb-2.5 h-10 w-10 text-muted-foreground" />
-						)}
-						<p className="text-xs text-muted-foreground">{getEmptyStateMessage().title}</p>
-						<p className="mt-1 text-[11px] text-muted-foreground/70">
-							{getEmptyStateMessage().hint}
-						</p>
-					</div>
-				)}
-			</div>
-		</>
-	);
-}
-
-export function InboxSidebar({
-	open,
-	onOpenChange,
-	comments,
-	status,
-	totalUnreadCount,
-	onCloseMobileSidebar,
-}: InboxSidebarProps) {
-	const t = useTranslations("sidebar");
-
-	return (
-		<SidebarSlideOutPanel open={open} onOpenChange={onOpenChange} ariaLabel={t("inbox") || "Inbox"}>
-			<InboxSidebarContent
-				onOpenChange={onOpenChange}
-				comments={comments}
-				status={status}
-				totalUnreadCount={totalUnreadCount}
-				onCloseMobileSidebar={onCloseMobileSidebar}
-			/>
-		</SidebarSlideOutPanel>
-	);
-}
diff --git a/surfsense_web/components/layout/ui/sidebar/SidebarSlideOutPanel.tsx b/surfsense_web/components/layout/ui/sidebar/SidebarSlideOutPanel.tsx
deleted file mode 100644
index 52b2cf998..000000000
--- a/surfsense_web/components/layout/ui/sidebar/SidebarSlideOutPanel.tsx
+++ /dev/null
@@ -1,115 +0,0 @@
-"use client";
-
-import { useSetAtom } from "jotai";
-import { AnimatePresence, motion } from "motion/react";
-import { useCallback, useEffect } from "react";
-import { useIsMobile } from "@/hooks/use-mobile";
-import { slideoutOpenedTickAtom } from "@/lib/layout-events";
-
-interface SidebarSlideOutPanelProps {
-	open: boolean;
-	onOpenChange: (open: boolean) => void;
-	ariaLabel: string;
-	width?: number;
-	children: React.ReactNode;
-}
-
-/**
- * Reusable slide-out panel that extends from the sidebar.
- *
- * Desktop: absolutely positioned at the sidebar's right edge, overlaying the main
- * content with a blur backdrop. Does not push/shrink the main content.
- *
- * Mobile: full-width absolute overlay (unchanged).
- */
-export function SidebarSlideOutPanel({
-	open,
-	onOpenChange,
-	ariaLabel,
-	width = 360,
-	children,
-}: SidebarSlideOutPanelProps) {
-	const isMobile = useIsMobile();
-	const bumpSlideoutOpenedTick = useSetAtom(slideoutOpenedTickAtom);
-
-	useEffect(() => {
-		if (open) {
-			bumpSlideoutOpenedTick((tick) => tick + 1);
-		}
-	}, [open, bumpSlideoutOpenedTick]);
-
-	const handleEscape = useCallback(
-		(e: KeyboardEvent) => {
-			if (e.key === "Escape") onOpenChange(false);
-		},
-		[onOpenChange]
-	);
-
-	useEffect(() => {
-		if (!open) return;
-		document.addEventListener("keydown", handleEscape);
-		return () => document.removeEventListener("keydown", handleEscape);
-	}, [open, handleEscape]);
-
-	if (isMobile) {
-		return (
-			<AnimatePresence>
-				{open && (
-					<div className="absolute left-0 inset-y-0 z-30 w-full overflow-hidden pointer-events-none">
-						<motion.div
-							initial={{ x: "-100%" }}
-							animate={{ x: 0 }}
-							exit={{ x: "-100%" }}
-							transition={{ type: "tween", duration: 0.2, ease: [0.4, 0, 0.2, 1] }}
-							className="h-full w-full bg-sidebar text-sidebar-foreground flex flex-col pointer-events-auto select-none"
-							role="dialog"
-							aria-modal="true"
-							aria-label={ariaLabel}
-						>
-							{children}
-						</motion.div>
-					</div>
-				)}
-			</AnimatePresence>
-		);
-	}
-
-	return (
-		<AnimatePresence initial={false}>
-			{open && (
-				<>
-					{/* Blur backdrop covering the main content area (right of sidebar) */}
-					<motion.div
-						initial={{ opacity: 0 }}
-						animate={{ opacity: 1 }}
-						exit={{ opacity: 0 }}
-						transition={{ duration: 0.15 }}
-						className="absolute z-10 bg-black/30 backdrop-blur-sm rounded-xl"
-						style={{ top: -9, bottom: -9, left: "calc(100% + 1px)", width: "200vw" }}
-						onClick={() => onOpenChange(false)}
-						aria-hidden="true"
-					/>
-
-					{/* Panel extending from sidebar's right edge, flush with the wrapper border */}
-					<motion.div
-						initial={{ width: 0 }}
-						animate={{ width }}
-						exit={{ width: 0 }}
-						transition={{ type: "tween", duration: 0.2, ease: [0.4, 0, 0.2, 1] }}
-						className="absolute z-20 overflow-hidden"
-						style={{ left: "100%", top: -1, bottom: -1 }}
-					>
-						<div
-							style={{ width }}
-							className="h-full bg-sidebar text-sidebar-foreground flex flex-col select-none border shadow-xl"
-							role="dialog"
-							aria-label={ariaLabel}
-						>
-							{children}
-						</div>
-					</motion.div>
-				</>
-			)}
-		</AnimatePresence>
-	);
-}

From 335e37e1d3ebae5f418f89412df3ed770c1cbf22 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 20:48:16 +0530
Subject: [PATCH 03/27] feat(notifications): enhance notification handling with
 total counts and improved filtering

- Added totalCount to comments and status notifications for better tracking.
- Updated NotificationsDropdown to support new filters and improved loading behavior.
- Refactored notification display logic to accommodate the new structure, enhancing user experience.
---
 .../layout/providers/LayoutDataProvider.tsx   |   2 +
 .../ui/sidebar/NotificationsDropdown.tsx      | 188 ++++++++++++------
 surfsense_web/hooks/use-inbox.ts              |   5 +
 3 files changed, 130 insertions(+), 65 deletions(-)

diff --git a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
index bac179816..a70e8f59e 100644
--- a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
+++ b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
@@ -727,6 +727,7 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 					comments: {
 						items: commentsInbox.inboxItems,
 						unreadCount: commentsInbox.unreadCount,
+						totalCount: commentsInbox.totalCount,
 						loading: commentsInbox.loading,
 						loadingMore: commentsInbox.loadingMore,
 						hasMore: commentsInbox.hasMore,
@@ -737,6 +738,7 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 					status: {
 						items: statusInbox.inboxItems,
 						unreadCount: statusInbox.unreadCount,
+						totalCount: statusInbox.totalCount,
 						loading: statusInbox.loading,
 						loadingMore: statusInbox.loadingMore,
 						hasMore: statusInbox.hasMore,
diff --git a/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
index e432e077a..3ada5de46 100644
--- a/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
@@ -3,7 +3,7 @@
 import { useAtom } from "jotai";
 import { Bell } from "lucide-react";
 import { useRouter } from "next/navigation";
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { setTargetCommentIdAtom } from "@/atoms/chat/current-thread.atom";
 import { Button } from "@/components/ui/button";
 import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
@@ -21,6 +21,7 @@ import { cn } from "@/lib/utils";
 export interface NotificationsDataSource {
 	items: InboxItem[];
 	unreadCount: number;
+	totalCount?: number;
 	loading: boolean;
 	loadingMore?: boolean;
 	hasMore?: boolean;
@@ -40,7 +41,7 @@ interface NotificationsDropdownProps {
 	onCloseMobileSidebar?: () => void;
 }
 
-type NotificationFilter = "mentions" | "status" | null;
+type NotificationFilter = "all" | "mentions" | "unread";
 
 function formatNotificationCount(count: number): string {
 	if (count <= 999) {
@@ -80,37 +81,84 @@ export function NotificationsDropdown({
 	const router = useRouter();
 	const [, setTargetCommentId] = useAtom(setTargetCommentIdAtom);
 	const [open, setOpen] = useState(false);
-	const [activeFilter, setActiveFilter] = useState<NotificationFilter>(null);
+	const [activeFilter, setActiveFilter] = useState<NotificationFilter>("all");
 	const [markingAsReadId, setMarkingAsReadId] = useState<number | null>(null);
 	const [markingAllAsRead, setMarkingAllAsRead] = useState(false);
+	const scrollContainerRef = useRef<HTMLDivElement>(null);
+	const loadMoreTriggerRef = useRef<HTMLDivElement>(null);
 
 	const unreadLabel = formatNotificationCount(notifications.totalUnreadCount);
+	const allCount =
+		(notifications.comments.totalCount ?? 0) + (notifications.status.totalCount ?? 0);
+	const mentionsCount = notifications.comments.totalCount ?? notifications.comments.items.length;
 	const visibleUnreadCount =
 		activeFilter === "mentions"
 			? notifications.comments.unreadCount
-			: activeFilter === "status"
-				? notifications.status.unreadCount
-				: notifications.totalUnreadCount;
-	const visibleUnreadLabel = formatNotificationCount(visibleUnreadCount);
+			: notifications.totalUnreadCount;
 	const isLoading =
 		activeFilter === "mentions"
 			? notifications.comments.loading
-			: activeFilter === "status"
-				? notifications.status.loading
-				: notifications.comments.loading || notifications.status.loading;
+			: notifications.comments.loading || notifications.status.loading;
+	const isLoadingMore =
+		activeFilter === "mentions"
+			? !!notifications.comments.loadingMore
+			: !!notifications.comments.loadingMore || !!notifications.status.loadingMore;
+	const hasMore =
+		activeFilter === "mentions"
+			? !!notifications.comments.hasMore
+			: !!notifications.comments.hasMore || !!notifications.status.hasMore;
 	const items = useMemo(() => {
 		const sourceItems =
 			activeFilter === "mentions"
 				? notifications.comments.items
-				: activeFilter === "status"
-					? notifications.status.items
-					: [...notifications.comments.items, ...notifications.status.items];
+				: [...notifications.comments.items, ...notifications.status.items];
 
 		return sourceItems
-			.toSorted((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())
-			.slice(0, 8);
+			.filter((item) => activeFilter !== "unread" || !item.read)
+			.toSorted((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
 	}, [activeFilter, notifications.comments.items, notifications.status.items]);
 
+	const loadMoreForActiveFilter = useCallback(() => {
+		if (isLoadingMore) return;
+
+		if (activeFilter === "mentions") {
+			if (notifications.comments.hasMore) {
+				notifications.comments.loadMore?.();
+			}
+			return;
+		}
+
+		if (notifications.comments.hasMore) {
+			notifications.comments.loadMore?.();
+		}
+		if (notifications.status.hasMore) {
+			notifications.status.loadMore?.();
+		}
+	}, [activeFilter, isLoadingMore, notifications.comments, notifications.status]);
+
+	useEffect(() => {
+		if (!open || isLoading || isLoadingMore || !hasMore) return;
+		const root = scrollContainerRef.current;
+		const target = loadMoreTriggerRef.current;
+		if (!root || !target) return;
+
+		const observer = new IntersectionObserver(
+			(entries) => {
+				if (entries[0]?.isIntersecting) {
+					loadMoreForActiveFilter();
+				}
+			},
+			{
+				root,
+				rootMargin: "120px",
+				threshold: 0,
+			}
+		);
+
+		observer.observe(target);
+		return () => observer.disconnect();
+	}, [hasMore, isLoading, isLoadingMore, loadMoreForActiveFilter, open]);
+
 	const markItemAsRead = useCallback(
 		async (item: InboxItem) => {
 			if (item.read) return;
@@ -179,8 +227,6 @@ export function NotificationsDropdown({
 		try {
 			if (activeFilter === "mentions") {
 				await notifications.comments.markAllAsRead();
-			} else if (activeFilter === "status") {
-				await notifications.status.markAllAsRead();
 			} else {
 				await Promise.all([
 					notifications.comments.markAllAsRead(),
@@ -192,26 +238,28 @@ export function NotificationsDropdown({
 		}
 	}, [activeFilter, markingAllAsRead, notifications, visibleUnreadCount]);
 
-	const handleFilterClick = useCallback((filter: Exclude<NotificationFilter, null>) => {
-		setActiveFilter((current) => (current === filter ? null : filter));
-	}, []);
-
 	const emptyStateCopy =
 		activeFilter === "mentions"
 			? {
 					title: "No mentions",
 					description: "Mentions and replies will appear here.",
 				}
-			: activeFilter === "status"
+			: activeFilter === "unread"
 				? {
-						title: "No status updates",
-						description: "Connector and document updates will appear here.",
+						title: "No unread notifications",
+						description: "New mentions and status updates will appear here.",
 					}
 				: {
 						title: "No notifications",
 						description: "Mentions, replies, and status updates will appear here.",
 					};
 
+	const tabs: { value: NotificationFilter; label: string; count: number }[] = [
+		{ value: "all", label: "All", count: allCount },
+		{ value: "mentions", label: "Mentions", count: mentionsCount },
+		{ value: "unread", label: "Unread", count: notifications.totalUnreadCount },
+	];
+
 	return (
 		<Popover open={open} onOpenChange={setOpen}>
 			<Tooltip>
@@ -253,9 +301,6 @@ export function NotificationsDropdown({
 				<div className="flex shrink-0 items-center justify-between gap-3 border-b px-4 py-3">
 					<div className="min-w-0">
 						<h2 className="text-base font-semibold">Notifications</h2>
-						<p className="text-xs text-muted-foreground">
-							{visibleUnreadCount > 0 ? `${visibleUnreadLabel} unread` : "You're all caught up"}
-						</p>
 					</div>
 					<Button
 						type="button"
@@ -270,46 +315,38 @@ export function NotificationsDropdown({
 					</Button>
 				</div>
 
-				<div className="flex shrink-0 items-center gap-2 border-b px-3 py-2">
-					<Button
-						type="button"
-						variant="ghost"
-						size="sm"
-						aria-pressed={activeFilter === "mentions"}
-						onClick={() => handleFilterClick("mentions")}
-						className={cn(
-							"h-7 rounded-full px-2.5 text-xs text-muted-foreground",
-							activeFilter === "mentions" && "bg-accent text-accent-foreground"
-						)}
-					>
-						Mentions
-						{notifications.comments.unreadCount > 0 ? (
-							<span className="ml-1 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-primary/15 px-1 text-[10px] font-medium text-primary">
-								{formatNotificationCount(notifications.comments.unreadCount)}
-							</span>
-						) : null}
-					</Button>
-					<Button
-						type="button"
-						variant="ghost"
-						size="sm"
-						aria-pressed={activeFilter === "status"}
-						onClick={() => handleFilterClick("status")}
-						className={cn(
-							"h-7 rounded-full px-2.5 text-xs text-muted-foreground",
-							activeFilter === "status" && "bg-accent text-accent-foreground"
-						)}
-					>
-						Status
-						{notifications.status.unreadCount > 0 ? (
-							<span className="ml-1 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-primary/15 px-1 text-[10px] font-medium text-primary">
-								{formatNotificationCount(notifications.status.unreadCount)}
-							</span>
-						) : null}
-					</Button>
+				<div className="relative flex shrink-0 items-end gap-4 px-4 after:absolute after:inset-x-0 after:bottom-0 after:z-0 after:h-px after:bg-muted-foreground/25 after:content-['']">
+					{tabs.map((tab) => {
+						const isActive = activeFilter === tab.value;
+						return (
+							<button
+								key={tab.value}
+								type="button"
+								aria-pressed={isActive}
+								onClick={() => setActiveFilter(tab.value)}
+								className={cn(
+									"relative z-10 flex h-11 items-center gap-2 border-b-2 border-transparent px-0 text-sm font-medium text-muted-foreground transition-colors",
+									"hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+									isActive && "border-primary text-primary"
+								)}
+							>
+								<span>{tab.label}</span>
+								<span
+									className={cn(
+										"inline-flex h-5 min-w-5 items-center justify-center rounded-full px-1.5 text-[11px] font-semibold",
+										isActive
+											? "bg-primary text-primary-foreground"
+											: "bg-muted text-muted-foreground"
+									)}
+								>
+									{formatNotificationCount(tab.count)}
+								</span>
+							</button>
+						);
+					})}
 				</div>
 
-				<div className="min-h-0 flex-1 overflow-y-auto p-2">
+				<div ref={scrollContainerRef} className="min-h-0 flex-1 overflow-y-auto p-2">
 					{isLoading ? (
 						<div className="space-y-1">
 							{[82, 64, 74].map((width) => (
@@ -364,11 +401,32 @@ export function NotificationsDropdown({
 									</Button>
 								);
 							})}
+							{hasMore ? (
+								<div
+									ref={loadMoreTriggerRef}
+									className="flex min-h-10 items-center justify-center py-2"
+								>
+									{isLoadingMore ? <Spinner size="xs" /> : null}
+								</div>
+							) : null}
 						</div>
 					) : (
 						<div className="flex flex-col items-center justify-center px-6 py-10 text-center">
 							<p className="text-sm font-medium">{emptyStateCopy.title}</p>
 							<p className="mt-1 text-xs text-muted-foreground">{emptyStateCopy.description}</p>
+							{hasMore ? (
+								<Button
+									type="button"
+									variant="ghost"
+									size="sm"
+									onClick={loadMoreForActiveFilter}
+									disabled={isLoadingMore}
+									className="mt-3 text-xs"
+								>
+									{isLoadingMore ? <Spinner size="xs" /> : null}
+									Load more
+								</Button>
+							) : null}
 						</div>
 					)}
 				</div>
diff --git a/surfsense_web/hooks/use-inbox.ts b/surfsense_web/hooks/use-inbox.ts
index 1caf73b1d..eb33f84f7 100644
--- a/surfsense_web/hooks/use-inbox.ts
+++ b/surfsense_web/hooks/use-inbox.ts
@@ -54,6 +54,7 @@ export function useInbox(
 	const [hasMore, setHasMore] = useState(false);
 	const [error, setError] = useState<Error | null>(null);
 	const [unreadCount, setUnreadCount] = useState(0);
+	const [totalCount, setTotalCount] = useState(0);
 
 	const initialLoadDoneRef = useRef(false);
 	const olderUnreadOffsetRef = useRef<number | null>(null);
@@ -71,6 +72,7 @@ export function useInbox(
 		setLoading(true);
 		setInboxItems([]);
 		setHasMore(false);
+		setTotalCount(0);
 		initialLoadDoneRef.current = false;
 		olderUnreadOffsetRef.current = null;
 		apiUnreadTotalRef.current = 0;
@@ -97,6 +99,7 @@ export function useInbox(
 				if (cancelled) return;
 
 				setInboxItems(notificationsResponse.items);
+				setTotalCount(notificationsResponse.total);
 				setHasMore(notificationsResponse.has_more);
 				setUnreadCount(unreadResponse.total_unread);
 				apiUnreadTotalRef.current = unreadResponse.total_unread;
@@ -222,6 +225,7 @@ export function useInbox(
 				const deduped = newItems.filter((d) => !existingIds.has(d.id));
 				return [...prev, ...deduped];
 			});
+			setTotalCount(response.total);
 			setHasMore(response.has_more);
 		} catch (err) {
 			console.error(`[useInbox:${category}] Load more failed:`, err);
@@ -299,6 +303,7 @@ export function useInbox(
 	return {
 		inboxItems,
 		unreadCount,
+		totalCount,
 		markAsRead,
 		markAllAsRead,
 		loading,

From c12790f091b184c4f29888772daf1460b2b6379a Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 20:55:58 +0530
Subject: [PATCH 04/27] feat(notifications): integrate Drawer for mobile
 notifications and enhance UI components

- Added Drawer component to NotificationsDropdown for improved mobile experience.
- Refactored notification trigger button and panel content for better accessibility and usability.
- Enhanced loading states and notification filtering options to streamline user interaction.
---
 .../ui/sidebar/NotificationsDropdown.tsx      | 341 ++++++++++--------
 1 file changed, 186 insertions(+), 155 deletions(-)

diff --git a/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
index 3ada5de46..bf3ce4322 100644
--- a/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
@@ -6,6 +6,13 @@ import { useRouter } from "next/navigation";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { setTargetCommentIdAtom } from "@/atoms/chat/current-thread.atom";
 import { Button } from "@/components/ui/button";
+import {
+	Drawer,
+	DrawerContent,
+	DrawerHandle,
+	DrawerTitle,
+	DrawerTrigger,
+} from "@/components/ui/drawer";
 import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
 import { Skeleton } from "@/components/ui/skeleton";
 import { Spinner } from "@/components/ui/spinner";
@@ -16,6 +23,7 @@ import {
 	isNewMentionMetadata,
 } from "@/contracts/types/inbox.types";
 import type { InboxItem } from "@/hooks/use-inbox";
+import { useIsMobile } from "@/hooks/use-mobile";
 import { cn } from "@/lib/utils";
 
 export interface NotificationsDataSource {
@@ -79,6 +87,7 @@ export function NotificationsDropdown({
 	onCloseMobileSidebar,
 }: NotificationsDropdownProps) {
 	const router = useRouter();
+	const isMobile = useIsMobile();
 	const [, setTargetCommentId] = useAtom(setTargetCommentIdAtom);
 	const [open, setOpen] = useState(false);
 	const [activeFilter, setActiveFilter] = useState<NotificationFilter>("all");
@@ -260,33 +269,186 @@ export function NotificationsDropdown({
 		{ value: "unread", label: "Unread", count: notifications.totalUnreadCount },
 	];
 
+	const triggerButton = (
+		<Button
+			type="button"
+			variant="ghost"
+			size="icon"
+			aria-label={
+				notifications.totalUnreadCount > 0
+					? `Notifications, ${unreadLabel} unread`
+					: "Notifications"
+			}
+			className={cn(
+				"relative h-10 w-10 rounded-lg text-muted-foreground hover:bg-accent hover:text-accent-foreground",
+				open && "bg-accent text-accent-foreground"
+			)}
+		>
+			<Bell className="h-4 w-4" />
+			{notifications.totalUnreadCount > 0 ? (
+				<span className="absolute right-1 top-1 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-destructive px-1 text-[10px] font-semibold leading-none text-destructive-foreground">
+					{unreadLabel}
+				</span>
+			) : null}
+		</Button>
+	);
+
+	const panelContent = (
+		<>
+			<div className="flex shrink-0 items-center justify-between gap-3 border-b px-4 py-3">
+				<div className="min-w-0">
+					<h2 className="text-base font-semibold">Notifications</h2>
+				</div>
+				<Button
+					type="button"
+					variant="ghost"
+					size="sm"
+					onClick={handleMarkAllAsRead}
+					disabled={visibleUnreadCount === 0 || markingAllAsRead}
+					className="h-8 shrink-0 gap-1.5 px-2 text-xs text-muted-foreground hover:text-accent-foreground"
+				>
+					{markingAllAsRead ? <Spinner size="xs" /> : null}
+					Mark all read
+				</Button>
+			</div>
+
+			<div className="relative flex shrink-0 items-end gap-4 px-4 after:absolute after:inset-x-0 after:bottom-0 after:z-0 after:h-px after:bg-muted-foreground/25 after:content-['']">
+				{tabs.map((tab) => {
+					const isActive = activeFilter === tab.value;
+					return (
+						<button
+							key={tab.value}
+							type="button"
+							aria-pressed={isActive}
+							onClick={() => setActiveFilter(tab.value)}
+							className={cn(
+								"relative z-10 flex h-11 items-center gap-2 border-b-2 border-transparent px-0 text-sm font-medium text-muted-foreground transition-colors",
+								"hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+								isActive && "border-primary text-primary"
+							)}
+						>
+							<span>{tab.label}</span>
+							<span
+								className={cn(
+									"inline-flex h-5 min-w-5 items-center justify-center rounded-full px-1.5 text-[11px] font-semibold",
+									isActive ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground"
+								)}
+							>
+								{formatNotificationCount(tab.count)}
+							</span>
+						</button>
+					);
+				})}
+			</div>
+
+			<div ref={scrollContainerRef} className="min-h-0 flex-1 overflow-y-auto p-2">
+				{isLoading ? (
+					<div className="space-y-1">
+						{[82, 64, 74].map((width) => (
+							<div key={width} className="flex h-[72px] items-center rounded-lg px-2 py-2">
+								<div className="min-w-0 flex-1 space-y-2">
+									<Skeleton className="h-3 rounded" style={{ width: `${width}%` }} />
+									<Skeleton className="h-2.5 w-1/2 rounded" />
+								</div>
+							</div>
+						))}
+					</div>
+				) : items.length > 0 ? (
+					<div className="space-y-1">
+						{items.map((item) => {
+							const isMarkingAsRead = markingAsReadId === item.id;
+							return (
+								<Button
+									key={item.id}
+									type="button"
+									variant="ghost"
+									disabled={isMarkingAsRead}
+									onClick={() => handleItemClick(item)}
+									className={cn(
+										"group h-auto w-full justify-start rounded-lg px-2 py-2 text-left",
+										"hover:bg-accent hover:text-accent-foreground",
+										!item.read && "bg-accent/40"
+									)}
+									style={{ contentVisibility: "auto", containIntrinsicSize: "0 72px" }}
+								>
+									<div className="min-w-0 flex-1">
+										<div className="flex min-w-0 items-start gap-2">
+											<p
+												className={cn(
+													"line-clamp-1 flex-1 text-sm font-medium",
+													!item.read && "font-semibold"
+												)}
+											>
+												{item.title}
+											</p>
+											{!item.read ? (
+												<span className="mt-1.5 h-1.5 w-1.5 shrink-0 rounded-full bg-primary" />
+											) : null}
+										</div>
+										<p className="mt-0.5 line-clamp-2 text-xs font-normal text-muted-foreground group-hover:text-accent-foreground/80">
+											{item.message}
+										</p>
+										<p className="mt-1 text-[11px] font-normal text-muted-foreground/70">
+											{formatTime(item.created_at)}
+										</p>
+									</div>
+									{isMarkingAsRead ? <Spinner size="xs" className="shrink-0" /> : null}
+								</Button>
+							);
+						})}
+						{hasMore ? (
+							<div
+								ref={loadMoreTriggerRef}
+								className="flex min-h-10 items-center justify-center py-2"
+							>
+								{isLoadingMore ? <Spinner size="xs" /> : null}
+							</div>
+						) : null}
+					</div>
+				) : (
+					<div className="flex flex-col items-center justify-center px-6 py-10 text-center">
+						<p className="text-sm font-medium">{emptyStateCopy.title}</p>
+						<p className="mt-1 text-xs text-muted-foreground">{emptyStateCopy.description}</p>
+						{hasMore ? (
+							<Button
+								type="button"
+								variant="ghost"
+								size="sm"
+								onClick={loadMoreForActiveFilter}
+								disabled={isLoadingMore}
+								className="mt-3 text-xs"
+							>
+								{isLoadingMore ? <Spinner size="xs" /> : null}
+								Load more
+							</Button>
+						) : null}
+					</div>
+				)}
+			</div>
+		</>
+	);
+
+	if (isMobile) {
+		return (
+			<Drawer open={open} onOpenChange={setOpen} shouldScaleBackground={false}>
+				<DrawerTrigger asChild>{triggerButton}</DrawerTrigger>
+				<DrawerContent
+					className="z-80 h-[78vh] max-h-[90vh] overflow-hidden rounded-t-2xl border bg-popover text-popover-foreground"
+					overlayClassName="z-80"
+				>
+					<DrawerHandle className="mt-3 h-1.5 w-10" />
+					<DrawerTitle className="sr-only">Notifications</DrawerTitle>
+					<div className="flex min-h-0 flex-1 flex-col">{panelContent}</div>
+				</DrawerContent>
+			</Drawer>
+		);
+	}
+
 	return (
 		<Popover open={open} onOpenChange={setOpen}>
 			<Tooltip>
 				<TooltipTrigger asChild>
-					<PopoverTrigger asChild>
-						<Button
-							type="button"
-							variant="ghost"
-							size="icon"
-							aria-label={
-								notifications.totalUnreadCount > 0
-									? `Notifications, ${unreadLabel} unread`
-									: "Notifications"
-							}
-							className={cn(
-								"relative h-10 w-10 rounded-lg text-muted-foreground hover:bg-accent hover:text-accent-foreground",
-								open && "bg-accent text-accent-foreground"
-							)}
-						>
-							<Bell className="h-4 w-4" />
-							{notifications.totalUnreadCount > 0 ? (
-								<span className="absolute right-1 top-1 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-destructive px-1 text-[10px] font-semibold leading-none text-destructive-foreground">
-									{unreadLabel}
-								</span>
-							) : null}
-						</Button>
-					</PopoverTrigger>
+					<PopoverTrigger asChild>{triggerButton}</PopoverTrigger>
 				</TooltipTrigger>
 				<TooltipContent side="right" sideOffset={8}>
 					Notifications
@@ -298,138 +460,7 @@ export function NotificationsDropdown({
 				sideOffset={10}
 				className="z-80 flex max-h-[min(520px,calc(100vh-2rem))] w-[360px] flex-col overflow-hidden rounded-xl border bg-popover p-0 text-popover-foreground shadow-lg"
 			>
-				<div className="flex shrink-0 items-center justify-between gap-3 border-b px-4 py-3">
-					<div className="min-w-0">
-						<h2 className="text-base font-semibold">Notifications</h2>
-					</div>
-					<Button
-						type="button"
-						variant="ghost"
-						size="sm"
-						onClick={handleMarkAllAsRead}
-						disabled={visibleUnreadCount === 0 || markingAllAsRead}
-						className="h-8 shrink-0 gap-1.5 px-2 text-xs text-muted-foreground hover:text-accent-foreground"
-					>
-						{markingAllAsRead ? <Spinner size="xs" /> : null}
-						Mark all read
-					</Button>
-				</div>
-
-				<div className="relative flex shrink-0 items-end gap-4 px-4 after:absolute after:inset-x-0 after:bottom-0 after:z-0 after:h-px after:bg-muted-foreground/25 after:content-['']">
-					{tabs.map((tab) => {
-						const isActive = activeFilter === tab.value;
-						return (
-							<button
-								key={tab.value}
-								type="button"
-								aria-pressed={isActive}
-								onClick={() => setActiveFilter(tab.value)}
-								className={cn(
-									"relative z-10 flex h-11 items-center gap-2 border-b-2 border-transparent px-0 text-sm font-medium text-muted-foreground transition-colors",
-									"hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
-									isActive && "border-primary text-primary"
-								)}
-							>
-								<span>{tab.label}</span>
-								<span
-									className={cn(
-										"inline-flex h-5 min-w-5 items-center justify-center rounded-full px-1.5 text-[11px] font-semibold",
-										isActive
-											? "bg-primary text-primary-foreground"
-											: "bg-muted text-muted-foreground"
-									)}
-								>
-									{formatNotificationCount(tab.count)}
-								</span>
-							</button>
-						);
-					})}
-				</div>
-
-				<div ref={scrollContainerRef} className="min-h-0 flex-1 overflow-y-auto p-2">
-					{isLoading ? (
-						<div className="space-y-1">
-							{[82, 64, 74].map((width) => (
-								<div key={width} className="flex h-[72px] items-center rounded-lg px-2 py-2">
-									<div className="min-w-0 flex-1 space-y-2">
-										<Skeleton className="h-3 rounded" style={{ width: `${width}%` }} />
-										<Skeleton className="h-2.5 w-1/2 rounded" />
-									</div>
-								</div>
-							))}
-						</div>
-					) : items.length > 0 ? (
-						<div className="space-y-1">
-							{items.map((item) => {
-								const isMarkingAsRead = markingAsReadId === item.id;
-								return (
-									<Button
-										key={item.id}
-										type="button"
-										variant="ghost"
-										disabled={isMarkingAsRead}
-										onClick={() => handleItemClick(item)}
-										className={cn(
-											"group h-auto w-full justify-start rounded-lg px-2 py-2 text-left",
-											"hover:bg-accent hover:text-accent-foreground",
-											!item.read && "bg-accent/40"
-										)}
-										style={{ contentVisibility: "auto", containIntrinsicSize: "0 72px" }}
-									>
-										<div className="min-w-0 flex-1">
-											<div className="flex min-w-0 items-start gap-2">
-												<p
-													className={cn(
-														"line-clamp-1 flex-1 text-sm font-medium",
-														!item.read && "font-semibold"
-													)}
-												>
-													{item.title}
-												</p>
-												{!item.read ? (
-													<span className="mt-1.5 h-1.5 w-1.5 shrink-0 rounded-full bg-primary" />
-												) : null}
-											</div>
-											<p className="mt-0.5 line-clamp-2 text-xs font-normal text-muted-foreground group-hover:text-accent-foreground/80">
-												{item.message}
-											</p>
-											<p className="mt-1 text-[11px] font-normal text-muted-foreground/70">
-												{formatTime(item.created_at)}
-											</p>
-										</div>
-										{isMarkingAsRead ? <Spinner size="xs" className="shrink-0" /> : null}
-									</Button>
-								);
-							})}
-							{hasMore ? (
-								<div
-									ref={loadMoreTriggerRef}
-									className="flex min-h-10 items-center justify-center py-2"
-								>
-									{isLoadingMore ? <Spinner size="xs" /> : null}
-								</div>
-							) : null}
-						</div>
-					) : (
-						<div className="flex flex-col items-center justify-center px-6 py-10 text-center">
-							<p className="text-sm font-medium">{emptyStateCopy.title}</p>
-							<p className="mt-1 text-xs text-muted-foreground">{emptyStateCopy.description}</p>
-							{hasMore ? (
-								<Button
-									type="button"
-									variant="ghost"
-									size="sm"
-									onClick={loadMoreForActiveFilter}
-									disabled={isLoadingMore}
-									className="mt-3 text-xs"
-								>
-									{isLoadingMore ? <Spinner size="xs" /> : null}
-									Load more
-								</Button>
-							) : null}
-						</div>
-					)}
-				</div>
+				{panelContent}
 			</PopoverContent>
 		</Popover>
 	);

From 80a6b054781091e959a6962aa360525359c81dfa Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 21:28:32 +0530
Subject: [PATCH 05/27] refactor(sidebar): enhance MobileSidebar and
 SidebarUserProfile UI

- Updated MobileSidebar to include a right border for improved visual separation.
- Modified SidebarUserProfile to add a relative positioning and a top border for better layout consistency.
---
 surfsense_web/components/layout/ui/sidebar/MobileSidebar.tsx    | 2 +-
 .../components/layout/ui/sidebar/SidebarUserProfile.tsx         | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/surfsense_web/components/layout/ui/sidebar/MobileSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/MobileSidebar.tsx
index 94fe2d413..1d02b56f4 100644
--- a/surfsense_web/components/layout/ui/sidebar/MobileSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/MobileSidebar.tsx
@@ -176,7 +176,7 @@ export function MobileSidebar({
 				</div>
 
 				{/* Sidebar Content - right side */}
-				<div className="flex-1 overflow-hidden flex flex-col [&>*]:!w-full">
+				<div className="flex-1 overflow-hidden flex flex-col border-r [&>*]:!w-full">
 					<Sidebar
 						workspace={workspace}
 						isCollapsed={false}
diff --git a/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx b/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
index 0fc9b769b..a2cf4f3e3 100644
--- a/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
@@ -172,7 +172,7 @@ export function SidebarUserProfile({
 	// Collapsed view - just show avatar with dropdown
 	if (isCollapsed) {
 		return (
-			<div className="w-full border-t px-1.5 py-2">
+			<div className="relative w-full px-1.5 py-2 before:absolute before:inset-x-3 before:top-0 before:h-px before:bg-border">
 				<div className="flex flex-col items-center gap-2">
 					{topContent}
 					{showDownloadCta && (

From 24613533123ddb34c1d3290eb25ea258e6561c14 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 21:36:18 +0530
Subject: [PATCH 06/27] feat(sidebar): implement mobile submenus in
 SidebarUserProfile

- Added mobile submenus for theme, language, and learn more options in SidebarUserProfile.
- Integrated Drawer component for improved mobile navigation experience.
- Enhanced UI with new dropdown items and improved accessibility for user settings.
---
 .../layout/ui/sidebar/SidebarUserProfile.tsx  | 414 +++++++++++-------
 1 file changed, 251 insertions(+), 163 deletions(-)

diff --git a/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx b/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
index a2cf4f3e3..09fb3f6d0 100644
--- a/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
@@ -2,6 +2,7 @@
 
 import {
 	Check,
+	ChevronRight,
 	ChevronUp,
 	Download,
 	ExternalLink,
@@ -17,8 +18,9 @@ import {
 import Image from "next/image";
 import { useTranslations } from "next-intl";
 import type React from "react";
-import { useState } from "react";
+import { Fragment, useState } from "react";
 import { Button } from "@/components/ui/button";
+import { Drawer, DrawerContent, DrawerHandle, DrawerTitle } from "@/components/ui/drawer";
 import {
 	DropdownMenu,
 	DropdownMenuContent,
@@ -64,6 +66,8 @@ const LEARN_MORE_LINKS = [
 	{ key: "github" as const, href: "https://github.com/MODSetter/SurfSense" },
 ];
 
+type MobileProfileSubmenu = "theme" | "language" | "learn_more";
+
 interface SidebarUserProfileProps {
 	user: User;
 	onUserSettings?: () => void;
@@ -144,12 +148,14 @@ export function SidebarUserProfile({
 	const isDesktopViewport = useMediaQuery("(min-width: 768px)");
 	const { os, primary, isMobileOS } = usePrimaryDownload();
 	const [isLoggingOut, setIsLoggingOut] = useState(false);
+	const [mobileSubmenu, setMobileSubmenu] = useState<MobileProfileSubmenu | null>(null);
 	const bgColor = getUserAvatarColor(user.email);
 	const initials = getUserInitials(user.email);
 	const displayName = user.name || user.email.split("@")[0];
 	const downloadUrl = primary?.url ?? GITHUB_RELEASES_URL;
 	const downloadLabel = t("download_for_os", { os });
 	const showDownloadCta = !isDesktop && !isMobileOS && isDesktopViewport;
+	const useMobileSubmenus = !isDesktopViewport;
 
 	const handleLanguageChange = (newLocale: "en" | "es" | "pt" | "hi" | "zh") => {
 		setLocale(newLocale);
@@ -169,6 +175,242 @@ export function SidebarUserProfile({
 		}
 	};
 
+	const submenuTriggerClassName = "cursor-default";
+	const drawerItemClassName = cn(
+		"flex h-12 w-full items-center gap-3 rounded-lg px-3 text-left text-sm transition-colors",
+		"hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+	);
+	const drawerSeparatorClassName = "mx-3 h-px bg-popover-border";
+
+	const renderThemeSubmenu = () => {
+		if (!setTheme) return null;
+
+		if (useMobileSubmenus) {
+			return (
+				<DropdownMenuItem
+					className={submenuTriggerClassName}
+					onSelect={() => setMobileSubmenu("theme")}
+				>
+					<Sun className="h-4 w-4" />
+					<span className="flex-1">{t("theme")}</span>
+					<ChevronRight className="h-4 w-4 text-muted-foreground" />
+				</DropdownMenuItem>
+			);
+		}
+
+		return (
+			<DropdownMenuSub>
+				<DropdownMenuSubTrigger>
+					<Sun className="h-4 w-4" />
+					{t("theme")}
+				</DropdownMenuSubTrigger>
+				<DropdownMenuPortal>
+					<DropdownMenuSubContent className="gap-1">
+						{THEMES.map((themeOption) => {
+							const Icon = themeOption.icon;
+							const isSelected = theme === themeOption.value;
+							return (
+								<DropdownMenuItem
+									key={themeOption.value}
+									onClick={() => handleThemeChange(themeOption.value)}
+									className={cn(
+										"mb-1 last:mb-0 transition-all",
+										"hover:bg-accent hover:text-accent-foreground",
+										isSelected && "text-primary"
+									)}
+								>
+									<Icon className="h-4 w-4" />
+									<span className="flex-1">{t(themeOption.value)}</span>
+									{isSelected && <Check className="h-4 w-4 shrink-0" />}
+								</DropdownMenuItem>
+							);
+						})}
+					</DropdownMenuSubContent>
+				</DropdownMenuPortal>
+			</DropdownMenuSub>
+		);
+	};
+
+	const renderLanguageSubmenu = () => {
+		if (useMobileSubmenus) {
+			return (
+				<DropdownMenuItem
+					className={submenuTriggerClassName}
+					onSelect={() => setMobileSubmenu("language")}
+				>
+					<Languages className="h-4 w-4" />
+					<span className="flex-1">{t("language")}</span>
+					<ChevronRight className="h-4 w-4 text-muted-foreground" />
+				</DropdownMenuItem>
+			);
+		}
+
+		return (
+			<DropdownMenuSub>
+				<DropdownMenuSubTrigger>
+					<Languages className="h-4 w-4" />
+					{t("language")}
+				</DropdownMenuSubTrigger>
+				<DropdownMenuPortal>
+					<DropdownMenuSubContent className="gap-1">
+						{LANGUAGES.map((language) => {
+							const isSelected = locale === language.code;
+							return (
+								<DropdownMenuItem
+									key={language.code}
+									onClick={() => handleLanguageChange(language.code)}
+									className={cn(
+										"mb-1 last:mb-0 transition-all",
+										"hover:bg-accent hover:text-accent-foreground",
+										isSelected && "text-primary"
+									)}
+								>
+									<span className="mr-2">{language.flag}</span>
+									<span className="flex-1">{language.name}</span>
+									{isSelected && <Check className="h-4 w-4 shrink-0" />}
+								</DropdownMenuItem>
+							);
+						})}
+					</DropdownMenuSubContent>
+				</DropdownMenuPortal>
+			</DropdownMenuSub>
+		);
+	};
+
+	const renderLearnMoreSubmenu = () => {
+		if (useMobileSubmenus) {
+			return (
+				<DropdownMenuItem
+					className={submenuTriggerClassName}
+					onSelect={() => setMobileSubmenu("learn_more")}
+				>
+					<Info className="h-4 w-4" />
+					<span className="flex-1">{t("learn_more")}</span>
+					<ChevronRight className="h-4 w-4 text-muted-foreground" />
+				</DropdownMenuItem>
+			);
+		}
+
+		return (
+			<DropdownMenuSub>
+				<DropdownMenuSubTrigger>
+					<Info className="h-4 w-4" />
+					{t("learn_more")}
+				</DropdownMenuSubTrigger>
+				<DropdownMenuPortal>
+					<DropdownMenuSubContent className="min-w-[180px] gap-1">
+						{LEARN_MORE_LINKS.map((link) => (
+							<DropdownMenuItem key={link.key} asChild>
+								<a href={link.href} target="_blank" rel="noopener noreferrer">
+									<span className="flex-1">{t(link.key)}</span>
+									<ExternalLink className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+								</a>
+							</DropdownMenuItem>
+						))}
+						<DropdownMenuSeparator />
+						<p className="select-none px-2 py-1 text-xs leading-tight text-muted-foreground/50">
+							v{APP_VERSION}
+						</p>
+					</DropdownMenuSubContent>
+				</DropdownMenuPortal>
+			</DropdownMenuSub>
+		);
+	};
+
+	const mobileSubmenuDrawer = (
+		<Drawer
+			open={mobileSubmenu !== null}
+			onOpenChange={(open) => {
+				if (!open) setMobileSubmenu(null);
+			}}
+			shouldScaleBackground={false}
+		>
+			<DrawerContent
+				className="z-80 max-h-[75vh] rounded-t-2xl border bg-popover text-popover-foreground"
+				overlayClassName="z-80"
+			>
+				<DrawerHandle className="mt-3 h-1.5 w-10" />
+				<DrawerTitle className="px-4 pb-2 pt-3 text-center text-base font-semibold">
+					{mobileSubmenu === "theme"
+						? t("theme")
+						: mobileSubmenu === "language"
+							? t("language")
+							: t("learn_more")}
+				</DrawerTitle>
+				<div className="space-y-1 px-4 pb-6 pt-1">
+					{mobileSubmenu === "theme" &&
+						setTheme &&
+						THEMES.map((themeOption, index) => {
+							const Icon = themeOption.icon;
+							const isSelected = theme === themeOption.value;
+							return (
+								<Fragment key={themeOption.value}>
+									{index > 0 && <div className={drawerSeparatorClassName} />}
+									<button
+										type="button"
+										className={cn(drawerItemClassName, isSelected && "text-primary")}
+										onClick={() => {
+											handleThemeChange(themeOption.value);
+											setMobileSubmenu(null);
+										}}
+									>
+										<Icon className="h-4 w-4 text-muted-foreground" />
+										<span className="flex-1">{t(themeOption.value)}</span>
+										{isSelected && <Check className="h-4 w-4 shrink-0" />}
+									</button>
+								</Fragment>
+							);
+						})}
+
+					{mobileSubmenu === "language" &&
+						LANGUAGES.map((language, index) => {
+							const isSelected = locale === language.code;
+							return (
+								<Fragment key={language.code}>
+									{index > 0 && <div className={drawerSeparatorClassName} />}
+									<button
+										type="button"
+										className={cn(drawerItemClassName, isSelected && "text-primary")}
+										onClick={() => {
+											handleLanguageChange(language.code);
+											setMobileSubmenu(null);
+										}}
+									>
+										<span className="text-base">{language.flag}</span>
+										<span className="flex-1">{language.name}</span>
+										{isSelected && <Check className="h-4 w-4 shrink-0" />}
+									</button>
+								</Fragment>
+							);
+						})}
+
+					{mobileSubmenu === "learn_more" && (
+						<>
+							{LEARN_MORE_LINKS.map((link, index) => (
+								<Fragment key={link.key}>
+									{index > 0 && <div className={drawerSeparatorClassName} />}
+									<a
+										href={link.href}
+										target="_blank"
+										rel="noopener noreferrer"
+										className={drawerItemClassName}
+										onClick={() => setMobileSubmenu(null)}
+									>
+										<span className="flex-1">{t(link.key)}</span>
+										<ExternalLink className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+									</a>
+								</Fragment>
+							))}
+							<p className="select-none px-3 py-1 text-xs leading-tight text-muted-foreground/50">
+								v{APP_VERSION}
+							</p>
+						</>
+					)}
+				</div>
+			</DrawerContent>
+		</Drawer>
+	);
+
 	// Collapsed view - just show avatar with dropdown
 	if (isCollapsed) {
 		return (
@@ -251,89 +493,11 @@ export function SidebarUserProfile({
 								</DropdownMenuItem>
 							)}
 
-							{setTheme && (
-								<DropdownMenuSub>
-									<DropdownMenuSubTrigger>
-										<Sun className="h-4 w-4" />
-										{t("theme")}
-									</DropdownMenuSubTrigger>
-									<DropdownMenuPortal>
-										<DropdownMenuSubContent className="gap-1">
-											{THEMES.map((themeOption) => {
-												const Icon = themeOption.icon;
-												const isSelected = theme === themeOption.value;
-												return (
-													<DropdownMenuItem
-														key={themeOption.value}
-														onClick={() => handleThemeChange(themeOption.value)}
-														className={cn(
-															"mb-1 last:mb-0 transition-all",
-															"hover:bg-accent hover:text-accent-foreground",
-															isSelected && "text-primary"
-														)}
-													>
-														<Icon className="h-4 w-4" />
-														<span className="flex-1">{t(themeOption.value)}</span>
-														{isSelected && <Check className="h-4 w-4 shrink-0" />}
-													</DropdownMenuItem>
-												);
-											})}
-										</DropdownMenuSubContent>
-									</DropdownMenuPortal>
-								</DropdownMenuSub>
-							)}
+							{renderThemeSubmenu()}
 
-							<DropdownMenuSub>
-								<DropdownMenuSubTrigger>
-									<Languages className="h-4 w-4" />
-									{t("language")}
-								</DropdownMenuSubTrigger>
-								<DropdownMenuPortal>
-									<DropdownMenuSubContent className="gap-1">
-										{LANGUAGES.map((language) => {
-											const isSelected = locale === language.code;
-											return (
-												<DropdownMenuItem
-													key={language.code}
-													onClick={() => handleLanguageChange(language.code)}
-													className={cn(
-														"mb-1 last:mb-0 transition-all",
-														"hover:bg-accent hover:text-accent-foreground",
-														isSelected && "text-primary"
-													)}
-												>
-													<span className="mr-2">{language.flag}</span>
-													<span className="flex-1">{language.name}</span>
-													{isSelected && <Check className="h-4 w-4 shrink-0" />}
-												</DropdownMenuItem>
-											);
-										})}
-									</DropdownMenuSubContent>
-								</DropdownMenuPortal>
-							</DropdownMenuSub>
+							{renderLanguageSubmenu()}
 
-							<DropdownMenuSub>
-								<DropdownMenuSubTrigger>
-									<Info className="h-4 w-4" />
-									{t("learn_more")}
-								</DropdownMenuSubTrigger>
-								<DropdownMenuPortal>
-									<DropdownMenuSubContent className="min-w-[180px] gap-1">
-										{LEARN_MORE_LINKS.map((link) => (
-											<DropdownMenuItem key={link.key} asChild>
-												<a href={link.href} target="_blank" rel="noopener noreferrer">
-													<span className="flex-1">{t(link.key)}</span>
-													<ExternalLink className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
-												</a>
-											</DropdownMenuItem>
-										))}
-										<DropdownMenuSeparator />
-										<p className="select-none px-2 py-1 text-xs leading-tight text-muted-foreground/50">
-											v{APP_VERSION}
-										</p>
-									</DropdownMenuSubContent>
-								</DropdownMenuPortal>
-							</DropdownMenuSub>
+							{renderLearnMoreSubmenu()}
 
 							{!isDesktop && !isMobileOS && (
 								<DropdownMenuItem asChild className="font-medium">
@@ -356,6 +520,7 @@ export function SidebarUserProfile({
 							</DropdownMenuItem>
 						</DropdownMenuContent>
 					</DropdownMenu>
+					{mobileSubmenuDrawer}
 				</div>
 			</div>
 		);
@@ -433,89 +598,11 @@ export function SidebarUserProfile({
 						</DropdownMenuItem>
 					)}
 
-					{setTheme && (
-						<DropdownMenuSub>
-							<DropdownMenuSubTrigger>
-								<Sun className="h-4 w-4" />
-								{t("theme")}
-							</DropdownMenuSubTrigger>
-							<DropdownMenuPortal>
-								<DropdownMenuSubContent className="gap-1">
-									{THEMES.map((themeOption) => {
-										const Icon = themeOption.icon;
-										const isSelected = theme === themeOption.value;
-										return (
-											<DropdownMenuItem
-												key={themeOption.value}
-												onClick={() => handleThemeChange(themeOption.value)}
-												className={cn(
-													"mb-1 last:mb-0 transition-all",
-													"hover:bg-accent hover:text-accent-foreground",
-													isSelected && "text-primary"
-												)}
-											>
-												<Icon className="h-4 w-4" />
-												<span className="flex-1">{t(themeOption.value)}</span>
-												{isSelected && <Check className="h-4 w-4 shrink-0" />}
-											</DropdownMenuItem>
-										);
-									})}
-								</DropdownMenuSubContent>
-							</DropdownMenuPortal>
-						</DropdownMenuSub>
-					)}
+					{renderThemeSubmenu()}
 
-					<DropdownMenuSub>
-						<DropdownMenuSubTrigger>
-							<Languages className="h-4 w-4" />
-							{t("language")}
-						</DropdownMenuSubTrigger>
-						<DropdownMenuPortal>
-							<DropdownMenuSubContent className="gap-1">
-								{LANGUAGES.map((language) => {
-									const isSelected = locale === language.code;
-									return (
-										<DropdownMenuItem
-											key={language.code}
-											onClick={() => handleLanguageChange(language.code)}
-											className={cn(
-												"mb-1 last:mb-0 transition-all",
-												"hover:bg-accent hover:text-accent-foreground",
-												isSelected && "text-primary"
-											)}
-										>
-											<span className="mr-2">{language.flag}</span>
-											<span className="flex-1">{language.name}</span>
-											{isSelected && <Check className="h-4 w-4 shrink-0" />}
-										</DropdownMenuItem>
-									);
-								})}
-							</DropdownMenuSubContent>
-						</DropdownMenuPortal>
-					</DropdownMenuSub>
+					{renderLanguageSubmenu()}
 
-					<DropdownMenuSub>
-						<DropdownMenuSubTrigger>
-							<Info className="h-4 w-4" />
-							{t("learn_more")}
-						</DropdownMenuSubTrigger>
-						<DropdownMenuPortal>
-							<DropdownMenuSubContent className="min-w-[180px] gap-1">
-								{LEARN_MORE_LINKS.map((link) => (
-									<DropdownMenuItem key={link.key} asChild>
-										<a href={link.href} target="_blank" rel="noopener noreferrer">
-											<span className="flex-1">{t(link.key)}</span>
-											<ExternalLink className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
-										</a>
-									</DropdownMenuItem>
-								))}
-								<DropdownMenuSeparator />
-								<p className="select-none px-2 py-1 text-xs leading-tight text-muted-foreground/50">
-									v{APP_VERSION}
-								</p>
-							</DropdownMenuSubContent>
-						</DropdownMenuPortal>
-					</DropdownMenuSub>
+					{renderLearnMoreSubmenu()}
 
 					{!isDesktop && (
 						<DropdownMenuItem asChild className="font-medium">
@@ -534,6 +621,7 @@ export function SidebarUserProfile({
 					</DropdownMenuItem>
 				</DropdownMenuContent>
 			</DropdownMenu>
+			{mobileSubmenuDrawer}
 		</div>
 	);
 }

From b911a36bcf454174bc70fb173d6a1a10733d3971 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 21:58:47 +0530
Subject: [PATCH 07/27] feat(sidebar): enhance document filtering with Drawer
 component

- Integrated Drawer component in EmbeddedDocumentsMenu for mobile-friendly document type filtering.
- Updated UI to improve accessibility and user experience with new button interactions and layout adjustments.
- Refactored document type display logic to streamline filtering options and enhance visual clarity.
---
 .../layout/ui/sidebar/DocumentsSidebar.tsx    | 140 ++++++++++++------
 .../components/layout/ui/sidebar/Sidebar.tsx  |   9 +-
 2 files changed, 105 insertions(+), 44 deletions(-)

diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index a5b67ae7d..5d4efac81 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -3,6 +3,7 @@
 import { useQuery } from "@rocicorp/zero/react";
 import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import {
+	Check,
 	FolderInput,
 	FolderPlus,
 	FolderSync,
@@ -50,6 +51,7 @@ import {
 	AlertDialogTitle,
 } from "@/components/ui/alert-dialog";
 import { Button } from "@/components/ui/button";
+import { Drawer, DrawerContent, DrawerHandle, DrawerTitle } from "@/components/ui/drawer";
 import {
 	DropdownMenu,
 	DropdownMenuCheckboxItem,
@@ -69,6 +71,7 @@ import { EnumConnectorName } from "@/contracts/enums/connector";
 import { getConnectorIcon } from "@/contracts/enums/connectorIcons";
 import type { SearchSourceConnector } from "@/contracts/types/connector.types";
 import type { DocumentTypeEnum } from "@/contracts/types/document.types";
+import { useIsMobile } from "@/hooks/use-mobile";
 import { useElectronAPI, usePlatform } from "@/hooks/use-platform";
 import { documentsApiService } from "@/lib/apis/documents-api.service";
 import { foldersApiService } from "@/lib/apis/folders-api.service";
@@ -127,60 +130,111 @@ export function EmbeddedDocumentsMenu({
 	onToggleType: (type: DocumentTypeEnum, checked: boolean) => void;
 	onCreateFolder: () => void;
 }) {
+	const isMobile = useIsMobile();
+	const [filterDrawerOpen, setFilterDrawerOpen] = useState(false);
 	const documentTypes = useMemo(
 		() => Object.keys(typeCounts).sort() as DocumentTypeEnum[],
 		[typeCounts]
 	);
 
 	return (
-		<DropdownMenu>
-			<DropdownMenuTrigger asChild>
-				<Button
-					type="button"
-					variant="ghost"
-					size="icon"
-					className="relative h-7 w-7 text-muted-foreground hover:bg-accent hover:text-accent-foreground"
-					aria-label="Document actions"
+		<>
+			<DropdownMenu>
+				<DropdownMenuTrigger asChild>
+					<Button
+						type="button"
+						variant="ghost"
+						size="icon"
+						className="relative h-7 w-7 text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+						aria-label="Document actions"
+					>
+						<SlidersVertical className="h-3.5 w-3.5" />
+						{activeTypes.length > 0 ? (
+							<span className="absolute right-0.5 top-0.5 h-1.5 w-1.5 rounded-full bg-primary" />
+						) : null}
+					</Button>
+				</DropdownMenuTrigger>
+				<DropdownMenuContent align="end" className="w-44">
+					<DropdownMenuItem onSelect={onCreateFolder}>
+						<FolderPlus className="h-4 w-4" />
+						New folder
+					</DropdownMenuItem>
+					{isMobile ? (
+						<DropdownMenuItem onSelect={() => setFilterDrawerOpen(true)}>
+							<ListFilter className="h-4 w-4" />
+							<span className="flex-1">Filter by type</span>
+						</DropdownMenuItem>
+					) : (
+						<DropdownMenuSub>
+							<DropdownMenuSubTrigger>
+								<ListFilter className="h-4 w-4" />
+								Filter by type
+							</DropdownMenuSubTrigger>
+							<DropdownMenuSubContent className="w-52 max-h-72 overflow-y-auto">
+								{documentTypes.length > 0 ? (
+									documentTypes.map((type) => (
+										<DropdownMenuCheckboxItem
+											key={type}
+											checked={activeTypes.includes(type)}
+											onCheckedChange={(checked) => onToggleType(type, checked === true)}
+											onSelect={(event) => event.preventDefault()}
+										>
+											{getDocumentTypeIcon(type, "h-4 w-4")}
+											<span className="min-w-0 flex-1 truncate">{getDocumentTypeLabel(type)}</span>
+											<span className="ml-auto text-xs text-muted-foreground">
+												{typeCounts[type] ?? 0}
+											</span>
+										</DropdownMenuCheckboxItem>
+									))
+								) : (
+									<DropdownMenuItem disabled>No document types</DropdownMenuItem>
+								)}
+							</DropdownMenuSubContent>
+						</DropdownMenuSub>
+					)}
+				</DropdownMenuContent>
+			</DropdownMenu>
+
+			<Drawer
+				open={filterDrawerOpen}
+				onOpenChange={setFilterDrawerOpen}
+				shouldScaleBackground={false}
+			>
+				<DrawerContent
+					className="z-80 max-h-[75vh] rounded-t-2xl border bg-popover text-popover-foreground"
+					overlayClassName="z-80"
 				>
-					<SlidersVertical className="h-3.5 w-3.5" />
-					{activeTypes.length > 0 ? (
-						<span className="absolute right-0.5 top-0.5 h-1.5 w-1.5 rounded-full bg-primary" />
-					) : null}
-				</Button>
-			</DropdownMenuTrigger>
-			<DropdownMenuContent align="end" className="w-44">
-				<DropdownMenuItem onSelect={onCreateFolder}>
-					<FolderPlus className="h-4 w-4" />
-					New folder
-				</DropdownMenuItem>
-				<DropdownMenuSub>
-					<DropdownMenuSubTrigger>
-						<ListFilter className="h-4 w-4" />
+					<DrawerHandle className="mt-3 h-1.5 w-10" />
+					<DrawerTitle className="px-4 pb-2 pt-3 text-center text-base font-semibold">
 						Filter by type
-					</DropdownMenuSubTrigger>
-					<DropdownMenuSubContent className="w-52 max-h-72 overflow-y-auto">
+					</DrawerTitle>
+					<div className="px-4 pb-6 pt-1">
 						{documentTypes.length > 0 ? (
-							documentTypes.map((type) => (
-								<DropdownMenuCheckboxItem
-									key={type}
-									checked={activeTypes.includes(type)}
-									onCheckedChange={(checked) => onToggleType(type, checked === true)}
-									onSelect={(event) => event.preventDefault()}
-								>
-									{getDocumentTypeIcon(type, "h-4 w-4")}
-									<span className="min-w-0 flex-1 truncate">{getDocumentTypeLabel(type)}</span>
-									<span className="ml-auto text-xs text-muted-foreground">
-										{typeCounts[type] ?? 0}
-									</span>
-								</DropdownMenuCheckboxItem>
-							))
+							documentTypes.map((type, index) => {
+								const isActive = activeTypes.includes(type);
+								return (
+									<div key={type}>
+										{index > 0 && <div className="mx-3 h-px bg-popover-border" />}
+										<button
+											type="button"
+											className="flex h-12 w-full items-center gap-3 rounded-lg px-3 text-left text-sm transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+											onClick={() => onToggleType(type, !isActive)}
+										>
+											{getDocumentTypeIcon(type, "h-4 w-4")}
+											<span className="min-w-0 flex-1 truncate">{getDocumentTypeLabel(type)}</span>
+											<span className="text-xs text-muted-foreground">{typeCounts[type] ?? 0}</span>
+											{isActive && <Check className="h-4 w-4 shrink-0 text-primary" />}
+										</button>
+									</div>
+								);
+							})
 						) : (
-							<DropdownMenuItem disabled>No document types</DropdownMenuItem>
+							<p className="px-3 py-4 text-sm text-muted-foreground">No document types</p>
 						)}
-					</DropdownMenuSubContent>
-				</DropdownMenuSub>
-			</DropdownMenuContent>
-		</DropdownMenu>
+					</div>
+				</DrawerContent>
+			</Drawer>
+		</>
 	);
 }
 
diff --git a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
index 28264a77f..edd978283 100644
--- a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
@@ -5,6 +5,7 @@ import Link from "next/link";
 import { useParams } from "next/navigation";
 import { useTranslations } from "next-intl";
 import { type ReactNode, useMemo, useState } from "react";
+import { ConnectAgentDialog } from "@/components/mcp/connect-agent-dialog";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Progress } from "@/components/ui/progress";
@@ -322,10 +323,16 @@ export function Sidebar({
 					/>
 				)}
 
+				{!isCollapsed && (
+					<div className="shrink-0 py-1.5">
+						<ConnectAgentDialog className="w-[calc(100%-1rem)]" />
+					</div>
+				)}
+
 				<SidebarUsageFooter
 					pageUsage={pageUsage}
 					isCollapsed={isCollapsed}
-					hasNavSectionAbove={footerNavItems.length > 0}
+					hasNavSectionAbove={footerNavItems.length > 0 || !isCollapsed}
 					onNavigate={onNavigate}
 				/>
 

From ac41671467322ec947dbf90de07f5152bc3348a1 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 22:03:31 +0530
Subject: [PATCH 08/27] refactor(notifications): streamline
 NotificationsDropdown UI and remove unused components

- Simplified the styling of notification count indicators for better visual consistency.
- Enhanced the empty state layout for improved user experience.
- Removed the ConnectAgentDialog from PlaygroundSidebar to declutter the UI.
---
 .../layout/ui/sidebar/NotificationsDropdown.tsx       | 11 ++++-------
 .../layout/ui/sidebar/PlaygroundSidebar.tsx           |  4 ----
 2 files changed, 4 insertions(+), 11 deletions(-)

diff --git a/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
index bf3ce4322..f9441d2c3 100644
--- a/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
@@ -329,10 +329,7 @@ export function NotificationsDropdown({
 						>
 							<span>{tab.label}</span>
 							<span
-								className={cn(
-									"inline-flex h-5 min-w-5 items-center justify-center rounded-full px-1.5 text-[11px] font-semibold",
-									isActive ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground"
-								)}
+								className="inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-muted px-1.5 text-[11px] font-semibold text-muted-foreground"
 							>
 								{formatNotificationCount(tab.count)}
 							</span>
@@ -406,7 +403,7 @@ export function NotificationsDropdown({
 						) : null}
 					</div>
 				) : (
-					<div className="flex flex-col items-center justify-center px-6 py-10 text-center">
+					<div className="flex min-h-full flex-col items-center justify-center px-6 py-10 text-center">
 						<p className="text-sm font-medium">{emptyStateCopy.title}</p>
 						<p className="mt-1 text-xs text-muted-foreground">{emptyStateCopy.description}</p>
 						{hasMore ? (
@@ -438,7 +435,7 @@ export function NotificationsDropdown({
 				>
 					<DrawerHandle className="mt-3 h-1.5 w-10" />
 					<DrawerTitle className="sr-only">Notifications</DrawerTitle>
-					<div className="flex min-h-0 flex-1 flex-col">{panelContent}</div>
+					<div className="flex min-h-0 flex-1 select-none flex-col">{panelContent}</div>
 				</DrawerContent>
 			</Drawer>
 		);
@@ -458,7 +455,7 @@ export function NotificationsDropdown({
 				side="right"
 				align="end"
 				sideOffset={10}
-				className="z-80 flex max-h-[min(520px,calc(100vh-2rem))] w-[360px] flex-col overflow-hidden rounded-xl border bg-popover p-0 text-popover-foreground shadow-lg"
+				className="z-80 flex h-[min(420px,calc(100vh-2rem))] w-[360px] select-none flex-col overflow-hidden rounded-xl border bg-popover p-0 text-popover-foreground shadow-lg"
 			>
 				{panelContent}
 			</PopoverContent>
diff --git a/surfsense_web/components/layout/ui/sidebar/PlaygroundSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/PlaygroundSidebar.tsx
index 1c2f96212..ffdab8004 100644
--- a/surfsense_web/components/layout/ui/sidebar/PlaygroundSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/PlaygroundSidebar.tsx
@@ -3,7 +3,6 @@
 import { History, KeyRound } from "lucide-react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
-import { ConnectAgentDialog } from "@/components/mcp/connect-agent-dialog";
 import { PLAYGROUND_PLATFORMS, type PlatformIcon } from "@/lib/playground/catalog";
 import { cn } from "@/lib/utils";
 
@@ -90,9 +89,6 @@ export function PlaygroundSidebar({ workspaceId }: PlaygroundSidebarProps) {
 				))}
 			</div>
 
-			<div className="shrink-0 py-1.5 before:mx-3 before:mb-1.5 before:block before:h-px before:bg-border">
-				<ConnectAgentDialog />
-			</div>
 		</div>
 	);
 }

From f2b326b63bcad62114237954d47c737dbf1889f6 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 22:17:51 +0530
Subject: [PATCH 09/27] feat(playground): implement Playground layout and
 navigation structure

- Introduced PlaygroundLayoutShell component for managing the layout and navigation of the API Playground.
- Added PlaygroundLayout component to handle workspace-specific rendering.
- Removed PlaygroundSidebar and related state management to simplify the UI and enhance mobile responsiveness.
- Updated LayoutDataProvider and LayoutShell components to reflect the new Playground structure.
---
 .../playground/layout-shell.tsx               | 192 ++++++++++++++++++
 .../[workspace_id]/playground/layout.tsx      |  15 ++
 surfsense_web/atoms/layout/playground.atom.ts |  10 -
 .../layout/providers/LayoutDataProvider.tsx   |  39 +---
 .../layout/ui/shell/LayoutShell.tsx           |  23 +--
 .../layout/ui/sidebar/PlaygroundSidebar.tsx   |  94 ---------
 .../components/layout/ui/sidebar/index.ts     |   1 -
 7 files changed, 214 insertions(+), 160 deletions(-)
 create mode 100644 surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
 create mode 100644 surfsense_web/app/dashboard/[workspace_id]/playground/layout.tsx
 delete mode 100644 surfsense_web/atoms/layout/playground.atom.ts
 delete mode 100644 surfsense_web/components/layout/ui/sidebar/PlaygroundSidebar.tsx

diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
new file mode 100644
index 000000000..0d0211f99
--- /dev/null
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
@@ -0,0 +1,192 @@
+"use client";
+
+import { History, KeyRound, LayoutGrid } from "lucide-react";
+import Link from "next/link";
+import { useSelectedLayoutSegments } from "next/navigation";
+import type React from "react";
+import { useCallback, useMemo, useState } from "react";
+import { Separator } from "@/components/ui/separator";
+import { PLAYGROUND_PLATFORMS, type PlatformIcon } from "@/lib/playground/catalog";
+import { cn } from "@/lib/utils";
+
+interface PlaygroundLayoutShellProps {
+	workspaceId: string;
+	children: React.ReactNode;
+}
+
+type PlaygroundNavItem =
+	| {
+			type: "item";
+			value: string;
+			label: string;
+			href: string;
+			icon: React.ReactNode;
+			indented?: boolean;
+	  }
+	| {
+			type: "section";
+			value: string;
+			label: string;
+			icon: PlatformIcon;
+	  };
+
+function PlaygroundNavLink({
+	item,
+	activeValue,
+}: {
+	item: Extract<PlaygroundNavItem, { type: "item" }>;
+	activeValue: string;
+}) {
+	const isActive = activeValue === item.value;
+
+	return (
+		<Link
+			href={item.href}
+			replace
+			scroll={false}
+			prefetch
+			className={cn(
+				"inline-flex h-auto items-center justify-start gap-3 rounded-md px-3 py-2.5 text-left text-sm font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
+				item.indented && "pl-9",
+				isActive
+					? "bg-accent text-accent-foreground"
+					: "bg-transparent text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+			)}
+		>
+			{item.icon}
+			<span className="min-w-0 truncate">{item.label}</span>
+		</Link>
+	);
+}
+
+export function PlaygroundLayoutShell({ workspaceId, children }: PlaygroundLayoutShellProps) {
+	const segments = useSelectedLayoutSegments();
+	const [tabScrollPos, setTabScrollPos] = useState<"start" | "middle" | "end">("start");
+	const base = `/dashboard/${workspaceId}/playground`;
+
+	const handleTabScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
+		const el = e.currentTarget;
+		const atStart = el.scrollLeft <= 2;
+		const atEnd = el.scrollWidth - el.scrollLeft - el.clientWidth <= 2;
+		setTabScrollPos(atStart ? "start" : atEnd ? "end" : "middle");
+	}, []);
+
+	const navItems = useMemo<PlaygroundNavItem[]>(
+		() => [
+			{
+				type: "item",
+				value: "overview",
+				label: "Overview",
+				href: base,
+				icon: <LayoutGrid className="h-4 w-4" />,
+			},
+			{
+				type: "item",
+				value: "runs",
+				label: "Runs",
+				href: `${base}/runs`,
+				icon: <History className="h-4 w-4" />,
+			},
+			{
+				type: "item",
+				value: "api-keys",
+				label: "API Keys",
+				href: `${base}/api-keys`,
+				icon: <KeyRound className="h-4 w-4" />,
+			},
+			...PLAYGROUND_PLATFORMS.flatMap<PlaygroundNavItem>((platform) => [
+				{
+					type: "section",
+					value: platform.id,
+					label: platform.label,
+					icon: platform.icon,
+				},
+				...platform.verbs.map((verb) => ({
+					type: "item" as const,
+					value: `${platform.id}/${verb.verb}`,
+					label: verb.label,
+					href: `${base}/${platform.id}/${verb.verb}`,
+					icon: <span className="h-4 w-4" />,
+					indented: true,
+				})),
+			]),
+		],
+		[base]
+	);
+
+	const activeValue =
+		segments.length >= 2
+			? `${segments[0]}/${segments[1]}`
+			: segments[0] && navItems.some((item) => item.type === "item" && item.value === segments[0])
+				? segments[0]
+				: "overview";
+	const selectedLabel =
+		navItems.find((item) => item.type === "item" && item.value === activeValue)?.label ??
+		"API Playground";
+	const mobileItems = navItems.filter(
+		(item): item is Extract<PlaygroundNavItem, { type: "item" }> => item.type === "item"
+	);
+
+	return (
+		<section className="flex h-full min-h-[min(680px,calc(100vh-5rem))] w-full select-none flex-col gap-6 md:flex-row">
+			<div className="md:w-[220px] md:shrink-0">
+				<h1 className="mb-4 px-1 text-2xl font-semibold tracking-tight">API Playground</h1>
+				<nav className="hidden flex-col gap-0.5 md:flex">
+					{navItems.map((item) => {
+						if (item.type === "section") {
+							const Icon = item.icon;
+							return (
+								<div
+									key={item.value}
+									className="mt-3 flex items-center gap-2 px-3 py-1 text-xs font-medium text-muted-foreground first:mt-1"
+								>
+									<Icon className="h-3.5 w-3.5 shrink-0" />
+									<span className="truncate">{item.label}</span>
+								</div>
+							);
+						}
+
+						return <PlaygroundNavLink key={item.value} item={item} activeValue={activeValue} />;
+					})}
+				</nav>
+				<div
+					className="overflow-x-auto border-b border-border pb-3 md:hidden"
+					onScroll={handleTabScroll}
+					style={{
+						maskImage: `linear-gradient(to right, ${tabScrollPos === "start" ? "black" : "transparent"}, black 24px, black calc(100% - 24px), ${tabScrollPos === "end" ? "black" : "transparent"})`,
+						WebkitMaskImage: `linear-gradient(to right, ${tabScrollPos === "start" ? "black" : "transparent"}, black 24px, black calc(100% - 24px), ${tabScrollPos === "end" ? "black" : "transparent"})`,
+					}}
+				>
+					<div className="flex gap-1">
+						{mobileItems.map((item) => (
+							<Link
+								key={item.value}
+								href={item.href}
+								replace
+								scroll={false}
+								prefetch
+								className={cn(
+									"inline-flex h-auto shrink-0 items-center gap-2 rounded-md px-3 py-1.5 text-xs font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
+									activeValue === item.value
+										? "bg-accent text-accent-foreground"
+										: "bg-transparent text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+								)}
+							>
+								{item.icon}
+								{item.label}
+							</Link>
+						))}
+					</div>
+				</div>
+			</div>
+
+			<div className="min-w-0 flex-1">
+				<div className="hidden md:block">
+					<h2 className="text-lg font-semibold">{selectedLabel}</h2>
+					<Separator className="mt-4 bg-border" />
+				</div>
+				<div className="min-w-0 pt-4">{children}</div>
+			</div>
+		</section>
+	);
+}
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/layout.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/layout.tsx
new file mode 100644
index 000000000..318886e31
--- /dev/null
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/layout.tsx
@@ -0,0 +1,15 @@
+import type React from "react";
+import { use } from "react";
+import { PlaygroundLayoutShell } from "./layout-shell";
+
+export default function PlaygroundLayout({
+	params,
+	children,
+}: {
+	params: Promise<{ workspace_id: string }>;
+	children: React.ReactNode;
+}) {
+	const { workspace_id } = use(params);
+
+	return <PlaygroundLayoutShell workspaceId={workspace_id}>{children}</PlaygroundLayoutShell>;
+}
diff --git a/surfsense_web/atoms/layout/playground.atom.ts b/surfsense_web/atoms/layout/playground.atom.ts
deleted file mode 100644
index 6cbe8d276..000000000
--- a/surfsense_web/atoms/layout/playground.atom.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import { atom } from "jotai";
-
-/**
- * Whether the second-level API Playground sidebar is open. Toggled by the
- * Playground nav button and kept in memory for the session, so it survives
- * in-app navigation (opening a new chat won't close it) and only closes when
- * the user clicks the toggle. It defaults to open, so a fresh app load — a new
- * signup or a relogin — always starts with the playground visible.
- */
-export const playgroundSidebarOpenAtom = atom<boolean>(true);
diff --git a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
index a70e8f59e..9821a9f83 100644
--- a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
+++ b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useQuery } from "@tanstack/react-query";
-import { useAtom, useAtomValue, useSetAtom } from "jotai";
+import { useAtomValue, useSetAtom } from "jotai";
 import { AlarmClock, AlertTriangle, Boxes, SquareTerminal } from "lucide-react";
 import { useParams, usePathname, useRouter } from "next/navigation";
 import { useTranslations } from "next-intl";
@@ -11,7 +11,6 @@ import { toast } from "sonner";
 import { currentThreadAtom, resetCurrentThreadAtom } from "@/atoms/chat/current-thread.atom";
 import { statusInboxItemsAtom } from "@/atoms/inbox/status-inbox.atom";
 import { announcementsDialogAtom } from "@/atoms/layout/dialogs.atom";
-import { playgroundSidebarOpenAtom } from "@/atoms/layout/playground.atom";
 import { removeChatTabAtom, syncChatTabAtom, type Tab } from "@/atoms/tabs/tabs.atom";
 import { currentUserAtom } from "@/atoms/user/user-query.atoms";
 import { deleteWorkspaceMutationAtom } from "@/atoms/workspaces/workspace-mutation.atoms";
@@ -43,7 +42,6 @@ import { Spinner } from "@/components/ui/spinner";
 import { useActivateChatThread } from "@/hooks/use-activate-chat-thread";
 import { useAnnouncements } from "@/hooks/use-announcements";
 import { useInbox } from "@/hooks/use-inbox";
-import { useIsMobile } from "@/hooks/use-mobile";
 import { useArchiveThread, useDeleteThread, useRenameThread } from "@/hooks/use-thread-mutations";
 import { notificationsApiService } from "@/lib/apis/notifications-api.service";
 import { workspacesApiService } from "@/lib/apis/workspaces-api.service";
@@ -68,8 +66,6 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 	const params = useParams();
 	const pathname = usePathname();
 	const { theme, setTheme } = useTheme();
-	const isMobile = useIsMobile();
-	const [playgroundSidebarOpen, setPlaygroundSidebarOpen] = useAtom(playgroundSidebarOpenAtom);
 
 	// Announcements
 	const { unreadCount: announcementUnreadCount } = useAnnouncements();
@@ -316,20 +312,11 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 						title: "Playground",
 						url: `/dashboard/${workspaceId}/playground`,
 						icon: SquareTerminal,
-						// Mobile has no second-level sidebar: Playground is a plain link
-						// there, so highlight by route. Desktop highlights the toggle state.
-						isActive: isMobile ? isPlaygroundRoute : playgroundSidebarOpen,
+						isActive: isPlaygroundRoute,
 					},
 				] as (NavItem | null)[]
 			).filter((item): item is NavItem => item !== null),
-		[
-			workspaceId,
-			isAutomationsActive,
-			isArtifactsActive,
-			isPlaygroundRoute,
-			playgroundSidebarOpen,
-			isMobile,
-		]
+		[workspaceId, isAutomationsActive, isArtifactsActive, isPlaygroundRoute]
 	);
 
 	// Handlers
@@ -466,18 +453,9 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 
 	const handleNavItemClick = useCallback(
 		(item: NavItem) => {
-			// Desktop: Playground is a persistent toggle, not a plain link — it just
-			// opens the second-level sidebar (which holds the whole API playground)
-			// and only closes on a second click, never navigating away from the
-			// current page (e.g. a new chat). Mobile has no second-level sidebar,
-			// so there it navigates to the playground index page instead.
-			if (item.url.endsWith("/playground") && !isMobile) {
-				setPlaygroundSidebarOpen((prev) => !prev);
-				return;
-			}
 			router.push(item.url);
 		},
-		[router, setPlaygroundSidebarOpen, isMobile]
+		[router]
 	);
 
 	const handleNewChat = useCallback(() => {
@@ -699,7 +677,6 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 				setTheme={setTheme}
 				isChatPage={isChatPage}
 				isAllChatsPage={isAllChatsPage}
-				showPlaygroundSidebar={playgroundSidebarOpen}
 				useWorkspacePanel={useWorkspacePanel}
 				workspacePanelViewportClassName={
 					isUserSettingsPage ||
@@ -713,13 +690,7 @@ export function LayoutDataProvider({ workspaceId, children }: LayoutDataProvider
 						: undefined
 				}
 				workspacePanelContentClassName={
-					isAutomationsPage || isPlaygroundPage
-						? "max-w-none select-none"
-						: isAllChatsPage
-							? "max-w-5xl"
-							: isUserSettingsPage || isWorkspaceSettingsPage || isTeamPage || isArtifactsPage
-								? "max-w-5xl"
-								: undefined
+					useWorkspacePanel ? "max-w-5xl select-none" : undefined
 				}
 				isLoadingChats={isLoadingThreads}
 				notifications={{
diff --git a/surfsense_web/components/layout/ui/shell/LayoutShell.tsx b/surfsense_web/components/layout/ui/shell/LayoutShell.tsx
index 00e606024..06ccaab80 100644
--- a/surfsense_web/components/layout/ui/shell/LayoutShell.tsx
+++ b/surfsense_web/components/layout/ui/shell/LayoutShell.tsx
@@ -27,7 +27,6 @@ import {
 import {
 	MobileSidebar,
 	MobileSidebarTrigger,
-	PlaygroundSidebar,
 	Sidebar,
 	SidebarCollapseButton,
 } from "../sidebar";
@@ -109,7 +108,6 @@ interface LayoutShellProps {
 	defaultCollapsed?: boolean;
 	isChatPage?: boolean;
 	isAllChatsPage?: boolean;
-	showPlaygroundSidebar?: boolean;
 	useWorkspacePanel?: boolean;
 	workspacePanelViewportClassName?: string;
 	workspacePanelContentClassName?: string;
@@ -210,7 +208,6 @@ export function LayoutShell({
 	defaultCollapsed = false,
 	isChatPage = false,
 	isAllChatsPage = false,
-	showPlaygroundSidebar = false,
 	useWorkspacePanel = false,
 	workspacePanelViewportClassName,
 	workspacePanelContentClassName,
@@ -338,27 +335,11 @@ export function LayoutShell({
 							/>
 						</div>
 
-						{/* Playground second-level sidebar — contextual, desktop only. Sits
-						    between the icon rail and the main sidebar. On Mac it becomes the
-						    leftmost panel, so it takes the rounded-corner/left-border treatment. */}
-						{showPlaygroundSidebar && activeWorkspaceId != null && (
-							<div
-								className={cn(
-									"relative hidden md:flex shrink-0 z-20 -mr-2 bg-panel",
-									isMacDesktop ? "rounded-tl-xl border-t border-r border-l" : "border-r"
-								)}
-							>
-								<PlaygroundSidebar workspaceId={activeWorkspaceId} />
-							</div>
-						)}
-
 						{/* Sidebar + slide-out panels share one container; overflow visible so panels can overlay main content. Negative right margin closes the flex gap so the sidebar sits flush against the main panel, separated only by a border. */}
 						<div
 							className={cn(
 								"relative hidden md:flex shrink-0 z-20 -mr-2 bg-panel",
-								isMacDesktop
-									? cn("border-t border-r", !showPlaygroundSidebar && "rounded-tl-xl border-l")
-									: "border-r"
+								isMacDesktop ? "rounded-tl-xl border-l border-t border-r" : "border-r"
 							)}
 						>
 							<Sidebar
@@ -396,7 +377,7 @@ export function LayoutShell({
 								}
 								className={cn(
 									"flex shrink-0",
-									isMacDesktop && !showPlaygroundSidebar && "rounded-tl-xl"
+									isMacDesktop && "rounded-tl-xl"
 								)}
 								isLoadingChats={isLoadingChats}
 								sidebarWidth={sidebarWidth}
diff --git a/surfsense_web/components/layout/ui/sidebar/PlaygroundSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/PlaygroundSidebar.tsx
deleted file mode 100644
index ffdab8004..000000000
--- a/surfsense_web/components/layout/ui/sidebar/PlaygroundSidebar.tsx
+++ /dev/null
@@ -1,94 +0,0 @@
-"use client";
-
-import { History, KeyRound } from "lucide-react";
-import Link from "next/link";
-import { usePathname } from "next/navigation";
-import { PLAYGROUND_PLATFORMS, type PlatformIcon } from "@/lib/playground/catalog";
-import { cn } from "@/lib/utils";
-
-interface PlaygroundSidebarProps {
-	workspaceId: number | string;
-}
-
-function PlaygroundNavLink({
-	href,
-	label,
-	icon: Icon,
-	isActive,
-	indented = false,
-}: {
-	href: string;
-	label: string;
-	icon?: PlatformIcon;
-	isActive: boolean;
-	indented?: boolean;
-}) {
-	return (
-		<Link
-			href={href}
-			aria-current={isActive ? "page" : undefined}
-			className={cn(
-				"group/link relative flex h-9 items-center gap-2 rounded-md mx-2 px-2 text-sm text-left",
-				"transition-colors hover:bg-accent hover:text-accent-foreground",
-				"focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
-				indented && "pl-8",
-				isActive && "bg-accent text-accent-foreground"
-			)}
-		>
-			{Icon ? <Icon className="h-3.5 w-3.5 shrink-0" /> : null}
-			<span className="min-w-0 flex-1 truncate">{label}</span>
-		</Link>
-	);
-}
-
-export function PlaygroundSidebar({ workspaceId }: PlaygroundSidebarProps) {
-	const pathname = usePathname();
-	const base = `/dashboard/${workspaceId}/playground`;
-
-	return (
-		<div className="relative flex h-full w-[240px] flex-col bg-panel text-sidebar-foreground overflow-hidden select-none">
-			<div className="flex h-12 shrink-0 items-center px-4">
-				<span className="text-sm font-semibold">API Playground</span>
-			</div>
-
-			<div className="flex flex-col gap-0.5 pt-1.5 pb-1.5 after:mx-3 after:mt-1.5 after:block after:h-px after:bg-border">
-				<PlaygroundNavLink
-					href={`${base}/runs`}
-					label="Runs"
-					icon={History}
-					isActive={pathname === `${base}/runs`}
-				/>
-				<PlaygroundNavLink
-					href={`${base}/api-keys`}
-					label="API Keys"
-					icon={KeyRound}
-					isActive={pathname === `${base}/api-keys`}
-				/>
-			</div>
-
-			<div className="flex-1 w-full min-h-0 overflow-y-auto overflow-x-hidden scrollbar-thin scrollbar-thumb-muted-foreground/20 scrollbar-track-transparent pb-2">
-				{PLAYGROUND_PLATFORMS.map((platform) => (
-					<div key={platform.id} className="flex flex-col gap-0.5 pt-2">
-						<div className="flex items-center gap-2 pl-4 pr-2.5 py-1 text-xs font-medium text-muted-foreground">
-							<platform.icon className="h-3.5 w-3.5 shrink-0" />
-							<span className="truncate">{platform.label}</span>
-						</div>
-						{platform.verbs.map((verb) => {
-							const href = `${base}/${platform.id}/${verb.verb}`;
-							return (
-								<PlaygroundNavLink
-									key={verb.name}
-									href={href}
-									label={verb.label}
-									isActive={pathname === href}
-									indented
-								/>
-							);
-						})}
-					</div>
-				))}
-			</div>
-
-		</div>
-	);
-}
diff --git a/surfsense_web/components/layout/ui/sidebar/index.ts b/surfsense_web/components/layout/ui/sidebar/index.ts
index b74e31b53..e806b06d0 100644
--- a/surfsense_web/components/layout/ui/sidebar/index.ts
+++ b/surfsense_web/components/layout/ui/sidebar/index.ts
@@ -5,7 +5,6 @@ export { DocumentsSidebar } from "./DocumentsSidebar";
 export { MobileSidebar, MobileSidebarTrigger } from "./MobileSidebar";
 export { NavSection } from "./NavSection";
 export { NotificationsDropdown } from "./NotificationsDropdown";
-export { PlaygroundSidebar } from "./PlaygroundSidebar";
 export { Sidebar } from "./Sidebar";
 export { SidebarCollapseButton } from "./SidebarCollapseButton";
 export { SidebarHeader } from "./SidebarHeader";

From 58b26af1e0b237146414dce7883bf258c561c110 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 22:29:16 +0530
Subject: [PATCH 10/27] feat(playground): update header styles for improved
 visual consistency

- Enhanced header styles across Playground components to include text-foreground and responsive sizing.
- Updated API Playground, API Keys, Runs Table, and other sections for a unified look and feel.
- Improved accessibility and readability with consistent font sizes and colors.
---
 .../[workspace_id]/playground/components/api-keys-section.tsx | 2 +-
 .../[workspace_id]/playground/components/playground-index.tsx | 2 +-
 .../playground/components/playground-runner.tsx               | 2 +-
 .../[workspace_id]/playground/components/runs-table.tsx       | 2 +-
 .../app/dashboard/[workspace_id]/playground/layout-shell.tsx  | 4 +++-
 .../dashboard/[workspace_id]/user-settings/layout-shell.tsx   | 4 +++-
 .../[workspace_id]/workspace-settings/layout-shell.tsx        | 4 +++-
 7 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-keys-section.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-keys-section.tsx
index e3df313f0..2e1f272e9 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-keys-section.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-keys-section.tsx
@@ -50,7 +50,7 @@ export function ApiKeysSection({ workspaceId }: { workspaceId: number }) {
 	return (
 		<div className="space-y-6">
 			<div>
-				<h1 className="text-xl font-semibold">API Keys</h1>
+				<h1 className="text-xl font-semibold text-foreground md:text-2xl">API Keys</h1>
 				<p className="mt-1 text-sm text-muted-foreground">
 					Enable API access for this workspace and manage the keys that use it.
 				</p>
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
index 741ed291f..80b7e841f 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
@@ -21,7 +21,7 @@ export function PlaygroundIndex({ workspaceId }: { workspaceId: number }) {
 	return (
 		<div className="space-y-8">
 			<div>
-				<h1 className="text-xl font-semibold">API Playground</h1>
+				<h1 className="text-xl font-semibold text-foreground md:text-2xl">API Playground</h1>
 				<p className="mt-1 text-sm text-muted-foreground">
 					Manually run SurfSense's platform-native APIs and inspect their output. Every run is
 					captured under Runs.
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
index 3b76a7d09..effce913b 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
@@ -189,7 +189,7 @@ export function PlaygroundRunner({ workspaceId, platform, verb }: PlaygroundRunn
 			<div className="grid gap-6 lg:grid-cols-2">
 				<div className="space-y-5">
 					<div>
-						<h1 className="text-lg font-semibold">
+						<h1 className="text-xl font-semibold text-foreground md:text-2xl">
 							{catalogVerb.label} <span className="text-muted-foreground">· {platform}</span>
 						</h1>
 						{capability.description && (
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx
index f47bd4572..17508c0ff 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx
@@ -68,7 +68,7 @@ export function RunsTable({ workspaceId }: { workspaceId: number }) {
 	return (
 		<div className="space-y-4">
 			<div>
-				<h1 className="text-xl font-semibold">Runs</h1>
+				<h1 className="text-xl font-semibold text-foreground md:text-2xl">Runs</h1>
 				<p className="mt-1 text-sm text-muted-foreground">
 					Every platform-native API run in this workspace — from the playground, API keys, and
 					agents. Newest first.
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
index 0d0211f99..43331651d 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
@@ -130,7 +130,9 @@ export function PlaygroundLayoutShell({ workspaceId, children }: PlaygroundLayou
 	return (
 		<section className="flex h-full min-h-[min(680px,calc(100vh-5rem))] w-full select-none flex-col gap-6 md:flex-row">
 			<div className="md:w-[220px] md:shrink-0">
-				<h1 className="mb-4 px-1 text-2xl font-semibold tracking-tight">API Playground</h1>
+				<h1 className="mb-4 px-1 text-xl font-semibold tracking-tight text-foreground md:text-2xl">
+					API Playground
+				</h1>
 				<nav className="hidden flex-col gap-0.5 md:flex">
 					{navItems.map((item) => {
 						if (item.type === "section") {
diff --git a/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx
index 5446c4167..0559deaf9 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx
@@ -117,7 +117,9 @@ export function UserSettingsLayoutShell({ workspaceId, children }: UserSettingsL
 	return (
 		<section className="flex h-full min-h-[min(680px,calc(100vh-5rem))] w-full select-none flex-col gap-6 md:flex-row">
 			<div className="md:w-[220px] md:shrink-0">
-				<h1 className="mb-4 px-1 text-2xl font-semibold tracking-tight">{t("title")}</h1>
+				<h1 className="mb-4 px-1 text-xl font-semibold tracking-tight text-foreground md:text-2xl">
+					{t("title")}
+				</h1>
 				<nav className="hidden flex-col gap-0.5 md:flex">
 					{navItems.map((item) => (
 						<Link
diff --git a/surfsense_web/app/dashboard/[workspace_id]/workspace-settings/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/workspace-settings/layout-shell.tsx
index e23daecb9..ffef57a03 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/workspace-settings/layout-shell.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/workspace-settings/layout-shell.tsx
@@ -76,7 +76,9 @@ export function WorkspaceSettingsLayoutShell({
 	return (
 		<section className="flex h-full min-h-[min(680px,calc(100vh-5rem))] w-full select-none flex-col gap-6 md:flex-row">
 			<div className="md:w-[220px] md:shrink-0">
-				<h1 className="mb-4 px-1 text-2xl font-semibold tracking-tight">{t("title")}</h1>
+				<h1 className="mb-4 px-1 text-xl font-semibold tracking-tight text-foreground md:text-2xl">
+					{t("title")}
+				</h1>
 				<nav className="hidden flex-col gap-0.5 md:flex">
 					{navItems.map((item) => (
 						<Link

From cd4eb189810f4b43182096628770a7ef290d405e Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 22:33:29 +0530
Subject: [PATCH 11/27] fix(sidebar): adjust button sizes and layout for
 improved UI consistency

- Reduced button sizes in EmbeddedDocumentsMenu and EmbeddedImportMenu for better alignment.
- Updated layout spacing in SidebarButton to enhance visual clarity and consistency.
- Added a new badge to the Sidebar component to indicate new items, improving user awareness.
---
 surfsense_web/components/assistant-ui/thread.tsx |  8 ++++----
 .../layout/ui/sidebar/DocumentsSidebar.tsx       | 12 ++++++------
 .../components/layout/ui/sidebar/Sidebar.tsx     |  8 ++++++++
 .../layout/ui/sidebar/SidebarButton.tsx          | 16 +++++++++-------
 4 files changed, 27 insertions(+), 17 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/thread.tsx b/surfsense_web/components/assistant-ui/thread.tsx
index 1b8548e3d..08ebc6a19 100644
--- a/surfsense_web/components/assistant-ui/thread.tsx
+++ b/surfsense_web/components/assistant-ui/thread.tsx
@@ -1014,13 +1014,13 @@ const ConnectedScraperIcons: FC<{ workspaceId: number }> = ({ workspaceId }) =>
 	return (
 		<div className="hidden items-center gap-1 sm:flex">
 			<div aria-hidden className="h-5 w-px shrink-0 bg-border" />
-			<div className="flex items-center gap-0.5" aria-label="Connected data sources">
+			<ul className="m-0 flex list-none items-center gap-0.5 p-0" aria-label="Connected data sources">
 				{platforms.map((platform, i) => {
 					const Icon = platform.icon;
 					return (
 						<Tooltip key={platform.id}>
 							<TooltipTrigger asChild>
-								<motion.span
+								<motion.li
 									initial={{ opacity: 0, y: reduceMotion ? 0 : 4 }}
 									animate={{ opacity: 1, y: 0 }}
 									transition={{
@@ -1031,13 +1031,13 @@ const ConnectedScraperIcons: FC<{ workspaceId: number }> = ({ workspaceId }) =>
 									className="flex size-5 items-center justify-center"
 								>
 									<Icon className="size-3.5" />
-								</motion.span>
+								</motion.li>
 							</TooltipTrigger>
 							<TooltipContent side="bottom">{platform.label} · Connected</TooltipContent>
 						</Tooltip>
 					);
 				})}
-			</div>
+			</ul>
 		</div>
 	);
 };
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index 5d4efac81..10c4247eb 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -145,10 +145,10 @@ export function EmbeddedDocumentsMenu({
 						type="button"
 						variant="ghost"
 						size="icon"
-						className="relative h-7 w-7 text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+						className="relative h-6 w-6 text-muted-foreground hover:bg-accent hover:text-accent-foreground"
 						aria-label="Document actions"
 					>
-						<SlidersVertical className="h-3.5 w-3.5" />
+						<SlidersVertical className="size-3.5" />
 						{activeTypes.length > 0 ? (
 							<span className="absolute right-0.5 top-0.5 h-1.5 w-1.5 rounded-full bg-primary" />
 						) : null}
@@ -284,10 +284,10 @@ export function EmbeddedImportMenu({
 					type="button"
 					variant="ghost"
 					size="icon"
-					className="h-7 w-7 text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+					className="h-6 w-6 text-muted-foreground hover:bg-accent hover:text-accent-foreground"
 					aria-label="Import documents"
 				>
-					<FolderInput className="h-3.5 w-3.5" />
+					<FolderInput className="size-3.5" />
 				</Button>
 			</DropdownMenuTrigger>
 			<DropdownMenuContent align="end" className="w-56">
@@ -1267,7 +1267,7 @@ function AuthenticatedDocumentsSidebarBase({
 					defaultOpen={true}
 					contentClassName="px-0"
 					persistentAction={
-						<div className="flex items-center gap-0.5">
+						<div className="flex items-center gap-1.5">
 							<EmbeddedImportMenu onFolderWatched={refreshWatchedIds} />
 							<EmbeddedDocumentsMenu
 								typeCounts={typeCounts}
@@ -1443,7 +1443,7 @@ function AnonymousDocumentsSidebar({ embedded = false }: DocumentsSidebarProps)
 				defaultOpen={true}
 				contentClassName="px-0"
 				persistentAction={
-					<div className="flex items-center gap-0.5">
+					<div className="flex items-center gap-1.5">
 						<EmbeddedImportMenu gate={gate} />
 						<EmbeddedDocumentsMenu
 							typeCounts={hasDoc ? { FILE: 1 } : {}}
diff --git a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
index edd978283..f240ff3d7 100644
--- a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
@@ -246,6 +246,14 @@ export function Sidebar({
 							onClick={() => onNavItemClick?.(playgroundItem)}
 							isCollapsed={isCollapsed}
 							isActive={playgroundItem.isActive}
+							badge={
+								<Badge
+									variant="secondary"
+									className="h-5 shrink-0 rounded-sm border-0 bg-popover-foreground/10 px-1.5 text-[11px] text-popover-foreground hover:bg-popover-foreground/10"
+								>
+									New
+								</Badge>
+							}
 							tooltipContent={isCollapsed ? playgroundItem.title : undefined}
 						/>
 					)}
diff --git a/surfsense_web/components/layout/ui/sidebar/SidebarButton.tsx b/surfsense_web/components/layout/ui/sidebar/SidebarButton.tsx
index cc7f83e1d..5b98be560 100644
--- a/surfsense_web/components/layout/ui/sidebar/SidebarButton.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/SidebarButton.tsx
@@ -73,17 +73,19 @@ export function SidebarButton({
 						isCollapsed ? "max-w-0 opacity-0 ml-0" : "max-w-[260px] flex-1 opacity-100 ml-2"
 					)}
 				>
-					<span className="block truncate">{label}</span>
+					<span className="flex min-w-0 items-center gap-1.5">
+						<span className="truncate">{label}</span>
+						{!isCollapsed && badge && typeof badge !== "string" ? badge : null}
+						{!isCollapsed && badge && typeof badge === "string" ? (
+							<span className="inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-red-500 px-1 text-[10px] font-medium text-white">
+								{badge}
+							</span>
+						) : null}
+					</span>
 				</span>
 			</span>
 
 			{!isCollapsed && trailingContent}
-			{!isCollapsed && badge && typeof badge !== "string" ? badge : null}
-			{!isCollapsed && badge && typeof badge === "string" ? (
-				<span className="ml-1 inline-flex items-center justify-center min-w-4 h-4 px-1 rounded-full bg-red-500 text-white text-[10px] font-medium">
-					{badge}
-				</span>
-			) : null}
 
 			{collapsedOverlay && (
 				<span

From 2670ad96c8d33f5f00d375f5e84d23c78c02beb4 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 22:41:32 +0530
Subject: [PATCH 12/27] feat(sidebar): highlight active chat items for improved
 user interaction

---
 .../components/layout/ui/sidebar/ChatListItem.tsx          | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/surfsense_web/components/layout/ui/sidebar/ChatListItem.tsx b/surfsense_web/components/layout/ui/sidebar/ChatListItem.tsx
index e39075443..013714fcf 100644
--- a/surfsense_web/components/layout/ui/sidebar/ChatListItem.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/ChatListItem.tsx
@@ -47,6 +47,7 @@ export function ChatListItem({
 	const dropdownOpen = controlledOpen ?? internalOpen;
 	const setDropdownOpen = onDropdownOpenChange ?? setInternalOpen;
 	const animatedName = useTypewriter(name);
+	const isHighlighted = isActive || dropdownOpen;
 
 	const { handlers: longPressHandlers, wasLongPress } = useLongPress(
 		useCallback(() => setDropdownOpen(true), [setDropdownOpen])
@@ -67,9 +68,9 @@ export function ChatListItem({
 				onFocus={onPrefetch}
 				{...(isMobile ? longPressHandlers : {})}
 				className={sidebarListItemClassName({
-					active: isActive,
+					active: isHighlighted,
 					className:
-						"justify-start gap-2 overflow-hidden px-2 py-1.5 font-normal focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+						"justify-start gap-2 overflow-hidden px-2 py-1.5 font-normal group-hover/item:bg-accent group-hover/item:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
 				})}
 			>
 				<span className="min-w-0 flex-1 truncate">{animatedName}</span>
@@ -79,7 +80,7 @@ export function ChatListItem({
 			<div
 				className={cn(
 					"pointer-events-none absolute right-0 top-0 bottom-0 flex items-center pr-1 pl-6 rounded-r-md",
-					isActive
+					isHighlighted
 						? "bg-gradient-to-l from-accent from-60% to-transparent"
 						: "bg-gradient-to-l from-sidebar from-60% to-transparent group-hover/item:from-accent",
 					isMobile

From d6fbbb97d486368fa0848543e685d7fb105396e5 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 22:48:23 +0530
Subject: [PATCH 13/27] feat(sidebar): introduce SidebarButtonBadge for
 improved badge display

- Added SidebarButtonBadge component to encapsulate badge styling and functionality.
- Updated Sidebar to utilize SidebarButtonBadge for displaying new item notifications, enhancing visual clarity.
- Adjusted SidebarUserProfile layout for better alignment in collapsed view.
---
 .../components/layout/ui/sidebar/Sidebar.tsx  | 11 ++--------
 .../layout/ui/sidebar/SidebarButton.tsx       | 21 +++++++++++++++++++
 .../layout/ui/sidebar/SidebarUserProfile.tsx  |  2 +-
 .../components/mcp/connect-agent-dialog.tsx   |  2 +-
 4 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
index f240ff3d7..bd6029d89 100644
--- a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
@@ -19,7 +19,7 @@ import { ChatListItem } from "./ChatListItem";
 import { CreditBalanceDisplay } from "./CreditBalanceDisplay";
 import { DocumentsSidebar } from "./DocumentsSidebar";
 import { NavSection } from "./NavSection";
-import { SidebarButton } from "./SidebarButton";
+import { SidebarButton, SidebarButtonBadge } from "./SidebarButton";
 import { SidebarCollapseButton } from "./SidebarCollapseButton";
 import { SidebarHeader } from "./SidebarHeader";
 import { SidebarSection } from "./SidebarSection";
@@ -246,14 +246,7 @@ export function Sidebar({
 							onClick={() => onNavItemClick?.(playgroundItem)}
 							isCollapsed={isCollapsed}
 							isActive={playgroundItem.isActive}
-							badge={
-								<Badge
-									variant="secondary"
-									className="h-5 shrink-0 rounded-sm border-0 bg-popover-foreground/10 px-1.5 text-[11px] text-popover-foreground hover:bg-popover-foreground/10"
-								>
-									New
-								</Badge>
-							}
+							badge={<SidebarButtonBadge>New</SidebarButtonBadge>}
 							tooltipContent={isCollapsed ? playgroundItem.title : undefined}
 						/>
 					)}
diff --git a/surfsense_web/components/layout/ui/sidebar/SidebarButton.tsx b/surfsense_web/components/layout/ui/sidebar/SidebarButton.tsx
index 5b98be560..1557253a9 100644
--- a/surfsense_web/components/layout/ui/sidebar/SidebarButton.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/SidebarButton.tsx
@@ -2,6 +2,7 @@
 
 import type { LucideIcon } from "lucide-react";
 import type React from "react";
+import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import { cn } from "@/lib/utils";
@@ -28,6 +29,26 @@ const baseClassName = cn(
 	"focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
 );
 
+export function SidebarButtonBadge({
+	children,
+	className,
+}: {
+	children: React.ReactNode;
+	className?: string;
+}) {
+	return (
+		<Badge
+			variant="secondary"
+			className={cn(
+				"h-5 shrink-0 rounded-sm border-0 bg-popover-foreground/10 px-1.5 text-[11px] text-popover-foreground hover:bg-popover-foreground/10",
+				className
+			)}
+		>
+			{children}
+		</Badge>
+	);
+}
+
 export function SidebarButton({
 	icon: Icon,
 	label,
diff --git a/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx b/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
index 09fb3f6d0..d5e72174e 100644
--- a/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/SidebarUserProfile.tsx
@@ -414,7 +414,7 @@ export function SidebarUserProfile({
 	// Collapsed view - just show avatar with dropdown
 	if (isCollapsed) {
 		return (
-			<div className="relative w-full px-1.5 py-2 before:absolute before:inset-x-3 before:top-0 before:h-px before:bg-border">
+			<div className="relative w-full px-1.5 py-2 before:absolute before:inset-x-1.5 before:top-0 before:h-px before:bg-border">
 				<div className="flex flex-col items-center gap-2">
 					{topContent}
 					{showDownloadCta && (
diff --git a/surfsense_web/components/mcp/connect-agent-dialog.tsx b/surfsense_web/components/mcp/connect-agent-dialog.tsx
index b48b849c6..86edf6716 100644
--- a/surfsense_web/components/mcp/connect-agent-dialog.tsx
+++ b/surfsense_web/components/mcp/connect-agent-dialog.tsx
@@ -29,7 +29,7 @@ export function ConnectAgentDialog({ className }: { className?: string }) {
 				)}
 			>
 				<Cable className="h-3.5 w-3.5 shrink-0" />
-				<span className="min-w-0 flex-1 truncate">Connect your AI Agent</span>
+				<span className="min-w-0 flex-1 truncate">Connect your agent</span>
 			</DialogTrigger>
 			<DialogContent className="max-h-[85vh] overflow-y-auto sm:max-w-2xl">
 				<DialogHeader>

From 2927a9484ee553e3f330986dc3f054b724acfc50 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 22:56:09 +0530
Subject: [PATCH 14/27] refactor(assistant-ui): simplify ConnectedScraperIcons
 and update ConnectAgentDialog UI

- Removed unused `useReducedMotion` hook from ConnectedScraperIcons for cleaner code.
- Replaced `Cable` icon with a masked SVG in ConnectAgentDialog for improved visual representation.
- Enhanced layout in ConnectAgentDialog to include a badge indicating new items, improving user awareness.
---
 .../components/assistant-ui/thread.tsx        | 32 ++++++++-----------
 .../components/mcp/connect-agent-dialog.tsx   | 16 ++++++++--
 2 files changed, 26 insertions(+), 22 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/thread.tsx b/surfsense_web/components/assistant-ui/thread.tsx
index 08ebc6a19..1e8c66e8a 100644
--- a/surfsense_web/components/assistant-ui/thread.tsx
+++ b/surfsense_web/components/assistant-ui/thread.tsx
@@ -22,7 +22,7 @@ import {
 	Wrench,
 	X,
 } from "lucide-react";
-import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import { AnimatePresence, motion } from "motion/react";
 import Image from "next/image";
 import { useParams } from "next/navigation";
 import { type FC, useCallback, useEffect, useMemo, useRef, useState } from "react";
@@ -986,14 +986,12 @@ const Composer: FC = () => {
  * Full-color brand marks for the platform-native scraper APIs (web, Google
  * Search, Google Maps, Reddit, YouTube) available in this workspace, shown beside the
  * composer "+" so the user can see these native endpoints are connected. Laid
- * out as a clean row (not stacked) after a hairline divider that separates them
+ * out as the same overlapping avatar group used by the connect-tools tray
  * from the composer actions. The capability registry is the source of truth;
- * icons are display-only with a status tooltip. One-time staggered entrance,
- * reduced-motion aware.
+ * icons are display-only with a status tooltip.
  */
 const ConnectedScraperIcons: FC<{ workspaceId: number }> = ({ workspaceId }) => {
 	const { data: capabilities } = useScraperCapabilities(workspaceId);
-	const reduceMotion = useReducedMotion();
 
 	const platforms = useMemo<PlaygroundPlatform[]>(() => {
 		if (!capabilities?.length) return [];
@@ -1014,30 +1012,26 @@ const ConnectedScraperIcons: FC<{ workspaceId: number }> = ({ workspaceId }) =>
 	return (
 		<div className="hidden items-center gap-1 sm:flex">
 			<div aria-hidden className="h-5 w-px shrink-0 bg-border" />
-			<ul className="m-0 flex list-none items-center gap-0.5 p-0" aria-label="Connected data sources">
+			<AvatarGroup className="shrink-0">
 				{platforms.map((platform, i) => {
 					const Icon = platform.icon;
 					return (
 						<Tooltip key={platform.id}>
 							<TooltipTrigger asChild>
-								<motion.li
-									initial={{ opacity: 0, y: reduceMotion ? 0 : 4 }}
-									animate={{ opacity: 1, y: 0 }}
-									transition={{
-										duration: 0.2,
-										ease: [0.23, 1, 0.32, 1],
-										delay: reduceMotion ? 0 : i * 0.04,
-									}}
-									className="flex size-5 items-center justify-center"
+								<Avatar
+									className="size-5"
+									style={{ zIndex: platforms.length - i }}
 								>
-									<Icon className="size-3.5" />
-								</motion.li>
+									<AvatarFallback className="bg-popover text-[10px]">
+										<Icon className="size-3" />
+									</AvatarFallback>
+								</Avatar>
 							</TooltipTrigger>
-							<TooltipContent side="bottom">{platform.label} · Connected</TooltipContent>
+							<TooltipContent side="bottom">{platform.label} scraper available</TooltipContent>
 						</Tooltip>
 					);
 				})}
-			</ul>
+			</AvatarGroup>
 		</div>
 	);
 };
diff --git a/surfsense_web/components/mcp/connect-agent-dialog.tsx b/surfsense_web/components/mcp/connect-agent-dialog.tsx
index 86edf6716..fdbf08d71 100644
--- a/surfsense_web/components/mcp/connect-agent-dialog.tsx
+++ b/surfsense_web/components/mcp/connect-agent-dialog.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { Cable } from "lucide-react";
+import { SidebarButtonBadge } from "@/components/layout/ui/sidebar/SidebarButton";
 import { AgentSetupTabs } from "@/components/mcp/agent-setup-tabs";
 import {
 	Dialog,
@@ -28,8 +28,18 @@ export function ConnectAgentDialog({ className }: { className?: string }) {
 					className
 				)}
 			>
-				<Cable className="h-3.5 w-3.5 shrink-0" />
-				<span className="min-w-0 flex-1 truncate">Connect your agent</span>
+				<span
+					aria-hidden="true"
+					className="size-3.5 shrink-0 bg-current"
+					style={{
+						mask: "url('/connectors/modelcontextprotocol.svg') center / contain no-repeat",
+						WebkitMask: "url('/connectors/modelcontextprotocol.svg') center / contain no-repeat",
+					}}
+				/>
+				<span className="flex min-w-0 flex-1 items-center gap-1.5">
+					<span className="min-w-0 truncate">Connect your agent</span>
+					<SidebarButtonBadge>New</SidebarButtonBadge>
+				</span>
 			</DialogTrigger>
 			<DialogContent className="max-h-[85vh] overflow-y-auto sm:max-w-2xl">
 				<DialogHeader>

From 803577436fb6077c17e762c2d175b6ab4b8cf7d9 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 7 Jul 2026 23:12:08 +0530
Subject: [PATCH 15/27] refactor(playground): simplify API Playground
 description for clarity

- Removed redundant text from the API Playground description to enhance readability.
- Improved layout in FolderNode by adding dropdown state management for better user interaction.
- Updated Sidebar component styles for improved visual consistency and user experience.
---
 .../components/playground-index.tsx           |  3 +--
 .../components/documents/FolderNode.tsx       | 10 ++++++--
 .../components/layout/ui/sidebar/Sidebar.tsx  | 23 ++++++++-----------
 3 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
index 80b7e841f..cf10260ad 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
@@ -23,8 +23,7 @@ export function PlaygroundIndex({ workspaceId }: { workspaceId: number }) {
 			<div>
 				<h1 className="text-xl font-semibold text-foreground md:text-2xl">API Playground</h1>
 				<p className="mt-1 text-sm text-muted-foreground">
-					Manually run SurfSense's platform-native APIs and inspect their output. Every run is
-					captured under Runs.
+					Manually run SurfSense's platform-native APIs and inspect their output.
 				</p>
 			</div>
 
diff --git a/surfsense_web/components/documents/FolderNode.tsx b/surfsense_web/components/documents/FolderNode.tsx
index b46af227a..1cf74f549 100644
--- a/surfsense_web/components/documents/FolderNode.tsx
+++ b/surfsense_web/components/documents/FolderNode.tsx
@@ -129,6 +129,7 @@ export const FolderNode = React.memo(function FolderNode({
 	const rowRef = useRef<HTMLDivElement>(null);
 	const [dropZone, setDropZone] = useState<DropZone | null>(null);
 	const [isRescanning, setIsRescanning] = useState(false);
+	const [dropdownOpen, setDropdownOpen] = useState(false);
 
 	const handleRescan = useCallback(async () => {
 		if (isRescanning) return;
@@ -349,12 +350,17 @@ export const FolderNode = React.memo(function FolderNode({
 					)}
 
 					{!isRenaming && (
-						<DropdownMenu>
+						<DropdownMenu open={dropdownOpen} onOpenChange={setDropdownOpen}>
 							<DropdownMenuTrigger asChild>
 								<Button
 									variant="ghost"
 									size="icon"
-									className="hidden sm:inline-flex h-6 w-6 shrink-0 opacity-0 group-hover:opacity-100 transition-opacity"
+									className={cn(
+										"hidden sm:inline-flex h-6 w-6 shrink-0 hover:bg-transparent transition-opacity",
+										dropdownOpen
+											? "opacity-100 bg-accent hover:bg-accent"
+											: "opacity-0 group-hover:opacity-100"
+									)}
 									onClick={(e) => e.stopPropagation()}
 								>
 									<MoreHorizontal className="h-3.5 w-3.5 text-muted-foreground" />
diff --git a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
index bd6029d89..d1a568fa9 100644
--- a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
@@ -6,7 +6,6 @@ import { useParams } from "next/navigation";
 import { useTranslations } from "next-intl";
 import { type ReactNode, useMemo, useState } from "react";
 import { ConnectAgentDialog } from "@/components/mcp/connect-agent-dialog";
-import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Progress } from "@/components/ui/progress";
 import { Skeleton } from "@/components/ui/skeleton";
@@ -410,29 +409,25 @@ function SidebarUsageFooter({
 	return (
 		<div className={containerClass}>
 			<CreditBalanceDisplay />
-			<div className="space-y-0.5">
+			<div className="relative grid grid-cols-2 before:absolute before:inset-y-1 before:left-1/2 before:w-px before:-translate-x-1/2 before:bg-border">
 				<Link
 					href={`/dashboard/${workspaceId}/earn-credits`}
 					onClick={onNavigate}
-					className="group flex w-full items-center justify-between rounded-md px-1.5 py-1 transition-colors hover:bg-accent"
+					className="group relative z-10 mx-0.5 flex min-w-0 items-center justify-center gap-1 rounded-md px-1.5 py-1 text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
 				>
-					<span className="flex items-center gap-1.5 text-xs text-muted-foreground group-hover:text-accent-foreground">
-						<Zap className="h-3 w-3 shrink-0" />
-						Earn credits
-					</span>
-					<Badge className="h-4 rounded px-1 text-[10px] font-semibold leading-none bg-emerald-600 text-white border-transparent hover:bg-emerald-600">
+					<Zap className="h-3 w-3 shrink-0" />
+					<span className="truncate">Earn</span>
+					<SidebarButtonBadge className="h-4 px-1 text-[10px] bg-emerald-600 text-white hover:bg-emerald-600">
 						FREE
-					</Badge>
+					</SidebarButtonBadge>
 				</Link>
 				<Link
 					href={`/dashboard/${workspaceId}/buy-more`}
 					onClick={onNavigate}
-					className="group flex w-full items-center justify-between rounded-md px-1.5 py-1 transition-colors hover:bg-accent"
+					className="group relative z-10 mx-0.5 flex min-w-0 items-center justify-center gap-1 rounded-md px-1.5 py-1 text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
 				>
-					<span className="flex items-center gap-1.5 text-xs text-muted-foreground group-hover:text-accent-foreground">
-						<CreditCard className="h-3 w-3 shrink-0" />
-						Buy credits
-					</span>
+					<CreditCard className="h-3 w-3 shrink-0" />
+					<span className="truncate">Buy</span>
 				</Link>
 			</div>
 		</div>

From c31f72e5bb7c67f56e62b4ba140df4dd707fa84f Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 00:59:16 +0530
Subject: [PATCH 16/27] refactor(sidebar): simplify NotificationsDropdown
 aria-label and adjust Sidebar layout

- Updated aria-label in NotificationsDropdown for improved accessibility and clarity.
- Adjusted Sidebar layout to enhance spacing and visual consistency.
---
 .../components/layout/ui/sidebar/NotificationsDropdown.tsx  | 6 +-----
 surfsense_web/components/layout/ui/sidebar/Sidebar.tsx      | 2 +-
 2 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
index f9441d2c3..4fe035ec2 100644
--- a/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
@@ -274,11 +274,7 @@ export function NotificationsDropdown({
 			type="button"
 			variant="ghost"
 			size="icon"
-			aria-label={
-				notifications.totalUnreadCount > 0
-					? `Notifications, ${unreadLabel} unread`
-					: "Notifications"
-			}
+			aria-label="Notifications"
 			className={cn(
 				"relative h-10 w-10 rounded-lg text-muted-foreground hover:bg-accent hover:text-accent-foreground",
 				open && "bg-accent text-accent-foreground"
diff --git a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
index d1a568fa9..483d3a43d 100644
--- a/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/Sidebar.tsx
@@ -201,7 +201,7 @@ export function Sidebar({
 
 			<div
 				className={cn(
-					"relative flex flex-col gap-0.5 pt-1.5 pb-0 after:absolute after:inset-x-3 after:bottom-0 after:h-px after:bg-border after:transition-opacity",
+					"relative flex flex-col gap-0.5 pt-1.5 pb-0 after:absolute after:inset-x-0 after:bottom-0 after:h-px after:bg-border after:transition-opacity",
 					isSidebarNavScrolled ? "after:opacity-100" : "after:opacity-0"
 				)}
 			>

From e48b1c1f90c18052e7561e19fced4a7a908edaba Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 01:02:05 +0530
Subject: [PATCH 17/27] refactor(playground): remove API Keys section and
 update navigation

- Deleted the ApiKeysSection component to streamline the Playground layout.
- Updated PlaygroundLayoutShell and PlaygroundIndex to remove references to API Keys.
- Redirected API Keys page to User Settings for improved navigation flow.
---
 .../playground/api-keys/page.tsx              |  8 +-
 .../components/api-keys-section.tsx           | 82 -------------------
 .../playground/components/api-reference.tsx   |  6 +-
 .../components/playground-index.tsx           | 17 +---
 .../playground/layout-shell.tsx               |  9 +-
 5 files changed, 7 insertions(+), 115 deletions(-)
 delete mode 100644 surfsense_web/app/dashboard/[workspace_id]/playground/components/api-keys-section.tsx

diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/api-keys/page.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/api-keys/page.tsx
index 0dbd12818..2df3ec58e 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/api-keys/page.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/api-keys/page.tsx
@@ -1,4 +1,4 @@
-import { ApiKeysSection } from "../components/api-keys-section";
+import { redirect } from "next/navigation";
 
 export default async function PlaygroundApiKeysPage({
 	params,
@@ -7,9 +7,5 @@ export default async function PlaygroundApiKeysPage({
 }) {
 	const { workspace_id } = await params;
 
-	return (
-		<div className="mx-auto w-full max-w-3xl">
-			<ApiKeysSection workspaceId={Number(workspace_id)} />
-		</div>
-	);
+	redirect(`/dashboard/${workspace_id}/user-settings/api-key`);
 }
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-keys-section.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-keys-section.tsx
deleted file mode 100644
index 2e1f272e9..000000000
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-keys-section.tsx
+++ /dev/null
@@ -1,82 +0,0 @@
-"use client";
-
-import { useQuery } from "@tanstack/react-query";
-import { useAtomValue } from "jotai";
-import { useState } from "react";
-import { toast } from "sonner";
-import { updateWorkspaceApiAccessMutationAtom } from "@/atoms/workspaces/workspace-mutation.atoms";
-import { Label } from "@/components/ui/label";
-import { Skeleton } from "@/components/ui/skeleton";
-import { Switch } from "@/components/ui/switch";
-import { workspacesApiService } from "@/lib/apis/workspaces-api.service";
-import { cacheKeys } from "@/lib/query-client/cache-keys";
-import { ApiKeyContent } from "../../user-settings/components/ApiKeyContent";
-
-/**
- * One-stop API key management for the playground: the workspace API-access
- * toggle (otherwise buried in workspace settings) plus the personal API key
- * manager (otherwise buried in user settings).
- */
-export function ApiKeysSection({ workspaceId }: { workspaceId: number }) {
-	const {
-		data: workspace,
-		isLoading,
-		refetch,
-	} = useQuery({
-		queryKey: cacheKeys.workspaces.detail(workspaceId.toString()),
-		queryFn: () => workspacesApiService.getWorkspace({ id: workspaceId }),
-		enabled: !!workspaceId,
-	});
-	const { mutateAsync: updateWorkspaceApiAccess } = useAtomValue(
-		updateWorkspaceApiAccessMutationAtom
-	);
-	const [saving, setSaving] = useState(false);
-
-	const handleToggle = async (enabled: boolean) => {
-		try {
-			setSaving(true);
-			await updateWorkspaceApiAccess({ id: workspaceId, api_access_enabled: enabled });
-			await refetch();
-		} catch (error) {
-			console.error("Error updating API access:", error);
-			toast.error(error instanceof Error ? error.message : "Failed to update API access");
-		} finally {
-			setSaving(false);
-		}
-	};
-
-	const apiAccessEnabled = !!workspace?.api_access_enabled;
-
-	return (
-		<div className="space-y-6">
-			<div>
-				<h1 className="text-xl font-semibold text-foreground md:text-2xl">API Keys</h1>
-				<p className="mt-1 text-sm text-muted-foreground">
-					Enable API access for this workspace and manage the keys that use it.
-				</p>
-			</div>
-
-			<div className="flex items-center justify-between gap-4 rounded-lg border border-border/60 px-4 py-3">
-				<div className="space-y-1">
-					<Label htmlFor="playground-api-access">API key access</Label>
-					<p className="text-xs text-muted-foreground">
-						Allow API keys to access this workspace.
-						{!isLoading && !apiAccessEnabled && " Currently disabled — keys won't work here."}
-					</p>
-				</div>
-				{isLoading ? (
-					<Skeleton className="h-5 w-9 rounded-full" />
-				) : (
-					<Switch
-						id="playground-api-access"
-						checked={apiAccessEnabled}
-						disabled={saving}
-						onCheckedChange={handleToggle}
-					/>
-				)}
-			</div>
-
-			<ApiKeyContent />
-		</div>
-	);
-}
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx
index acdcddd6c..1bc4fe1d3 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx
@@ -90,9 +90,9 @@ export function ApiReference({
 			<div>
 				<h2 className="text-base font-semibold">API reference</h2>
 				<p className="mt-1 text-sm text-muted-foreground">
-					Call this API from your own project. Create a key under{" "}
-					<span className="font-medium text-foreground">API Keys</span> (and enable API access for
-					this workspace), then send it as a{" "}
+					Call this API from your own project. Create a key in{" "}
+					<span className="font-medium text-foreground">User settings</span> and enable API access
+					for this workspace, then send it as a{" "}
 					<code className="rounded bg-muted/40 px-1 py-0.5 text-xs">Authorization: Bearer</code>{" "}
 					header.
 				</p>
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
index cf10260ad..c634dbc6d 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { ArrowRight, History, KeyRound } from "lucide-react";
+import { ArrowRight, History } from "lucide-react";
 import Link from "next/link";
 import { useMemo } from "react";
 import { useScraperCapabilities } from "@/hooks/use-scraper-capabilities";
@@ -41,21 +41,6 @@ export function PlaygroundIndex({ workspaceId }: { workspaceId: number }) {
 					</div>
 					<ArrowRight className="h-4 w-4 text-muted-foreground" />
 				</Link>
-				<Link
-					href={`${base}/api-keys`}
-					className="flex items-center justify-between rounded-lg border border-border/60 bg-accent/40 px-4 py-3 transition-colors hover:bg-accent"
-				>
-					<div className="flex items-center gap-3">
-						<KeyRound className="h-5 w-5 text-muted-foreground" />
-						<div>
-							<p className="text-sm font-medium">API Keys</p>
-							<p className="text-xs text-muted-foreground">
-								Enable workspace access and manage keys
-							</p>
-						</div>
-					</div>
-					<ArrowRight className="h-4 w-4 text-muted-foreground" />
-				</Link>
 			</div>
 
 			<div className="space-y-6">
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
index 43331651d..c680cf6d4 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { History, KeyRound, LayoutGrid } from "lucide-react";
+import { History, LayoutGrid } from "lucide-react";
 import Link from "next/link";
 import { useSelectedLayoutSegments } from "next/navigation";
 import type React from "react";
@@ -87,13 +87,6 @@ export function PlaygroundLayoutShell({ workspaceId, children }: PlaygroundLayou
 				href: `${base}/runs`,
 				icon: <History className="h-4 w-4" />,
 			},
-			{
-				type: "item",
-				value: "api-keys",
-				label: "API Keys",
-				href: `${base}/api-keys`,
-				icon: <KeyRound className="h-4 w-4" />,
-			},
 			...PLAYGROUND_PLATFORMS.flatMap<PlaygroundNavItem>((platform) => [
 				{
 					type: "section",

From 7ec33171c7e2dfab98aadca22c48d6763274d086 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 01:17:09 +0530
Subject: [PATCH 18/27] feat(playground): enhance API Playground with alert
 component and updated Reddit SVG

---
 .../components/playground-index.tsx           | 24 +++++---
 surfsense_web/public/connectors/reddit.svg    | 58 ++++++++++++++++++-
 2 files changed, 74 insertions(+), 8 deletions(-)

diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
index c634dbc6d..17f0591c8 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
@@ -1,8 +1,9 @@
 "use client";
 
-import { ArrowRight, History } from "lucide-react";
+import { ArrowRight, History, Info } from "lucide-react";
 import Link from "next/link";
 import { useMemo } from "react";
+import { Alert, AlertDescription } from "@/components/ui/alert";
 import { useScraperCapabilities } from "@/hooks/use-scraper-capabilities";
 import { PLAYGROUND_PLATFORMS } from "@/lib/playground/catalog";
 import { formatPricing } from "@/lib/playground/format";
@@ -20,12 +21,21 @@ export function PlaygroundIndex({ workspaceId }: { workspaceId: number }) {
 
 	return (
 		<div className="space-y-8">
-			<div>
-				<h1 className="text-xl font-semibold text-foreground md:text-2xl">API Playground</h1>
-				<p className="mt-1 text-sm text-muted-foreground">
-					Manually run SurfSense's platform-native APIs and inspect their output.
-				</p>
-			</div>
+			<Alert>
+				<Info />
+				<AlertDescription>
+					<p>
+						Manually run SurfSense's platform-native APIs and inspect their output. To use these APIs outside SurfSense,{" "}
+						<Link
+							href={`/dashboard/${workspaceId}/user-settings/api-key`}
+							className="font-medium text-foreground underline-offset-4 hover:underline"
+						>
+							create an API key
+						</Link>
+						.
+					</p>
+				</AlertDescription>
+			</Alert>
 
 			<div className="grid gap-3 sm:grid-cols-2">
 				<Link
diff --git a/surfsense_web/public/connectors/reddit.svg b/surfsense_web/public/connectors/reddit.svg
index 97b05bc57..488596ce1 100644
--- a/surfsense_web/public/connectors/reddit.svg
+++ b/surfsense_web/public/connectors/reddit.svg
@@ -1 +1,57 @@
-<svg role="img" viewBox="0 0 24 24" fill="#FF4500" xmlns="http://www.w3.org/2000/svg"><title>Reddit</title><path d="M12 0C5.373 0 0 5.373 0 12c0 3.314 1.343 6.314 3.515 8.485l-2.286 2.286C.775 23.225 1.097 24 1.738 24H12c6.627 0 12-5.373 12-12S18.627 0 12 0Zm4.388 3.199c1.104 0 1.999.895 1.999 1.999 0 1.105-.895 2-1.999 2-.946 0-1.739-.657-1.947-1.539v.002c-1.147.162-2.032 1.15-2.032 2.341v.007c1.776.067 3.4.567 4.686 1.363.473-.363 1.064-.58 1.707-.58 1.547 0 2.802 1.254 2.802 2.802 0 1.117-.655 2.081-1.601 2.531-.088 3.256-3.637 5.876-7.997 5.876-4.361 0-7.905-2.617-7.998-5.87-.954-.447-1.614-1.415-1.614-2.538 0-1.548 1.255-2.802 2.803-2.802.645 0 1.239.218 1.712.585 1.275-.79 2.881-1.291 4.64-1.365v-.01c0-1.663 1.263-3.034 2.88-3.207.188-.911.993-1.595 1.959-1.595Zm-8.085 8.376c-.784 0-1.459.78-1.506 1.797-.047 1.016.64 1.429 1.426 1.429.786 0 1.371-.369 1.418-1.385.047-1.017-.553-1.841-1.338-1.841Zm7.406 0c-.786 0-1.385.824-1.338 1.841.047 1.017.634 1.385 1.418 1.385.785 0 1.473-.413 1.426-1.429-.046-1.017-.721-1.797-1.506-1.797Zm-3.703 4.013c-.974 0-1.907.048-2.77.135-.147.015-.241.168-.183.305.483 1.154 1.622 1.964 2.953 1.964 1.33 0 2.47-.81 2.953-1.964.057-.137-.037-.29-.184-.305-.863-.087-1.795-.135-2.769-.135Z"/></svg>
\ No newline at end of file
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" class="_1O4jTk-dZ-VIxsCuYB6OR8" viewBox="0 0 216 216">
+    <defs>
+        <radialGradient id="snoo-radial-gragient" cx="169.75" cy="92.19" r="50.98" fx="169.75" fy="92.19" gradientTransform="matrix(1 0 0 .87 0 11.64)" gradientUnits="userSpaceOnUse">
+            <stop offset="0" stop-color="#feffff"/>
+            <stop offset=".4" stop-color="#feffff"/>
+            <stop offset=".51" stop-color="#f9fcfc"/>
+            <stop offset=".62" stop-color="#edf3f5"/>
+            <stop offset=".7" stop-color="#dee9ec"/>
+            <stop offset=".72" stop-color="#d8e4e8"/>
+            <stop offset=".76" stop-color="#ccd8df"/>
+            <stop offset=".8" stop-color="#c8d5dd"/>
+            <stop offset=".83" stop-color="#ccd6de"/>
+            <stop offset=".85" stop-color="#d8dbe2"/>
+            <stop offset=".88" stop-color="#ede3e9"/>
+            <stop offset=".9" stop-color="#ffebef"/>
+        </radialGradient>
+        <radialGradient xlink:href="#snoo-radial-gragient" id="snoo-radial-gragient-2" cx="47.31" r="50.98" fx="47.31"/>
+        <radialGradient xlink:href="#snoo-radial-gragient" id="snoo-radial-gragient-3" cx="109.61" cy="85.59" r="153.78" fx="109.61" fy="85.59" gradientTransform="matrix(1 0 0 .7 0 25.56)"/>
+        <radialGradient id="snoo-radial-gragient-4" cx="-6.01" cy="64.68" r="12.85" fx="-6.01" fy="64.68" gradientTransform="matrix(1.07 0 0 1.55 81.08 27.26)" gradientUnits="userSpaceOnUse">
+            <stop offset="0" stop-color="#f60"/>
+            <stop offset=".5" stop-color="#ff4500"/>
+            <stop offset=".7" stop-color="#fc4301"/>
+            <stop offset=".82" stop-color="#f43f07"/>
+            <stop offset=".92" stop-color="#e53812"/>
+            <stop offset="1" stop-color="#d4301f"/>
+        </radialGradient>
+        <radialGradient xlink:href="#snoo-radial-gragient-4" id="snoo-radial-gragient-5" cx="-73.55" cy="64.68" r="12.85" fx="-73.55" fy="64.68" gradientTransform="matrix(-1.07 0 0 1.55 62.87 27.26)"/>
+        <radialGradient id="snoo-radial-gragient-6" cx="107.93" cy="166.96" r="45.3" fx="107.93" fy="166.96" gradientTransform="matrix(1 0 0 .66 0 57.4)" gradientUnits="userSpaceOnUse">
+            <stop offset="0" stop-color="#172e35"/>
+            <stop offset=".29" stop-color="#0e1c21"/>
+            <stop offset=".73" stop-color="#030708"/>
+            <stop offset="1"/>
+        </radialGradient>
+        <radialGradient xlink:href="#snoo-radial-gragient" id="snoo-radial-gragient-7" cx="147.88" cy="32.94" r="39.77" fx="147.88" fy="32.94" gradientTransform="matrix(1 0 0 .98 0 .54)"/>
+        <radialGradient id="snoo-radial-gragient-8" cx="131.31" cy="73.08" r="32.6" fx="131.31" fy="73.08" gradientUnits="userSpaceOnUse">
+            <stop offset=".48" stop-color="#7a9299"/>
+            <stop offset=".67" stop-color="#172e35"/>
+            <stop offset=".75"/>
+            <stop offset=".82" stop-color="#172e35"/>
+        </radialGradient>
+        <style>
+            .snoo-cls-11{stroke-width:0;fill:#ffc49c}
+        </style>
+    </defs>
+    <path fill="#ff4500" stroke-width="0" d="M108 0C48.35 0 0 48.35 0 108c0 29.82 12.09 56.82 31.63 76.37l-20.57 20.57C6.98 209.02 9.87 216 15.64 216H108c59.65 0 108-48.35 108-108S167.65 0 108 0Z"/>
+    <circle cx="169.22" cy="106.98" r="25.22" fill="url(#snoo-radial-gragient)" stroke-width="0"/>
+    <circle cx="46.78" cy="106.98" r="25.22" fill="url(#snoo-radial-gragient-2)" stroke-width="0"/>
+    <ellipse cx="108.06" cy="128.64" fill="url(#snoo-radial-gragient-3)" stroke-width="0" rx="72" ry="54"/>
+    <path fill="url(#snoo-radial-gragient-4)" stroke-width="0" d="M86.78 123.48c-.42 9.08-6.49 12.38-13.56 12.38s-12.46-4.93-12.04-14.01c.42-9.08 6.49-15.02 13.56-15.02s12.46 7.58 12.04 16.66Z"/>
+    <path fill="url(#snoo-radial-gragient-5)" stroke-width="0" d="M129.35 123.48c.42 9.08 6.49 12.38 13.56 12.38s12.46-4.93 12.04-14.01c-.42-9.08-6.49-15.02-13.56-15.02s-12.46 7.58-12.04 16.66Z"/>
+    <ellipse cx="79.63" cy="116.37" class="snoo-cls-11" rx="2.8" ry="3.05"/>
+    <ellipse cx="146.21" cy="116.37" class="snoo-cls-11" rx="2.8" ry="3.05"/>
+    <path fill="url(#snoo-radial-gragient-6)" stroke-width="0" d="M108.06 142.92c-8.76 0-17.16.43-24.92 1.22-1.33.13-2.17 1.51-1.65 2.74 4.35 10.39 14.61 17.69 26.57 17.69s22.23-7.3 26.57-17.69c.52-1.23-.33-2.61-1.65-2.74-7.77-.79-16.16-1.22-24.92-1.22Z"/>
+    <circle cx="147.49" cy="49.43" r="17.87" fill="url(#snoo-radial-gragient-7)" stroke-width="0"/>
+    <path fill="url(#snoo-radial-gragient-8)" stroke-width="0" d="M107.8 76.92c-2.14 0-3.87-.89-3.87-2.27 0-16.01 13.03-29.04 29.04-29.04 2.14 0 3.87 1.73 3.87 3.87s-1.73 3.87-3.87 3.87c-11.74 0-21.29 9.55-21.29 21.29 0 1.38-1.73 2.27-3.87 2.27Z"/>
+    <path fill="#842123" stroke-width="0" d="M62.82 122.65c.39-8.56 6.08-14.16 12.69-14.16 6.26 0 11.1 6.39 11.28 14.33.17-8.88-5.13-15.99-12.05-15.99s-13.14 6.05-13.56 15.2c-.42 9.15 4.97 13.83 12.04 13.83h.52c-6.44-.16-11.3-4.79-10.91-13.2Zm90.48 0c-.39-8.56-6.08-14.16-12.69-14.16-6.26 0-11.1 6.39-11.28 14.33-.17-8.88 5.13-15.99 12.05-15.99 7.07 0 13.14 6.05 13.56 15.2.42 9.15-4.97 13.83-12.04 13.83h-.52c6.44-.16 11.3-4.79 10.91-13.2Z"/>
+</svg>
\ No newline at end of file

From 9109f0aa058997b86f2f98b0e8996732fbd591bb Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 02:07:44 +0530
Subject: [PATCH 19/27] refactor(playground): enhance PlaygroundLayoutShell
 with improved navigation and component structure

- Added new TopLevelNavLink and ProviderNavGroup components for better organization of navigation items.
- Updated state management for expanded providers and active navigation items.
- Refactored navigation item structure to simplify rendering and improve clarity.
- Integrated ChevronRight icon for visual indication of expandable sections.
---
 .../playground/layout-shell.tsx               | 268 +++++++++++-------
 1 file changed, 170 insertions(+), 98 deletions(-)

diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
index c680cf6d4..08ca498af 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
@@ -1,12 +1,20 @@
 "use client";
 
-import { History, LayoutGrid } from "lucide-react";
+import { ChevronRight, History, LayoutGrid } from "lucide-react";
 import Link from "next/link";
 import { useSelectedLayoutSegments } from "next/navigation";
 import type React from "react";
-import { useCallback, useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
+import { Button } from "@/components/ui/button";
+import {
+	Drawer,
+	DrawerContent,
+	DrawerHandle,
+	DrawerTitle,
+	DrawerTrigger,
+} from "@/components/ui/drawer";
 import { Separator } from "@/components/ui/separator";
-import { PLAYGROUND_PLATFORMS, type PlatformIcon } from "@/lib/playground/catalog";
+import { PLAYGROUND_PLATFORMS, type PlaygroundPlatform, type PlaygroundVerb } from "@/lib/playground/catalog";
 import { cn } from "@/lib/utils";
 
 interface PlaygroundLayoutShellProps {
@@ -14,28 +22,21 @@ interface PlaygroundLayoutShellProps {
 	children: React.ReactNode;
 }
 
-type PlaygroundNavItem =
-	| {
-			type: "item";
-			value: string;
-			label: string;
-			href: string;
-			icon: React.ReactNode;
-			indented?: boolean;
-	  }
-	| {
-			type: "section";
-			value: string;
-			label: string;
-			icon: PlatformIcon;
-	  };
+interface TopLevelNavItem {
+	value: "overview" | "runs";
+	label: string;
+	href: string;
+	icon: React.ReactNode;
+}
 
-function PlaygroundNavLink({
+function TopLevelNavLink({
 	item,
 	activeValue,
+	onNavigate,
 }: {
-	item: Extract<PlaygroundNavItem, { type: "item" }>;
+	item: TopLevelNavItem;
 	activeValue: string;
+	onNavigate?: () => void;
 }) {
 	const isActive = activeValue === item.value;
 
@@ -45,9 +46,9 @@ function PlaygroundNavLink({
 			replace
 			scroll={false}
 			prefetch
+			onClick={onNavigate}
 			className={cn(
 				"inline-flex h-auto items-center justify-start gap-3 rounded-md px-3 py-2.5 text-left text-sm font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
-				item.indented && "pl-9",
 				isActive
 					? "bg-accent text-accent-foreground"
 					: "bg-transparent text-muted-foreground hover:bg-accent hover:text-accent-foreground"
@@ -59,50 +60,109 @@ function PlaygroundNavLink({
 	);
 }
 
+function ProviderNavGroup({
+	platform,
+	base,
+	activeValue,
+	isExpanded,
+	onToggle,
+	onNavigate,
+}: {
+	platform: PlaygroundPlatform;
+	base: string;
+	activeValue: string;
+	isExpanded: boolean;
+	onToggle: () => void;
+	onNavigate?: () => void;
+}) {
+	const Icon = platform.icon;
+
+	return (
+		<div className="flex flex-col gap-0.5">
+			<button
+				type="button"
+				aria-expanded={isExpanded}
+				onClick={onToggle}
+				className={cn(
+					"inline-flex h-auto items-center justify-start gap-3 rounded-md px-3 py-2.5 text-left text-sm font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
+					isExpanded
+						? "text-accent-foreground"
+						: "text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+				)}
+			>
+				<Icon className="h-4 w-4 shrink-0" />
+				<span className="min-w-0 truncate">{platform.label}</span>
+				<ChevronRight
+					className={cn("ml-auto h-4 w-4 shrink-0 transition-transform", isExpanded && "rotate-90")}
+				/>
+			</button>
+			<div
+				className={cn(
+					"grid overflow-hidden transition-[grid-template-rows,opacity] duration-200 ease-out",
+					isExpanded ? "grid-rows-[1fr] opacity-100" : "grid-rows-[0fr] opacity-0"
+				)}
+				aria-hidden={!isExpanded}
+			>
+				<div className="min-h-0 overflow-hidden">
+					<div className="flex flex-col gap-0.5 pl-10">
+						{platform.verbs.map((verb) => {
+							const value = `${platform.id}/${verb.verb}`;
+							const isActive = activeValue === value;
+							return (
+								<Link
+									key={value}
+									href={`${base}/${platform.id}/${verb.verb}`}
+									replace
+									scroll={false}
+									prefetch
+									onClick={onNavigate}
+									className={cn(
+										"inline-flex h-auto items-center justify-start rounded-md px-3 py-2 text-left text-sm font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
+										isActive
+											? "bg-accent text-accent-foreground"
+											: "text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+									)}
+								>
+									<span className="min-w-0 truncate">{verb.label}</span>
+								</Link>
+							);
+						})}
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+}
+
 export function PlaygroundLayoutShell({ workspaceId, children }: PlaygroundLayoutShellProps) {
 	const segments = useSelectedLayoutSegments();
-	const [tabScrollPos, setTabScrollPos] = useState<"start" | "middle" | "end">("start");
 	const base = `/dashboard/${workspaceId}/playground`;
+	const activePlatform = PLAYGROUND_PLATFORMS.some((platform) => platform.id === segments[0])
+		? segments[0]
+		: null;
+	const [expandedProvider, setExpandedProvider] = useState<string | null>(activePlatform);
+	const [mobileNavOpen, setMobileNavOpen] = useState(false);
 
-	const handleTabScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
-		const el = e.currentTarget;
-		const atStart = el.scrollLeft <= 2;
-		const atEnd = el.scrollWidth - el.scrollLeft - el.clientWidth <= 2;
-		setTabScrollPos(atStart ? "start" : atEnd ? "end" : "middle");
-	}, []);
+	useEffect(() => {
+		if (activePlatform) {
+			setExpandedProvider(activePlatform);
+		}
+	}, [activePlatform]);
 
-	const navItems = useMemo<PlaygroundNavItem[]>(
+	const topLevelItems = useMemo<TopLevelNavItem[]>(
 		() => [
 			{
-				type: "item",
 				value: "overview",
 				label: "Overview",
 				href: base,
 				icon: <LayoutGrid className="h-4 w-4" />,
 			},
 			{
-				type: "item",
 				value: "runs",
 				label: "Runs",
 				href: `${base}/runs`,
 				icon: <History className="h-4 w-4" />,
 			},
-			...PLAYGROUND_PLATFORMS.flatMap<PlaygroundNavItem>((platform) => [
-				{
-					type: "section",
-					value: platform.id,
-					label: platform.label,
-					icon: platform.icon,
-				},
-				...platform.verbs.map((verb) => ({
-					type: "item" as const,
-					value: `${platform.id}/${verb.verb}`,
-					label: verb.label,
-					href: `${base}/${platform.id}/${verb.verb}`,
-					icon: <span className="h-4 w-4" />,
-					indented: true,
-				})),
-			]),
 		],
 		[base]
 	);
@@ -110,14 +170,39 @@ export function PlaygroundLayoutShell({ workspaceId, children }: PlaygroundLayou
 	const activeValue =
 		segments.length >= 2
 			? `${segments[0]}/${segments[1]}`
-			: segments[0] && navItems.some((item) => item.type === "item" && item.value === segments[0])
+			: segments[0] && topLevelItems.some((item) => item.value === segments[0])
 				? segments[0]
 				: "overview";
-	const selectedLabel =
-		navItems.find((item) => item.type === "item" && item.value === activeValue)?.label ??
-		"API Playground";
-	const mobileItems = navItems.filter(
-		(item): item is Extract<PlaygroundNavItem, { type: "item" }> => item.type === "item"
+
+	const selectedLabel = getSelectedLabel(activeValue, topLevelItems);
+
+	const renderNav = (onNavigate?: () => void) => (
+		<>
+			{topLevelItems.map((item) => (
+				<TopLevelNavLink
+					key={item.value}
+					item={item}
+					activeValue={activeValue}
+					onNavigate={onNavigate}
+				/>
+			))}
+			<Separator className="my-3 bg-border" />
+			<div className="flex flex-col gap-0.5">
+				{PLAYGROUND_PLATFORMS.map((platform) => (
+					<ProviderNavGroup
+						key={platform.id}
+						platform={platform}
+						base={base}
+						activeValue={activeValue}
+						isExpanded={expandedProvider === platform.id}
+						onToggle={() =>
+							setExpandedProvider((current) => (current === platform.id ? null : platform.id))
+						}
+						onNavigate={onNavigate}
+					/>
+				))}
+			</div>
+		</>
 	);
 
 	return (
@@ -127,52 +212,27 @@ export function PlaygroundLayoutShell({ workspaceId, children }: PlaygroundLayou
 					API Playground
 				</h1>
 				<nav className="hidden flex-col gap-0.5 md:flex">
-					{navItems.map((item) => {
-						if (item.type === "section") {
-							const Icon = item.icon;
-							return (
-								<div
-									key={item.value}
-									className="mt-3 flex items-center gap-2 px-3 py-1 text-xs font-medium text-muted-foreground first:mt-1"
-								>
-									<Icon className="h-3.5 w-3.5 shrink-0" />
-									<span className="truncate">{item.label}</span>
-								</div>
-							);
-						}
-
-						return <PlaygroundNavLink key={item.value} item={item} activeValue={activeValue} />;
-					})}
+					{renderNav()}
 				</nav>
-				<div
-					className="overflow-x-auto border-b border-border pb-3 md:hidden"
-					onScroll={handleTabScroll}
-					style={{
-						maskImage: `linear-gradient(to right, ${tabScrollPos === "start" ? "black" : "transparent"}, black 24px, black calc(100% - 24px), ${tabScrollPos === "end" ? "black" : "transparent"})`,
-						WebkitMaskImage: `linear-gradient(to right, ${tabScrollPos === "start" ? "black" : "transparent"}, black 24px, black calc(100% - 24px), ${tabScrollPos === "end" ? "black" : "transparent"})`,
-					}}
-				>
-					<div className="flex gap-1">
-						{mobileItems.map((item) => (
-							<Link
-								key={item.value}
-								href={item.href}
-								replace
-								scroll={false}
-								prefetch
-								className={cn(
-									"inline-flex h-auto shrink-0 items-center gap-2 rounded-md px-3 py-1.5 text-xs font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
-									activeValue === item.value
-										? "bg-accent text-accent-foreground"
-										: "bg-transparent text-muted-foreground hover:bg-accent hover:text-accent-foreground"
-								)}
-							>
-								{item.icon}
-								{item.label}
-							</Link>
-						))}
-					</div>
-				</div>
+				<Drawer open={mobileNavOpen} onOpenChange={setMobileNavOpen} shouldScaleBackground={false}>
+					<DrawerTrigger asChild>
+						<Button
+							type="button"
+							variant="outline"
+							className="flex h-10 w-full justify-between bg-transparent px-3 hover:bg-accent md:hidden"
+						>
+							<span className="truncate">{selectedLabel}</span>
+							<ChevronRight className="h-4 w-4 rotate-90 text-muted-foreground" />
+						</Button>
+					</DrawerTrigger>
+					<DrawerContent className="h-[88vh] overflow-hidden rounded-t-2xl border bg-popover text-popover-foreground">
+						<DrawerHandle className="mt-3 h-1.5 w-10" />
+						<DrawerTitle className="sr-only">API Playground navigation</DrawerTitle>
+						<nav className="flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto p-4">
+							{renderNav(() => setMobileNavOpen(false))}
+						</nav>
+					</DrawerContent>
+				</Drawer>
 			</div>
 
 			<div className="min-w-0 flex-1">
@@ -185,3 +245,15 @@ export function PlaygroundLayoutShell({ workspaceId, children }: PlaygroundLayou
 		</section>
 	);
 }
+
+function getSelectedLabel(activeValue: string, topLevelItems: TopLevelNavItem[]): string {
+	const topLevelItem = topLevelItems.find((item) => item.value === activeValue);
+	if (topLevelItem) return topLevelItem.label;
+
+	const [platformId, verbId] = activeValue.split("/");
+	const platform = PLAYGROUND_PLATFORMS.find((item) => item.id === platformId);
+	const verb: PlaygroundVerb | undefined = platform?.verbs.find((item) => item.verb === verbId);
+
+	if (platform && verb) return `${platform.label} / ${verb.label}`;
+	return "API Playground";
+}

From 0c2db7dfd52351c169ee2a340f27c8acae9f5f86 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 02:29:33 +0530
Subject: [PATCH 20/27] refactor(layout): streamline layout components with
 RoutedSectionShell

- Introduced RoutedSectionShell to unify navigation structure across Playground, User Settings, and Workspace Settings layouts.
- Replaced individual navigation implementations with a more cohesive and reusable component.
- Updated navigation items to include href properties for better routing.
- Enhanced mobile navigation experience with drawer support and improved scroll handling.
---
 .../playground/layout-shell.tsx               | 256 +++--------------
 .../user-settings/layout-shell.tsx            | 102 ++-----
 .../workspace-settings/layout-shell.tsx       |  99 ++-----
 surfsense_web/components/layout/index.ts      |   2 +
 .../layout/ui/RoutedSectionShell.tsx          | 267 ++++++++++++++++++
 surfsense_web/components/layout/ui/index.ts   |   2 +
 6 files changed, 357 insertions(+), 371 deletions(-)
 create mode 100644 surfsense_web/components/layout/ui/RoutedSectionShell.tsx

diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
index 08ca498af..e03667944 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
@@ -1,155 +1,26 @@
 "use client";
 
-import { ChevronRight, History, LayoutGrid } from "lucide-react";
-import Link from "next/link";
+import { History, LayoutGrid } from "lucide-react";
 import { useSelectedLayoutSegments } from "next/navigation";
 import type React from "react";
-import { useEffect, useMemo, useState } from "react";
-import { Button } from "@/components/ui/button";
+import { useMemo } from "react";
 import {
-	Drawer,
-	DrawerContent,
-	DrawerHandle,
-	DrawerTitle,
-	DrawerTrigger,
-} from "@/components/ui/drawer";
-import { Separator } from "@/components/ui/separator";
-import { PLAYGROUND_PLATFORMS, type PlaygroundPlatform, type PlaygroundVerb } from "@/lib/playground/catalog";
-import { cn } from "@/lib/utils";
+	type RoutedSectionGroup,
+	type RoutedSectionItem,
+	RoutedSectionShell,
+} from "@/components/layout";
+import { PLAYGROUND_PLATFORMS } from "@/lib/playground/catalog";
 
 interface PlaygroundLayoutShellProps {
 	workspaceId: string;
 	children: React.ReactNode;
 }
 
-interface TopLevelNavItem {
-	value: "overview" | "runs";
-	label: string;
-	href: string;
-	icon: React.ReactNode;
-}
-
-function TopLevelNavLink({
-	item,
-	activeValue,
-	onNavigate,
-}: {
-	item: TopLevelNavItem;
-	activeValue: string;
-	onNavigate?: () => void;
-}) {
-	const isActive = activeValue === item.value;
-
-	return (
-		<Link
-			href={item.href}
-			replace
-			scroll={false}
-			prefetch
-			onClick={onNavigate}
-			className={cn(
-				"inline-flex h-auto items-center justify-start gap-3 rounded-md px-3 py-2.5 text-left text-sm font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
-				isActive
-					? "bg-accent text-accent-foreground"
-					: "bg-transparent text-muted-foreground hover:bg-accent hover:text-accent-foreground"
-			)}
-		>
-			{item.icon}
-			<span className="min-w-0 truncate">{item.label}</span>
-		</Link>
-	);
-}
-
-function ProviderNavGroup({
-	platform,
-	base,
-	activeValue,
-	isExpanded,
-	onToggle,
-	onNavigate,
-}: {
-	platform: PlaygroundPlatform;
-	base: string;
-	activeValue: string;
-	isExpanded: boolean;
-	onToggle: () => void;
-	onNavigate?: () => void;
-}) {
-	const Icon = platform.icon;
-
-	return (
-		<div className="flex flex-col gap-0.5">
-			<button
-				type="button"
-				aria-expanded={isExpanded}
-				onClick={onToggle}
-				className={cn(
-					"inline-flex h-auto items-center justify-start gap-3 rounded-md px-3 py-2.5 text-left text-sm font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
-					isExpanded
-						? "text-accent-foreground"
-						: "text-muted-foreground hover:bg-accent hover:text-accent-foreground"
-				)}
-			>
-				<Icon className="h-4 w-4 shrink-0" />
-				<span className="min-w-0 truncate">{platform.label}</span>
-				<ChevronRight
-					className={cn("ml-auto h-4 w-4 shrink-0 transition-transform", isExpanded && "rotate-90")}
-				/>
-			</button>
-			<div
-				className={cn(
-					"grid overflow-hidden transition-[grid-template-rows,opacity] duration-200 ease-out",
-					isExpanded ? "grid-rows-[1fr] opacity-100" : "grid-rows-[0fr] opacity-0"
-				)}
-				aria-hidden={!isExpanded}
-			>
-				<div className="min-h-0 overflow-hidden">
-					<div className="flex flex-col gap-0.5 pl-10">
-						{platform.verbs.map((verb) => {
-							const value = `${platform.id}/${verb.verb}`;
-							const isActive = activeValue === value;
-							return (
-								<Link
-									key={value}
-									href={`${base}/${platform.id}/${verb.verb}`}
-									replace
-									scroll={false}
-									prefetch
-									onClick={onNavigate}
-									className={cn(
-										"inline-flex h-auto items-center justify-start rounded-md px-3 py-2 text-left text-sm font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
-										isActive
-											? "bg-accent text-accent-foreground"
-											: "text-muted-foreground hover:bg-accent hover:text-accent-foreground"
-									)}
-								>
-									<span className="min-w-0 truncate">{verb.label}</span>
-								</Link>
-							);
-						})}
-					</div>
-				</div>
-			</div>
-		</div>
-	);
-}
-
 export function PlaygroundLayoutShell({ workspaceId, children }: PlaygroundLayoutShellProps) {
 	const segments = useSelectedLayoutSegments();
 	const base = `/dashboard/${workspaceId}/playground`;
-	const activePlatform = PLAYGROUND_PLATFORMS.some((platform) => platform.id === segments[0])
-		? segments[0]
-		: null;
-	const [expandedProvider, setExpandedProvider] = useState<string | null>(activePlatform);
-	const [mobileNavOpen, setMobileNavOpen] = useState(false);
 
-	useEffect(() => {
-		if (activePlatform) {
-			setExpandedProvider(activePlatform);
-		}
-	}, [activePlatform]);
-
-	const topLevelItems = useMemo<TopLevelNavItem[]>(
+	const topLevelItems = useMemo<RoutedSectionItem[]>(
 		() => [
 			{
 				value: "overview",
@@ -167,6 +38,24 @@ export function PlaygroundLayoutShell({ workspaceId, children }: PlaygroundLayou
 		[base]
 	);
 
+	const providerGroups = useMemo<RoutedSectionGroup[]>(
+		() =>
+			PLAYGROUND_PLATFORMS.map((platform) => {
+				const Icon = platform.icon;
+				return {
+					value: platform.id,
+					label: platform.label,
+					icon: <Icon className="h-4 w-4 shrink-0" />,
+					items: platform.verbs.map((verb) => ({
+						value: `${platform.id}/${verb.verb}`,
+						label: verb.label,
+						href: `${base}/${platform.id}/${verb.verb}`,
+					})),
+				};
+			}),
+		[base]
+	);
+
 	const activeValue =
 		segments.length >= 2
 			? `${segments[0]}/${segments[1]}`
@@ -174,86 +63,33 @@ export function PlaygroundLayoutShell({ workspaceId, children }: PlaygroundLayou
 				? segments[0]
 				: "overview";
 
-	const selectedLabel = getSelectedLabel(activeValue, topLevelItems);
-
-	const renderNav = (onNavigate?: () => void) => (
-		<>
-			{topLevelItems.map((item) => (
-				<TopLevelNavLink
-					key={item.value}
-					item={item}
-					activeValue={activeValue}
-					onNavigate={onNavigate}
-				/>
-			))}
-			<Separator className="my-3 bg-border" />
-			<div className="flex flex-col gap-0.5">
-				{PLAYGROUND_PLATFORMS.map((platform) => (
-					<ProviderNavGroup
-						key={platform.id}
-						platform={platform}
-						base={base}
-						activeValue={activeValue}
-						isExpanded={expandedProvider === platform.id}
-						onToggle={() =>
-							setExpandedProvider((current) => (current === platform.id ? null : platform.id))
-						}
-						onNavigate={onNavigate}
-					/>
-				))}
-			</div>
-		</>
-	);
+	const selectedLabel = getSelectedLabel(activeValue, topLevelItems, providerGroups);
 
 	return (
-		<section className="flex h-full min-h-[min(680px,calc(100vh-5rem))] w-full select-none flex-col gap-6 md:flex-row">
-			<div className="md:w-[220px] md:shrink-0">
-				<h1 className="mb-4 px-1 text-xl font-semibold tracking-tight text-foreground md:text-2xl">
-					API Playground
-				</h1>
-				<nav className="hidden flex-col gap-0.5 md:flex">
-					{renderNav()}
-				</nav>
-				<Drawer open={mobileNavOpen} onOpenChange={setMobileNavOpen} shouldScaleBackground={false}>
-					<DrawerTrigger asChild>
-						<Button
-							type="button"
-							variant="outline"
-							className="flex h-10 w-full justify-between bg-transparent px-3 hover:bg-accent md:hidden"
-						>
-							<span className="truncate">{selectedLabel}</span>
-							<ChevronRight className="h-4 w-4 rotate-90 text-muted-foreground" />
-						</Button>
-					</DrawerTrigger>
-					<DrawerContent className="h-[88vh] overflow-hidden rounded-t-2xl border bg-popover text-popover-foreground">
-						<DrawerHandle className="mt-3 h-1.5 w-10" />
-						<DrawerTitle className="sr-only">API Playground navigation</DrawerTitle>
-						<nav className="flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto p-4">
-							{renderNav(() => setMobileNavOpen(false))}
-						</nav>
-					</DrawerContent>
-				</Drawer>
-			</div>
-
-			<div className="min-w-0 flex-1">
-				<div className="hidden md:block">
-					<h2 className="text-lg font-semibold">{selectedLabel}</h2>
-					<Separator className="mt-4 bg-border" />
-				</div>
-				<div className="min-w-0 pt-4">{children}</div>
-			</div>
-		</section>
+		<RoutedSectionShell
+			title="API Playground"
+			items={topLevelItems}
+			groups={providerGroups}
+			activeValue={activeValue}
+			selectedLabel={selectedLabel}
+			mobileNav="drawer"
+		>
+			{children}
+		</RoutedSectionShell>
 	);
 }
 
-function getSelectedLabel(activeValue: string, topLevelItems: TopLevelNavItem[]): string {
-	const topLevelItem = topLevelItems.find((item) => item.value === activeValue);
+function getSelectedLabel(
+	activeValue: string,
+	items: RoutedSectionItem[],
+	groups: RoutedSectionGroup[]
+): string {
+	const topLevelItem = items.find((item) => item.value === activeValue);
 	if (topLevelItem) return topLevelItem.label;
 
-	const [platformId, verbId] = activeValue.split("/");
-	const platform = PLAYGROUND_PLATFORMS.find((item) => item.id === platformId);
-	const verb: PlaygroundVerb | undefined = platform?.verbs.find((item) => item.verb === verbId);
+	const group = groups.find((item) => item.items.some((child) => child.value === activeValue));
+	const child = group?.items.find((item) => item.value === activeValue);
 
-	if (platform && verb) return `${platform.label} / ${verb.label}`;
+	if (group && child) return `${group.label} / ${child.label}`;
 	return "API Playground";
 }
diff --git a/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx
index 0559deaf9..aa73917ef 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx
@@ -11,14 +11,12 @@ import {
 	ShieldCheck,
 	WandSparkles,
 } from "lucide-react";
-import Link from "next/link";
 import { useSelectedLayoutSegment } from "next/navigation";
 import { useTranslations } from "next-intl";
 import type React from "react";
-import { useCallback, useMemo, useState } from "react";
-import { Separator } from "@/components/ui/separator";
+import { useMemo } from "react";
+import { type RoutedSectionItem, RoutedSectionShell } from "@/components/layout";
 import { usePlatform } from "@/hooks/use-platform";
-import { cn } from "@/lib/utils";
 
 export type UserSettingsTab =
 	| "profile"
@@ -42,50 +40,49 @@ export function UserSettingsLayoutShell({ workspaceId, children }: UserSettingsL
 	const t = useTranslations("userSettings");
 	const { isDesktop } = usePlatform();
 	const segment = useSelectedLayoutSegment();
-	const [tabScrollPos, setTabScrollPos] = useState<"start" | "middle" | "end">("start");
 
-	const handleTabScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
-		const el = e.currentTarget;
-		const atStart = el.scrollLeft <= 2;
-		const atEnd = el.scrollWidth - el.scrollLeft - el.clientWidth <= 2;
-		setTabScrollPos(atStart ? "start" : atEnd ? "end" : "middle");
-	}, []);
-
-	const navItems = useMemo(
+	const navItems = useMemo<RoutedSectionItem[]>(
 		() => [
 			{
 				value: "profile" as const,
 				label: t("profile_nav_label"),
+				href: `/dashboard/${workspaceId}/user-settings/profile`,
 				icon: <CircleUser className="h-4 w-4" />,
 			},
 			{
 				value: "api-key" as const,
 				label: t("api_key_nav_label"),
+				href: `/dashboard/${workspaceId}/user-settings/api-key`,
 				icon: <KeyRound className="h-4 w-4" />,
 			},
 			{
 				value: "prompts" as const,
 				label: "My Prompts",
+				href: `/dashboard/${workspaceId}/user-settings/prompts`,
 				icon: <WandSparkles className="h-4 w-4" />,
 			},
 			{
 				value: "community-prompts" as const,
 				label: "Community Prompts",
+				href: `/dashboard/${workspaceId}/user-settings/community-prompts`,
 				icon: <Library className="h-4 w-4" />,
 			},
 			{
 				value: "agent-permissions" as const,
 				label: "Agent Permissions",
+				href: `/dashboard/${workspaceId}/user-settings/agent-permissions`,
 				icon: <ShieldCheck className="h-4 w-4" />,
 			},
 			{
 				value: "messaging-channels" as const,
 				label: "Messaging Channels",
+				href: `/dashboard/${workspaceId}/user-settings/messaging-channels`,
 				icon: <MessageCircle className="h-4 w-4" />,
 			},
 			{
 				value: "purchases" as const,
 				label: "Purchase History",
+				href: `/dashboard/${workspaceId}/user-settings/purchases`,
 				icon: <ReceiptText className="h-4 w-4" />,
 			},
 			...(isDesktop
@@ -93,17 +90,19 @@ export function UserSettingsLayoutShell({ workspaceId, children }: UserSettingsL
 						{
 							value: "desktop" as const,
 							label: "App Preferences",
+							href: `/dashboard/${workspaceId}/user-settings/desktop`,
 							icon: <Monitor className="h-4 w-4" />,
 						},
 						{
 							value: "hotkeys" as const,
 							label: "Hotkeys",
+							href: `/dashboard/${workspaceId}/user-settings/hotkeys`,
 							icon: <Keyboard className="h-4 w-4" />,
 						},
 					]
 				: []),
 		],
-		[t, isDesktop]
+		[t, isDesktop, workspaceId]
 	);
 
 	const activeTab: UserSettingsTab =
@@ -112,72 +111,15 @@ export function UserSettingsLayoutShell({ workspaceId, children }: UserSettingsL
 			: DEFAULT_TAB;
 	const selectedLabel = navItems.find((item) => item.value === activeTab)?.label ?? t("title");
 
-	const hrefFor = (tab: UserSettingsTab) => `/dashboard/${workspaceId}/user-settings/${tab}`;
-
 	return (
-		<section className="flex h-full min-h-[min(680px,calc(100vh-5rem))] w-full select-none flex-col gap-6 md:flex-row">
-			<div className="md:w-[220px] md:shrink-0">
-				<h1 className="mb-4 px-1 text-xl font-semibold tracking-tight text-foreground md:text-2xl">
-					{t("title")}
-				</h1>
-				<nav className="hidden flex-col gap-0.5 md:flex">
-					{navItems.map((item) => (
-						<Link
-							key={item.value}
-							href={hrefFor(item.value)}
-							replace
-							scroll={false}
-							prefetch
-							className={cn(
-								"inline-flex h-auto items-center justify-start gap-3 rounded-md px-3 py-2.5 text-left text-sm font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
-								activeTab === item.value
-									? "bg-accent text-accent-foreground"
-									: "bg-transparent text-muted-foreground hover:bg-accent hover:text-accent-foreground"
-							)}
-						>
-							{item.icon}
-							{item.label}
-						</Link>
-					))}
-				</nav>
-				<div
-					className="overflow-x-auto border-b border-border pb-3 md:hidden"
-					onScroll={handleTabScroll}
-					style={{
-						maskImage: `linear-gradient(to right, ${tabScrollPos === "start" ? "black" : "transparent"}, black 24px, black calc(100% - 24px), ${tabScrollPos === "end" ? "black" : "transparent"})`,
-						WebkitMaskImage: `linear-gradient(to right, ${tabScrollPos === "start" ? "black" : "transparent"}, black 24px, black calc(100% - 24px), ${tabScrollPos === "end" ? "black" : "transparent"})`,
-					}}
-				>
-					<div className="flex gap-1">
-						{navItems.map((item) => (
-							<Link
-								key={item.value}
-								href={hrefFor(item.value)}
-								replace
-								scroll={false}
-								prefetch
-								className={cn(
-									"inline-flex h-auto shrink-0 items-center gap-2 rounded-md px-3 py-1.5 text-xs font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
-									activeTab === item.value
-										? "bg-accent text-accent-foreground"
-										: "bg-transparent text-muted-foreground hover:bg-accent hover:text-accent-foreground"
-								)}
-							>
-								{item.icon}
-								{item.label}
-							</Link>
-						))}
-					</div>
-				</div>
-			</div>
-
-			<div className="min-w-0 flex-1">
-				<div className="hidden md:block">
-					<h2 className="text-lg font-semibold">{selectedLabel}</h2>
-					<Separator className="mt-4 bg-border" />
-				</div>
-				<div className="min-w-0 pt-4 md:max-w-3xl">{children}</div>
-			</div>
-		</section>
+		<RoutedSectionShell
+			title={t("title")}
+			items={navItems}
+			activeValue={activeTab}
+			selectedLabel={selectedLabel}
+			contentClassName="md:max-w-3xl"
+		>
+			{children}
+		</RoutedSectionShell>
 	);
 }
diff --git a/surfsense_web/app/dashboard/[workspace_id]/workspace-settings/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/workspace-settings/layout-shell.tsx
index ffef57a03..80276d30a 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/workspace-settings/layout-shell.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/workspace-settings/layout-shell.tsx
@@ -1,13 +1,11 @@
 "use client";
 
 import { BookText, Cpu, Earth, Settings, UserKey } from "lucide-react";
-import Link from "next/link";
 import { useSelectedLayoutSegment } from "next/navigation";
 import { useTranslations } from "next-intl";
 import type React from "react";
-import { useCallback, useMemo, useState } from "react";
-import { Separator } from "@/components/ui/separator";
-import { cn } from "@/lib/utils";
+import { useMemo } from "react";
+import { type RoutedSectionItem, RoutedSectionShell } from "@/components/layout";
 
 export type WorkspaceSettingsTab = "general" | "models" | "team-roles" | "prompts" | "public-links";
 
@@ -24,44 +22,41 @@ export function WorkspaceSettingsLayoutShell({
 }: WorkspaceSettingsLayoutShellProps) {
 	const t = useTranslations("workspaceSettings");
 	const segment = useSelectedLayoutSegment();
-	const [tabScrollPos, setTabScrollPos] = useState<"start" | "middle" | "end">("start");
 
-	const handleTabScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
-		const el = e.currentTarget;
-		const atStart = el.scrollLeft <= 2;
-		const atEnd = el.scrollWidth - el.scrollLeft - el.clientWidth <= 2;
-		setTabScrollPos(atStart ? "start" : atEnd ? "end" : "middle");
-	}, []);
-
-	const navItems = useMemo(
+	const navItems = useMemo<RoutedSectionItem[]>(
 		() => [
 			{
 				value: "general" as const,
 				label: t("nav_general"),
+				href: `/dashboard/${workspaceId}/workspace-settings/general`,
 				icon: <Settings className="h-4 w-4" />,
 			},
 			{
 				value: "models" as const,
 				label: t("nav_models"),
+				href: `/dashboard/${workspaceId}/workspace-settings/models`,
 				icon: <Cpu className="h-4 w-4" />,
 			},
 			{
 				value: "team-roles" as const,
 				label: t("nav_team_roles"),
+				href: `/dashboard/${workspaceId}/workspace-settings/team-roles`,
 				icon: <UserKey className="h-4 w-4" />,
 			},
 			{
 				value: "prompts" as const,
 				label: t("nav_system_instructions"),
+				href: `/dashboard/${workspaceId}/workspace-settings/prompts`,
 				icon: <BookText className="h-4 w-4" />,
 			},
 			{
 				value: "public-links" as const,
 				label: t("nav_public_links"),
+				href: `/dashboard/${workspaceId}/workspace-settings/public-links`,
 				icon: <Earth className="h-4 w-4" />,
 			},
 		],
-		[t]
+		[t, workspaceId]
 	);
 
 	const activeTab: WorkspaceSettingsTab =
@@ -70,73 +65,15 @@ export function WorkspaceSettingsLayoutShell({
 			: DEFAULT_TAB;
 	const selectedLabel = navItems.find((item) => item.value === activeTab)?.label ?? t("title");
 
-	const hrefFor = (tab: WorkspaceSettingsTab) =>
-		`/dashboard/${workspaceId}/workspace-settings/${tab}`;
-
 	return (
-		<section className="flex h-full min-h-[min(680px,calc(100vh-5rem))] w-full select-none flex-col gap-6 md:flex-row">
-			<div className="md:w-[220px] md:shrink-0">
-				<h1 className="mb-4 px-1 text-xl font-semibold tracking-tight text-foreground md:text-2xl">
-					{t("title")}
-				</h1>
-				<nav className="hidden flex-col gap-0.5 md:flex">
-					{navItems.map((item) => (
-						<Link
-							key={item.value}
-							href={hrefFor(item.value)}
-							replace
-							scroll={false}
-							prefetch
-							className={cn(
-								"inline-flex h-auto items-center justify-start gap-3 rounded-md px-3 py-2.5 text-left text-sm font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
-								activeTab === item.value
-									? "bg-accent text-accent-foreground"
-									: "bg-transparent text-muted-foreground hover:bg-accent hover:text-accent-foreground"
-							)}
-						>
-							{item.icon}
-							{item.label}
-						</Link>
-					))}
-				</nav>
-				<div
-					className="overflow-x-auto border-b border-border pb-3 md:hidden"
-					onScroll={handleTabScroll}
-					style={{
-						maskImage: `linear-gradient(to right, ${tabScrollPos === "start" ? "black" : "transparent"}, black 24px, black calc(100% - 24px), ${tabScrollPos === "end" ? "black" : "transparent"})`,
-						WebkitMaskImage: `linear-gradient(to right, ${tabScrollPos === "start" ? "black" : "transparent"}, black 24px, black calc(100% - 24px), ${tabScrollPos === "end" ? "black" : "transparent"})`,
-					}}
-				>
-					<div className="flex gap-1">
-						{navItems.map((item) => (
-							<Link
-								key={item.value}
-								href={hrefFor(item.value)}
-								replace
-								scroll={false}
-								prefetch
-								className={cn(
-									"inline-flex h-auto shrink-0 items-center gap-2 rounded-md px-3 py-1.5 text-xs font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
-									activeTab === item.value
-										? "bg-accent text-accent-foreground"
-										: "bg-transparent text-muted-foreground hover:bg-accent hover:text-accent-foreground"
-								)}
-							>
-								{item.icon}
-								{item.label}
-							</Link>
-						))}
-					</div>
-				</div>
-			</div>
-
-			<div className="min-w-0 flex-1">
-				<div className="hidden md:block">
-					<h2 className="text-lg font-semibold">{selectedLabel}</h2>
-					<Separator className="mt-4" />
-				</div>
-				<div className="min-w-0 pt-4 md:max-w-3xl">{children}</div>
-			</div>
-		</section>
+		<RoutedSectionShell
+			title={t("title")}
+			items={navItems}
+			activeValue={activeTab}
+			selectedLabel={selectedLabel}
+			contentClassName="md:max-w-3xl"
+		>
+			{children}
+		</RoutedSectionShell>
 	);
 }
diff --git a/surfsense_web/components/layout/index.ts b/surfsense_web/components/layout/index.ts
index e6903c642..a4d4a88f8 100644
--- a/surfsense_web/components/layout/index.ts
+++ b/surfsense_web/components/layout/index.ts
@@ -9,6 +9,7 @@ export type {
 	User,
 	Workspace,
 } from "./types/layout.types";
+export type { RoutedSectionGroup, RoutedSectionItem } from "./ui";
 export {
 	ChatListItem,
 	CreateWorkspaceDialog,
@@ -20,6 +21,7 @@ export {
 	MobileSidebarTrigger,
 	NavIcon,
 	NavSection,
+	RoutedSectionShell,
 	Sidebar,
 	SidebarCollapseButton,
 	SidebarHeader,
diff --git a/surfsense_web/components/layout/ui/RoutedSectionShell.tsx b/surfsense_web/components/layout/ui/RoutedSectionShell.tsx
new file mode 100644
index 000000000..007244806
--- /dev/null
+++ b/surfsense_web/components/layout/ui/RoutedSectionShell.tsx
@@ -0,0 +1,267 @@
+"use client";
+
+import { ChevronRight } from "lucide-react";
+import Link from "next/link";
+import type React from "react";
+import { useCallback, useEffect, useState } from "react";
+import { Button } from "@/components/ui/button";
+import {
+	Drawer,
+	DrawerContent,
+	DrawerHandle,
+	DrawerTitle,
+	DrawerTrigger,
+} from "@/components/ui/drawer";
+import { Separator } from "@/components/ui/separator";
+import { cn } from "@/lib/utils";
+
+export interface RoutedSectionItem {
+	value: string;
+	label: string;
+	href: string;
+	icon?: React.ReactNode;
+}
+
+export interface RoutedSectionGroup {
+	value: string;
+	label: string;
+	icon?: React.ReactNode;
+	items: RoutedSectionItem[];
+}
+
+interface RoutedSectionShellProps {
+	title: string;
+	items: RoutedSectionItem[];
+	activeValue: string;
+	selectedLabel: string;
+	children: React.ReactNode;
+	groups?: RoutedSectionGroup[];
+	mobileNav?: "scroll" | "drawer";
+	contentClassName?: string;
+}
+
+function findActiveGroupValue(groups: RoutedSectionGroup[], activeValue: string): string | null {
+	return (
+		groups.find((group) => group.items.some((item) => item.value === activeValue))?.value ?? null
+	);
+}
+
+function SectionNavLink({
+	item,
+	activeValue,
+	onNavigate,
+}: {
+	item: RoutedSectionItem;
+	activeValue: string;
+	onNavigate?: () => void;
+}) {
+	const isActive = activeValue === item.value;
+
+	return (
+		<Link
+			href={item.href}
+			replace
+			scroll={false}
+			prefetch
+			onClick={onNavigate}
+			className={cn(
+				"inline-flex h-auto items-center justify-start gap-3 rounded-md px-3 py-2.5 text-left text-sm font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
+				isActive
+					? "bg-accent text-accent-foreground"
+					: "bg-transparent text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+			)}
+		>
+			{item.icon}
+			<span className="min-w-0 truncate">{item.label}</span>
+		</Link>
+	);
+}
+
+function SectionNavGroup({
+	group,
+	activeValue,
+	isExpanded,
+	onToggle,
+	onNavigate,
+}: {
+	group: RoutedSectionGroup;
+	activeValue: string;
+	isExpanded: boolean;
+	onToggle: () => void;
+	onNavigate?: () => void;
+}) {
+	return (
+		<div className="flex flex-col gap-0.5">
+			<button
+				type="button"
+				aria-expanded={isExpanded}
+				onClick={onToggle}
+				className={cn(
+					"inline-flex h-auto items-center justify-start gap-3 rounded-md px-3 py-2.5 text-left text-sm font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
+					isExpanded
+						? "text-accent-foreground"
+						: "text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+				)}
+			>
+				{group.icon}
+				<span className="min-w-0 truncate">{group.label}</span>
+				<ChevronRight
+					className={cn("ml-auto h-4 w-4 shrink-0 transition-transform", isExpanded && "rotate-90")}
+				/>
+			</button>
+			<div
+				className={cn(
+					"grid overflow-hidden transition-[grid-template-rows,opacity] duration-200 ease-out",
+					isExpanded ? "grid-rows-[1fr] opacity-100" : "grid-rows-[0fr] opacity-0"
+				)}
+				aria-hidden={!isExpanded}
+			>
+				<div className="min-h-0 overflow-hidden">
+					<div className="flex flex-col gap-0.5 pl-10">
+						{group.items.map((item) => (
+							<SectionNavLink
+								key={item.value}
+								item={item}
+								activeValue={activeValue}
+								onNavigate={onNavigate}
+							/>
+						))}
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+}
+
+export function RoutedSectionShell({
+	title,
+	items,
+	activeValue,
+	selectedLabel,
+	children,
+	groups = [],
+	mobileNav = "scroll",
+	contentClassName,
+}: RoutedSectionShellProps) {
+	const [tabScrollPos, setTabScrollPos] = useState<"start" | "middle" | "end">("start");
+	const [drawerOpen, setDrawerOpen] = useState(false);
+	const [expandedGroup, setExpandedGroup] = useState<string | null>(() =>
+		findActiveGroupValue(groups, activeValue)
+	);
+
+	useEffect(() => {
+		const activeGroup = findActiveGroupValue(groups, activeValue);
+		if (activeGroup) {
+			setExpandedGroup(activeGroup);
+		}
+	}, [activeValue, groups]);
+
+	const handleTabScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
+		const el = e.currentTarget;
+		const atStart = el.scrollLeft <= 2;
+		const atEnd = el.scrollWidth - el.scrollLeft - el.clientWidth <= 2;
+		setTabScrollPos(atStart ? "start" : atEnd ? "end" : "middle");
+	}, []);
+
+	const renderNav = (onNavigate?: () => void) => (
+		<>
+			{items.map((item) => (
+				<SectionNavLink
+					key={item.value}
+					item={item}
+					activeValue={activeValue}
+					onNavigate={onNavigate}
+				/>
+			))}
+			{groups.length > 0 && (
+				<>
+					<Separator className="my-3 bg-border" />
+					<div className="flex flex-col gap-0.5">
+						{groups.map((group) => (
+							<SectionNavGroup
+								key={group.value}
+								group={group}
+								activeValue={activeValue}
+								isExpanded={expandedGroup === group.value}
+								onToggle={() =>
+									setExpandedGroup((current) => (current === group.value ? null : group.value))
+								}
+								onNavigate={onNavigate}
+							/>
+						))}
+					</div>
+				</>
+			)}
+		</>
+	);
+
+	return (
+		<section className="flex h-full min-h-[min(680px,calc(100vh-5rem))] w-full select-none flex-col gap-6 md:flex-row">
+			<div className="md:w-[220px] md:shrink-0">
+				<h1 className="mb-4 px-1 text-xl font-semibold tracking-tight text-foreground md:text-2xl">
+					{title}
+				</h1>
+				<nav className="hidden flex-col gap-0.5 md:flex">{renderNav()}</nav>
+				{mobileNav === "drawer" ? (
+					<Drawer open={drawerOpen} onOpenChange={setDrawerOpen} shouldScaleBackground={false}>
+						<DrawerTrigger asChild>
+							<Button
+								type="button"
+								variant="outline"
+								className="flex h-10 w-full justify-between bg-transparent px-3 hover:bg-accent md:hidden"
+							>
+								<span className="truncate">{selectedLabel}</span>
+								<ChevronRight className="h-4 w-4 rotate-90 text-muted-foreground" />
+							</Button>
+						</DrawerTrigger>
+						<DrawerContent className="h-[88vh] overflow-hidden rounded-t-2xl border bg-popover text-popover-foreground">
+							<DrawerHandle className="mt-3 h-1.5 w-10" />
+							<DrawerTitle className="sr-only">{title} navigation</DrawerTitle>
+							<nav className="flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto p-4">
+								{renderNav(() => setDrawerOpen(false))}
+							</nav>
+						</DrawerContent>
+					</Drawer>
+				) : (
+					<div
+						className="overflow-x-auto border-b border-border pb-3 md:hidden"
+						onScroll={handleTabScroll}
+						style={{
+							maskImage: `linear-gradient(to right, ${tabScrollPos === "start" ? "black" : "transparent"}, black 24px, black calc(100% - 24px), ${tabScrollPos === "end" ? "black" : "transparent"})`,
+							WebkitMaskImage: `linear-gradient(to right, ${tabScrollPos === "start" ? "black" : "transparent"}, black 24px, black calc(100% - 24px), ${tabScrollPos === "end" ? "black" : "transparent"})`,
+						}}
+					>
+						<div className="flex gap-1">
+							{items.map((item) => (
+								<Link
+									key={item.value}
+									href={item.href}
+									replace
+									scroll={false}
+									prefetch
+									className={cn(
+										"inline-flex h-auto shrink-0 items-center gap-2 rounded-md px-3 py-1.5 text-xs font-medium transition-colors duration-150 focus:outline-none focus-visible:outline-none",
+										activeValue === item.value
+											? "bg-accent text-accent-foreground"
+											: "bg-transparent text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+									)}
+								>
+									{item.icon}
+									{item.label}
+								</Link>
+							))}
+						</div>
+					</div>
+				)}
+			</div>
+
+			<div className="min-w-0 flex-1">
+				<div className="hidden md:block">
+					<h2 className="text-lg font-semibold">{selectedLabel}</h2>
+					<Separator className="mt-4 bg-border" />
+				</div>
+				<div className={cn("min-w-0 pt-4", contentClassName)}>{children}</div>
+			</div>
+		</section>
+	);
+}
diff --git a/surfsense_web/components/layout/ui/index.ts b/surfsense_web/components/layout/ui/index.ts
index 52507ba37..338a4f352 100644
--- a/surfsense_web/components/layout/ui/index.ts
+++ b/surfsense_web/components/layout/ui/index.ts
@@ -1,6 +1,8 @@
 export { CreateWorkspaceDialog } from "./dialogs";
 export { Header } from "./header";
 export { IconRail, NavIcon, WorkspaceAvatar } from "./icon-rail";
+export type { RoutedSectionGroup, RoutedSectionItem } from "./RoutedSectionShell";
+export { RoutedSectionShell } from "./RoutedSectionShell";
 export { LayoutShell } from "./shell";
 export {
 	ChatListItem,

From d54e21e066893266d496f7fcf07ca08cfa3c5499 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 02:37:31 +0530
Subject: [PATCH 21/27] feat(runs-table): add alert component for API runs
 overview

- Introduced an Alert component to provide a concise description of API runs in the workspace.
- Replaced the previous header and description with the new alert for improved clarity and user experience.
---
 .../playground/components/runs-table.tsx         | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx
index 17508c0ff..6368a1f76 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx
@@ -1,8 +1,9 @@
 "use client";
 
 import { useInfiniteQuery } from "@tanstack/react-query";
-import { ChevronDown, ChevronRight, History } from "lucide-react";
+import { ChevronDown, ChevronRight, History, Info } from "lucide-react";
 import { Fragment, useState } from "react";
+import { Alert, AlertDescription } from "@/components/ui/alert";
 import { Button } from "@/components/ui/button";
 import {
 	Select,
@@ -67,13 +68,12 @@ export function RunsTable({ workspaceId }: { workspaceId: number }) {
 
 	return (
 		<div className="space-y-4">
-			<div>
-				<h1 className="text-xl font-semibold text-foreground md:text-2xl">Runs</h1>
-				<p className="mt-1 text-sm text-muted-foreground">
-					Every platform-native API run in this workspace — from the playground, API keys, and
-					agents. Newest first.
-				</p>
-			</div>
+			<Alert>
+				<Info />
+				<AlertDescription>
+					View all API runs for this workspace, including runs from the playground, API keys, and agents.
+				</AlertDescription>
+			</Alert>
 
 			<div className="flex flex-wrap items-center gap-2">
 				<Select value={capability} onValueChange={setCapability}>

From bcfa3c5ef5b6f0080e46be93cae16e6244c84131 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 02:51:23 +0530
Subject: [PATCH 22/27] refactor(user-settings): update terminology for
 auto-reload and credit features

- Replaced instances of "auto-reload" with "top-ups" for consistency and clarity across user settings and pricing sections.
- Enhanced user feedback messages related to credit balance and top-up settings.
- Improved comments and descriptions in the Purchase History and Credit Balance Display components for better understanding.
---
 .../components/PurchaseHistoryContent.tsx     |   5 +-
 .../ui/sidebar/CreditBalanceDisplay.tsx       |   4 +-
 .../components/pricing/pricing-section.tsx    |   4 +-
 .../settings/auto-reload-settings.tsx         | 281 ++++++++++--------
 4 files changed, 163 insertions(+), 131 deletions(-)

diff --git a/surfsense_web/app/dashboard/[workspace_id]/user-settings/components/PurchaseHistoryContent.tsx b/surfsense_web/app/dashboard/[workspace_id]/user-settings/components/PurchaseHistoryContent.tsx
index 263a286c1..0056b9374 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/user-settings/components/PurchaseHistoryContent.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/user-settings/components/PurchaseHistoryContent.tsx
@@ -108,9 +108,8 @@ function normalizeCreditPurchase(p: CreditPurchase): UnifiedPurchase {
 function formatGranted(p: UnifiedPurchase): string {
 	if (p.kind === "credits") {
 		const dollars = p.granted / 1_000_000;
-		// Credit packs are always whole dollars at the moment, but future
-		// fractional grants (refunds, partial top-ups, auto-reload) shouldn't
-		// silently round to "$0".
+		// Credit packs are always whole dollars today, but future fractional grants
+		// such as refunds or low-balance refills shouldn't silently round to "$0".
 		if (dollars >= 1) return `$${dollars.toFixed(2)} of credit`;
 		if (dollars > 0) return `$${dollars.toFixed(3)} of credit`;
 		return "$0 of credit";
diff --git a/surfsense_web/components/layout/ui/sidebar/CreditBalanceDisplay.tsx b/surfsense_web/components/layout/ui/sidebar/CreditBalanceDisplay.tsx
index 1d45137fb..81a939b21 100644
--- a/surfsense_web/components/layout/ui/sidebar/CreditBalanceDisplay.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/CreditBalanceDisplay.tsx
@@ -27,7 +27,7 @@ function formatUsd(micros: number): string {
  * premium-credit meters. Values come from Zero (live-replicated from Postgres)
  * as integer micro-USD (1_000_000 == $1.00). A low-balance warning highlights
  * the amount when it falls below $0.50 so the user knows to top up or enable
- * auto-reload.
+ * automatic top-ups.
  */
 export function CreditBalanceDisplay() {
 	const isAnonymous = useIsAnonymous();
@@ -46,7 +46,7 @@ export function CreditBalanceDisplay() {
 					"font-medium tabular-nums",
 					isLow ? "text-amber-600 dark:text-amber-500" : "text-foreground"
 				)}
-				title={isLow ? "Low balance — buy credits or enable auto-reload" : undefined}
+				title={isLow ? "Low balance: add credits or enable top-ups" : undefined}
 			>
 				{formatUsd(balanceMicros)}
 			</span>
diff --git a/surfsense_web/components/pricing/pricing-section.tsx b/surfsense_web/components/pricing/pricing-section.tsx
index cc7d81307..74c76ad36 100644
--- a/surfsense_web/components/pricing/pricing-section.tsx
+++ b/surfsense_web/components/pricing/pricing-section.tsx
@@ -41,7 +41,7 @@ const demoPlans = [
 			"Premium models like GPT-5.5, Claude Sonnet 5, Gemini 3.1 Pro billed at provider cost",
 			"Scheduled and event-triggered agents for briefs, alerts, and monitoring",
 			"Write results back to Notion, Slack, Linear, and Jira",
-			"Top up any amount, $1 buys $1 of credit, optional auto-reload",
+			"Add credit any time. $1 buys $1 of credit, with optional automatic refills",
 			"Priority support on Discord",
 		],
 		description: "",
@@ -95,7 +95,7 @@ const faqData: FAQSection[] = [
 			{
 				question: "How does Pay As You Go work?",
 				answer:
-					"There is no monthly subscription. Start with $5 of free credit, and when you need more, top up any amount. $1 buys exactly $1 of credit, added to your balance immediately. You can enable auto-reload to top up automatically when your balance runs low, and turn it off any time.",
+					"There is no monthly subscription. Start with $5 of free credit, and when you need more, add any amount. $1 buys exactly $1 of credit, added to your balance immediately. You can enable automatic refills when your balance runs low, and turn them off any time."
 			},
 			{
 				question: "What happens if I run out of credit?",
diff --git a/surfsense_web/components/settings/auto-reload-settings.tsx b/surfsense_web/components/settings/auto-reload-settings.tsx
index b11a64353..ede826dd0 100644
--- a/surfsense_web/components/settings/auto-reload-settings.tsx
+++ b/surfsense_web/components/settings/auto-reload-settings.tsx
@@ -2,15 +2,15 @@
 
 import { useQuery as useZeroQuery } from "@rocicorp/zero/react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { AlertTriangle, CreditCard, RefreshCw } from "lucide-react";
+import { AlertTriangle, Info } from "lucide-react";
 import { useParams, usePathname, useRouter, useSearchParams } from "next/navigation";
 import { useEffect, useRef, useState } from "react";
 import { toast } from "sonner";
 import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
 import { Button } from "@/components/ui/button";
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
+import { Separator } from "@/components/ui/separator";
 import { Spinner } from "@/components/ui/spinner";
 import { Switch } from "@/components/ui/switch";
 import { stripeApiService } from "@/lib/apis/stripe-api.service";
@@ -69,7 +69,7 @@ export function AutoReloadSettings() {
 		const setupResult = searchParams.get("auto_reload_setup");
 		if (!setupResult) return;
 		if (setupResult === "success") {
-			toast.success("Card saved. You can now enable auto-reload.");
+			toast.success("Card saved. You can now enable top-ups.");
 			queryClient.invalidateQueries({ queryKey: ["auto-reload-settings"] });
 		} else if (setupResult === "cancel") {
 			toast.info("Card setup canceled.");
@@ -92,19 +92,19 @@ export function AutoReloadSettings() {
 		mutationFn: stripeApiService.updateAutoReloadSettings,
 		onSuccess: (updated) => {
 			queryClient.setQueryData(["auto-reload-settings"], updated);
-			toast.success(updated.enabled ? "Auto-reload is on." : "Auto-reload settings saved.");
+			toast.success(updated.enabled ? "Top-ups are on." : "Top-up settings saved.");
 		},
 		onError: (error) => {
 			if (error instanceof AppError && error.message) {
 				toast.error(error.message);
 				return;
 			}
-			toast.error("Couldn't save auto-reload settings. Please try again.");
+			toast.error("Couldn't save top-up settings. Please try again.");
 		},
 	});
 
 	// Render nothing while loading (avoids a spinner flash on pages where the
-	// feature flag turns out to be off) and when auto-reload is disabled
+	// feature flag turns out to be off) and when top-ups are disabled
 	// server-side.
 	if (isLoading || !settings || !settings.feature_enabled) {
 		return null;
@@ -131,7 +131,7 @@ export function AutoReloadSettings() {
 			return;
 		}
 		if (amountMicros == null || amountMicros < settings.min_amount_micros) {
-			toast.error(`Reload amount must be at least $${minAmountDollars}.`);
+			toast.error(`Top-up amount must be at least $${minAmountDollars}.`);
 			return;
 		}
 
@@ -142,135 +142,168 @@ export function AutoReloadSettings() {
 		});
 	};
 
-	return (
-		<Card>
-			<CardHeader>
-				<CardTitle className="flex items-center gap-2 text-base">
-					<RefreshCw className="h-4 w-4 text-amber-500" />
-					Auto-reload
-				</CardTitle>
-				<CardDescription>
-					Automatically top up your credit balance when it drops below a threshold, using a saved
-					card. Current balance:{" "}
-					<span className="font-medium text-foreground">{formatUsd(balanceMicros)}</span>.
-				</CardDescription>
-			</CardHeader>
-			<CardContent className="space-y-5">
+	const addCardButton = (
+		<Button
+			className="w-full sm:w-auto"
+			onClick={() => setupMutation.mutate()}
+			disabled={setupMutation.isPending}
+		>
+			{setupMutation.isPending ? (
+				<>
+					<Spinner size="xs" />
+					Redirecting
+				</>
+			) : (
+				"Add a card"
+			)}
+		</Button>
+	);
+
+	if (!hasCard) {
+		return (
+			<div className="space-y-5">
 				{settings.failed_at && (
 					<Alert variant="destructive">
 						<AlertTriangle className="h-4 w-4" />
-						<AlertTitle>Last auto-reload failed</AlertTitle>
+						<AlertTitle>Last top-up failed</AlertTitle>
 						<AlertDescription>
-							Your saved card was declined and auto-reload was turned off. Update your card and
-							re-enable it below to keep topping up automatically.
+							Your saved card was declined and top-ups were turned off. Update your card and
+							re-enable top-ups below.
 						</AlertDescription>
 					</Alert>
 				)}
 
-				{!hasCard ? (
-					<div className="flex flex-col items-start gap-3 rounded-lg border bg-muted/20 p-4">
-						<div className="flex items-center gap-2 text-sm">
-							<CreditCard className="h-4 w-4 text-muted-foreground" />
-							<span>Add a card to enable automatic top-ups.</span>
+				<div className="space-y-6">
+					<Alert className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+						<div className="flex min-w-0 items-start gap-3">
+							<Info className="mt-0.5 h-4 w-4 shrink-0" />
+							<p className="text-sm leading-relaxed text-muted-foreground">
+								Automatically top up your credit balance when it drops below a threshold, using a
+								saved card. Current balance:{" "}
+								<span className="font-medium text-foreground">{formatUsd(balanceMicros)}</span>.
+							</p>
 						</div>
-						<Button onClick={() => setupMutation.mutate()} disabled={setupMutation.isPending}>
-							{setupMutation.isPending ? (
-								<>
-									<Spinner size="xs" />
-									Redirecting
-								</>
-							) : (
-								"Add a card"
-							)}
-						</Button>
+						{addCardButton}
+					</Alert>
+					<Separator />
+				</div>
+			</div>
+		);
+	}
+
+	return (
+		<div className="space-y-6">
+			{settings.failed_at && (
+				<Alert variant="destructive">
+					<AlertTriangle className="h-4 w-4" />
+					<AlertTitle>Last top-up failed</AlertTitle>
+					<AlertDescription>
+						Your saved card was declined and top-ups were turned off. Update your card and
+						re-enable top-ups below.
+					</AlertDescription>
+				</Alert>
+			)}
+
+			<section className="space-y-5">
+				<div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+					<div className="space-y-1">
+						<h2 className="text-base font-semibold tracking-tight">Automatic top-ups</h2>
+						<p className="text-sm text-muted-foreground">
+							Current balance:{" "}
+							<span className="font-medium text-foreground">{formatUsd(balanceMicros)}</span>
+						</p>
 					</div>
-				) : (
-					<>
-						<div className="flex items-center justify-between gap-4">
-							<div className="space-y-0.5">
-								<Label htmlFor="auto-reload-toggle" className="text-sm font-medium">
-									Enable auto-reload
-								</Label>
-								<p className="text-xs text-muted-foreground">
-									Charge your saved card when the balance gets low.
-								</p>
-							</div>
-							<Switch id="auto-reload-toggle" checked={enabled} onCheckedChange={setEnabled} />
-						</div>
+					<Button
+						className="w-full sm:w-auto"
+						onClick={() => setupMutation.mutate()}
+						disabled={setupMutation.isPending}
+					>
+						{setupMutation.isPending ? (
+							<>
+								<Spinner size="xs" />
+								Redirecting
+							</>
+						) : (
+							"Update card"
+						)}
+					</Button>
+				</div>
 
-						<div className="grid gap-4 sm:grid-cols-2">
-							<div className="space-y-1.5">
-								<Label htmlFor="auto-reload-threshold" className="text-xs">
-									When balance falls below
-								</Label>
-								<div className="relative">
-									<span className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-sm text-muted-foreground">
-										$
-									</span>
-									<Input
-										id="auto-reload-threshold"
-										type="number"
-										min="0"
-										step="1"
-										inputMode="decimal"
-										className="pl-6 tabular-nums"
-										value={thresholdInput}
-										onChange={(e) => setThresholdInput(e.target.value)}
-										disabled={!enabled}
-										placeholder="5"
-									/>
-								</div>
-							</div>
-							<div className="space-y-1.5">
-								<Label htmlFor="auto-reload-amount" className="text-xs">
-									Add this much credit
-								</Label>
-								<div className="relative">
-									<span className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-sm text-muted-foreground">
-										$
-									</span>
-									<Input
-										id="auto-reload-amount"
-										type="number"
-										min={minAmountDollars}
-										step="1"
-										inputMode="decimal"
-										className="pl-6 tabular-nums"
-										value={amountInput}
-										onChange={(e) => setAmountInput(e.target.value)}
-										disabled={!enabled}
-										placeholder="10"
-									/>
-								</div>
-								<p className="text-[11px] text-muted-foreground">Minimum ${minAmountDollars}.</p>
-							</div>
-						</div>
+				<div className="flex items-center justify-between gap-4">
+					<div className="space-y-0.5">
+						<Label htmlFor="top-ups-toggle" className="text-sm font-medium">
+							Enable top-ups
+						</Label>
+						<p className="text-xs text-muted-foreground">
+							Charge your saved card when the balance gets low.
+						</p>
+					</div>
+					<Switch id="top-ups-toggle" checked={enabled} onCheckedChange={setEnabled} />
+				</div>
 
-						<div className="flex items-center justify-between gap-3">
-							<Button
-								variant="ghost"
-								size="sm"
-								className="text-muted-foreground"
-								onClick={() => setupMutation.mutate()}
-								disabled={setupMutation.isPending}
-							>
-								<CreditCard className="h-3.5 w-3.5" />
-								Update card
-							</Button>
-							<Button onClick={handleSave} disabled={saveMutation.isPending}>
-								{saveMutation.isPending ? (
-									<>
-										<Spinner size="xs" />
-										Saving
-									</>
-								) : (
-									"Save"
-								)}
-							</Button>
+				<div className="grid gap-4 sm:grid-cols-2">
+					<div className="space-y-1.5">
+						<Label htmlFor="top-ups-threshold" className="text-xs">
+							When balance falls below
+						</Label>
+						<div className="relative">
+							<span className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-sm text-muted-foreground">
+								$
+							</span>
+							<Input
+								id="top-ups-threshold"
+								type="number"
+								min="0"
+								step="1"
+								inputMode="decimal"
+								className="pl-6 tabular-nums"
+								value={thresholdInput}
+								onChange={(e) => setThresholdInput(e.target.value)}
+								disabled={!enabled}
+								placeholder="5"
+							/>
 						</div>
-					</>
-				)}
-			</CardContent>
-		</Card>
+					</div>
+					<div className="space-y-1.5">
+						<Label htmlFor="top-ups-amount" className="text-xs">
+							Add this much credit
+						</Label>
+						<div className="relative">
+							<span className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-sm text-muted-foreground">
+								$
+							</span>
+							<Input
+								id="top-ups-amount"
+								type="number"
+								min={minAmountDollars}
+								step="1"
+								inputMode="decimal"
+								className="pl-6 tabular-nums"
+								value={amountInput}
+								onChange={(e) => setAmountInput(e.target.value)}
+								disabled={!enabled}
+								placeholder="10"
+							/>
+						</div>
+						<p className="text-[11px] text-muted-foreground">Minimum ${minAmountDollars}.</p>
+					</div>
+				</div>
+
+				<div className="flex justify-end">
+					<Button className="w-full sm:w-auto" onClick={handleSave} disabled={saveMutation.isPending}>
+						{saveMutation.isPending ? (
+							<>
+								<Spinner size="xs" />
+								Saving
+							</>
+						) : (
+							"Save"
+						)}
+					</Button>
+				</div>
+			</section>
+
+			<Separator />
+		</div>
 	);
 }

From 7268eae7fa45e553a7cb0ee663b65691776cc1cd Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 03:08:39 +0530
Subject: [PATCH 23/27] refactor(playground): update terminology and enhance UI
 components for API runs

- Changed label from "Runs" to "API Runs" in PlaygroundLayoutShell and PlaygroundIndex for clarity.
- Improved the API reference UI by adding a ChevronRight icon for expandable sections and enhancing the summary layout.
- Introduced an EndpointCopyButton component for easier copying of API endpoint details, improving user experience.
---
 .../playground/components/api-reference.tsx   |   7 +-
 .../components/playground-index.tsx           |   2 +-
 .../components/playground-runner.tsx          | 123 ++++++++++++------
 .../playground/layout-shell.tsx               |   2 +-
 4 files changed, 89 insertions(+), 45 deletions(-)

diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx
index 1bc4fe1d3..caf7cf9eb 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { Check, Copy } from "lucide-react";
+import { Check, ChevronRight, Copy } from "lucide-react";
 import { useMemo, useState } from "react";
 import { Button } from "@/components/ui/button";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
@@ -45,8 +45,9 @@ function SchemaBlock({ title, schema }: { title: string; schema: Record<string,
 	const json = useMemo(() => JSON.stringify(schema, null, 2), [schema]);
 	return (
 		<details className="group rounded-md border border-border/60">
-			<summary className="cursor-pointer select-none px-3 py-2 text-sm font-medium text-muted-foreground transition-colors hover:text-foreground">
-				{title}
+			<summary className="flex cursor-pointer list-none items-center justify-between gap-3 px-3 py-2 text-sm font-medium text-muted-foreground transition-colors hover:text-foreground [&::-webkit-details-marker]:hidden">
+				<span>{title}</span>
+				<ChevronRight className="h-4 w-4 shrink-0 transition-transform group-open:rotate-90" />
 			</summary>
 			<div className="relative border-t border-border/60">
 				<CopyButton text={json} />
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
index 17f0591c8..7e9d45373 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
@@ -45,7 +45,7 @@ export function PlaygroundIndex({ workspaceId }: { workspaceId: number }) {
 					<div className="flex items-center gap-3">
 						<History className="h-5 w-5 text-muted-foreground" />
 						<div>
-							<p className="text-sm font-medium">Runs</p>
+							<p className="text-sm font-medium">API Runs</p>
 							<p className="text-xs text-muted-foreground">See every API run in this workspace</p>
 						</div>
 					</div>
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
index effce913b..d80af42f6 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
@@ -1,14 +1,25 @@
 "use client";
 
-import { AlertTriangle, Coins, Hash, Loader2, Play, Timer, X } from "lucide-react";
-import Link from "next/link";
+import {
+	Check,
+	Coins,
+	Copy,
+	Hash,
+	Info,
+	Loader2,
+	Play,
+	Timer,
+	X,
+} from "lucide-react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { toast } from "sonner";
+import { Alert, AlertDescription } from "@/components/ui/alert";
 import { Button } from "@/components/ui/button";
 import { Spinner } from "@/components/ui/spinner";
 import { useRunStream } from "@/hooks/use-run-stream";
 import { useScraperCapabilities } from "@/hooks/use-scraper-capabilities";
 import { scrapersApiService } from "@/lib/apis/scrapers-api.service";
-import { AbortedError, AppError } from "@/lib/error";
+import { AppError } from "@/lib/error";
 import { findVerb } from "@/lib/playground/catalog";
 import { formatCost, formatDuration, formatPricing } from "@/lib/playground/format";
 import { buildPayload, initialFormValues, parseSchemaFields } from "@/lib/playground/json-schema";
@@ -58,36 +69,44 @@ function RunStat({
 	);
 }
 
-function ErrorPanel({ error, workspaceId }: { error: unknown; workspaceId: number }) {
-	if (error instanceof AbortedError) {
-		return null;
-	}
+function getRunErrorMessage(error: unknown): string {
 	const status = error instanceof AppError ? error.status : undefined;
 
 	if (status === 402) {
-		return (
-			<div className="rounded-md border border-destructive/40 bg-destructive/5 p-4 text-sm">
-				<p className="font-medium text-destructive">Insufficient credits</p>
-				<p className="mt-1 text-muted-foreground">You don't have enough credits to run this API.</p>
-				<Button asChild size="sm" variant="outline" className="mt-3">
-					<Link href={`/dashboard/${workspaceId}/buy-more`}>Buy credits</Link>
-				</Button>
-			</div>
-		);
+		return "Insufficient credits. Add credits to run this API.";
 	}
 
-	const message =
-		status === 422
-			? "Invalid input. Check the fields above and try again."
-			: error instanceof Error && error.message
-				? error.message
-				: "Something went wrong running this API.";
+	if (status === 422) {
+		return "Invalid input. Check the fields above and try again.";
+	}
+
+	return error instanceof Error && error.message
+		? error.message
+		: "Something went wrong running this API.";
+}
+
+function EndpointCopyButton({ endpoint }: { endpoint: string }) {
+	const [copied, setCopied] = useState(false);
+
+	const handleCopy = () => {
+		navigator.clipboard.writeText(endpoint).then(() => {
+			setCopied(true);
+			setTimeout(() => setCopied(false), 1500);
+		});
+	};
 
 	return (
-		<div className="flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/5 p-4 text-sm text-destructive">
-			<AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
-			<span>{message}</span>
-		</div>
+		<Button
+			type="button"
+			variant="ghost"
+			size="sm"
+			onClick={handleCopy}
+			className="h-auto justify-start gap-2 rounded bg-muted/40 px-2 py-1 font-mono text-xs text-muted-foreground hover:bg-muted hover:text-foreground"
+		>
+			<code>{endpoint}</code>
+			{copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
+			<span className="sr-only">{copied ? "Copied endpoint" : "Copy endpoint"}</span>
+		</Button>
 	);
 }
 
@@ -110,6 +129,8 @@ export function PlaygroundRunner({ workspaceId, platform, verb }: PlaygroundRunn
 	const [values, setValues] = useState<Record<string, unknown>>({});
 	const run = useRunStream(workspaceId);
 	const isRunning = run.status === "running";
+	const previousStatusRef = useRef(run.status);
+	const notifiedRunRef = useRef<string | null>(null);
 
 	// Seed form defaults once the schema is available.
 	useEffect(() => {
@@ -158,6 +179,29 @@ export function PlaygroundRunner({ workspaceId, platform, verb }: PlaygroundRunn
 		() => (run.detail ? parseJsonlOutput(run.detail.output_text) : null),
 		[run.detail]
 	);
+	const endpoint = `POST /workspaces/${workspaceId}/scrapers/${platform}/${verb}`;
+
+	useEffect(() => {
+		const previousStatus = previousStatusRef.current;
+		previousStatusRef.current = run.status;
+
+		if (previousStatus !== "running") return;
+
+		if (run.status === "success") {
+			const key = `${run.runId ?? "run"}:success`;
+			if (notifiedRunRef.current === key) return;
+			notifiedRunRef.current = key;
+			toast.success("API run completed.");
+			return;
+		}
+
+		if (run.status === "error") {
+			const key = `${run.runId ?? "run"}:error`;
+			if (notifiedRunRef.current === key) return;
+			notifiedRunRef.current = key;
+			toast.error(getRunErrorMessage(run.error));
+		}
+	}, [run.status, run.runId, run.error]);
 
 	if (isLoading) {
 		return (
@@ -186,26 +230,26 @@ export function PlaygroundRunner({ workspaceId, platform, verb }: PlaygroundRunn
 
 	return (
 		<div className="space-y-10">
-			<div className="grid gap-6 lg:grid-cols-2">
+			<div className="space-y-6">
+				{capability.description && (
+					<Alert>
+						<Info />
+						<AlertDescription>
+							<p>{capability.description}</p>
+						</AlertDescription>
+					</Alert>
+				)}
+
 				<div className="space-y-5">
-					<div>
-						<h1 className="text-xl font-semibold text-foreground md:text-2xl">
-							{catalogVerb.label} <span className="text-muted-foreground">· {platform}</span>
-						</h1>
-						{capability.description && (
-							<p className="mt-1 text-sm text-muted-foreground">{capability.description}</p>
-						)}
-						<code className="mt-2 inline-block rounded bg-muted/40 px-1.5 py-0.5 text-xs text-muted-foreground">
-							POST /workspaces/{workspaceId}/scrapers/{platform}/{verb}
-						</code>
-						<div className="mt-2 flex items-center gap-1.5 text-xs text-muted-foreground">
+					<div className="space-y-2">
+						<EndpointCopyButton endpoint={endpoint} />
+						<div className="flex items-center gap-1.5 text-xs text-muted-foreground">
 							<Coins className="h-3.5 w-3.5" />
 							<span className="font-medium tabular-nums text-foreground">
 								{formatPricing(capability.pricing)}
 							</span>
 						</div>
 					</div>
-
 					<SchemaForm
 						fields={fields}
 						values={values}
@@ -230,7 +274,6 @@ export function PlaygroundRunner({ workspaceId, platform, verb }: PlaygroundRunn
 						)}
 					</div>
 
-					{run.status === "error" && <ErrorPanel error={run.error} workspaceId={workspaceId} />}
 				</div>
 
 				<div className="space-y-3">
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
index e03667944..e17a9a584 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
@@ -30,7 +30,7 @@ export function PlaygroundLayoutShell({ workspaceId, children }: PlaygroundLayou
 			},
 			{
 				value: "runs",
-				label: "Runs",
+				label: "API Runs",
 				href: `${base}/runs`,
 				icon: <History className="h-4 w-4" />,
 			},

From 3b9c806c90304cbcc5bcc1b909c0660d23059ad4 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 03:35:32 +0530
Subject: [PATCH 24/27] feat(capabilities): add documentation URL to
 capabilities and enhance Reddit scrape capability

- Introduced a `docs_url` field to the `Capability` and `CapabilitySummary` classes for better documentation access.
- Updated the `REDDIT_SCRAPE` capability to include a specific documentation link.
- Enhanced the PlaygroundRunner component to display the documentation link when available, improving user guidance.
---
 .../app/capabilities/core/access/rest.py      |  2 +
 .../app/capabilities/core/types.py            |  1 +
 .../capabilities/reddit/scrape/definition.py  |  8 ++--
 .../playground/components/api-reference.tsx   | 10 ++--
 .../playground/components/output-viewer.tsx   | 48 +++++++------------
 .../components/playground-runner.tsx          | 39 ++++++++-------
 .../playground/layout-shell.tsx               |  2 +-
 surfsense_web/components/ui/tabs.tsx          |  2 +-
 .../contracts/types/scraper.types.ts          |  1 +
 9 files changed, 51 insertions(+), 62 deletions(-)

diff --git a/surfsense_backend/app/capabilities/core/access/rest.py b/surfsense_backend/app/capabilities/core/access/rest.py
index 328a7c5a1..2047b21ae 100644
--- a/surfsense_backend/app/capabilities/core/access/rest.py
+++ b/surfsense_backend/app/capabilities/core/access/rest.py
@@ -71,6 +71,7 @@ class CapabilitySummary(BaseModel):
 
     name: str
     description: str
+    docs_url: str | None = None
     input_schema: dict
     output_schema: dict
     # Empty list = free (billing disabled or an unmetered verb).
@@ -145,6 +146,7 @@ def _register_capabilities_list(
             CapabilitySummary(
                 name=capability.name,
                 description=capability.description,
+                docs_url=capability.docs_url,
                 input_schema=capability.input_schema.model_json_schema(),
                 output_schema=capability.output_schema.model_json_schema(),
             ),
diff --git a/surfsense_backend/app/capabilities/core/types.py b/surfsense_backend/app/capabilities/core/types.py
index ec44d29aa..c87601832 100644
--- a/surfsense_backend/app/capabilities/core/types.py
+++ b/surfsense_backend/app/capabilities/core/types.py
@@ -62,3 +62,4 @@ class Capability:
     output_schema: type[BaseModel]
     executor: Executor
     billing_unit: BillingUnit | None
+    docs_url: str | None = None
diff --git a/surfsense_backend/app/capabilities/reddit/scrape/definition.py b/surfsense_backend/app/capabilities/reddit/scrape/definition.py
index 01fb6db5f..fe00a77be 100644
--- a/surfsense_backend/app/capabilities/reddit/scrape/definition.py
+++ b/surfsense_backend/app/capabilities/reddit/scrape/definition.py
@@ -10,16 +10,14 @@ from app.capabilities.reddit.scrape.schemas import ScrapeInput, ScrapeOutput
 REDDIT_SCRAPE = Capability(
     name="reddit.scrape",
     description=(
-        "Scrape public Reddit data. Give it Reddit URLs (post, subreddit, or "
-        "user) and/or search terms, and it returns structured items — posts "
-        "(title, body, score, comment count, subreddit, author), their comments, "
-        "and community/user metadata. Use search_queries (optionally scoped to a "
-        "community) to discover posts, or urls to pull a known post/subreddit/user."
+        "Scrape public Reddit posts, comments, and metadata. Use urls or "
+        "search_queries."
     ),
     input_schema=ScrapeInput,
     output_schema=ScrapeOutput,
     executor=build_scrape_executor(),
     billing_unit=BillingUnit.REDDIT_ITEM,
+    docs_url="/docs/connectors/native/reddit",
 )
 
 register_capability(REDDIT_SCRAPE)
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx
index caf7cf9eb..beed5d525 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/api-reference.tsx
@@ -22,10 +22,10 @@ function CopyButton({ text }: { text: string }) {
 			variant="ghost"
 			size="sm"
 			onClick={copy}
-			className="absolute right-2 top-2 h-7 gap-1.5 px-2 text-xs"
+			aria-label={copied ? "Copied" : "Copy"}
+			className="absolute right-2 top-2 h-7 w-7 p-0"
 		>
 			{copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
-			{copied ? "Copied" : "Copy"}
 		</Button>
 	);
 }
@@ -91,11 +91,7 @@ export function ApiReference({
 			<div>
 				<h2 className="text-base font-semibold">API reference</h2>
 				<p className="mt-1 text-sm text-muted-foreground">
-					Call this API from your own project. Create a key in{" "}
-					<span className="font-medium text-foreground">User settings</span> and enable API access
-					for this workspace, then send it as a{" "}
-					<code className="rounded bg-muted/40 px-1 py-0.5 text-xs">Authorization: Bearer</code>{" "}
-					header.
+					Create an API key, enable API access for this workspace, then use the examples below to call this endpoint.
 				</p>
 			</div>
 
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/output-viewer.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/output-viewer.tsx
index 606548e14..e692734d3 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/output-viewer.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/output-viewer.tsx
@@ -3,6 +3,7 @@
 import { Check, Copy, Download } from "lucide-react";
 import { useMemo, useState } from "react";
 import { Button } from "@/components/ui/button";
+import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import {
 	Table,
 	TableBody,
@@ -12,7 +13,6 @@ import {
 	TableRow,
 } from "@/components/ui/table";
 import { downloadCsv, rowsToCsv } from "@/lib/playground/csv";
-import { cn } from "@/lib/utils";
 
 const MAX_TABLE_ROWS = 200;
 
@@ -109,34 +109,12 @@ export function OutputViewer({ data, filenameBase }: { data: unknown; filenameBa
 	return (
 		<div className="space-y-3">
 			<div className="flex items-center justify-between">
-				<div className="inline-flex rounded-md border border-border/60 p-0.5">
-					{items && (
-						<button
-							type="button"
-							onClick={() => setView("table")}
-							className={cn(
-								"rounded px-2.5 py-1 text-xs font-medium transition-colors",
-								view === "table"
-									? "bg-accent text-accent-foreground"
-									: "text-muted-foreground hover:text-foreground"
-							)}
-						>
-							Table
-						</button>
-					)}
-					<button
-						type="button"
-						onClick={() => setView("json")}
-						className={cn(
-							"rounded px-2.5 py-1 text-xs font-medium transition-colors",
-							view === "json"
-								? "bg-accent text-accent-foreground"
-								: "text-muted-foreground hover:text-foreground"
-						)}
-					>
-						JSON
-					</button>
-				</div>
+				<Tabs value={view} onValueChange={(value) => setView(value as "table" | "json")}>
+					<TabsList className="h-auto">
+						{items && <TabsTrigger value="table">Table</TabsTrigger>}
+						<TabsTrigger value="json">JSON</TabsTrigger>
+					</TabsList>
+				</Tabs>
 				<div className="flex items-center gap-1">
 					{items && items.length > 0 && (
 						<Button
@@ -150,9 +128,15 @@ export function OutputViewer({ data, filenameBase }: { data: unknown; filenameBa
 							Export CSV
 						</Button>
 					)}
-					<Button type="button" variant="ghost" size="sm" onClick={copy} className="gap-1.5">
+					<Button
+						type="button"
+						variant="ghost"
+						size="sm"
+						onClick={copy}
+						aria-label={copied ? "Copied JSON" : "Copy JSON"}
+						className="h-8 w-8 p-0"
+					>
 						{copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
-						{copied ? "Copied" : "Copy JSON"}
 					</Button>
 				</div>
 			</div>
@@ -168,7 +152,7 @@ export function OutputViewer({ data, filenameBase }: { data: unknown; filenameBa
 					<ResultTable items={items} />
 					{truncated && (
 						<p className="text-xs text-muted-foreground">
-							Showing first {MAX_TABLE_ROWS} of {items.length} items. Use Copy JSON for the full
+							Showing first {MAX_TABLE_ROWS} of {items.length} items. Switch to JSON for the full
 							output.
 						</p>
 					)}
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
index d80af42f6..030c7c933 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
@@ -2,15 +2,13 @@
 
 import {
 	Check,
-	Coins,
 	Copy,
 	Hash,
 	Info,
-	Loader2,
-	Play,
+	Coins,
 	Timer,
-	X,
 } from "lucide-react";
+import Link from "next/link";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { toast } from "sonner";
 import { Alert, AlertDescription } from "@/components/ui/alert";
@@ -235,7 +233,21 @@ export function PlaygroundRunner({ workspaceId, platform, verb }: PlaygroundRunn
 					<Alert>
 						<Info />
 						<AlertDescription>
-							<p>{capability.description}</p>
+							<p>
+								{capability.description}
+								{capability.docs_url ? (
+									<>
+										{" "}
+										<Link
+											href={capability.docs_url}
+											className="font-medium text-foreground underline-offset-4 hover:underline"
+										>
+											Read docs
+										</Link>
+										.
+									</>
+								) : null}
+							</p>
 						</AlertDescription>
 					</Alert>
 				)}
@@ -243,8 +255,8 @@ export function PlaygroundRunner({ workspaceId, platform, verb }: PlaygroundRunn
 				<div className="space-y-5">
 					<div className="space-y-2">
 						<EndpointCopyButton endpoint={endpoint} />
-						<div className="flex items-center gap-1.5 text-xs text-muted-foreground">
-							<Coins className="h-3.5 w-3.5" />
+						<div className="text-xs text-muted-foreground">
+							<span>Pricing: </span>
 							<span className="font-medium tabular-nums text-foreground">
 								{formatPricing(capability.pricing)}
 							</span>
@@ -258,17 +270,12 @@ export function PlaygroundRunner({ workspaceId, platform, verb }: PlaygroundRunn
 					/>
 
 					<div className="flex items-center gap-2">
-						<Button type="button" onClick={handleRun} disabled={isRunning} className="gap-1.5">
-							{isRunning ? (
-								<Loader2 className="h-4 w-4 animate-spin" />
-							) : (
-								<Play className="h-4 w-4" />
-							)}
-							Run
+						<Button type="button" onClick={handleRun} disabled={isRunning} className="relative">
+							<span className={isRunning ? "opacity-0" : ""}>Run</span>
+							{isRunning && <Spinner size="sm" className="absolute" />}
 						</Button>
 						{isRunning && (
-							<Button type="button" variant="outline" onClick={run.cancel} className="gap-1.5">
-								<X className="h-4 w-4" />
+							<Button type="button" variant="secondary" onClick={run.cancel}>
 								Cancel
 							</Button>
 						)}
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
index e17a9a584..59b8ad50b 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/layout-shell.tsx
@@ -90,6 +90,6 @@ function getSelectedLabel(
 	const group = groups.find((item) => item.items.some((child) => child.value === activeValue));
 	const child = group?.items.find((item) => item.value === activeValue);
 
-	if (group && child) return `${group.label} / ${child.label}`;
+	if (group && child) return `${group.label}: ${child.label}`;
 	return "API Playground";
 }
diff --git a/surfsense_web/components/ui/tabs.tsx b/surfsense_web/components/ui/tabs.tsx
index 5dbfc4bc5..693e246f4 100644
--- a/surfsense_web/components/ui/tabs.tsx
+++ b/surfsense_web/components/ui/tabs.tsx
@@ -29,7 +29,7 @@ const TabsTrigger = React.forwardRef<
 	<TabsPrimitive.Trigger
 		ref={ref}
 		className={cn(
-			"inline-flex items-center justify-center whitespace-nowrap rounded-sm px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm",
+			"inline-flex items-center justify-center whitespace-nowrap rounded-sm px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-popover data-[state=active]:text-popover-foreground data-[state=active]:shadow-sm",
 			className
 		)}
 		{...props}
diff --git a/surfsense_web/contracts/types/scraper.types.ts b/surfsense_web/contracts/types/scraper.types.ts
index d31e9d4fb..63c043fa7 100644
--- a/surfsense_web/contracts/types/scraper.types.ts
+++ b/surfsense_web/contracts/types/scraper.types.ts
@@ -15,6 +15,7 @@ export const scraperPricingMeter = z.object({
 export const scraperCapability = z.object({
 	name: z.string(),
 	description: z.string(),
+	docs_url: z.string().nullable().optional(),
 	input_schema: z.record(z.string(), z.unknown()),
 	// Optional so a backend that predates output schemas degrades to just not
 	// showing the output-schema block instead of failing the whole fetch.

From 7ba77c6b86634c399577fccc1af65cdf28423127 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 03:38:08 +0530
Subject: [PATCH 25/27] feat(capabilities): add documentation URLs to Google
 Maps, YouTube, and web crawl capabilities

- Introduced a `docs_url` field to the Google Maps reviews, scrape, YouTube comments, YouTube scrape, and web crawl capabilities for improved documentation access.
- Simplified descriptions for each capability to enhance clarity and user understanding.
---
 .../google_maps/reviews/definition.py         |  7 +++----
 .../google_maps/scrape/definition.py          |  9 +++-----
 .../google_search/scrape/definition.py        |  8 +++----
 .../app/capabilities/web/crawl/definition.py  | 21 +++----------------
 .../youtube/comments/definition.py            |  7 +++----
 .../capabilities/youtube/scrape/definition.py |  8 +++----
 .../components/playground-runner.tsx          |  2 +-
 7 files changed, 19 insertions(+), 43 deletions(-)

diff --git a/surfsense_backend/app/capabilities/google_maps/reviews/definition.py b/surfsense_backend/app/capabilities/google_maps/reviews/definition.py
index e96c6f906..5366194d5 100644
--- a/surfsense_backend/app/capabilities/google_maps/reviews/definition.py
+++ b/surfsense_backend/app/capabilities/google_maps/reviews/definition.py
@@ -10,15 +10,14 @@ from app.capabilities.google_maps.reviews.schemas import ReviewsInput, ReviewsOu
 GOOGLE_MAPS_REVIEWS = Capability(
     name="google_maps.reviews",
     description=(
-        "Fetch public reviews for one or more Google Maps places. Give it place "
-        "URLs or place IDs; returns structured review items with author, text, "
-        "star rating, like count, owner response, and timestamps. Use it to "
-        "gauge sentiment or pull recent feedback on specific places."
+        "Fetch public Google Maps reviews with authors, ratings, text, and "
+        "owner responses. Use urls or place IDs."
     ),
     input_schema=ReviewsInput,
     output_schema=ReviewsOutput,
     executor=build_reviews_executor(),
     billing_unit=BillingUnit.GOOGLE_MAPS_REVIEW,
+    docs_url="/docs/connectors/native/google-maps",
 )
 
 register_capability(GOOGLE_MAPS_REVIEWS)
diff --git a/surfsense_backend/app/capabilities/google_maps/scrape/definition.py b/surfsense_backend/app/capabilities/google_maps/scrape/definition.py
index 035b7e00d..db117a2ac 100644
--- a/surfsense_backend/app/capabilities/google_maps/scrape/definition.py
+++ b/surfsense_backend/app/capabilities/google_maps/scrape/definition.py
@@ -11,17 +11,14 @@ from app.capabilities.google_maps.scrape.schemas import ScrapeInput, ScrapeOutpu
 GOOGLE_MAPS_SCRAPE = Capability(
     name="google_maps.scrape",
     description=(
-        "Scrape public Google Maps places. Give it search queries (optionally "
-        "scoped by location), Google Maps URLs, or place IDs, and it returns "
-        "structured place items — name, address, category, phone, website, "
-        "rating, review count, coordinates, and opening hours. Set "
-        "include_details for richer detail-page fields, or max_reviews/"
-        "max_images to attach reviews and photos per place."
+        "Scrape public Google Maps places, details, reviews, and photos. Use "
+        "search_queries, urls, or place IDs."
     ),
     input_schema=ScrapeInput,
     output_schema=ScrapeOutput,
     executor=build_scrape_executor(),
     billing_unit=BillingUnit.GOOGLE_MAPS_PLACE,
+    docs_url="/docs/connectors/native/google-maps",
 )
 
 register_capability(GOOGLE_MAPS_SCRAPE)
diff --git a/surfsense_backend/app/capabilities/google_search/scrape/definition.py b/surfsense_backend/app/capabilities/google_search/scrape/definition.py
index 2f2c9de03..2f62847d1 100644
--- a/surfsense_backend/app/capabilities/google_search/scrape/definition.py
+++ b/surfsense_backend/app/capabilities/google_search/scrape/definition.py
@@ -10,16 +10,14 @@ from app.capabilities.google_search.scrape.schemas import ScrapeInput, ScrapeOut
 GOOGLE_SEARCH_SCRAPE = Capability(
     name="google_search.scrape",
     description=(
-        "Search Google and return structured results. Give it search terms "
-        "(optionally scoped by country/language or to a single site) or full "
-        "Google Search URLs, and it returns SERP items — organic results "
-        "(title, url, description), related queries, people-also-ask, and any "
-        "AI overview. Use max_pages_per_query to page deeper."
+        "Search Google and return structured SERP results. Use search_queries "
+        "or Google Search URLs."
     ),
     input_schema=ScrapeInput,
     output_schema=ScrapeOutput,
     executor=build_scrape_executor(),
     billing_unit=BillingUnit.GOOGLE_SEARCH_SERP,
+    docs_url="/docs/connectors/native/google-search",
 )
 
 register_capability(GOOGLE_SEARCH_SCRAPE)
diff --git a/surfsense_backend/app/capabilities/web/crawl/definition.py b/surfsense_backend/app/capabilities/web/crawl/definition.py
index cd3db2306..362f4bcd0 100644
--- a/surfsense_backend/app/capabilities/web/crawl/definition.py
+++ b/surfsense_backend/app/capabilities/web/crawl/definition.py
@@ -9,29 +9,14 @@ from app.capabilities.web.crawl.schemas import CrawlInput, CrawlOutput
 WEB_CRAWL = Capability(
     name="web.crawl",
     description=(
-        "Scrape a single web page or crawl a whole website. Give it one or more "
-        "startUrls. Set maxCrawlDepth=0 to fetch just those URLs, or higher to "
-        "also follow the links on each page (depth 1 = the start pages plus the "
-        "pages they link to, and so on) — staying on the same site and stopping "
-        "at maxCrawlPages. On a deeper crawl, narrow which links are followed with "
-        "includeUrlPatterns / excludeUrlPatterns (regexes). Returns one item per "
-        "fetched page with clean markdown content, metadata (title, description), "
-        "crawl provenance, every link with its anchor text and kind "
-        "(internal/external/social/email/tel — use the text/context to tie a "
-        "profile URL to a person or company), and contact signals (emails, phone "
-        "numbers, social profiles). The site-wide contacts summary deduplicates "
-        "them with provenance: siteWide=true marks footer/header values (the "
-        "company's own contacts) vs page-local finds (e.g. team members' "
-        "profiles). Useful for lead generation and competitive intelligence; "
-        "contact details often live on about/contact/privacy pages, so crawl "
-        "with maxCrawlDepth >= 1 to surface them. JS-rendered pages are loaded "
-        "in a real browser and auto-scrolled, so lazy-loaded listings "
-        "(directories, infinite-scroll feeds) are captured too."
+        "Scrape pages or crawl websites for clean markdown, links, metadata, "
+        "and contact signals. Use startUrls and crawl-depth controls."
     ),
     input_schema=CrawlInput,
     output_schema=CrawlOutput,
     executor=build_crawl_executor(),
     billing_unit=BillingUnit.WEB_CRAWL,
+    docs_url="/docs/connectors/native/web-crawl",
 )
 
 register_capability(WEB_CRAWL)
diff --git a/surfsense_backend/app/capabilities/youtube/comments/definition.py b/surfsense_backend/app/capabilities/youtube/comments/definition.py
index ec689a23c..c22145547 100644
--- a/surfsense_backend/app/capabilities/youtube/comments/definition.py
+++ b/surfsense_backend/app/capabilities/youtube/comments/definition.py
@@ -10,15 +10,14 @@ from app.capabilities.youtube.comments.schemas import CommentsInput, CommentsOut
 YOUTUBE_COMMENTS = Capability(
     name="youtube.comments",
     description=(
-        "Fetch public comments (and their replies) for one or more YouTube "
-        "videos. Give it the video URLs; returns structured comment items with "
-        "author, text, like count, reply relationships, and timestamps. Use it "
-        "to gauge sentiment or pull discussion on specific videos."
+        "Fetch public YouTube comments and replies with authors, text, likes, "
+        "and timestamps. Use video URLs."
     ),
     input_schema=CommentsInput,
     output_schema=CommentsOutput,
     executor=build_comments_executor(),
     billing_unit=BillingUnit.YOUTUBE_COMMENT,
+    docs_url="/docs/connectors/native/youtube",
 )
 
 register_capability(YOUTUBE_COMMENTS)
diff --git a/surfsense_backend/app/capabilities/youtube/scrape/definition.py b/surfsense_backend/app/capabilities/youtube/scrape/definition.py
index 43874e254..d281ea7d6 100644
--- a/surfsense_backend/app/capabilities/youtube/scrape/definition.py
+++ b/surfsense_backend/app/capabilities/youtube/scrape/definition.py
@@ -10,16 +10,14 @@ from app.capabilities.youtube.scrape.schemas import ScrapeInput, ScrapeOutput
 YOUTUBE_SCRAPE = Capability(
     name="youtube.scrape",
     description=(
-        "Scrape public YouTube data. Give it YouTube URLs (video, channel, "
-        "playlist, shorts, or hashtag) and/or search queries, and it returns "
-        "structured video items — title, views, likes, publish date, channel "
-        "info, description, and optionally subtitles. Use search_queries to "
-        "discover videos, or urls to pull a known video/channel/playlist."
+        "Scrape public YouTube videos, channels, playlists, and subtitles. Use "
+        "urls or search_queries."
     ),
     input_schema=ScrapeInput,
     output_schema=ScrapeOutput,
     executor=build_scrape_executor(),
     billing_unit=BillingUnit.YOUTUBE_VIDEO,
+    docs_url="/docs/connectors/native/youtube",
 )
 
 register_capability(YOUTUBE_SCRAPE)
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
index 030c7c933..f62ffc312 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-runner.tsx
@@ -244,7 +244,7 @@ export function PlaygroundRunner({ workspaceId, platform, verb }: PlaygroundRunn
 										>
 											Read docs
 										</Link>
-										.
+										{" "}for more info.
 									</>
 								) : null}
 							</p>

From 248e62247895067503dbcb0b6c569ede1c346720 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 03:53:41 +0530
Subject: [PATCH 26/27] feat(playground): enhance schema form and artifacts
 library UI

- Replaced required/optional text with Badge component in schema form for better visual distinction.
- Updated EmptyState in artifacts library to include a more informative and visually appealing layout with an icon and description.
---
 .../playground/components/schema-form.tsx           |  8 +++++++-
 .../artifacts-library/ui/artifacts-library.tsx      | 13 ++++++++++---
 surfsense_web/public/connectors/web.svg             |  9 ++++++++-
 3 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/schema-form.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/schema-form.tsx
index 0b3b641ed..36aee26bb 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/schema-form.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/schema-form.tsx
@@ -2,6 +2,7 @@
 
 import { ChevronDown } from "lucide-react";
 import { useMemo, useState } from "react";
+import { Badge } from "@/components/ui/badge";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import {
@@ -133,7 +134,12 @@ function FieldRow({
 				<Label htmlFor={`field-${field.name}`} className="text-sm font-medium">
 					{field.title}
 				</Label>
-				{field.required && <span className="text-xs text-destructive">required</span>}
+				<Badge
+					variant={field.required ? "destructive" : "secondary"}
+					className="px-1.5 py-0 text-[10px]"
+				>
+					{field.required ? "required" : "optional"}
+				</Badge>
 			</div>
 			{field.description && (
 				<p className="text-xs text-muted-foreground">{field.description}</p>
diff --git a/surfsense_web/features/artifacts-library/ui/artifacts-library.tsx b/surfsense_web/features/artifacts-library/ui/artifacts-library.tsx
index 53010fba2..642fed1c1 100644
--- a/surfsense_web/features/artifacts-library/ui/artifacts-library.tsx
+++ b/surfsense_web/features/artifacts-library/ui/artifacts-library.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useSetAtom } from "jotai";
-import { RefreshCw, TriangleAlert } from "lucide-react";
+import { Boxes, RefreshCw, TriangleAlert } from "lucide-react";
 import { useMemo, useState } from "react";
 import { openReportPanelAtom } from "@/atoms/chat/report-panel.atom";
 import { MobileReportPanel } from "@/components/report-panel/report-panel";
@@ -46,8 +46,15 @@ function ErrorState({ onRetry }: { onRetry: () => void }) {
 
 function EmptyState() {
 	return (
-		<div className="flex items-center justify-center py-20 text-center">
-			<p className="font-medium text-foreground">No artifacts yet</p>
+		<div className="rounded-lg border border-dashed border-border/60 bg-muted/20 px-6 py-12 text-center">
+			<div className="mx-auto flex h-12 w-12 items-center justify-center rounded-full bg-muted text-muted-foreground">
+				<Boxes className="h-6 w-6" aria-hidden />
+			</div>
+			<h3 className="mt-4 text-base font-semibold text-foreground">No artifacts yet</h3>
+			<p className="mt-1 text-sm text-muted-foreground max-w-md mx-auto">
+				Artifacts collect the reports, resumes, podcasts, presentations, and images SurfSense
+				creates for this workspace. Generated deliverables from your chats will appear here.
+			</p>
 		</div>
 	);
 }
diff --git a/surfsense_web/public/connectors/web.svg b/surfsense_web/public/connectors/web.svg
index 15a38b8c1..699027f7c 100644
--- a/surfsense_web/public/connectors/web.svg
+++ b/surfsense_web/public/connectors/web.svg
@@ -1 +1,8 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#1a73e8" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9.25"/><path d="M2.75 12h18.5"/><ellipse cx="12" cy="12" rx="4.1" ry="9.25"/><path d="M5 6.4h14M5 17.6h14"/></svg>
\ No newline at end of file
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">
+	<g fill="none" stroke-width="3">
+		<path fill="#8fbffa" d="M3 24a21 21 0 1 0 42 0a21 21 0 1 0-42 0" />
+		<path stroke="#2859c5" stroke-linejoin="round" d="M3 24a21 21 0 1 0 42 0a21 21 0 1 0-42 0" />
+		<path stroke="#2859c5" stroke-linejoin="round" d="M15 24a9 21 0 1 1 18 0a9 21 0 1 1-18 0" />
+		<path stroke="#2859c5" stroke-linecap="round" stroke-linejoin="round" d="M4.5 31h39m-39-14h39" />
+	</g>
+</svg>

From 3eb963b8b31abce8ecca66af7760da5fd7c8c340 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 8 Jul 2026 04:09:47 +0530
Subject: [PATCH 27/27] fix(placeholder): update placeholder text for clarity
 in assistant UI and hero chat demo

- Revised placeholder text to improve readability and user understanding by replacing the dash with a period and adding "Use" for prompts and docs.
---
 surfsense_web/components/assistant-ui/thread.tsx     | 2 +-
 surfsense_web/components/homepage/hero-chat-demo.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/thread.tsx b/surfsense_web/components/assistant-ui/thread.tsx
index 1e8c66e8a..0cf6ef296 100644
--- a/surfsense_web/components/assistant-ui/thread.tsx
+++ b/surfsense_web/components/assistant-ui/thread.tsx
@@ -119,7 +119,7 @@ import {
 } from "../new-chat/document-mention-picker";
 
 const COMPOSER_PLACEHOLDER =
-	"Track competitors, scrape platforms, automate briefs — / for prompts, @ for docs";
+	"Track competitors, scrape platforms, automate briefs. Use / for prompts, @ for docs";
 
 type ComposerSuggestionAnchorPoint = {
 	left: number;
diff --git a/surfsense_web/components/homepage/hero-chat-demo.tsx b/surfsense_web/components/homepage/hero-chat-demo.tsx
index ef4b7cfc1..e617cd51e 100644
--- a/surfsense_web/components/homepage/hero-chat-demo.tsx
+++ b/surfsense_web/components/homepage/hero-chat-demo.tsx
@@ -27,7 +27,7 @@ export type HeroChatDemoScript = {
 
 type Stage = "typing" | "steps" | "answer" | "done";
 
-const PLACEHOLDER = "Track competitors, scrape platforms, automate briefs — / for prompts, @ for docs";
+const PLACEHOLDER = "Track competitors, scrape platforms, automate briefs. Use / for prompts, @ for docs";
 
 /** Blinking caret for the typewriter (overlay only, never inside the real input). */
 function Caret() {