feat: add main-thread blocking detection (Long Tasks + LoAF + web Vitals)

packages/javascript/README.md

@@ -11,6 +11,7 @@ Error tracking for JavaScript/TypeScript applications.
 - 🛡️ Sensitive data filtering
 - 🌟 Source maps consuming
 - 💬 Console logs tracking
+- 🧊 Main-thread blocking detection (Chromium-only)
 - <img src="https://cdn.svglogos.dev/logos/vue.svg" width="16" height="16"> &nbsp;Vue support
 - <img src="https://cdn.svglogos.dev/logos/react.svg" width="16" height="16">  &nbsp;React support
 
@@ -85,11 +86,12 @@ Initialization settings:
 | `user`                        | {id: string, name?: string, image?: string, url?: string} | optional     | Current authenticated user                                                          |
 | `context`                     | object                                                    | optional     | Any data you want to pass with every message. Has limitation of length.             |
 | `vue`                         | Vue constructor                                           | optional     | Pass Vue constructor to set up the [Vue integration](#integrate-to-vue-application) |
-| `disableGlobalErrorsHandling` | boolean                                                   | optional     | Do not initialize global errors handling                                            |
+| `disableGlobalErrorsHandling` | boolean                                                   | optional     | Deprecated. Use `issues.errors: false` instead.                                     |
 | `disableVueErrorHandler`      | boolean                                                   | optional     | Do not initialize Vue errors handling                                               |
 | `consoleTracking`             | boolean                                                   | optional     | Initialize console logs tracking                                                    |
 | `breadcrumbs`                 | false or BreadcrumbsOptions object                        | optional     | Configure breadcrumbs tracking (see below)                                          |
 | `beforeSend`                  | function(event) => event \| false \| void                 | optional     | Filter data before sending. Return modified event, `false` to drop the event.       |
+| `issues`                      | IssuesOptions object                                      | optional     | Issues config: `errors`, `webVitals`, `longTasks.thresholdMs`, `longAnimationFrames.thresholdMs` |
 
 Other available [initial settings](types/hawk-initial-settings.d.ts) are described at the type definition.
 
@@ -232,6 +234,83 @@ const breadcrumbs = hawk.breadcrumbs.get();
 hawk.breadcrumbs.clear();
 ```
 
+## Issues Detection
+
+`issues` is an umbrella option for problems detected by the catcher.
+Browser support depends on the specific detector:
+- `errors` — works in all supported browsers
+- `webVitals` — via `web-vitals` package
+- `longTasks` / `longAnimationFrames` — Chromium-only (`long-animation-frame` requires Chrome/Edge 123+)
+
+It currently includes three groups:
+
+- `issues.errors` — global runtime errors handling
+- `issues.webVitals` — aggregated Core Web Vitals report
+- `issues.longTasks` and `issues.longAnimationFrames` — freeze-related detectors
+
+Freeze detectors use two complementary APIs:
+
+- **Long Tasks API** — browser reports tasks taking longer than 50 ms.
+- **Long Animation Frames (LoAF)** — browser reports frames taking longer than 50 ms with richer script attribution (Chrome 123+, Edge 123+).
+
+Both freeze detectors are disabled by default. If enabled and one API is unsupported, the other still works.
+Each detected freeze is reported immediately with detailed context (duration, blocking time, scripts involved, etc.).
+`thresholdMs` is an additional Hawk filter on top of browser reporting. Hawk emits an issue when measured duration is equal to or greater than this value. Values below `50ms` are clamped to `50ms`.
+
+### Web Vitals (Aggregated)
+
+When `issues.webVitals` is enabled, Hawk collects Core Web Vitals (`LCP`, `FCP`, `TTFB`, `INP`, `CLS`) and sends a single issue event when at least one metric is rated `poor`.
+Reporting happens when all five metrics are collected, or earlier on timeout/page unload to avoid waiting indefinitely on pages where some metrics never fire.
+
+The event context contains all metrics with:
+- `value`
+- `rating`
+- `delta`
+
+`web-vitals` is an optional peer dependency and is loaded only when `issues.webVitals: true`.
+
+### Disabling
+
+Disable global errors handling:
+
+```js
+const hawk = new HawkCatcher({
+  token: 'INTEGRATION_TOKEN',
+  issues: {
+    errors: false
+  }
+});
+```
+
+### Selective Configuration
+
+Configure all issue detectors:
+
+```js
+const hawk = new HawkCatcher({
+  token: 'INTEGRATION_TOKEN',
+  issues: {
+    errors: true,
+    webVitals: true,
+    longTasks: {
+      thresholdMs: 70
+    },
+    longAnimationFrames: {
+      thresholdMs: 200
+    }
+  }
+});
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `errors` | `boolean` | `true` | Enable global errors handling (`window.onerror` and `unhandledrejection`). |
+| `webVitals` | `boolean` | `false` | Collect all Core Web Vitals and send one issue event when at least one metric is rated `poor`. Requires optional `web-vitals` dependency. |
+| `longTasks` | `boolean` or `{ thresholdMs?: number }` | `false` | `false` disables. `true` enables with default threshold. Object enables and uses `thresholdMs` when valid; otherwise fallback threshold `70ms` is used (minimum effective value `50ms`). |
+| `longAnimationFrames` | `boolean` or `{ thresholdMs?: number }` | `false` | `false` disables. `true` enables with default threshold. Object enables and uses `thresholdMs` when valid; otherwise fallback threshold `200ms` is used (minimum effective value `50ms`). Requires Chrome 123+ / Edge 123+. |
+
 ## Source maps consuming
 
 If your bundle is minified, it is useful to pass source-map files to the Hawk. After that you will see beautiful

packages/javascript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hawk.so/javascript",
-  "version": "3.2.18",
+  "version": "3.3.0",
   "description": "JavaScript errors tracking for Hawk.so",
   "files": [
     "dist"
@@ -41,6 +41,14 @@
   "dependencies": {
     "error-stack-parser": "^2.1.4"
   },
+  "peerDependencies": {
+    "web-vitals": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "web-vitals": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@hawk.so/types": "0.5.8",
     "jsdom": "^28.0.0",