@uptimizr/db 0.3.0 → 0.5.0

package/dist/query/aggregations.d.ts

@@ -10,7 +10,16 @@
  * optional scene/source/session dimensions only.
  */
 import { type Dialect } from "./dialect.js";
-import type { QuerySpec, CameraModeOptions, FunnelOptions, RangeOptions, SceneOptions, SessionOptions, SourceOptions, TimeseriesOptions } from "./types.js";
+import type { QuerySpec, CameraModeOptions, FunnelOptions, RangeOptions, RegionOptions, SceneOptions, SessionOptions, SourceOptions, TimeseriesOptions, WorldAabb } from "./types.js";
+/**
+ * Bounds-driven default voxel size (ADR 0040 §1). Picks a `cellSize` so the
+ * longest axis of `bounds` spans roughly `targetCells` cells, keeping spatial
+ * resolution proportional to scene extent instead of a fixed world-unit default
+ * that dissolves large scenes into a few coarse blocks. Returns `null` for a
+ * missing or degenerate (zero/negative longest-axis) box so the caller can fall
+ * back to its fixed default.
+ */
+export declare function defaultCellSizeForBounds(bounds: WorldAabb | null | undefined, targetCells?: number): number | null;
 /** List sessions for a project with event counts and time bounds. */
 export declare function buildListSessions(projectId: string, opts: RangeOptions & CameraModeOptions & {
     limit?: number;
@@ -27,10 +36,20 @@ export declare function buildPointerHeatmap(projectId: string, opts: RangeOption
  * events into a uniform grid of `cellSize`-sized cubes. Results are capped to the
  * busiest `limit` voxels.
  */
-export declare function buildWorldHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & CameraModeOptions & {
+export declare function buildWorldHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & RegionOptions & CameraModeOptions & {
     cellSize?: number;
     limit?: number;
 }, d: Dialect): QuerySpec;
+/**
+ * Scene-wide totals for the world (pointer) heatmap (ADR 0040 §3): the true count
+ * of occupied voxels and total hits, computed with no `LIMIT` so the viewer can
+ * report "showing top N of M cells" and reason about cold spots/coverage. Shares
+ * every filter (including {@link RegionOptions.region}) with {@link buildWorldHeatmap}.
+ * Uses a grouped sub-select so the dialect needs no `COUNT(DISTINCT tuple)`.
+ */
+export declare function buildWorldHeatmapStats(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & RegionOptions & CameraModeOptions & {
+    cellSize?: number;
+}, d: Dialect): QuerySpec;
 /**
  * World-space (3D) gaze heatmap (ADR 0030): voxel-bin the camera-pose gaze
  * surface hits (`camera_sample.hitPoint`) into the same uniform grid as the
@@ -41,10 +60,18 @@ export declare function buildWorldHeatmap(projectId: string, opts: RangeOptions
  * the busiest `limit` voxels; an optional `session` scopes it to one visit
  * (ADR 0010 §1a). Gaze has no pointer input-source, so there is no `source` filter.
  */
-export declare function buildGazeHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & CameraModeOptions & {
+export declare function buildGazeHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & RegionOptions & CameraModeOptions & {
     cellSize?: number;
     limit?: number;
 }, d: Dialect): QuerySpec;
+/**
+ * Scene-wide totals for the gaze heatmap (ADR 0040 §3): the true occupied-voxel
+ * and hit counts behind the truncated top-N gaze voxels, with no `LIMIT`. Shares
+ * every filter (including {@link RegionOptions.region}) with {@link buildGazeHeatmap}.
+ */
+export declare function buildGazeHeatmapStats(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & RegionOptions & CameraModeOptions & {
+    cellSize?: number;
+}, d: Dialect): QuerySpec;
 /**
  * View-direction heatmap: bin camera forward vectors by spherical angles.
  * `azimuth = atan2(z, x)`, `elevation = asin(y / |v|)`, each bucketed into `bins`.
@@ -58,7 +85,7 @@ export declare function buildCameraDirectionHeatmap(projectId: string, opts: Ran
  * mean height per cell. For first-person (`cameraType: "free"`) sessions this is
  * the "where do visitors walk / dwell" map; capped to the busiest `limit` cells.
  */
-export declare function buildCameraPositionHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & CameraModeOptions & {
+export declare function buildCameraPositionHeatmap(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions & RegionOptions & CameraModeOptions & {
     cellSize?: number;
     limit?: number;
 }, d: Dialect): QuerySpec;
@@ -96,11 +123,18 @@ export declare function buildAggregateTrajectories(projectId: string, opts: Rang
  * controllers, hands, gaze) carry their own world-space pointing ray, so when a
  * click has a `ray.origin` we use it verbatim — the controller/hand/gaze is the
  * true pointing origin, not the headset/camera. Flat pointers (mouse, touch,
- * stylus) have no native ray, so they fall back to the nearest preceding
- * `camera_sample` in the same session (the historical view-gated behavior). The
- * camera join is therefore a LEFT join so pose clicks survive even in sessions
- * that never emit a `camera_sample`; rows with neither a ray nor a camera origin
- * are dropped.
+ * stylus) have no native ray; when the ASOF-joined `camera_sample` carries the
+ * projection intrinsics (`fov`/`aspect`/`near`, #22, ADR 0043) we unproject the
+ * click's normalized `screen[x, y]` onto the camera **near plane** and use that
+ * point as the origin, so flat-pointer rays fan out across the near plane the way
+ * the clicks were actually made. The near-plane basis assumes the canonical
+ * world-up `(0, 1, 0)` and no camera roll (true for mouse/touch); a degenerate
+ * look-straight-up/down view (or any missing/zero intrinsic, e.g. legacy data)
+ * falls back to the nearest preceding `camera_sample` **position** — the
+ * historical view-gated behavior. The camera join is therefore a LEFT join so
+ * pose clicks survive even in sessions that never emit a `camera_sample`; rows
+ * with neither a ray, a reconstructable near-plane point, nor a camera origin are
+ * dropped.
  */
 export declare function buildClickGazeRay(projectId: string, opts: RangeOptions & SceneOptions & SourceOptions & SessionOptions & {
     cellSize?: number;
@@ -328,11 +362,13 @@ export declare function buildJankRate(projectId: string, opts: RangeOptions & Sc
 /**
  * FPS segmented by device class, computed **per-session then aggregated** (ADR
  * 0028 §2). Each session's median FPS is attributed to the graphics backend,
- * mobile flag, and GPU `renderer` recorded in its `session_start.device` block —
- * data already on the wire, so there is no SDK or schema change. Device fields
- * are read from the `session_start` payload JSON (they are not promoted columns)
- * and `coalesce`d to `''` when a session never reported them. `p50_fps` is the
- * median across sessions in the group of each session's median FPS.
+ * mobile flag, and GPU `renderer` recorded in its `session_start.device` block,
+ * plus the coarse `browser`/`os` families derived server-side from the
+ * User-Agent at ingestion (ADR 0041) — all data already on the wire, so there is
+ * no SDK or schema change. Device fields are read from the `session_start`
+ * payload JSON (they are not promoted columns) and `coalesce`d to `''` when a
+ * session never reported them. `p50_fps` is the median across sessions in the
+ * group of each session's median FPS.
  */
 export declare function buildPerfByDevice(projectId: string, opts: RangeOptions & SceneOptions & SessionOptions, d: Dialect): QuerySpec;
 /**

package/dist/query/aggregations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../../src/query/aggregations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../../src/query/aggregations.ts"],"names":[],"mappings":"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"}

package/dist/query/aggregations.js

@@ -9,7 +9,28 @@
  * Invariant: no multi-tenant concepts here. Filtering is by `project_id` and the
  * optional scene/source/session dimensions only.
  */
-import { ParamBag, cameraModeClause, dayRangeClause, rangeClause, sceneClause, sessionClause, sourceClause, } from "./dialect.js";
+import { ParamBag, cameraModeClause, dayRangeClause, rangeClause, regionClause, sceneClause, sessionClause, sourceClause, } from "./dialect.js";
+/** World/gaze voxel coordinates derive from the raycast `hit_point` vector. */
+const HIT_POINT_COLS = { x: "hit_point[1]", y: "hit_point[2]", z: "hit_point[3]" };
+/** Floor-plan cells derive from the camera `position` vector (Y is height). */
+const POSITION_COLS = { x: "position[1]", y: "position[2]", z: "position[3]" };
+/**
+ * Bounds-driven default voxel size (ADR 0040 §1). Picks a `cellSize` so the
+ * longest axis of `bounds` spans roughly `targetCells` cells, keeping spatial
+ * resolution proportional to scene extent instead of a fixed world-unit default
+ * that dissolves large scenes into a few coarse blocks. Returns `null` for a
+ * missing or degenerate (zero/negative longest-axis) box so the caller can fall
+ * back to its fixed default.
+ */
+export function defaultCellSizeForBounds(bounds, targetCells = 64) {
+    if (bounds == null)
+        return null;
+    const [minX, minY, minZ, maxX, maxY, maxZ] = bounds;
+    const longest = Math.max(maxX - minX, maxY - minY, maxZ - minZ);
+    if (!Number.isFinite(longest) || longest <= 0 || targetCells <= 0)
+        return null;
+    return longest / targetCells;
+}
 /** List sessions for a project with event counts and time bounds. */
 export function buildListSessions(projectId, opts, d) {
     const bag = new ParamBag(d);
@@ -76,6 +97,7 @@ export function buildWorldHeatmap(projectId, opts, d) {
     const scene = sceneClause(bag, opts);
     const source = sourceClause(bag, opts);
     const cameraMode = cameraModeClause(bag, d, projectId, opts);
+    const region = regionClause(bag, opts, HIT_POINT_COLS);
     const limit = bag.add("limit", "u32", opts.limit ?? 1000);
     return {
         query: `
@@ -87,7 +109,7 @@ export function buildWorldHeatmap(projectId, opts, d) {
       FROM events
       WHERE project_id = ${pid}
         AND event_type IN ('pointer_move', 'pointer_click')
-        AND length(hit_point) = 3${range}${scene}${source}${cameraMode}
+        AND length(hit_point) = 3${range}${scene}${source}${cameraMode}${region}
       GROUP BY vx, vy, vz
       ORDER BY count DESC
       LIMIT ${limit}
@@ -95,6 +117,41 @@ export function buildWorldHeatmap(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * Scene-wide totals for the world (pointer) heatmap (ADR 0040 §3): the true count
+ * of occupied voxels and total hits, computed with no `LIMIT` so the viewer can
+ * report "showing top N of M cells" and reason about cold spots/coverage. Shares
+ * every filter (including {@link RegionOptions.region}) with {@link buildWorldHeatmap}.
+ * Uses a grouped sub-select so the dialect needs no `COUNT(DISTINCT tuple)`.
+ */
+export function buildWorldHeatmapStats(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const cellSize = bag.add("cellSize", "f64", opts.cellSize ?? 0.5);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const source = sourceClause(bag, opts);
+    const cameraMode = cameraModeClause(bag, d, projectId, opts);
+    const region = regionClause(bag, opts, HIT_POINT_COLS);
+    return {
+        query: `
+      SELECT count() AS cells, coalesce(sum(c), 0) AS hits
+      FROM (
+        SELECT
+          floor(hit_point[1] / ${cellSize}) AS vx,
+          floor(hit_point[2] / ${cellSize}) AS vy,
+          floor(hit_point[3] / ${cellSize}) AS vz,
+          count() AS c
+        FROM events
+        WHERE project_id = ${pid}
+          AND event_type IN ('pointer_move', 'pointer_click')
+          AND length(hit_point) = 3${range}${scene}${source}${cameraMode}${region}
+        GROUP BY vx, vy, vz
+      ) t
+    `,
+        query_params: bag.values,
+    };
+}
 /**
  * World-space (3D) gaze heatmap (ADR 0030): voxel-bin the camera-pose gaze
  * surface hits (`camera_sample.hitPoint`) into the same uniform grid as the
@@ -113,6 +170,7 @@ export function buildGazeHeatmap(projectId, opts, d) {
     const scene = sceneClause(bag, opts);
     const session = sessionClause(bag, opts);
     const cameraMode = cameraModeClause(bag, d, projectId, opts);
+    const region = regionClause(bag, opts, HIT_POINT_COLS);
     const limit = bag.add("limit", "u32", opts.limit ?? 1000);
     return {
         query: `
@@ -124,7 +182,7 @@ export function buildGazeHeatmap(projectId, opts, d) {
       FROM events
       WHERE project_id = ${pid}
         AND event_type = 'camera_sample'
-        AND length(hit_point) = 3${range}${scene}${session}${cameraMode}
+        AND length(hit_point) = 3${range}${scene}${session}${cameraMode}${region}
       GROUP BY vx, vy, vz
       ORDER BY count DESC
       LIMIT ${limit}
@@ -132,6 +190,39 @@ export function buildGazeHeatmap(projectId, opts, d) {
         query_params: bag.values,
     };
 }
+/**
+ * Scene-wide totals for the gaze heatmap (ADR 0040 §3): the true occupied-voxel
+ * and hit counts behind the truncated top-N gaze voxels, with no `LIMIT`. Shares
+ * every filter (including {@link RegionOptions.region}) with {@link buildGazeHeatmap}.
+ */
+export function buildGazeHeatmapStats(projectId, opts, d) {
+    const bag = new ParamBag(d);
+    const pid = bag.add("projectId", "string", projectId);
+    const cellSize = bag.add("cellSize", "f64", opts.cellSize ?? 0.5);
+    const range = rangeClause(bag, opts);
+    const scene = sceneClause(bag, opts);
+    const session = sessionClause(bag, opts);
+    const cameraMode = cameraModeClause(bag, d, projectId, opts);
+    const region = regionClause(bag, opts, HIT_POINT_COLS);
+    return {
+        query: `
+      SELECT count() AS cells, coalesce(sum(c), 0) AS hits
+      FROM (
+        SELECT
+          floor(hit_point[1] / ${cellSize}) AS vx,
+          floor(hit_point[2] / ${cellSize}) AS vy,
+          floor(hit_point[3] / ${cellSize}) AS vz,
+          count() AS c
+        FROM events
+        WHERE project_id = ${pid}
+          AND event_type = 'camera_sample'
+          AND length(hit_point) = 3${range}${scene}${session}${cameraMode}${region}
+        GROUP BY vx, vy, vz
+      ) t
+    `,
+        query_params: bag.values,
+    };
+}
 /**
  * View-direction heatmap: bin camera forward vectors by spherical angles.
  * `azimuth = atan2(z, x)`, `elevation = asin(y / |v|)`, each bucketed into `bins`.
@@ -174,6 +265,7 @@ export function buildCameraPositionHeatmap(projectId, opts, d) {
     const scene = sceneClause(bag, opts);
     const session = sessionClause(bag, opts);
     const cameraMode = cameraModeClause(bag, d, projectId, opts);
+    const region = regionClause(bag, opts, POSITION_COLS);
     const limit = bag.add("limit", "u32", opts.limit ?? 2000);
     return {
         query: `
@@ -185,7 +277,7 @@ export function buildCameraPositionHeatmap(projectId, opts, d) {
       FROM events
       WHERE project_id = ${pid}
         AND event_type = 'camera_sample'
-        AND length(position) = 3${range}${scene}${session}${cameraMode}
+        AND length(position) = 3${range}${scene}${session}${cameraMode}${region}
       GROUP BY gx, gz
       ORDER BY count DESC
       LIMIT ${limit}
@@ -269,11 +361,18 @@ export function buildAggregateTrajectories(projectId, opts, d) {
  * controllers, hands, gaze) carry their own world-space pointing ray, so when a
  * click has a `ray.origin` we use it verbatim — the controller/hand/gaze is the
  * true pointing origin, not the headset/camera. Flat pointers (mouse, touch,
- * stylus) have no native ray, so they fall back to the nearest preceding
- * `camera_sample` in the same session (the historical view-gated behavior). The
- * camera join is therefore a LEFT join so pose clicks survive even in sessions
- * that never emit a `camera_sample`; rows with neither a ray nor a camera origin
- * are dropped.
+ * stylus) have no native ray; when the ASOF-joined `camera_sample` carries the
+ * projection intrinsics (`fov`/`aspect`/`near`, #22, ADR 0043) we unproject the
+ * click's normalized `screen[x, y]` onto the camera **near plane** and use that
+ * point as the origin, so flat-pointer rays fan out across the near plane the way
+ * the clicks were actually made. The near-plane basis assumes the canonical
+ * world-up `(0, 1, 0)` and no camera roll (true for mouse/touch); a degenerate
+ * look-straight-up/down view (or any missing/zero intrinsic, e.g. legacy data)
+ * falls back to the nearest preceding `camera_sample` **position** — the
+ * historical view-gated behavior. The camera join is therefore a LEFT join so
+ * pose clicks survive even in sessions that never emit a `camera_sample`; rows
+ * with neither a ray, a reconstructable near-plane point, nor a camera origin are
+ * dropped.
  */
 export function buildClickGazeRay(projectId, opts, d) {
     const bag = new ParamBag(d);
@@ -302,29 +401,66 @@ export function buildClickGazeRay(projectId, opts, d) {
         count() AS count
       FROM (
         SELECT
-          c.hx AS hx, c.hy AS hy, c.hz AS hz, c.mesh AS mesh,
-          CASE WHEN c.has_ray THEN c.rox WHEN m.cam_present = 1 THEN m.px END AS ox,
-          CASE WHEN c.has_ray THEN c.roy WHEN m.cam_present = 1 THEN m.py END AS oy,
-          CASE WHEN c.has_ray THEN c.roz WHEN m.cam_present = 1 THEN m.pz END AS oz
+          ja.hx AS hx, ja.hy AS hy, ja.hz AS hz, ja.mesh AS mesh,
+          CASE
+            WHEN ja.has_ray THEN ja.rox
+            WHEN ja.recon THEN ja.px + ja.dx * ja.near / ja.dlen
+              + (ja.dz / ja.hlen) * ja.off_r
+              + (-(ja.dx * ja.dy) / (ja.dlen * ja.hlen)) * ja.off_u
+            WHEN ja.cam_present = 1 THEN ja.px
+          END AS ox,
+          CASE
+            WHEN ja.has_ray THEN ja.roy
+            WHEN ja.recon THEN ja.py + ja.dy * ja.near / ja.dlen
+              + (ja.hlen / ja.dlen) * ja.off_u
+            WHEN ja.cam_present = 1 THEN ja.py
+          END AS oy,
+          CASE
+            WHEN ja.has_ray THEN ja.roz
+            WHEN ja.recon THEN ja.pz + ja.dz * ja.near / ja.dlen
+              + (-(ja.dx) / ja.hlen) * ja.off_r
+              + (-(ja.dy * ja.dz) / (ja.dlen * ja.hlen)) * ja.off_u
+            WHEN ja.cam_present = 1 THEN ja.pz
+          END AS oz
         FROM (
-          SELECT session_id, ts,
-            hit_point[1] AS hx, hit_point[2] AS hy, hit_point[3] AS hz, mesh,
-            length(ray_origin) = 3 AS has_ray,
-            ray_origin[1] AS rox, ray_origin[2] AS roy, ray_origin[3] AS roz
-          FROM events
-          WHERE project_id = ${pid}
-            AND event_type = 'pointer_click'
-            AND length(hit_point) = 3${range}${scene}${source}${session}
-        ) AS c
-        ${d.asofLeftJoin} (
-          SELECT session_id, ts, 1 AS cam_present,
-            position[1] AS px, position[2] AS py, position[3] AS pz
-          FROM events
-          WHERE project_id = ${pid}
-            AND event_type = 'camera_sample'
-            AND length(position) = 3${range}${scene}${session}
-        ) AS m
-        ON c.session_id = m.session_id AND c.ts >= m.ts
+          SELECT
+            c.hx AS hx, c.hy AS hy, c.hz AS hz, c.mesh AS mesh,
+            c.has_ray AS has_ray, c.rox AS rox, c.roy AS roy, c.roz AS roz,
+            m.cam_present AS cam_present,
+            m.px AS px, m.py AS py, m.pz AS pz,
+            m.dx AS dx, m.dy AS dy, m.dz AS dz, m.cam_near AS near,
+            sqrt(m.dx * m.dx + m.dy * m.dy + m.dz * m.dz) AS dlen,
+            sqrt(m.dx * m.dx + m.dz * m.dz) AS hlen,
+            (2 * c.sx - 1) * m.cam_near * tan(m.cam_fov / 2) * m.cam_aspect AS off_r,
+            (1 - 2 * c.sy) * m.cam_near * tan(m.cam_fov / 2) AS off_u,
+            (NOT c.has_ray) AND c.has_screen
+              AND m.cam_fov > 0 AND m.cam_aspect > 0 AND m.cam_near > 0
+              AND sqrt(m.dx * m.dx + m.dz * m.dz)
+                  > 1e-6 * sqrt(m.dx * m.dx + m.dy * m.dy + m.dz * m.dz) AS recon
+          FROM (
+            SELECT session_id, ts,
+              hit_point[1] AS hx, hit_point[2] AS hy, hit_point[3] AS hz, mesh,
+              length(ray_origin) = 3 AS has_ray,
+              ray_origin[1] AS rox, ray_origin[2] AS roy, ray_origin[3] AS roz,
+              length(screen) = 2 AS has_screen,
+              screen[1] AS sx, screen[2] AS sy
+            FROM events
+            WHERE project_id = ${pid}
+              AND event_type = 'pointer_click'
+              AND length(hit_point) = 3${range}${scene}${source}${session}
+          ) AS c
+          ${d.asofLeftJoin} (
+            SELECT session_id, ts, 1 AS cam_present,
+              position[1] AS px, position[2] AS py, position[3] AS pz,
+              direction[1] AS dx, direction[2] AS dy, direction[3] AS dz,
+              fov AS cam_fov, aspect AS cam_aspect, near AS cam_near
+            FROM events
+            WHERE project_id = ${pid}
+              AND event_type = 'camera_sample'
+              AND length(position) = 3${range}${scene}${session}
+          ) AS m
+          ON c.session_id = m.session_id AND c.ts >= m.ts
+        ) AS ja
       ) AS j
       WHERE j.ox IS NOT NULL
       GROUP BY cam_vx, cam_vy, cam_vz, hit_vx, hit_vy, hit_vz, mesh
@@ -1081,11 +1217,13 @@ export function buildJankRate(projectId, opts, d) {
 /**
  * FPS segmented by device class, computed **per-session then aggregated** (ADR
  * 0028 §2). Each session's median FPS is attributed to the graphics backend,
- * mobile flag, and GPU `renderer` recorded in its `session_start.device` block —
- * data already on the wire, so there is no SDK or schema change. Device fields
- * are read from the `session_start` payload JSON (they are not promoted columns)
- * and `coalesce`d to `''` when a session never reported them. `p50_fps` is the
- * median across sessions in the group of each session's median FPS.
+ * mobile flag, and GPU `renderer` recorded in its `session_start.device` block,
+ * plus the coarse `browser`/`os` families derived server-side from the
+ * User-Agent at ingestion (ADR 0041) — all data already on the wire, so there is
+ * no SDK or schema change. Device fields are read from the `session_start`
+ * payload JSON (they are not promoted columns) and `coalesce`d to `''` when a
+ * session never reported them. `p50_fps` is the median across sessions in the
+ * group of each session's median FPS.
  */
 export function buildPerfByDevice(projectId, opts, d) {
     const bag = new ParamBag(d);
@@ -1096,6 +1234,8 @@ export function buildPerfByDevice(projectId, opts, d) {
     const engine = d.jsonText("payload", "device", "engine");
     const isMobile = d.jsonText("payload", "device", "isMobile");
     const renderer = d.jsonText("payload", "device", "renderer");
+    const browser = d.jsonText("payload", "device", "browser");
+    const os = d.jsonText("payload", "device", "os");
     return {
         query: `
       WITH session_device AS (
@@ -1103,7 +1243,9 @@ export function buildPerfByDevice(projectId, opts, d) {
           session_id,
           ${engine} AS engine,
           ${isMobile} AS is_mobile,
-          ${renderer} AS renderer
+          ${renderer} AS renderer,
+          ${browser} AS browser,
+          ${os} AS os
         FROM events
         WHERE project_id = ${pid} AND event_type = 'session_start'
       ),
@@ -1120,12 +1262,14 @@ export function buildPerfByDevice(projectId, opts, d) {
         coalesce(dev.engine, '') AS engine,
         coalesce(dev.is_mobile, '') AS is_mobile,
         coalesce(dev.renderer, '') AS renderer,
+        coalesce(dev.browser, '') AS browser,
+        coalesce(dev.os, '') AS os,
         count() AS sessions,
         sum(perf.s_samples) AS samples,
         ${d.quantile("perf.s_p50", 0.5)} AS p50_fps
       FROM session_perf perf
       LEFT JOIN session_device dev ON dev.session_id = perf.session_id
-      GROUP BY engine, is_mobile, renderer
+      GROUP BY engine, is_mobile, renderer, browser, os
       ORDER BY sessions DESC
     `,
         query_params: bag.values,