blocfeed 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.20.0 — 2026-05-07
+
+### Signal accuracy
+
+- **rage-click now emits exactly one event per burst.** The previous behaviour fired an immediate `final: false` event at threshold-crossing and a follow-up `final: true` after the streak idled out, so a single rage produced two server-side rows the dashboard had to reconcile. The detector now emits a single event with `final: true` and the full `click_count` once the streak ends (`streakIdleMs`, default 1500). On `pagehide`, in-progress bursts that crossed the threshold are flushed via the same code path so we don't lose data when the user closes the tab mid-rage.
+
+### New: stable element keys
+
+- New `stable_key: string | null` field on every `BehavioralEvent`. Built by walking up to four ancestors and emitting the first of `data-blocfeed-component` (→ `bf:component:<value>`), a `data-testid` family attribute (→ `bf:testid:<value>`), or `id` (→ `bf:id:<value>`). Lets the backend dedupe and aggregate events for the "same logical element" across re-renders even when the CSS selector path shifts.
+- The `rage_click` and `dead_click` detectors now key their internal grouping maps on `stable_key ?? selector`, so bursts and rate-limit budgets follow the logical element, not its current selector path.
+- New exported helper `buildStableElementKey(el, maxDepth?)` from `blocfeed/shared/dom`.
+
+---
+
+## 0.19.0 — 2026-05-07
+
+### Signal accuracy fixes
+
+- **rage-click** now emits a follow-up `final: true` event with the real total `click_count` after the click streak ends (default 1500 ms idle). Previously the count was capped at the threshold, so a 20-click rage looked identical to a 3-click rage. New `RageClickConfig.streakIdleMs` (default 1500).
+- **dead-click** observation is now scoped to the click target's nearest interesting ancestor (button / a / form / [role=button]) instead of the entire document body. Unrelated re-renders elsewhere on the page no longer suppress real dead clicks.
+- **httpFail** now catches fetch exceptions (network errors, CORS, abort) and emits with `event_data.http_status: 0` and `error_kind: "network" | "abort"`. Also adds `404, 408, 409, 429` to the default tracked status codes. New optional `treatJsonErrorAsFail` config to flag 2xx responses with `{ ok: false }` / `{ error }` / `{ success: false }` bodies.
+- **formDataLoss** clears dirty state on `submit` and `reset` events, and suppresses bfcache emission for 60 s after a successful submit. Eliminates false "form abandonment" events on successful conversions.
+
+### Reliability fixes
+
+- **Sampling consistency.** Behavioral and replay sampling now both use the same deterministic `simpleHash(session_id) % 100` decision. A sampled session is in both cohorts or neither — no more "signal exists but no replay" or vice-versa.
+- **Replay restart after inactivity.** The 30-min inactivity timer now triggers a soft pause (uninstalls rrweb, keeps the controller alive). A one-shot pointerdown/keydown listener resumes recording when the user returns. The 4-hour absolute cap still terminates fully. New `pause_count` field appears in chunk POST bodies.
+
+### New: widget heartbeat
+
+- New `installHeartbeat()` helper (auto-installed by `BehavioralTracker`) POSTs to `/api/heartbeat` every 5 minutes (and on pagehide) with `{ blocfeed_id, session_id, version, page_url, user_agent, sdk_features }`. Lets the dashboard surface a "last seen" indicator and detect silent SDK breakage.
+- New exported constant `SDK_VERSION` from `blocfeed`.
+
+---
+
 ## 0.18.0 — 2026-04-30
 
 - **feat:** new `track(name, properties?, options?)` API on `BlocFeedApi` and exported as `BlocFeed.track()` for non-React usage. Send custom events to BlocFeed for funnels, conversion tracking, and segment filters.