@cross-deck/web 1.6.4 → 1.8.0

package/CHANGELOG.md

@@ -2,26 +2,43 @@
 
 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.4] — 2026-06-01
-
-Patch — contract-integrity fixes. Two issues found by adversarial testing of
-the shipped contracts against real wire traffic. No public API change.
-
-**`super-property-merge-precedence` — registered super-properties now win over
-auto-collected fields, as the contract claims.** The merge had an inverted
-guard (`if (!(k in enriched))`) so a device-seeded key (`os`, `locale`,
-`timezone`, …) silently clobbered a value set via `register()`. Effective order
-is now **caller > super > auto-collected**; caller properties still win.
-
-**Three contracts were stamped `runtimeVerified: true` but only had a boot-time
-self-test (off by default in production) — now they run on real production
-hot-path hooks.** `flush-interval-parity` validates the live flush interval on
-every `track()`; `sdk-error-codes-catalogue` confirms each real wire error's
-code carries remediation on `onErrorParse`; `contract-failed-payload-schema-lock`
-schema-locks the actual outgoing telemetry on the emit path. The bundled-manifest
-generator now derives `runtimeVerified` from the presence of a hot-path hook
-(not merely a registered verifier), so the flag can no longer claim runtime
-enforcement a verifier doesn't deliver.
+## [1.8.0] — 2026-06-11
+
+**PARK on version-rejection — events are held, never dropped.** A third
+event-queue outcome for the day the server stops accepting an outdated event
+format. Purely additive; no public API change.
+
+**Added:**
+
+- **PARK (HTTP `426` / `sdk_version_unsupported`).** Previously a permanent 4xx
+  dropped the batch. Now a version-rejection is recognised as its own outcome —
+  distinct from retry (transient) and drop (invalid): the data is good, only the
+  wire dialect is stale. The queue **holds** the events (folded to the front of
+  the durable localStorage queue, FIFO-capped at 1000), **hushes** (stops
+  flushing a known-too-old payload — no wasted battery/bandwidth), **signals**
+  once (one `console.warn` + a typed `sdk.parked` debug event the dashboard
+  reads), and **backfills** on the next page load after you upgrade. So "paused,
+  not lost — held on-device, resumes on upgrade" is literally true.
+- **`sdk_version_unsupported`** added to the error-codes catalogue with
+  remediation, and `version_error` to `CrossdeckErrorType`. `CrossdeckError`
+  now carries `minVersion` / `surface` (parsed from the 426 body) so the PARK
+  message names the exact version to update to.
+- New `onParked` queue callback (host → dashboard heartbeat channel).
+- Bundle-size budget: UMD min 33 → 35 KB gzipped (~0.5 KB for the PARK branch +
+  onParked + catalogue entry + minVersion/surface). core/react/vue unchanged,
+  under budget.
+
+See https://cross-deck.com/docs/sdk-event-durability/ for the full durability
+contract.
+
+## [1.7.0] — 2026-06-10
+
+Event Envelope v1 conformance (`backend/docs/event-envelope-spec-v1.md`). Wire-breaking change (pre-launch; free). No public API change.
+
+- **`envelopeVersion: 1`** (integer) added to every batch POST body (spec §1). Distinct from `sdk.version`; the server uses it to gate parsing and will refuse payloads without it once enforcement deploys.
+- **`seq`** (number) on every event (spec §3). Per-session monotonic integer, assigned synchronously at `track()` time alongside `timestamp` (one sample). Counter lives in `AutoTracker`, resets to 0 at every session boundary (`session.started`, `resetSession()`, 30-min idle rollover), and persists across tab hide/show within a session. The deterministic tiebreak for events sharing a timestamp.
+- **`context`** object on every event (spec §4). Device/platform facts (`os`, `osVersion`, `appVersion`, `sdkName`, `sdkVersion`, `locale`, `timezone`, `browser`, `browserVersion`) are promoted OUT of `properties` into a standardised top-level object. `properties` retains screen dimensions and all app-supplied properties. This aligns the Web SDK field-set with Swift (which ships `os`, `osVersion`, `sdkName`, `sdkVersion`, `locale`, `timezone`, `deviceModel`), closing the Q3 drift documented in the spec's Phase-0 audit matrix.
+- Bundle-size budget: core ESM + CJS 58 → 60 KB gzipped (~0.5 KB for the envelope fields + browser/browserVersion detection; CJS landed at 58.26, over the old ceiling). react/vue ESM and UMD unchanged, comfortably under budget.
 
 ## [1.6.3] — 2026-06-01
 
@@ -45,38 +62,46 @@ regardless, so context is preserved on other errors.
 
 ## [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.
+Session-boundary correctness, plus the per-platform contract runtime status
+that had been sitting unreleased. No public API change; `session.ended`
+emission timing changes as described, so read before upgrading if you key
+downstream logic 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.
+**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 inactivity 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.
+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.
+
+**Per-platform contract runtime status + a 7th live verifier.** Each bundled
+
+**Per-platform contract runtime status + a 7th live verifier.** Each bundled
+contract now carries `runtimeVerified` — whether *this* SDK self-verifies it
+at runtime vs. proving it in CI only. It is derived at build time from the
+SDK's `STATIC_VERIFIERS` registry (never hand-set), so the registry can't
+disagree with what actually runs. `CrossdeckContracts` consumers can read it
+to distinguish "watch it pass live" from "CI-proven every release".
+
+- New runtime verifier `sdk-error-codes-catalogue` (boot self-test: every
+  backend wire code carries a description + resolution in the shipped
+  catalogue). Web now self-verifies **7** contracts live.
+- Bundle-size budget: UMD min 32 → 33 KB (~0.4 KB gzipped for the flag + the
+  new verifier's frozen 15-code list). Other bundles unchanged, under budget.
+
+## [1.6.0] — 2026-05-30
+
+Minor — two autocapture fidelity fixes. 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