diff --git a/content/llms-root.txt b/content/llms-root.txt
index 8cab4b770..9a38b80e0 100644
--- a/content/llms-root.txt
+++ b/content/llms-root.txt
@@ -58,6 +58,7 @@ Keploy (founded 2021) is a CNCF Landscape project and API testing platform with
## UI Testing (Beta)
- [UI Testing overview](https://keploy.io/docs/running-keploy/ui-capture/): Record real user sessions in a web app with the capture SDK (@keploy/capture-sdk) and read each visit as UI flows and journeys in the dashboard, over the REST API, or from an AI agent through MCP
- [Dashboard quickstart](https://keploy.io/docs/ui-capture/quickstart-dashboard/): Create an ingest key, add it to a sample React shop, and see your first flows
+- [Install the SDK](https://keploy.io/docs/ui-capture/install-sdk/): Add @keploy/capture-sdk to a React and Vite app, a Next.js App Router app or plain HTML pages, and check that recordings arrive
- [From first visit to journeys](https://keploy.io/docs/ui-capture/walkthrough-dashboard/): Record five visits, read their flows and journeys, read the same data from a script, and clean up
- [AI agent quickstart](https://keploy.io/docs/ui-capture/quickstart-agent/): Connect Claude Code, Cursor, Codex or another MCP client to Keploy and have it set up UI capture in your frontend
- [An agent onboards a web app](https://keploy.io/docs/ui-capture/walkthrough-agent/): Every MCP tool call an agent makes to set up UI capture and read flows and journeys, with the answers
diff --git a/docusaurus.config.js b/docusaurus.config.js
index 5ebd9fdc5..b2005d835 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -221,14 +221,11 @@ s.parentNode.insertBefore(b, s);})(window.lintrk);`,
"@docusaurus/plugin-client-redirects",
{
redirects: [
- // The README of @keploy/capture-sdk 3.0.1, on npm.
+ // The README of @keploy/capture-sdk 3.0.1, on npm. Its other link,
+ // /ui-capture/install-sdk/, is a page of its own.
// scripts/verify-ui-capture-sdk-links.js keeps every link the SDK
// ships resolvable.
{from: "/ui-capture/overview/", to: "/running-keploy/ui-capture/"},
- {
- from: "/ui-capture/install-sdk/",
- to: "/running-keploy/ui-capture/#install-the-sdk",
- },
// Pages that moved into the Universal Mocker section.
{
from: "/running-keploy/mock-quickstart/",
diff --git a/scripts/verify-ui-capture-sdk-links.js b/scripts/verify-ui-capture-sdk-links.js
index 46cbdc1ed..66c0cd797 100644
--- a/scripts/verify-ui-capture-sdk-links.js
+++ b/scripts/verify-ui-capture-sdk-links.js
@@ -97,7 +97,8 @@ const README_LINKS = [
// The README of the releases after 3.0.1.
"https://keploy.io/docs/",
"https://keploy.io/docs/running-keploy/ui-capture/",
- // The README of 3.0.1, on npm: pages that have since moved.
+ // The README of 3.0.1, on npm: the overview, since moved (a redirect),
+ // and the install page.
"https://keploy.io/docs/ui-capture/overview/",
"https://keploy.io/docs/ui-capture/install-sdk/",
];
diff --git a/versioned_docs/version-4.0.0/running-keploy/ui-capture.md b/versioned_docs/version-4.0.0/running-keploy/ui-capture.md
index decd8c72b..b66754729 100644
--- a/versioned_docs/version-4.0.0/running-keploy/ui-capture.md
+++ b/versioned_docs/version-4.0.0/running-keploy/ui-capture.md
@@ -108,8 +108,7 @@ await KeployCapture.init({
Use the `endpoint` the setup card or the API gives you. It is `https://api.keploy.io/ui/v1/ingest` on Keploy Cloud, and your own API server's URL followed by `/ui/v1/ingest` when you self-host. A self-hosted API server builds it from its `API_SERVER_URL`; if that isn't set to the server's public URL, the API returns an empty `endpoint` and says so in `next`, rather than guessing.
- **Early, and once.** The SDK starts recording the page's requests once it has loaded rrweb, which your bundler normally puts in a chunk of its own. A request the page makes before then is not recorded, so start `init` before your app's own code runs. Call it once per page load, not per route: a second `init` returns the same capture.
-- **Three sample setups.** The [UI capture sample shops](https://github.com/keploy/samples-typescript) show the call in a React and Vite app (`ui-capture-react-shop`: `src/keploy.ts`, imported first in `src/main.tsx`), a Next.js App Router app (`ui-capture-next-shop`: `instrumentation-client.ts`) and plain HTML pages with no bundler (`ui-capture-html-shop`).
-- **Without a bundler**, serve the package's `dist/` directory as it is, import `dist/index.mjs` from it, and map `rrweb` with an import map before the SDK loads. If rrweb cannot be loaded, the capture ends before anything is sent and reports [`KUI_E_DOM_RECORDER_UNAVAILABLE`](../ui-capture/errors.md#kui-e-dom-recorder-unavailable).
+- **Per framework.** [Install the SDK](../ui-capture/install-sdk.md) shows the call in a React and Vite app, a Next.js App Router app and plain HTML pages with no bundler, from the [UI capture sample shops](https://github.com/keploy/samples-typescript). [Bundlers and frameworks](../ui-capture/bundlers.md) says what webpack, Parcel, esbuild and a page with no bundler need, and [Content-Security-Policy and workers](../ui-capture/csp-and-workers.md) what a CSP must allow.
### SDK options {#sdk-options}
diff --git a/versioned_docs/version-4.0.0/ui-capture/bundlers.md b/versioned_docs/version-4.0.0/ui-capture/bundlers.md
new file mode 100644
index 000000000..767745af9
--- /dev/null
+++ b/versioned_docs/version-4.0.0/ui-capture/bundlers.md
@@ -0,0 +1,166 @@
+---
+id: bundlers
+title: Bundlers and frameworks for the Keploy capture SDK
+sidebar_label: Bundlers and frameworks
+description: Which bundlers and frameworks the Keploy capture SDK is built with in its tests, what each needs, and how it loads its body worker and chunks.
+tags:
+ - UI testing
+ - UI capture
+ - capture SDK
+keywords:
+ - capture SDK
+ - Vite
+ - Next.js
+ - webpack
+ - Create React App
+ - Parcel
+ - esbuild
+ - import map
+ - Web Worker
+---
+
+import ProductTier from '@site/src/components/ProductTier';
+
+
+
+`@keploy/capture-sdk` is an ES module that your bundler builds into your app. Besides its main bundle, it loads a few files of its own while it runs, and your build must emit and deploy them:
+
+- **rrweb**, the library it records the page with, which `init()` imports;
+- **its body redaction code** and **its body worker**, a Web Worker that redacts request and response bodies off your page's main thread, with a small module that starts it;
+- **its GraphQL code**, the first time a request body could be a GraphQL request;
+- **its attribute list**, under `privacyMode: "strict"` only.
+
+Most bundlers emit all of them on their own. This page says which setups the SDK's tests build, and what the others need.
+
+## Tested setups {#tested-setups}
+
+The SDK's tests install the package, packed as it is for publishing, beside each of these bundlers, build an app that starts a capture, and check in Chromium that it records a GraphQL request with its term, records under `privacyMode: "strict"`, and redacts a large request body.
+
+| Setup | Version tested | Body worker | What you do |
+| ----------------------------------------------------------------------------------------------- | -------------------- | ----------- | ------------------------------------------------------------------------------------- |
+| [Vite](#vite) | 8.3.8 | Yes | Nothing |
+| [Next.js](#nextjs), with Turbopack (its default) | 16.4.3, React 19.3.1 | Yes | Nothing |
+| [Next.js](#nextjs), with `--webpack` | 16.4.3, React 19.3.1 | Yes | Nothing |
+| [webpack 5](#webpack-5) | 5.112.2 | Yes | Nothing |
+| webpack 5 with babel-loader, for Chrome 60 and Safari 11 | 5.112.2 | Yes | Run babel-loader over `node_modules`, and set webpack's `target` to the same browsers |
+| [webpack 4](#webpack-4-and-create-react-app-4) with babel-loader, as Create React App 4 runs it | 4.47.0 | No | Nothing; bodies are redacted on the main thread |
+| [Parcel 2](#parcel-2) | 2.16.4 | Yes | `npm install buffer` |
+| [esbuild](#esbuild) | 0.28.2 | No | Copy the worker beside your bundle |
+| [esbuild](#esbuild), with the worker copied | 0.28.2 | Yes | — |
+| [No bundler](#no-bundler), an import map for rrweb | — | Yes | Serve the package's `dist/` as it is, and map `rrweb` |
+
+The three [UI capture sample shops](https://github.com/keploy/samples-typescript) are built and tested in their own CI: React with Vite 8.3.8, Next.js 16.4.3 with the App Router, and plain HTML pages with no bundler. [Install the SDK](./install-sdk.md#add-it-to-your-app) shows their setup.
+
+## Where there is no body worker {#where-there-is-no-body-worker}
+
+The SDK starts its worker as `new Worker(new URL("./body-worker.js", import.meta.url))`, which webpack 5, Next.js (webpack and Turbopack), Vite and Parcel 2 turn into a file of your build. Where the worker cannot run, the capture still records every request and response, and redacts the bodies on the page's main thread instead, each only up to its first 64 KiB: a body over that is recorded cut, under a first line `[Body cut: 65536 of N characters kept, unverified]`. The SDK says so once per page with the [`KUI_E_BODY_WORKER_UNAVAILABLE`](./errors.md#kui-e-body-worker-unavailable) warning. There is no worker:
+
+- under **webpack 4**, which cannot parse `import.meta`;
+- under **esbuild**, until you copy the worker beside your bundle;
+- in a build that loads the SDK's **CommonJS** files (its `require` entry), whose worker start has no `import.meta`;
+- when your build's **assets are served from another origin**, such as webpack's `publicPath` or Next.js's `assetPrefix` on a CDN: a browser runs a worker only from the page's own origin;
+- when the page's **Content-Security-Policy** does not let your origin run it: see [Content-Security-Policy and workers](./csp-and-workers.md).
+
+With any other bundler, check that your build emits the worker. [Redaction off the main thread](./network-and-bodies.md#redaction-off-the-main-thread) says what a cut body looks like.
+
+## Vite {#vite}
+
+Vite emits everything on its own. In the [React sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-react-shop)'s production build, `npm run build` writes rrweb, the SDK's body redaction code, its body worker, its GraphQL code and its attribute list as files of their own under `dist/assets/`, beside the app's own bundle. Deploy all of them.
+
+Under `npm run dev`, React's development checks (`StrictMode`) make every request twice, and the recording shows both, so check what is recorded against a production build (`npm run build && npm run preview`).
+
+## Next.js {#nextjs}
+
+Next.js emits the worker with Turbopack, its default, and with `--webpack`: in the [Next.js sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-next-shop)'s build, with Turbopack, it is `.next/static/media/body-worker..js`. The SDK's tests build both with an App Router page and a Pages Router page. The sample shop starts the capture from `instrumentation-client.ts`: see [Install the SDK](./install-sdk.md#add-it-to-your-app).
+
+- With `assetPrefix` on a CDN, the worker is served from another origin and cannot run.
+- The SDK records what runs in the browser. A fetch in a server component runs on the server and is not recorded.
+
+## webpack 5 {#webpack-5}
+
+webpack 5 reads the package's `exports` map, bundles the SDK's chunks and emits its worker. A build transpiled for older browsers builds too: the SDK's tests build webpack 5 with babel-loader for Chrome 60 and Safari 11, and check that every script it emits parses as ES2019, without `import()` or optional chaining. For that:
+
+- **Run babel-loader over `node_modules` too.** The SDK's and rrweb's files use newer syntax, such as optional chaining, so a rule that excludes `node_modules` leaves it in your bundle.
+- **Set webpack's own `target` to the same browsers** (`target: "browserslist:chrome 60, safari 11"` in the tests), or webpack's runtime code keeps syntax those browsers cannot parse.
+
+The tests run that build in current Chromium, not in Chrome 60 or Safari 11.
+
+With `publicPath` on another origin, the worker cannot run.
+
+## webpack 4 and Create React App 4 {#webpack-4-and-create-react-app-4}
+
+webpack 4 ignores a package's `exports` map and reads its `module` field, which names `dist/index.bundler.mjs`: the same SDK, built so that webpack 4 never reads `import.meta`. It resolves the SDK's GraphQL code and strict's attribute list through the `request-term/package.json` and `strict-attributes/package.json` the package ships. So the build works, with no worker: the main thread redacts bodies, each up to 64 KiB, and the console shows `KUI_E_BODY_WORKER_UNAVAILABLE` once per page load that records bodies. To redact large bodies whole, move to webpack 5 or another bundler that emits the worker.
+
+The SDK's tests run webpack 4 as Create React App 4 runs it: with babel-loader over `node_modules`, since webpack 4's parser predates the syntax the SDK and rrweb ship, and with Node's legacy OpenSSL provider (`NODE_OPTIONS=--openssl-legacy-provider`), since webpack 4 hashes with MD4. They also build the same entry for the server, as webpack 4's `target: "node"`, Nuxt 2 and Angular Universal 9 to 11 build it.
+
+## Parcel 2 {#parcel-2}
+
+Parcel 2 needs the `buffer` package:
+
+```bash
+npm install buffer
+```
+
+rrweb's build reads Node's `Buffer`, and Parcel bundles no polyfill for a Node built-in unless its package is installed. That is rrweb's need, and SDK 3.0.1 has it too. When `buffer` is missing, Parcel 2.16 installs it by itself, as a dev dependency, unless the `CI` environment variable is set. With `CI` set, `parcel build` fails, naming rrweb's files and saying:
+
+```text
+@parcel/resolver-default: Node builtin polyfill "buffer/" is not installed, but auto install is disabled.
+```
+
+Install it yourself, so that every build has it.
+
+Parcel reads the package's `module` field, as webpack 4 does, and the package's `alias` sends it to the worker's start, so Parcel emits the worker.
+
+## esbuild {#esbuild}
+
+esbuild does not emit the worker: copy it from the package into your output directory, beside your bundle, and it runs. The SDK's tests build esbuild with `--format=esm --splitting`, so that rrweb and the SDK's chunks stay files of their own:
+
+```bash
+npx esbuild src/main.js --bundle --format=esm --splitting --outdir=dist
+cp node_modules/@keploy/capture-sdk/dist/body-worker.js dist/
+```
+
+## No bundler {#no-bundler}
+
+There is no script-tag build. Without a bundler:
+
+- **Serve the package's `dist/` directory as it is**, and import `dist/index.mjs` from it. The SDK loads its other files from beside `dist/index.mjs`: `body-redact.mjs`, `request-term.mjs`, `strict-attributes.mjs` under strict, and `body-worker-unbundled.mjs`, which starts `body-worker.js`.
+- **Map `rrweb` with an import map** before the SDK loads, to rrweb's `dist/rrweb.js`. The SDK imports `rrweb` by name, which only a bundler or an import map resolves.
+- An import map that also maps `@keploy/capture-sdk/body-redact`, `/body-worker-start`, `/request-term` or `/strict-attributes` is used first.
+
+A page that serves `dist/index.mjs` alone has no code to redact a body with: it records each body as not captured, never in the clear, and refuses every strict capture with [`KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE`](./errors.md#kui-e-strict-attributes-unavailable). Without the import map, rrweb cannot load, and the capture ends before anything is sent with [`KUI_E_DOM_RECORDER_UNAVAILABLE`](./errors.md#kui-e-dom-recorder-unavailable).
+
+The [plain HTML sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-html-shop) does exactly this: see the **Plain HTML** tab of [Install the SDK](./install-sdk.md#add-it-to-your-app).
+
+## Assets on a CDN {#assets-on-a-cdn}
+
+A browser runs a worker only from the page's own origin. So when your build's assets are served from a CDN, through webpack's `publicPath` or Next.js's `assetPrefix`, the SDK's chunks load from there, but its worker cannot run, and bodies over 64 KiB are recorded cut.
+
+Loading the SDK itself from a CDN with no bundler works the same way: the chunks load from the CDN, which must send CORS headers, as CDNs do, and the worker cannot. Import `dist/index.mjs` by its path, for example `https://cdn.jsdelivr.net/npm/@keploy/capture-sdk@3.1.0/dist/index.mjs`:
+
+- unpkg's package root redirects to `dist/index.mjs`, so it works too.
+- jsDelivr's package root answers with the file at the root's own URL, where no chunk is beside it, so name the path.
+- Don't load the package root with unpkg's `?module`. It serves `dist/index.bundler.mjs`, the build for webpack 4, which loads no chunk from beside it: it records every body as not captured and refuses every strict capture.
+
+To have the worker, serve `dist/` from your own origin.
+
+## Size {#size}
+
+The SDK's main bundle, `dist/index.mjs`, is about 40.9 kB gzipped, rrweb not included; the CommonJS `dist/index.js` is 41.1 kB. Its other files load only when a capture needs them:
+
+| File | Gzipped | Loaded |
+| ---------------------------- | ------------ | ---------------------------------------------------------------------------------------- |
+| `dist/body-redact.mjs` | about 9.7 kB | At `init()`, beside rrweb, for a capture that records bodies (the default, `"balanced"`) |
+| `dist/body-worker.js` | about 9.3 kB | In the page's next idle period after such a capture starts |
+| `dist/strict-attributes.mjs` | about 1.3 kB | Under `privacyMode: "strict"` only, which loads neither body file |
+| `dist/request-term.mjs` | about 1.2 kB | The first time a request body could be a GraphQL request |
+
+The figures were measured on the SDK repository's build, as the package's README and the [3.1.0 release notes](./capture-sdk-3-1-0-release-notes.md#size) give them; the published files differ by a few bytes. The package also ships source maps beside each file, for your tools; they are never inlined.
+
+## Related
+
+- [Install the SDK](./install-sdk.md)
+- [Content-Security-Policy and workers](./csp-and-workers.md)
+- [Network calls and bodies](./network-and-bodies.md)
+- [`KUI_E_BODY_WORKER_UNAVAILABLE`](./errors.md#kui-e-body-worker-unavailable)
+- [UI capture sample shops](https://github.com/keploy/samples-typescript)
diff --git a/versioned_docs/version-4.0.0/ui-capture/csp-and-workers.md b/versioned_docs/version-4.0.0/ui-capture/csp-and-workers.md
new file mode 100644
index 000000000..712a86003
--- /dev/null
+++ b/versioned_docs/version-4.0.0/ui-capture/csp-and-workers.md
@@ -0,0 +1,96 @@
+---
+id: csp-and-workers
+title: Content-Security-Policy and workers for UI capture
+sidebar_label: Content-Security-Policy and workers
+description: What the Keploy capture SDK loads and sends while it runs, the Content-Security-Policy directives it needs, and what happens when one is blocked.
+tags:
+ - UI testing
+ - UI capture
+ - capture SDK
+keywords:
+ - Content-Security-Policy
+ - CSP
+ - worker-src
+ - connect-src
+ - script-src
+ - Web Worker
+ - service worker
+ - import map
+---
+
+import ProductTier from '@site/src/components/ProductTier';
+
+
+
+If your site sends a `Content-Security-Policy` header, it must let the capture SDK load its own files, start its body worker and post to Keploy's ingest endpoint. This page lists what the SDK loads and sends, the directives that allow each, and what the SDK does when one is blocked. It also covers pages a service worker serves, and pages that start offline.
+
+## What the SDK loads and sends {#what-the-sdk-loads-and-sends}
+
+Besides the SDK's main bundle, which is part of your app's bundle, a capture loads these files while it runs. Your bundler emits each as a file of your build (Vite names them `rrweb-.js`, `body-redact-.js` and so on); with no bundler, they are the files of the package's `dist/` directory.
+
+| What | When | Directive |
+| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------- |
+| rrweb, the library that records the page | At `init()`, for every capture | `script-src` |
+| The body redaction code (`body-redact`) | At `init()`, beside rrweb, for a capture that records bodies (the default) | `script-src` |
+| The worker's start (`body-worker-start`; `body-worker-unbundled.mjs` with no bundler) | Just before the body worker | `script-src` |
+| The body worker (`body-worker.js`) | In the page's next idle period after such a capture starts | `worker-src` |
+| The GraphQL code (`request-term`) | The first time a request body could be a GraphQL request | `script-src` |
+| The attribute list (`strict-attributes`) | At `init()`, beside rrweb, under `privacyMode: "strict"` only, which loads neither body file | `script-src` |
+| The batches, posted to your `endpoint` | Every few seconds while there is something to send, with `fetch` | `connect-src` |
+
+A capture that masks every body, under `privacyMode: "strict"` or with `privacy.maskNetworkBodies: true`, loads neither the body code nor the worker.
+
+## The directives it needs {#the-directives-it-needs}
+
+- **`script-src`** must allow the SDK's chunks wherever your build serves them, as it allows the rest of your build's scripts. When they are served from your own origin, `'self'` does.
+- **`worker-src 'self'`** lets the body worker run, or the `child-src` or `script-src` that a policy with no `worker-src` falls back to. A browser runs a worker only from the page's own origin, so the worker must be served from it.
+- **`connect-src`** must allow the ingest endpoint's origin: `https://api.keploy.io` on Keploy Cloud, or your own API server's origin when you self-host.
+
+For example, under this policy the [React sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-react-shop)'s production build records its visits in Chromium with no violation: its body worker runs, and a GraphQL request sent from the page loads the GraphQL code. That check posted to a local test ingest, whose origin took the place of `https://api.keploy.io`.
+
+```text
+Content-Security-Policy: default-src 'self'; script-src 'self'; worker-src 'self'; connect-src 'self' https://api.keploy.io
+```
+
+A policy for your own app also needs whatever the rest of your app loads.
+
+### Without a bundler {#without-a-bundler}
+
+The import map that tells the browser where `rrweb` is (see [No bundler](./bundlers.md#no-bundler)) is an inline script, so `script-src 'self'` alone blocks it. Allow it by its hash: the SHA-256 of the text between ``, whitespace included, base64-encoded. Under this policy, with the hash of its own import map, the [plain HTML sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-html-shop)'s pages record their visits in Chromium with no violation, again with a local test ingest in place of `https://api.keploy.io`:
+
+```text
+Content-Security-Policy: default-src 'self'; script-src 'self' 'sha256-Im2C7SeFUs3EXTFUZJSteww4lP72+k39AUQCo6TeygI='; worker-src 'self'; connect-src 'self' https://api.keploy.io
+```
+
+Your own import map has a hash of its own. The surest way to get it: when the policy blocks the import map, Chromium's console error names the hash it expects. Without the import map, rrweb cannot be imported, and the capture ends before anything is sent with [`KUI_E_DOM_RECORDER_UNAVAILABLE`](./errors.md#kui-e-dom-recorder-unavailable).
+
+## What happens when one is blocked {#what-happens-when-one-is-blocked}
+
+| Blocked | What the SDK does | You see |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| rrweb | Ends the capture before sending anything, with `fetch` and `XMLHttpRequest` left unpatched | [`KUI_E_DOM_RECORDER_UNAVAILABLE`](./errors.md#kui-e-dom-recorder-unavailable) in `onError` and the console |
+| The attribute list, under strict | Ends the capture before recording anything | [`KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE`](./errors.md#kui-e-strict-attributes-unavailable) in `onError` and the console |
+| The body worker | Goes on recording, and redacts each body on the main thread instead, up to 64 KiB: a body over that is recorded cut | One [`KUI_E_BODY_WORKER_UNAVAILABLE`](./errors.md#kui-e-body-worker-unavailable) warning, `"part":"worker"` |
+| The body redaction code | Goes on recording; a body the main thread must redact is recorded as not captured, never in the clear | One `KUI_E_BODY_WORKER_UNAVAILABLE` warning, `"part":"code"` |
+| The GraphQL code | Goes on recording; each request that could be GraphQL is recorded with the term `body:*`, and the load is not retried on that page | One [`KUI_E_REQUEST_TERM_FAILED`](./errors.md#kui-e-request-term-failed) warning |
+| The ingest endpoint (`connect-src`) | Reads each refused upload as a network failure: keeps the events, retries with backoff, never calls `onError`; past `maxQueueSize` or 16 MiB held, events are dropped: see [Batching and outages](./sessions-and-sampling.md#batching-and-outages) | A Content-Security-Policy error in the console for each upload; nothing arrives in Keploy |
+
+A browser keeps a failed module import for the life of the page, so after you fix the policy, reload the page: calling `init()` again on the same page does not load the file.
+
+A warning does not end the capture: the SDK writes it with `console.warn`, never `console.error`, so a page whose tests or error tracker fail on console errors does not fail on one.
+
+## Service workers and offline starts {#service-workers-and-offline-starts}
+
+- **A page that starts offline** does not ask for rrweb until the browser is back online, since a browser keeps a failed module import for the life of the page. It patches `fetch` and `XMLHttpRequest` at once, so the page's requests are recorded, and sends nothing until rrweb has loaded. If rrweb then cannot load, the capture ends with `KUI_E_DOM_RECORDER_UNAVAILABLE`, and what it recorded meanwhile is dropped, unsent.
+- **A page a service worker controls** (`navigator.serviceWorker.controller` is set) is different: a service worker can answer the import with no network, so `init()` asks for rrweb at once and records what the visitor does offline. Precache rrweb's chunk with the rest of your app, and under strict its attribute list too.
+- **Any service worker in control counts**, one with no `fetch` handler included. An `init()` called offline under it asks for rrweb at once. If the service worker cannot answer, the import fails and the capture is refused at that `init()`, and again at an `init()` made once the browser is back online, until the page is loaded again.
+
+The SDK's body worker is a dedicated Web Worker that the SDK starts with `new Worker`, not a service worker.
+
+## Related
+
+- [Install the SDK](./install-sdk.md)
+- [Bundlers and frameworks](./bundlers.md)
+- [Network calls and bodies](./network-and-bodies.md#redaction-off-the-main-thread)
+- [`KUI_E_BODY_WORKER_UNAVAILABLE`](./errors.md#kui-e-body-worker-unavailable)
+- [UI Capture errors and warnings](./errors.md)
diff --git a/versioned_docs/version-4.0.0/ui-capture/install-sdk.md b/versioned_docs/version-4.0.0/ui-capture/install-sdk.md
new file mode 100644
index 000000000..df8cfa8e1
--- /dev/null
+++ b/versioned_docs/version-4.0.0/ui-capture/install-sdk.md
@@ -0,0 +1,272 @@
+---
+id: install-sdk
+title: Install the Keploy capture SDK in your web app
+sidebar_label: Install the SDK
+description: Add @keploy/capture-sdk to a React and Vite app, a Next.js App Router app or plain HTML pages, start it early, and check that recordings arrive.
+tags:
+ - UI testing
+ - UI capture
+ - capture SDK
+keywords:
+ - capture SDK
+ - "@keploy/capture-sdk"
+ - install
+ - React
+ - Vite
+ - Next.js
+ - import map
+ - ingest key
+ - Do Not Track
+ - Global Privacy Control
+---
+
+import ProductTier from '@site/src/components/ProductTier';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+
+The Keploy capture SDK, `@keploy/capture-sdk`, records what people do in your web app and the requests the page makes, masks personal data in the browser, and posts the recording to Keploy in batches. This page adds it to your own app: install the package, call `init` once and early, keep the ingest key in your configuration, and check that recordings arrive. It describes SDK 3.1.0.
+
+The code on this page comes from the three [UI capture sample shops](https://github.com/keploy/samples-typescript): one small shop built with React and Vite (`ui-capture-react-shop`), with the Next.js App Router (`ui-capture-next-shop`), and as plain HTML pages with no bundler (`ui-capture-html-shop`). Each sample's CI visits it in Chromium and checks what its SDK sent.
+
+## Before you begin
+
+You need an **ingest key** for the Keploy app you want to record into, and the **ingest endpoint** the SDK sends to.
+
+- In the dashboard, open **UI Testing → UI Flows** and click **Create ingest key**: see [Create an ingest key](./quickstart-dashboard.md#create-an-ingest-key).
+- With the REST API, `POST /client/v1/apps//ui/ingest-keys` returns the key as `apiKey` and the `endpoint` to use; an AI agent calls the same thing as the MCP tool `uiCaptureSetup`. See [Create an ingest key](./rest-api.md#create-an-ingest-key).
+
+The endpoint is `https://api.keploy.io/ui/v1/ingest` on Keploy Cloud. When you self-host Keploy, it is your API server's URL followed by `/ui/v1/ingest`.
+
+## Install {#install}
+
+```bash
+npm install @keploy/capture-sdk
+```
+
+Install it as a runtime dependency, not a dev one: it runs in production, in your visitors' browsers. Its only dependency is `rrweb`, the library it records the page with, which your bundler resolves, and it has no peer dependencies. The package ships ES module and CommonJS builds with TypeScript types. The samples pin the exact version they are tested with, `"@keploy/capture-sdk": "3.1.0"`.
+
+There is no script-tag build: the only way in is an `import`. A page with no bundler imports it from the package's `dist/` directory, as the **Plain HTML** tab below shows.
+
+## Call init once, as early as you can {#call-init-once-as-early-as-you-can}
+
+`KeployCapture.init` starts the capture. It has two required options: `endpoint`, the ingest endpoint, and `apiKey`, your ingest key, which the SDK sends in the `X-API-Key` header of every batch. Every other option has a default. Each sample calls it once, from a module of its own; this is the React shop's:
+
+```ts title="src/keploy.ts (excerpt)"
+import {KeployCapture} from "@keploy/capture-sdk";
+
+const endpoint = import.meta.env.VITE_KEPLOY_INGEST_ENDPOINT;
+const apiKey = import.meta.env.VITE_KEPLOY_INGEST_KEY;
+
+async function startCapture(): Promise {
+ if (!endpoint || !apiKey) {
+ console.info(
+ "[shop] Keploy UI capture is off: set VITE_KEPLOY_INGEST_ENDPOINT and VITE_KEPLOY_INGEST_KEY in .env"
+ );
+ return;
+ }
+ await KeployCapture.init({
+ endpoint,
+ apiKey,
+ // The default, written out: every typed value is masked, and the page's
+ // visible text is kept. "strict" also masks all visible text and records
+ // no request or response body.
+ privacyMode: "balanced",
+ privacy: {
+ // Text that repeats what the shopper typed: the order confirmation
+ // shows their email, so its text is masked.
+ maskSelectors: ["[data-testid=order-confirmation]"],
+ // Never recorded: the reviews (people's names) are replaced by an
+ // empty box of the same size.
+ blockSelectors: ["[data-testid=reviews]"],
+ // A route whose path holds a credential, such as an invite link, is
+ // declared so its value is kept out of every event. The shop has none:
+ // secretRoutes: ["/invites/:key"],
+ },
+ onError(err) {
+ // The visitor's browser sends Do Not Track or Global Privacy Control:
+ // nothing is recorded, and nothing needs fixing.
+ if (err.code === "KUI_E_CAPTURE_DECLINED") return;
+ console.error(
+ `[shop] Keploy UI capture stopped: ${err.code}`,
+ err.message
+ );
+ },
+ });
+ const sessionId = KeployCapture.getSessionId();
+ if (sessionId)
+ console.info(`[shop] Keploy UI capture is recording session ${sessionId}`);
+}
+
+/** Settles once capture has started, or once it is off, declined or refused. */
+export const captureStarted: Promise = startCapture().catch(
+ (err: unknown) => {
+ console.error("[shop] Keploy UI capture did not start:", err);
+ }
+);
+```
+
+The Next.js and plain HTML shops make the same call; only where they read the endpoint and key differs (see the tabs below).
+
+- **As early as you can.** `init()` loads rrweb, which your bundler puts in a chunk of its own, before it starts recording the page's `fetch` and `XMLHttpRequest` calls. A request the page makes before then is not recorded at all. Starting `init()` before your app's own code runs narrows that window, but nothing closes it, so the first request of a page load may be missing from its recording. Each sample's `npm test` prints whether its first page's request was recorded. See [Start capture before your first call](./network-and-bodies.md#start-capture-before-your-first-call).
+- **Without holding your app back.** Start `init()` and let your app go on: don't make rendering or routing wait for it. Online, an awaited `init()` resolves only once rrweb has loaded, and a refused one can resolve about 30 seconds after the call, longer in a hidden tab (see [Handle SDK errors and warnings](./errors.md#handle-sdk-errors-and-warnings)). The samples start it first and never wait for it.
+- **Once per page load, not per route.** A second `init()` returns the capture that is already running, and `KeployCapture.stop()` ends it, so that a later `init()` starts a new session. In a single-page app a session holds the page load's route changes too, up to `maxSessionDuration` (10 minutes by default): see [Single-page apps and navigation](./spa-navigation.md) and [Sessions and sampling](./sessions-and-sampling.md#what-a-session-is). On a site whose links load pages, every page load runs `init()` again and starts a session of its own.
+- **In the browser.** Call it from code that runs in the browser, not during server-side rendering. The Next.js shop's module does nothing on the server.
+
+## Add it to your app {#add-it-to-your-app}
+
+
+
+
+The [React shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-react-shop) (React 19, Vite 8, React Router) calls `init` in `src/keploy.ts`, above. `src/main.tsx` imports that module before anything else, so the capture starts before the app's own code runs:
+
+```tsx title="src/main.tsx (excerpt)"
+// Keploy UI capture first, so it starts before any of the app's code: see keploy.ts.
+import "./keploy";
+```
+
+Vite reads the endpoint and key from `.env` into `import.meta.env`, and `src/vite-env.d.ts` declares the two variables for TypeScript:
+
+```bash title=".env"
+VITE_KEPLOY_INGEST_ENDPOINT=https://api.keploy.io/ui/v1/ingest
+VITE_KEPLOY_INGEST_KEY=kep_YOUR_INGEST_KEY
+```
+
+Vite builds the SDK's own files as chunks of your build, beside rrweb's, and emits its body worker as a file. Deploy every file the build emits: see [Bundlers and frameworks](./bundlers.md#vite).
+
+
+
+
+The [Next.js shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-next-shop) (Next.js 16 App Router) starts the capture from `instrumentation-client.ts`, at the shop's root: Next.js runs that file in the browser before the app hydrates.
+
+```ts title="instrumentation-client.ts (excerpt)"
+// Next.js runs this file in the browser before the app hydrates, so Keploy
+// UI capture starts from here. lib/keploy.ts does the work.
+import "./lib/keploy";
+```
+
+`lib/keploy.ts` makes the React shop's `init` call. It reads the endpoint and key from `NEXT_PUBLIC_` variables:
+
+```ts title="lib/keploy.ts (excerpt)"
+const endpoint = process.env.NEXT_PUBLIC_KEPLOY_INGEST_ENDPOINT;
+const apiKey = process.env.NEXT_PUBLIC_KEPLOY_INGEST_KEY;
+```
+
+And it starts nothing on the server, where Next.js renders the pages too:
+
+```ts title="lib/keploy.ts (excerpt)"
+/** Settles once capture has started, or once it is off, declined or refused. */
+export const captureStarted: Promise =
+ typeof window === "undefined"
+ ? Promise.resolve()
+ : startCapture().catch((err: unknown) => {
+ console.error("[shop] Keploy UI capture did not start:", err);
+ });
+```
+
+```bash title=".env"
+NEXT_PUBLIC_KEPLOY_INGEST_ENDPOINT=https://api.keploy.io/ui/v1/ingest
+NEXT_PUBLIC_KEPLOY_INGEST_KEY=kep_YOUR_INGEST_KEY
+```
+
+Next.js writes `NEXT_PUBLIC_` variables into the page when it builds it, so build again after you change them.
+
+The SDK records the requests the browser makes. A fetch in a server component runs on the server and is not part of the recording; the shop's pages are client components that fetch their data in the browser. Next.js's own requests from the browser are recorded too: a `` fetches its page's server component payload (`GET /products?_rsc=…`) as it prefetches or when it is followed.
+
+
+
+
+Without a bundler, serve the package's `dist/` directory as it is and import `dist/index.mjs` from it. The SDK imports `rrweb` by name, so map that name with an import map before the SDK loads. The [plain HTML shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-html-shop)'s server, `server.mjs`, serves `node_modules/@keploy/capture-sdk/dist/` at `/vendor/capture-sdk/` and rrweb's `dist/` at `/vendor/rrweb/`, and every page has these lines in its ``:
+
+
+```html title="pages/index.html (excerpt)"
+
+
+
+
+```
+
+`app/keploy.js` is the React shop's `src/keploy.ts` in plain JavaScript, with the SDK imported by its path:
+
+```js title="app/keploy.js (excerpt)"
+import {KeployCapture} from "/vendor/capture-sdk/index.mjs";
+import {apiKey, endpoint} from "/keploy-config.js";
+```
+
+- **Serve the whole `dist/` directory**, not `index.mjs` alone. The SDK loads its other files from beside `dist/index.mjs`: its body redaction code, its GraphQL code, its body worker and, under `privacyMode: "strict"`, its attribute list. A page that serves `index.mjs` alone records each request and response body as not captured, and refuses every strict capture.
+- **Install rrweb yourself**, at a version inside the SDK's own `rrweb` range, so that npm installs one copy, at `node_modules/rrweb`. The shop's `package.json` lists `"rrweb": "2.2.2"`.
+- **The endpoint and key** come from the shop's `.env`, which its server hands to `app/keploy.js` as `/keploy-config.js`. On your own static site, write them into your `keploy.js`: an ingest key is safe to ship in a page.
+
+```bash title=".env"
+KEPLOY_INGEST_ENDPOINT=https://api.keploy.io/ui/v1/ingest
+KEPLOY_INGEST_KEY=kep_YOUR_INGEST_KEY
+```
+
+Every link on this site loads a page, so each page load starts its own capture and is a session of its own, and a page's flows never span two pages. If the import map is missing or rrweb cannot load, the capture ends before anything is sent, with [`KUI_E_DOM_RECORDER_UNAVAILABLE`](./errors.md#kui-e-dom-recorder-unavailable). A Content-Security-Policy must allow the import map, an inline script: see [Content-Security-Policy and workers](./csp-and-workers.md#without-a-bundler).
+
+
+
+
+## Choose a privacy mode {#choose-a-privacy-mode}
+
+Masking happens in the browser, before anything is sent. `privacyMode` sets how much the SDK records:
+
+| `privacyMode` | Typed values | Visible text | Request and response bodies |
+| ---------------------------- | ------------------------------------------ | --------------------------------------------------------------- | --------------------------- |
+| `"balanced"` (the default) | Masked in every input, textarea and select | Recorded, except inside `maskSelectors` | Recorded, redacted |
+| `"strict"`, for public sites | Masked | Masked, and every attribute value that can hold text is blanked | Not recorded |
+| `"off"` | Masked only in password and hidden fields | Recorded, except inside `maskSelectors` | Recorded, redacted |
+
+`"strict"` also replaces every query value in a URL. Under `"balanced"` and `"off"`, a body's values under a credential's name, such as `password` or `token`, are replaced with `[REDACTED]` before it is sent.
+
+The dashboard's setup card and the REST API's `init` snippet set only `endpoint` and `apiKey`, so they record under `"balanced"`. The samples write `privacyMode: "balanced"` out, so the choice is visible in the code. Strict still records `data-testid` values as written, so never build one from user data. [Privacy and masking](./privacy.md) covers every rule, and what each mode still records.
+
+## Keep the key in configuration {#keep-the-key-in-configuration}
+
+- **The key is safe to ship.** An ingest key can post recordings into the one app it was made for and do nothing else: no reads and no other API. That is why it can sit in a page every visitor can read. Never put any other kind of Keploy key in its place: the ingest server refuses a personal access token with `403`.
+- **Read it from the build's configuration**, as the samples do: `VITE_` variables for Vite, `NEXT_PUBLIC_` variables for Next.js. Both are built into the page, so rebuild after you change one.
+- **One key records into one app**, the one it was made for: the SDK sends no app of its own, so a key made for another app is accepted, and its recordings go into that app with no error. An app's journey shares are shares of every session the app receives, so give an environment whose visits you don't want mixed with production's, such as staging or CI, an app and a key of its own: see [One app per environment](./ingest-keys.md#one-app-per-environment).
+
+## Visitors who send Do Not Track or Global Privacy Control {#visitors-who-send-do-not-track-or-global-privacy-control}
+
+The SDK honours both signals by default (`honorPrivacySignals: true`). When a visitor's browser sends Global Privacy Control (`navigator.globalPrivacyControl === true`) or Do Not Track (`navigator.doNotTrack === "1"`, or as older browsers spell it), `init()` records, patches and sends nothing for that page load. The SDK then:
+
+- calls `onError` with [`KUI_E_CAPTURE_DECLINED`](./errors.md#kui-e-capture-declined), in a task of its own after the `init()` call, for every declined `init()` except one made while 16 already wait for their hand-over;
+- writes one `console.info` line per page, not a `console.error`.
+
+Some browsers send Global Privacy Control by default, Brave and DuckDuckGo among them, so expect this from a share of your real visitors. It is not an error: return early on `KUI_E_CAPTURE_DECLINED` in `onError` and keep it out of your error tracking, as the samples' `onError` does. Calling `init()` again does not help: every `init()` is declined while the browser sends the signal.
+
+Set `honorPrivacySignals: false` only where your site has its own lawful basis to record such visitors and says so in its privacy policy. The SDK then records regardless of the signals.
+
+## Handle errors {#handle-errors}
+
+`onError` is called once when a condition that ends the capture happens: the ingest server refused a batch (a revoked key, a wrong endpoint), or the SDK refused to start (rrweb could not load, a conflicting privacy option, the visitor's privacy signal). Branch on `err.code`, never on the message. The samples' `onError`, above, returns on `KUI_E_CAPTURE_DECLINED` and logs every other code.
+
+- **A refusal before anything is sent does not reject `init()`.** It reaches `onError` in a task of its own, and `init()` resolves once the handler has run.
+- **Warnings don't call `onError`.** The capture goes on, and the SDK writes one `console.warn` line with the code, such as [`KUI_E_BODY_WORKER_UNAVAILABLE`](./errors.md#kui-e-body-worker-unavailable).
+- **A `429`, a `5xx` or a network failure is not an error.** The SDK retries with backoff and never calls `onError` for it.
+
+[UI Capture errors and warnings](./errors.md) explains every code: what happened, why, and how to fix it.
+
+## Check that it works {#check-that-it-works}
+
+1. **Open your app with your browser's developer tools.** `KeployCapture.getSessionId()` returns the id of the session being recorded, and `""` when no session is live; the samples log it as `[shop] Keploy UI capture is recording session `.
+2. **Watch the Network tab.** While you click around, the SDK posts a batch to `/ui/v1/ingest` every few seconds (every 5 seconds by default), and each is answered `200`.
+3. **Check that sessions arrive in Keploy.** The dashboard's setup card counts them under **3. Check that sessions arrive**, and `GET /client/v1/apps//ui/capture-status` reports the same: see [Watch the sessions arrive](./quickstart-dashboard.md#watch-the-sessions-arrive) and [Capture status](./rest-api.md#capture-status).
+
+Nothing is posted? Check the console for a `KUI_E_` code, and test in a browser that sends neither Do Not Track nor Global Privacy Control: in one that does, nothing is recorded, as above. A `401` or `403` on those posts means the key is missing, unknown, expired, revoked or not an ingest key.
+
+## Other bundlers and frameworks {#other-bundlers-and-frameworks}
+
+The SDK's tests build it with webpack 4 and 5, Parcel 2, Next.js (Turbopack and webpack), Vite, esbuild, and with no bundler. [Bundlers and frameworks](./bundlers.md) says what each needs. If your site sends a Content-Security-Policy, read [Content-Security-Policy and workers](./csp-and-workers.md).
+
+## Related
+
+- [Dashboard quickstart](./quickstart-dashboard.md)
+- [Privacy and masking](./privacy.md)
+- [Single-page apps and navigation](./spa-navigation.md)
+- [Bundlers and frameworks](./bundlers.md)
+- [UI Capture errors and warnings](./errors.md)
diff --git a/versioned_docs/version-4.0.0/ui-capture/quickstart-dashboard.md b/versioned_docs/version-4.0.0/ui-capture/quickstart-dashboard.md
index de9a15394..39599a17a 100644
--- a/versioned_docs/version-4.0.0/ui-capture/quickstart-dashboard.md
+++ b/versioned_docs/version-4.0.0/ui-capture/quickstart-dashboard.md
@@ -226,7 +226,7 @@ This is not an error to fix. Keep `KUI_E_CAPTURE_DECLINED` out of your error tra
## Next steps
- [From first visit to journeys](./walkthrough-dashboard.md): record five visits along three paths, read their flows and journeys, read the same data from a script, and clean up.
-- [Install the SDK in your own app](../running-keploy/ui-capture.md#install-the-sdk): the same `init` call, in your app's entry point.
+- [Install the SDK in your own app](./install-sdk.md): the same `init` call, in a React and Vite app, a Next.js app or plain HTML pages.
- [UI Capture errors and warnings](./errors.md): what each `KUI_E_` code the SDK reports means and how to fix it.
## Related
diff --git a/versioned_docs/version-4.0.0/ui-capture/spa-navigation.md b/versioned_docs/version-4.0.0/ui-capture/spa-navigation.md
new file mode 100644
index 000000000..9345bff08
--- /dev/null
+++ b/versioned_docs/version-4.0.0/ui-capture/spa-navigation.md
@@ -0,0 +1,103 @@
+---
+id: spa-navigation
+title: Single-page apps and navigation in UI capture
+sidebar_label: Single-page apps and navigation
+description: How the Keploy capture SDK records route changes in a single-page app, what counts as a page change, and how each route becomes its own flow.
+tags:
+ - UI testing
+ - UI capture
+ - capture SDK
+keywords:
+ - single-page app
+ - SPA
+ - client-side routing
+ - history.pushState
+ - hash router
+ - Navigation API
+ - React Router
+ - Next.js
+ - UI flows
+---
+
+import ProductTier from '@site/src/components/ProductTier';
+
+
+
+In a single-page app, a click on a link changes the route without loading a page. Since SDK 3.1.0 the capture SDK records each such route change, so every step it records belongs to the page it happened on, and Keploy makes each route its own flow. This page says what counts as a page change, what a route change records, and what the SDK cannot see.
+
+## Sessions and page loads {#sessions-and-page-loads}
+
+The SDK starts a session when `init()` runs, once per page load, and a single-page app's route changes stay in that session. So a visit to Home, Products, Cart and Checkout in the [React sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-react-shop) is one session holding four pages. A session also ends at `maxSessionDuration`, 10 minutes by default; with `continuous: true`, the next one starts at the visitor's next click, tap or key press. `KeployCapture.stop()` ends the capture for good. On a site whose links load pages, such as the [plain HTML shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-html-shop), every page load starts a session of its own. [Sessions and sampling](./sessions-and-sampling.md) says when a session starts and ends.
+
+## What counts as a page change {#what-counts-as-a-page-change}
+
+A route change without a page load is recorded the way rrweb records a page load: as a Meta event with the new URL. These count:
+
+- a `history.pushState`, or a `history.replaceState` that changes the path, as a router makes them;
+- the visitor going back or forward, or the page's own `history.back()`, `forward()` or `go()`;
+- a hash router's change of `#/route`.
+
+These are not page changes and record no navigation of their own:
+
+- **A change of the query alone**, pushed, replaced or traversed, such as a router syncing a filter or a search box that pushes `?q=` on every keystroke. The URL recorded is always the one the page is on, so a snapshot taken later, when a hidden tab comes back or at `resume()`, carries the query as it is then.
+- **An in-page anchor**, such as `#reviews`.
+
+## What a route change records {#what-a-route-change-records}
+
+Each route change's Meta event says what moved the page, as `cause`:
+
+| `cause` | What moved the page |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `push` | A navigation that added a history entry: `history.pushState`, as a router calls it to follow a link, or the Navigation API reporting a push |
+| `replace` | A `history.replaceState` that changes the path, such as a redirect |
+| `traverse` | A move through the session history: the browser's Back or Forward, or the page's own `history.back()` or `go()` |
+| `hash` | A fragment navigation the History API did not make: a link to `#/route`, or `location.hash = ...` |
+
+The Meta event rrweb writes with every full snapshot (a page load, a tab that comes back, `resume()`) has no `cause`. The React and Next.js sample shops' tests check that every route change their links make is recorded with `cause: "push"`.
+
+Two more fields can say who moved the page:
+
+- **`userInitiated`**, where the browser has the Navigation API, as its `navigate` event reported it: `true` when the visitor started the move, `false` when the page's script did. Browsers differ, and the SDK records what each says: a `pushState` or `history.back()` called from a click handler reads `true` in WebKit and `false` in Chromium and Firefox. So this field alone does not tell an in-app Back button from the browser's own Back in every browser.
+- **`initiator: "script"`**, on a traversal the page's own script asked for: `history.back()`, `forward()` or `go()`, or the Navigation API's `navigation.back()`, `forward()` or `traverseTo()`, as an in-app Back button calls them. This one tells an in-app Back from the browser's Back in every browser that has the Navigation API, WebKit included.
+
+## Hash routers {#hash-routers}
+
+A hash router's route change is recorded as a page change. Where the browser has the Navigation API, a fragment navigation the History API did not make is recorded with `cause: "hash"`. Where it has none, the browser fires `popstate` before `hashchange` for that navigation, and the change reads as `traverse`.
+
+An anchor link inside a page, such as `#reviews`, is not a page change.
+
+## How the SDK sees route changes {#how-the-sdk-sees-route-changes}
+
+To record route changes, the SDK wraps `history.pushState`, `replaceState`, `back`, `forward` and `go`, and, where the browser has the Navigation API, `navigation.back`, `forward` and `traverseTo`, once per page. It records a change only once the URL has changed.
+
+- **Where the browser has the Navigation API**, as every shipping Chromium does, its `currententrychange` event decides. It comes before `popstate`, so the browser's Back is a `traverse` even when a router redirects from its own `popstate` listener; the redirect is then a `replace` of its own. It also reports a navigation that calls no `pushState`, such as one an app intercepts with `navigation.navigate()`.
+- **Without it**, the History API calls and the `popstate` and `hashchange` events decide.
+- **A router that wraps any of these methods after the SDK** keeps its own wrapper when the capture stops.
+
+## Routers that keep their own pushState {#routers-that-keep-their-own-pushstate}
+
+A router that calls a `pushState` or `replaceState` it kept from before `init()`, as SvelteKit does, does not go through the SDK's wrapper. Where the browser has the Navigation API, it still reports the move, and the route change is recorded. Where it has none, the SDK finds the move only when the next event is recorded, and records it just before that event: as a `traverse` when that event comes during a `popstate`, otherwise as a `push`, a `replace` included. A `history.back()` such a router kept from before `init()` carries no `initiator`.
+
+## When the SDK cannot wrap history {#when-the-sdk-cannot-wrap-history}
+
+The SDK wraps all of these methods or none. If code that ran before `init()` made one of them impossible to replace and put back, such as an own property that is neither writable nor configurable, or a frozen `history` or `navigation`, the SDK wraps none and writes one [`KUI_E_NAVIGATION_UNWRAPPED`](./errors.md#kui-e-navigation-unwrapped) warning to the console, naming the method. The capture goes on. Route changes are still recorded, from the page's navigation events, with less detail: no traversal carries `initiator`, and, in a browser without the Navigation API, a `pushState` or `replaceState` is found only at the next recorded event. To fix it, remove the code that locks the method, then reload the page.
+
+## One flow per route; journeys chain them {#one-flow-per-route-journeys-chain-them}
+
+Keploy never lets a flow span a navigation, so each route a visitor opens is its own flow, holding the steps taken there. One visit to Products, Cart and Checkout makes a flow for each of the three pages. The dashboard's **Flows** tab says so above the table:
+
+
+
+The **Journeys** tab chains a session's flows back together, in order, into the path the visit took, and shows each journey's share of sessions. On a site whose links load pages, each page load is a session of its own, so its journeys never span a page load.
+
+## Before 3.1.0 {#before-310}
+
+`@keploy/capture-sdk` 3.0.1 recorded no navigation at `history.pushState`, so a visit that changed route by script was a single flow, on the page where it landed. If a test or a dashboard of yours expects one flow per single-page-app visit, look at the flow for each route instead. The [3.1.0 release notes](./capture-sdk-3-1-0-release-notes.md#15-the-sdk-wraps-the-history-api) list this change.
+
+## Related
+
+- [Install the SDK](./install-sdk.md)
+- [Sessions and sampling](./sessions-and-sampling.md)
+- [From first visit to journeys](./walkthrough-dashboard.md)
+- [`KUI_E_NAVIGATION_UNWRAPPED`](./errors.md#kui-e-navigation-unwrapped)
+- [@keploy/capture-sdk 3.1.0 release notes](./capture-sdk-3-1-0-release-notes.md)
diff --git a/versioned_docs/version-4.0.0/ui-capture/walkthrough-dashboard.md b/versioned_docs/version-4.0.0/ui-capture/walkthrough-dashboard.md
index 86493c0c4..bdfca006e 100644
--- a/versioned_docs/version-4.0.0/ui-capture/walkthrough-dashboard.md
+++ b/versioned_docs/version-4.0.0/ui-capture/walkthrough-dashboard.md
@@ -360,7 +360,7 @@ curl -X DELETE https://api.keploy.io/client/v1/apps/ \
## What's next {#whats-next}
-- [Install the SDK in your own app](../running-keploy/ui-capture.md#install-the-sdk), as early in its startup as you can.
+- [Install the SDK in your own app](./install-sdk.md), as early in its startup as you can.
- [Set up UI capture from an AI agent](./quickstart-agent.md) through the Keploy MCP server.
- [UI Capture errors and warnings](./errors.md): what each `KUI_E_` code means and how to fix it.
diff --git a/versioned_sidebars/version-4.0.0-sidebars.json b/versioned_sidebars/version-4.0.0-sidebars.json
index 8b779635e..00d337b3d 100644
--- a/versioned_sidebars/version-4.0.0-sidebars.json
+++ b/versioned_sidebars/version-4.0.0-sidebars.json
@@ -296,7 +296,8 @@
"collapsed": false,
"items": [
"ui-capture/quickstart-dashboard",
- "ui-capture/quickstart-agent"
+ "ui-capture/quickstart-agent",
+ "ui-capture/install-sdk"
]
},
{
@@ -318,6 +319,9 @@
"ui-capture/privacy",
"ui-capture/sessions-and-sampling",
"ui-capture/network-and-bodies",
+ "ui-capture/spa-navigation",
+ "ui-capture/bundlers",
+ "ui-capture/csp-and-workers",
"ui-capture/ingest-keys",
"ui-capture/agents"
]