feat(alerts): scroll Slack alert links to the firing tile

[teeohhem]

Summary

When a dashboard tile alert fires and posts to Slack, the link drops you on the dashboard at the right time range but doesn't tell you which tile triggered the alert — on a busy dashboard you have to hunt for it.

The dashboard page already scrolls to and highlights a tile when the URL has ?highlightedTileId=<id> (the in-app alert-link path on AlertsPage.tsx has used this for a while). This PR closes the two gaps that kept that behavior from working for Slack alert links:

1. The Slack/webhook link wasn't carrying the firing tile's id.
2. When the tile lives inside a non-active tab of a container, the tile isn't in the DOM, so scrollIntoView/highlight silently no-ops.

Changes

Backend (API):

• AlertProvider.buildChartLink gains an optional tileId?: string.
• DefaultAlertProvider.buildChartLink appends highlightedTileId=<tileId> to the URL when set, omits it when undefined or empty.
• buildAlertMessageTemplateHdxLink passes alert.tileId through.
• Unit tests cover tileId present / undefined / empty-string.
• Four existing inline-snapshot fixtures in checkAlerts.test.ts updated for the new param.

Frontend (App):

• On arrival with ?highlightedTileId=<id>, if the tile's container has tabs and the tile is in a non-active tab, switch to it once so the tile renders. Guarded by a ref keyed on highlightedTileId so a user manually switching tabs afterwards isn't reverted.

What the user sees

Before: Slack alert link → dashboard loads at the alert's time range, no indication of which tile fired.

After: Slack alert link → dashboard loads at the alert's time range, the firing tile's tab is selected if needed, and the tile is scrolled into view with the existing orange highlight fade (same UI as clicking an alert link from inside the app).

Out of scope

The earlier draft of this PR also added auto-expand for collapsed containers, a persistent/dismissible highlight, and a new e2e regression test. Those were dropped to keep this change focused — the existing scroll/highlight is good enough for the common case, and the extras can land separately if needed.

Test plan

• make ci-lint — passes
• tsc --noEmit on packages/app — passes
• CI integration tests for checkAlerts (Slack/webhook URL inline snapshots)
• CI unit tests for DefaultAlertProvider.buildChartLink

References

• Linear Issue:
• Related PRs:

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	May 13, 2026 3:59pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: 43fe377

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

🔴 Tier 4 — Critical

Touches auth, data models, config, tasks, OTel pipeline, ClickHouse, or CI/CD.

Why this tier:

• Critical-path files (3):
  • packages/api/src/tasks/checkAlerts/providers/default.ts
  • packages/api/src/tasks/checkAlerts/providers/index.ts
  • packages/api/src/tasks/checkAlerts/template.ts
• Cross-layer change: touches frontend (packages/app) + backend (packages/api)

Review process: Deep review from a domain expert. Synchronous walkthrough may be required.
SLA: Schedule synchronous review within 2 business days.

Stats

• Production files changed: 4
• Production lines changed: 33 (+ 46 in test files, excluded from tier calculation)
• Branch: teeohhem/scroll-to-alert-tile
• Author: teeohhem

To override this classification, remove the review/tier-4 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[github-actions]

PR Review

✅ No critical issues found.

Minor (non-blocking) observations:

• ℹ️ PR description says "backend-only," but DBDashboardPage.tsx has a real 26-line frontend addition (the tab-switching useEffect). Update the description so reviewers know to look at the React change too.
• ℹ️ alert.tileId is z.string().min(1) (see common-utils/src/types.ts:471), so the tileId === '' guard in default.ts is dead defense — fine to keep, just noting it can never trigger today.
• ℹ️ handledHighlightRef is keyed only on the id, so if a user navigates ?highlightedTileId=A → clears it → back to A, the effect is skipped and the tab isn't re-switched. Likely acceptable, but worth noting if you intend the link to be re-clickable.
• ℹ️ If a tile's tabId doesn't exist in the container's tabs (stale data), the effect will still write it into urlActiveTabs, and getActiveTabId will silently fall back to tabs[0]. Harmless but creates a phantom URL param.

[github-actions]

E2E Test Results

✅ All tests passed • 131 passed • 2 skipped • 885s

Status	Count
✅ Passed	131
❌ Failed	0
⚠️ Flaky	4
⏭️ Skipped	2

Tests ran across 3 shards in parallel.

View full report →

[github-actions]

Deep Review

🟡 P2 -- recommended

• packages/app/src/DBDashboardPage.tsx:1566 -- the new auto-tab-switch useEffect for ?highlightedTileId ships untested despite packages/app/ having React Testing Library infrastructure, and the ref-guard interaction with user-initiated tab changes is a likely regression vector.
  • Fix: add an RTL test for DBDashboardPage covering (a) tile in inactive tab → tab switches, (b) tile already in active tab → no switch, (c) re-render with same highlightedTileId does not revert a user's manual tab change, (d) highlightedTileId resolves to no tile or a tile with no tabId → no-op without throwing.
  • _{testing, maintainability, kieran-typescript}

🔵 P3 nitpicks (2)

• packages/app/src/DBDashboardPage.tsx:1569 -- handledHighlightRef.current is assigned before the tile?.containerId/tile.tabId/container existence checks, so any render that finds the dashboard but not the target tile poisons the ref and the effect will not retry when data populates on a later render.
  • Fix: move handledHighlightRef.current = highlightedTileId to after the successful setUrlActiveTabs call (and any terminal no-op branches such as "tab already active") so transient missing-data renders don't lock out subsequent attempts.
  • _{correctness, kieran-typescript, adversarial}
• packages/app/src/DBDashboardPage.tsx:1570 -- a Slack link referencing a since-deleted or renamed tile loads the dashboard with no signal that the linked tile is gone; the effect silently no-ops and the page looks the same as any normal navigation.
  • Fix: when highlightedTileId is set on arrival and dashboard.tiles.find(t => t.id === highlightedTileId) returns undefined, surface a one-time toast or banner so the user knows the alert's target tile no longer exists.

---

Reviewers (6): correctness, testing, maintainability, api-contract, kieran-typescript, adversarial.

Testing gaps:

• No frontend test for the new auto-tab-switch useEffect in DBDashboardPage.tsx.
• No end-to-end test for a TILE-source alert with alert.tileId undefined exercising the template.ts pass-through.
• No URL-encoding edge-case test for buildChartLink's new tileId parameter (current tests use plain alphanumeric ids).
• Updated inline snapshots in checkAlerts.test.ts lock in the new query param only as snapshot text, not as an explicit toContain('highlightedTileId=...') assertion.