[browser-client] add sequence id plugin#1861
Conversation
| "@rrweb/rrweb-plugin-sequential-id-record": patch | ||
| --- | ||
|
|
||
| Add browser-client `sequenceId` assignment for Cloud-bound events and allow the sequential-id record plugin to resume from a provided starting ID. |
There was a problem hiding this comment.
this should be split in two changesets, one for browser-client, and one with the changes for the plugin
There was a problem hiding this comment.
Split into separate changesets in 9a25441: one for @rrweb/browser-client and one for @rrweb/rrweb-plugin-sequential-id-record.
There was a problem hiding this comment.
Pull request overview
This pull request adds browser-client-owned, persistent sequenceId assignment for all events sent from @rrweb/browser-client to rrweb Cloud, and enhances @rrweb/rrweb-plugin-sequential-id-record so it can resume sequencing from a caller-provided starting point while optionally preserving existing valid IDs.
Changes:
- Added
sequenceIdstate management in@rrweb/browser-client, persisting the latest value insessionStorageperrecordingId, and ensuring every outbound event is sequenced before serialization. - Extended
@rrweb/rrweb-plugin-sequential-id-recordwithstartId+preserveExistingoptions and added a Vitest test suite for the new behavior. - Updated documentation/specs and integration tests to assert increasing
sequenceIdvalues.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| packages/plugins/rrweb-plugin-sequential-id-record/vitest.config.ts | Adds package-level Vitest config for plugin tests. |
| packages/plugins/rrweb-plugin-sequential-id-record/tsconfig.json | Adjusts TS project config and adds project reference(s). |
| packages/plugins/rrweb-plugin-sequential-id-record/test/index.test.ts | Adds unit tests for startId/preserveExisting and default behavior. |
| packages/plugins/rrweb-plugin-sequential-id-record/src/index.ts | Implements new plugin options and normalization logic. |
| packages/plugins/rrweb-plugin-sequential-id-record/README.md | Documents new plugin options and intended usage. |
| packages/plugins/rrweb-plugin-sequential-id-record/package.json | Adds Vitest scripts/deps for plugin testing. |
| packages/browser-client/tsconfig.json | Adds project reference to the sequential-id record plugin. |
| packages/browser-client/test/sequence-id.test.ts | Adds happy-dom tests covering browser-client sequencing + persistence behavior. |
| packages/browser-client/test/integration.test.ts | Adds assertions that server-returned events have increasing sequenceId values. |
| packages/browser-client/src/index.ts | Adds sequencing helpers, storage persistence, and plugin injection into the record pipeline. |
| packages/browser-client/README.md | Documents browser-client sequencing semantics and persistence behavior. |
| packages/browser-client/package.json | Adds plugin dependency so sequencing plugin is bundled/available. |
| docs/superpowers/specs/2026-06-02-browser-client-sequence-id-design.md | Adds design spec for sequencing architecture, goals, and testing strategy. |
| docs/superpowers/plans/2026-06-02-browser-client-sequence-id.md | Adds implementation plan detailing tasks, steps, and verification commands. |
| .changeset/browser-client-sequence-id.md | Adds changeset for patch releases of browser-client and the plugin. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
🦋 Changeset detectedLatest commit: 8495733 The changes in this PR will be included in the next version bump. This PR includes changesets to release 20 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Bundle Size ChangesSize change: +18.88 kB (+0.19%) | Total size: 9735.65 kB
|
| File | Base | PR | Diff |
|---|---|---|---|
browser-client.cjs |
191.96 kB | 197.07 kB | +5.11 kB (+2.66%) |
browser-client.js |
191.73 kB | 196.84 kB | +5.11 kB (+2.67%) |
browser-client.umd.cjs |
194.78 kB | 199.94 kB | +5.16 kB (+2.65%) |
browser-client.umd.min.cjs |
90.97 kB | 92.93 kB | +1.96 kB (+2.15%) |
plugins 🔍 - 4.35 kB -> 5.89 kB (+1.54 kB (+35.44%))
| File | Base | PR | Diff |
|---|---|---|---|
packages/plugins/rrweb-plugin-sequential-id-record/dist/rrweb-plugin-sequential-id-record.cjs |
681 B | 1.10 kB | +446 B (+65.49%) 🔍 |
packages/plugins/rrweb-plugin-sequential-id-record/dist/rrweb-plugin-sequential-id-record.js |
548 B | 994 B | +446 B (+81.39%) 🔍 |
packages/plugins/rrweb-plugin-sequential-id-record/dist/rrweb-plugin-sequential-id-record.umd.cjs |
1.72 kB | 2.15 kB | +446 B (+25.34%) 🔍 |
packages/plugins/rrweb-plugin-sequential-id-record/dist/rrweb-plugin-sequential-id-record.umd.min.cjs |
1.43 kB | 1.67 kB | +241 B (+16.43%) 🔍 |
| }; | ||
| const sessionStorageName = 'rrweb-browser-client-recording-id'; | ||
| const sequenceStoragePrefix = 'rrweb-browser-client-sequence-id:'; | ||
| const browserClientStartTokenName = '__rrweb_browser_client_start_token__'; |
There was a problem hiding this comment.
what happens if we have multiple versions of the same plugin running here across multiple rrweb versions. We could even have multi tab recording across multiple rrweb sessions
There was a problem hiding this comment.
if we can we should use recording-id in here
There was a problem hiding this comment.
Scoped this by recording ID in 349706f: the delayed-start window token now uses __rrweb_browser_client_start_token__:${recordingId} instead of one fixed global key. Added coverage for the recording-scoped key and for invalidating only the matching recording ID. Follow-up commits db92d8a/8495733c keep permanent-stop cancellation working if storage is unavailable by falling back to tracked active token names without using Array.from.
This pull request adds browser-client-managed
sequenceIdassignment to all Cloud-bound events and enhances the sequential-id record plugin to support resuming from a provided starting ID. The changes ensure that every event sent from@rrweb/browser-clientto Cloud has a unique, incrementingsequenceId, which is persisted in session storage per recording ID to allow correct ordering across same-tab navigations and page reloads. The sequential-id plugin is now included in the browser-client bundle, and new options allow it to start from the current sequence state and preserve existing IDs. The implementation also updates documentation and adds robust error handling for sequence state persistence.Sequence ID Management and Persistence:
All browser-client events sent to Cloud now include a top-level
sequenceId, which is incremented and persisted insessionStorageper recording ID, allowing correct ordering even across same-tab navigations and reloads. Gaps in the sequence are permitted if events are lost before reaching the server. ([[1]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8R203-R303),[[2]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8R460-R466),[[3]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8L393-R540),[[4]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8L407-R574),[[5]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8R586-R607),[[6]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-2bdf284b861b6d2a5636130cc53e24c0ffe000c9d7849c17b6c10e23adfbd741R68-R69),[[7]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-c4205cb8d35d732d6f3ad1288c218d3c5e0da64c8674dedcf0bc1e19c57e339dR1-R6))Introduced helpers for reading, persisting, and removing sequence state, and for guaranteeing that every outbound event has a valid
sequenceId. The sequence state is initialized from storage and advanced on every event serialization. ([[1]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8R203-R303),[[2]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8R152-R157))Sequential-ID Plugin Enhancements:
Added
@rrweb/rrweb-plugin-sequential-id-recordas a browser-client dependency and included it in the recording pipeline. The plugin now acceptsstartIdandpreserveExistingoptions, allowing it to resume from the current sequence and avoid overwriting valid existing IDs. ([[1]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-0c093a6d6ad9d0724147893036442dd3b5fb7c91205bad783e3c12212f294f62R68),[[2]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8R2),[[3]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8R50-R58),[[4]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8R203-R303))The plugin is built immediately before each
record()call, ensuring it always starts from the latest sequence state, and is appended after any user-supplied plugins withpreserveExisting: true. ([[1]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8R203-R303),[[2]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8R586-R607))API and Documentation Updates:
[[1]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-2bdf284b861b6d2a5636130cc53e24c0ffe000c9d7849c17b6c10e23adfbd741R68-R69),[[2]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-275fc204ca8eed360e226f94007f48ee9d04d62eb24c72f516ca0e6192c9b49cR1-R159))Error Handling and Robustness:
0, and storage failures do not block recording. Sequence IDs are not reused after transport failures, and duplicate IDs are prevented. ([[1]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-67ff6dc74469cd8f3fc41b16068a323c3f5b956d087b855040eada60ccef6df8R203-R303),[[2]](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-275fc204ca8eed360e226f94007f48ee9d04d62eb24c72f516ca0e6192c9b49cR1-R159))Testing and Verification:
[docs/superpowers/specs/2026-06-02-browser-client-sequence-id-design.mdR1-R159](https://github.com/rrweb-io/rrweb/pull/1861/files#diff-275fc204ca8eed360e226f94007f48ee9d04d62eb24c72f516ca0e6192c9b49cR1-R159))References:
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15]