feat: signals UI enhancement

.gitignore

@@ -5,3 +5,4 @@
 .idea
 target/
 .claude/
+.agent-browser/

CLAUDE.md

@@ -99,7 +99,7 @@ App Server                               │
          ├──► PostgreSQL (5433) - main database [required]
          ├──► ClickHouse (8123) - analytics/spans [required]
          ├──► RabbitMQ (5672) - async processing [optional, has in-memory fallback]
-         ├──► Query Engine (8903) - SQL processing [required]
+#        ├──► Query Engine (8903) - SQL processing [required]
          └──► Quickwit (7280/7281) - full-text search [optional]
 ```
 
@@ -127,3 +127,23 @@ The frontend uses Husky with lint-staged. Before commits:
 - Prettier formats staged files
 - ESLint fixes issues
 - TypeScript type-check runs
+
+## Frontend Best Practices
+
+### One component per file
+
+Related components should be in a folder named by the parent component (`my-list/`) and the parent component should follow the index.tsx pattern (`my-list/index.tsx`) and all related components should be in the folder (`my-list/my-list-item.tsx`).
+
+Please do your best to keep components <150 lines.
+
+### Bias towards complex logic and state in the Zustand store
+
+When you anticipate lots of complex state management with useState and useEffects, this would be a good time to rethink or refactor and move state into a shared store and expose derived state via selectors.
+
+### Avoid syncing URL params with Zustand store antipattern
+
+Use the nuqs library to handle url param state when possible. Avoid using a useEffect to sync URL param state with the Zustand store. Prefer keeping source of truth as the useQueryState and passing in necessary state as function params to the store when needed.
+
+### Use Zustand shallow to avoid unnecessary rerenders
+
+Pass shallow as the equality function to useStore when applicable. That way even with a new selector reference each render, Zustand compares the result shallowly and won't re-render if the contents are the same.

frontend/app/api/projects/[projectId]/signals/[id]/events/clusters/route.ts

@@ -15,7 +15,11 @@ export async function GET(
       signalId,
     });
 
-    return NextResponse.json(result);
+    return NextResponse.json({
+      items: result.items,
+      totalEventCount: result.totalEventCount,
+      clusteredEventCount: result.clusteredEventCount,
+    });
   } catch (error) {
     if (error instanceof ZodError) {
       return NextResponse.json({ success: false, error: prettifyError(error) }, { status: 400 });

frontend/app/api/projects/[projectId]/signals/[id]/events/stats/route.ts → frontend/app/api/projects/[projectId]/signals/[id]/events/clusters/stats/route.ts

@@ -1,34 +1,33 @@
 import { type NextRequest } from "next/server";
 import { prettifyError, ZodError } from "zod/v4";
 
+import { getClusterEventCounts, GetClusterEventCountsSchema } from "@/lib/actions/clusters";
 import { parseUrlParams } from "@/lib/actions/common/utils";
-import { getEventStats, GetEventStatsSchema } from "@/lib/actions/events/stats";
 
 export async function GET(
   req: NextRequest,
   props: { params: Promise<{ projectId: string; id: string }> }
 ): Promise<Response> {
-  const params = await props.params;
-  const { projectId, id: signalId } = params;
+  const { projectId, id: signalId } = await props.params;
 
   const parseResult = parseUrlParams(
     req.nextUrl.searchParams,
-    GetEventStatsSchema.omit({ projectId: true, signalId: true })
+    GetClusterEventCountsSchema.omit({ projectId: true, signalId: true })
   );
 
   if (!parseResult.success) {
     return Response.json({ error: prettifyError(parseResult.error) }, { status: 400 });
   }
 
   try {
-    const result = await getEventStats({ ...parseResult.data, projectId, signalId });
+    const result = await getClusterEventCounts({ ...parseResult.data, projectId, signalId });
     return Response.json(result);
   } catch (error) {
     if (error instanceof ZodError) {
       return Response.json({ error: prettifyError(error) }, { status: 400 });
     }
     return Response.json(
-      { error: error instanceof Error ? error.message : "Failed to fetch event stats." },
+      { error: error instanceof Error ? error.message : "Failed to fetch cluster event counts." },
       { status: 500 }
     );
   }

frontend/app/api/projects/[projectId]/signals/[id]/events/route.ts

@@ -12,7 +12,8 @@ export async function GET(
   const { projectId, id: signalId } = params;
   const parseResult = parseUrlParams(
     req.nextUrl.searchParams,
-    GetEventsPaginatedSchema.omit({ projectId: true, signalId: true })
+    GetEventsPaginatedSchema.omit({ projectId: true, signalId: true }),
+    ["filter", "searchIn", "clusterId"]
   );
 
   if (!parseResult.success) {

frontend/app/api/projects/[projectId]/sql/export-job/route.ts

@@ -1,7 +1,7 @@
 import { type NextRequest, NextResponse } from "next/server";
 import { prettifyError, ZodError } from "zod/v4";
 
-import { createExportJob } from "@/lib/actions/sql";
+import { createExportJob } from "@/lib/actions/sql/export-job";
 
 export async function POST(req: NextRequest, props: { params: Promise<{ projectId: string }> }): Promise<NextResponse> {
   const params = await props.params;

frontend/app/api/projects/[projectId]/sql/generate/route.ts

@@ -1,7 +1,7 @@
 import { type NextRequest } from "next/server";
 import { prettifyError, z, ZodError } from "zod/v4";
 
-import { generateSql } from "@/lib/actions/sql";
+import { generateSql } from "@/lib/actions/sql/generate";
 
 const GenerateSchema = z.object({
   prompt: z.string().min(1, "Prompt is required"),

frontend/app/layout.tsx

@@ -2,6 +2,7 @@ import "@/app/globals.css";
 import "@/app/scroll.css";
 
 import { type Metadata } from "next";
+import { NuqsAdapter } from "nuqs/adapters/next/app";
 import { type PropsWithChildren } from "react";
 
 import { Toaster } from "@/components/ui/toaster";
@@ -78,12 +79,14 @@ export default async function RootLayout({ children }: PropsWithChildren) {
       <FeatureFlagsProvider flags={featureFlags}>
         <PostHogProvider telemetryEnabled={featureFlags[Feature.POSTHOG]}>
           <body className="flex flex-col h-full">
-            <div className="flex">
-              <div className="flex flex-col grow max-w-full min-h-screen">
-                <main className="z-10 flex flex-col grow">{children}</main>
-                <Toaster />
+            <NuqsAdapter>
+              <div className="flex">
+                <div className="flex flex-col grow max-w-full min-h-screen">
+                  <main className="z-10 flex flex-col grow">{children}</main>
+                  <Toaster />
+                </div>
               </div>
-            </div>
+            </NuqsAdapter>
           </body>
         </PostHogProvider>
       </FeatureFlagsProvider>

frontend/components/chart-builder/charts/utils.ts

@@ -1,4 +1,4 @@
-import { scaleTime, scaleUtc } from "d3-scale";
+import { scaleUtc } from "d3-scale";
 import { format, isValid, parseISO } from "date-fns";
 import { isNil } from "lodash";
 
@@ -106,7 +106,7 @@ export const selectNiceTicksFromData = (
 
   const scale = scaleUtc().domain([startDate, endDate]);
   const idealTicks = scale.ticks(targetTickCount);
-  const formatTick = scaleTime().domain([startDate, endDate]).tickFormat();
+  const formatTick = scale.tickFormat();
 
   const findClosestTimestamp = (targetTime: number) =>
     dataTimestamps.reduce((closest, current) => {

frontend/components/charts/time-series-chart/index.tsx

@@ -7,6 +7,7 @@ import { type CategoricalChartFunc } from "recharts/types/chart/generateCategori
 
 import { numberFormatter, parseUtcTimestamp, selectNiceTicksFromData } from "@/components/chart-builder/charts/utils";
 import { ChartContainer, ChartTooltip, ChartTooltipContent } from "@/components/ui/chart";
+import { cn } from "@/lib/utils";
 
 import RoundedBar from "./bar";
 import { type TimeSeriesChartProps, type TimeSeriesDataPoint } from "./types";
@@ -32,7 +33,8 @@ export default function TimeSeriesChart<T extends TimeSeriesDataPoint>({
   onZoom,
   formatValue = numberFormatter.format,
   showTotal = true,
-}: Omit<TimeSeriesChartProps<T>, "isLoading" | "className">) {
+  className,
+}: Omit<TimeSeriesChartProps<T>, "isLoading">) {
   const router = useRouter();
   const pathName = usePathname();
   const searchParams = useSearchParams();
@@ -104,8 +106,8 @@ export default function TimeSeriesChart<T extends TimeSeriesDataPoint>({
   );
 
   return (
-    <div className="flex flex-col items-start">
-      <ChartContainer config={chartConfig} className="h-48 w-full">
+    <div className="flex flex-col items-start h-full">
+      <ChartContainer config={chartConfig} className={cn("h-48 w-full", className)}>
         <BarChart
           data={data}
           margin={{ left: -8, top: 8 }}

frontend/components/client-timestamp-formatter.tsx

@@ -6,7 +6,7 @@ import { differenceInDays, differenceInHours, differenceInMinutes, differenceInS
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
 import { cn, formatTimestamp } from "@/lib/utils.ts";
 
-function formatShortRelativeTime(date: Date): string {
+export function formatShortRelativeTime(date: Date): string {
   const now = new Date();
   const seconds = differenceInSeconds(now, date);
   const minutes = differenceInMinutes(now, date);

frontend/components/common/advanced-search/store.tsx

@@ -7,7 +7,7 @@ import { createContext, type PropsWithChildren, type RefObject, useContext, useM
 import { createStore, type StoreApi, useStore } from "zustand";
 
 import { dataTypeOperationsMap } from "@/components/ui/infinite-datatable/ui/datatable-filter/utils";
-import { type Filter, FilterSchema } from "@/lib/actions/common/filters";
+import { type Filter, type FilterDataType, FilterSchema } from "@/lib/actions/common/filters";
 import { Operator } from "@/lib/actions/common/operators";
 
 import {
@@ -23,6 +23,11 @@ import {
 } from "./types";
 import { getNextField, getPreviousField } from "./utils";
 
+/** Map UI column dataType (which includes "enum") to the Filter schema's FilterDataType */
+function toFilterDataType(uiDataType: ColumnFilter["dataType"]): FilterDataType {
+  return uiDataType === "enum" ? "string" : uiDataType;
+}
+
 interface AdvancedSearchStore {
   // State
   autocompleteData: AutocompleteCache;
@@ -154,6 +159,7 @@ const createAdvancedSearchStore = (
       const newTag: FilterTag = {
         id: `tag-${uniqueId()}`,
         field,
+        dataType: toFilterDataType(columnFilter.dataType),
         operator: defaultOperator,
         value: defaultValue,
       };
@@ -183,6 +189,7 @@ const createAdvancedSearchStore = (
       const newTag: FilterTag = {
         id: `tag-${uniqueId()}`,
         field,
+        dataType: toFilterDataType(columnFilter.dataType),
         operator,
         value: tagValue,
       };
@@ -242,8 +249,11 @@ const createAdvancedSearchStore = (
     },
 
     updateTagField: (tagId, field) => {
+      const { filters } = get();
+      const columnFilter = filters.find((f) => f.key === field);
+      const dataType = columnFilter ? toFilterDataType(columnFilter.dataType) : "string";
       set((state) => ({
-        tags: state.tags.map((t) => (t.id === tagId ? { ...t, field } : t)),
+        tags: state.tags.map((t) => (t.id === tagId ? { ...t, field, dataType } : t)),
       }));
     },
 

frontend/components/common/advanced-search/types.ts

@@ -1,7 +1,7 @@
 import { uniqueId } from "lodash";
 
 import { type ColumnFilter, dataTypeOperationsMap } from "@/components/ui/infinite-datatable/ui/datatable-filter/utils";
-import { type Filter } from "@/lib/actions/common/filters";
+import { type Filter, type FilterDataType } from "@/lib/actions/common/filters";
 import { type Operator } from "@/lib/actions/common/operators";
 
 export type { ColumnFilter } from "@/components/ui/infinite-datatable/ui/datatable-filter/utils";
@@ -21,6 +21,7 @@ export interface FilterTagRef {
 export interface FilterTag {
   id: string;
   field: string;
+  dataType?: FilterDataType;
   operator: Operator;
   value: string | string[];
 }
@@ -38,6 +39,7 @@ export type FilterTagFocusState =
 
 export function createFilterFromTag(tag: FilterTag): Filter {
   return {
+    dataType: tag.dataType,
     column: tag.field,
     operator: tag.operator,
     value: tag.value,
@@ -48,6 +50,7 @@ export function createTagFromFilter(filter: Filter): FilterTag {
   return {
     id: `tag-${uniqueId()}`,
     field: filter.column,
+    dataType: filter.dataType,
     operator: filter.operator,
     // Preserve array values directly, stringify others
     value: Array.isArray(filter.value) ? filter.value : String(filter.value),

frontend/components/settings/alerts/manage-alert-sheet.tsx

@@ -7,8 +7,8 @@ import useSWR from "swr";
 
 import TimeSeriesChart from "@/components/charts/time-series-chart";
 import { ChartSkeleton } from "@/components/charts/time-series-chart/skeleton";
+import { type TimeSeriesDataPoint } from "@/components/charts/time-series-chart/types";
 import { useTimeSeriesStatsUrl } from "@/components/charts/time-series-chart/use-time-series-stats-url";
-import { type EventsStatsDataPoint } from "@/components/signal/store";
 import { Button } from "@/components/ui/button";
 import DateRangeFilter from "@/components/ui/date-range-filter";
 import { Input } from "@/components/ui/input";
@@ -143,7 +143,7 @@ export default function ManageAlertSheet({
     endDate: dateRange.endDate ?? null,
   });
 
-  const { data: eventsStats, isLoading: isLoadingStats } = useSWR<{ items: EventsStatsDataPoint[] }>(
+  const { data: eventsStats, isLoading: isLoadingStats } = useSWR<{ items: TimeSeriesDataPoint[] }>(
     selectedSignal && statsUrl ? statsUrl : null,
     swrFetcher,
     {

frontend/components/signal/clusters-section/cluster-breadcrumb.tsx

@@ -0,0 +1,91 @@
+"use client";
+
+import { AnimatePresence, motion } from "framer-motion";
+
+import { type ClusterNode } from "./utils";
+
+interface ClusterBreadcrumbProps {
+  breadcrumb: ClusterNode[];
+  selectedClusterId: string | null;
+  onNavigateToBreadcrumb: (index: number) => void;
+}
+
+const slideIn = {
+  initial: { opacity: 0.3, x: -45 },
+  animate: { opacity: 1, x: 0, transition: { type: "spring", stiffness: 300, damping: 30, mass: 0.3 } },
+  exit: {
+    opacity: 0.3,
+    x: -20,
+    transition: { duration: 0.1, ease: "easeOut" },
+  },
+};
+
+const slashSlideIn = {
+  initial: { opacity: 0.3, x: -12 },
+  animate: { opacity: 1, x: 0, transition: { type: "spring", stiffness: 300, damping: 30, mass: 0.8 } },
+  exit: {
+    opacity: 0.3,
+    x: -8,
+    transition: { duration: 0.1, ease: "easeOut" },
+  },
+};
+
+const levelTransition = {
+  initial: { opacity: 0, width: 0 },
+  animate: { opacity: 1, width: "auto" },
+  exit: { opacity: 0, width: 0 },
+  transition: { type: "spring", stiffness: 300, damping: 30, mass: 0.3 },
+};
+
+// Slash width (~6px at text-sm) + gap to match parent's gap-2 (8px) on each side
+const SLASH_CONTAINER_PL = "pl-[22px]";
+
+export default function ClusterBreadcrumb({
+  breadcrumb,
+  selectedClusterId,
+  onNavigateToBreadcrumb,
+}: ClusterBreadcrumbProps) {
+  return (
+    <div className="flex items-center text-sm min-w-0 pl-1">
+      <button
+        className={`hover:underline shrink-0 ${!selectedClusterId ? "text-secondary-foreground" : "text-muted-foreground"}`}
+        onClick={() => onNavigateToBreadcrumb(-1)}
+      >
+        Event clusters
+      </button>
+
+      {/* Outer: handles levels appearing/disappearing */}
+      <AnimatePresence initial={false}>
+        {breadcrumb.map((node, index) => {
+          const isLast = index === breadcrumb.length - 1;
+          return (
+            <motion.div
+              key={index}
+              className={`relative min-w-0 flex-shrink overflow-hidden ${SLASH_CONTAINER_PL}`}
+              style={{ maskImage: "linear-gradient(to right, transparent, black 12px, black)" }}
+              {...levelTransition}
+            >
+              {/* Inner: handles swaps within this level (e.g. sibling leaf selection) */}
+              <AnimatePresence initial={false} mode="wait">
+                <motion.div key={node.id} className="flex">
+                  <motion.span className="absolute left-[8px] top-0 text-muted-foreground" {...slashSlideIn}>
+                    /
+                  </motion.span>
+                  <motion.button
+                    className={`hover:underline truncate block max-w-full text-left ${
+                      isLast ? "text-secondary-foreground" : "text-muted-foreground"
+                    }`}
+                    onClick={() => onNavigateToBreadcrumb(index)}
+                    {...slideIn}
+                  >
+                    {node.name}
+                  </motion.button>
+                </motion.div>
+              </AnimatePresence>
+            </motion.div>
+          );
+        })}
+      </AnimatePresence>
+    </div>
+  );
+}