@cross-deck/web 1.5.7 → 1.6.2

package/CHANGELOG.md

@@ -2,6 +2,78 @@
 
 All notable changes to `@cross-deck/web` will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.2] — 2026-05-31
+
+Patch — session-boundary correctness. A stored session could span a gap
+longer than the 30-minute inactivity window in two cases the resume logic
+missed, fragmenting journey grouping. Both are now fixed. No public API
+change; `session.ended` emission timing changes as described, so read
+before upgrading if you have downstream logic keyed on it.
+
+**A tab left open and idle, then used again, no longer stretches one
+session across the gap.** `markActivity()` now rolls to a new session when
+an event lands after the 30-minute window has lapsed — covering the case
+the page-load and tab-return resume checks miss entirely (a tab kept open
+and idle, then interacted with, with no visibility transition). A single
+stored session can no longer contain a >30-minute gap.
+
+**Returning to a long-idle tab no longer back-dates `session.ended`.** The
+visibility-resume path emitted `session.ended` at the moment of return —
+more than 30 minutes after the session's last real event — which itself
+opened an intra-session gap. The prior session now ends implicitly (its
+end inferred from its last event), consistent with the page-load resume
+path. If you key downstream logic on `session.ended`, note it no longer
+fires on a >30-minute tab-return.
+
+## [1.6.1] — 2026-05-30
+
+Minor — two autocapture fidelity fixes, plus a repair to the release
+pipeline itself. (1.6.0 carried the same two fixes but never reached npm:
+its automated publish hit a pre-existing broken test gate — a schema-lock
+test that loaded a contract via a monorepo-only path that doesn't exist
+in the published package. Fixed by reading the contract from the copy
+bundled into the SDK, so this is the first build of these changes to
+ship.) No public API change; event emission behaviour changes as
+described, so read before upgrading if you have downstream logic keyed on
+`session.ended` timing.
+
+**Sessions now survive full-page navigations.** Session state was
+in-memory only, so on a multi-page site (where the SDK re-installs on
+every navigation) one visit was split into a separate session per page —
+each `session.ended` on `pagehide` landing at the same instant the next
+page's `session.started` fired. Sessions are now persisted (id, start,
+last-activity, first-touch acquisition) to the same storage adapter as
+identity and **resumed** across page loads within a rolling 30-minute
+inactivity window.
+
+- `session.started` no longer fires on a resumed page load — only on a
+  genuinely new session (first visit, or first load after >30 min idle).
+- `session.ended` no longer fires on `pagehide` / `beforeunload` (a
+  navigation is not a session end). It fires only on real 30-min
+  inactivity or an explicit `Crossdeck.stop()`.
+- The inactivity window is bumped by every tracked event (auto or
+  custom), not just pageviews/clicks.
+- Honours consent posture: with `persistIdentity: false` or a
+  `MemoryStorage` adapter, the session is in-memory only (per-page, the
+  prior behaviour).
+- Continuity is same-origin (localStorage); cross-subdomain stitching is
+  not yet handled.
+
+**Click autocapture no longer mashes labels.** A click on a control that
+wraps other controls or a content block (a card around several buttons, a
+hero `<a>` around a heading + paragraph) used to collapse the whole
+subtree into one string — `"Log inContinue with GoogleContinue with
+Apple…"`, `"Tudo que você é,em um só link.Portfolio…"`. The resolver now
+returns the control's own label (word boundaries preserved, decorative
+`svg`/`style`/`script` skipped), or for a wrapper its direct label / the
+first heading inside it, falling through to the selector rather than a
+concatenation. Attribute precedence (`data-*` → aria → value → text →
+title → img/svg) is unchanged.
+
+Bundle-size budget for the core bundles raised 55 → 58 KB gzipped (ESM +
+CJS) to fit the ~1 KB of new code; react/vue/UMD bundles unchanged and
+still under budget.
+
 ## [1.5.1] — 2026-05-27
 
 `crossdeck.contract_failed` is now single-fire to a dedicated

package/README.md

@@ -86,13 +86,15 @@ That's the full happy path.
 
 | Event | When |
 |---|---|
-| `session.started` | On boot. Carries `sessionId`. |
-| `session.ended` | On `pagehide` / `beforeunload`, OR when returning to a tab after >30 min idle. Carries `sessionId` and `durationMs`. |
+| `session.started` | When a **new** session begins — first visit, or the first page load after >30 min of inactivity. A session resumed across a page navigation does **not** re-fire it. Carries `sessionId`. |
+| `session.ended` | On a real session end only: >30 min of inactivity, or an explicit `Crossdeck.stop()`. Carries `sessionId` and `durationMs`. |
 | `page.viewed` | On initial load + every SPA navigation (`history.pushState`, `replaceState`, `popstate`). Carries `path`, `url`, `search`, `hash`, `title`, `referrer`. |
 
-Every event — auto-tracked and developer-emitted — is enriched with the device-info payload below. Quick tab switches (Cmd-Tab, switching browser tabs) don't end the session — only real closes do, matching GA4's session-window convention.
+Every event — auto-tracked and developer-emitted — is enriched with the device-info payload below.
 
-**Per-session acquisition (v0.6.0+):** when a session starts the SDK reads `window.location.search` and `document.referrer` and captures `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, plus `referrer`. Non-empty values are auto-attached to every subsequent event of that session — first-touch attribution stays pinned to the entry URL even after SPA route changes strip the params away. A new session (>30 min idle) re-reads the URL.
+**Sessions survive page loads (v1.6.0+).** A session is a *visit*, not a page. The SDK persists the session (id, start time, last-activity time, first-touch acquisition) to the same storage as identity, so a full-page navigation on a multi-page site **resumes the same session** rather than starting a new one. The window is a rolling 30-minute inactivity timer bumped by every tracked event (auto or custom); only real 30-min inactivity or `Crossdeck.stop()` ends it. A page unload (`pagehide`/`beforeunload`) is treated as a navigation, not an end. Quick tab switches (Cmd-Tab) likewise don't end the session — matching GA4's session-window convention. Continuity is same-origin; cross-subdomain stitching is on the roadmap. With `persistIdentity: false` (or a `MemoryStorage` adapter) the session is in-memory only and resets per page.
+
+**Per-session acquisition (v0.6.0+):** when a session starts the SDK reads `window.location.search` and `document.referrer` and captures `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, plus `referrer`. Non-empty values are auto-attached to every subsequent event of that session — first-touch attribution stays pinned to the entry URL even after SPA route changes strip the params away, and now stays pinned across full-page navigations within the session too. A new session (>30 min idle) re-reads the URL.
 
 ## Auto-attached device info
 

package/dist/contracts.json

@@ -1,10 +1,10 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "generatedAt": "2026-05-28T10:12:32.152Z",
+  "generatedAt": "2026-06-01T05:25:25.624Z",
   "sdk": "@cross-deck/web",
-  "sdkVersion": "1.5.7",
-  "bundledIn": "@cross-deck/web@1.5.7",
-  "count": 8,
+  "sdkVersion": "1.6.2",
+  "bundledIn": "@cross-deck/web@1.6.2",
+  "count": 9,
   "contracts": [
     {
       "id": "contract-failed-payload-schema-lock",
@@ -126,7 +126,7 @@
         "legal/security/index.html#diagnostic",
         "legal/sdk-data/index.html#b-diagnostic"
       ],
-      "bundledIn": "@cross-deck/web@1.5.7"
+      "bundledIn": "@cross-deck/web@1.6.2"
     },
     {
       "id": "error-envelope-shape",
@@ -165,7 +165,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 8 (codifies existing contract)",
-      "bundledIn": "@cross-deck/web@1.5.7"
+      "bundledIn": "@cross-deck/web@1.6.2"
     },
     {
       "id": "flush-interval-parity",
@@ -210,7 +210,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.3",
-      "bundledIn": "@cross-deck/web@1.5.7"
+      "bundledIn": "@cross-deck/web@1.6.2"
     },
     {
       "id": "idempotency-key-deterministic",
@@ -315,7 +315,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 2.2.a + 2.2.b + 2.2.c",
-      "bundledIn": "@cross-deck/web@1.5.7"
+      "bundledIn": "@cross-deck/web@1.6.2"
     },
     {
       "id": "init-reentry-drains-prior-queue",
@@ -342,7 +342,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 5.5",
-      "bundledIn": "@cross-deck/web@1.5.7"
+      "bundledIn": "@cross-deck/web@1.6.2"
     },
     {
       "id": "per-user-cache-isolation",
@@ -421,7 +421,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 1.3 (web/RN) + dogfood-gap fix (swift + android)",
-      "bundledIn": "@cross-deck/web@1.5.7"
+      "bundledIn": "@cross-deck/web@1.6.2"
     },
     {
       "id": "sdk-error-codes-catalogue",
@@ -435,9 +435,14 @@
       "codeRef": [
         "sdks/web/src/error-codes.ts",
         "sdks/node/src/error-codes.ts",
+        "sdks/web/src/_contract-verifiers.ts",
         "backend/src/api/v1-errors.ts"
       ],
       "testRef": [
+        {
+          "file": "sdks/web/tests/contract-verifiers.test.ts",
+          "name": "sdk-error-codes-catalogue covers every backend wire code with remediation"
+        },
         {
           "file": "sdks/web/tests/error-codes-backfill.test.ts",
           "name": "includes backend code"
@@ -461,7 +466,48 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 6.2",
-      "bundledIn": "@cross-deck/web@1.5.7"
+      "bundledIn": "@cross-deck/web@1.6.2"
+    },
+    {
+      "id": "super-property-merge-precedence",
+      "pillar": "analytics",
+      "status": "enforced",
+      "claim": "Every Crossdeck SDK merges event properties with the precedence device < super < caller (caller-supplied values win over registered super-properties, which win over auto-attached device info). Pre-v1.4.0 Swift had it INVERTED (super < device < caller — device clobbered super), so a `register('plan', 'pro')` super-property was silently overridden by auto-attached device fields whenever keys collided. Cross-SDK funnel queries on super-property keys returned different answers per platform.",
+      "appliesTo": [
+        "web",
+        "swift"
+      ],
+      "codeRef": [
+        "sdks/web/src/super-properties.ts",
+        "sdks/web/src/_contract-verifiers.ts",
+        "sdks/swift/Sources/Crossdeck/EventPropertyMerge.swift",
+        "sdks/swift/Sources/Crossdeck/Crossdeck.swift"
+      ],
+      "testRef": [
+        {
+          "file": "sdks/web/tests/contract-verifiers.test.ts",
+          "name": "super-property-merge-precedence verifies caller > super > device"
+        },
+        {
+          "file": "sdks/swift/Tests/CrossdeckTests/EventPropertyMergeTests.swift",
+          "name": "test_super_overrides_device"
+        },
+        {
+          "file": "sdks/swift/Tests/CrossdeckTests/EventPropertyMergeTests.swift",
+          "name": "test_caller_overrides_super"
+        },
+        {
+          "file": "sdks/swift/Tests/CrossdeckTests/EventPropertyMergeTests.swift",
+          "name": "test_full_precedence_chain"
+        },
+        {
+          "file": "sdks/swift/Tests/CrossdeckTests/EventPropertyMergeTests.swift",
+          "name": "test_matchesWebNodeRNPrecedence"
+        }
+      ],
+      "registeredAt": "2026-05-26",
+      "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.2",
+      "bundledIn": "@cross-deck/web@1.6.2"
     },
     {
       "id": "sync-purchases-funnel-parity",
@@ -494,7 +540,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.5",
-      "bundledIn": "@cross-deck/web@1.5.7"
+      "bundledIn": "@cross-deck/web@1.6.2"
     }
   ]
 }