fix(charts): restore the default log axis grid

Assisted-by: Claude Opus 5.5

.github/workflows/goci.yaml

@@ -67,7 +67,7 @@ jobs:
         with:
           go-version: "1.24"
       - name: check-semconv-generated-files
-        run: go run ./scripts/semconv -check
+        run: make semconv-check
   build:
     if: |
       github.event_name == 'merge_group' ||

Makefile

@@ -262,6 +262,10 @@ py-clean: ## Clear all pycache and pytest cache from tests directory recursively
 semconv-generate: ## Regenerate semantic-convention families for Go and TypeScript
 	@go run ./scripts/semconv
 
+.PHONY: semconv-check
+semconv-check: ## Fail if the generated semantic-convention files are stale
+	@go run ./scripts/semconv -check
+
 .PHONY: gen-mocks
 gen-mocks:
 	@echo ">> Generating mocks"

docs/api/openapi.yml

@@ -3425,6 +3425,13 @@ components:
           nullable: true
           type: number
       type: object
+    DashboardtypesAxisScale:
+      enum:
+      - auto
+      - linear
+      - log
+      - symlog
+      type: string
     DashboardtypesBarChartPanelSpec:
       properties:
         axes:
@@ -3731,6 +3738,84 @@ components:
         hide:
           type: boolean
       type: object
+    DashboardtypesHeatmapAxes:
+      properties:
+        "y":
+          $ref: '#/components/schemas/DashboardtypesHeatmapAxis'
+      type: object
+    DashboardtypesHeatmapAxis:
+      properties:
+        scale:
+          $ref: '#/components/schemas/DashboardtypesHeatmapYScale'
+      type: object
+    DashboardtypesHeatmapChartAppearance:
+      properties:
+        colors:
+          $ref: '#/components/schemas/DashboardtypesHeatmapColors'
+      type: object
+    DashboardtypesHeatmapColorMode:
+      enum:
+      - palette
+      - opacity
+      type: string
+    DashboardtypesHeatmapColorScale:
+      enum:
+      - log
+      - sqrt
+      - linear
+      type: string
+    DashboardtypesHeatmapColors:
+      properties:
+        fill:
+          type: string
+        maxCount:
+          nullable: true
+          type: number
+        minCount:
+          nullable: true
+          type: number
+        mode:
+          $ref: '#/components/schemas/DashboardtypesHeatmapColorMode'
+        palette:
+          $ref: '#/components/schemas/DashboardtypesHeatmapPalette'
+        scale:
+          $ref: '#/components/schemas/DashboardtypesHeatmapColorScale'
+        steps:
+          type: integer
+      type: object
+    DashboardtypesHeatmapPalette:
+      enum:
+      - ice
+      - moss
+      - rust
+      - graphite
+      - ember
+      - lagoon
+      - orchid
+      - verdant
+      - lava
+      - beacon
+      type: string
+    DashboardtypesHeatmapPanelSpec:
+      properties:
+        axes:
+          $ref: '#/components/schemas/DashboardtypesHeatmapAxes'
+        chartAppearance:
+          $ref: '#/components/schemas/DashboardtypesHeatmapChartAppearance'
+        formatting:
+          $ref: '#/components/schemas/DashboardtypesPanelFormatting'
+        legend:
+          $ref: '#/components/schemas/DashboardtypesLegend'
+        visualization:
+          $ref: '#/components/schemas/DashboardtypesBasicVisualization'
+      type: object
+    DashboardtypesHeatmapYScale:
+      enum:
+      - auto
+      - linear
+      - log
+      - symlog
+      type: string
     DashboardtypesHistogramBuckets:
       properties:
         bucketCount:
@@ -4084,10 +4169,12 @@ components:
         mapping:
           signoz/AreaChartPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesAreaChartPanelSpec'
           signoz/BarChartPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesBarChartPanelSpec'
+          signoz/HeatmapPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHeatmapPanelSpec'
           signoz/HistogramPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHistogramPanelSpec'
           signoz/ListPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesListPanelSpec'
           signoz/NumberPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesNumberPanelSpec'
           signoz/PieChartPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesPieChartPanelSpec'
+          signoz/ScatterPlotPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesScatterPlotPanelSpec'
           signoz/TablePanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpec'
           signoz/TextPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpec'
           signoz/TimeSeriesPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTimeSeriesPanelSpec'
@@ -4102,6 +4189,8 @@ components:
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHistogramPanelSpec'
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesListPanelSpec'
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpec'
+      - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHeatmapPanelSpec'
+      - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesScatterPlotPanelSpec'
       type: object
     DashboardtypesPanelPluginKind:
       enum:
@@ -4114,6 +4203,8 @@ components:
       - signoz/HistogramPanel
       - signoz/ListPanel
       - signoz/TextPanel
+      - signoz/HeatmapPanel
+      - signoz/ScatterPlotPanel
       type: string
     DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesAreaChartPanelSpec:
       properties:
@@ -4139,6 +4230,18 @@ components:
       - kind
       - spec
       type: object
+    DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHeatmapPanelSpec:
+      properties:
+        kind:
+          enum:
+          - signoz/HeatmapPanel
+          type: string
+        spec:
+          $ref: '#/components/schemas/DashboardtypesHeatmapPanelSpec'
+      required:
+      - kind
+      - spec
+      type: object
     DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHistogramPanelSpec:
       properties:
         kind:
@@ -4187,6 +4290,18 @@ components:
       - kind
       - spec
       type: object
+    DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesScatterPlotPanelSpec:
+      properties:
+        kind:
+          enum:
+          - signoz/ScatterPlotPanel
+          type: string
+        spec:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotPanelSpec'
+      required:
+      - kind
+      - spec
+      type: object
     DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpec:
       properties:
         kind:
@@ -4266,6 +4381,16 @@ components:
         visualization:
           $ref: '#/components/schemas/DashboardtypesBasicVisualization'
       type: object
+    DashboardtypesPointDiameter:
+      maximum: 40
+      minimum: 2
+      nullable: true
+      type: integer
+    DashboardtypesPointOpacity:
+      maximum: 1
+      minimum: 0.1
+      nullable: true
+      type: number
     DashboardtypesPostableDashboardV2:
       properties:
         generateName:
@@ -4439,6 +4564,87 @@ components:
       required:
       - queryValue
       type: object
+    DashboardtypesScatterPlotAxes:
+      properties:
+        x:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotAxis'
+        "y":
+          $ref: '#/components/schemas/DashboardtypesScatterPlotAxis'
+      type: object
+    DashboardtypesScatterPlotAxis:
+      properties:
+        label:
+          description: Axis title. Empty draws none.
+          type: string
+        scale:
+          $ref: '#/components/schemas/DashboardtypesAxisScale'
+        softMax:
+          nullable: true
+          type: number
+        softMin:
+          nullable: true
+          type: number
+      type: object
+    DashboardtypesScatterPlotChartAppearance:
+      properties:
+        points:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotPoints'
+      type: object
+    DashboardtypesScatterPlotDimensions:
+      properties:
+        color:
+          description: Group-by label names (e.g. k8s.namespace.name) whose combined
+            values colour dots and drive the legend. Empty colours by every group-by
+            label.
+          items:
+            type: string
+          nullable: true
+          type: array
+        size:
+          description: Value column key that scales dot size. Empty draws every dot
+            at the default size.
+          type: string
+        x:
+          description: Value column key (queryName, or queryName.expression for a
+            multi-aggregation query) plotted on the x axis. Empty uses the first value
+            column.
+          type: string
+        "y":
+          description: Value column key plotted on the y axis. Empty uses the second
+            value column.
+          type: string
+      type: object
+    DashboardtypesScatterPlotPanelSpec:
+      properties:
+        axes:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotAxes'
+        chartAppearance:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotChartAppearance'
+        dimensions:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotDimensions'
+        formatting:
+          $ref: '#/components/schemas/DashboardtypesTableFormatting'
+        legend:
+          $ref: '#/components/schemas/DashboardtypesLegend'
+        thresholds:
+          items:
+            $ref: '#/components/schemas/DashboardtypesThresholdWithLabel'
+          nullable: true
+          type: array
+        visualization:
+          $ref: '#/components/schemas/DashboardtypesBasicVisualization'
+      type: object
+    DashboardtypesScatterPlotPoints:
+      properties:
+        maxSize:
+          $ref: '#/components/schemas/DashboardtypesPointDiameter'
+        minSize:
+          $ref: '#/components/schemas/DashboardtypesPointDiameter'
+        opacity:
+          $ref: '#/components/schemas/DashboardtypesPointOpacity'
+        size:
+          $ref: '#/components/schemas/DashboardtypesPointDiameter'
+      type: object
     DashboardtypesSource:
       enum:
       - user
@@ -9041,6 +9247,15 @@ components:
       - alertType
       - ruleType
       type: object
+    RuletypesListableRuleViews:
+      properties:
+        views:
+          items:
+            $ref: '#/components/schemas/RuletypesRuleView'
+          type: array
+      required:
+      - views
+      type: object
     RuletypesListableRules:
       properties:
         labels:
@@ -9138,6 +9353,16 @@ components:
       - ruleType
       - condition
       type: object
+    RuletypesPostableRuleView:
+      properties:
+        data:
+          $ref: '#/components/schemas/RuletypesRuleViewData'
+        name:
+          type: string
+      required:
+      - name
+      - data
+      type: object
     RuletypesQueryType:
       enum:
       - builder
@@ -9276,6 +9501,45 @@ components:
       - promql_rule
       - anomaly_rule
       type: string
+    RuletypesRuleView:
+      properties:
+        createdAt:
+          format: date-time
+          type: string
+        data:
+          $ref: '#/components/schemas/RuletypesRuleViewData'
+        id:
+          type: string
+        name:
+          type: string
+        orgId:
+          type: string
+        updatedAt:
+          format: date-time
+          type: string
+      required:
+      - id
+      - name
+      - data
+      - orgId
+      type: object
+    RuletypesRuleViewData:
+      properties:
+        order:
+          $ref: '#/components/schemas/RuletypesListOrder'
+        query:
+          type: string
+        sort:
+          $ref: '#/components/schemas/RuletypesListSort'
+        states:
+          items:
+            type: string
+          type: array
+        version:
+          type: string
+      required:
+      - version
+      type: object
     RuletypesScheduleType:
       enum:
       - hourly
@@ -21193,6 +21457,235 @@ paths:
       tags:
       - users
       x-signoz-stability: alpha
+  /api/v2/rule_views:
+    get:
+      deprecated: false
+      description: Returns every saved view in the calling user's org. Saved views
+        are shared org-wide.
+      operationId: ListRuleViews
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    $ref: '#/components/schemas/RuletypesListableRuleViews'
+                  status:
+                    type: string
+                required:
+                - status
+                - data
+                type: object
+          description: OK
+        "401":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Unauthorized
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Forbidden
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Internal Server Error
+      security:
+      - api_key:
+        - VIEWER
+      - tokenizer:
+        - VIEWER
+      summary: List rule saved views
+      tags:
+      - rules
+      x-signoz-stability: alpha
+    post:
+      deprecated: false
+      description: Persists the calling user's rule listing state (query, states,
+        sort, order) as a named, reusable view shared across the org.
+      operationId: CreateRuleView
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RuletypesPostableRuleView'
+      responses:
+        "201":
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    $ref: '#/components/schemas/RuletypesRuleView'
+                  status:
+                    type: string
+                required:
+                - status
+                - data
+                type: object
+          description: Created
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Bad Request
+        "401":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Unauthorized
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Forbidden
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Internal Server Error
+      security:
+      - api_key:
+        - VIEWER
+      - tokenizer:
+        - VIEWER
+      summary: Create rule saved view
+      tags:
+      - rules
+      x-signoz-stability: alpha
+  /api/v2/rule_views/{id}:
+    delete:
+      deprecated: false
+      description: Removes a saved view. Saved views are shared org-wide. Deleting
+        a non-existent view returns 404.
+      operationId: DeleteRuleView
+      parameters:
+      - in: path
+        name: id
+        required: true
+        schema:
+          type: string
+      responses:
+        "204":
+          description: No Content
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Bad Request
+        "401":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Unauthorized
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Forbidden
+        "404":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Not Found
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Internal Server Error
+      security:
+      - api_key:
+        - VIEWER
+      - tokenizer:
+        - VIEWER
+      summary: Delete rule saved view
+      tags:
+      - rules
+      x-signoz-stability: alpha
+    put:
+      deprecated: false
+      description: Replaces a saved view's name and data. Saved views are shared org-wide.
+      operationId: UpdateRuleView
+      parameters:
+      - in: path
+        name: id
+        required: true
+        schema:
+          type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RuletypesPostableRuleView'
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    $ref: '#/components/schemas/RuletypesRuleView'
+                  status:
+                    type: string
+                required:
+                - status
+                - data
+                type: object
+          description: OK
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Bad Request
+        "401":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Unauthorized
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Forbidden
+        "404":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Not Found
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Internal Server Error
+      security:
+      - api_key:
+        - VIEWER
+      - tokenizer:
+        - VIEWER
+      summary: Update rule saved view
+      tags:
+      - rules
+      x-signoz-stability: alpha
   /api/v2/rules:
     get:
       deprecated: true

docs/contributing/query-range.md

@@ -84,9 +84,9 @@ A storage answers four questions and nothing else:
 | WhenAbsent | Absent row reads | Positive filter | Raw select | Multi-candidate column | Field keys |
 |---|---|---|---|---|---|
 | `AlwaysPresent` | a real value | no guard | no guard | no branch, ends the candidate list | table columns |
-| `AbsentIsSentinel` | `''`, 0, false, and that is not a value | exists guard | exists guard | presence branch | map attributes, cast JSON paths, string families |
+| `AbsentIsSentinel` | `''`, 0, false, and that is not a value | exists guard | exists guard | presence branch | map attributes, cast JSON paths, string families of such members |
 | `AbsentIsNull` | NULL | no guard | no guard | presence branch | multi-era folds, body JSON paths, numeric families |
-| `AbsentIsValue` | `''`, and that is the keyless contract | no guard | no guard | no presence branch | metrics labels, rule state history labels |
+| `AbsentIsValue` | `''`, and that is the keyless contract | no guard | no guard | no presence branch | metrics labels, rule state history labels, and families of such members |
 
 ### The generic layer
 
@@ -109,7 +109,7 @@ The functions, from the outside in:
 | `RejectsBodyFunction(traits, operator)` | Runs before resolution. A storage without body functions (`has`, `hasAny`, `hasAll`, `hasToken`, `search`) errors. The fingerprint side of a split skips the term, because the main query evaluates it. After resolution, `Condition` errors when `has`, `hasAny`, `hasAll`, or `hasToken` lands on a map-backed key (resource, attribute, scope), before the split can drop it. |
 | `SharedCondition(...)` | The `Compile` of every storage without its own condition language: `LogicalRead`, the shared data-type collision cast, `OperatorCondition`, then the guard rule. |
 | `OperatorCondition(...)` | The operator switch over an already cast read. A storage with its own cast policy composes with it. |
-| `LogicalRead(...)` | The only place family expressions are built. A single-member field reads through its member. A family merges the member reads, current member first: `COALESCE(NULLIF(m1, ''), NULLIF(m2, ''), '')` for strings, `multiIf` with a NULL tail for numbers. It ORs the member presence tests. A row without any member reads what the tail of the merge reads. A member with a value map reads through `TransformRead`. `NOT EXISTS` is the read's `Absence`, the storage's own negated form. |
+| `LogicalRead(...)` | The only place family expressions are built. A single-member field reads through its member. A family merges the member reads, current member first: `COALESCE(NULLIF(m1, ''), NULLIF(m2, ''), '')` for strings, `multiIf` with a NULL tail for numbers. It ORs the member presence tests. A row without any member reads what the tail of the merge reads. When every member reads its sentinel as a value, so does the family. A member with a value map reads through `TransformRead`. `NOT EXISTS` is the read's `Absence`, the storage's own negated form. |
 
 ### A resolved key
 

frontend/__mocks__/uplotMock.ts

@@ -2,6 +2,8 @@
 
 // Mock for uplot library used in tests
 export interface MockUPlotInstance {
+	/** Consumers read `root.parentElement` to detect a re-mounted container. */
+	root: HTMLDivElement;
 	setData: jest.Mock;
 	setSize: jest.Mock;
 	destroy: jest.Mock;
@@ -17,13 +19,20 @@ export interface MockUPlotPaths {
 }
 
 // Create mock instance methods
-const createMockUPlotInstance = (): MockUPlotInstance => ({
-	setData: jest.fn(),
-	setSize: jest.fn(),
-	destroy: jest.fn(),
-	redraw: jest.fn(),
-	setSeries: jest.fn(),
-});
+const createMockUPlotInstance = (target?: HTMLElement): MockUPlotInstance => {
+	const root = document.createElement('div');
+	// Real uPlot mounts its root inside the target; without it a re-render reads
+	// `root.parentElement` off undefined and throws.
+	target?.appendChild(root);
+	return {
+		root,
+		setData: jest.fn(),
+		setSize: jest.fn(),
+		destroy: jest.fn(),
+		redraw: jest.fn(),
+		setSeries: jest.fn(),
+	};
+};
 
 // Path builder: (self, seriesIdx, idx0, idx1) => paths or null
 const createMockPathBuilder = (name: string): jest.Mock =>
@@ -48,19 +57,23 @@ const mockPaths = {
 const mockTzDate = jest.fn(
 	(date: Date, _timezone: string) => new Date(date.getTime()),
 );
+const mockOrient = jest.fn();
 
 // Mock uPlot constructor - this needs to be a proper constructor function
 function MockUPlot(
 	_options: unknown,
 	_data: unknown,
-	_target: HTMLElement,
+	target: HTMLElement,
 ): MockUPlotInstance {
-	return createMockUPlotInstance();
+	return createMockUPlotInstance(target);
 }
 
 // Add static methods to the constructor
 MockUPlot.tzDate = mockTzDate;
 MockUPlot.paths = mockPaths;
+MockUPlot.orient = mockOrient;
+// Pinned so canvas-space maths in draw hooks is deterministic under jsdom.
+MockUPlot.pxRatio = 1;
 
 // Export the constructor as default
 export default MockUPlot;

frontend/scripts/story-shots.mjs

@@ -417,7 +417,7 @@ for (const theme of themes.length ? themes : [null]) {
 						break;
 					}
 
-					height = needed;
+					height = Math.ceil(needed);
 					await page.setViewportSize({ width: Number(opts.width), height });
 					await page.waitForTimeout(Number(opts.settle));
 				}

frontend/src/api/generated/services/rules/index.ts

@@ -19,7 +19,9 @@ import type {
 
 import type {
 	CreateRule201,
+	CreateRuleView201,
 	DeleteRuleByIDPathParameters,
+	DeleteRuleViewPathParameters,
 	GetRuleByID200,
 	GetRuleByIDPathParameters,
 	GetRuleHistoryFilterKeys200,
@@ -40,6 +42,7 @@ import type {
 	GetRuleHistoryTopContributors200,
 	GetRuleHistoryTopContributorsParams,
 	GetRuleHistoryTopContributorsPathParameters,
+	ListRuleViews200,
 	ListRules200,
 	ListRulesV3200,
 	ListRulesV3Params,
@@ -47,8 +50,11 @@ import type {
 	PatchRuleByIDPathParameters,
 	RenderErrorResponseDTO,
 	RuletypesPostableRuleDTO,
+	RuletypesPostableRuleViewDTO,
 	TestRule200,
 	UpdateRuleByIDPathParameters,
+	UpdateRuleView200,
+	UpdateRuleViewPathParameters,
 } from '../sigNoz.schemas';
 
 import { GeneratedAPIInstance } from '../../../generatedAPIInstance';
@@ -74,6 +80,351 @@ const withQueryKey = <T extends object, K>(
 	return result;
 };
 
+/**
+ * Returns every saved view in the calling user's org. Saved views are shared org-wide.
+ * @summary List rule saved views
+ */
+export const listRuleViews = (signal?: AbortSignal) => {
+	return GeneratedAPIInstance<ListRuleViews200>({
+		url: `/api/v2/rule_views`,
+		method: 'GET',
+		signal,
+	});
+};
+
+export const getListRuleViewsQueryKey = () => {
+	return [`/api/v2/rule_views`] as const;
+};
+
+export const getListRuleViewsQueryOptions = <
+	TData = Awaited<ReturnType<typeof listRuleViews>>,
+	TError = ErrorType<RenderErrorResponseDTO>,
+>(options?: {
+	query?: UseQueryOptions<
+		Awaited<ReturnType<typeof listRuleViews>>,
+		TError,
+		TData
+	>;
+}) => {
+	const { query: queryOptions } = options ?? {};
+
+	const queryKey = queryOptions?.queryKey ?? getListRuleViewsQueryKey();
+
+	const queryFn: QueryFunction<Awaited<ReturnType<typeof listRuleViews>>> = ({
+		signal,
+	}) => listRuleViews(signal);
+
+	return { queryKey, queryFn, ...queryOptions } as UseQueryOptions<
+		Awaited<ReturnType<typeof listRuleViews>>,
+		TError,
+		TData
+	> & { queryKey: QueryKey };
+};
+
+export type ListRuleViewsQueryResult = NonNullable<
+	Awaited<ReturnType<typeof listRuleViews>>
+>;
+export type ListRuleViewsQueryError = ErrorType<RenderErrorResponseDTO>;
+
+/**
+ * @summary List rule saved views
+ */
+
+export function useListRuleViews<
+	TData = Awaited<ReturnType<typeof listRuleViews>>,
+	TError = ErrorType<RenderErrorResponseDTO>,
+>(options?: {
+	query?: UseQueryOptions<
+		Awaited<ReturnType<typeof listRuleViews>>,
+		TError,
+		TData
+	>;
+}): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+	const queryOptions = getListRuleViewsQueryOptions(options);
+
+	const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+		queryKey: QueryKey;
+	};
+
+	return withQueryKey(query, queryOptions.queryKey);
+}
+
+/**
+ * @summary List rule saved views
+ */
+export const invalidateListRuleViews = async (
+	queryClient: QueryClient,
+	options?: InvalidateOptions,
+): Promise<QueryClient> => {
+	await queryClient.invalidateQueries(
+		{ queryKey: getListRuleViewsQueryKey() },
+		options,
+	);
+
+	return queryClient;
+};
+
+/**
+ * Persists the calling user's rule listing state (query, states, sort, order) as a named, reusable view shared across the org.
+ * @summary Create rule saved view
+ */
+export const createRuleView = (
+	ruletypesPostableRuleViewDTO?: BodyType<RuletypesPostableRuleViewDTO>,
+	signal?: AbortSignal,
+) => {
+	return GeneratedAPIInstance<CreateRuleView201>({
+		url: `/api/v2/rule_views`,
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		data: ruletypesPostableRuleViewDTO,
+		signal,
+	});
+};
+
+export const getCreateRuleViewMutationOptions = <
+	TError = ErrorType<RenderErrorResponseDTO>,
+	TContext = unknown,
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof createRuleView>>,
+		TError,
+		{ data?: BodyType<RuletypesPostableRuleViewDTO> },
+		TContext
+	>;
+}): UseMutationOptions<
+	Awaited<ReturnType<typeof createRuleView>>,
+	TError,
+	{ data?: BodyType<RuletypesPostableRuleViewDTO> },
+	TContext
+> => {
+	const mutationKey = ['createRuleView'];
+	const { mutation: mutationOptions } = options
+		? options.mutation &&
+			'mutationKey' in options.mutation &&
+			options.mutation.mutationKey
+			? options
+			: { ...options, mutation: { ...options.mutation, mutationKey } }
+		: { mutation: { mutationKey } };
+
+	const mutationFn: MutationFunction<
+		Awaited<ReturnType<typeof createRuleView>>,
+		{ data?: BodyType<RuletypesPostableRuleViewDTO> }
+	> = (props) => {
+		const { data } = props ?? {};
+
+		return createRuleView(data);
+	};
+
+	return { mutationFn, ...mutationOptions };
+};
+
+export type CreateRuleViewMutationResult = NonNullable<
+	Awaited<ReturnType<typeof createRuleView>>
+>;
+export type CreateRuleViewMutationBody =
+	| BodyType<RuletypesPostableRuleViewDTO>
+	| undefined;
+export type CreateRuleViewMutationError = ErrorType<RenderErrorResponseDTO>;
+
+/**
+ * @summary Create rule saved view
+ */
+export const useCreateRuleView = <
+	TError = ErrorType<RenderErrorResponseDTO>,
+	TContext = unknown,
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof createRuleView>>,
+		TError,
+		{ data?: BodyType<RuletypesPostableRuleViewDTO> },
+		TContext
+	>;
+}): UseMutationResult<
+	Awaited<ReturnType<typeof createRuleView>>,
+	TError,
+	{ data?: BodyType<RuletypesPostableRuleViewDTO> },
+	TContext
+> => {
+	return useMutation(getCreateRuleViewMutationOptions(options));
+};
+/**
+ * Removes a saved view. Saved views are shared org-wide. Deleting a non-existent view returns 404.
+ * @summary Delete rule saved view
+ */
+export const deleteRuleView = (
+	{ id }: DeleteRuleViewPathParameters,
+	signal?: AbortSignal,
+) => {
+	return GeneratedAPIInstance<void>({
+		url: `/api/v2/rule_views/${id}`,
+		method: 'DELETE',
+		signal,
+	});
+};
+
+export const getDeleteRuleViewMutationOptions = <
+	TError = ErrorType<RenderErrorResponseDTO>,
+	TContext = unknown,
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof deleteRuleView>>,
+		TError,
+		{ pathParams: DeleteRuleViewPathParameters },
+		TContext
+	>;
+}): UseMutationOptions<
+	Awaited<ReturnType<typeof deleteRuleView>>,
+	TError,
+	{ pathParams: DeleteRuleViewPathParameters },
+	TContext
+> => {
+	const mutationKey = ['deleteRuleView'];
+	const { mutation: mutationOptions } = options
+		? options.mutation &&
+			'mutationKey' in options.mutation &&
+			options.mutation.mutationKey
+			? options
+			: { ...options, mutation: { ...options.mutation, mutationKey } }
+		: { mutation: { mutationKey } };
+
+	const mutationFn: MutationFunction<
+		Awaited<ReturnType<typeof deleteRuleView>>,
+		{ pathParams: DeleteRuleViewPathParameters }
+	> = (props) => {
+		const { pathParams } = props ?? {};
+
+		return deleteRuleView(pathParams);
+	};
+
+	return { mutationFn, ...mutationOptions };
+};
+
+export type DeleteRuleViewMutationResult = NonNullable<
+	Awaited<ReturnType<typeof deleteRuleView>>
+>;
+
+export type DeleteRuleViewMutationError = ErrorType<RenderErrorResponseDTO>;
+
+/**
+ * @summary Delete rule saved view
+ */
+export const useDeleteRuleView = <
+	TError = ErrorType<RenderErrorResponseDTO>,
+	TContext = unknown,
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof deleteRuleView>>,
+		TError,
+		{ pathParams: DeleteRuleViewPathParameters },
+		TContext
+	>;
+}): UseMutationResult<
+	Awaited<ReturnType<typeof deleteRuleView>>,
+	TError,
+	{ pathParams: DeleteRuleViewPathParameters },
+	TContext
+> => {
+	return useMutation(getDeleteRuleViewMutationOptions(options));
+};
+/**
+ * Replaces a saved view's name and data. Saved views are shared org-wide.
+ * @summary Update rule saved view
+ */
+export const updateRuleView = (
+	{ id }: UpdateRuleViewPathParameters,
+	ruletypesPostableRuleViewDTO?: BodyType<RuletypesPostableRuleViewDTO>,
+	signal?: AbortSignal,
+) => {
+	return GeneratedAPIInstance<UpdateRuleView200>({
+		url: `/api/v2/rule_views/${id}`,
+		method: 'PUT',
+		headers: { 'Content-Type': 'application/json' },
+		data: ruletypesPostableRuleViewDTO,
+		signal,
+	});
+};
+
+export const getUpdateRuleViewMutationOptions = <
+	TError = ErrorType<RenderErrorResponseDTO>,
+	TContext = unknown,
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof updateRuleView>>,
+		TError,
+		{
+			pathParams: UpdateRuleViewPathParameters;
+			data?: BodyType<RuletypesPostableRuleViewDTO>;
+		},
+		TContext
+	>;
+}): UseMutationOptions<
+	Awaited<ReturnType<typeof updateRuleView>>,
+	TError,
+	{
+		pathParams: UpdateRuleViewPathParameters;
+		data?: BodyType<RuletypesPostableRuleViewDTO>;
+	},
+	TContext
+> => {
+	const mutationKey = ['updateRuleView'];
+	const { mutation: mutationOptions } = options
+		? options.mutation &&
+			'mutationKey' in options.mutation &&
+			options.mutation.mutationKey
+			? options
+			: { ...options, mutation: { ...options.mutation, mutationKey } }
+		: { mutation: { mutationKey } };
+
+	const mutationFn: MutationFunction<
+		Awaited<ReturnType<typeof updateRuleView>>,
+		{
+			pathParams: UpdateRuleViewPathParameters;
+			data?: BodyType<RuletypesPostableRuleViewDTO>;
+		}
+	> = (props) => {
+		const { pathParams, data } = props ?? {};
+
+		return updateRuleView(pathParams, data);
+	};
+
+	return { mutationFn, ...mutationOptions };
+};
+
+export type UpdateRuleViewMutationResult = NonNullable<
+	Awaited<ReturnType<typeof updateRuleView>>
+>;
+export type UpdateRuleViewMutationBody =
+	| BodyType<RuletypesPostableRuleViewDTO>
+	| undefined;
+export type UpdateRuleViewMutationError = ErrorType<RenderErrorResponseDTO>;
+
+/**
+ * @summary Update rule saved view
+ */
+export const useUpdateRuleView = <
+	TError = ErrorType<RenderErrorResponseDTO>,
+	TContext = unknown,
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof updateRuleView>>,
+		TError,
+		{
+			pathParams: UpdateRuleViewPathParameters;
+			data?: BodyType<RuletypesPostableRuleViewDTO>;
+		},
+		TContext
+	>;
+}): UseMutationResult<
+	Awaited<ReturnType<typeof updateRuleView>>,
+	TError,
+	{
+		pathParams: UpdateRuleViewPathParameters;
+		data?: BodyType<RuletypesPostableRuleViewDTO>;
+	},
+	TContext
+> => {
+	return useMutation(getUpdateRuleViewMutationOptions(options));
+};
 /**
  * This endpoint lists all alert rules with their current evaluation state. Deprecated: use ListRulesV3, which supports filtering, sorting and pagination.
  * @deprecated

frontend/src/api/generated/services/sigNoz.schemas.ts

@@ -5291,6 +5291,87 @@ export interface DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDa
 	spec: DashboardtypesTextPanelSpecDTO;
 }
 
+export enum DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHeatmapPanelSpecDTOKind {
+	'signoz/HeatmapPanel' = 'signoz/HeatmapPanel',
+}
+export enum DashboardtypesHeatmapYScaleDTO {
+	auto = 'auto',
+	linear = 'linear',
+	log = 'log',
+	symlog = 'symlog',
+}
+export interface DashboardtypesHeatmapAxisDTO {
+	scale?: DashboardtypesHeatmapYScaleDTO;
+}
+
+export interface DashboardtypesHeatmapAxesDTO {
+	y?: DashboardtypesHeatmapAxisDTO;
+}
+
+export enum DashboardtypesHeatmapColorModeDTO {
+	palette = 'palette',
+	opacity = 'opacity',
+}
+export enum DashboardtypesHeatmapPaletteDTO {
+	ice = 'ice',
+	moss = 'moss',
+	rust = 'rust',
+	graphite = 'graphite',
+	ember = 'ember',
+	lagoon = 'lagoon',
+	orchid = 'orchid',
+	verdant = 'verdant',
+	lava = 'lava',
+	beacon = 'beacon',
+}
+export enum DashboardtypesHeatmapColorScaleDTO {
+	log = 'log',
+	sqrt = 'sqrt',
+	linear = 'linear',
+}
+export interface DashboardtypesHeatmapColorsDTO {
+	/**
+	 * @type string
+	 */
+	fill?: string;
+	/**
+	 * @type number,null
+	 */
+	maxCount?: number | null;
+	/**
+	 * @type number,null
+	 */
+	minCount?: number | null;
+	mode?: DashboardtypesHeatmapColorModeDTO;
+	palette?: DashboardtypesHeatmapPaletteDTO;
+	scale?: DashboardtypesHeatmapColorScaleDTO;
+	/**
+	 * @type integer
+	 */
+	steps?: number;
+}
+
+export interface DashboardtypesHeatmapChartAppearanceDTO {
+	colors?: DashboardtypesHeatmapColorsDTO;
+}
+
+export interface DashboardtypesHeatmapPanelSpecDTO {
+	axes?: DashboardtypesHeatmapAxesDTO;
+	chartAppearance?: DashboardtypesHeatmapChartAppearanceDTO;
+	formatting?: DashboardtypesPanelFormattingDTO;
+	legend?: DashboardtypesLegendDTO;
+	visualization?: DashboardtypesBasicVisualizationDTO;
+}
+
+export interface DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHeatmapPanelSpecDTO {
+	/**
+	 * @enum signoz/HeatmapPanel
+	 * @type string
+	 */
+	kind: DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHeatmapPanelSpecDTOKind;
+	spec: DashboardtypesHeatmapPanelSpecDTO;
+}
+
 export type DashboardtypesPanelPluginDTO =
 	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTimeSeriesPanelSpecDTO
 	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesBarChartPanelSpecDTO
@@ -5300,7 +5381,8 @@ export type DashboardtypesPanelPluginDTO =
 	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpecDTO
 	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHistogramPanelSpecDTO
 	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesListPanelSpecDTO
-	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpecDTO;
+	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpecDTO
+	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHeatmapPanelSpecDTO;
 
 export enum Querybuildertypesv5RequestTypeDTO {
 	scalar = 'scalar',
@@ -6226,6 +6308,7 @@ export enum DashboardtypesPanelPluginKindDTO {
 	'signoz/HistogramPanel' = 'signoz/HistogramPanel',
 	'signoz/ListPanel' = 'signoz/ListPanel',
 	'signoz/TextPanel' = 'signoz/TextPanel',
+	'signoz/HeatmapPanel' = 'signoz/HeatmapPanel',
 }
 /**
  * @nullable
@@ -10328,6 +10411,56 @@ export interface RuletypesListableRuleDTO {
 	updatedBy?: string;
 }
 
+export interface RuletypesRuleViewDataDTO {
+	order?: RuletypesListOrderDTO;
+	/**
+	 * @type string
+	 */
+	query?: string;
+	sort?: RuletypesListSortDTO;
+	/**
+	 * @type array
+	 */
+	states?: string[];
+	/**
+	 * @type string
+	 */
+	version: string;
+}
+
+export interface RuletypesRuleViewDTO {
+	/**
+	 * @type string
+	 * @format date-time
+	 */
+	createdAt?: string;
+	data: RuletypesRuleViewDataDTO;
+	/**
+	 * @type string
+	 */
+	id: string;
+	/**
+	 * @type string
+	 */
+	name: string;
+	/**
+	 * @type string
+	 */
+	orgId: string;
+	/**
+	 * @type string
+	 * @format date-time
+	 */
+	updatedAt?: string;
+}
+
+export interface RuletypesListableRuleViewsDTO {
+	/**
+	 * @type array
+	 */
+	views: RuletypesRuleViewDTO[];
+}
+
 export interface RuletypesListableRulesDTO {
 	/**
 	 * @type array
@@ -10496,6 +10629,14 @@ export interface RuletypesPostableRuleDTO {
 	version?: string;
 }
 
+export interface RuletypesPostableRuleViewDTO {
+	data: RuletypesRuleViewDataDTO;
+	/**
+	 * @type string
+	 */
+	name: string;
+}
+
 export type RuletypesRuleDTOAnnotations = { [key: string]: string };
 
 export type RuletypesRuleDTOLabels = { [key: string]: string };
@@ -13783,6 +13924,36 @@ export type GetUsersByRoleID200 = {
 	status: string;
 };
 
+export type ListRuleViews200 = {
+	data: RuletypesListableRuleViewsDTO;
+	/**
+	 * @type string
+	 */
+	status: string;
+};
+
+export type CreateRuleView201 = {
+	data: RuletypesRuleViewDTO;
+	/**
+	 * @type string
+	 */
+	status: string;
+};
+
+export type DeleteRuleViewPathParameters = {
+	id: string;
+};
+export type UpdateRuleViewPathParameters = {
+	id: string;
+};
+export type UpdateRuleView200 = {
+	data: RuletypesRuleViewDTO;
+	/**
+	 * @type string
+	 */
+	status: string;
+};
+
 export type ListRules200 = {
 	/**
 	 * @type array

frontend/src/api/v5/queryRange/prepareQueryRangePayloadV5.ts

@@ -198,6 +198,7 @@ function createBaseSpec(
 				: undefined,
 		legend: isEmpty(queryData.legend) ? undefined : queryData.legend,
 		having: normalizeHaving(queryData.having),
+		bucketOptions: queryData.bucketOptions,
 		functions: isEmpty(queryData.functions)
 			? undefined
 			: queryData.functions.map((func: QueryFunction): QueryFunction => {

frontend/src/components/InputWithLabel/InputWithLabel.styles.scss

@@ -5,6 +5,10 @@
 	border-radius: 2px 0px 0px 2px;
 
 	.label {
+		// Typography.Text takes its display from this token; at its `inline` default
+		// the label blockifies as a flex item and the text rides the top of the row.
+		--typography-text-display: flex;
+
 		font-size: 12px;
 		font-style: normal;
 		font-weight: 500;

frontend/src/components/QueryBuilderV2/QueryV2/QueryAddOns/BucketOptions/BucketOptions.module.scss

@@ -0,0 +1,142 @@
+/**
+ * Borrows the query builder's control metrics rather than the component defaults the
+ * toggle group and number input ship with: 36px tall, 2px radius, and the
+ * `--query-builder-v2-*` surface the selects above this row already paint on.
+ */
+.bucketOptions {
+	--toggle-group-radius: var(--radius-1);
+	--toggle-group-item-size: 36px;
+	--toggle-group-item-font-size: 13px;
+	--toggle-group-item-padding-left: var(--spacing-6);
+	--toggle-group-item-padding-right: var(--spacing-6);
+
+	// Repeated from `.query-add-ons` rather than inherited: the section also renders on a
+	// formula, which has no add-ons ancestor to pick the toggle palette up from.
+	--toggle-group-secondary-bg: var(
+		--query-builder-v2-toggle-group-background-color,
+		var(--l1-background-hover)
+	);
+	--toggle-group-secondary-border: var(
+		--query-builder-v2-toggle-group-border-color,
+		var(--l2-border)
+	);
+	--toggle-group-secondary-active-bg: var(
+		--query-builder-v2-toggle-group-active-background-color,
+		var(--l1-background)
+	);
+	--toggle-group-secondary-bg-hover: var(
+		--query-builder-v2-toggle-group-background-color-hover,
+		var(--l2-background)
+	);
+
+	--input-height: 36px;
+	--input-font-size: 13px;
+	--input-border-radius: var(--radius-1);
+	--input-border-color: var(--query-builder-v2-border-color, var(--l2-border));
+	--input-background: var(
+		--query-builder-v2-background-color,
+		var(--l2-background)
+	);
+	--input-foreground: var(--query-builder-v2-color, var(--l2-foreground));
+
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-6);
+
+	padding: var(--spacing-4);
+	box-sizing: border-box;
+	border: 1px solid var(--query-builder-v2-border-color, var(--l2-border));
+	border-radius: var(--radius-1);
+	background: var(--query-builder-v2-background-color, var(--l2-background));
+}
+
+.controls {
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	gap: var(--spacing-8);
+}
+
+/** One label paired with its control, at the same 10px rhythm as the aggregate rows. */
+.field {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-5);
+}
+
+.bounds {
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	gap: var(--spacing-6);
+}
+
+.label {
+	display: inline-flex;
+	align-items: center;
+	gap: var(--spacing-2);
+
+	color: var(--l3-foreground);
+	font-family: 'Geist Mono';
+	font-size: 12px;
+	font-weight: var(--font-weight-medium);
+	line-height: 18px;
+	letter-spacing: 0.48px;
+	text-transform: uppercase;
+	white-space: nowrap;
+}
+
+/**
+ * The toggle group exposes a font-size token but no family, so each item's label carries
+ * the query builder's value type itself.
+ */
+.toggleLabel {
+	font-family: 'Geist Mono';
+	font-size: 13px;
+	font-weight: var(--font-weight-normal);
+	letter-spacing: -0.07px;
+}
+
+/** Surface and metrics come from the `--input-*` tokens above; only the family has none. */
+.numberInput {
+	width: 104px;
+
+	font-family: 'Geist Mono';
+	letter-spacing: -0.07px;
+}
+
+/** Unfilled: a pill on the same row as the toggles above reads as another control,
+ *  and the bounds are derived rather than set here. */
+.bound {
+	padding: var(--spacing-1) 0;
+
+	font-family: 'Geist Mono';
+	font-size: 13px;
+	line-height: 20px;
+	letter-spacing: -0.07px;
+
+	color: var(--query-builder-v2-color, var(--l2-foreground));
+}
+
+.overflowBound {
+	color: var(--l3-foreground);
+}
+
+.muted {
+	font-family: 'Geist Mono';
+	font-size: 13px;
+	line-height: 20px;
+	color: var(--l3-foreground);
+}
+
+.hintIcon {
+	flex: none;
+	cursor: help;
+	color: var(--l3-foreground);
+}
+
+.closeButton {
+	margin-left: auto;
+	width: 24px;
+	height: 24px;
+}

frontend/src/components/QueryBuilderV2/QueryV2/QueryAddOns/BucketOptions/BucketOptions.tsx

@@ -0,0 +1,279 @@
+import { useCallback, useMemo, useState } from 'react';
+import { Tooltip } from 'antd';
+import cx from 'classnames';
+import { Button } from '@signozhq/ui/button';
+import { InputNumber } from '@signozhq/ui/input-number';
+import { ToggleGroupSimple } from '@signozhq/ui/toggle-group';
+import { ChevronUp, Info } from '@signozhq/icons';
+import {
+	Querybuildertypesv5BucketOptionsDTO,
+	Querybuildertypesv5BucketsKindDTO,
+} from 'api/generated/services/sigNoz.schemas';
+
+import {
+	BUCKET_KIND_HINTS,
+	BUCKET_KIND_OPTIONS,
+	DEFAULT_NUM_BUCKETS,
+	LOG_SCALE_OPTIONS,
+	MAX_NUM_BUCKETS,
+} from './constants';
+import {
+	formatUpperBound,
+	hasBoundsBeyondPreview,
+	isLinearBuckets,
+	kindOptionOf,
+	linearBuckets,
+	logBuckets,
+	logScaleOf,
+	previewUpperBounds,
+} from './utils';
+
+import styles from './BucketOptions.module.scss';
+
+function BucketOptions({
+	bucketOptions,
+	unit,
+	onChange,
+	onClose,
+}: {
+	bucketOptions?: Querybuildertypesv5BucketOptionsDTO;
+	/** The panel's y-axis unit, so the previewed bounds read the way the axis will. */
+	unit?: string;
+	onChange: (next: Querybuildertypesv5BucketOptionsDTO | undefined) => void;
+	/** Omitted where the section isn't dismissable, as on a formula. */
+	onClose?: () => void;
+}): JSX.Element {
+	// A linear axis has no bounds to describe until it has a max value, so the picked
+	// kind is held here rather than read back off the emitted options: it has to survive
+	// the gap between choosing Linear and filling the field in.
+	const [kind, setKind] = useState<Querybuildertypesv5BucketsKindDTO>(() =>
+		kindOptionOf(bucketOptions),
+	);
+	const linearSpec =
+		bucketOptions && isLinearBuckets(bucketOptions)
+			? bucketOptions.spec
+			: undefined;
+	const [logScale, setLogScale] = useState<number>(() =>
+		logScaleOf(bucketOptions),
+	);
+	const [maxValue, setMaxValue] = useState<number | null>(
+		linearSpec?.maxValue ?? null,
+	);
+	const [numBuckets, setNumBuckets] = useState<number | null>(
+		linearSpec?.numBuckets ?? null,
+	);
+
+	const emitLinear = useCallback(
+		(nextMaxValue: number | null, nextNumBuckets: number | null): void => {
+			// An incomplete linear axis is sent as no axis at all rather than as a spec the
+			// request would reject.
+			if (nextMaxValue === null || nextMaxValue <= 0) {
+				onChange(undefined);
+				return;
+			}
+
+			onChange(linearBuckets(nextMaxValue, nextNumBuckets));
+		},
+		[onChange],
+	);
+
+	const handleKindChange = useCallback(
+		(value: string): void => {
+			// Radix clears the value when the active item is clicked again; a bucket axis is
+			// always one of the two, so keep the current pick instead.
+			if (!value) {
+				return;
+			}
+
+			const nextKind = value as Querybuildertypesv5BucketsKindDTO;
+			setKind(nextKind);
+
+			if (nextKind === Querybuildertypesv5BucketsKindDTO.log) {
+				onChange(logBuckets(logScale));
+			} else {
+				emitLinear(maxValue, numBuckets);
+			}
+		},
+		[emitLinear, logScale, maxValue, numBuckets, onChange],
+	);
+
+	const handleScaleChange = useCallback(
+		(value: string): void => {
+			if (!value) {
+				return;
+			}
+
+			const nextScale = Number(value);
+			setLogScale(nextScale);
+			onChange(logBuckets(nextScale));
+		},
+		[onChange],
+	);
+
+	const handleMaxValueChange = useCallback(
+		(value: number | string | null): void => {
+			const next = value === null || value === '' ? null : Number(value);
+			setMaxValue(next);
+			emitLinear(next, numBuckets);
+		},
+		[emitLinear, numBuckets],
+	);
+
+	const handleNumBucketsChange = useCallback(
+		(value: number | string | null): void => {
+			const next = value === null || value === '' ? null : Number(value);
+			setNumBuckets(next);
+			emitLinear(maxValue, next);
+		},
+		[emitLinear, maxValue],
+	);
+
+	// The toggle group takes a ReactNode label, which is how each item picks up the
+	// query builder's value type — the component exposes no font-family token.
+	const kindItems = useMemo(
+		() =>
+			BUCKET_KIND_OPTIONS.map(({ value, label }) => ({
+				value,
+				label: <span className={styles.toggleLabel}>{label}</span>,
+				'aria-label': label,
+			})),
+		[],
+	);
+
+	const scaleItems = useMemo(
+		() =>
+			LOG_SCALE_OPTIONS.map(({ value, label }) => ({
+				value,
+				label: <span className={styles.toggleLabel}>{label}</span>,
+				'aria-label': label,
+			})),
+		[],
+	);
+
+	// The kind toggle can be ahead of what has been emitted, so the preview describes
+	// the picked kind rather than the emitted options.
+	const previewedOptions = useMemo(():
+		| Querybuildertypesv5BucketOptionsDTO
+		| undefined => {
+		if (kind === Querybuildertypesv5BucketsKindDTO.log) {
+			return logBuckets(logScale);
+		}
+		if (kind === Querybuildertypesv5BucketsKindDTO.linear && maxValue !== null) {
+			return linearBuckets(maxValue, numBuckets);
+		}
+		return undefined;
+	}, [kind, logScale, maxValue, numBuckets]);
+
+	const bounds = useMemo(
+		() =>
+			kind === Querybuildertypesv5BucketsKindDTO.linear && !previewedOptions
+				? undefined
+				: previewUpperBounds(previewedOptions),
+		[kind, previewedOptions],
+	);
+
+	return (
+		<div className={styles.bucketOptions} data-testid="bucket-options">
+			<div className={styles.controls}>
+				<div className={styles.field}>
+					<span className={styles.label}>Bucket by</span>
+					<ToggleGroupSimple
+						type="single"
+						value={kind}
+						items={kindItems}
+						onChange={handleKindChange}
+						testId="bucket-options-kind"
+					/>
+				</div>
+
+				{kind === Querybuildertypesv5BucketsKindDTO.log && (
+					<div className={styles.field}>
+						<span className={styles.label}>Scale</span>
+						<ToggleGroupSimple
+							type="single"
+							value={String(logScale)}
+							items={scaleItems}
+							onChange={handleScaleChange}
+							testId="bucket-options-scale"
+						/>
+					</div>
+				)}
+
+				{kind === Querybuildertypesv5BucketsKindDTO.linear && (
+					<>
+						<div className={styles.field}>
+							<span className={styles.label}>Max value</span>
+							<InputNumber
+								className={styles.numberInput}
+								min={0}
+								value={maxValue}
+								onChange={handleMaxValueChange}
+								placeholder="Required"
+								status={maxValue !== null && maxValue <= 0 ? 'error' : undefined}
+								data-testid="bucket-options-max-value"
+							/>
+						</div>
+						<div className={styles.field}>
+							<span className={styles.label}>Buckets</span>
+							<InputNumber
+								className={styles.numberInput}
+								min={1}
+								max={MAX_NUM_BUCKETS}
+								precision={0}
+								value={numBuckets}
+								onChange={handleNumBucketsChange}
+								placeholder={`Default ${DEFAULT_NUM_BUCKETS}`}
+								data-testid="bucket-options-num-buckets"
+							/>
+						</div>
+					</>
+				)}
+
+				{onClose && (
+					<Button
+						color="secondary"
+						variant="ghost"
+						size="icon"
+						aria-label="Close bucket options"
+						className={styles.closeButton}
+						prefix={<ChevronUp size={16} />}
+						onClick={onClose}
+						data-testid="bucket-options-close"
+					/>
+				)}
+			</div>
+
+			<div className={styles.bounds} data-testid="bucket-options-bounds">
+				<span className={styles.label}>
+					Bounds
+					<Tooltip title={BUCKET_KIND_HINTS[kind]} placement="top">
+						<Info size={12} className={styles.hintIcon} />
+					</Tooltip>
+				</span>
+				{bounds ? (
+					<>
+						{bounds.map((bound) => (
+							<span className={styles.bound} key={bound}>
+								{formatUpperBound(bound, unit)}
+							</span>
+						))}
+						{hasBoundsBeyondPreview(previewedOptions) && (
+							<span className={styles.muted}>…</span>
+						)}
+						<span className={cx(styles.bound, styles.overflowBound)}>+Inf</span>
+					</>
+				) : (
+					<span className={styles.muted}>Set a max value to see the bounds</span>
+				)}
+			</div>
+		</div>
+	);
+}
+
+BucketOptions.defaultProps = {
+	bucketOptions: undefined,
+	unit: undefined,
+	onClose: undefined,
+};
+
+export default BucketOptions;

frontend/src/components/QueryBuilderV2/QueryV2/QueryAddOns/BucketOptions/__tests__/utils.test.ts

@@ -0,0 +1,88 @@
+import { MAX_LOG_SCALE } from '../constants';
+import {
+	bandsPerDoublingFromScale,
+	formatUpperBound,
+	hasBoundsBeyondPreview,
+	kindOptionOf,
+	linearBuckets,
+	logBuckets,
+	previewUpperBounds,
+} from '../utils';
+
+describe('bucket option scales', () => {
+	it.each([
+		[-2, 0.25],
+		[0, 1],
+		[1, 2],
+		[2, 4],
+		[3, 8],
+		[4, 16],
+	])('scale %i is %i bands per doubling', (scale, bands) => {
+		expect(bandsPerDoublingFromScale(scale)).toBe(bands);
+	});
+});
+
+describe('kindOptionOf', () => {
+	it('reads no options as log, the server default', () => {
+		expect(kindOptionOf(undefined)).toBe('log');
+	});
+
+	it('reads the kind off the options', () => {
+		expect(kindOptionOf(logBuckets(MAX_LOG_SCALE))).toBe('log');
+		expect(kindOptionOf(linearBuckets(10, null))).toBe('linear');
+	});
+});
+
+describe('previewUpperBounds', () => {
+	it('doubles at one band per doubling', () => {
+		expect(previewUpperBounds(logBuckets(0))).toStrictEqual([
+			1, 2, 4, 8, 16, 32, 64, 128,
+		]);
+	});
+
+	it('falls back to the finest log axis when no options are set', () => {
+		const bounds = previewUpperBounds(undefined);
+
+		expect(bounds).toHaveLength(8);
+		// 16 bands per doubling: the eighth bound is 2^(7/16), still short of the first doubling.
+		expect(bounds?.[7]).toBeCloseTo(2 ** (7 / 16));
+	});
+
+	it('spaces a linear axis evenly by bucket width', () => {
+		expect(previewUpperBounds(linearBuckets(100, 10))).toStrictEqual(
+			[10, 20, 30, 40, 50, 60, 70, 80, 90, 100].slice(0, 8),
+		);
+	});
+
+	it('stops at the last bucket when the axis has fewer than the preview shows', () => {
+		expect(previewUpperBounds(linearBuckets(9, 3))).toStrictEqual([3, 6, 9]);
+	});
+
+	it('has no bounds to preview for a linear axis without a usable max value', () => {
+		expect(previewUpperBounds(linearBuckets(0, null))).toBeUndefined();
+		expect(previewUpperBounds(linearBuckets(-1, null))).toBeUndefined();
+	});
+});
+
+describe('hasBoundsBeyondPreview', () => {
+	it('is always true for a log axis, which has no top', () => {
+		expect(hasBoundsBeyondPreview(logBuckets(0))).toBe(true);
+		expect(hasBoundsBeyondPreview(undefined)).toBe(true);
+	});
+
+	it('tracks whether a linear axis runs past the preview', () => {
+		expect(hasBoundsBeyondPreview(linearBuckets(100, 4))).toBe(false);
+		expect(hasBoundsBeyondPreview(linearBuckets(100, 20))).toBe(true);
+	});
+});
+
+describe('formatUpperBound', () => {
+	it('reads a bound in the panel unit when one is set', () => {
+		expect(formatUpperBound(1, 'ms')).toContain('ms');
+	});
+
+	it('keeps three significant digits when unitless', () => {
+		expect(formatUpperBound(128, undefined)).toBe('128');
+		expect(formatUpperBound(2 ** (1 / 16), undefined)).toBe('1.04');
+	});
+});

frontend/src/components/QueryBuilderV2/QueryV2/QueryAddOns/BucketOptions/constants.ts

@@ -0,0 +1,54 @@
+import { Querybuildertypesv5BucketsKindDTO } from 'api/generated/services/sigNoz.schemas';
+
+/**
+ * Mirrors the limits `querybuildertypesv5` validates `bucketOptions` against. The
+ * builder keeps its own copy so an out-of-range axis is refused before the request
+ * rather than after it.
+ */
+
+/**
+ * A log axis spaces bounds at 2^scale bands per doubling. MaxLogScale is the
+ * resolution ClickHouse buckets at, so it is both the finest available and what an
+ * absent `bucketOptions` resolves to.
+ */
+export const MAX_LOG_SCALE = 4;
+
+/** One band per 16x, the coarsest axis worth rendering. */
+export const MIN_LOG_SCALE = -4;
+
+export const MAX_NUM_BUCKETS = 512;
+
+export const DEFAULT_NUM_BUCKETS = 60;
+
+/** Every scale the request accepts, coarsest first. The bounds strip below says
+ *  how coarse a given one is, so the numbers stand alone. */
+export const LOG_SCALES = Array.from(
+	{ length: MAX_LOG_SCALE - MIN_LOG_SCALE + 1 },
+	(_, index) => MIN_LOG_SCALE + index,
+);
+
+/** How many leading upper bounds the bounds strip previews before eliding. */
+export const PREVIEW_BOUND_COUNT = 8;
+
+export const BUCKET_KIND_OPTIONS: {
+	value: Querybuildertypesv5BucketsKindDTO;
+	label: string;
+}[] = [
+	{ value: Querybuildertypesv5BucketsKindDTO.log, label: 'Log' },
+	{ value: Querybuildertypesv5BucketsKindDTO.linear, label: 'Linear' },
+];
+
+export const LOG_SCALE_OPTIONS = LOG_SCALES.map((scale) => ({
+	value: String(scale),
+	label: String(scale),
+}));
+
+export const BUCKET_KIND_HINTS: Record<
+	Querybuildertypesv5BucketsKindDTO,
+	string
+> = {
+	[Querybuildertypesv5BucketsKindDTO.log]:
+		'Bounds are spaced evenly on a log axis, so every band is the same height on screen and the tail stays readable. A lower scale means fewer, coarser bands; scale 4, the finest, is the default.',
+	[Querybuildertypesv5BucketsKindDTO.linear]:
+		'Bounds are spaced evenly from 0 up to the max value, so a band covers the same width wherever it sits. Everything above the max value lands in a single overflow band.',
+};

frontend/src/components/QueryBuilderV2/QueryV2/QueryAddOns/BucketOptions/utils.ts

@@ -0,0 +1,120 @@
+import {
+	Querybuildertypesv5BucketOptionsDTO,
+	Querybuildertypesv5BucketOptionsLinearDTO,
+	Querybuildertypesv5BucketOptionsLinearDTOKind,
+	Querybuildertypesv5BucketOptionsLogDTO,
+	Querybuildertypesv5BucketOptionsLogDTOKind,
+	Querybuildertypesv5BucketsKindDTO,
+} from 'api/generated/services/sigNoz.schemas';
+import { getYAxisFormattedValue } from 'components/Graph/yAxisConfig';
+
+import {
+	DEFAULT_NUM_BUCKETS,
+	MAX_LOG_SCALE,
+	PREVIEW_BOUND_COUNT,
+} from './constants';
+
+export const isLinearBuckets = (
+	bucketOptions: Querybuildertypesv5BucketOptionsDTO,
+): bucketOptions is Querybuildertypesv5BucketOptionsLinearDTO =>
+	bucketOptions.kind === Querybuildertypesv5BucketOptionsLinearDTOKind.linear;
+
+export const linearBuckets = (
+	maxValue: number,
+	numBuckets: number | null,
+): Querybuildertypesv5BucketOptionsLinearDTO => ({
+	kind: Querybuildertypesv5BucketOptionsLinearDTOKind.linear,
+	spec: { maxValue, ...(numBuckets ? { numBuckets } : {}) },
+});
+
+export const logBuckets = (
+	scale: number,
+): Querybuildertypesv5BucketOptionsLogDTO => ({
+	kind: Querybuildertypesv5BucketOptionsLogDTOKind.log,
+	spec: { scale },
+});
+
+/**
+ * The log spec's scale, defaulted the way the server defaults it. A linear axis has
+ * no scale, so it reads as the default too.
+ */
+export const logScaleOf = (
+	bucketOptions: Querybuildertypesv5BucketOptionsDTO | undefined,
+): number =>
+	bucketOptions && !isLinearBuckets(bucketOptions)
+		? (bucketOptions.spec.scale ?? MAX_LOG_SCALE)
+		: MAX_LOG_SCALE;
+
+/** A log axis places `2^scale` bounds per doubling. */
+export const bandsPerDoublingFromScale = (scale: number): number => 2 ** scale;
+
+export const kindOptionOf = (
+	bucketOptions: Querybuildertypesv5BucketOptionsDTO | undefined,
+): Querybuildertypesv5BucketsKindDTO =>
+	bucketOptions && isLinearBuckets(bucketOptions)
+		? Querybuildertypesv5BucketsKindDTO.linear
+		: Querybuildertypesv5BucketsKindDTO.log;
+
+/**
+ * The leading upper bounds the axis will carry. A log axis is anchored at 1 — band
+ * index 0's boundary — and a linear one at the top of its first band; both continue
+ * past what the strip shows, and everything above the last one lands in the overflow
+ * band the UI labels separately.
+ *
+ * `undefined` for a linear axis with no max value yet: without a top there is nothing
+ * to divide.
+ */
+export function previewUpperBounds(
+	bucketOptions: Querybuildertypesv5BucketOptionsDTO | undefined,
+): number[] | undefined {
+	if (bucketOptions && isLinearBuckets(bucketOptions)) {
+		const { maxValue, numBuckets = DEFAULT_NUM_BUCKETS } = bucketOptions.spec;
+
+		if (!Number.isFinite(maxValue) || maxValue <= 0 || numBuckets <= 0) {
+			return undefined;
+		}
+
+		const width = maxValue / numBuckets;
+
+		return Array.from(
+			{ length: Math.min(numBuckets, PREVIEW_BOUND_COUNT) },
+			(_, index) => (index + 1) * width,
+		);
+	}
+
+	const bands = bandsPerDoublingFromScale(logScaleOf(bucketOptions));
+
+	return Array.from(
+		{ length: PREVIEW_BOUND_COUNT },
+		(_, index) => 2 ** (index / bands),
+	);
+}
+
+/**
+ * Whether the strip elides bounds after the ones it shows. A linear axis with no more
+ * buckets than the strip holds ends where the strip does.
+ */
+export function hasBoundsBeyondPreview(
+	bucketOptions: Querybuildertypesv5BucketOptionsDTO | undefined,
+): boolean {
+	if (!bucketOptions || !isLinearBuckets(bucketOptions)) {
+		return true;
+	}
+
+	return (
+		(bucketOptions.spec.numBuckets ?? DEFAULT_NUM_BUCKETS) > PREVIEW_BOUND_COUNT
+	);
+}
+
+/**
+ * A bound is a value on the panel's own axis, so it reads in the panel's unit when one
+ * is set. Unitless, three significant digits keep the tightly spaced bounds of a fine
+ * log axis distinguishable without printing the float in full.
+ */
+export function formatUpperBound(bound: number, unit?: string): string {
+	if (unit) {
+		return getYAxisFormattedValue(String(bound), unit);
+	}
+
+	return Number(bound.toPrecision(3)).toString();
+}

frontend/src/components/QueryBuilderV2/QueryV2/QueryAddOns/QueryAddOns.tsx

@@ -3,14 +3,21 @@ import { Button, Tooltip } from 'antd';
 import cx from 'classnames';
 import { ToggleGroupSimple } from '@signozhq/ui/toggle-group';
 import InputWithLabel from 'components/InputWithLabel/InputWithLabel';
-import { PANEL_TYPES } from 'constants/queryBuilder';
+import { ATTRIBUTE_TYPES, PANEL_TYPES } from 'constants/queryBuilder';
 import { GroupByFilter } from 'container/QueryBuilder/filters/GroupByFilter/GroupByFilter';
 import { OrderByFilter } from 'container/QueryBuilder/filters/OrderByFilter/OrderByFilter';
 import { ReduceToFilter } from 'container/QueryBuilder/filters/ReduceToFilter/ReduceToFilter';
 import { useQueryBuilder } from 'hooks/queryBuilder/useQueryBuilder';
 import { useQueryOperations } from 'hooks/queryBuilder/useQueryBuilderOperations';
 import { get, isEmpty } from 'lodash-es';
-import { BarChart, ChevronUp, ExternalLink, ScrollText } from '@signozhq/icons';
+import {
+	BarChart,
+	ChevronUp,
+	ExternalLink,
+	Grid3X3,
+	ScrollText,
+} from '@signozhq/icons';
+import { Querybuildertypesv5BucketOptionsDTO } from 'api/generated/services/sigNoz.schemas';
 import { IBuilderQuery } from 'types/api/queryBuilder/queryBuilderData';
 import { MetricAggregation } from 'types/api/v5/queryRange';
 import { DataSource, ReduceOperators } from 'types/common/queryBuilder';
@@ -25,6 +32,7 @@ import {
 	resolveQueryBuilderFields,
 } from '../../queryBuilderFields.utils';
 
+import BucketOptions from './BucketOptions/BucketOptions';
 import HavingFilter from './HavingFilter/HavingFilter';
 import { buildDefaultLegendFromGroupBy } from './utils';
 
@@ -57,6 +65,7 @@ const ADD_ONS_KEYS_TO_QUERY_PATH: Omit<
 	[QueryBuilderField.Limit]: 'limit',
 	[QueryBuilderField.Legend]: 'legend',
 	[QueryBuilderField.ReduceTo]: 'reduceTo',
+	[QueryBuilderField.BucketOptions]: 'bucketOptions',
 };
 
 const ADD_ONS: AddOn[] = [
@@ -116,6 +125,22 @@ const REDUCE_TO: AddOn = {
 		'https://signoz.io/docs/userguide/query-builder-v5/#result-manipulation',
 };
 
+// Offered only by a heatmap over metrics: the bucket axis is what a heatmap plots
+// against, and no other panel type sends one. A histogram brings its own buckets.
+const HISTOGRAM_ATTRIBUTE_TYPES = new Set<string>([
+	ATTRIBUTE_TYPES.HISTOGRAM,
+	ATTRIBUTE_TYPES.EXPONENTIAL_HISTOGRAM,
+]);
+
+const BUCKET_OPTIONS: AddOn = {
+	icon: <Grid3X3 size={14} />,
+	label: 'Bucket by',
+	key: QueryBuilderField.BucketOptions,
+	description:
+		'Choose how the bucket axis is spaced — logarithmically, so every band is the same height and the tail stays readable, or linearly up to a max value. Left to Auto, the query picks the finest log axis it can return.',
+	docLink: 'https://signoz.io/docs/userguide/query-builder-v5/',
+};
+
 const hasValue = (value: unknown): boolean =>
 	value != null && value !== '' && !(Array.isArray(value) && value.length === 0);
 
@@ -196,7 +221,7 @@ function QueryAddOns({
 		isForTraceOperator,
 	});
 
-	const { handleSetQueryData } = useQueryBuilder();
+	const { handleSetQueryData, currentQuery } = useQueryBuilder();
 
 	const supportedAddOns = useMemo((): AddOn[] => {
 		let addOns: AddOn[];
@@ -210,8 +235,25 @@ function QueryAddOns({
 			addOns = [...ADD_ONS];
 		}
 
-		return showReduceTo ? [...addOns, REDUCE_TO] : addOns;
-	}, [panelType, query.dataSource, showReduceTo]);
+		if (showReduceTo) {
+			addOns = [...addOns, REDUCE_TO];
+		}
+
+		if (
+			panelType === PANEL_TYPES.HEATMAP &&
+			query.dataSource === DataSource.METRICS &&
+			!HISTOGRAM_ATTRIBUTE_TYPES.has(query.aggregateAttribute?.type ?? '')
+		) {
+			addOns = [...addOns, BUCKET_OPTIONS];
+		}
+
+		return addOns;
+	}, [
+		panelType,
+		query.dataSource,
+		query.aggregateAttribute?.type,
+		showReduceTo,
+	]);
 
 	const resolvedFields = useMemo(
 		() =>
@@ -392,6 +434,13 @@ function QueryAddOns({
 		[handleChangeQueryData],
 	);
 
+	const handleChangeBucketOptions = useCallback(
+		(value: Querybuildertypesv5BucketOptionsDTO | undefined) => {
+			handleChangeQueryData('bucketOptions', value);
+		},
+		[handleChangeQueryData],
+	);
+
 	return (
 		<div className="query-add-ons" data-testid="query-add-ons">
 			{selectedViews.length > 0 && (
@@ -559,6 +608,19 @@ function QueryAddOns({
 							/>
 						</div>
 					)}
+
+					{selectedViews.find(
+						(view) => view.key === QueryBuilderField.BucketOptions,
+					) && (
+						<div className="add-on-content" data-testid="bucket-options-content">
+							<BucketOptions
+								bucketOptions={query.bucketOptions}
+								unit={currentQuery.unit}
+								onChange={handleChangeBucketOptions}
+								onClose={(): void => handleRemoveView(QueryBuilderField.BucketOptions)}
+							/>
+						</div>
+					)}
 				</div>
 			)}
 

frontend/src/components/QueryBuilderV2/__tests__/QueryAddOns.test.tsx

@@ -1,4 +1,4 @@
-import { PANEL_TYPES } from 'constants/queryBuilder';
+import { ATTRIBUTE_TYPES, PANEL_TYPES } from 'constants/queryBuilder';
 import {
 	fireEvent,
 	render,
@@ -26,8 +26,10 @@ jest.mock('hooks/queryBuilder/useQueryBuilderOperations', () => ({
 jest.mock('hooks/queryBuilder/useQueryBuilder', () => ({
 	useQueryBuilder: (): {
 		handleSetQueryData: typeof mockHandleSetQueryData;
+		currentQuery: { unit: string | undefined };
 	} => ({
 		handleSetQueryData: mockHandleSetQueryData,
+		currentQuery: { unit: undefined },
 	}),
 }));
 
@@ -330,4 +332,175 @@ describe('QueryAddOns', () => {
 			expect.anything(),
 		);
 	});
+	describe('bucket options', () => {
+		function renderHeatmap(overrides: Partial<any> = {}): void {
+			render(
+				<QueryAddOns
+					query={baseQuery({ dataSource: DataSource.METRICS, ...overrides })}
+					version="v5"
+					isRawQuery={false}
+					showReduceTo={false}
+					panelType={PANEL_TYPES.HEATMAP}
+					index={0}
+					isForTraceOperator={false}
+				/>,
+			);
+		}
+
+		it('is offered on a metrics heatmap only', () => {
+			renderHeatmap();
+
+			expect(
+				screen.getByTestId('query-add-on-bucket_options'),
+			).toBeInTheDocument();
+		});
+
+		it('is not offered on other panel types', () => {
+			render(
+				<QueryAddOns
+					query={baseQuery({ dataSource: DataSource.METRICS })}
+					version="v5"
+					isRawQuery={false}
+					showReduceTo={false}
+					panelType={PANEL_TYPES.TIME_SERIES}
+					index={0}
+					isForTraceOperator={false}
+				/>,
+			);
+
+			expect(
+				screen.queryByTestId('query-add-on-bucket_options'),
+			).not.toBeInTheDocument();
+		});
+
+		it('is not offered on a heatmap over another signal', () => {
+			render(
+				<QueryAddOns
+					query={baseQuery({ dataSource: DataSource.LOGS })}
+					version="v5"
+					isRawQuery={false}
+					showReduceTo={false}
+					panelType={PANEL_TYPES.HEATMAP}
+					index={0}
+					isForTraceOperator={false}
+				/>,
+			);
+
+			expect(
+				screen.queryByTestId('query-add-on-bucket_options'),
+			).not.toBeInTheDocument();
+		});
+
+		it.each([ATTRIBUTE_TYPES.HISTOGRAM, ATTRIBUTE_TYPES.EXPONENTIAL_HISTOGRAM])(
+			'is not offered for a %s metric, which carries its own buckets',
+			(type) => {
+				renderHeatmap({
+					aggregateAttribute: { key: 'http_duration_bucket', type },
+				});
+
+				expect(
+					screen.queryByTestId('query-add-on-bucket_options'),
+				).not.toBeInTheDocument();
+			},
+		);
+
+		it("auto-opens on the query's own kind", () => {
+			renderHeatmap({ bucketOptions: { kind: 'log', spec: { scale: 0 } } });
+
+			expect(screen.getByTestId('bucket-options-content')).toBeInTheDocument();
+			expect(screen.getByRole('radio', { name: 'Log' })).toBeChecked();
+			expect(screen.getByRole('radio', { name: '0' })).toBeChecked();
+		});
+
+		it('shows the server default, log at scale 4, without sending it', async () => {
+			const user = userEvent.setup();
+			renderHeatmap();
+
+			await user.click(screen.getByTestId('query-add-on-bucket_options'));
+
+			expect(screen.getByRole('radio', { name: 'Log' })).toBeChecked();
+			expect(screen.getByRole('radio', { name: '4' })).toBeChecked();
+			expect(
+				screen.queryByRole('radio', { name: 'Auto' }),
+			).not.toBeInTheDocument();
+			expect(mockHandleChangeQueryData).not.toHaveBeenCalledWith(
+				'bucketOptions',
+				expect.anything(),
+			);
+		});
+
+		it('sends the picked scale', async () => {
+			const user = userEvent.setup();
+			renderHeatmap({ bucketOptions: { kind: 'log', spec: { scale: 4 } } });
+
+			await user.click(screen.getByRole('radio', { name: '0' }));
+
+			expect(mockHandleChangeQueryData).toHaveBeenCalledWith('bucketOptions', {
+				kind: 'log',
+				spec: { scale: 0 },
+			});
+		});
+
+		it('offers the coarser scales the request accepts below one band per doubling', async () => {
+			const user = userEvent.setup();
+			renderHeatmap({ bucketOptions: { kind: 'log', spec: { scale: 0 } } });
+
+			await user.click(screen.getByRole('radio', { name: '-4' }));
+
+			expect(mockHandleChangeQueryData).toHaveBeenCalledWith('bucketOptions', {
+				kind: 'log',
+				spec: { scale: -4 },
+			});
+		});
+
+		it('previews the bounds the picked axis will carry', () => {
+			renderHeatmap({ bucketOptions: { kind: 'log', spec: { scale: 0 } } });
+
+			const bounds = within(screen.getByTestId('bucket-options-bounds'));
+			['1', '2', '4', '8', '16', '32', '64', '128', '+Inf'].forEach((bound) => {
+				expect(bounds.getByText(bound)).toBeInTheDocument();
+			});
+		});
+
+		it('sends nothing for a linear axis until it has a max value', async () => {
+			const user = userEvent.setup();
+			renderHeatmap({ bucketOptions: { kind: 'log', spec: { scale: 0 } } });
+
+			await user.click(screen.getByRole('radio', { name: 'Linear' }));
+
+			expect(mockHandleChangeQueryData).toHaveBeenLastCalledWith(
+				'bucketOptions',
+				undefined,
+			);
+			expect(
+				screen.getByText('Set a max value to see the bounds'),
+			).toBeInTheDocument();
+		});
+
+		it('sends the linear axis once a max value is filled in', async () => {
+			const user = userEvent.setup();
+			renderHeatmap({ bucketOptions: { kind: 'log', spec: { scale: 0 } } });
+
+			await user.click(screen.getByRole('radio', { name: 'Linear' }));
+			await user.type(screen.getByTestId('bucket-options-max-value'), '500');
+
+			await waitFor(() => {
+				expect(mockHandleChangeQueryData).toHaveBeenLastCalledWith(
+					'bucketOptions',
+					{ kind: 'linear', spec: { maxValue: 500 } },
+				);
+			});
+		});
+
+		it('closes back to the toggle bar', async () => {
+			const user = userEvent.setup();
+			renderHeatmap({ bucketOptions: { kind: 'log', spec: { scale: 0 } } });
+
+			await user.click(screen.getByTestId('bucket-options-close'));
+
+			expect(
+				screen.queryByTestId('bucket-options-content'),
+			).not.toBeInTheDocument();
+		});
+	});
 });

frontend/src/components/QueryBuilderV2/queryBuilderFields.types.ts

@@ -16,6 +16,7 @@ export enum QueryBuilderField {
 	Limit = 'limit',
 	Legend = 'legend_format',
 	ReduceTo = 'reduce_to',
+	BucketOptions = 'bucket_options',
 	// Builder level
 	Formula = 'formula',
 	AdditionalQueries = 'additional_queries',

frontend/src/components/QueryBuilderV2/queryBuilderFields.utils.ts

@@ -76,6 +76,7 @@ export const RAW_QUERY_FIELDS: Omit<
 	[QueryBuilderField.Limit]: { state: 'hidden' },
 	[QueryBuilderField.Legend]: { state: 'hidden' },
 	[QueryBuilderField.ReduceTo]: { state: 'hidden' },
+	[QueryBuilderField.BucketOptions]: { state: 'hidden' },
 	[QueryBuilderField.Formula]: { state: 'hidden' },
 	[QueryBuilderField.OrderBy]: { state: 'pinned' },
 };

frontend/src/components/QuickFilters/QuickFilters.styles.scss

@@ -12,6 +12,7 @@
 		overflow: visible;
 		position: relative;
 		align-self: stretch;
+		clip-path: inset(0 -100vw 0 0);
 	}
 }
 

frontend/src/components/QuickFilters/QuickFilters.tsx

@@ -57,6 +57,7 @@ export default function QuickFilters(props: IQuickFiltersProps): JSX.Element {
 		showFilterCollapse = true,
 		showQueryName = true,
 		useFieldApis,
+		savedViewsHeader,
 	} = props;
 	const [isSettingsOpen, setIsSettingsOpen] = useState(false);
 	const [params, setParams] = useApiMonitoringParams();
@@ -379,6 +380,7 @@ export default function QuickFilters(props: IQuickFiltersProps): JSX.Element {
 	return (
 		<div className="quick-filters-container">
 			<div className="quick-filters">
+				{savedViewsHeader}
 				{source !== QuickFiltersSource.INFRA_MONITORING && (
 					<section className="header">
 						{renderLeftActions()}

frontend/src/components/QuickFilters/QuickFiltersLayout/QuickFiltersLayout.module.scss

@@ -8,9 +8,7 @@
 	overflow: hidden;
 }
 
-// Positioned so overlays (settings drawer) paint above the content pane
-// without changing this pane's layout width.
-.filters {
+.sidebar {
 	width: 280px;
 	flex-shrink: 0;
 	display: flex;
@@ -21,6 +19,44 @@
 	z-index: 2;
 }
 
+.savedViews {
+	flex: 1;
+	min-height: 0;
+	display: flex;
+	flex-direction: column;
+	background: var(--l1-background);
+	border-right: 1px solid var(--l1-border);
+}
+
+.quickFilters {
+	position: absolute;
+	inset: 0;
+	display: flex;
+	flex-direction: column;
+	min-height: 0;
+	background: var(--l1-background);
+	transition: transform 0.2s ease-in-out;
+	z-index: 1;
+
+	&.isOpen {
+		transform: translateX(100%);
+	}
+}
+
+// No quick filters: the header sits in flow and the list stays under it
+.isStatic {
+	border-right: 1px solid var(--l1-border);
+
+	.quickFilters {
+		position: static;
+		flex-shrink: 0;
+	}
+
+	.savedViews {
+		border-right: 0;
+	}
+}
+
 // Bounded box for the OverlayScrollbar inside it (`.overlay-scrollbar` is
 // `height: 100%`), which owns the scrolling.
 .content {
@@ -31,3 +67,7 @@
 	flex-direction: column;
 	overflow: hidden;
 }
+
+.contentInner {
+	height: 100%;
+}

frontend/src/components/QuickFilters/QuickFiltersLayout/QuickFiltersLayout.tsx

@@ -1,6 +1,9 @@
-import { ComponentProps, ReactNode } from 'react';
+import { ComponentProps, ReactNode, useState } from 'react';
 import cx from 'classnames';
 import OverlayScrollbar from 'components/OverlayScrollbar/OverlayScrollbar';
+import SavedViewsHeader from 'container/SavedViews/SavedViewsHeader';
+import SavedViewsPanel from 'container/SavedViews/SavedViewsPanel';
+import { useSavedViewEnabled } from 'hooks/useSavedViewEnabled';
 
 import QuickFilters from '../QuickFilters';
 
@@ -12,8 +15,15 @@ type QuickFiltersElementProps = JSX.LibraryManagedAttributes<
 	ComponentProps<typeof QuickFilters>
 >;
 
+// What the page configures; the layout adds the open / close wiring.
+type SavedViewsElementProps = Omit<
+	ComponentProps<typeof SavedViewsPanel>,
+	'onClose'
+>;
+
 export interface QuickFiltersLayoutProps {
-	quickFilterProps: QuickFiltersElementProps;
+	quickFilterProps?: QuickFiltersElementProps;
+	savedViewProps?: SavedViewsElementProps;
 	showFilters: boolean;
 	className?: string;
 	contentClassName?: string;
@@ -23,20 +33,60 @@ export interface QuickFiltersLayoutProps {
 
 function QuickFiltersLayout({
 	quickFilterProps,
+	savedViewProps,
 	showFilters,
 	className,
 	contentClassName,
 	testId,
 	children,
 }: QuickFiltersLayoutProps): JSX.Element {
+	const [isViewsOpen, setIsViewsOpen] = useState(false);
+	const isSavedViewEnabled = useSavedViewEnabled();
+
+	const hasQuickFilters = !!quickFilterProps;
+	const hasSavedViews = !!savedViewProps && isSavedViewEnabled;
+
+	const showSidebar = showFilters && (hasQuickFilters || hasSavedViews);
+
+	const isPanelPinned = hasSavedViews && !hasQuickFilters;
+
+	const isSliding = hasQuickFilters && isViewsOpen;
+
+	const savedViewsHeader = hasSavedViews ? (
+		<SavedViewsHeader
+			{...savedViewProps}
+			onOpenViews={isPanelPinned ? undefined : (): void => setIsViewsOpen(true)}
+		/>
+	) : undefined;
+
 	return (
 		<div className={cx(styles.layout, className)} data-testid={testId}>
-			{showFilters && (
+			{showSidebar && (
 				<aside
-					className={styles.filters}
+					className={cx(styles.sidebar, { [styles.isStatic]: !hasQuickFilters })}
 					data-testid="quick-filters-layout-filters"
 				>
-					<QuickFilters {...quickFilterProps} />
+					<div
+						className={cx(styles.quickFilters, { [styles.isOpen]: isSliding })}
+						data-testid="quick-filters-layout-drawer"
+					>
+						{hasQuickFilters ? (
+							<QuickFilters
+								{...quickFilterProps}
+								savedViewsHeader={savedViewsHeader}
+							/>
+						) : (
+							savedViewsHeader
+						)}
+					</div>
+					<div className={styles.savedViews}>
+						{hasSavedViews && (isPanelPinned || isViewsOpen) && (
+							<SavedViewsPanel
+								{...savedViewProps}
+								onClose={isPanelPinned ? undefined : (): void => setIsViewsOpen(false)}
+							/>
+						)}
+					</div>
 				</aside>
 			)}
 			<section
@@ -44,7 +94,7 @@ function QuickFiltersLayout({
 				data-testid="quick-filters-layout-content"
 			>
 				<OverlayScrollbar>
-					<div>{children}</div>
+					<div className={styles.contentInner}>{children}</div>
 				</OverlayScrollbar>
 			</section>
 		</div>

frontend/src/components/QuickFilters/QuickFiltersLayout/__tests__/QuickFiltersLayout.test.tsx

@@ -1,4 +1,6 @@
-import { render, screen } from 'tests/test-utils';
+import { SavedviewtypesSourceDTO } from 'api/generated/services/sigNoz.schemas';
+import { useSavedViewEnabled } from 'hooks/useSavedViewEnabled';
+import { render, screen, userEvent } from 'tests/test-utils';
 
 import { QuickFiltersSource } from '../../types';
 import QuickFiltersLayout from '../QuickFiltersLayout';
@@ -7,15 +9,33 @@ jest.mock('../QuickFiltersLayout.module.scss', () => ({
 	__esModule: true,
 	default: {
 		layout: 'layout',
-		filters: 'filters',
+		sidebar: 'sidebar',
+		isStatic: 'isStatic',
+		savedViews: 'savedViews',
+		quickFilters: 'quickFilters',
+		isOpen: 'isOpen',
 		content: 'content',
+		contentInner: 'contentInner',
 	},
 }));
 
+jest.mock('hooks/useSavedViewEnabled', () => ({
+	useSavedViewEnabled: jest.fn(() => true),
+}));
+
 jest.mock('../../QuickFilters', () => ({
 	__esModule: true,
-	default: ({ source }: { source: string }): JSX.Element => (
-		<div data-testid="quick-filters">{source}</div>
+	default: ({
+		source,
+		savedViewsHeader,
+	}: {
+		source: string;
+		savedViewsHeader?: React.ReactNode;
+	}): JSX.Element => (
+		<div data-testid="quick-filters">
+			{savedViewsHeader}
+			{source}
+		</div>
 	),
 }));
 
@@ -23,8 +43,16 @@ const quickFilterProps = {
 	source: QuickFiltersSource.TRACES_EXPLORER,
 	handleFilterVisibilityChange: jest.fn(),
 };
+const savedViewProps = { source: SavedviewtypesSourceDTO.traces };
+
+const drawer = (): HTMLElement =>
+	screen.getByTestId('quick-filters-layout-drawer');
 
 describe('QuickFiltersLayout', () => {
+	beforeEach(() => {
+		jest.mocked(useSavedViewEnabled).mockReturnValue(true);
+	});
+
 	it('renders QuickFilters with the given props inside the filters pane', () => {
 		render(
 			<QuickFiltersLayout showFilters quickFilterProps={quickFilterProps}>
@@ -40,11 +68,16 @@ describe('QuickFiltersLayout', () => {
 		expect(screen.getByTestId('quick-filters-layout-content')).toHaveTextContent(
 			'content',
 		);
+		expect(screen.queryByTestId('saved-views-header')).not.toBeInTheDocument();
 	});
 
 	it('does not render the filters pane when showFilters is false', () => {
 		render(
-			<QuickFiltersLayout showFilters={false} quickFilterProps={quickFilterProps}>
+			<QuickFiltersLayout
+				showFilters={false}
+				quickFilterProps={quickFilterProps}
+				savedViewProps={savedViewProps}
+			>
 				<div>content</div>
 			</QuickFiltersLayout>,
 		);
@@ -56,24 +89,138 @@ describe('QuickFiltersLayout', () => {
 		expect(screen.getByText('content')).toBeInTheDocument();
 	});
 
+	it('renders no sidebar at all without quick filters or saved views', () => {
+		render(
+			<QuickFiltersLayout showFilters>
+				<div>content</div>
+			</QuickFiltersLayout>,
+		);
+
+		expect(
+			screen.queryByTestId('quick-filters-layout-filters'),
+		).not.toBeInTheDocument();
+		expect(screen.getByText('content')).toBeInTheDocument();
+	});
+
 	it('merges classNames onto the root and content panes', () => {
 		render(
 			<QuickFiltersLayout
 				showFilters
 				quickFilterProps={quickFilterProps}
-				className="page-root"
-				contentClassName="page-content"
-				testId="page"
+				className="root-extra"
+				contentClassName="content-extra"
+				testId="layout"
 			>
 				<div>content</div>
 			</QuickFiltersLayout>,
 		);
 
-		const root = screen.getByTestId('page');
-		expect(root).toHaveClass('layout', 'page-root');
+		expect(screen.getByTestId('layout')).toHaveClass('layout', 'root-extra');
 		expect(screen.getByTestId('quick-filters-layout-content')).toHaveClass(
 			'content',
-			'page-content',
+			'content-extra',
 		);
 	});
+
+	describe('saved views', () => {
+		it('ignores savedViewProps while the flag is off', () => {
+			jest.mocked(useSavedViewEnabled).mockReturnValue(false);
+			const { unmount } = render(
+				<QuickFiltersLayout
+					showFilters
+					quickFilterProps={quickFilterProps}
+					savedViewProps={savedViewProps}
+				>
+					<div>content</div>
+				</QuickFiltersLayout>,
+			);
+
+			expect(screen.getByTestId('quick-filters')).toBeInTheDocument();
+			expect(screen.queryByTestId('saved-views-header')).not.toBeInTheDocument();
+			expect(screen.queryByTestId('saved-views-panel')).not.toBeInTheDocument();
+
+			// Saved views only, so nothing is left to show.
+			unmount();
+			render(
+				<QuickFiltersLayout showFilters savedViewProps={savedViewProps}>
+					<div>content</div>
+				</QuickFiltersLayout>,
+			);
+			expect(
+				screen.queryByTestId('quick-filters-layout-filters'),
+			).not.toBeInTheDocument();
+		});
+
+		it('opens the panel from the header and slides the quick filters drawer, keeping the same QuickFilters node', async () => {
+			render(
+				<QuickFiltersLayout
+					showFilters
+					quickFilterProps={quickFilterProps}
+					savedViewProps={savedViewProps}
+				>
+					<div>content</div>
+				</QuickFiltersLayout>,
+			);
+			const user = userEvent.setup();
+			const quickFilters = screen.getByTestId('quick-filters');
+
+			expect(quickFilters).toContainElement(
+				screen.getByTestId('saved-views-header'),
+			);
+			expect(drawer()).toContainElement(quickFilters);
+			expect(screen.queryByTestId('saved-views-panel')).not.toBeInTheDocument();
+			expect(drawer()).not.toHaveClass('isOpen');
+
+			await user.click(screen.getByTestId('saved-views-open'));
+
+			expect(screen.getByTestId('saved-views-panel')).toBeInTheDocument();
+			expect(drawer()).toHaveClass('isOpen');
+			expect(screen.getByTestId('quick-filters')).toBe(quickFilters);
+
+			await user.click(screen.getByTestId('saved-views-close'));
+
+			expect(screen.queryByTestId('saved-views-panel')).not.toBeInTheDocument();
+			expect(drawer()).not.toHaveClass('isOpen');
+			expect(screen.getByTestId('quick-filters')).toBe(quickFilters);
+		});
+
+		it('hands the source to the header and the panel', async () => {
+			render(
+				<QuickFiltersLayout
+					showFilters
+					quickFilterProps={quickFilterProps}
+					savedViewProps={savedViewProps}
+				>
+					<div>content</div>
+				</QuickFiltersLayout>,
+			);
+
+			expect(screen.getByTestId('saved-views-header')).toHaveAttribute(
+				'data-source',
+				SavedviewtypesSourceDTO.traces,
+			);
+			await userEvent.setup().click(screen.getByTestId('saved-views-open'));
+			expect(screen.getByTestId('saved-views-panel')).toHaveAttribute(
+				'data-source',
+				SavedviewtypesSourceDTO.traces,
+			);
+		});
+
+		it('without quick filters: static sidebar, header on top, list always on screen with no open or close controls', () => {
+			render(
+				<QuickFiltersLayout showFilters savedViewProps={savedViewProps}>
+					<div>content</div>
+				</QuickFiltersLayout>,
+			);
+
+			const sidebar = screen.getByTestId('quick-filters-layout-filters');
+			expect(sidebar).toHaveClass('isStatic');
+			expect(screen.queryByTestId('quick-filters')).not.toBeInTheDocument();
+			expect(screen.getByTestId('saved-views-header')).toBeInTheDocument();
+			expect(screen.getByTestId('saved-views-panel')).toBeInTheDocument();
+			expect(screen.queryByTestId('saved-views-open')).not.toBeInTheDocument();
+			expect(screen.queryByTestId('saved-views-close')).not.toBeInTheDocument();
+			expect(drawer()).not.toHaveClass('isOpen');
+		});
+	});
 });

frontend/src/components/QuickFilters/QuickFiltersSettings/QuickFiltersSettings.styles.scss

@@ -8,12 +8,20 @@
 	width: 342px;
 	height: 100%;
 	background: var(--l1-background);
-	transition: width 0.05s ease-in-out;
+	border-right: 1px solid var(--l1-border);
 	overflow: hidden;
 	color: var(--l1-foreground);
+	transition:
+		transform 0.2s ease-in-out,
+		visibility 0s;
 
 	&.hidden {
-		width: 0;
+		transform: translateX(-100%);
+		visibility: hidden;
+		pointer-events: none;
+		transition:
+			transform 0.2s ease-in-out,
+			visibility 0s 0.2s;
 	}
 	.qf-header {
 		display: flex;

frontend/src/components/QuickFilters/types.ts

@@ -1,3 +1,4 @@
+import { ReactNode } from 'react';
 import { BaseAutocompleteData } from 'types/api/queryBuilder/queryAutocompleteResponse';
 import { Query } from 'types/api/queryBuilder/queryBuilderData';
 import { DataSource } from 'types/common/queryBuilder';
@@ -61,6 +62,7 @@ export interface IQuickFiltersProps {
 	showFilterCollapse?: boolean;
 	showQueryName?: boolean;
 	useFieldApis?: QuickFilterCheckboxUseFieldApis;
+	savedViewsHeader?: ReactNode;
 }
 
 export enum QuickFiltersSource {

frontend/src/constants/generated/semconvFamilies.gen.ts

@@ -1,32 +1,82 @@
 // Code generated by scripts/semconv. DO NOT EDIT.
 
-export type SemconvFamily = {
-	readonly current: string;
-	readonly old: readonly string[];
-	readonly kind: 'attribute' | 'metric';
+// An empty contexts/signals/applyToMetrics array places no constraint on
+// that axis.
+export type SemconvMember = {
+	readonly name: string;
 	readonly contexts: readonly string[];
 	readonly signals: readonly string[];
 	readonly applyToMetrics: readonly string[];
+};
+
+export type SemconvFamily = {
+	readonly current: string;
+	readonly kind: 'attribute' | 'metric';
+	readonly members: readonly SemconvMember[];
+	readonly contexts: readonly string[];
+	readonly signals: readonly string[];
 	readonly valueMap: Readonly<Record<string, string>>;
 };
 
 export const SEMCONV_FAMILIES: readonly SemconvFamily[] = [
 	{
-		current: 'db.system.name',
-		old: ['db.system'],
-		kind: 'attribute',
+		current: 'container.cpu.usage',
+		kind: 'metric',
+		members: [
+			{
+				name: 'container.cpu.utilization',
+				contexts: [],
+				signals: [],
+				applyToMetrics: [],
+			},
+		],
 		contexts: [],
 		signals: [],
-		applyToMetrics: [],
 		valueMap: {},
 	},
 	{
 		current: 'deployment.environment.name',
-		old: ['deployment.environment'],
 		kind: 'attribute',
+		members: [
+			{
+				name: 'deployment.environment',
+				contexts: [],
+				signals: [],
+				applyToMetrics: [],
+			},
+		],
+		contexts: ['attribute', 'resource'],
+		signals: ['logs', 'metrics', 'traces'],
+		valueMap: {},
+	},
+	{
+		current: 'k8s.node.cpu.usage',
+		kind: 'metric',
+		members: [
+			{
+				name: 'k8s.node.cpu.utilization',
+				contexts: [],
+				signals: [],
+				applyToMetrics: [],
+			},
+		],
+		contexts: [],
+		signals: [],
+		valueMap: {},
+	},
+	{
+		current: 'k8s.pod.cpu.usage',
+		kind: 'metric',
+		members: [
+			{
+				name: 'k8s.pod.cpu.utilization',
+				contexts: [],
+				signals: [],
+				applyToMetrics: [],
+			},
+		],
 		contexts: [],
 		signals: [],
-		applyToMetrics: [],
 		valueMap: {},
 	},
 ] as const;

frontend/src/constants/panelTypes.ts

@@ -32,6 +32,8 @@ export const getComponentForPanelType = (
 		[PANEL_TYPES.AREA]: Uplot,
 		[PANEL_TYPES.PIE]: null,
 		[PANEL_TYPES.HISTOGRAM]: Uplot,
+		// V2-only kind; it renders through the V2 panel registry.
+		[PANEL_TYPES.HEATMAP]: null,
 		// Dashboards v2 renders this kind; nothing reaches the V1 chart map for it.
 		[PANEL_TYPES.TEXT]: null,
 		[PANEL_TYPES.EMPTY_WIDGET]: null,

frontend/src/constants/queryBuilder.ts

@@ -339,6 +339,7 @@ export enum PANEL_TYPES {
 	AREA = 'area',
 	PIE = 'pie',
 	HISTOGRAM = 'histogram',
+	HEATMAP = 'heatmap',
 	TEXT = 'text',
 	EMPTY_WIDGET = 'EMPTY_WIDGET',
 }

frontend/src/constants/queryBuilderOperators.ts

@@ -527,6 +527,21 @@ export const metricsHistogramSpaceAggregateOperatorOptions: SelectOption<
 	},
 ];
 
+/**
+ * A heatmap's Y axis is the `le` labels themselves, so every percentile draws the grid a
+ * count already draws. Sum is also what the statement builder forces on a histogram
+ * heatmap whatever is asked for, so it is the only honest option to offer.
+ */
+export const metricsHeatmapHistogramSpaceAggregateOperatorOptions: SelectOption<
+	string,
+	string
+>[] = [
+	{
+		value: MetricAggregateOperator.COUNT,
+		label: 'Count',
+	},
+];
+
 export const metricsEmptyTimeAggregateOperatorOptions: SelectOption<
 	string,
 	string

frontend/src/container/AllError/__tests__/useExceptionsStripInfo.test.tsx

@@ -0,0 +1,53 @@
+import { renderHook } from '@testing-library/react';
+import { useBottomStripStore } from 'container/BottomStrip/store/useBottomStripStore';
+import { StripItemKind } from 'container/BottomStrip/types';
+
+import { useExceptionsStripInfo } from '../useExceptionsStripInfo';
+
+describe('useExceptionsStripInfo', () => {
+	beforeEach(() => {
+		useBottomStripStore.setState({ left: null, ownerId: null });
+	});
+
+	it('shows the rows on the page against the total', () => {
+		renderHook(() => useExceptionsStripInfo({ shownCount: 25, totalCount: 500 }));
+
+		expect(useBottomStripStore.getState().left).toMatchObject([
+			{ kind: StripItemKind.Text, text: '25 of 500 exceptions' },
+		]);
+	});
+
+	it('still says n of m when the whole list fits on one page', () => {
+		renderHook(() => useExceptionsStripInfo({ shownCount: 42, totalCount: 42 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '42 of 42 exceptions',
+		});
+	});
+
+	it('says exception, not exceptions, when there is one', () => {
+		renderHook(() => useExceptionsStripInfo({ shownCount: 1, totalCount: 1 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '1 of 1 exception',
+		});
+	});
+
+	it('shows zero before the counts land', () => {
+		renderHook(() => useExceptionsStripInfo({ shownCount: 0, totalCount: 0 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '0 of 0 exceptions',
+		});
+	});
+
+	it('clears the strip when the page unmounts', () => {
+		const { unmount } = renderHook(() =>
+			useExceptionsStripInfo({ shownCount: 25, totalCount: 500 }),
+		);
+
+		unmount();
+
+		expect(useBottomStripStore.getState().left).toBeNull();
+	});
+});

frontend/src/container/AllError/index.tsx

@@ -38,6 +38,7 @@ import { Exception, PayloadProps } from 'types/api/errors/getAll';
 import { GlobalReducer } from 'types/reducer/globalTime';
 
 import { FilterDropdownExtendsProps } from './types';
+import { useExceptionsStripInfo } from './useExceptionsStripInfo';
 import {
 	extractFilterValues,
 	getDefaultFilterValue,
@@ -160,6 +161,11 @@ function AllErrors(): JSX.Element {
 			},
 		]);
 
+	useExceptionsStripInfo({
+		shownCount: data?.payload?.length ?? 0,
+		totalCount: errorCountResponse.data?.payload ?? 0,
+	});
+
 	const isFetching = isErrorsFetching || errorCountResponse.isFetching;
 	useEffect(() => {
 		setIsFetching(isFetching);

frontend/src/container/AllError/useExceptionsStripInfo.ts

@@ -0,0 +1,26 @@
+import { useMemo } from 'react';
+import { useBottomStrip } from 'container/BottomStrip/useBottomStrip';
+import { type StripItem, StripItemKind } from 'container/BottomStrip/types';
+import { pluralize } from 'utils/pluralize';
+
+interface UseExceptionsStripInfoArgs {
+	shownCount: number;
+	totalCount: number;
+}
+
+export function useExceptionsStripInfo({
+	shownCount,
+	totalCount,
+}: UseExceptionsStripInfoArgs): void {
+	const items = useMemo<StripItem[]>(
+		() => [
+			{
+				kind: StripItemKind.Text,
+				text: `${shownCount} of ${pluralize(totalCount, 'exception')}`,
+			},
+		],
+		[shownCount, totalCount],
+	);
+
+	useBottomStrip(items);
+}

frontend/src/container/AppLayout/index.tsx

@@ -854,7 +854,9 @@ function AppLayout(props: AppLayoutProps): JSX.Element {
 					<ChangelogModal changelog={changelog} onClose={toggleChangelogModal} />
 				)}
 
-				<Toaster />
+				<Toaster
+					offset={{ bottom: 'calc(var(--bottom-strip-height, 0px) + 24px)' }}
+				/>
 			</Layout>
 		</TooltipProvider>
 	);

frontend/src/container/CreateAlertV2/Footer/__tests__/utils.test.ts

@@ -467,6 +467,7 @@ describe('Footer utils', () => {
 											timeAggregation: 'avg',
 										},
 									],
+									bucketOptions: undefined,
 									disabled: false,
 									filter: {
 										expression: '',

frontend/src/container/Home/Home.tsx

@@ -26,6 +26,7 @@ import { initialQueriesMap, PANEL_TYPES } from 'constants/queryBuilder';
 import { REACT_QUERY_KEY } from 'constants/reactQueryKeys';
 import ROUTES from 'constants/routes';
 import { DEFAULT_TIME_RANGE } from 'container/TopNav/DateTimeSelectionV2/constants';
+import { useHomeStripInfo } from 'container/Home/useHomeStripInfo';
 import { useGetQueryRange } from 'hooks/queryBuilder/useGetQueryRange';
 import { useIsDarkMode } from 'hooks/useDarkMode';
 import { useSafeNavigate } from 'hooks/useSafeNavigate';
@@ -64,6 +65,8 @@ const homeInterval = 30 * 60 * 1000;
 
 // eslint-disable-next-line sonarjs/cognitive-complexity
 export default function Home(): JSX.Element {
+	useHomeStripInfo();
+
 	const { user } = useAppContext();
 	const { safeNavigate } = useSafeNavigate();
 	const isDarkMode = useIsDarkMode();

frontend/src/container/Home/__tests__/useHomeStripInfo.test.tsx

@@ -0,0 +1,58 @@
+import { renderHook } from '@testing-library/react';
+import { useGetAlerts } from 'api/generated/services/alerts';
+import { useBottomStripStore } from 'container/BottomStrip/store/useBottomStripStore';
+import { StripItemKind } from 'container/BottomStrip/types';
+
+import { useHomeStripInfo } from '../useHomeStripInfo';
+
+jest.mock('api/generated/services/alerts', () => ({
+	useGetAlerts: jest.fn(),
+}));
+
+const mockUseGetAlerts = useGetAlerts as jest.Mock;
+
+describe('useHomeStripInfo', () => {
+	beforeEach(() => {
+		useBottomStripStore.setState({ left: null, ownerId: null });
+	});
+
+	it('counts the firing alert instances', () => {
+		mockUseGetAlerts.mockReturnValue({ data: { data: [{}, {}, {}] } });
+
+		renderHook(() => useHomeStripInfo());
+
+		expect(useBottomStripStore.getState().left).toMatchObject([
+			{ kind: StripItemKind.Text, text: '3 alerts firing' },
+		]);
+	});
+
+	it('says alert, not alerts, when only one is firing', () => {
+		mockUseGetAlerts.mockReturnValue({ data: { data: [{}] } });
+
+		renderHook(() => useHomeStripInfo());
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '1 alert firing',
+		});
+	});
+
+	it('shows zero before the response lands', () => {
+		mockUseGetAlerts.mockReturnValue({ data: undefined });
+
+		renderHook(() => useHomeStripInfo());
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '0 alerts firing',
+		});
+	});
+
+	it('clears the strip when the page unmounts', () => {
+		mockUseGetAlerts.mockReturnValue({ data: { data: [{}, {}, {}] } });
+
+		const { unmount } = renderHook(() => useHomeStripInfo());
+
+		unmount();
+
+		expect(useBottomStripStore.getState().left).toBeNull();
+	});
+});

frontend/src/container/Home/useHomeStripInfo.ts

@@ -0,0 +1,21 @@
+import { useMemo } from 'react';
+import { useGetAlerts } from 'api/generated/services/alerts';
+import { useBottomStrip } from 'container/BottomStrip/useBottomStrip';
+import { type StripItem, StripItemKind } from 'container/BottomStrip/types';
+import { pluralize } from 'utils/pluralize';
+
+export function useHomeStripInfo(): void {
+	// Firing instances, not rules, matching the triggered alerts page.
+	const { data } = useGetAlerts();
+
+	const count = data?.data?.length ?? 0;
+
+	const items = useMemo<StripItem[]>(
+		() => [
+			{ kind: StripItemKind.Text, text: `${pluralize(count, 'alert')} firing` },
+		],
+		[count],
+	);
+
+	useBottomStrip(items);
+}

frontend/src/container/LLMObservability/Settings/ModelPricing/UnpricedModelsTab/UnpricedModelsTab.module.scss

@@ -5,22 +5,9 @@
 }
 
 .banner {
-	display: flex;
-	align-items: flex-start;
-	gap: var(--spacing-5);
-	padding: var(--spacing-6) var(--spacing-8);
-	border-radius: var(--radius-2);
-	border: 1px solid color-mix(in srgb, var(--bg-amber-400) 30%, transparent);
-	background: color-mix(in srgb, var(--bg-amber-400) 8%, transparent);
-	color: var(--bg-amber-300, var(--bg-amber-400));
 	margin-top: var(--spacing-4);
 }
 
-.bannerIcon {
-	flex-shrink: 0;
-	margin-top: var(--spacing-1);
-}
-
 .error {
 	padding: var(--spacing-6) var(--spacing-8);
 	border-radius: var(--radius-2);

frontend/src/container/LLMObservability/Settings/ModelPricing/UnpricedModelsTab/UnpricedModelsTab.tsx

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo } from 'react';
+import { Callout } from '@signozhq/ui/callout';
 import { Typography } from '@signozhq/ui/typography';
-import { TriangleAlert } from '@signozhq/icons';
 import { useListUnmappedLLMModels } from 'api/generated/services/llmpricingrules';
 import useComponentPermission from 'hooks/useComponentPermission';
 import { useAppContext } from 'providers/App/App';
@@ -80,13 +80,10 @@ function UnpricedModelsTab(): JSX.Element {
 
 	return (
 		<div className={styles.unpricedModelsTab}>
-			<div className={styles.banner}>
-				<TriangleAlert size="sm" className={styles.bannerIcon} />
-				<Typography.Text as="span" size="small" color="warning">
-					Models detected in traces without pricing. Map each to a billing model or
-					create pricing so estimated cost can be computed.
-				</Typography.Text>
-			</div>
+			<Callout type="warning" size="small" showIcon className={styles.banner}>
+				Models detected in traces without pricing. Map each to a billing model or
+				create pricing so estimated cost can be computed.
+			</Callout>
 
 			{isError && (
 				<div className={styles.error}>

frontend/src/container/ListAlertRules/__tests__/useAlertRulesStripInfo.test.tsx

@@ -0,0 +1,53 @@
+import { renderHook } from '@testing-library/react';
+import { useBottomStripStore } from 'container/BottomStrip/store/useBottomStripStore';
+import { StripItemKind } from 'container/BottomStrip/types';
+
+import { useAlertRulesStripInfo } from '../useAlertRulesStripInfo';
+
+describe('useAlertRulesStripInfo', () => {
+	beforeEach(() => {
+		useBottomStripStore.setState({ left: null, ownerId: null });
+	});
+
+	it('shows the rows on the page against the total', () => {
+		renderHook(() => useAlertRulesStripInfo({ shownCount: 15, totalCount: 17 }));
+
+		expect(useBottomStripStore.getState().left).toMatchObject([
+			{ kind: StripItemKind.Text, text: '15 of 17 rules' },
+		]);
+	});
+
+	it('still says n of m when the whole list fits on one page', () => {
+		renderHook(() => useAlertRulesStripInfo({ shownCount: 17, totalCount: 17 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '17 of 17 rules',
+		});
+	});
+
+	it('says rule, not rules, when there is only one', () => {
+		renderHook(() => useAlertRulesStripInfo({ shownCount: 1, totalCount: 1 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '1 of 1 rule',
+		});
+	});
+
+	it('shows zero when nothing matched', () => {
+		renderHook(() => useAlertRulesStripInfo({ shownCount: 0, totalCount: 12 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '0 of 12 rules',
+		});
+	});
+
+	it('clears the strip when the page unmounts', () => {
+		const { unmount } = renderHook(() =>
+			useAlertRulesStripInfo({ shownCount: 15, totalCount: 17 }),
+		);
+
+		unmount();
+
+		expect(useBottomStripStore.getState().left).toBeNull();
+	});
+});

frontend/src/container/ListAlertRules/index.tsx

@@ -20,6 +20,7 @@ import { ALERT_RULES_PARAMS, useAlertRulesFilters } from './hooks';
 import styles from './ListAlertRules.module.scss';
 import { getAlertRuleColumns } from './table.config';
 import type { AlertRule } from './types';
+import { useAlertRulesStripInfo } from './useAlertRulesStripInfo';
 import { useAlertRulesData } from './useAlertRulesData';
 import { useAlertRulesHandlers } from './useAlertRulesHandlers';
 
@@ -87,6 +88,11 @@ function ListAlertRules(): JSX.Element {
 		return filteredRules.slice(start, start + limit);
 	}, [filteredRules, page, limit]);
 
+	useAlertRulesStripInfo({
+		shownCount: paginatedRules.length,
+		totalCount: filteredRules.length,
+	});
+
 	const columnsWithActions = useMemo(() => {
 		if (!action) {
 			return columns;

frontend/src/container/ListAlertRules/useAlertRulesStripInfo.ts

@@ -0,0 +1,27 @@
+import { useMemo } from 'react';
+import { useBottomStrip } from 'container/BottomStrip/useBottomStrip';
+import { type StripItem, StripItemKind } from 'container/BottomStrip/types';
+import { pluralize } from 'utils/pluralize';
+
+interface UseAlertRulesStripInfoArgs {
+	/** Rows on the current page, matching the table's own footer. */
+	shownCount: number;
+	totalCount: number;
+}
+
+export function useAlertRulesStripInfo({
+	shownCount,
+	totalCount,
+}: UseAlertRulesStripInfoArgs): void {
+	const items = useMemo<StripItem[]>(
+		() => [
+			{
+				kind: StripItemKind.Text,
+				text: `${shownCount} of ${pluralize(totalCount, 'rule')}`,
+			},
+		],
+		[shownCount, totalCount],
+	);
+
+	useBottomStrip(items);
+}

frontend/src/container/MetricsExplorer/Explorer/Explorer.tsx

@@ -10,6 +10,8 @@ import WarningPopover from 'components/WarningPopover/WarningPopover';
 import { initialQueriesMap, PANEL_TYPES } from 'constants/queryBuilder';
 import { REACT_QUERY_KEY } from 'constants/reactQueryKeys';
 import { usePageActions } from 'container/AIAssistant/pageActions/usePageActions';
+import { SavedviewtypesSourceDTO } from 'api/generated/services/sigNoz.schemas';
+import QuickFiltersLayout from 'components/QuickFilters/QuickFiltersLayout/QuickFiltersLayout';
 import ExplorerOptionWrapper from 'container/ExplorerOptions/ExplorerOptionWrapper';
 import RightToolbarActions from 'container/QueryBuilder/components/ToolbarActions/RightToolbarActions';
 import DateTimeSelector from 'container/TopNav/DateTimeSelectionV2';
@@ -347,57 +349,62 @@ function Explorer(): JSX.Element {
 
 	return (
 		<Sentry.ErrorBoundary fallback={<ErrorBoundaryFallback />}>
-			<div className="metrics-explorer-explore-container">
-				<div className="explore-header">
-					<div className="explore-header-left-actions">
-						<span>1 chart/query</span>
-						<Tooltip
-							open={disableOneChartPerQuery ? undefined : false}
-							title={oneChartPerQueryDisabledTooltip}
-						>
-							<Switch
-								value={showOneChartPerQuery}
-								onChange={handleToggleShowOneChartPerQuery}
-								disabled={disableOneChartPerQuery || splitedQueries.length <= 1}
+			<QuickFiltersLayout
+				showFilters
+				savedViewProps={{ source: SavedviewtypesSourceDTO.metrics }}
+			>
+				<div className="metrics-explorer-explore-container">
+					<div className="explore-header">
+						<div className="explore-header-left-actions">
+							<span>1 chart/query</span>
+							<Tooltip
+								open={disableOneChartPerQuery ? undefined : false}
+								title={oneChartPerQueryDisabledTooltip}
+							>
+								<Switch
+									value={showOneChartPerQuery}
+									onChange={handleToggleShowOneChartPerQuery}
+									disabled={disableOneChartPerQuery || splitedQueries.length <= 1}
+								/>
+							</Tooltip>
+						</div>
+						<div className="explore-header-right-actions">
+							{!isEmpty(warning) && <WarningPopover warningData={warning} />}
+							<DateTimeSelector showAutoRefresh />
+							<RightToolbarActions
+								onStageRunQuery={(): void => handleRunQuery()}
+								isLoadingQueries={isLoadingQueries}
+								handleCancelQuery={handleCancelQuery}
 							/>
-						</Tooltip>
+						</div>
 					</div>
-					<div className="explore-header-right-actions">
-						{!isEmpty(warning) && <WarningPopover warningData={warning} />}
-						<DateTimeSelector showAutoRefresh />
-						<RightToolbarActions
-							onStageRunQuery={(): void => handleRunQuery()}
-							isLoadingQueries={isLoadingQueries}
-							handleCancelQuery={handleCancelQuery}
+					<QueryBuilderV2
+						config={{ initialDataSource: DataSource.METRICS, queryVariant: 'static' }}
+						panelType={PANEL_TYPES.TIME_SERIES}
+						showFunctions={false}
+						version="v3"
+					/>
+					<div className="explore-content">
+						<TimeSeries
+							onFetchingStateChange={setIsLoadingQueries}
+							showOneChartPerQuery={showOneChartPerQuery}
+							setWarning={setWarning}
+							areAllMetricUnitsSame={areAllMetricUnitsSame}
+							isMetricUnitsLoading={isMetricUnitsLoading}
+							isMetricUnitsError={isMetricUnitsError}
+							metricUnits={units}
+							metricNames={metricNames}
+							metrics={metrics}
+							handleOpenMetricDetails={handleOpenMetricDetails}
+							yAxisUnit={yAxisUnit}
+							setYAxisUnit={setYAxisUnit}
+							showYAxisUnitSelector={showYAxisUnitSelector}
+							isCancelled={isCancelled}
+							exportDefaultQuery={exportDefaultQuery}
 						/>
 					</div>
 				</div>
-				<QueryBuilderV2
-					config={{ initialDataSource: DataSource.METRICS, queryVariant: 'static' }}
-					panelType={PANEL_TYPES.TIME_SERIES}
-					showFunctions={false}
-					version="v3"
-				/>
-				<div className="explore-content">
-					<TimeSeries
-						onFetchingStateChange={setIsLoadingQueries}
-						showOneChartPerQuery={showOneChartPerQuery}
-						setWarning={setWarning}
-						areAllMetricUnitsSame={areAllMetricUnitsSame}
-						isMetricUnitsLoading={isMetricUnitsLoading}
-						isMetricUnitsError={isMetricUnitsError}
-						metricUnits={units}
-						metricNames={metricNames}
-						metrics={metrics}
-						handleOpenMetricDetails={handleOpenMetricDetails}
-						yAxisUnit={yAxisUnit}
-						setYAxisUnit={setYAxisUnit}
-						showYAxisUnitSelector={showYAxisUnitSelector}
-						isCancelled={isCancelled}
-						exportDefaultQuery={exportDefaultQuery}
-					/>
-				</div>
-			</div>
+			</QuickFiltersLayout>
 			<ExplorerOptionWrapper
 				disabled={!stagedQuery}
 				query={exportDefaultQuery}

frontend/src/container/QueryBuilder/components/DataSourceDropdown/__tests__/DataSourceDropdown.test.tsx

@@ -0,0 +1,79 @@
+import { TelemetrytypesSignalDTO } from 'api/generated/services/sigNoz.schemas';
+import { render, screen, userEvent } from 'tests/test-utils';
+import { DataSource } from 'types/common/queryBuilder';
+
+import { DataSourceDropdown } from '../DataSourceDropdown';
+
+const TEST_ID = 'query-data-source-selector';
+
+async function openDropdown(): Promise<void> {
+	const user = userEvent.setup();
+	const trigger = screen.getByTestId(TEST_ID);
+	await user.click(trigger.querySelector('.ant-select-selector') as HTMLElement);
+}
+
+describe('DataSourceDropdown', () => {
+	// antd's virtual list renders only the first couple of options into jsdom, so
+	// each case asserts what the restriction admits and excludes, not the full list.
+	it('offers the signals beyond the current one when nothing restricts it', async () => {
+		render(
+			<DataSourceDropdown
+				data-testid={TEST_ID}
+				value={DataSource.METRICS}
+				onChange={jest.fn()}
+			/>,
+		);
+		await openDropdown();
+
+		await expect(
+			screen.findByRole('option', { name: 'Logs' }),
+		).resolves.toBeInTheDocument();
+		expect(screen.getByRole('option', { name: 'Metrics' })).toBeInTheDocument();
+	});
+
+	it('offers only the signals the caller can visualize', async () => {
+		render(
+			<DataSourceDropdown
+				data-testid={TEST_ID}
+				value={DataSource.METRICS}
+				allowedDataSources={[TelemetrytypesSignalDTO.metrics]}
+				onChange={jest.fn()}
+			/>,
+		);
+		await openDropdown();
+
+		await expect(
+			screen.findByRole('option', { name: 'Metrics' }),
+		).resolves.toBeInTheDocument();
+		expect(
+			screen.queryByRole('option', { name: 'Logs' }),
+		).not.toBeInTheDocument();
+		expect(
+			screen.queryByRole('option', { name: 'Traces' }),
+		).not.toBeInTheDocument();
+	});
+
+	it('drops a signal that is not a data source a query can be built against', async () => {
+		render(
+			<DataSourceDropdown
+				data-testid={TEST_ID}
+				value={DataSource.LOGS}
+				allowedDataSources={[
+					TelemetrytypesSignalDTO.logs,
+					TelemetrytypesSignalDTO.traces,
+					TelemetrytypesSignalDTO[''],
+				]}
+				onChange={jest.fn()}
+			/>,
+		);
+		await openDropdown();
+
+		await expect(
+			screen.findByRole('option', { name: 'Logs' }),
+		).resolves.toBeInTheDocument();
+		expect(screen.getByRole('option', { name: 'Traces' })).toBeInTheDocument();
+		expect(
+			screen.queryByRole('option', { name: 'Metrics' }),
+		).not.toBeInTheDocument();
+	});
+});

frontend/src/container/QueryBuilder/components/Formula/Formula.tsx

@@ -1,7 +1,9 @@
 import { ChangeEvent, useCallback, useMemo, useState } from 'react';
 import { Col, Input, Row, Select } from 'antd';
 import InputWithLabel from 'components/InputWithLabel/InputWithLabel';
+import BucketOptions from 'components/QueryBuilderV2/QueryV2/QueryAddOns/BucketOptions/BucketOptions';
 import { LEGEND } from 'constants/global';
+import { PANEL_TYPES } from 'constants/queryBuilder';
 // ** Hooks
 import { useQueryBuilder } from 'hooks/queryBuilder/useQueryBuilder';
 import { useQueryOperations } from 'hooks/queryBuilder/useQueryBuilderOperations';
@@ -24,8 +26,12 @@ export function Formula({
 	query,
 	isQBV2,
 }: FormulaProps): JSX.Element {
-	const { removeQueryBuilderEntityByIndex, handleSetFormulaData } =
-		useQueryBuilder();
+	const {
+		removeQueryBuilderEntityByIndex,
+		handleSetFormulaData,
+		panelType,
+		currentQuery,
+	} = useQueryBuilder();
 
 	const { handleChangeFormulaData } = useQueryOperations({
 		index,
@@ -73,6 +79,13 @@ export function Formula({
 		[handleChangeFormulaData],
 	);
 
+	const handleChangeBucketOptions = useCallback(
+		(value: IBuilderFormula['bucketOptions']) => {
+			handleChangeFormulaData('bucketOptions', value);
+		},
+		[handleChangeFormulaData],
+	);
+
 	const handleQBV2OrderByChange = useCallback(
 		(value: string) => {
 			const [columnName, order] = value.split(' ');
@@ -163,6 +176,17 @@ export function Formula({
 							</div>
 						</Col>
 					)}
+					{/* A heatmap draws its one enabled query, which is the formula when its
+					    inputs are disabled — so the formula states its own bucket axis. */}
+					{isQBV2 && panelType === PANEL_TYPES.HEATMAP && (
+						<Col span={24}>
+							<BucketOptions
+								bucketOptions={formula.bucketOptions}
+								unit={currentQuery.unit}
+								onChange={handleChangeBucketOptions}
+							/>
+						</Col>
+					)}
 				</Row>
 			)}
 		</Row>

frontend/src/container/QueryBuilder/components/Formula/__tests__/Formula.bucketOptions.test.tsx

@@ -0,0 +1,91 @@
+import { PANEL_TYPES } from 'constants/queryBuilder';
+import { render, screen, userEvent } from 'tests/test-utils';
+import type { IBuilderFormula } from 'types/api/queryBuilder/queryBuilderData';
+
+import { Formula } from '../Formula';
+
+const mockHandleChangeFormulaData = jest.fn();
+let mockPanelType: PANEL_TYPES = PANEL_TYPES.HEATMAP;
+
+jest.mock('hooks/queryBuilder/useQueryBuilder', () => ({
+	useQueryBuilder: (): Record<string, unknown> => ({
+		removeQueryBuilderEntityByIndex: jest.fn(),
+		handleSetFormulaData: jest.fn(),
+		panelType: mockPanelType,
+		currentQuery: { unit: undefined },
+	}),
+}));
+
+jest.mock('hooks/queryBuilder/useQueryBuilderOperations', () => ({
+	useQueryOperations: (): Record<string, unknown> => ({
+		handleChangeFormulaData: mockHandleChangeFormulaData,
+	}),
+}));
+
+jest.mock('../../QBEntityOptions/QBEntityOptions', () => ({
+	__esModule: true,
+	default: (): JSX.Element => <div data-testid="qb-entity-options" />,
+}));
+
+function formula(overrides: Partial<IBuilderFormula> = {}): IBuilderFormula {
+	return {
+		queryName: 'F1',
+		expression: 'A',
+		legend: '',
+		disabled: false,
+		...overrides,
+	};
+}
+
+function renderFormula(overrides: Partial<IBuilderFormula> = {}): void {
+	render(
+		<Formula index={0} formula={formula(overrides)} query={{} as never} isQBV2 />,
+	);
+}
+
+describe('Formula bucket options', () => {
+	beforeEach(() => {
+		jest.clearAllMocks();
+		mockPanelType = PANEL_TYPES.HEATMAP;
+	});
+
+	it('offers a bucket axis on a heatmap', () => {
+		renderFormula();
+
+		expect(screen.getByTestId('bucket-options')).toBeInTheDocument();
+	});
+
+	it('is not dismissable — a formula has no add-on toggle bar to collapse into', () => {
+		renderFormula();
+
+		expect(screen.queryByTestId('bucket-options-close')).not.toBeInTheDocument();
+	});
+
+	it('offers no bucket axis on other panel types', () => {
+		mockPanelType = PANEL_TYPES.TIME_SERIES;
+		renderFormula();
+
+		expect(screen.queryByTestId('bucket-options')).not.toBeInTheDocument();
+	});
+
+	it('opens on the axis the formula already carries', () => {
+		renderFormula({
+			bucketOptions: { kind: 'log', spec: { scale: 0 } } as never,
+		});
+
+		expect(screen.getByRole('radio', { name: 'Log' })).toBeChecked();
+		expect(screen.getByRole('radio', { name: '0' })).toBeChecked();
+	});
+
+	it('writes the picked axis onto the formula', async () => {
+		const user = userEvent.setup();
+		renderFormula();
+
+		await user.click(screen.getByRole('radio', { name: '0' }));
+
+		expect(mockHandleChangeFormulaData).toHaveBeenCalledWith('bucketOptions', {
+			kind: 'log',
+			spec: { scale: 0 },
+		});
+	});
+});

frontend/src/container/ResetPassword/__tests__/ResetPassword.test.tsx

@@ -155,6 +155,39 @@ describe('ResetPassword Component', () => {
 				{ timeout: 200 },
 			);
 		});
+
+		it('clears password mismatch error when confirm password is emptied', async () => {
+			const user = userEvent.setup({ pointerEventsCheck: 0 });
+
+			render(<ResetPassword version="1.0.0" />, undefined, {
+				initialRoute: '/password-reset?token=reset-token-123',
+			});
+
+			const passwordInput = screen.getByPlaceholderText(/enter new password/i);
+			const confirmPasswordInput = screen.getByPlaceholderText(
+				/confirm your new password/i,
+			);
+			const submitButton = screen.getByRole('button', {
+				name: /reset password/i,
+			});
+
+			await user.type(passwordInput, 'password123');
+			await user.type(confirmPasswordInput, 'password456');
+			await user.tab();
+
+			await waitFor(() => {
+				expect(screen.getByText(/passwords don't match/i)).toBeInTheDocument();
+			});
+
+			await user.clear(confirmPasswordInput);
+
+			await waitFor(() => {
+				expect(
+					screen.queryByText(/passwords don't match/i),
+				).not.toBeInTheDocument();
+				expect(submitButton).toBeDisabled();
+			});
+		});
 	});
 
 	describe('Successful Password Reset', () => {
@@ -288,6 +321,65 @@ describe('ResetPassword Component', () => {
 				expect(screen.queryByText(/invalid token/i)).not.toBeInTheDocument();
 			});
 		});
+
+		it('clears API error when the user edits the password', async () => {
+			const user = userEvent.setup({ pointerEventsCheck: 0 });
+
+			server.use(
+				rest.post(RESET_PASSWORD_ENDPOINT, (_req, res, ctx) =>
+					res(
+						ctx.status(400),
+						ctx.json({
+							error: {
+								code: 'invalid_password',
+								message: 'password must be at least 8 characters long',
+							},
+						}),
+					),
+				),
+			);
+
+			render(<ResetPassword version="1.0.0" />, undefined, {
+				initialRoute: '/password-reset?token=reset-token-123',
+			});
+
+			const passwordInput = screen.getByPlaceholderText(/enter new password/i);
+			const confirmPasswordInput = screen.getByPlaceholderText(
+				/confirm your new password/i,
+			);
+			const submitButton = screen.getByRole('button', {
+				name: /reset password/i,
+			});
+
+			await user.type(passwordInput, 'weak');
+			await user.type(confirmPasswordInput, 'weak');
+
+			await waitFor(() => {
+				expect(submitButton).not.toBeDisabled();
+			});
+
+			await user.click(submitButton);
+
+			await waitFor(() => {
+				expect(
+					screen.getByText(/password must be at least 8 characters long/i),
+				).toBeInTheDocument();
+			});
+
+			await user.type(passwordInput, 'Er1!');
+
+			await waitFor(() => {
+				expect(
+					screen.queryByText(/password must be at least 8 characters long/i),
+				).not.toBeInTheDocument();
+			});
+
+			await user.type(confirmPasswordInput, 'Er1!');
+
+			await waitFor(() => {
+				expect(submitButton).not.toBeDisabled();
+			});
+		});
 	});
 
 	describe('Loading States', () => {

frontend/src/container/ResetPassword/index.tsx

@@ -10,7 +10,6 @@ import { useResetPassword } from 'api/generated/services/users';
 import AuthError from 'components/AuthError/AuthError';
 import AuthPageContainer from 'components/AuthPageContainer';
 import ROUTES from 'constants/routes';
-import useDebouncedFn from 'hooks/useDebouncedFunction';
 import { useNotifications } from 'hooks/useNotifications';
 import history from 'lib/history';
 import { ArrowRight, CircleAlert, KeyRound } from '@signozhq/icons';
@@ -23,10 +22,7 @@ import './ResetPassword.styles.scss';
 type FormValues = { password: string; confirmPassword: string };
 
 function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
-	const [confirmPasswordError, setConfirmPasswordError] =
-		useState<boolean>(false);
-
-	const [isValidPassword, setIsValidPassword] = useState(false);
+	const [confirmPasswordTouched, setConfirmPasswordTouched] = useState(false);
 	const { t } = useTranslation(['common']);
 	const { search } = useLocation();
 	const params = new URLSearchParams(search);
@@ -37,6 +33,7 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 		mutate: resetPassword,
 		isLoading,
 		error: mutationError,
+		reset: resetMutation,
 	} = useResetPassword();
 
 	const errorMessage = useMemo(
@@ -45,11 +42,30 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 	);
 
 	const [form] = Form.useForm<FormValues>();
-	const handleFormSubmit = (): void => {
-		const { password } = form.getFieldsValue();
+	const password = Form.useWatch('password', form);
+	const confirmPassword = Form.useWatch('confirmPassword', form);
+
+	const isPasswordMismatch =
+		Boolean(confirmPassword) && password !== confirmPassword;
+	const showPasswordMismatchError = confirmPasswordTouched && isPasswordMismatch;
+	const isValidPassword =
+		Boolean(password?.trim()) &&
+		Boolean(confirmPassword?.trim()) &&
+		password === confirmPassword;
+
+	const handleValuesChange = (): void => {
+		if (mutationError) {
+			resetMutation();
+		}
+	};
+
+	const handleSubmit = (): void => {
+		if (!token) {
+			return;
+		}
 
 		resetPassword(
-			{ data: { password, token: token || '' } },
+			{ data: { password: form.getFieldValue('password'), token } },
 			{
 				onSuccess: (): void => {
 					notifications.success({
@@ -63,80 +79,6 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 		);
 	};
 
-	const validatePassword = (): boolean => {
-		const { password, confirmPassword } = form.getFieldsValue();
-
-		if (
-			password &&
-			confirmPassword &&
-			password.trim() &&
-			confirmPassword.trim() &&
-			password.length > 0 &&
-			confirmPassword.length > 0
-		) {
-			return password === confirmPassword;
-		}
-
-		return false;
-	};
-
-	const handleValuesChange = useDebouncedFn((): void => {
-		const { password, confirmPassword } = form.getFieldsValue();
-
-		if (!password || !confirmPassword) {
-			setIsValidPassword(false);
-		}
-
-		// Only clear error if passwords match while typing (but don't set error until blur)
-		if (
-			password &&
-			confirmPassword &&
-			password.trim() &&
-			confirmPassword.trim()
-		) {
-			const isValid = validatePassword();
-			setIsValidPassword(isValid);
-
-			// Only clear error if passwords match, don't set error on mismatch
-			if (isValid) {
-				setConfirmPasswordError(false);
-			}
-		}
-	}, 100);
-
-	const handlePasswordBlur = (): void => {
-		const { confirmPassword } = form.getFieldsValue();
-		// Only validate if confirm password has a value
-		if (confirmPassword && confirmPassword.trim()) {
-			const isValid = validatePassword();
-			setIsValidPassword(isValid);
-			setConfirmPasswordError(!isValid);
-		}
-	};
-
-	const handleConfirmPasswordBlur = (): void => {
-		const { password, confirmPassword } = form.getFieldsValue();
-		if (
-			password &&
-			password.trim() &&
-			confirmPassword &&
-			confirmPassword.trim()
-		) {
-			const isValid = validatePassword();
-			setIsValidPassword(isValid);
-			setConfirmPasswordError(!isValid);
-		}
-	};
-
-	const handleSubmit = (): void => {
-		const isValid = validatePassword();
-		setIsValidPassword(isValid);
-
-		if (token) {
-			handleFormSubmit();
-		}
-	};
-
 	return (
 		<AuthPageContainer>
 			<div className="reset-password-card">
@@ -158,6 +100,7 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 				<FormContainer
 					form={form}
 					onFinish={handleSubmit}
+					onValuesChange={handleValuesChange}
 					className="reset-password-form"
 				>
 					<div className="reset-password-form-container">
@@ -171,8 +114,6 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 								>
 									<AntdInput.Password
 										tabIndex={0}
-										onChange={handleValuesChange}
-										onBlur={handlePasswordBlur}
 										id="password"
 										data-testid="password"
 										placeholder="Enter new password"
@@ -189,8 +130,7 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 									rules={[{ required: true, message: 'Please enter confirm password!' }]}
 								>
 									<AntdInput.Password
-										onChange={handleValuesChange}
-										onBlur={handleConfirmPasswordBlur}
+										onBlur={(): void => setConfirmPasswordTouched(true)}
 										id="confirmPassword"
 										data-testid="confirmPassword"
 										placeholder="Confirm your new password"
@@ -201,7 +141,7 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 						</div>
 					</div>
 
-					{confirmPasswordError && (
+					{showPasswordMismatchError && (
 						<Callout
 							type="error"
 							size="small"
@@ -213,7 +153,7 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 						</Callout>
 					)}
 
-					{errorMessage && !confirmPasswordError && (
+					{errorMessage && !showPasswordMismatchError && (
 						<AuthError error={errorMessage} />
 					)}
 

frontend/src/container/SavedViews/SavedViewsHeader.module.scss

@@ -0,0 +1,19 @@
+.header {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: var(--spacing-2);
+	padding: var(--spacing-2) var(--spacing-3);
+	border-bottom: 1px solid var(--l1-border);
+	color: var(--l1-foreground);
+	flex-shrink: 0;
+}
+
+.name {
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	font-size: var(--font-size-sm);
+	font-weight: var(--font-weight-medium);
+}

frontend/src/container/SavedViews/SavedViewsHeader.tsx

@@ -0,0 +1,43 @@
+import { Menu } from '@signozhq/icons';
+import { Button } from '@signozhq/ui/button';
+import { Typography } from '@signozhq/ui/typography';
+import { SavedviewtypesSourceDTO } from 'api/generated/services/sigNoz.schemas';
+
+import styles from './SavedViewsHeader.module.scss';
+
+// Temp Placeholder data till main functionality is plugged in
+const PLACEHOLDER_VIEW_NAME = 'My view';
+
+function SavedViewsHeader({
+	source,
+	onOpenViews,
+}: {
+	source: SavedviewtypesSourceDTO;
+	// Absent when the list is always on screen.
+	onOpenViews?: () => void;
+}): JSX.Element {
+	return (
+		<div
+			className={styles.header}
+			data-testid="saved-views-header"
+			data-source={source}
+		>
+			<Typography.Text className={styles.name}>
+				{PLACEHOLDER_VIEW_NAME}
+			</Typography.Text>
+			{onOpenViews && (
+				<Button
+					variant="ghost"
+					color="secondary"
+					size="icon"
+					aria-label="All views"
+					prefix={<Menu size={14} />}
+					onClick={onOpenViews}
+					data-testid="saved-views-open"
+				/>
+			)}
+		</div>
+	);
+}
+
+export default SavedViewsHeader;

frontend/src/container/SavedViews/SavedViewsPanel.module.scss

@@ -0,0 +1,21 @@
+.panel {
+	display: flex;
+	flex-direction: column;
+	flex: 1;
+	min-height: 0;
+	color: var(--l1-foreground);
+}
+
+.header {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	padding: var(--spacing-2) var(--spacing-3);
+	border-bottom: 1px solid var(--l1-border);
+	flex-shrink: 0;
+}
+
+.title {
+	font-size: var(--font-size-sm);
+	font-weight: var(--font-weight-medium);
+}

frontend/src/container/SavedViews/SavedViewsPanel.tsx

@@ -0,0 +1,40 @@
+import { X } from '@signozhq/icons';
+import { Button } from '@signozhq/ui/button';
+import { Typography } from '@signozhq/ui/typography';
+import { SavedviewtypesSourceDTO } from 'api/generated/services/sigNoz.schemas';
+
+import styles from './SavedViewsPanel.module.scss';
+
+function SavedViewsPanel({
+	source,
+	onClose,
+}: {
+	source: SavedviewtypesSourceDTO;
+	// Absent when the list is always on screen.
+	onClose?: () => void;
+}): JSX.Element {
+	return (
+		<div
+			className={styles.panel}
+			data-testid="saved-views-panel"
+			data-source={source}
+		>
+			<div className={styles.header}>
+				<Typography.Text className={styles.title}>All views</Typography.Text>
+				{onClose && (
+					<Button
+						variant="ghost"
+						color="secondary"
+						size="icon"
+						aria-label="Close"
+						prefix={<X size={14} />}
+						onClick={onClose}
+						data-testid="saved-views-close"
+					/>
+				)}
+			</div>
+		</div>
+	);
+}
+
+export default SavedViewsPanel;

frontend/src/container/ServiceApplication/ServiceMetrics/ServiceMetricTable.tsx

@@ -21,6 +21,7 @@ import { getTotalRPS } from 'utils/services';
 
 import { getColumns } from '../Columns/ServiceColumn';
 import { ServiceMetricsTableProps } from '../types';
+import { useServicesStripInfo } from '../useServicesStripInfo';
 import { getServiceListFromQuery } from '../utils';
 
 function ServiceMetricTable({
@@ -67,6 +68,8 @@ function ServiceMetricTable({
 		[isLoading, queries, topLevelOperations],
 	);
 
+	useServicesStripInfo(services.length);
+
 	const { search } = useLocation();
 	const tableColumns = useMemo(() => getColumns(search, true), [search]);
 	const [RPS, setRPS] = useState(0);

frontend/src/container/ServiceApplication/ServiceTraces/index.tsx

@@ -18,6 +18,7 @@ import { GlobalReducer } from 'types/reducer/globalTime';
 import { Tags } from 'hooks/useResourceAttribute/types';
 
 import SkipOnBoardingModal from '../SkipOnBoardModal';
+import { useServicesStripInfo } from '../useServicesStripInfo';
 import ServiceTraceTable from './ServiceTracesTable';
 
 function ServiceTraces(): JSX.Element {
@@ -42,6 +43,8 @@ function ServiceTraces(): JSX.Element {
 
 	const services = data || [];
 
+	useServicesStripInfo(services.length);
+
 	const [skipOnboarding, setSkipOnboarding] = useState(
 		localStorageGet(SKIP_ONBOARDING) === 'true',
 	);

frontend/src/container/ServiceApplication/__tests__/useServicesStripInfo.test.tsx

@@ -0,0 +1,43 @@
+import { renderHook } from '@testing-library/react';
+import { useBottomStripStore } from 'container/BottomStrip/store/useBottomStripStore';
+import { StripItemKind } from 'container/BottomStrip/types';
+
+import { useServicesStripInfo } from '../useServicesStripInfo';
+
+describe('useServicesStripInfo', () => {
+	beforeEach(() => {
+		useBottomStripStore.setState({ left: null, ownerId: null });
+	});
+
+	it('shows how many services are listed', () => {
+		renderHook(() => useServicesStripInfo(18));
+
+		expect(useBottomStripStore.getState().left).toMatchObject([
+			{ kind: StripItemKind.Text, text: '18 services' },
+		]);
+	});
+
+	it('says service, not services, when there is one', () => {
+		renderHook(() => useServicesStripInfo(1));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '1 service',
+		});
+	});
+
+	it('shows zero when there are none', () => {
+		renderHook(() => useServicesStripInfo(0));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '0 services',
+		});
+	});
+
+	it('clears the strip when the page unmounts', () => {
+		const { unmount } = renderHook(() => useServicesStripInfo(18));
+
+		unmount();
+
+		expect(useBottomStripStore.getState().left).toBeNull();
+	});
+});

frontend/src/container/ServiceApplication/useServicesStripInfo.ts

@@ -0,0 +1,13 @@
+import { useMemo } from 'react';
+import { useBottomStrip } from 'container/BottomStrip/useBottomStrip';
+import { type StripItem, StripItemKind } from 'container/BottomStrip/types';
+import { pluralize } from 'utils/pluralize';
+
+export function useServicesStripInfo(count: number): void {
+	const items = useMemo<StripItem[]>(
+		() => [{ kind: StripItemKind.Text, text: pluralize(count, 'service') }],
+		[count],
+	);
+
+	useBottomStrip(items);
+}

frontend/src/container/WidgetCard/Card/FullView/contants.ts

@@ -30,6 +30,7 @@ export const PANEL_TYPES_VS_FULL_VIEW_TABLE: PanelTypeAndGraphManagerVisibilityP
 		AREA: true,
 		PIE: false,
 		HISTOGRAM: false,
+		HEATMAP: false,
 		TEXT: false,
 		EMPTY_WIDGET: false,
 	};

frontend/src/container/WidgetCard/Panels/constants.ts

@@ -21,4 +21,6 @@ export const PanelTypeVsPanelWrapper = {
 	[PANEL_TYPES.BAR]: BarPanel,
 	[PANEL_TYPES.AREA]: TimeSeriesPanel,
 	[PANEL_TYPES.HISTOGRAM]: HistogramPanel,
+	// V2-only kind; it renders through the V2 panel registry.
+	[PANEL_TYPES.HEATMAP]: null,
 };

frontend/src/hooks/queryBuilder/__tests__/useQueryBuilderOperations.test.ts

@@ -62,14 +62,14 @@ describe('useQueryBuilderOperations - Empty Aggregate Attribute Type', () => {
 		legend: '',
 	};
 
-	const setupMockQueryBuilder = (): void => {
+	const setupMockQueryBuilder = (panelType = 'time_series'): void => {
 		(useQueryBuilder as jest.Mock).mockReturnValue({
 			handleSetQueryData: mockHandleSetQueryData,
 			handleSetFormulaData: mockHandleSetFormulaData,
 			removeQueryBuilderEntityByIndex: mockRemoveQueryBuilderEntityByIndex,
 			setLastUsedQuery: mockSetLastUsedQuery,
 			redirectWithQueryBuilderData: mockRedirectWithQueryBuilderData,
-			panelType: 'time_series',
+			panelType,
 			currentQuery: {
 				builder: {
 					queryData: [defaultMockQuery, defaultMockQuery],
@@ -332,4 +332,105 @@ describe('useQueryBuilderOperations - Empty Aggregate Attribute Type', () => {
 			);
 		});
 	});
+
+	describe('spaceAggregationOptions for a histogram metric', () => {
+		const histogramQuery: IBuilderQuery = {
+			...defaultMockQuery,
+			aggregateAttribute: {
+				key: 'signoz_latency',
+				dataType: DataTypes.Float64,
+				type: ATTRIBUTE_TYPES.HISTOGRAM,
+			} as BaseAutocompleteData,
+		};
+
+		it('offers the percentiles on a time series panel', () => {
+			const result = renderHookWithProps({ query: histogramQuery });
+
+			expect(
+				result.current.spaceAggregationOptions.map((o) => o.value),
+			).toStrictEqual([
+				MetricAggregateOperator.P50,
+				MetricAggregateOperator.P75,
+				MetricAggregateOperator.P90,
+				MetricAggregateOperator.P95,
+				MetricAggregateOperator.P99,
+			]);
+		});
+
+		it('offers count alone on a heatmap panel, whose Y axis is the `le` labels', () => {
+			setupMockQueryBuilder('heatmap');
+
+			const result = renderHookWithProps({ query: histogramQuery });
+
+			expect(
+				result.current.spaceAggregationOptions.map((o) => o.value),
+			).toStrictEqual([MetricAggregateOperator.COUNT]);
+		});
+	});
+
+	describe('picking a histogram metric', () => {
+		const histogramAttribute: BaseAutocompleteData = {
+			key: 'http.client.duration.bucket',
+			dataType: DataTypes.Float64,
+			type: ATTRIBUTE_TYPES.HISTOGRAM,
+		};
+
+		it('defaults the spatial aggregation to p90 on a time series panel', () => {
+			const result = renderHookWithProps({ entityVersion: ENTITY_VERSION_V5 });
+			act(() => {
+				result.current.handleChangeAggregatorAttribute(histogramAttribute);
+			});
+
+			expect(mockHandleSetQueryData).toHaveBeenLastCalledWith(
+				0,
+				expect.objectContaining({
+					aggregations: [
+						expect.objectContaining({
+							spaceAggregation: MetricAggregateOperator.P90,
+						}),
+					],
+				}),
+			);
+		});
+
+		it('defaults it to count on a heatmap panel, which offers nothing else', () => {
+			setupMockQueryBuilder('heatmap');
+
+			const result = renderHookWithProps({ entityVersion: ENTITY_VERSION_V5 });
+			act(() => {
+				result.current.handleChangeAggregatorAttribute(histogramAttribute);
+			});
+
+			expect(mockHandleSetQueryData).toHaveBeenLastCalledWith(
+				0,
+				expect.objectContaining({
+					aggregations: [
+						expect.objectContaining({
+							spaceAggregation: MetricAggregateOperator.COUNT,
+						}),
+					],
+				}),
+			);
+		});
+
+		it('drops the bucket axis a gauge had chosen, since `le` is the axis now', () => {
+			setupMockQueryBuilder('heatmap');
+
+			const result = renderHookWithProps({
+				entityVersion: ENTITY_VERSION_V5,
+				query: {
+					...defaultMockQuery,
+					bucketOptions: { kind: 'log', spec: { scale: 2 } },
+				},
+			});
+			act(() => {
+				result.current.handleChangeAggregatorAttribute(histogramAttribute);
+			});
+
+			expect(mockHandleSetQueryData).toHaveBeenLastCalledWith(
+				0,
+				expect.objectContaining({ bucketOptions: undefined }),
+			);
+		});
+	});
 });

frontend/src/hooks/queryBuilder/useQueryBuilderOperations.ts

@@ -18,6 +18,7 @@ import {
 } from 'constants/queryBuilder';
 import {
 	metricsGaugeSpaceAggregateOperatorOptions,
+	metricsHeatmapHistogramSpaceAggregateOperatorOptions,
 	metricsHistogramSpaceAggregateOperatorOptions,
 	metricsSumSpaceAggregateOperatorOptions,
 	metricsUnknownSpaceAggregateOperatorOptions,
@@ -176,6 +177,11 @@ export const useQueryOperations: UseQueryOperations = ({
 							(aggregateAttribute?.type as ATTRIBUTE_TYPES) || ATTRIBUTE_TYPES.GAUGE,
 					});
 
+			const histogramSpaceAggregationOptions =
+				panelType === PANEL_TYPES.HEATMAP
+					? metricsHeatmapHistogramSpaceAggregateOperatorOptions
+					: metricsHistogramSpaceAggregateOperatorOptions;
+
 			switch (aggregateAttribute?.type) {
 				case ATTRIBUTE_TYPES.SUM:
 					setSpaceAggregationOptions(metricsSumSpaceAggregateOperatorOptions);
@@ -185,11 +191,11 @@ export const useQueryOperations: UseQueryOperations = ({
 					break;
 
 				case ATTRIBUTE_TYPES.HISTOGRAM:
-					setSpaceAggregationOptions(metricsHistogramSpaceAggregateOperatorOptions);
+					setSpaceAggregationOptions(histogramSpaceAggregationOptions);
 					break;
 
 				case ATTRIBUTE_TYPES.EXPONENTIAL_HISTOGRAM:
-					setSpaceAggregationOptions(metricsHistogramSpaceAggregateOperatorOptions);
+					setSpaceAggregationOptions(histogramSpaceAggregationOptions);
 					break;
 				default:
 					setSpaceAggregationOptions(metricsUnknownSpaceAggregateOperatorOptions);
@@ -298,10 +304,17 @@ export const useQueryOperations: UseQueryOperations = ({
 									timeAggregation: '',
 									metricName: newQuery.aggregateAttribute?.key || '',
 									temporality: '',
-									spaceAggregation: MetricAggregateOperator.P90,
+									// A heatmap cell holds a count of observations per `le` band, which is
+									// the one option the kind offers — a percentile default would sit in the
+									// selector with nothing behind it.
+									spaceAggregation:
+										panelType === PANEL_TYPES.HEATMAP
+											? MetricAggregateOperator.COUNT
+											: MetricAggregateOperator.P90,
 									reduceTo: ReduceOperators.AVG,
 								},
 							];
+							newQuery.bucketOptions = undefined;
 						} else {
 							newQuery.aggregations = [
 								{
@@ -388,6 +401,7 @@ export const useQueryOperations: UseQueryOperations = ({
 			index,
 			handleMetricAggregateAtributeTypes,
 			previousMetricInfo,
+			panelType,
 		],
 	);
 

frontend/src/hooks/useGetYAxisUnit.test.ts

@@ -222,6 +222,31 @@ describe('useGetYAxisUnit', () => {
 		expect(result.current.isError).toBe(false);
 	});
 
+	it('resolves the unit on the first render, without a settling pass', () => {
+		// The real `useGetMetrics` rebuilds its array on every render; a hook that
+		// stored the unit would need an extra render to settle, and would schedule one
+		// after every render of the panel editor.
+		mockUseGetMetrics.mockImplementation(() => ({
+			isLoading: false,
+			isError: false,
+			metrics: [MOCK_METRIC_1],
+		}));
+
+		let renderCount = 0;
+		const { result, rerender } = renderHook(() => {
+			renderCount += 1;
+			return useGetYAxisUnit();
+		});
+
+		expect(result.current.yAxisUnit).toBe(UniversalYAxisUnit.BYTES);
+		expect(renderCount).toBe(1);
+
+		rerender();
+
+		expect(result.current.yAxisUnit).toBe(UniversalYAxisUnit.BYTES);
+		expect(renderCount).toBe(2);
+	});
+
 	it('should return undefined when metrics have different units', async () => {
 		mockUseGetMetrics.mockReturnValueOnce({
 			isLoading: false,

frontend/src/hooks/useGetYAxisUnit.ts

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useState } from 'react';
+import { useMemo } from 'react';
 import {
 	getMetricUnits,
 	useGetMetrics,
@@ -46,7 +46,6 @@ function useGetYAxisUnit(
 	},
 ): UseGetYAxisUnitResult {
 	const { stagedQuery } = useQueryBuilder();
-	const [yAxisUnit, setYAxisUnit] = useState<string | undefined>();
 
 	const metricNames: string[] | null = useMemo(() => {
 		// If the query type is not QUERY_BUILDER, return null
@@ -95,27 +94,13 @@ function useGetYAxisUnit(
 		[units],
 	);
 
-	useEffect(() => {
-		// If there are no metrics, set the y-axis unit to undefined
-		if (units.length === 0) {
-			setYAxisUnit(undefined);
-			// If there is one metric and it has a non-empty unit, set the y-axis unit to it
-		} else if (units.length === 1 && units[0] !== '') {
-			setYAxisUnit(units[0]);
-			// If all metrics have the same non-empty unit, set the y-axis unit to it
-		} else if (areAllMetricUnitsSame) {
-			if (units[0] !== '') {
-				setYAxisUnit(units[0]);
-			} else {
-				setYAxisUnit(undefined);
-			}
-			// If there is more than one metric and they have different units, set the y-axis unit to undefined
-		} else if (units.length > 1 && !areAllMetricUnitsSame) {
-			setYAxisUnit(undefined);
-			// If there is one metric and it has an empty unit, set the y-axis unit to undefined
-		} else if (units.length === 1 && units[0] === '') {
-			setYAxisUnit(undefined);
+	const yAxisUnit = useMemo(() => {
+		// A single shared unit is the only thing a single axis can carry; metrics that
+		// disagree, or that carry no unit at all, leave the axis unitless.
+		if (units.length === 0 || !areAllMetricUnitsSame) {
+			return undefined;
 		}
+		return units[0] || undefined;
 	}, [units, areAllMetricUnitsSame]);
 
 	return { yAxisUnit, isLoading, isError };

frontend/src/lib/query/__tests__/handleQueryChange.test.ts

@@ -0,0 +1,78 @@
+import { Querybuildertypesv5BucketOptionsLogDTOKind } from 'api/generated/services/sigNoz.schemas';
+import { initialQueriesMap, PANEL_TYPES } from 'constants/queryBuilder';
+import type {
+	IBuilderFormula,
+	Query,
+} from 'types/api/queryBuilder/queryBuilderData';
+import { DataSource } from 'types/common/queryBuilder';
+
+import { handleQueryChange } from '../panelQuery';
+
+const bucketOptions = {
+	kind: Querybuildertypesv5BucketOptionsLogDTOKind.log,
+	spec: { scale: 0 },
+};
+
+function queryWithFormulaAxis(): Query {
+	const base = initialQueriesMap[DataSource.METRICS];
+	const formula: IBuilderFormula = {
+		queryName: 'F1',
+		expression: 'A',
+		legend: '',
+		disabled: false,
+		bucketOptions,
+	};
+
+	return {
+		...base,
+		builder: {
+			...base.builder,
+			queryData: [{ ...base.builder.queryData[0], bucketOptions }],
+			queryFormulas: [formula],
+		},
+	};
+}
+
+describe('handleQueryChange bucket options', () => {
+	it('keeps both axes when the panel stays a heatmap', () => {
+		const result = handleQueryChange(
+			PANEL_TYPES.HEATMAP,
+			queryWithFormulaAxis(),
+			PANEL_TYPES.HEATMAP,
+		);
+
+		expect(result.builder.queryData[0].bucketOptions).toStrictEqual(
+			bucketOptions,
+		);
+		expect(result.builder.queryFormulas[0].bucketOptions).toStrictEqual(
+			bucketOptions,
+		);
+	});
+
+	// The request rejects an axis on any type but heatmap, so a switch has to shed it
+	// from the query (via the field allowlist) and from the formula (by hand).
+	it('drops both axes when switching to another panel type', () => {
+		const result = handleQueryChange(
+			PANEL_TYPES.TIME_SERIES,
+			queryWithFormulaAxis(),
+			PANEL_TYPES.HEATMAP,
+		);
+
+		expect(result.builder.queryData[0].bucketOptions).toBeUndefined();
+		expect(result.builder.queryFormulas[0].bucketOptions).toBeUndefined();
+	});
+
+	it('leaves the rest of the formula intact', () => {
+		const result = handleQueryChange(
+			PANEL_TYPES.TIME_SERIES,
+			queryWithFormulaAxis(),
+			PANEL_TYPES.HEATMAP,
+		);
+
+		expect(result.builder.queryFormulas[0]).toMatchObject({
+			queryName: 'F1',
+			expression: 'A',
+			disabled: false,
+		});
+	});
+});

frontend/src/lib/query/panelQuery.ts

@@ -8,7 +8,11 @@ import {
 	PANEL_TYPES,
 } from 'constants/queryBuilder';
 import { cloneDeep, isEqual, set, unset } from 'lodash-es';
-import { IBuilderQuery, Query } from 'types/api/queryBuilder/queryBuilderData';
+import {
+	IBuilderFormula,
+	IBuilderQuery,
+	Query,
+} from 'types/api/queryBuilder/queryBuilderData';
 
 import {
 	panelTypeDataSourceFormValuesMap,
@@ -95,6 +99,24 @@ export const getIsQueryModified = (
 	);
 };
 
+/**
+ * Formulas are carried across a panel-type switch whole, not rebuilt from
+ * `panelTypeDataSourceFormValuesMap` the way `queryData` is, so a bucket axis has to be
+ * dropped by hand. The request rejects one on any type but heatmap.
+ */
+const withHeatmapBucketOptions = (
+	formulas: IBuilderFormula[],
+	newPanelType: keyof PartialPanelTypes,
+): IBuilderFormula[] => {
+	if (newPanelType === PANEL_TYPES.HEATMAP) {
+		return formulas;
+	}
+
+	return (formulas ?? []).map(
+		({ bucketOptions: _bucketOptions, ...rest }) => rest,
+	);
+};
+
 export function handleQueryChange(
 	newPanelType: keyof PartialPanelTypes,
 	supersetQuery: Query,
@@ -138,6 +160,10 @@ export function handleQueryChange(
 
 				return tempQuery;
 			}),
+			queryFormulas: withHeatmapBucketOptions(
+				supersetQuery.builder.queryFormulas,
+				newPanelType,
+			),
 			queryTraceOperator:
 				newPanelType === PANEL_TYPES.LIST
 					? []

frontend/src/lib/query/panelTypeDataSourceFormValuesMap.ts

@@ -15,6 +15,7 @@ export type PartialPanelTypes = {
 	[PANEL_TYPES.VALUE]: 'value';
 	[PANEL_TYPES.PIE]: 'pie';
 	[PANEL_TYPES.HISTOGRAM]: 'histogram';
+	[PANEL_TYPES.HEATMAP]: 'heatmap';
 };
 
 export type BuilderField = keyof IBuilderQuery;
@@ -45,6 +46,8 @@ const IS_CARRIED = {
 	legend: true,
 	// `dataSource` is appended by the provider; the rest drive surfaces this switch
 	// does not reach.
+	// Heatmap only; listed for it below.
+	bucketOptions: false,
 	dataSource: false,
 	temporality: false,
 	pageSize: false,
@@ -112,6 +115,16 @@ const RAW_ROWS_METRICS: readonly BuilderField[] = omit(
 	'functions',
 );
 
+// `functions` and `having` are dropped rather than carried: the heatmap request
+// rejects both. Logs and traces keep the metrics aggregations too, because the map is
+// keyed by the query's own signal, which a switch can still be holding.
+const HEATMAP: readonly BuilderField[] = omit(
+	SERIES_METRICS,
+	'functions',
+	'having',
+);
+const HEATMAP_METRICS: readonly BuilderField[] = [...HEATMAP, 'bucketOptions'];
+
 /** Each cell gets its own copy; a shared instance would let cells contaminate
  * each other. */
 function bySource(
@@ -133,6 +146,7 @@ export const panelTypeDataSourceFormValuesMap: Record<
 	[PANEL_TYPES.AREA]: bySource(SERIES, SERIES_METRICS),
 	[PANEL_TYPES.BAR]: bySource(SERIES, SERIES_METRICS),
 	[PANEL_TYPES.HISTOGRAM]: bySource(SERIES, SERIES_METRICS),
+	[PANEL_TYPES.HEATMAP]: bySource(HEATMAP, HEATMAP_METRICS),
 	[PANEL_TYPES.TABLE]: bySource(SERIES, SCALAR_METRICS),
 	[PANEL_TYPES.PIE]: bySource(SERIES, SCALAR_METRICS),
 	[PANEL_TYPES.VALUE]: bySource(SINGLE_VALUE, SINGLE_VALUE_METRICS),

frontend/src/lib/uPlotV2/components/ColorBar/ColorBar.module.scss

@@ -0,0 +1,74 @@
+.container {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	width: 100%;
+	padding: 4px 12px 8px;
+	box-sizing: border-box;
+}
+
+.label {
+	flex: 0 0 auto;
+	font-size: 11px;
+	line-height: 16px;
+	color: var(--muted-foreground);
+	font-variant-numeric: tabular-nums;
+}
+
+.track {
+	position: relative;
+	flex: 1 1 auto;
+	height: 8px;
+	border-radius: 2px;
+	border: 1px solid var(--l2-border);
+}
+
+.marker {
+	position: absolute;
+	top: -3px;
+	bottom: -3px;
+	width: 2px;
+	transform: translateX(-1px);
+	// Reads against the panel through the 3px it overhangs the track at either end,
+	// which is what carries it where the ramp happens to match it.
+	background: var(--popover-foreground);
+	border-radius: 1px;
+}
+
+.caption {
+	flex: 0 0 auto;
+	font-size: 10px;
+	letter-spacing: 0.06em;
+	text-transform: uppercase;
+	color: var(--muted-foreground);
+}
+
+.keys {
+	display: flex;
+	flex: 0 0 auto;
+	gap: 12px;
+	align-items: center;
+}
+
+.key {
+	display: flex;
+	gap: 5px;
+	align-items: center;
+	font-size: 11px;
+	color: var(--muted-foreground);
+}
+
+// Approximates the canvas hatch painted over null cells, which `createHatchPattern`
+// strokes in the theme's own direction — light on dark, dark on light.
+.hatchSwatch {
+	width: 11px;
+	height: 11px;
+	border-radius: 2px;
+	border: 1px solid var(--l2-border);
+	box-sizing: border-box;
+	background-image: repeating-linear-gradient(
+		45deg,
+		transparent 0 2px,
+		var(--muted-foreground) 2px 3px
+	);
+}

frontend/src/lib/uPlotV2/components/ColorBar/ColorBar.tsx

@@ -0,0 +1,76 @@
+import { useMemo } from 'react';
+
+import Styles from './ColorBar.module.scss';
+
+export interface ColorBarProps {
+	/** Low to high, drawn as hard-edged segments so the bar shows the same set of
+	 *  colours as the cells. */
+	ramp: string[];
+	minLabel: string;
+	maxLabel: string;
+	/** 0..1. `null` hides the marker. */
+	markerPosition?: number | null;
+	/** What the colour encodes, e.g. "count". */
+	label?: string;
+	/** Keys the one state a ramp cannot express: a hatched data gap. */
+	showNoDataKey?: boolean;
+	'data-testid'?: string;
+}
+
+/** What a colour means, plus a marker for the value under the cursor. */
+export default function ColorBar({
+	ramp,
+	minLabel,
+	maxLabel,
+	markerPosition = null,
+	label,
+	showNoDataKey = false,
+	'data-testid': testId = 'color-bar',
+}: ColorBarProps): JSX.Element | null {
+	const gradient = useMemo(() => {
+		if (ramp.length === 0) {
+			return undefined;
+		}
+		if (ramp.length === 1) {
+			return ramp[0];
+		}
+		const stops = ramp.flatMap((color, index) => {
+			const from = (index / ramp.length) * 100;
+			const to = ((index + 1) / ramp.length) * 100;
+			return [`${color} ${from}%`, `${color} ${to}%`];
+		});
+		return `linear-gradient(to right, ${stops.join(', ')})`;
+	}, [ramp]);
+
+	if (gradient === undefined) {
+		return null;
+	}
+
+	const clampedMarker =
+		markerPosition === null ? null : Math.min(Math.max(markerPosition, 0), 1);
+
+	return (
+		<div className={Styles.container} data-testid={testId}>
+			{label && <span className={Styles.caption}>{label}</span>}
+			<span className={Styles.label}>{minLabel}</span>
+			<div className={Styles.track} style={{ background: gradient }}>
+				{clampedMarker !== null && (
+					<span
+						className={Styles.marker}
+						style={{ left: `${clampedMarker * 100}%` }}
+						data-testid={`${testId}-marker`}
+					/>
+				)}
+			</div>
+			<span className={Styles.label}>{maxLabel}</span>
+			{showNoDataKey && (
+				<div className={Styles.keys} data-testid={`${testId}-state-keys`}>
+					<span className={Styles.key}>
+						<span className={Styles.hatchSwatch} />
+						no data
+					</span>
+				</div>
+			)}
+		</div>
+	);
+}

frontend/src/lib/uPlotV2/components/ColorBar/__tests__/ColorBar.test.tsx

@@ -0,0 +1,85 @@
+import { render, screen } from '@testing-library/react';
+
+import ColorBar from '../ColorBar';
+
+const RAMP = ['#111111', '#555555', '#999999', '#dddddd'];
+
+describe('ColorBar', () => {
+	it('renders the domain labels', () => {
+		render(<ColorBar ramp={RAMP} minLabel="0" maxLabel="1,204" />);
+
+		expect(screen.getByText('0')).toBeInTheDocument();
+		expect(screen.getByText('1,204')).toBeInTheDocument();
+	});
+
+	it('renders nothing without a ramp', () => {
+		const { container } = render(
+			<ColorBar ramp={[]} minLabel="0" maxLabel="0" />,
+		);
+
+		expect(container).toBeEmptyDOMElement();
+	});
+
+	it('hides the marker when nothing is hovered', () => {
+		render(<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" />);
+
+		expect(screen.queryByTestId('color-bar-marker')).not.toBeInTheDocument();
+	});
+
+	it('positions the marker at the hovered value', () => {
+		render(
+			<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" markerPosition={0.25} />,
+		);
+
+		expect(screen.getByTestId('color-bar-marker')).toHaveStyle({ left: '25%' });
+	});
+
+	it('clamps a marker outside the ramp to its ends', () => {
+		const { rerender } = render(
+			<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" markerPosition={-2} />,
+		);
+		expect(screen.getByTestId('color-bar-marker')).toHaveStyle({ left: '0%' });
+
+		rerender(
+			<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" markerPosition={4} />,
+		);
+		expect(screen.getByTestId('color-bar-marker')).toHaveStyle({ left: '100%' });
+	});
+
+	it('keys the one state a colour ramp cannot express', () => {
+		render(
+			<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" showNoDataKey={true} />,
+		);
+
+		expect(screen.getByText('no data')).toBeInTheDocument();
+	});
+
+	it('leaves the no-data key out unless the data has a gap', () => {
+		render(<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" />);
+
+		expect(screen.queryByText('no data')).not.toBeInTheDocument();
+	});
+
+	it('captions what the colour encodes', () => {
+		render(<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" label="count" />);
+
+		expect(screen.getByText('count')).toBeInTheDocument();
+	});
+
+	it('renders hard-edged segments so the bar matches the drawn cells', () => {
+		render(
+			<ColorBar
+				ramp={['#111111', '#dddddd']}
+				minLabel="0"
+				maxLabel="10"
+				data-testid="scale"
+			/>,
+		);
+
+		const track = screen.getByTestId('scale').querySelector('div');
+		expect(track).toHaveStyle({
+			background:
+				'linear-gradient(to right, #111111 0%, #111111 50%, #dddddd 50%, #dddddd 100%)',
+		});
+	});
+});

frontend/src/lib/uPlotV2/components/Tooltip/ScatterTooltip.module.scss

@@ -0,0 +1,100 @@
+// Surface matches the shared Tooltip: same tokens, same radius, no shadow.
+// Padding lives on the sections so a footer can reach the container edges.
+.container {
+	font-family: 'Inter';
+	font-size: 12px;
+	background: var(--l2-background);
+	-webkit-font-smoothing: antialiased;
+	color: var(--l2-foreground);
+	border-radius: 6px;
+	border: 1px solid var(--l2-border);
+	display: flex;
+	flex-direction: column;
+	min-width: 200px;
+
+	&.pinned {
+		border-color: var(--ring);
+	}
+}
+
+.divider {
+	display: block;
+	width: 100%;
+	height: 1px;
+	background-color: var(--l2-border);
+}
+
+.header {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-2);
+	padding: var(--spacing-3) var(--spacing-4);
+}
+
+// Matches the legend row's marker.
+.marker {
+	width: 10px;
+	height: 10px;
+	border-radius: var(--radius);
+	flex-shrink: 0;
+}
+
+.title {
+	flex: 1;
+	min-width: 0;
+	font-family: var(--font-mono);
+	font-size: var(--font-size-xs);
+	font-weight: 600;
+	color: var(--text-vanilla-100);
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.status {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-1);
+	font-size: 11px;
+	color: var(--text-vanilla-400);
+	flex-shrink: 0;
+}
+
+.rows {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-1);
+	padding: var(--spacing-3) var(--spacing-4);
+}
+
+.row {
+	display: flex;
+	align-items: baseline;
+	justify-content: space-between;
+	gap: var(--spacing-4);
+	font-family: var(--font-mono);
+	font-size: var(--font-size-xs);
+	font-variant-numeric: tabular-nums;
+	color: var(--text-vanilla-100);
+}
+
+// The group values name the point; the channels are what it says.
+.rowMuted {
+	color: var(--text-vanilla-400);
+}
+
+.rowLabel {
+	flex: 1;
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.rowValue {
+	flex: 0 0 auto;
+	max-width: 60%;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}

frontend/src/lib/uPlotV2/components/Tooltip/ScatterTooltip.tsx

@@ -0,0 +1,111 @@
+import { useMemo } from 'react';
+import cx from 'classnames';
+import { Pin } from '@signozhq/icons';
+
+import { ScatterTooltipProps } from '../types';
+import { buildChannelRows, resolveHoveredPoint } from './scatterTooltipContent';
+
+import Styles from './ScatterTooltip.module.scss';
+
+/**
+ * One point, its channels, then the group values that name it. Purpose-built
+ * rather than composed from the shared `Tooltip`, whose list is one row per
+ * series at a shared x; a scatter point has no such neighbours.
+ */
+export default function ScatterTooltip({
+	uPlotInstance,
+	dataIndexes,
+	seriesIndex,
+	channels,
+	resolvePointLabels,
+	decimalPrecision,
+	isPinned,
+	dismiss,
+	renderTooltipFooter,
+}: ScatterTooltipProps): JSX.Element | null {
+	const point = useMemo(
+		() => resolveHoveredPoint(uPlotInstance, seriesIndex, dataIndexes),
+		[uPlotInstance, seriesIndex, dataIndexes],
+	);
+
+	const rows = useMemo(
+		() => (point ? buildChannelRows(point, channels, decimalPrecision) : []),
+		[point, channels, decimalPrecision],
+	);
+
+	const labels = useMemo(
+		() =>
+			point
+				? (resolvePointLabels?.(point.seriesIndex, point.dataIndex) ?? [])
+				: [],
+		[point, resolvePointLabels],
+	);
+
+	if (!point) {
+		return null;
+	}
+
+	return (
+		<div
+			className={cx(Styles.container, { [Styles.pinned]: isPinned })}
+			data-pinned={isPinned}
+			data-testid="scatter-tooltip"
+		>
+			<div className={Styles.header}>
+				<span className={Styles.marker} style={{ backgroundColor: point.color }} />
+				<span
+					className={Styles.title}
+					title={point.label}
+					data-testid="scatter-tooltip-title"
+				>
+					{point.label}
+				</span>
+				{isPinned && (
+					<span className={Styles.status} data-testid="scatter-tooltip-status">
+						<Pin size={12} />
+						<span>Pinned</span>
+					</span>
+				)}
+			</div>
+
+			<span className={Styles.divider} />
+
+			<div className={Styles.rows}>
+				{rows.map((row) => (
+					<div
+						key={row.label}
+						className={Styles.row}
+						data-testid="scatter-tooltip-row"
+					>
+						<span className={Styles.rowLabel}>{row.label}</span>
+						<span className={Styles.rowValue}>{row.value}</span>
+					</div>
+				))}
+			</div>
+
+			{labels.length > 0 && (
+				<>
+					<span className={Styles.divider} />
+					<div className={Styles.rows}>
+						{labels.map((label) => (
+							<div
+								key={label.key}
+								className={cx(Styles.row, Styles.rowMuted)}
+								data-testid="scatter-tooltip-label"
+							>
+								<span className={Styles.rowLabel} title={label.key}>
+									{label.key}
+								</span>
+								<span className={Styles.rowValue} title={label.value}>
+									{label.value}
+								</span>
+							</div>
+						))}
+					</div>
+				</>
+			)}
+
+			{renderTooltipFooter?.({ isPinned, dismiss })}
+		</div>
+	);
+}

frontend/src/lib/uPlotV2/components/Tooltip/__tests__/scatterTooltipContent.test.ts

@@ -0,0 +1,94 @@
+import type uPlot from 'uplot';
+
+import {
+	buildChannelRows,
+	resolveHoveredPoint,
+	ScatterHoveredPoint,
+} from '../scatterTooltipContent';
+
+jest.mock('components/Graph/yAxisConfig', () => ({
+	getToolTipValue: jest.fn((value: number | string, unit?: string) =>
+		`${value} ${unit ?? ''}`.trim(),
+	),
+}));
+
+const plot = {
+	data: [
+		null,
+		[
+			[10, 20],
+			[100, 200],
+			[5, null],
+		],
+		[[30], [300]],
+	],
+	series: [
+		{},
+		{ label: 'cart', stroke: '#ff0000' },
+		{ label: 'checkout', stroke: (): string => '#00ff00' },
+	],
+} as unknown as uPlot;
+
+describe('resolveHoveredPoint', () => {
+	it('reads the focused series at its own data index', () => {
+		expect(resolveHoveredPoint(plot, 1, [null, 1, null])).toStrictEqual({
+			seriesIndex: 1,
+			dataIndex: 1,
+			label: 'cart',
+			color: '#ff0000',
+			x: 20,
+			y: 200,
+			size: null,
+		});
+	});
+
+	it('carries the size column when present and resolves function strokes', () => {
+		expect(resolveHoveredPoint(plot, 1, [null, 0, null])?.size).toBe(5);
+		expect(resolveHoveredPoint(plot, 2, [null, null, 0])).toMatchObject({
+			label: 'checkout',
+			color: '#00ff00',
+			size: null,
+		});
+	});
+
+	it('is null without a focused series or an index for it', () => {
+		expect(resolveHoveredPoint(plot, null, [null, 0, null])).toBeNull();
+		expect(resolveHoveredPoint(plot, 0, [0, 0, null])).toBeNull();
+		expect(resolveHoveredPoint(plot, 1, [null, null, null])).toBeNull();
+	});
+});
+
+describe('buildChannelRows', () => {
+	const point: ScatterHoveredPoint = {
+		seriesIndex: 1,
+		dataIndex: 0,
+		label: 'cart',
+		color: '#f00',
+		x: 12,
+		y: 340,
+		size: 7,
+	};
+
+	it('formats x and y with their own units', () => {
+		const rows = buildChannelRows(point, {
+			x: { label: 'Throughput', unit: 'reqps' },
+			y: { label: 'p99', unit: 'ms' },
+		});
+
+		expect(rows).toStrictEqual([
+			{ label: 'Throughput', value: '12 reqps' },
+			{ label: 'p99', value: '340 ms' },
+		]);
+	});
+
+	it('adds the size row only when the channel is mapped and the point has one', () => {
+		const channels = {
+			x: { label: 'x' },
+			y: { label: 'y' },
+			size: { label: 'Errors' },
+		};
+
+		expect(buildChannelRows(point, channels)).toHaveLength(3);
+		expect(buildChannelRows({ ...point, size: null }, channels)).toHaveLength(2);
+	});
+});

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/HeatmapBucketList.tsx

@@ -0,0 +1,31 @@
+import cx from 'classnames';
+
+import { formatCount } from './heatmapTooltipContent';
+import { HeatmapBucketRow } from './types';
+
+import Styles from './HeatmapTooltip.module.scss';
+
+/** The buckets either side of the hovered one, so a mode reads as a shape rather
+ *  than a single number. */
+export default function HeatmapBucketList({
+	rows,
+}: {
+	rows: HeatmapBucketRow[];
+}): JSX.Element {
+	return (
+		<div className={Styles.rows} data-testid="heatmap-tooltip-buckets">
+			{rows.map((bucket) => (
+				<div
+					key={bucket.row}
+					className={cx(Styles.row, { [Styles.rowHovered]: bucket.isHovered })}
+					data-hovered={bucket.isHovered}
+					data-testid="heatmap-tooltip-bucket-row"
+				>
+					<span className={Styles.rowLabel}>{bucket.label}</span>
+					<span className={Styles.rowSeparator} />
+					<span className={Styles.rowValue}>{formatCount(bucket.count)}</span>
+				</div>
+			))}
+		</div>
+	);
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/HeatmapContributionList.tsx

@@ -0,0 +1,42 @@
+import { formatCount, formatShare } from './heatmapTooltipContent';
+import { HeatmapContributionRow } from './types';
+
+import Styles from './HeatmapTooltip.module.scss';
+
+/** Only shown when the cell sums more than one group. */
+export default function HeatmapContributionList({
+	rows,
+}: {
+	rows: HeatmapContributionRow[];
+}): JSX.Element {
+	return (
+		<div className={Styles.rows} data-testid="heatmap-tooltip-contribution">
+			<div className={Styles.columnHeader}>
+				<span>Group</span>
+				<span>Contribution</span>
+			</div>
+			{rows.map((row) => (
+				<div
+					key={row.label}
+					className={Styles.row}
+					data-testid="heatmap-tooltip-contribution-row"
+				>
+					<span
+						className={Styles.marker}
+						style={{ borderColor: row.color, backgroundColor: row.color }}
+						data-is-legend-marker={true}
+					/>
+					<span className={Styles.rowLabel}>{row.label}</span>
+					<span className={Styles.rowSeparator} style={{ borderColor: row.color }} />
+					<span className={Styles.rowValue}>{formatCount(row.count)}</span>
+					<span
+						className={Styles.rowShare}
+						data-testid="heatmap-tooltip-contribution-share"
+					>
+						{formatShare(row.share)}
+					</span>
+				</div>
+			))}
+		</div>
+	);
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/HeatmapTooltip.module.scss

@@ -0,0 +1,200 @@
+@use '../../../../../../styles/scrollbar' as *;
+
+// Surface matches the shared Tooltip exactly — same tokens, same radius, no
+// shadow (the plugin's portal wrapper is transparent and paints nothing). Text
+// follows the theme through the popover/muted pair; the fixed vanilla ramp reads
+// as white-on-white in light mode.
+//
+// Padding lives on the sections rather than here, also matching the shared
+// tooltip: TooltipFooter draws its own dashed top border, background and bottom
+// corner radius, so it has to reach the container edges.
+.container {
+	// The list pays this less each row's own inset, so its text lands on it too.
+	--gutter: 14px;
+	--row-inset: 6px;
+
+	font-family: 'Inter';
+	font-size: 12px;
+	background: var(--l2-background);
+	-webkit-font-smoothing: antialiased;
+	color: var(--l2-foreground);
+	border-radius: 6px;
+	border: 1px solid var(--l2-border);
+	display: flex;
+	flex-direction: column;
+	min-width: 220px;
+
+	&.pinned {
+		border-color: var(--ring);
+	}
+}
+
+// Separates the cell identity from whichever question the second block answers.
+.divider {
+	display: block;
+	width: 100%;
+	height: 1px;
+	background-color: var(--l2-border);
+}
+
+.identity {
+	display: flex;
+	flex-direction: column;
+}
+
+.header {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: var(--spacing-6);
+	padding: var(--spacing-8) var(--gutter) 0;
+	font-size: var(--font-size-sm);
+	font-weight: 500;
+	font-variant-numeric: tabular-nums;
+}
+
+.filter {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-2);
+	min-width: 0;
+	padding: var(--spacing-3) var(--gutter) 0;
+}
+
+// Names the group the grid is under, as the legend draws a shown series; it is
+// not a colour key.
+.filterMarker {
+	width: 12px;
+	height: 12px;
+	border-radius: var(--radius);
+	border: 1.5px solid currentColor;
+	background: currentColor;
+	box-sizing: border-box;
+	flex-shrink: 0;
+}
+
+.filterLabel {
+	font-family: var(--font-mono);
+	font-size: var(--font-size-xs);
+	letter-spacing: -0.01em;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.title {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: var(--spacing-2);
+	padding: var(--spacing-4) var(--gutter);
+}
+
+.titleBucket,
+.titleCount {
+	font-family: var(--font-mono);
+	font-size: var(--font-size-xs);
+	font-weight: 700;
+	letter-spacing: -0.01em;
+	color: var(--popover-foreground);
+}
+
+.titleCount {
+	font-variant-numeric: tabular-nums;
+	white-space: nowrap;
+}
+
+.rows {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-2);
+	padding: var(--spacing-4) calc(var(--gutter) - var(--row-inset))
+		var(--spacing-6);
+	max-height: 320px;
+	overflow-y: auto;
+
+	@include custom-scrollbar;
+}
+
+.columnHeader {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: var(--spacing-2);
+	padding: 0 var(--row-inset) var(--spacing-2);
+
+	font-family: var(--font-mono);
+	font-size: 10px;
+	letter-spacing: 0.06em;
+	text-transform: uppercase;
+	color: var(--muted-foreground);
+}
+
+.row {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-2);
+	padding: var(--row-inset);
+	border-radius: var(--radius);
+	font-weight: 400;
+	font-variant-numeric: tabular-nums;
+}
+
+// The hovered bucket is the one the cursor is on; lift it out of the neighbours.
+.rowHovered {
+	background: var(--l3-background);
+	font-weight: 700;
+}
+
+.rowLabel,
+.rowValue {
+	font-family: var(--font-mono);
+	font-size: var(--font-size-xs);
+	letter-spacing: -0.01em;
+}
+
+.rowLabel {
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.rowValue {
+	flex: 0 0 auto;
+	text-align: right;
+	white-space: nowrap;
+}
+
+.rowShare {
+	flex: 0 0 auto;
+	min-width: 34px;
+	text-align: right;
+	white-space: nowrap;
+
+	font-family: var(--font-mono);
+	font-size: var(--font-size-xs);
+	letter-spacing: -0.01em;
+	font-variant-numeric: tabular-nums;
+	color: var(--muted-foreground);
+}
+
+.marker {
+	width: 12px;
+	height: 12px;
+	border-radius: var(--radius);
+	border-style: solid;
+	border-width: 1.5px;
+	box-sizing: border-box;
+	flex-shrink: 0;
+}
+
+.rowSeparator,
+.titleSeparator {
+	flex: 1;
+	border-width: 0.5px;
+	border-style: dashed;
+	border-color: currentColor;
+	min-width: 24px;
+	opacity: 0.5;
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/HeatmapTooltip.tsx

@@ -0,0 +1,180 @@
+import { useMemo } from 'react';
+import cx from 'classnames';
+import {
+	resolveColumnIndex,
+	resolveRowIndex,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/geometry';
+import { useTimezone } from 'providers/Timezone';
+
+import { HeatmapTooltipProps } from '../../../types';
+import TooltipPinnedBadge from '../TooltipPinnedBadge/TooltipPinnedBadge';
+import HeatmapBucketList from './HeatmapBucketList';
+import HeatmapContributionList from './HeatmapContributionList';
+import {
+	buildBucketRows,
+	buildContributionRows,
+	formatBucketLabel,
+	formatColumnRange,
+	formatCount,
+	resolveTooltipBody,
+} from './heatmapTooltipContent';
+import { HeatmapTooltipBody } from './types';
+
+import Styles from './HeatmapTooltip.module.scss';
+
+/**
+ * The cell identity is the same in every state; the second block answers whichever
+ * question the panel state leaves open (see `resolveTooltipBody`). Purpose-built
+ * rather than composed from the shared `Tooltip`, which renders a flat list of
+ * series values — none of these states is that shape.
+ *
+ * The cell comes from the live cursor, not a prop: uPlot's `cursor.idx` snaps to
+ * the nearest timestamp, so half of every column would report its neighbour.
+ */
+export default function HeatmapTooltip({
+	uPlotInstance,
+	yAxis,
+	step,
+	series,
+	visibleGroups,
+	groupColor,
+	yAxisUnit,
+	decimalPrecision,
+	timezone,
+	isPinned,
+	dismiss,
+	renderTooltipFooter,
+}: HeatmapTooltipProps): JSX.Element | null {
+	const { timezone: userTimezone } = useTimezone();
+	const resolvedTimezone = timezone?.value ?? userTimezone.value;
+
+	// Read outside the memo: uPlot mutates the same instance on every move, so
+	// keying off the instance alone would freeze the cell.
+	const { left = -10, top = -10 } = uPlotInstance.cursor;
+
+	const cell = useMemo(() => {
+		if (left < 0 || top < 0) {
+			return null;
+		}
+		const timestamps = uPlotInstance.data[0] as ArrayLike<number>;
+		const column = resolveColumnIndex(
+			timestamps,
+			uPlotInstance.posToVal(left, 'x'),
+			step,
+		);
+		const row = resolveRowIndex(yAxis.edges, uPlotInstance.posToVal(top, 'y'));
+		if (column === null || row === null) {
+			return null;
+		}
+		return {
+			row,
+			column,
+			timestamp: timestamps[column],
+			count:
+				(uPlotInstance.data[row + 1] as Array<number | null> | undefined)?.[
+					column
+				] ?? null,
+		};
+	}, [left, top, uPlotInstance, yAxis, step]);
+
+	// The cell sums the enabled groups, so those are what a breakdown must cover.
+	const visible = useMemo(
+		() => series.filter((entry) => visibleGroups.includes(entry.label)),
+		[series, visibleGroups],
+	);
+	const body = resolveTooltipBody(visible.length);
+
+	const bucketRows = useMemo(() => {
+		if (!cell || body !== HeatmapTooltipBody.Buckets) {
+			return [];
+		}
+		return buildBucketRows({
+			counts: uPlotInstance.data.slice(1) as Array<
+				ArrayLike<number | null> | undefined
+			>,
+			yAxis,
+			row: cell.row,
+			column: cell.column,
+			yAxisUnit,
+			decimalPrecision,
+		});
+	}, [cell, body, uPlotInstance, yAxis, yAxisUnit, decimalPrecision]);
+
+	const contributionRows = useMemo(() => {
+		if (!cell || body !== HeatmapTooltipBody.Contribution) {
+			return [];
+		}
+		return buildContributionRows({
+			series: visible,
+			timestamp: cell.timestamp,
+			row: cell.row,
+			color: groupColor,
+		});
+	}, [cell, body, visible, groupColor]);
+
+	if (!cell) {
+		return null;
+	}
+
+	// A single enabled group out of several means the legend has isolated it.
+	const isolated =
+		series.length > 1 && visible.length === 1 ? visible[0] : undefined;
+	const filterLabel = isolated?.label ?? '';
+
+	return (
+		<div
+			className={cx(Styles.container, { [Styles.pinned]: isPinned })}
+			data-pinned={isPinned}
+			data-testid="heatmap-tooltip"
+		>
+			<div className={Styles.identity}>
+				<div className={Styles.header}>
+					<span data-testid="heatmap-tooltip-range">
+						{formatColumnRange({
+							start: cell.timestamp,
+							step,
+							timezone: resolvedTimezone,
+						})}
+					</span>
+					{isPinned && <TooltipPinnedBadge />}
+				</div>
+
+				{filterLabel && (
+					<div
+						className={Styles.filter}
+						style={{ color: groupColor }}
+						data-testid="heatmap-tooltip-filter"
+					>
+						<span className={Styles.filterMarker} />
+						<span className={Styles.filterLabel}>{filterLabel}</span>
+					</div>
+				)}
+
+				<div className={Styles.title}>
+					<span className={Styles.titleBucket} data-testid="heatmap-tooltip-bucket">
+						{formatBucketLabel({
+							yAxis,
+							row: cell.row,
+							yAxisUnit,
+							decimalPrecision,
+						})}
+					</span>
+					<span className={Styles.titleSeparator} />
+					<span className={Styles.titleCount} data-testid="heatmap-tooltip-count">
+						{formatCount(cell.count)}
+					</span>
+				</div>
+			</div>
+
+			<span className={Styles.divider} data-testid="heatmap-tooltip-divider" />
+
+			{body === HeatmapTooltipBody.Contribution ? (
+				<HeatmapContributionList rows={contributionRows} />
+			) : (
+				<HeatmapBucketList rows={bucketRows} />
+			)}
+
+			{renderTooltipFooter?.({ isPinned, dismiss })}
+		</div>
+	);
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/__tests__/HeatmapTooltip.test.tsx

@@ -0,0 +1,305 @@
+import { resolveHeatmapYAxis } from 'lib/uPlotV2/plugins/HeatmapPlugin/geometry';
+import {
+	HeatmapAxisScale,
+	HeatmapSeries,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/types';
+import { render, RenderResult, screen } from 'tests/test-utils';
+import type uPlot from 'uplot';
+
+import HeatmapTooltip from '../HeatmapTooltip';
+
+const BOUNDS = [100, 500, 1000, 2500];
+const Y_AXIS = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Log);
+const TIMESTAMPS = [1_700_000_000, 1_700_000_300];
+const STEP = 300;
+const PLOT_SIZE = 500;
+const ROW_COUNT = BOUNDS.length + 1;
+
+/** Row 2 is the 500ms–1s bucket the design mock hovers. */
+const HOVERED_ROW = 2;
+
+function seriesFor(
+	group: string,
+	countsAtHoveredRow: [number, number],
+): HeatmapSeries {
+	return {
+		label: `{service.name="${group}"}`,
+		points: TIMESTAMPS.map((timestamp, column) => ({
+			timestamp,
+			counts: Array.from({ length: ROW_COUNT }, (_, row) =>
+				row === HOVERED_ROW ? countsAtHoveredRow[column] : row * 10,
+			),
+		})),
+	};
+}
+
+const GROUPED: HeatmapSeries[] = [
+	seriesFor('checkout', [355, 300]),
+	seriesFor('frontend', [86, 80]),
+	seriesFor('cart', [14, 10]),
+	seriesFor('payments', [0, 0]),
+];
+
+/** Grid counts, matching what the renderer would have been handed. */
+function gridData(rowTotals: number[]): uPlot.AlignedData {
+	return [
+		TIMESTAMPS,
+		...Array.from({ length: ROW_COUNT }, (_, row) => [
+			rowTotals[row] ?? row * 40,
+			rowTotals[row] ?? row * 40,
+		]),
+	] as unknown as uPlot.AlignedData;
+}
+
+// Totals chosen to match the mock: 2 / 92 / 455 / 269 / 10 bottom-up.
+const ROW_TOTALS = [10, 269, 455, 92, 2];
+
+function createFakePlot(): uPlot {
+	const xSpan = TIMESTAMPS[TIMESTAMPS.length - 1] + STEP - TIMESTAMPS[0];
+	const ySpan = Y_AXIS.max - Y_AXIS.min;
+	// Aim the cursor at the middle of the hovered row, first column.
+	const rowMid = (Y_AXIS.edges[HOVERED_ROW] + Y_AXIS.edges[HOVERED_ROW + 1]) / 2;
+	const top = PLOT_SIZE * (1 - (rowMid - Y_AXIS.min) / ySpan);
+
+	return {
+		data: gridData(ROW_TOTALS),
+		cursor: { left: PLOT_SIZE * 0.25, top },
+		posToVal: (pos: number, scaleKey: string): number =>
+			scaleKey === 'x'
+				? TIMESTAMPS[0] + (pos / PLOT_SIZE) * xSpan
+				: Y_AXIS.min + ((PLOT_SIZE - pos) / PLOT_SIZE) * ySpan,
+	} as unknown as uPlot;
+}
+
+function renderTooltip(
+	overrides: Partial<React.ComponentProps<typeof HeatmapTooltip>> = {},
+): RenderResult {
+	return render(
+		<HeatmapTooltip
+			id="panel-1"
+			uPlotInstance={createFakePlot()}
+			dataIndexes={[]}
+			seriesIndex={null}
+			isPinned={false}
+			dismiss={jest.fn()}
+			viaSync={false}
+			yAxis={Y_AXIS}
+			step={STEP}
+			series={GROUPED}
+			visibleGroups={GROUPED.map((entry) => entry.label)}
+			groupColor="#fcfdbf"
+			yAxisUnit="ms"
+			{...overrides}
+		/>,
+	);
+}
+
+describe('HeatmapTooltip — cell identity', () => {
+	it('heads with the time span the column covers, not a single instant', () => {
+		renderTooltip();
+
+		expect(screen.getByTestId('heatmap-tooltip-range').textContent).toMatch(
+			/^\d{2}\/\d{2} \d{2}:\d{2} → \d{2}:\d{2}$/,
+		);
+	});
+
+	it('names the hovered bucket and its count', () => {
+		renderTooltip();
+
+		expect(screen.getByTestId('heatmap-tooltip-bucket')).toHaveTextContent(
+			'500 ms – 1 s',
+		);
+		expect(screen.getByTestId('heatmap-tooltip-count')).toHaveTextContent('455');
+	});
+
+	it('marks the surface as pinned so the border picks up the ring', () => {
+		renderTooltip({ isPinned: true });
+
+		expect(screen.getByTestId('heatmap-tooltip')).toHaveAttribute(
+			'data-pinned',
+			'true',
+		);
+	});
+
+	it('names a pinned tooltip in its header, as the shared tooltip does', () => {
+		renderTooltip({ isPinned: true });
+
+		expect(screen.getByTestId('uplot-tooltip-status')).toBeInTheDocument();
+	});
+
+	it('leaves the header unbadged while unpinned', () => {
+		renderTooltip();
+
+		expect(screen.queryByTestId('uplot-tooltip-status')).not.toBeInTheDocument();
+	});
+
+	it('is unpinned by default', () => {
+		renderTooltip();
+
+		expect(screen.getByTestId('heatmap-tooltip')).toHaveAttribute(
+			'data-pinned',
+			'false',
+		);
+	});
+
+	it('separates the cell identity from the block below it', () => {
+		renderTooltip();
+
+		expect(screen.getByTestId('heatmap-tooltip-divider')).toBeInTheDocument();
+	});
+
+	it('renders a footer when the panel supplies one', () => {
+		renderTooltip({
+			renderTooltipFooter: ({ isPinned }): JSX.Element => (
+				<div data-testid="footer">{isPinned ? 'pinned' : 'press P'}</div>
+			),
+		});
+
+		expect(screen.getByTestId('footer')).toHaveTextContent('press P');
+	});
+
+	it('tells the footer when the tooltip is pinned', () => {
+		renderTooltip({
+			isPinned: true,
+			renderTooltipFooter: ({ isPinned }): JSX.Element => (
+				<div data-testid="footer">{isPinned ? 'pinned' : 'press P'}</div>
+			),
+		});
+
+		expect(screen.getByTestId('footer')).toHaveTextContent('pinned');
+	});
+
+	it('renders nothing when the cursor is off the plot', () => {
+		const plot = createFakePlot();
+		(plot as { cursor: unknown }).cursor = { left: -10, top: -10 };
+
+		const { container } = renderTooltip({ uPlotInstance: plot });
+
+		expect(container).toBeEmptyDOMElement();
+	});
+});
+
+describe('HeatmapTooltip — grouped, nothing selected', () => {
+	it('breaks the cell down by group instead of showing neighbours', () => {
+		renderTooltip();
+
+		expect(
+			screen.getByTestId('heatmap-tooltip-contribution'),
+		).toBeInTheDocument();
+		expect(
+			screen.queryByTestId('heatmap-tooltip-buckets'),
+		).not.toBeInTheDocument();
+	});
+
+	it('names each row as the legend does and orders by contribution', () => {
+		renderTooltip();
+
+		const rows = screen
+			.getAllByTestId('heatmap-tooltip-contribution-row')
+			.map((row) => row.textContent);
+
+		expect(rows[0]).toContain('checkout');
+		expect(rows[0]).toContain('355');
+		expect(rows[1]).toContain('frontend');
+		expect(rows[2]).toContain('cart');
+	});
+
+	it('still lists a group that contributed nothing', () => {
+		renderTooltip();
+
+		const rows = screen.getAllByTestId('heatmap-tooltip-contribution-row');
+		expect(rows).toHaveLength(GROUPED.length);
+		expect(rows[3]).toHaveTextContent('payments');
+		expect(rows[3]).toHaveTextContent('0');
+	});
+
+	it('names what the two columns hold', () => {
+		renderTooltip();
+
+		expect(screen.getByText('Group')).toBeInTheDocument();
+		expect(screen.getByText('Contribution')).toBeInTheDocument();
+	});
+
+	it('gives each group its share of the cell alongside the count', () => {
+		renderTooltip();
+
+		const shares = screen
+			.getAllByTestId('heatmap-tooltip-contribution-share')
+			.map((share) => share.textContent);
+
+		expect(shares).toHaveLength(GROUPED.length);
+		expect(
+			shares.reduce((sum, share) => sum + parseInt(share ?? '0', 10), 0),
+		).toBe(100);
+		expect(shares[shares.length - 1]).toBe('0%');
+	});
+
+	it('does not name a filter when every group is enabled', () => {
+		renderTooltip();
+
+		expect(
+			screen.queryByTestId('heatmap-tooltip-filter'),
+		).not.toBeInTheDocument();
+	});
+});
+
+describe('HeatmapTooltip — grouped, one enabled', () => {
+	const selected = { visibleGroups: ['{service.name="checkout"}'] };
+
+	it('returns to neighbouring buckets, since contribution is already answered', () => {
+		renderTooltip(selected);
+
+		expect(screen.getByTestId('heatmap-tooltip-buckets')).toBeInTheDocument();
+		expect(
+			screen.queryByTestId('heatmap-tooltip-contribution'),
+		).not.toBeInTheDocument();
+	});
+
+	it('names the active filter', () => {
+		renderTooltip(selected);
+
+		expect(screen.getByTestId('heatmap-tooltip-filter')).toHaveTextContent(
+			'{service.name="checkout"}',
+		);
+	});
+});
+
+describe('HeatmapTooltip — no grouping', () => {
+	const ungrouped = {
+		series: [{ label: '', points: GROUPED[0].points }],
+		visibleGroups: [''],
+	};
+
+	it('shows neighbouring buckets, highest first', () => {
+		renderTooltip(ungrouped);
+
+		const rows = screen
+			.getAllByTestId('heatmap-tooltip-bucket-row')
+			.map((row) => row.textContent);
+
+		// Two buckets either side of 500ms – 1s, reading down the y axis.
+		expect(rows).toHaveLength(5);
+		expect(rows[0]).toContain('> 2.5 s');
+		expect(rows[2]).toContain('500 ms – 1 s');
+		expect(rows[4]).toContain('≤ 100 ms');
+	});
+
+	it('marks the hovered bucket among its neighbours', () => {
+		renderTooltip(ungrouped);
+
+		const hovered = screen
+			.getAllByTestId('heatmap-tooltip-bucket-row')
+			.filter((row) => row.dataset.hovered === 'true');
+
+		expect(hovered).toHaveLength(1);
+		expect(hovered[0]).toHaveTextContent('500 ms – 1 s');
+	});
+
+	it('never breaks down a single series', () => {
+		renderTooltip(ungrouped);
+
+		expect(
+			screen.queryByTestId('heatmap-tooltip-contribution'),
+		).not.toBeInTheDocument();
+	});
+});

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/__tests__/heatmapTooltipContent.test.ts

@@ -0,0 +1,65 @@
+import { resolveHeatmapYAxis } from 'lib/uPlotV2/plugins/HeatmapPlugin/geometry';
+import { HeatmapAxisScale } from 'lib/uPlotV2/plugins/HeatmapPlugin/types';
+
+import { buildBucketRows, formatColumnRange } from '../heatmapTooltipContent';
+
+const TIMEZONE = 'UTC';
+/** 2026-09-02T05:30:00Z. */
+const START = 1_788_327_000;
+
+/** Two decimals round every one of these to `0.06 ms` or `0.07 ms`. */
+const CLOSE_BOUNDS = [
+	0.05731275270029195, 0.059850205043660856, 0.0625, 0.06526711140171336,
+	0.0681567332915786,
+];
+const CLOSE_Y_AXIS = resolveHeatmapYAxis(CLOSE_BOUNDS, HeatmapAxisScale.Log);
+const COUNTS = CLOSE_Y_AXIS.rows.map((_, row) => [row]);
+
+describe('formatColumnRange', () => {
+	it('dates the column once while it stays inside a day', () => {
+		expect(
+			formatColumnRange({ start: START, step: 9 * 3600, timezone: TIMEZONE }),
+		).toBe('09/02 05:30 → 14:30');
+	});
+
+	it('carries the date across a column that spans days', () => {
+		expect(
+			formatColumnRange({ start: START, step: 2 * 86_400, timezone: TIMEZONE }),
+		).toBe('09/02 05:30 → 09/04 05:30');
+	});
+
+	it('adds seconds for a sub-minute column, which times alone cannot separate', () => {
+		expect(
+			formatColumnRange({ start: START, step: 30, timezone: TIMEZONE }),
+		).toBe('09/02 05:30:00 → 05:30:30');
+	});
+
+	it('reads the day in the panel timezone, not UTC', () => {
+		// 05:30Z is the previous evening in Los Angeles, so the same column reads as
+		// crossing a date boundary there and not in UTC.
+		expect(
+			formatColumnRange({
+				start: START,
+				step: 9 * 3600,
+				timezone: 'America/Los_Angeles',
+			}),
+		).toBe('09/01 22:30 → 09/02 07:30');
+	});
+});
+
+describe('buildBucketRows', () => {
+	it('identifies a row by its place on the axis, which its label cannot', () => {
+		const rows = buildBucketRows({
+			counts: COUNTS,
+			yAxis: CLOSE_Y_AXIS,
+			row: 3,
+			column: 0,
+			yAxisUnit: 'ms',
+			decimalPrecision: 2,
+		});
+
+		expect(new Set(rows.map((row) => row.label)).size).toBeLessThan(rows.length);
+		expect(rows.map((row) => row.row)).toStrictEqual([5, 4, 3, 2, 1]);
+		expect(rows.map((row) => row.count)).toStrictEqual([5, 4, 3, 2, 1]);
+	});
+});

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/heatmapTooltipContent.ts

@@ -0,0 +1,165 @@
+import { PrecisionOption } from 'components/Graph/types';
+import { getToolTipValue } from 'components/Graph/yAxisConfig';
+import { DATE_TIME_FORMATS } from 'constants/dateTimeFormats';
+import dayjs from 'dayjs';
+import { formatRowLabel } from 'lib/uPlotV2/plugins/HeatmapPlugin/geometry';
+import {
+	HeatmapSeries,
+	HeatmapYAxis,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/types';
+import 'utils/timeUtils';
+
+import {
+	HeatmapBucketRow,
+	HeatmapContributionRow,
+	HeatmapTooltipBody,
+} from './types';
+
+/** Rows shown either side of the hovered one. */
+const NEIGHBOUR_SPAN = 2;
+/** Below this, the header needs seconds to distinguish columns. */
+const SUB_MINUTE_STEP = 60;
+
+export const NO_DATA_LABEL = 'no data';
+
+export function resolveTooltipBody(visibleCount: number): HeatmapTooltipBody {
+	// One enabled group contributes the whole cell, so there is nothing to break
+	// down — whether the query is ungrouped or the legend has isolated a group.
+	return visibleCount > 1
+		? HeatmapTooltipBody.Contribution
+		: HeatmapTooltipBody.Buckets;
+}
+
+/** A cell is an interval, so a single instant would misreport what it contains.
+ *  The start carries the date — the x axis prints one only where the day turns
+ *  over — and the end repeats it only across midnight. */
+export function formatColumnRange({
+	start,
+	step,
+	timezone,
+}: {
+	/** Column start, in seconds. */
+	start: number;
+	/** Column width, in seconds. */
+	step: number;
+	timezone: string;
+}): string {
+	const time =
+		step < SUB_MINUTE_STEP
+			? DATE_TIME_FORMATS.TIME_SECONDS
+			: DATE_TIME_FORMATS.TIME;
+	const dated = `${DATE_TIME_FORMATS.DATE_SHORT} ${time}`;
+	const from = dayjs(start * 1000).tz(timezone);
+	const to = dayjs((start + step) * 1000).tz(timezone);
+	const toFormat = to.isSame(from, 'day') ? time : dated;
+	return `${from.format(dated)} → ${to.format(toFormat)}`;
+}
+
+/** Formatted with the panel's unit. */
+export function formatBucketLabel({
+	yAxis,
+	row,
+	yAxisUnit,
+	decimalPrecision,
+}: {
+	yAxis: HeatmapYAxis;
+	row: number;
+	yAxisUnit?: string;
+	decimalPrecision?: PrecisionOption;
+}): string {
+	const bucket = yAxis.rows[row];
+	if (!bucket) {
+		return '';
+	}
+	return formatRowLabel(bucket, (value) =>
+		getToolTipValue(String(value), yAxisUnit, decimalPrecision),
+	);
+}
+
+export function formatCount(count: number | null): string {
+	return count === null ? NO_DATA_LABEL : count.toLocaleString();
+}
+
+/** `<1%` rather than `0%`, so a group that did contribute never reads as one
+ *  that didn't. */
+export function formatShare(share: number): string {
+	if (share > 0 && share < 0.005) {
+		return '<1%';
+	}
+	return `${Math.round(share * 100)}%`;
+}
+
+/** Highest first, so the list reads in the same direction as the y axis. */
+export function buildBucketRows({
+	counts,
+	yAxis,
+	row,
+	column,
+	yAxisUnit,
+	decimalPrecision,
+}: {
+	/** Row-major, as the renderer draws them. */
+	counts: Array<ArrayLike<number | null> | undefined>;
+	yAxis: HeatmapYAxis;
+	row: number;
+	column: number;
+	yAxisUnit?: string;
+	decimalPrecision?: PrecisionOption;
+}): HeatmapBucketRow[] {
+	const formatBucketValue = (value: number): string =>
+		getToolTipValue(String(value), yAxisUnit, decimalPrecision);
+
+	const rows: HeatmapBucketRow[] = [];
+	for (let offset = NEIGHBOUR_SPAN; offset >= -NEIGHBOUR_SPAN; offset -= 1) {
+		const index = row + offset;
+		const bucket = yAxis.rows[index];
+		if (!bucket) {
+			continue;
+		}
+		rows.push({
+			row: index,
+			label: formatRowLabel(bucket, formatBucketValue),
+			count: counts[index]?.[column] ?? null,
+			isHovered: offset === 0,
+		});
+	}
+	return rows;
+}
+
+/**
+ * Largest first. Groups that contributed nothing are still listed — that is an
+ * answer, and dropping the row makes the list look truncated.
+ */
+export function buildContributionRows({
+	series,
+	timestamp,
+	row,
+	color,
+}: {
+	/** Only the groups the legend has enabled — they are what the cell sums. */
+	series: HeatmapSeries[];
+	/** Column start, in seconds. */
+	timestamp: number;
+	row: number;
+	/** The grid's one colour; there is no per-series hue. */
+	color: string;
+}): HeatmapContributionRow[] {
+	const counted = series.map((entry) => {
+		const point = entry.points.find((item) => item.timestamp === timestamp);
+		return {
+			label: entry.label,
+			color,
+			// Absent or null contributed nothing to the sum this breaks down.
+			count: point?.counts[row] ?? 0,
+		};
+	});
+
+	const total = counted.reduce((sum, entry) => sum + entry.count, 0);
+
+	return counted
+		.map((entry) => ({
+			...entry,
+			share: total > 0 ? entry.count / total : 0,
+		}))
+		.sort((a, b) => b.count - a.count);
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/types.ts

@@ -0,0 +1,24 @@
+/** Which question the second block answers: "which group?" for a cell summed
+ *  across several, "how does this bucket compare?" for one that is one series. */
+export enum HeatmapTooltipBody {
+	Buckets = 'buckets',
+	Contribution = 'contribution',
+}
+
+export interface HeatmapBucketRow {
+	/** The bucket's row on the y axis. Labels are not unique — two boundaries can
+	 *  round to the same text — so this is what identifies a row. */
+	row: number;
+	label: string;
+	/** `null` where the bucket has no observation in that column, never a 0. */
+	count: number | null;
+	isHovered: boolean;
+}
+
+export interface HeatmapContributionRow {
+	label: string;
+	color: string;
+	count: number;
+	/** Fraction of the cell this group contributed, 0..1. */
+	share: number;
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/TooltipHeader/TooltipHeader.module.scss

@@ -16,15 +16,3 @@
 .pinnedItem {
 	padding: var(--spacing-4);
 }
-
-.status {
-	display: flex;
-	align-items: center;
-	gap: var(--spacing-1);
-	font-size: 10px;
-	font-weight: 600;
-	text-transform: uppercase;
-	letter-spacing: 0.05em;
-	color: var(--callout-primary-title);
-	flex-shrink: 0;
-}

frontend/src/lib/uPlotV2/components/Tooltip/components/TooltipHeader/TooltipHeader.tsx

@@ -1,13 +1,13 @@
 import { useMemo } from 'react';
 import cx from 'classnames';
 import type { Timezone } from 'components/CustomTimePicker/timezoneUtils';
-import { Pin } from '@signozhq/icons';
 import { useTimezone } from 'providers/Timezone';
 import type uPlot from 'uplot';
 import { formatTimestampOmittingTodaysDate } from 'utils/timeUtils';
 
 import { TooltipContentItem } from '../../../types';
 import TooltipItem from '../TooltipItem/TooltipItem';
+import TooltipPinnedBadge from '../TooltipPinnedBadge/TooltipPinnedBadge';
 
 import Styles from './TooltipHeader.module.scss';
 
@@ -67,14 +67,7 @@ export default function TooltipHeader({
 			{showTooltipHeader && headerTitle && (
 				<div className={cx(Styles.headerRow, headerRowClassName)}>
 					<span>{headerTitle}</span>
-					{isPinned && (
-						<div className={cx(Styles.status)} data-testid="uplot-tooltip-status">
-							<>
-								<Pin size={12} />
-								<span>Pinned</span>
-							</>
-						</div>
-					)}
+					{isPinned && <TooltipPinnedBadge />}
 				</div>
 			)}
 

frontend/src/lib/uPlotV2/components/Tooltip/components/TooltipPinnedBadge/TooltipPinnedBadge.module.scss

@@ -0,0 +1,11 @@
+.status {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-1);
+	font-size: 10px;
+	font-weight: 600;
+	text-transform: uppercase;
+	letter-spacing: 0.05em;
+	color: var(--callout-primary-title);
+	flex-shrink: 0;
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/TooltipPinnedBadge/TooltipPinnedBadge.tsx

@@ -0,0 +1,12 @@
+import { Pin } from '@signozhq/icons';
+
+import Styles from './TooltipPinnedBadge.module.scss';
+
+export default function TooltipPinnedBadge(): JSX.Element {
+	return (
+		<div className={Styles.status} data-testid="uplot-tooltip-status">
+			<Pin size={12} />
+			<span>Pinned</span>
+		</div>
+	);
+}

frontend/src/lib/uPlotV2/components/Tooltip/scatterTooltipContent.ts

@@ -0,0 +1,90 @@
+import { PrecisionOption } from 'components/Graph/types';
+import { getToolTipValue } from 'components/Graph/yAxisConfig';
+import type uPlot from 'uplot';
+
+import type {
+	ScatterChannel,
+	ScatterChannels,
+	ScatterSeriesData,
+} from '../../plugins/ScatterPlugin/types';
+import { resolveSeriesColor } from './utils';
+
+export interface ScatterHoveredPoint {
+	seriesIndex: number;
+	dataIndex: number;
+	label: string;
+	color: string;
+	x: number;
+	y: number;
+	size: number | null;
+}
+
+export interface ScatterTooltipRow {
+	label: string;
+	value: string;
+}
+
+/** The point the cursor resolved to: the focused series' own index into its columns. */
+export function resolveHoveredPoint(
+	u: uPlot,
+	seriesIndex: number | null,
+	dataIndexes: Array<number | null>,
+): ScatterHoveredPoint | null {
+	if (seriesIndex == null || seriesIndex < 1) {
+		return null;
+	}
+	const dataIndex = dataIndexes[seriesIndex];
+	const series = u.series[seriesIndex];
+	const columns = u.data[seriesIndex] as unknown as
+		| ScatterSeriesData
+		| undefined;
+	if (dataIndex == null || !series || !columns) {
+		return null;
+	}
+	const x = columns[0][dataIndex];
+	const y = columns[1][dataIndex];
+	if (x == null || y == null) {
+		return null;
+	}
+	return {
+		seriesIndex,
+		dataIndex,
+		label: String(series.label ?? ''),
+		color: resolveSeriesColor(series.stroke, u, seriesIndex),
+		x,
+		y,
+		size: columns[2]?.[dataIndex] ?? null,
+	};
+}
+
+function formatChannel(
+	value: number,
+	channel: ScatterChannel,
+	decimalPrecision?: PrecisionOption,
+): string {
+	return getToolTipValue(value, channel.unit, decimalPrecision);
+}
+
+export function buildChannelRows(
+	point: ScatterHoveredPoint,
+	channels: ScatterChannels,
+	decimalPrecision?: PrecisionOption,
+): ScatterTooltipRow[] {
+	const rows: ScatterTooltipRow[] = [
+		{
+			label: channels.x.label,
+			value: formatChannel(point.x, channels.x, decimalPrecision),
+		},
+		{
+			label: channels.y.label,
+			value: formatChannel(point.y, channels.y, decimalPrecision),
+		},
+	];
+	if (channels.size && point.size != null) {
+		rows.push({
+			label: channels.size.label,
+			value: formatChannel(point.size, channels.size, decimalPrecision),
+		});
+	}
+	return rows;
+}

frontend/src/lib/uPlotV2/components/types.ts

@@ -5,6 +5,11 @@ import uPlot from 'uplot';
 
 import { UPlotConfigBuilder } from '../config/UPlotConfigBuilder';
 import { LegendItem } from '../config/types';
+import { HeatmapSeries, HeatmapYAxis } from '../plugins/HeatmapPlugin/types';
+import type {
+	ScatterChannels,
+	ScatterPointLabel,
+} from '../plugins/ScatterPlugin/types';
 import { SyncTooltipFilterMode } from '../plugins/TooltipPlugin/types';
 
 /**
@@ -103,6 +108,32 @@ export interface BarTooltipProps extends BaseTooltipProps, TooltipRenderArgs {
 export interface HistogramTooltipProps
 	extends BaseTooltipProps, TooltipRenderArgs {}
 
+/** Not part of `TooltipProps`: it renders its own container, since none of its
+ *  states is the flat series list the shared `Tooltip` draws. */
+export interface HeatmapTooltipProps
+	extends BaseTooltipProps, TooltipRenderArgs {
+	yAxis: HeatmapYAxis;
+	/** Column width in seconds. */
+	step: number;
+	/** Needed to break a summed cell down by contribution. */
+	series: HeatmapSeries[];
+	/** Groups the legend has enabled; the cell sums exactly these. */
+	visibleGroups: string[];
+	/** Same colour the legend and the densest cells use. */
+	groupColor: string;
+}
+
+/** Not part of `TooltipProps`: it describes one point's channels, not a series list. */
+export interface ScatterTooltipProps
+	extends BaseTooltipProps, TooltipRenderArgs {
+	channels: ScatterChannels;
+	/** The group values behind a point, e.g. `service.name` → `cart`. */
+	resolvePointLabels?: (
+		seriesIndex: number,
+		dataIndex: number,
+	) => ScatterPointLabel[];
+}
+
 export type TooltipProps =
 	| TimeSeriesTooltipProps
 	| BarTooltipProps

frontend/src/lib/uPlotV2/config/UPlotAxisBuilder.ts

@@ -39,6 +39,16 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 		};
 	}
 
+	/** The axis line reads as the outermost grid line, so it takes the grid's style. */
+	private buildBorderConfig(
+		grid: uPlot.Axis.Grid | undefined,
+	): uPlot.Axis.Border | undefined {
+		if (this.props.showBorder === false || !grid) {
+			return undefined;
+		}
+		return { show: true, stroke: grid.stroke, width: grid.width };
+	}
+
 	/**
 	 * Build ticks configuration
 	 */
@@ -58,32 +68,49 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 	}
 
 	/**
-	 * Build values formatter for X-axis (time)
+	 * Build values formatter for X-axis: time, or a value axis when a unit or
+	 * precision is given (scatter). Neither leaves uPlot's numeric default.
 	 */
 	private buildXAxisValuesFormatter(): uPlot.Axis.Values | undefined {
-		const { isTimeAxis } = this.props;
+		const { isTimeAxis, yAxisUnit, decimalPrecision } = this.props;
 
 		if (isTimeAxis) {
 			return uPlotXAxisValuesFormat as uPlot.Axis.Values;
 		}
 
+		if (yAxisUnit !== undefined || decimalPrecision !== undefined) {
+			return this.buildValueAxisFormatter();
+		}
+
 		return undefined;
 	}
 
 	/**
-	 * Build values formatter for Y-axis (values with units)
+	 * Build values formatter for a value axis (values with units). A split outside
+	 * the scale's range gets no label: uPlot's arcsinh splits always include
+	 * ±threshold, and it would draw that label past the plot's edge.
 	 */
-	private buildYAxisValuesFormatter(): uPlot.Axis.Values {
-		const { yAxisUnit, decimalPrecision } = this.props;
+	private buildValueAxisFormatter(): uPlot.Axis.Values {
+		const { yAxisUnit, decimalPrecision, scaleKey } = this.props;
 
-		return (_, t): string[] =>
-			t.map((v) => {
-				if (v === null || v === undefined || Number.isNaN(v)) {
+		return (u, t): string[] => {
+			const scale = u?.scales?.[scaleKey];
+			const min = scale?.min ?? -Infinity;
+			const max = scale?.max ?? Infinity;
+			return t.map((v) => {
+				if (
+					v === null ||
+					v === undefined ||
+					Number.isNaN(v) ||
+					v < min ||
+					v > max
+				) {
 					return '';
 				}
 				const value = getToolTipValue(v.toString(), yAxisUnit, decimalPrecision);
 				return `${value}`;
 			});
+		};
 	}
 
 	/**
@@ -101,7 +128,7 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 		return scaleKey === 'x'
 			? this.buildXAxisValuesFormatter()
 			: scaleKey === 'y'
-				? this.buildYAxisValuesFormatter()
+				? this.buildValueAxisFormatter()
 				: undefined;
 	}
 
@@ -148,10 +175,13 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 			show = true,
 			side = 2, // bottom by default
 			space,
+			splits,
+			filter,
 			gap = 5, // default gap is 5
 		} = this.props;
 
 		const grid = this.buildGridConfig();
+		const border = this.buildBorderConfig(grid);
 		const ticks = this.buildTicksConfig();
 		const values = this.buildValuesFormatter();
 		const size = this.buildSizeCalculator();
@@ -176,15 +206,24 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 		if (ticks) {
 			axisConfig.ticks = ticks;
 		}
+		if (border) {
+			axisConfig.border = border;
+		}
 		if (values) {
 			axisConfig.values = values;
 		}
+		if (splits) {
+			axisConfig.splits = splits;
+		}
 		if (gap !== undefined) {
 			axisConfig.gap = gap;
 		}
 		if (space !== undefined) {
 			axisConfig.space = space;
 		}
+		if (filter) {
+			axisConfig.filter = filter;
+		}
 		if (size) {
 			axisConfig.size = size;
 		}

frontend/src/lib/uPlotV2/config/UPlotConfigBuilder.ts

@@ -19,6 +19,7 @@ import {
 	ConfigBuilder,
 	ConfigBuilderProps,
 	LegendItem,
+	PlotMode,
 	SelectionPreferencesSource,
 	StackMode,
 } from './types';
@@ -65,6 +66,8 @@ export class UPlotConfigBuilder extends ConfigBuilder<
 
 	private stackMode: StackMode = StackMode.None;
 
+	private mode: PlotMode = PlotMode.Aligned;
+
 	private cursor: Cursor | undefined;
 
 	private hooks: Hooks.Arrays = {};
@@ -160,6 +163,15 @@ export class UPlotConfigBuilder extends ConfigBuilder<
 		return this.stackMode;
 	}
 
+	/** Faceted series carry their own x column each; see `SeriesProps.facets`. */
+	setMode(mode: PlotMode): void {
+		this.mode = mode;
+	}
+
+	getMode(): PlotMode {
+		return this.mode;
+	}
+
 	/**
 	 * Add or merge a scale configuration
 	 */
@@ -512,6 +524,10 @@ export class UPlotConfigBuilder extends ConfigBuilder<
 			{} as Record<string, uPlot.Scale>,
 		);
 
+		if (this.mode === PlotMode.Faceted) {
+			config.mode = this.mode as number as uPlot.Mode;
+		}
+
 		config.hooks = this.hooks;
 		config.select = this.select;
 

frontend/src/lib/uPlotV2/config/UPlotScaleBuilder.ts

@@ -46,6 +46,12 @@ export class UPlotScaleBuilder extends ConfigBuilder<
 
 		// Special handling for time scales (X axis)
 		if (time) {
+			// A range supplied outright wins: marks spanning an interval have to reach
+			// the end of their last column, past the last timestamp min/max carry.
+			if (range) {
+				return { [scaleKey]: { time: true, auto: false, range } };
+			}
+
 			let minTime = this.min ?? 0;
 			let maxTime = this.max ?? 0;
 
@@ -93,6 +99,7 @@ export class UPlotScaleBuilder extends ConfigBuilder<
 			time,
 			distr,
 			logBase,
+			asinhThreshold: this.props.asinhThreshold,
 		});
 
 		const { rangeConfig, hardMinOnly, hardMaxOnly, hasFixedRange } =

frontend/src/lib/uPlotV2/config/UPlotSeriesBuilder.ts

@@ -87,6 +87,8 @@ export class UPlotSeriesBuilder extends ConfigBuilder<
 			lineConfig.fill = finalFillColor;
 		} else if (this.props.drawStyle === DrawStyle.Histogram) {
 			lineConfig.fill = `${finalFillColor}40`;
+		} else if (this.props.drawStyle === DrawStyle.Scatter) {
+			lineConfig.fill = `${finalFillColor}${toAlphaHex(resolveFillOpacity(fillOpacity))}`;
 		} else if (fillMode && fillMode !== FillMode.None) {
 			const resolvedOpacity = resolveFillOpacity(fillOpacity);
 			if (fillMode === FillMode.Solid) {
@@ -122,7 +124,8 @@ export class UPlotSeriesBuilder extends ConfigBuilder<
 			return { paths: pathBuilder };
 		}
 
-		if (drawStyle === DrawStyle.Points) {
+		// Scatter without a `pathBuilder` has nothing to draw its discs with.
+		if (drawStyle === DrawStyle.Points || drawStyle === DrawStyle.Scatter) {
 			return { paths: (): null => null };
 		}
 
@@ -194,6 +197,10 @@ export class UPlotSeriesBuilder extends ConfigBuilder<
 		if (drawStyle === DrawStyle.Points) {
 			return true;
 		}
+		// The discs are the series path; uPlot's own points would double-draw them.
+		if (drawStyle === DrawStyle.Scatter) {
+			return false;
+		}
 		return !!showPoints;
 	}
 
@@ -218,7 +225,7 @@ export class UPlotSeriesBuilder extends ConfigBuilder<
 	}
 
 	getConfig(): ExtendedSeries {
-		const { scaleKey, label, spanGaps, show = true, metric } = this.props;
+		const { scaleKey, label, spanGaps, show = true, metric, facets } = this.props;
 
 		const resolvedLineColor = this.getLineColor();
 
@@ -246,6 +253,7 @@ export class UPlotSeriesBuilder extends ConfigBuilder<
 			...pathConfig,
 			points: Object.keys(pointsConfig).length > 0 ? pointsConfig : undefined,
 			metric,
+			...(facets && { facets }),
 		};
 	}
 }

frontend/src/lib/uPlotV2/config/__tests__/UPlotAxisBuilder.test.ts

@@ -120,6 +120,35 @@ describe('UPlotAxisBuilder', () => {
 		});
 	});
 
+	it('draws the axis line by default, styled like the grid', () => {
+		const config = new UPlotAxisBuilder(
+			createAxisProps({ isDarkMode: true, grid: { width: 0.5 } }),
+		).getConfig();
+
+		expect(config.border).toStrictEqual({
+			show: true,
+			stroke: config.grid?.stroke,
+			width: 0.5,
+		});
+	});
+
+	it('leaves the axis line off when showBorder is false', () => {
+		expect(
+			new UPlotAxisBuilder(createAxisProps({ showBorder: false })).getConfig(),
+		).not.toHaveProperty('border');
+	});
+
+	it('passes explicit splits and a label filter through to uPlot', () => {
+		const splits = jest.fn();
+		const filter = jest.fn();
+		const config = new UPlotAxisBuilder(
+			createAxisProps({ splits, filter }),
+		).getConfig();
+
+		expect(config.splits).toBe(splits);
+		expect(config.filter).toBe(filter);
+	});
+
 	it('uses provided ticks config when present and falls back to defaults otherwise', () => {
 		const customTicks = { width: 1, show: false };
 		const withTicks = new UPlotAxisBuilder(
@@ -376,3 +405,51 @@ describe('UPlotAxisBuilder', () => {
 		expect(config.values).toBeDefined();
 	});
 });
+
+describe('UPlotAxisBuilder value x axis', () => {
+	it('formats a non-time x axis with its unit', () => {
+		(getToolTipValue as jest.Mock).mockReturnValue('1.2K req/s');
+		const config = new UPlotAxisBuilder(
+			createAxisProps({ scaleKey: 'x', isTimeAxis: false, yAxisUnit: 'reqps' }),
+		).getConfig();
+
+		const values = (config.values as uPlot.Axis.DynamicValues)(
+			{} as uPlot,
+			[1200],
+			0,
+			0,
+			0,
+		);
+
+		expect(values).toStrictEqual(['1.2K req/s']);
+		expect(getToolTipValue).toHaveBeenCalledWith('1200', 'reqps', undefined);
+	});
+
+	it('leaves a non-time x axis to uPlot when nothing says how to format it', () => {
+		const config = new UPlotAxisBuilder(
+			createAxisProps({ scaleKey: 'x', isTimeAxis: false }),
+		).getConfig();
+
+		expect(config.values).toBeUndefined();
+	});
+});
+
+describe('UPlotAxisBuilder out-of-range splits', () => {
+	it('leaves a split the scale cannot place unlabelled', () => {
+		(getToolTipValue as jest.Mock).mockImplementation((v: string) => `${v} ms`);
+		const config = new UPlotAxisBuilder(
+			createAxisProps({ scaleKey: 'y', yAxisUnit: 'ms' }),
+		).getConfig();
+		const u = { scales: { y: { min: 0, max: 1000 } } } as unknown as uPlot;
+
+		const values = (config.values as uPlot.Axis.DynamicValues)(
+			u,
+			[-10, 0, 500, 5000],
+			0,
+			0,
+			0,
+		);
+
+		expect(values).toStrictEqual(['', '0 ms', '500 ms', '']);
+	});
+});

frontend/src/lib/uPlotV2/config/__tests__/UPlotConfigBuilder.test.ts

@@ -5,7 +5,12 @@ import {
 	STEP_INTERVAL_MULTIPLIER,
 } from '../../constants';
 import type { SeriesProps } from '../types';
-import { DrawStyle, SelectionPreferencesSource, StackMode } from '../types';
+import {
+	DrawStyle,
+	PlotMode,
+	SelectionPreferencesSource,
+	StackMode,
+} from '../types';
 import { UPlotConfigBuilder } from '../UPlotConfigBuilder';
 
 // Mock only the real boundary that hits localStorage
@@ -651,3 +656,15 @@ describe('UPlotConfigBuilder stacking', () => {
 		expect(builder.getConfig().bands).toStrictEqual([{ series: [1, 3] }]);
 	});
 });
+
+describe('UPlotConfigBuilder plot mode', () => {
+	it('leaves mode unset for aligned data and emits 2 when faceted', () => {
+		const aligned = new UPlotConfigBuilder({ id: 'aligned' });
+		expect(aligned.getConfig().mode).toBeUndefined();
+
+		const faceted = new UPlotConfigBuilder({ id: 'faceted' });
+		faceted.setMode(PlotMode.Faceted);
+		expect(faceted.getMode()).toBe(PlotMode.Faceted);
+		expect(faceted.getConfig().mode).toBe(2);
+	});
+});

frontend/src/lib/uPlotV2/config/__tests__/UPlotSeriesBuilder.test.ts

@@ -399,3 +399,39 @@ describe('UPlotSeriesBuilder', () => {
 		expect(builder.getConfig().fill).toBeUndefined();
 	});
 });
+
+describe('UPlotSeriesBuilder scatter', () => {
+	it('draws through the given path builder and hides uPlot points', () => {
+		const pathBuilder = jest.fn();
+		const config = new UPlotSeriesBuilder(
+			createBaseProps({
+				drawStyle: DrawStyle.Scatter,
+				pathBuilder,
+				facets: [{ scale: 'x' }, { scale: 'y' }],
+				lineColor: '#ff0000',
+				fillOpacity: 0.5,
+				lineWidth: 1,
+				pointSize: 8,
+			}),
+		).getConfig();
+
+		expect(config.paths).toBe(pathBuilder);
+		expect(config.facets).toStrictEqual([{ scale: 'x' }, { scale: 'y' }]);
+		expect(config.points?.show).toBe(false);
+		expect(config.points?.size).toBe(8);
+		expect(config.stroke).toBe('#ff0000');
+		expect(config.width).toBe(1);
+		expect(config.fill).toBe('#ff000080');
+	});
+
+	it('draws nothing without a path builder', () => {
+		const config = new UPlotSeriesBuilder(
+			createBaseProps({ drawStyle: DrawStyle.Scatter }),
+		).getConfig();
+
+		expect(
+			(config.paths as uPlot.Series.PathBuilder)({} as uPlot, 1, 0, 0),
+		).toBeNull();
+		expect(config.facets).toBeUndefined();
+	});
+});

frontend/src/lib/uPlotV2/config/types.ts

@@ -78,6 +78,12 @@ export interface AxisProps {
 	};
 	/** Explicit tick formatter, replacing the scale's default (time / unit-formatted). */
 	values?: uPlot.Axis.Values;
+	/** Explicit tick positions, replacing uPlot's per-distribution default. */
+	splits?: uPlot.Axis.Splits;
+	/** Which splits get a label, replacing uPlot's per-distribution default. */
+	filter?: uPlot.Axis.Filter;
+	/** Draw the axis line along the plot edge, styled like the grid. Default true. */
+	showBorder?: boolean;
 	/** Pixels between the ticks and their labels; also feeds the y axis width calculation. */
 	gap?: number;
 	/** Explicit axis thickness. Left unset, the y axis sizes itself to its widest label. */
@@ -88,7 +94,8 @@ export interface AxisProps {
 	isDarkMode?: boolean;
 	/** Axis is on a log scale — thins the grid lines to keep dense decades readable. */
 	isLogScale?: boolean;
-	/** Unit the y axis ticks are formatted in (`spec.formatting.unit`). */
+	/** Unit the value ticks are formatted in (`spec.formatting.unit`). Named for the
+	 *  y axis, the only value axis until scatter; a non-time x axis reads it too. */
 	yAxisUnit?: string;
 	/**
 	 * X axis carries timestamps, so its ticks format as dates/times. Declared by the caller
@@ -107,6 +114,15 @@ export interface AxisProps {
 export enum DistributionType {
 	Linear = 'linear',
 	Logarithmic = 'logarithmic',
+	/** arcsinh: linear within ±`asinhThreshold`, logarithmic beyond. Takes zero and
+	 *  negatives, which a plain log cannot place. */
+	SymmetricLog = 'symlog',
+}
+
+/** uPlot's data layout: one shared x per chart, or per-series x/y columns. */
+export enum PlotMode {
+	Aligned = 1,
+	Faceted = 2,
 }
 
 export interface ScaleProps {
@@ -123,6 +139,8 @@ export interface ScaleProps {
 	auto?: boolean;
 	logBase?: uPlot.Scale.LogBase;
 	distribution?: DistributionType;
+	/** Half-width of a `SymmetricLog` scale's linear band around zero. Default 1. */
+	asinhThreshold?: number;
 }
 
 export enum DisconnectedValuesMode {
@@ -144,6 +162,8 @@ export enum DrawStyle {
 	Points = 'points',
 	Bar = 'bar',
 	Histogram = 'histogram',
+	/** Faceted (mode 2) discs at per-series x/y, drawn by the caller's `pathBuilder`. */
+	Scatter = 'scatter',
 }
 
 export enum LineInterpolation {
@@ -227,6 +247,8 @@ export interface SeriesProps extends LineConfig, PointsConfig, BarConfig {
 	isDarkMode?: boolean;
 	stepInterval?: number;
 	metric?: { [key: string]: string };
+	/** Mode 2 only: the scales the series' own x and y columns are read against. */
+	facets?: Series.Facet[];
 }
 
 export interface LegendItem {

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/__tests__/colorScale.test.ts

@@ -0,0 +1,290 @@
+import { Color } from '@signozhq/design-tokens';
+
+import {
+	clampColorSteps,
+	createHeatmapColorResolver,
+	DEFAULT_COLOR_STEPS,
+	DEFAULT_HEATMAP_COLORS,
+	getMaxCount,
+	getSmallestPositiveCount,
+	MAX_COLOR_STEPS,
+	MIN_OPACITY_ALPHA,
+	normalizeCount,
+	resolveCountDomain,
+} from '../colorScale';
+import { HeatmapColorMode, HeatmapColorScale } from '../types';
+
+const SERIES_COLOR = '#4e74f8';
+
+describe('getMaxCount', () => {
+	it('ignores null cells', () => {
+		expect(
+			getMaxCount([
+				[1, null, 9],
+				[null, 4],
+			]),
+		).toBe(9);
+	});
+
+	it('returns 0 for an empty or all-null grid', () => {
+		expect(getMaxCount([])).toBe(0);
+		expect(getMaxCount([[null, null]])).toBe(0);
+	});
+
+	it('ignores non-finite counts', () => {
+		expect(getMaxCount([[3, Number.POSITIVE_INFINITY, Number.NaN]])).toBe(3);
+	});
+});
+
+describe('getSmallestPositiveCount', () => {
+	it('ignores nulls, zeros and non-finite counts', () => {
+		expect(
+			getSmallestPositiveCount([
+				[0, null, 4],
+				[Number.NaN, 2, -3],
+			]),
+		).toBe(2);
+	});
+
+	it('returns null when nothing is above zero', () => {
+		expect(getSmallestPositiveCount([[0, null]])).toBeNull();
+	});
+});
+
+describe('resolveCountDomain', () => {
+	it('floors at 0 on auto so a zero count sits at the bottom of the scale', () => {
+		expect(
+			resolveCountDomain({ minCount: null, maxCount: null }, [[5, 20]]),
+		).toStrictEqual({
+			min: 0,
+			max: 20,
+			logFloor: 5,
+		});
+	});
+
+	it('honours explicit clamps', () => {
+		expect(
+			resolveCountDomain({ minCount: 10, maxCount: 100 }, [[5, 20]]),
+		).toStrictEqual({
+			min: 10,
+			max: 100,
+			logFloor: 5,
+		});
+	});
+
+	it('collapses a max at or below min', () => {
+		expect(
+			resolveCountDomain({ minCount: 50, maxCount: 10 }, [[5]]),
+		).toStrictEqual({
+			min: 50,
+			max: 50,
+			logFloor: 5,
+		});
+	});
+
+	it('takes the log floor from the smallest positive count, below 1 included', () => {
+		expect(
+			resolveCountDomain({ minCount: null, maxCount: null }, [[0, 0.02, 0.8]])
+				.logFloor,
+		).toBeCloseTo(0.02, 6);
+	});
+
+	it('keeps the log floor within MAX_LOG_DECADES of the max', () => {
+		expect(
+			resolveCountDomain({ minCount: null, maxCount: null }, [[1, 1e9]]).logFloor,
+		).toBe(1e3);
+	});
+
+	it('falls back to a floor of 1 for a grid without a positive count', () => {
+		expect(
+			resolveCountDomain({ minCount: null, maxCount: null }, [[null, 0]]).logFloor,
+		).toBe(1);
+	});
+});
+
+describe('normalizeCount', () => {
+	const domain = { min: 0, max: 1000, logFloor: 1 };
+
+	it('spreads low counts on a log scale where a linear one washes them out', () => {
+		const log = (count: number): number =>
+			normalizeCount({ count, domain, scale: HeatmapColorScale.Log });
+
+		expect(log(10)).toBeCloseTo(1 / 3, 5);
+		expect(log(20)).toBeCloseTo(Math.log10(20) / 3, 5);
+		expect(
+			normalizeCount({ count: 10, domain, scale: HeatmapColorScale.Linear }),
+		).toBeCloseTo(0.01, 5);
+	});
+
+	it('puts 0 and 1 at the bottom of a log scale', () => {
+		expect(
+			normalizeCount({ count: 0, domain, scale: HeatmapColorScale.Log }),
+		).toBe(0);
+		expect(
+			normalizeCount({ count: 1, domain, scale: HeatmapColorScale.Log }),
+		).toBe(0);
+	});
+
+	it('reaches the top of the scale at max on every scale', () => {
+		[
+			HeatmapColorScale.Log,
+			HeatmapColorScale.Sqrt,
+			HeatmapColorScale.Linear,
+		].forEach((scale) => {
+			expect(normalizeCount({ count: 1000, domain, scale })).toBeCloseTo(1, 6);
+		});
+	});
+
+	it('takes the square root of the linear position on a sqrt scale', () => {
+		expect(
+			normalizeCount({
+				count: 250,
+				domain: { min: 0, max: 1000, logFloor: 1 },
+				scale: HeatmapColorScale.Sqrt,
+			}),
+		).toBeCloseTo(0.5, 6);
+	});
+
+	it('clamps counts outside the domain', () => {
+		const scale = HeatmapColorScale.Linear;
+		expect(normalizeCount({ count: -5, domain, scale })).toBe(0);
+		expect(normalizeCount({ count: 5000, domain, scale })).toBe(1);
+	});
+
+	it('returns the bottom of the scale when min equals max', () => {
+		expect(
+			normalizeCount({
+				count: 7,
+				domain: { min: 7, max: 7, logFloor: 1 },
+				scale: HeatmapColorScale.Log,
+			}),
+		).toBe(0);
+	});
+
+	it('spreads a log domain that sits entirely below a count of 1', () => {
+		const fractional = { min: 0, max: 1, logFloor: 0.001 };
+		const log = (count: number): number =>
+			normalizeCount({
+				count,
+				domain: fractional,
+				scale: HeatmapColorScale.Log,
+			});
+
+		expect(log(0.001)).toBe(0);
+		expect(log(0.1)).toBeCloseTo(2 / 3, 5);
+		expect(log(1)).toBeCloseTo(1, 6);
+	});
+
+	it('reads a log scale linearly when the floor reaches the top of the domain', () => {
+		const domainAtFloor = { min: 0, max: 1, logFloor: 1 };
+
+		expect(
+			normalizeCount({
+				count: 1,
+				domain: domainAtFloor,
+				scale: HeatmapColorScale.Log,
+			}),
+		).toBe(1);
+		expect(
+			normalizeCount({
+				count: 0.5,
+				domain: domainAtFloor,
+				scale: HeatmapColorScale.Log,
+			}),
+		).toBe(0.5);
+	});
+});
+
+describe('clampColorSteps', () => {
+	it('clamps to the supported range', () => {
+		expect(clampColorSteps(1)).toBe(2);
+		expect(clampColorSteps(500)).toBe(MAX_COLOR_STEPS);
+		expect(clampColorSteps(32)).toBe(32);
+	});
+
+	it('falls back to the default for a non-finite value', () => {
+		expect(clampColorSteps(Number.NaN)).toBe(DEFAULT_COLOR_STEPS);
+	});
+});
+
+describe('createHeatmapColorResolver', () => {
+	const build = (
+		overrides: Partial<typeof DEFAULT_HEATMAP_COLORS> = {},
+		isDarkMode = true,
+	): ReturnType<typeof createHeatmapColorResolver> =>
+		createHeatmapColorResolver({
+			options: { ...DEFAULT_HEATMAP_COLORS, ...overrides },
+			domain: { min: 0, max: 1000, logFloor: 1 },
+			isDarkMode,
+			seriesColor: SERIES_COLOR,
+		});
+
+	it('leaves null cells uncoloured so they can be hatched', () => {
+		const resolver = build();
+
+		expect(resolver.colorFor(null)).toBeNull();
+		expect(resolver.positionOf(null)).toBeNull();
+	});
+
+	it('recedes a zero count into the surface, not the null treatment', () => {
+		const dark = build();
+		const light = build({}, false);
+
+		expect(dark.colorFor(0)).toBe(Color.BG_INK_500);
+		expect(light.colorFor(0)).toBe(Color.BG_VANILLA_100);
+	});
+
+	it('keeps the bottom of the ramp for the smallest count that occurred', () => {
+		const resolver = build();
+
+		// Zero and the floor both sit at position 0; only the floor takes a colour.
+		expect(resolver.colorFor(1)).toBe(resolver.ramp[0]);
+	});
+
+	it('colours zero off the ramp once an explicit minimum lifts it off the bottom', () => {
+		const resolver = createHeatmapColorResolver({
+			options: { ...DEFAULT_HEATMAP_COLORS, minCount: 5 },
+			domain: { min: 5, max: 1000, logFloor: 5 },
+			isDarkMode: true,
+			seriesColor: SERIES_COLOR,
+		});
+
+		expect(resolver.colorFor(0)).toBe(resolver.ramp[0]);
+	});
+
+	it('emits one ramp entry per step', () => {
+		expect(build({ steps: 8 }).ramp).toHaveLength(8);
+	});
+
+	it('maps the max count to the top of the ramp', () => {
+		const resolver = build({ steps: 8 });
+
+		expect(resolver.colorFor(1000)).toBe(resolver.ramp[7]);
+	});
+
+	it('picks different stops per theme so low counts stay near the surface', () => {
+		expect(build({}, true).ramp[0]).not.toBe(build({}, false).ramp[0]);
+	});
+
+	it('varies alpha in opacity mode, never below the visibility floor', () => {
+		const resolver = build({ mode: HeatmapColorMode.Opacity, steps: 4 });
+
+		expect(resolver.ramp[0]).toBe(`rgba(78, 116, 248, ${MIN_OPACITY_ALPHA})`);
+		// `color` drops the alpha channel from the string once it reaches 1.
+		expect(resolver.ramp[3]).toBe('rgb(78, 116, 248)');
+	});
+
+	it('prefers an explicit opacity fill over the series colour', () => {
+		const resolver = build({
+			mode: HeatmapColorMode.Opacity,
+			fill: '#e5484d',
+			steps: 2,
+		});
+
+		expect(resolver.ramp[1]).toBe('rgb(229, 72, 77)');
+	});
+
+	it('reports the domain it applied', () => {
+		expect(build().domain).toStrictEqual({ min: 0, max: 1000, logFloor: 1 });
+	});
+});

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/__tests__/geometry.test.ts

@@ -0,0 +1,706 @@
+import {
+	canUseLogAxis,
+	cropHeatmapYAxis,
+	decimateAxisSplits,
+	formatRowLabel,
+	resolveColumnAlignedSplits,
+	resolveColumnIndex,
+	resolveHeatmapYAxis,
+	resolveRowIndex,
+} from '../geometry';
+import { HeatmapAxisScale } from '../types';
+
+const BOUNDS = [128, 256, 1024, 4096];
+
+describe('canUseLogAxis', () => {
+	it('accepts strictly positive bounds', () => {
+		expect(canUseLogAxis(BOUNDS)).toBe(true);
+	});
+
+	it('rejects a zero or negative bound', () => {
+		expect(canUseLogAxis([0, 128])).toBe(false);
+		expect(canUseLogAxis([-1, 128])).toBe(false);
+	});
+
+	it('rejects empty bounds', () => {
+		expect(canUseLogAxis([])).toBe(false);
+	});
+});
+
+describe('resolveHeatmapYAxis', () => {
+	it('turns N bounds into N+1 rows with underflow and overflow at the ends', () => {
+		const { rows } = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Log);
+
+		expect(rows).toHaveLength(BOUNDS.length + 1);
+		expect(rows[0]).toMatchObject({
+			upper: 128,
+			isUnderflow: true,
+			isOverflow: false,
+		});
+		expect(rows[1]).toMatchObject({ lower: 128, upper: 256 });
+		expect(rows[4]).toMatchObject({
+			lower: 4096,
+			isOverflow: true,
+			isUnderflow: false,
+		});
+	});
+
+	it('exposes one edge per row boundary, ascending', () => {
+		const { rows, edges } = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Log);
+
+		expect(edges).toHaveLength(rows.length + 1);
+		expect([...edges].sort((a, b) => a - b)).toStrictEqual(edges);
+	});
+
+	it('places bounds in log space so row heights are log-proportional', () => {
+		const { splits, min, max } = resolveHeatmapYAxis(
+			BOUNDS,
+			HeatmapAxisScale.Log,
+		);
+
+		expect(splits).toStrictEqual(BOUNDS.map((bound) => Math.log10(bound)));
+		// Geometric mean ratio (4096/128)^(1/3) = 3.174…, two of them for the
+		// overflow row.
+		expect(10 ** min).toBeCloseTo(128 / (4096 / 128) ** (1 / 3), 6);
+		expect(10 ** max).toBeCloseTo(4096 * (4096 / 128) ** (2 / 3), 6);
+	});
+
+	it('keeps bounds in value space on a linear axis', () => {
+		const { splits, min } = resolveHeatmapYAxis(
+			[10, 20, 30],
+			HeatmapAxisScale.Linear,
+		);
+
+		expect(splits).toStrictEqual([10, 20, 30]);
+		// Mean gap is 10, and the underflow edge never crosses zero.
+		expect(min).toBe(0);
+	});
+
+	it('sorts and de-duplicates bounds', () => {
+		const { rows, splits } = resolveHeatmapYAxis(
+			[256, 128, 256, Number.NaN],
+			HeatmapAxisScale.Log,
+		);
+
+		expect(splits).toStrictEqual([Math.log10(128), Math.log10(256)]);
+		expect(rows).toHaveLength(3);
+	});
+
+	it('gives a single bound an underflow and an overflow row', () => {
+		const { rows, edges } = resolveHeatmapYAxis([100], HeatmapAxisScale.Log);
+
+		expect(rows).toHaveLength(2);
+		expect(rows[0].isUnderflow).toBe(true);
+		expect(rows[1].isOverflow).toBe(true);
+		expect(edges).toHaveLength(3);
+	});
+
+	it('degrades to an empty axis with no bounds', () => {
+		expect(resolveHeatmapYAxis([], HeatmapAxisScale.Log).rows).toStrictEqual([]);
+	});
+
+	it('puts the overflow label on the row"s upper edge, clear of the last boundary', () => {
+		const { overflowSplit, edges } = resolveHeatmapYAxis(
+			BOUNDS,
+			HeatmapAxisScale.Log,
+		);
+
+		// A full row above the last boundary tick, so the two labels cannot collide.
+		expect(overflowSplit).toBe(edges[edges.length - 1]);
+	});
+});
+
+describe('resolveRowIndex', () => {
+	const { edges } = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Linear);
+
+	it('finds the row containing a value', () => {
+		expect(resolveRowIndex(edges, 200)).toBe(1);
+		expect(resolveRowIndex(edges, 2000)).toBe(3);
+	});
+
+	it('assigns a boundary to the row it opens', () => {
+		expect(resolveRowIndex(edges, 256)).toBe(2);
+	});
+
+	it('returns the last row on the top edge', () => {
+		expect(resolveRowIndex(edges, edges[edges.length - 1])).toBe(
+			edges.length - 2,
+		);
+	});
+
+	it('returns null outside the grid', () => {
+		expect(resolveRowIndex(edges, edges[0] - 1)).toBeNull();
+		expect(resolveRowIndex(edges, edges[edges.length - 1] + 1)).toBeNull();
+	});
+
+	it('returns null without at least one row', () => {
+		expect(resolveRowIndex([5], 5)).toBeNull();
+	});
+});
+
+describe('resolveColumnIndex', () => {
+	const timestamps = [100, 160, 220, 280];
+	const step = 60;
+
+	it('resolves by containment, not proximity', () => {
+		// 155 is nearer to 160, but the observations at 155 belong to column 0.
+		expect(resolveColumnIndex(timestamps, 155, step)).toBe(0);
+		expect(resolveColumnIndex(timestamps, 160, step)).toBe(1);
+	});
+
+	it('includes the column start and excludes its end', () => {
+		expect(resolveColumnIndex(timestamps, 100, step)).toBe(0);
+		expect(resolveColumnIndex(timestamps, 159.9, step)).toBe(0);
+	});
+
+	it('covers the trailing column using the step, not the next timestamp', () => {
+		expect(resolveColumnIndex(timestamps, 330, step)).toBe(3);
+		expect(resolveColumnIndex(timestamps, 340, step)).toBeNull();
+	});
+
+	it('returns null before the first column', () => {
+		expect(resolveColumnIndex(timestamps, 99, step)).toBeNull();
+	});
+
+	it('returns null with no columns', () => {
+		expect(resolveColumnIndex([], 100, step)).toBeNull();
+	});
+
+	it('leaves the last column open when the step is unknown', () => {
+		expect(resolveColumnIndex(timestamps, 10_000, 0)).toBe(3);
+	});
+});
+
+describe('formatRowLabel', () => {
+	const format = (value: number): string => `${value}ms`;
+	const { rows } = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Log);
+
+	it('labels the underflow row by its only real bound', () => {
+		expect(formatRowLabel(rows[0], format)).toBe('≤ 128ms');
+	});
+
+	it('labels the overflow row by its only real bound', () => {
+		expect(formatRowLabel(rows[rows.length - 1], format)).toBe('> 4096ms');
+	});
+
+	it('labels an interior row as a range', () => {
+		expect(formatRowLabel(rows[1], format)).toBe('128ms – 256ms');
+	});
+});
+
+describe('decimateAxisSplits', () => {
+	const splits = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+	const domain = { min: 0, max: 10 };
+
+	it('keeps every tick when they all fit', () => {
+		expect(
+			decimateAxisSplits({ ...domain, splits, plotHeight: 400, minGapPx: 18 }),
+		).toStrictEqual(splits);
+	});
+
+	it('thins to whatever fits at the available height', () => {
+		// 11 ticks over 100px is 10px apart; an 18px floor keeps every other one.
+		expect(
+			decimateAxisSplits({ ...domain, splits, plotHeight: 100, minGapPx: 18 }),
+		).toStrictEqual([0, 2, 4, 6, 8, 10]);
+	});
+
+	it('always keeps the topmost tick, so the overflow edge survives thinning', () => {
+		const thinned = decimateAxisSplits({
+			...domain,
+			splits,
+			plotHeight: 40,
+			minGapPx: 18,
+		});
+
+		expect(thinned[thinned.length - 1]).toBe(10);
+	});
+
+	it('returns ascending positions', () => {
+		const thinned = decimateAxisSplits({
+			...domain,
+			splits,
+			plotHeight: 60,
+			minGapPx: 18,
+		});
+
+		expect([...thinned].sort((a, b) => a - b)).toStrictEqual(thinned);
+	});
+
+	it('thins by pixel distance, not index, so uneven rows are handled', () => {
+		// Three boundaries bunched at the bottom of a wide linear domain: only the
+		// first and the far-away last are far enough apart to both get labels.
+		expect(
+			decimateAxisSplits({
+				splits: [1, 2, 3, 1000],
+				min: 0,
+				max: 1000,
+				plotHeight: 200,
+				minGapPx: 18,
+			}),
+		).toStrictEqual([3, 1000]);
+	});
+
+	it('leaves the tick set alone when it cannot measure', () => {
+		expect(
+			decimateAxisSplits({ ...domain, splits, plotHeight: 0, minGapPx: 18 }),
+		).toStrictEqual(splits);
+		expect(
+			decimateAxisSplits({
+				splits,
+				min: 5,
+				max: 5,
+				plotHeight: 400,
+				minGapPx: 18,
+			}),
+		).toStrictEqual(splits);
+	});
+});
+
+describe('resolveHeatmapYAxis — the scale auto picks', () => {
+	// The OTel SDK default explicit bucket boundaries, which start at zero.
+	const OTEL = [
+		0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000,
+	];
+	// Clock skew in ms — a logs/traces field that straddles zero.
+	const SKEW = [-1000, -100, -10, -1, 0, 1, 10, 100, 1000];
+
+	const PLOT_HEIGHT = 250;
+
+	/** Row heights in axis units, less the deliberately taller overflow row. */
+	function rowHeights(bounds: number[]): number[] {
+		const { edges } = resolveHeatmapYAxis(bounds, HeatmapAxisScale.Auto);
+		return edges.slice(1, -1).map((edge, index) => edge - edges[index]);
+	}
+
+	/** Shortest row, in pixels, for a plot of `PLOT_HEIGHT`. */
+	function shortestRowPx(bounds: number[], scale: HeatmapAxisScale): number {
+		const { edges } = resolveHeatmapYAxis(bounds, scale);
+		const span = edges[edges.length - 1] - edges[0];
+		const heights = edges
+			.slice(1)
+			.map((edge, index) => ((edge - edges[index]) / span) * PLOT_HEIGHT);
+		return Math.min(...heights);
+	}
+
+	it('keeps a zero boundary on a log axis instead of giving up to linear', () => {
+		const { splits } = resolveHeatmapYAxis([0, 5, 10], HeatmapAxisScale.Auto);
+
+		// A linear fallback would leave the boundaries untransformed.
+		expect(splits).not.toStrictEqual([0, 5, 10]);
+	});
+
+	it('is what an all-positive layout does NOT get — that stays a plain log', () => {
+		const { splits } = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Auto);
+
+		expect(splits).toStrictEqual(BOUNDS.map((bound) => Math.log10(bound)));
+	});
+
+	it('gives every row a usable height for the OTel default boundaries', () => {
+		// Linear squeezes the 0–100ms buckets — where the data is — under a pixel.
+		expect(shortestRowPx(OTEL, HeatmapAxisScale.Linear)).toBeLessThan(1);
+		expect(shortestRowPx(OTEL, HeatmapAxisScale.Auto)).toBeGreaterThan(4);
+	});
+
+	it('gives the row above zero one bucket of height, not a whole decade', () => {
+		const heights = rowHeights(OTEL);
+		const { rows } = resolveHeatmapYAxis(OTEL, HeatmapAxisScale.Auto);
+		const nearZero = rows.findIndex((row) => row.lower === 0 && row.upper === 5);
+		const positive = OTEL.filter((bound) => bound > 0);
+		const bucket =
+			(Math.log10(positive[positive.length - 1]) - Math.log10(positive[0])) /
+			(positive.length - 1);
+
+		expect(heights[nearZero]).toBeCloseTo(bucket, 6);
+	});
+
+	it('reads a lone zero boundary as a log layout, not a zero-crossing one', () => {
+		expect(resolveHeatmapYAxis(OTEL, HeatmapAxisScale.Auto).edges).toStrictEqual(
+			resolveHeatmapYAxis(OTEL, HeatmapAxisScale.Log).edges,
+		);
+	});
+
+	it('turns to symlog once a boundary reaches below zero', () => {
+		expect(resolveHeatmapYAxis(SKEW, HeatmapAxisScale.Auto).edges).toStrictEqual(
+			resolveHeatmapYAxis(SKEW, HeatmapAxisScale.Symlog).edges,
+		);
+	});
+
+	it('places boundaries either side of zero symmetrically', () => {
+		const heights = rowHeights(SKEW);
+
+		expect(Math.max(...heights) - Math.min(...heights)).toBeCloseTo(0, 6);
+	});
+
+	it('draws the overflow row taller than a bucket, so its edge reads as one', () => {
+		const { edges } = resolveHeatmapYAxis(SKEW, HeatmapAxisScale.Auto);
+		const overflowHeight = edges[edges.length - 1] - edges[edges.length - 2];
+
+		expect(overflowHeight).toBeGreaterThan(Math.max(...rowHeights(SKEW)));
+	});
+
+	it('keeps negative boundaries ascending', () => {
+		const { edges } = resolveHeatmapYAxis(SKEW, HeatmapAxisScale.Auto);
+
+		expect([...edges].sort((a, b) => a - b)).toStrictEqual(edges);
+	});
+
+	it('round-trips a boundary back to its bucket value', () => {
+		const { splits, toBucketValue } = resolveHeatmapYAxis(
+			SKEW,
+			HeatmapAxisScale.Auto,
+		);
+
+		expect(
+			splits.map((split) => Math.round(toBucketValue(split) * 1e6) / 1e6),
+		).toStrictEqual(SKEW);
+	});
+
+	it('derives the linear threshold from the smallest non-zero boundary', () => {
+		// Threshold 10 puts -10 at -1 and 0 at 0 in axis space.
+		const { edges, rows } = resolveHeatmapYAxis(
+			[-100, -10, 0, 10, 100],
+			HeatmapAxisScale.Auto,
+		);
+		const crossing = rows.findIndex(
+			(row) => row.lower === -10 && row.upper === 0,
+		);
+
+		expect(edges[crossing]).toBeCloseTo(-1, 6);
+		expect(edges[crossing + 1]).toBeCloseTo(0, 6);
+	});
+
+	it('leaves an all-positive layout on a plain log axis', () => {
+		const { splits } = resolveHeatmapYAxis(
+			[128, 256, 1024],
+			HeatmapAxisScale.Auto,
+		);
+
+		expect(splits).toStrictEqual([128, 256, 1024].map((b) => Math.log10(b)));
+	});
+
+	it('falls back to linear when every boundary is zero', () => {
+		const { splits } = resolveHeatmapYAxis([0], HeatmapAxisScale.Auto);
+
+		expect(splits).toStrictEqual([0]);
+	});
+});
+
+describe('resolveHeatmapYAxis — an explicitly chosen scale', () => {
+	// The low end of the OTel SDK defaults: a zero bucket, then positive bounds.
+	const ZERO_HEAD = [0, 5, 10, 25];
+	// Clock skew in ms — a field that straddles zero.
+	const SKEW = [-100, -10, 0, 10, 100];
+
+	/** Row heights in axis units, less the deliberately taller overflow row. */
+	function rowHeights(bounds: number[], scale: HeatmapAxisScale): number[] {
+		const { edges } = resolveHeatmapYAxis(bounds, scale);
+		return edges.slice(1, -1).map((edge, index) => edge - edges[index]);
+	}
+
+	it('log stays a plain log10 for a positive layout', () => {
+		const { splits } = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Log);
+
+		expect(splits).toStrictEqual(BOUNDS.map((bound) => Math.log10(bound)));
+	});
+
+	it('log keeps its own answer for a zero bucket rather than becoming a symlog', () => {
+		const { splits } = resolveHeatmapYAxis(ZERO_HEAD, HeatmapAxisScale.Log);
+		// One bucket below the smallest positive bound, where a symlog would put it
+		// a whole decade below.
+		const gap = (Math.log10(25) - Math.log10(5)) / 2;
+
+		expect(splits[0]).toBeCloseTo(Math.log10(5) - gap, 6);
+		expect(splits.slice(1)).toStrictEqual([5, 10, 25].map((b) => Math.log10(b)));
+	});
+
+	it('log spends a bucket on the zero-crossing row where symlog spends a decade', () => {
+		const gap = (Math.log10(25) - Math.log10(5)) / 2;
+
+		// Row 1 is (0, 5] — the row above the zero bucket.
+		expect(rowHeights(ZERO_HEAD, HeatmapAxisScale.Log)[1]).toBeCloseTo(gap, 6);
+		expect(rowHeights(ZERO_HEAD, HeatmapAxisScale.Symlog)[1]).toBeCloseTo(1, 6);
+	});
+
+	it('log leaves every edge ascending with a zero bucket in the layout', () => {
+		const { edges } = resolveHeatmapYAxis(ZERO_HEAD, HeatmapAxisScale.Log);
+
+		expect([...edges].sort((a, b) => a - b)).toStrictEqual(edges);
+	});
+
+	it('log squashes several non-positive boundaries onto one edge — what symlog is for', () => {
+		const { edges } = resolveHeatmapYAxis(SKEW, HeatmapAxisScale.Log);
+
+		// -100, -10 and 0 have no logarithm and share the floor.
+		expect(edges[1]).toBe(edges[2]);
+		expect(edges[2]).toBe(edges[3]);
+		expect([...edges].sort((a, b) => a - b)).toStrictEqual(edges);
+	});
+
+	it('log has nothing to compress without a positive boundary and stays linear', () => {
+		const { splits } = resolveHeatmapYAxis([-5, 0], HeatmapAxisScale.Log);
+
+		expect(splits).toStrictEqual([-5, 0]);
+	});
+
+	it('symlog is a choice for a positive layout too, and is not the log axis', () => {
+		const positive = [1, 10, 100];
+
+		expect(
+			resolveHeatmapYAxis(positive, HeatmapAxisScale.Log).splits,
+		).toStrictEqual([0, 1, 2]);
+		// Threshold 1: the boundaries sit a decade apart, one unit above the linear band.
+		expect(
+			resolveHeatmapYAxis(positive, HeatmapAxisScale.Symlog).splits,
+		).toStrictEqual([1, 2, 3]);
+	});
+
+	it('symlog places boundaries either side of zero symmetrically', () => {
+		const heights = rowHeights(SKEW, HeatmapAxisScale.Symlog);
+
+		expect(Math.max(...heights) - Math.min(...heights)).toBeCloseTo(0, 6);
+	});
+
+	it('symlog has no magnitude to scale against when every boundary is zero', () => {
+		const { splits } = resolveHeatmapYAxis([0], HeatmapAxisScale.Symlog);
+
+		expect(splits).toStrictEqual([0]);
+	});
+});
+
+describe('cropHeatmapYAxis', () => {
+	// Four bounds, so five rows: underflow, three buckets, overflow.
+	const AXIS = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Log);
+
+	const counts = (perRow: Array<number | null>): Array<Array<number | null>> =>
+		perRow.map((count) => [count]);
+
+	it('stops one row above the highest occupied one', () => {
+		const cropped = cropHeatmapYAxis(AXIS, counts([3, 7, 0, 0, 0]));
+
+		expect(cropped.max).toBe(AXIS.edges[3]);
+		expect(cropped.splits).toStrictEqual(AXIS.splits.slice(0, 3));
+	});
+
+	it('drops the infinity tick once its row is off the top', () => {
+		const cropped = cropHeatmapYAxis(AXIS, counts([3, 7, 0, 0, 0]));
+
+		expect(cropped.overflowSplit).toBeNull();
+	});
+
+	it('keeps the rows intact, so a bucket is never relabelled', () => {
+		const cropped = cropHeatmapYAxis(AXIS, counts([3, 7, 0, 0, 0]));
+
+		expect(cropped.rows).toStrictEqual(AXIS.rows);
+		expect(cropped.edges).toStrictEqual(AXIS.edges);
+	});
+
+	it('leaves the axis alone when the top row is occupied', () => {
+		expect(cropHeatmapYAxis(AXIS, counts([0, 0, 0, 0, 2]))).toStrictEqual(AXIS);
+	});
+
+	it('leaves the axis alone when the row below the top is occupied', () => {
+		expect(cropHeatmapYAxis(AXIS, counts([0, 0, 0, 9, 0]))).toStrictEqual(AXIS);
+	});
+
+	it('treats zero and no-data cells alike — neither occupies a row', () => {
+		const cropped = cropHeatmapYAxis(AXIS, counts([4, 0, null, null, null]));
+
+		expect(cropped.max).toBe(AXIS.edges[2]);
+	});
+
+	it('leaves an entirely empty grid alone, having nothing to crop against', () => {
+		expect(
+			cropHeatmapYAxis(AXIS, counts([null, null, null, null, null])),
+		).toStrictEqual(AXIS);
+	});
+});
+
+describe('resolveColumnAlignedSplits', () => {
+	const MINUTE = 60;
+	const HOUR = 3600;
+	const DAY = 86400;
+
+	/** uPlot's `tzDate` for a fixed-offset zone: the returned date's local fields
+	 *  read as that zone's wall clock, whatever the machine's own zone is. */
+	const zoneAt =
+		(offsetSeconds: number) =>
+		(timestamp: number): Date => {
+			const browserOffset =
+				-new Date(timestamp * 1e3).getTimezoneOffset() * MINUTE;
+			return new Date((timestamp + offsetSeconds - browserOffset) * 1e3);
+		};
+
+	const UTC = zoneAt(0);
+	/** IST, whose half-hour offset is what pulls ticks off round local times. */
+	const IST = zoneAt(5.5 * HOUR);
+	/** 2024-03-11T00:00:00Z, a Monday. */
+	const MIDNIGHT_UTC = 1_710_115_200;
+
+	it('lands every tick on a column edge', () => {
+		const step = 90;
+		const anchor = 1_700_000_010;
+
+		const splits = resolveColumnAlignedSplits({
+			anchor,
+			step,
+			incr: 5 * MINUTE,
+			min: anchor,
+			max: anchor + 40 * step,
+		});
+
+		expect(splits.length).toBeGreaterThan(1);
+		splits.forEach((split) => {
+			expect((split - anchor) % step).toBe(0);
+		});
+	});
+
+	it('rounds the increment up to a whole number of columns', () => {
+		const splits = resolveColumnAlignedSplits({
+			anchor: 0,
+			step: 90,
+			incr: 5 * MINUTE,
+			min: 0,
+			max: HOUR,
+			toDate: UTC,
+		});
+
+		// 300s asked for, 360s is the next multiple of the 90s column.
+		expect(splits[1] - splits[0]).toBe(360);
+	});
+
+	it('covers the visible range without overshooting it', () => {
+		const splits = resolveColumnAlignedSplits({
+			anchor: 1000,
+			step: 100,
+			incr: 200,
+			min: 1050,
+			max: 1650,
+			toDate: UTC,
+		});
+
+		expect(splits[0]).toBeGreaterThanOrEqual(1050);
+		expect(splits[splits.length - 1]).toBeLessThanOrEqual(1650);
+		expect(splits[0] - 200).toBeLessThan(1050);
+	});
+
+	it("starts hourly ticks on the timezone's own hour, not the epoch's", () => {
+		const args = {
+			anchor: MIDNIGHT_UTC,
+			step: 5 * MINUTE,
+			incr: HOUR,
+			min: MIDNIGHT_UTC,
+			max: MIDNIGHT_UTC + 3 * HOUR,
+		};
+
+		// 05:30 IST is midnight UTC, so the two disagree by the half hour.
+		expect(resolveColumnAlignedSplits({ ...args, toDate: UTC })).toStrictEqual([
+			MIDNIGHT_UTC,
+			MIDNIGHT_UTC + HOUR,
+			MIDNIGHT_UTC + 2 * HOUR,
+			MIDNIGHT_UTC + 3 * HOUR,
+		]);
+		expect(resolveColumnAlignedSplits({ ...args, toDate: IST })).toStrictEqual([
+			MIDNIGHT_UTC + 0.5 * HOUR,
+			MIDNIGHT_UTC + 1.5 * HOUR,
+			MIDNIGHT_UTC + 2.5 * HOUR,
+		]);
+	});
+
+	it('gives up the round local time when no column edge carries one', () => {
+		// Hour-wide columns start on the UTC hour, so 00:00 IST is mid-cell and
+		// the nearest edge — 00:30 IST — is as close as the grid gets.
+		const splits = resolveColumnAlignedSplits({
+			anchor: MIDNIGHT_UTC,
+			step: HOUR,
+			incr: HOUR,
+			min: MIDNIGHT_UTC,
+			max: MIDNIGHT_UTC + 2 * HOUR,
+			toDate: IST,
+		});
+
+		expect(splits).toStrictEqual([
+			MIDNIGHT_UTC,
+			MIDNIGHT_UTC + HOUR,
+			MIDNIGHT_UTC + 2 * HOUR,
+		]);
+	});
+
+	it('puts a daily tick on the local day boundary', () => {
+		const splits = resolveColumnAlignedSplits({
+			anchor: MIDNIGHT_UTC,
+			step: 15 * MINUTE,
+			incr: DAY,
+			min: MIDNIGHT_UTC,
+			max: MIDNIGHT_UTC + 3 * DAY,
+			toDate: IST,
+		});
+
+		// 18:30 UTC the previous day is IST midnight, and 15m columns carry it.
+		expect(splits).toHaveLength(3);
+		splits.forEach((split) => {
+			expect(IST(split).getHours()).toBe(0);
+			expect(IST(split).getMinutes()).toBe(0);
+		});
+	});
+
+	it('walks month ticks as calendar dates, snapped to column edges', () => {
+		const splits = resolveColumnAlignedSplits({
+			anchor: MIDNIGHT_UTC,
+			step: DAY,
+			incr: 28 * DAY,
+			min: MIDNIGHT_UTC,
+			max: MIDNIGHT_UTC + 120 * DAY,
+			toDate: UTC,
+		});
+
+		// Month starts, not a drifting 28-day cadence that repeats a month name.
+		expect(
+			splits.map((split) => new Date(split * 1e3).toISOString()),
+		).toStrictEqual([
+			'2024-04-01T00:00:00.000Z',
+			'2024-05-01T00:00:00.000Z',
+			'2024-06-01T00:00:00.000Z',
+			'2024-07-01T00:00:00.000Z',
+		]);
+	});
+
+	it("falls back to uPlot's own increment without a column width", () => {
+		expect(
+			resolveColumnAlignedSplits({
+				anchor: MIDNIGHT_UTC,
+				step: 0,
+				incr: 5 * MINUTE,
+				min: MIDNIGHT_UTC,
+				max: MIDNIGHT_UTC + 15 * MINUTE,
+				toDate: UTC,
+			}),
+		).toStrictEqual([
+			MIDNIGHT_UTC,
+			MIDNIGHT_UTC + 5 * MINUTE,
+			MIDNIGHT_UTC + 10 * MINUTE,
+			MIDNIGHT_UTC + 15 * MINUTE,
+		]);
+	});
+
+	it('has nothing to place on an empty or inverted range', () => {
+		expect(
+			resolveColumnAlignedSplits({
+				anchor: 0,
+				step: MINUTE,
+				incr: MINUTE,
+				min: 10,
+				max: 10,
+			}),
+		).toStrictEqual([]);
+		expect(
+			resolveColumnAlignedSplits({
+				anchor: 0,
+				step: MINUTE,
+				incr: 0,
+				min: 0,
+				max: 100,
+			}),
+		).toStrictEqual([]);
+	});
+});

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/__tests__/grid.test.ts

@@ -0,0 +1,176 @@
+import { resolveHeatmapGrid } from '../grid';
+import { HeatmapSeries } from '../types';
+
+const BUCKETS = [10, 20];
+const STEP = 60;
+
+/** Two groups over two columns, each missing a value the other reports. */
+const TWO_GROUPS: HeatmapSeries[] = [
+	{
+		label: 'cart',
+		points: [
+			{ timestamp: 60, counts: [1, 2, 3] },
+			{ timestamp: 120, counts: [null, 5, 6] },
+		],
+	},
+	{
+		label: 'checkout',
+		points: [
+			{ timestamp: 60, counts: [10, 20, 30] },
+			{ timestamp: 120, counts: [40, null, 60] },
+		],
+	},
+];
+
+function resolve(
+	overrides: Partial<Parameters<typeof resolveHeatmapGrid>[0]> = {},
+): ReturnType<typeof resolveHeatmapGrid> {
+	return resolveHeatmapGrid({
+		buckets: BUCKETS,
+		step: STEP,
+		series: TWO_GROUPS,
+		...overrides,
+	});
+}
+
+describe('resolveHeatmapGrid', () => {
+	it('pivots per-timestamp count arrays into one row per bucket', () => {
+		const { counts } = resolve({ series: [TWO_GROUPS[0]] });
+
+		// 2 boundaries describe 3 rows; each row spans both columns.
+		expect(counts).toStrictEqual([
+			[1, null],
+			[2, 5],
+			[3, 6],
+		]);
+	});
+
+	it('carries the bounds and step through untouched', () => {
+		const { bounds, step } = resolve();
+
+		expect(bounds).toStrictEqual(BUCKETS);
+		expect(step).toBe(STEP);
+	});
+
+	it('sums every group for the combined view', () => {
+		const { counts } = resolve();
+
+		expect(counts[0]).toStrictEqual([11, 40]);
+		expect(counts[2]).toStrictEqual([33, 66]);
+	});
+
+	it('keeps one group"s count where the other has no data', () => {
+		const { counts } = resolve();
+
+		// cart is null at 120 in row 0 while checkout reports 40.
+		expect(counts[0][1]).toBe(40);
+		// checkout is null at 120 in row 1 while cart reports 5.
+		expect(counts[1][1]).toBe(5);
+	});
+
+	it('reports a cell as no-data only when every group is missing it', () => {
+		const { counts } = resolve({
+			buckets: [10],
+			series: [
+				{ label: 'a', points: [{ timestamp: 60, counts: [null, null] }] },
+				{ label: 'b', points: [{ timestamp: 60, counts: [null, null] }] },
+			],
+		});
+
+		expect(counts).toStrictEqual([[null], [null]]);
+	});
+
+	it('distinguishes a zero count from no data', () => {
+		const { counts } = resolve({
+			buckets: [10],
+			series: [{ label: 'a', points: [{ timestamp: 60, counts: [0, null] }] }],
+		});
+
+		expect(counts[0][0]).toBe(0);
+		expect(counts[1][0]).toBeNull();
+	});
+
+	it('sums only the groups the legend has enabled', () => {
+		const { counts } = resolve({ visibleGroups: ['cart'] });
+
+		expect(counts[0]).toStrictEqual([1, null]);
+		expect(counts[2]).toStrictEqual([3, 6]);
+	});
+
+	it('sums every group when the legend passes nothing', () => {
+		const { counts } = resolve({ visibleGroups: undefined });
+
+		expect(counts[0]).toStrictEqual([11, 40]);
+	});
+
+	it('ignores an enabled label that left the result', () => {
+		const { counts } = resolve({ visibleGroups: ['cart', 'gone'] });
+
+		expect(counts[0]).toStrictEqual([1, null]);
+	});
+
+	it('empties the grid when every group is excluded', () => {
+		const { timestamps, counts } = resolve({ visibleGroups: [] });
+
+		expect(timestamps).toStrictEqual([]);
+		expect(counts.every((row) => row.length === 0)).toBe(true);
+	});
+
+	it('unions timestamps when groups do not align', () => {
+		const { timestamps, counts } = resolve({
+			buckets: [10],
+			series: [
+				{ label: 'a', points: [{ timestamp: 60, counts: [1, 2] }] },
+				{ label: 'b', points: [{ timestamp: 180, counts: [3, 4] }] },
+			],
+		});
+
+		expect(timestamps).toStrictEqual([60, 180]);
+		expect(counts[0]).toStrictEqual([1, 3]);
+	});
+
+	it('sorts columns ascending regardless of response order', () => {
+		const { timestamps } = resolve({
+			buckets: [10],
+			series: [
+				{
+					label: 'a',
+					points: [
+						{ timestamp: 180, counts: [1, 2] },
+						{ timestamp: 60, counts: [3, 4] },
+					],
+				},
+			],
+		});
+
+		expect(timestamps).toStrictEqual([60, 180]);
+	});
+
+	it('pads rows the response left short', () => {
+		const { counts } = resolve({
+			buckets: [10, 20, 30],
+			series: [{ label: 'a', points: [{ timestamp: 60, counts: [1, 2] }] }],
+		});
+
+		expect(counts).toStrictEqual([[1], [2], [null], [null]]);
+	});
+
+	it('ignores counts beyond the bucket rows', () => {
+		const { counts } = resolve({
+			buckets: [10],
+			series: [{ label: 'a', points: [{ timestamp: 60, counts: [1, 2, 99] }] }],
+		});
+
+		expect(counts).toStrictEqual([[1], [2]]);
+	});
+
+	it('degrades to an empty grid with no buckets or no series', () => {
+		expect(resolve({ buckets: [] })).toStrictEqual({
+			bounds: [],
+			timestamps: [],
+			step: 0,
+			counts: [],
+		});
+		expect(resolve({ series: [] }).counts).toStrictEqual([]);
+	});
+});

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/__tests__/heatmapPlugin.test.ts

@@ -0,0 +1,314 @@
+import type uPlot from 'uplot';
+
+import { DEFAULT_HEATMAP_COLORS } from '../colorScale';
+import { resolveHeatmapYAxis } from '../geometry';
+import { createHeatmapHooks } from '../heatmapPlugin';
+import { HeatmapAxisScale, HeatmapCell } from '../types';
+
+const BOUNDS = [100, 1000];
+const Y_AXIS = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Linear);
+const TIMESTAMPS = [1000, 1060, 1120];
+const STEP = 60;
+const PLOT_WIDTH = 300;
+const PLOT_HEIGHT = 300;
+
+// Three rows for two bounds, three columns; row 1 column 1 is a data gap.
+const DATA = [
+	TIMESTAMPS,
+	[1, 2, 3],
+	[4, null, 6],
+	[7, 8, 9],
+] as unknown as uPlot.AlignedData;
+
+interface FakeContext {
+	fillRect: jest.Mock;
+	fills: string[];
+}
+
+interface FakePlot {
+	plot: uPlot;
+	context: FakeContext;
+	setSeries: jest.Mock;
+	over: HTMLDivElement;
+}
+
+function createFakePlot(cursor: { left: number; top: number }): FakePlot {
+	const over = document.createElement('div');
+	Object.defineProperty(over, 'clientWidth', { value: PLOT_WIDTH });
+	Object.defineProperty(over, 'clientHeight', { value: PLOT_HEIGHT });
+
+	const fills: string[] = [];
+	const fillRect = jest.fn();
+	const context = { fills, fillRect };
+	const setSeries = jest.fn();
+
+	const xSpan = TIMESTAMPS[TIMESTAMPS.length - 1] + STEP - TIMESTAMPS[0];
+	const ySpan = Y_AXIS.max - Y_AXIS.min;
+
+	const ctx = {
+		save: jest.fn(),
+		restore: jest.fn(),
+		beginPath: jest.fn(),
+		rect: jest.fn(),
+		clip: jest.fn(),
+		moveTo: jest.fn(),
+		lineTo: jest.fn(),
+		stroke: jest.fn(),
+		setLineDash: jest.fn(),
+		createPattern: jest.fn(() => null),
+		set fillStyle(value: string) {
+			fills.push(value);
+		},
+		fillRect: (...args: number[]): void => {
+			fillRect(...args);
+		},
+	};
+
+	const plot = {
+		data: DATA,
+		cursor,
+		over,
+		setSeries,
+		ctx,
+		bbox: { left: 0, top: 0, width: PLOT_WIDTH, height: PLOT_HEIGHT },
+		scales: { x: { min: TIMESTAMPS[0], max: TIMESTAMPS[2] + STEP } },
+		// x grows left to right; y is inverted, so the highest bucket is at the top.
+		valToPos: (value: number, scaleKey: string): number =>
+			scaleKey === 'x'
+				? ((value - TIMESTAMPS[0]) / xSpan) * PLOT_WIDTH
+				: PLOT_HEIGHT - ((value - Y_AXIS.min) / ySpan) * PLOT_HEIGHT,
+		posToVal: (pos: number, scaleKey: string): number =>
+			scaleKey === 'x'
+				? TIMESTAMPS[0] + (pos / PLOT_WIDTH) * xSpan
+				: Y_AXIS.min + ((PLOT_HEIGHT - pos) / PLOT_HEIGHT) * ySpan,
+	};
+
+	return { plot: plot as unknown as uPlot, context, setSeries, over };
+}
+
+/** Cursor `top` at the centre of `row`, so naming a cell does not also mean
+ *  knowing how tall the rows are. */
+function topOfRow(row: number): number {
+	const centre = (Y_AXIS.edges[row] + Y_AXIS.edges[row + 1]) / 2;
+	return (
+		PLOT_HEIGHT -
+		((centre - Y_AXIS.min) / (Y_AXIS.max - Y_AXIS.min)) * PLOT_HEIGHT
+	);
+}
+
+function createHooks(
+	onHoverChange?: (cell: HeatmapCell | null) => void,
+	dimOnHover = true,
+): ReturnType<typeof createHeatmapHooks> {
+	return createHeatmapHooks({
+		yAxis: Y_AXIS,
+		step: STEP,
+		colors: DEFAULT_HEATMAP_COLORS,
+		isDarkMode: true,
+		seriesColor: '#4e74f8',
+		dimOnHover,
+		onHoverChange,
+	});
+}
+
+describe('heatmap renderer — lifecycle', () => {
+	it('mounts the hover overlay into the plot overlay and tears it down', () => {
+		const hooks = createHooks();
+		const { plot, over } = createFakePlot({ left: -10, top: -10 });
+
+		hooks.init(plot);
+		expect(
+			over.querySelector('[data-testid="heatmap-hover-overlay"]'),
+		).not.toBeNull();
+
+		hooks.destroy(plot);
+		expect(
+			over.querySelector('[data-testid="heatmap-hover-overlay"]'),
+		).toBeNull();
+	});
+});
+
+describe('heatmap renderer — draw', () => {
+	it('paints every cell of every visible column', () => {
+		const hooks = createHooks();
+		const { plot, context } = createFakePlot({ left: -10, top: -10 });
+
+		hooks.init(plot);
+		hooks.draw(plot);
+
+		// 3 rows x 3 columns, less the one null cell that has no hatch pattern
+		// available under jsdom.
+		expect(context.fillRect).toHaveBeenCalledTimes(8);
+	});
+
+	it('gives a zero count the bottom-of-scale fill rather than skipping it', () => {
+		const hooks = createHooks();
+		const zeroed = [TIMESTAMPS, [0, 0, 0], [0, 0, 0], [0, 0, 0]];
+		const { plot, context } = createFakePlot({ left: -10, top: -10 });
+		(plot as { data: unknown }).data = zeroed;
+
+		hooks.init(plot);
+		hooks.draw(plot);
+
+		expect(context.fillRect).toHaveBeenCalledTimes(9);
+		expect(new Set(context.fills).size).toBe(1);
+	});
+
+	it('skips columns outside the current x range', () => {
+		const hooks = createHooks();
+		const { plot, context } = createFakePlot({ left: -10, top: -10 });
+		(plot as { scales: unknown }).scales = {
+			x: { min: TIMESTAMPS[0], max: TIMESTAMPS[0] + STEP },
+		};
+
+		hooks.init(plot);
+		hooks.draw(plot);
+
+		// Only the first two columns overlap the range; the third starts past its end.
+		// 2 columns x 3 rows, less the null cell in column 1.
+		expect(context.fillRect).toHaveBeenCalledTimes(5);
+	});
+
+	it('draws nothing without columns', () => {
+		const hooks = createHooks();
+		const { plot, context } = createFakePlot({ left: -10, top: -10 });
+		(plot as { data: unknown }).data = [[]];
+
+		hooks.init(plot);
+		hooks.draw(plot);
+
+		expect(context.fillRect).not.toHaveBeenCalled();
+	});
+});
+
+describe('heatmap renderer — hover', () => {
+	it('focuses the hovered row and reports the cell under the cursor', () => {
+		const onHoverChange = jest.fn();
+		const hooks = createHooks(onHoverChange);
+		// Left third of the plot is column 0; the top third is the overflow row.
+		const { plot, setSeries } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+
+		expect(onHoverChange).toHaveBeenCalledWith({ row: 2, column: 0, count: 7 });
+		expect(setSeries).toHaveBeenCalledWith(3, { focus: true });
+	});
+
+	it('reports a data gap as a null count instead of zero', () => {
+		const onHoverChange = jest.fn();
+		const hooks = createHooks(onHoverChange);
+		const { plot } = createFakePlot({
+			left: PLOT_WIDTH / 2,
+			top: topOfRow(1),
+		});
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+
+		expect(onHoverChange).toHaveBeenCalledWith({
+			row: 1,
+			column: 1,
+			count: null,
+		});
+	});
+
+	it('does not re-report the same cell', () => {
+		const onHoverChange = jest.fn();
+		const hooks = createHooks(onHoverChange);
+		const { plot } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+		hooks.setCursor(plot);
+
+		expect(onHoverChange).toHaveBeenCalledTimes(1);
+	});
+
+	it('shows the overlay over the hovered cell and dims around it', () => {
+		const hooks = createHooks(undefined, true);
+		const { plot, over } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+
+		const overlay = over.querySelector<HTMLDivElement>(
+			'[data-testid="heatmap-hover-overlay"]',
+		);
+		expect(overlay?.style.display).toBe('block');
+		// Column 0 spans the left third of a 300px plot.
+		expect(overlay?.lastElementChild).toHaveStyle({
+			left: '0px',
+			width: '100px',
+		});
+	});
+
+	it('clips the overlay to the plot area', () => {
+		const hooks = createHooks();
+		const { plot, over } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+
+		// An end cell whose bucket or time slice is only partly in view is positioned
+		// past the axis; the plot area's edge is where the highlight has to stop.
+		const overlay = over.querySelector<HTMLDivElement>(
+			'[data-testid="heatmap-hover-overlay"]',
+		);
+		expect(overlay?.style.overflow).toBe('hidden');
+	});
+
+	it('collapses the dim rects when dimming is off', () => {
+		const hooks = createHooks(undefined, false);
+		const { plot, over } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+
+		const overlay = over.querySelector<HTMLDivElement>(
+			'[data-testid="heatmap-hover-overlay"]',
+		);
+		expect(overlay?.firstElementChild).toHaveStyle({
+			width: '0px',
+			height: '0px',
+		});
+	});
+
+	it('releases focus and hides the overlay when the cursor leaves', () => {
+		const onHoverChange = jest.fn();
+		const hooks = createHooks(onHoverChange);
+		const { plot, over, setSeries } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+		(plot as { cursor: { left: number; top: number } }).cursor = {
+			left: -10,
+			top: -10,
+		};
+		hooks.setCursor(plot);
+
+		expect(onHoverChange).toHaveBeenLastCalledWith(null);
+		expect(setSeries).toHaveBeenLastCalledWith(null, { focus: true });
+		expect(
+			over.querySelector<HTMLDivElement>('[data-testid="heatmap-hover-overlay"]')
+				?.style.display,
+		).toBe('none');
+	});
+
+	it('clears the hover when the cursor is inside the plot but past the last column', () => {
+		const onHoverChange = jest.fn();
+		const hooks = createHooks(onHoverChange);
+		const { plot } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+		(plot as { data: unknown }).data = [[], [], [], []];
+		(plot as { cursor: { left: number; top: number } }).cursor = {
+			left: 10,
+			top: 10,
+		};
+		hooks.setCursor(plot);
+
+		expect(onHoverChange).toHaveBeenLastCalledWith(null);
+	});
+});

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/__tests__/palettes.test.ts

@@ -0,0 +1,67 @@
+import { getPaletteStops } from '../palettes';
+import { HeatmapColorPalette } from '../types';
+
+const ALL_PALETTES = Object.values(HeatmapColorPalette);
+
+/** Perceived brightness, good enough to tell a ramp's ends apart. */
+function luminance(hex: string): number {
+	const value = parseInt(hex.slice(1), 16);
+	// eslint-disable-next-line no-bitwise
+	const [r, g, b] = [(value >> 16) & 255, (value >> 8) & 255, value & 255];
+	return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+describe('getPaletteStops', () => {
+	it.each(ALL_PALETTES)('%s is a full ramp of valid colours', (palette) => {
+		const stops = getPaletteStops(palette, true);
+
+		expect(stops).toHaveLength(9);
+		stops.forEach((stop) => expect(stop).toMatch(/^#[0-9a-f]{6}$/));
+	});
+
+	it.each(ALL_PALETTES)(
+		'%s climbs from dark to bright on a dark panel',
+		(palette) => {
+			const stops = getPaletteStops(palette, true);
+
+			// Low counts must sit near the surface, whichever direction the ramp is
+			// stored in — otherwise empty cells become the loudest thing on screen.
+			expect(luminance(stops[0])).toBeLessThan(luminance(stops[stops.length - 1]));
+		},
+	);
+
+	it.each(ALL_PALETTES)(
+		'%s falls from pale to saturated on a light panel',
+		(palette) => {
+			const stops = getPaletteStops(palette, false);
+
+			expect(luminance(stops[0])).toBeGreaterThan(
+				luminance(stops[stops.length - 1]),
+			);
+		},
+	);
+
+	it.each(ALL_PALETTES)('%s uses the same colours in both themes', (palette) => {
+		// Only the polarity flips; the palette itself is theme-independent.
+		expect([...getPaletteStops(palette, false)].reverse()).toStrictEqual(
+			getPaletteStops(palette, true),
+		);
+	});
+
+	it('never mutates the stored ramp when reversing it', () => {
+		const first = getPaletteStops(HeatmapColorPalette.Lava, false);
+		const second = getPaletteStops(HeatmapColorPalette.Lava, false);
+
+		expect(first).toStrictEqual(second);
+	});
+
+	it('offers a neutral ramp for panels that already spend colour elsewhere', () => {
+		const stops = getPaletteStops(HeatmapColorPalette.Graphite, true);
+
+		// Every stop is a grey: red, green and blue channels stay equal.
+		stops.forEach((stop) => {
+			expect(stop.slice(1, 3)).toBe(stop.slice(3, 5));
+			expect(stop.slice(3, 5)).toBe(stop.slice(5, 7));
+		});
+	});
+});

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/colorScale.ts

@@ -0,0 +1,257 @@
+import { Color as DesignToken } from '@signozhq/design-tokens';
+import Color from 'color';
+
+import { DEFAULT_HEATMAP_PALETTE, getPaletteStops } from './palettes';
+import {
+	HeatmapColorMode,
+	HeatmapColorOptions,
+	HeatmapColorScale,
+} from './types';
+
+export const MIN_COLOR_STEPS = 2;
+export const MAX_COLOR_STEPS = 128;
+export const DEFAULT_COLOR_STEPS = 64;
+
+/** Without a floor, the lowest counts read as "no data". */
+export const MIN_OPACITY_ALPHA = 0.1;
+
+/** Log's bottom when the grid holds no positive count to take it from. */
+const DEFAULT_LOG_FLOOR = 1;
+
+/** Widest span a single ramp is stretched over on a log scale. */
+const MAX_LOG_DECADES = 6;
+
+/** Used when neither an explicit fill nor a series colour is available. */
+export const DEFAULT_OPACITY_FILL = DesignToken.BG_ROBIN_500;
+
+/** Zero takes the panel surface so an empty stretch recedes, leaving the ramp's
+ *  bottom to the smallest count that did occur — on a log scale the two collapse. */
+const ZERO_FILL: Record<'dark' | 'light', string> = {
+	dark: DesignToken.BG_INK_500,
+	light: DesignToken.BG_VANILLA_100,
+};
+
+export const DEFAULT_HEATMAP_COLORS: HeatmapColorOptions = {
+	mode: HeatmapColorMode.Palette,
+	scale: HeatmapColorScale.Log,
+	minCount: null,
+	maxCount: null,
+	palette: DEFAULT_HEATMAP_PALETTE,
+	steps: DEFAULT_COLOR_STEPS,
+	fill: '',
+};
+
+export interface CountDomain {
+	min: number;
+	max: number;
+	/** Bottom decade of the log scale: the smallest count it separates from zero.
+	 *  Always positive, since log has no bottom otherwise. */
+	logFloor: number;
+}
+
+/** Highest count, ignoring `null`. 0 for an empty grid. */
+export function getMaxCount(counts: Array<Array<number | null>>): number {
+	let max = 0;
+	for (const row of counts) {
+		for (const count of row) {
+			if (count !== null && Number.isFinite(count) && count > max) {
+				max = count;
+			}
+		}
+	}
+	return max;
+}
+
+/** Smallest count above zero, ignoring `null`. `null` for a grid without one. */
+export function getSmallestPositiveCount(
+	counts: Array<Array<number | null>>,
+): number | null {
+	let smallest: number | null = null;
+	for (const row of counts) {
+		for (const count of row) {
+			if (
+				count !== null &&
+				Number.isFinite(count) &&
+				count > 0 &&
+				(smallest === null || count < smallest)
+			) {
+				smallest = count;
+			}
+		}
+	}
+	return smallest;
+}
+
+/**
+ * The grid's own resolution: whole counts floor at 1, while a heatmap of rates or
+ * ratios can live entirely below it, where a fixed floor of 1 would flatten every
+ * cell onto the bottom colour. Capped at `MAX_LOG_DECADES` so one stray tiny cell
+ * cannot stretch the ramp over a range nothing else occupies.
+ */
+function resolveLogFloor(
+	counts: Array<Array<number | null>>,
+	max: number,
+): number {
+	const smallest = getSmallestPositiveCount(counts) ?? DEFAULT_LOG_FLOOR;
+	return Math.max(smallest, max / 10 ** MAX_LOG_DECADES);
+}
+
+/** Explicit clamps win; otherwise 0 to the grid's highest count. */
+export function resolveCountDomain(
+	options: Pick<HeatmapColorOptions, 'minCount' | 'maxCount'>,
+	counts: Array<Array<number | null>>,
+): CountDomain {
+	const min = options.minCount ?? 0;
+	const max = options.maxCount ?? getMaxCount(counts);
+	const logFloor = resolveLogFloor(counts, max);
+	return max > min ? { min, max, logFloor } : { min, max: min, logFloor };
+}
+
+/** Position on the colour scale, 0..1. A degenerate domain collapses to 0 so an
+ *  all-zero grid renders at the bottom rather than disappearing. */
+export function normalizeCount({
+	count,
+	domain,
+	scale,
+}: {
+	count: number;
+	domain: CountDomain;
+	scale: HeatmapColorScale;
+}): number {
+	const { min, max } = domain;
+	if (!(max > min)) {
+		return 0;
+	}
+
+	const clamped = Math.min(Math.max(count, min), max);
+
+	if (scale === HeatmapColorScale.Log) {
+		// Anything at or below the floor sits at the bottom; log cannot place it.
+		const bottom = Math.max(min, domain.logFloor);
+		const logMin = Math.log10(bottom);
+		const logMax = Math.log10(max);
+		if (logMax > logMin) {
+			return (Math.log10(Math.max(clamped, bottom)) - logMin) / (logMax - logMin);
+		}
+		// The floor already reaches the top of the domain, so there is no span to
+		// spread logarithmically. Fall through rather than flatten the whole grid.
+	}
+
+	const linear = (clamped - min) / (max - min);
+	return scale === HeatmapColorScale.Sqrt ? Math.sqrt(linear) : linear;
+}
+
+export function clampColorSteps(steps: number): number {
+	if (!Number.isFinite(steps)) {
+		return DEFAULT_COLOR_STEPS;
+	}
+	return Math.min(Math.max(Math.round(steps), MIN_COLOR_STEPS), MAX_COLOR_STEPS);
+}
+
+/** Colour at `t` (0..1) along a multi-stop ramp. */
+function sampleStops(stops: string[], t: number): string {
+	if (stops.length === 0) {
+		return 'transparent';
+	}
+	if (stops.length === 1) {
+		return stops[0];
+	}
+	const scaled = Math.min(Math.max(t, 0), 1) * (stops.length - 1);
+	const lower = Math.min(Math.floor(scaled), stops.length - 2);
+	return Color(stops[lower])
+		.mix(Color(stops[lower + 1]), scaled - lower)
+		.hex();
+}
+
+/**
+ * Colour the densest cells are drawn with — the palette's extreme, or the opacity
+ * fill at full strength. Depends only on the options, not on the data, so callers
+ * can read it before a grid exists.
+ */
+export function resolveExtremeColor({
+	options,
+	isDarkMode,
+	seriesColor,
+}: {
+	options: HeatmapColorOptions;
+	isDarkMode: boolean;
+	seriesColor: string;
+}): string {
+	if (options.mode === HeatmapColorMode.Opacity) {
+		return options.fill || seriesColor || DEFAULT_OPACITY_FILL;
+	}
+	const stops = getPaletteStops(options.palette, isDarkMode);
+	return stops[stops.length - 1] ?? DEFAULT_OPACITY_FILL;
+}
+
+export interface HeatmapColorResolver {
+	/** `null` for a `null` count, which must be hatched. */
+	colorFor: (count: number | null) => string | null;
+	/** 0..1, or `null` for a `null` count. */
+	positionOf: (count: number | null) => number | null;
+	/** Low to high. The colour bar renders exactly these. */
+	ramp: string[];
+	domain: CountDomain;
+}
+
+/** Palette mode walks a sequential ramp; opacity mode varies the alpha of one
+ *  fill, so the grid matches its group's legend swatch. */
+export function createHeatmapColorResolver({
+	options,
+	domain,
+	isDarkMode,
+	seriesColor,
+}: {
+	options: HeatmapColorOptions;
+	domain: CountDomain;
+	isDarkMode: boolean;
+	/** Opacity-mode fill when `options.fill` is empty. */
+	seriesColor: string;
+}): HeatmapColorResolver {
+	const steps = clampColorSteps(options.steps);
+	const positions = Array.from({ length: steps }, (_, index) =>
+		steps === 1 ? 0 : index / (steps - 1),
+	);
+
+	let ramp: string[];
+	if (options.mode === HeatmapColorMode.Opacity) {
+		const base = Color(options.fill || seriesColor || DEFAULT_OPACITY_FILL);
+		ramp = positions.map((t) =>
+			base
+				.alpha(MIN_OPACITY_ALPHA + t * (1 - MIN_OPACITY_ALPHA))
+				.rgb()
+				.string(),
+		);
+	} else {
+		const stops = getPaletteStops(options.palette, isDarkMode);
+		ramp = positions.map((t) => sampleStops(stops, t));
+	}
+
+	const positionOf = (count: number | null): number | null => {
+		if (count === null || !Number.isFinite(count)) {
+			return null;
+		}
+		return normalizeCount({ count, domain, scale: options.scale });
+	};
+
+	// An explicit `minCount` above zero makes it a clamped value like any other.
+	const zeroFill =
+		domain.min <= 0 ? ZERO_FILL[isDarkMode ? 'dark' : 'light'] : null;
+
+	return {
+		positionOf,
+		colorFor: (count): string | null => {
+			if (count === 0 && zeroFill !== null) {
+				return zeroFill;
+			}
+			const t = positionOf(count);
+			if (t === null) {
+				return null;
+			}
+			const index = Math.min(Math.floor(t * steps), steps - 1);
+			return ramp[index];
+		},
+		ramp,
+		domain,
+	};
+}