@loxel.dev/pharos-browser 0.6.0

package/TECHNICAL-DETAILS.md

@@ -0,0 +1,480 @@
+# @loxel.dev/pharos-browser — technical details
+
+How the client behaves underneath the API, and the full export reference.
+You do not need any of this to use the package — `README.md` is the guide.
+This is for reading a replay that looks wrong, auditing what leaves the
+browser, or wiring your own transport.
+
+## How a burst becomes one window, and when a trigger produces none
+
+De-duplication keeps the **first** trigger's `kind` and `name`. A `TypeError`
+followed half a second later by a manual capture ships as one
+`kind: "exception", occurrences: 2` window, and the manual kind is not recorded
+anywhere. That is the de-duplication rule, not an oversight: one upload per
+burst, described by the trigger whose pre-roll explains it.
+
+A trigger does **not** guarantee a window. Two shapes fail closed — a buffer
+with no extractable snapshot, and a window whose events all postdate the error
+(possible when memory pressure has evicted everything older). Neither produces
+a window, a stat or a degradation record, but **since `0.5.0` neither is
+silent**: `startReplayUpload` counts both into the `droppedWindows` it reports
+to Pharos, and `RecorderOptions.onWindowDropped` is the hook if you are wiring
+your own transport. A recorder started with a bare `startRecording({sink})`
+and no `onWindowDropped` still drops them without a trace.
+
+## Why rrweb is pinned exactly
+
+rrweb is pinned to **exactly `2.1.1`, with no caret** — deliberately. A replay
+recorder's *fidelity* and its *privacy behaviour* both change with the version:
+what rrweb serializes, which nodes it routes through `maskTextFn`, and which
+attributes it invents (`rr_dataURL` and friends) are all version-specific, and
+this package's privacy wiring is audited against that exact build. Widening the
+range would let a `bun install` change what a recorder sends. Bump it
+deliberately, re-run the leak test, and treat the result as a reviewable change.
+
+## Buffer ceiling and graceful degradation
+
+**Limits it enforces on itself.** The buffer has a hard **30 MB ceiling that
+wins over the configured pre-roll**: on a heavy page the buffer holds less
+history than requested and records that it did. That ceiling counts
+**serialized bytes** — the size the events would occupy on the wire — and is
+**not** a heap budget: the retained JavaScript objects behind them cost several
+times that, so read `30 MB` as a bound on captured data, never as "the recorder
+uses 30 MB of memory". `PerformanceObserver` long-task entries back off
+checkpoint frequency first and pointer sampling second, recovering gradually.
+Every transition is listed in the window's `degraded` array with its reason, so
+a sparse replay is explained rather than looking like a bug.
+
+## Flushing on unload
+
+**Unload.** A post-roll is a timer, and an unloading page does not run timers.
+The recorder listens for `pagehide` and for `visibilitychange` to `hidden` and
+flushes the in-flight window immediately, marking it `trigger.unloaded: true`.
+An error moments before the user navigates away is the most interesting kind
+there is; without this it would be the one kind that never shipped. Note the
+cost: `hidden` also means a plain tab switch, so `unloaded: true` marks "this
+window was cut short", **not** "the user left" — the session can carry on and
+produce more windows afterwards.
+
+## The wire format, IndexedDB rest, and droppedWindows
+
+**What goes on the wire.** The window is serialized to JSON, gzipped with
+`CompressionStream` (falling back to uncompressed, flagged `compressed: false`,
+on browsers that lack it), and sent as a **JSON envelope with the blob
+base64-encoded** — `{sessionId, trigger, degraded, config, compressed,
+droppedWindows, blob}` — not as `application/octet-stream`. The envelope form
+is required because raw bytes have nowhere to carry any of those other fields.
+**Base64 inflates the payload by about 33%**, and the client's own window limit
+(`MAX_WINDOW_BYTES`) is *derived* from the server's transport cap with that
+inflation accounted for, so a window this client agrees to send is one the
+transport can actually deliver. A window over the limit is **rejected, never
+truncated** — a truncated gzip stream is not a shorter replay, it is an
+unreadable one — and it is counted in `droppedWindows`. **This holds on both
+paths**: the live POST and the unload-time write to IndexedDB apply the same
+comparison to the same bytes.
+
+**Replay data rests in the user's browser, in IndexedDB.** When a trigger is
+flushed by the page-lifecycle path — `pagehide`, or `visibilitychange` to
+`hidden` — the window is not POSTed: `sendBeacon` and `fetch(keepalive)` both
+cap at **64 KiB** by browser design (the Fetch specification returns a network
+error past that), and a replay window is megabytes. So it is written to an
+IndexedDB database named `pharos-replay`.
+
+**Only `pagehide` genuinely *cannot* send.** `hidden` also means a plain tab
+switch (see the flush note above), and that page is fully alive with a working
+`fetch` — so a persisted window is **drained and POSTed as soon as the tab
+becomes `visible` again**, not on the next page load. That turns the tab-switch
+case from "delayed until the user reloads your site" — which for a long-lived
+SPA can mean *never*, and the window then expires unsent — into "delayed by
+seconds". A `pagehide` window really is delayed until the next
+`startReplayUpload()`, and nothing can do better: the page is gone.
+
+Three properties of that rest, each enforced and tested:
+
+- it is **consent-bound** — `startReplayUpload()`'s `stop()` deletes every
+  persisted window, not just the in-memory buffer, so withdrawing consent
+  leaves nothing of the user's anywhere. (A recorder started with a bare
+  `startRecording({sink})` clears only its buffer; `stop()` there knows
+  nothing about IndexedDB. Call `clearPersisted()` yourself if you wire your
+  own transport.)
+- it is **never read or uploaded until the application opts in again** — the
+  drain runs on `startReplayUpload()`, which is the consent event; and
+- **the 24-hour local expiry (`LOCAL_TTL_MS`) is enforced on the next visit,
+  not by a clock.** A record older than 24 hours is deleted **unsent** by the
+  first `startReplayUpload()` or the first `persistWindow()` after it lapses.
+  **Nothing runs while the page does not**: if the user never returns to your
+  site, the record stays on their device until the browser evicts the origin's
+  storage. There is no browser mechanism that can do better — a page that
+  never executes cannot delete anything — so read this as "it is never
+  *uploaded* after 24 hours, and it is removed the next time your site runs",
+  which is what the code actually provides.
+
+**An oversized window is never persisted either.** The same
+`MAX_WINDOW_BYTES` gate as the live path applies before the write, because a
+window the server is certain to refuse would otherwise sit on the user's disk
+and be retried on every load for 24 hours, failing every time. It is dropped
+and counted instead.
+
+If IndexedDB is unavailable or refuses the write, the window is lost and
+counted; it is never queued in memory across a navigation.
+
+**`droppedWindows` — what the number actually means.** It is a **cumulative
+per-session count** (the server merges it with `max(existing, incoming)`, so a
+delta would under-count). **Cumulative means across page loads**, not within
+one: the running total lives in `sessionStorage` next to the durable session
+id and is seeded from there on every `startReplayUpload()`, so a tab that
+reloads three times during an incident, losing two windows each time, reports
+`6` and not `2`. It is stored **with the session id it belongs to** and is
+discarded if they disagree, so a host that passes a fresh `sessionId` per page
+load gets a per-load count rather than another session's losses. `stop()`
+clears it along with the id — a pre-withdrawal count cannot ride out on a
+post-withdrawal upload.
+
+It counts every window this session lost:
+oversized windows (on either path), failed or refused POSTs, IndexedDB quota
+evictions and other local-storage failures, and the two B1 fail-closed drops
+above. It does **not** count a window that simply *expired* locally after 24
+hours — that is the retention the user was promised working, not data lost to
+a fault. It does **not** count buffer segment evictions
+under memory pressure — those *shorten* a window rather than losing one, and
+they are already reported separately in the window's `degraded` array with
+their own count. **`createUploadSink` used on its own counts only its own
+delivery failures**; `startReplayUpload` is what makes the number complete.
+
+**What the server can and cannot do with it.** Nothing. The bytes are
+compressed by this client and **stored opaque** — Loxel exposes no `inflate`
+binding today, so the Pharos server cannot decompress an upload. (The runtime
+*does* link zlib — `Archive.targz_*` — so an inflate intrinsic is a modest
+addition rather than an impossibility; the constraint is the current binding
+surface, not the platform.) **The decision to store opaque bytes stands
+regardless**, and its consequence is stated plainly because it is what the
+design chose: **there is no server-side validation or audit of uploaded replay
+content.** Only slice B3's console, in the browser, inflates a window.
+
+## Per-application replay configuration
+
+**Per-application replay configuration has no admin surface yet.** The TTL and
+session cap below are per-application columns an operator sets **by direct
+SQL**; there is no admin API or console screen for them, so in practice every
+application currently gets the platform default (14 days, 500 sessions). The
+bootstrap response and the ingest path already read whatever is stored, so
+closing this is a UI/route addition, not a data-model change.
+
+## Server-side storage notes
+
+Two storage facts worth knowing if you are reading the server side (both
+documented in full in
+[the Pharos README](../../README.md#session-replay-privacy-contract) and the
+`loxel-mongo` README):
+
+- `loxel-mongo`'s GridFS **deliberately deviates from the GridFS
+  specification** by writing `expiresAt` onto every chunk, because a TTL index
+  on `fs.files` does **not** cascade to `fs.chunks` — without the deviation,
+  expiry would delete the metadata and strand every chunk forever.
+- **MongoDB's TTL monitor expires only BSON dates.** A field stored as a
+  Number never expires, silently, so every `expiresAt` in this pipeline is a
+  BSON date and nothing may "simplify" one into an epoch number.
+
+## API
+
+- `PharosBrowserClient.init(config): Promise<PharosBrowserClient>` — bootstraps
+  and opens the live stream. `config.context` reserved fields
+  (`contextKey`/`application`/`release`/`sessionId`) are split from
+  `attributes` on the wire automatically; put anything else you want to
+  target on into `attributes`.
+- `flag<T>(key, defaultValue): T` — synchronous map lookup, no network call,
+  no evaluation. Returns `defaultValue` for any key not present in the
+  current flags map (unknown key, or a `server_side`-only flag the bootstrap
+  endpoint never sent).
+- `on(event, cb): () => void` — subscribe to `"change"` (a new flags payload
+  was applied — fires exactly once per accepted server push) or `"error"`
+  (stream/bootstrap failure). Returns an unsubscribe function.
+- `identify(context): Promise<void>` — re-bootstraps as a new context and
+  reopens the stream against the fresh `streamToken`. **This is a full HTTP
+  round trip, not a local re-key** — call it on meaningful identity changes
+  (login, plan change), not per-render.
+- `captureException(err, opts?): void` — reports one exception; see
+  "Error reporting" above. `opts` is `{site?: string, attributes?: Record<string, unknown>}`.
+  Never throws; a failed POST is reported via `on("error")`. A no-op after
+  `close()`.
+- `attachReplay(handle): void` — routes this client's error paths into a
+  running recorder (see "Session replay" above). **Throws if a different
+  recorder is already attached** — rrweb records into one process-wide session,
+  so a second `startRecording()` silently takes the first one over, and this is
+  the one place a client can see both. Call `detachReplay()` first to swap
+  deliberately; re-attaching the same handle is a no-op.
+- `detachReplay(): void` — stops routing errors into the recorder. Does **not**
+  stop the recorder: call `handle.stop()` for that (which also discards the
+  buffer). A no-op after `close()`, like
+  `captureException()` and `identify()`: `attachReplay()` after `close()`
+  registers nothing.
+- `close(): void` — closes the stream, cancels any pending reconnect, and
+  unregisters auto-capture listeners. Terminal; construct a new client to
+  resume. Calling `identify()` after `close()` is a no-op (no fetch, no
+  `"change"`) rather than a half-resume.
+- `init()`/`identify()` **reject (throw) on a failed bootstrap call**
+  (non-2xx HTTP status or a network error) — callers should `try`/`catch`
+  around them. This is distinct from the `on("error")` stream events, which
+  cover the live SSE connection after a successful bootstrap.
+
+### Replay exports
+
+The package root also exports the recorder entry points described under
+"Session replay". Everything below is the whole replay surface — if it is not
+here, it is internal.
+
+Exports marked **`/replay`** come from `@loxel.dev/pharos-browser/replay`;
+everything else is on the package root. That line is where `rrweb` enters a
+bundle — see [Bundle size](#bundle-size).
+
+- **`/replay`** `startRecording(options): RecorderHandle` — starts a recorder. `options` is
+  `{sink, onWindowDropped?, preRollMs?, postRollMs?, maxBytes?, pointerHz?}`
+  plus injectable seams for tests (`now`, `scheduleIdle`,
+  `setTimer`/`clearTimer`, `target`, `lifecycleTarget`, `doc`). The handle is
+  `{config, stop(), trigger(source), flushNow(), stats()}`. For uploading to
+  Pharos, prefer `startReplayUpload` below.
+- `resolveConfig(opts): ResolvedRecorderConfig` — the clamping the recorder
+  applies to its options, exposed so you can see what a configuration will
+  actually become before starting. `handle.config` is the same object for a
+  running recorder.
+- `MAX_BUFFER_BYTES` — the 30 MB serialized-size ceiling. Configuration can
+  lower it; nothing raises it.
+- `RECORDER_DEFAULTS` — `{preRollMs: 30_000, postRollMs: 10_000, pointerHz: 20}`.
+- `ACTIVATION_EVENT_TAG` — `"pharos-activation"`, the tag on the custom rrweb
+  event carrying the activation mode. Match on the constant, not the string.
+- `beginsWithSnapshot(events): boolean` — true when an event array opens with a
+  Meta or FullSnapshot event, i.e. is replayable on its own. A sink can assert
+  it; a window from this recorder always satisfies it.
+- **`/replay`** `startReplayUpload(options): ReplayUploadHandle` — a recorder wired to
+  Pharos (see "Uploading to Pharos" above). `options` is every
+  `startRecording` option except `sink`/`onWindowDropped`, plus
+  `{endpoint, appKey, fetchImpl?, compress?, sessionId?, indexedDB?,
+  sessionStorage?}`. The handle is a `RecorderHandle` plus `sessionId`,
+  `drops()` and `settled()`.
+- `PharosBrowserClient.startReplay(options?): Promise<ReplayUploadHandle | null>`
+  — the same thing, with `endpoint`, `appKey` and `sessionId` taken from the
+  client, and `attachReplay` already called. **Prefer this**: it is the only
+  form in which replay and errors cannot end up under two different session
+  ids, and the only one that keeps `rrweb` out of your bundle until it runs
+  (it loads the recorder through a dynamic `import()`). Resolves to `null`
+  after `close()`; rejects only if the chunk cannot be loaded.
+- `createUploadSink(options): Sink` — the live-POST sink alone, for an
+  application wiring its own recorder. **Counts only its own delivery
+  failures** in `droppedWindows` unless you inject a shared `DropLedger`.
+- `encodeWindow(window)` — JSON + gzip, returning `{body, compressed}`.
+- `postEnvelope(body, meta, target)` / `envelopeMetaFor(...)` — the one
+  implementation of the wire format, exported so a custom transport reuses it
+  rather than re-deriving it.
+- `MAX_WINDOW_BYTES` — the largest decoded window this client will send,
+  derived from the server's transport cap and base64's 4/3 inflation.
+- `persistWindow` / `drainPersisted` / `clearPersisted` / `LOCAL_TTL_MS` —
+  the IndexedDB rest described above. `clearPersisted` is the consent
+  primitive; `startReplayUpload`'s `stop()` calls it for you. Both
+  `persistWindow` and `drainPersisted` delete records older than
+  `LOCAL_TTL_MS` as they go — that is the only thing that enforces the local
+  expiry, so neither running means nothing expires.
+- `quotaDroppedWindows()` / `resetQuotaDroppedWindows()` — the quota-eviction
+  count on `persistWindow`'s *default* ledger, for callers that inject none.
+- `createDropLedger()` — the cumulative `droppedWindows` ledger, if you are
+  assembling the pieces yourself.
+- **`/replay`** `resolveSessionId(explicit, storage)` / `SESSION_STORAGE_KEY` — the durable
+  session-id rule, exported so a host can see or pre-seed it.
+  `SESSION_DROPS_KEY` is where the session's cumulative `droppedWindows` rides
+  alongside it, scoped to that id.
+- Types: `ActivationMode`, `DegradationReason`, `DegradationRecord`,
+  `DropLedger`, `DropReason`, `PostTarget`, `RecorderHandle`,
+  `RecorderOptions`, `RecorderStats`, `ReplayUploadHandle`,
+  `ReplayUploadOptions`, `ReplayWindow`, `ResolvedRecorderConfig`, `Sink`,
+  `TriggerInfo`, `TriggerKind`, `TriggerSource`, `UploadEnvelopeMeta`,
+  `UploadOptions`, `WindowDropReason`.
+
+## Stream resilience
+
+The browser's native `EventSource` already retries transient drops on its
+own. The one case it cannot recover from is an **expired stream session**
+(the server holds a 10-minute token TTL, refreshed only at connect): the
+browser sees repeated errors and keeps retrying the same dead token forever.
+When `EventSource` settles into its terminal `CLOSED` state, this client
+re-bootstraps once (short fixed backoff) to mint a fresh token and reconnect.
+It does not attempt a queue or exponential ramp — if the server is down, the
+next successful `identify()`/reconnect will resync from scratch, and `flag()`
+keeps serving the last-known values in the meantime.
+
+Only payloads with `version >= current` are applied; stale (older-version)
+pushes are ignored. An equal-version push (e.g. the replay a fresh stream
+sends on connect) is still applied and still fires `change`.
+
+## Wiring a recorder yourself
+
+```typescript
+import { PharosBrowserClient } from "@loxel.dev/pharos-browser";
+import { startRecording } from "@loxel.dev/pharos-browser/replay";
+
+const client = await PharosBrowserClient.init({ /* … */ });
+
+const recorder = startRecording({
+  // B1 ships no network code. The sink receives a replayable window; slice B2
+  // replaces this with a real uploader.
+  sink: (window) => console.log("replay window", window.events.length),
+  preRollMs: 30_000,   // default
+  postRollMs: 10_000,  // default
+  pointerHz: 20,       // default
+});
+
+// Route this client's errors into the recorder, so an error flushes a window.
+client.attachReplay(recorder);
+
+// Consent withdrawn: capture stops and the buffer is DISCARDED. Detach first —
+// the client keeps the handle it was given, and `attachReplay` refuses a second
+// recorder while one is attached, stopped or not.
+client.detachReplay();
+recorder.stop();
+```
+
+### Uploading to Pharos
+
+`startReplayUpload` is the entry point that turns the recorder into a
+recorder-with-a-destination. It starts a recorder, routes its windows to
+Pharos, drains anything a previous page load left behind, and makes `stop()` a
+total delete.
+
+```typescript
+import { PharosBrowserClient } from "@loxel.dev/pharos-browser";
+import { startReplayUpload } from "@loxel.dev/pharos-browser/replay";
+
+const client = await PharosBrowserClient.init({ /* … */ });
+
+const recorder = startReplayUpload({
+  endpoint: "https://pharos-ops.app/api/v1/client/replay",
+  appKey: "phc_…",            // the same CLIENT key the rest of the SDK uses
+  sessionId: myAppSessionId,  // optional — see "Sessions" below
+  // every startRecording() option is accepted too
+  preRollMs: 30_000,
+  postRollMs: 10_000,
+});
+
+client.attachReplay(recorder);
+
+// Consent withdrawn.
+client.detachReplay();
+recorder.stop();               // buffer discarded AND IndexedDB cleared
+await recorder.settled();      // optional: wait for that clear to finish
+```
+
+**Sessions.** Windows group server-side by `sessionId`. Pass your own if your
+application already has a session concept — replay then groups the same way
+your errors and flags do. Otherwise a durable id is kept in `sessionStorage`
+under `pharos-replay-session`, so **a reload or a same-tab navigation stays one
+session** rather than minting a new one per page load. `stop()` removes it, so
+recording again after a consent withdrawal is a *new* session, never a
+continuation of the one the user withdrew from.
+
+**`sessionId`: replay and errors are joined by it, or not at all.**
+`PharosContext.sessionId` is what rides the errors envelope and what the
+server stores on an error row. `startReplayUpload` mints **its own** unless you
+pass one. **If they differ, an error and the replay window captured around that
+same error cannot be joined** — which is precisely the correlation the replay
+console exists to perform. Two ways not to get this wrong:
+
+- **`await client.startReplay(options)`** — starts a recorder wired to that
+  client's base URL, client key and `PharosContext.sessionId`, and attaches it.
+  One id by construction; nothing to remember. It is **async**: it loads the
+  recorder on demand, so you never import `/replay` yourself and never pay for
+  rrweb unless you call it.
+- `client.attachReplay(handle)` **warns** (`console.warn`, once) when the
+  handle's `sessionId` disagrees with the context's. It does not repair it:
+  windows already uploaded under the other id cannot be re-keyed from here,
+  and only you can say which id is authoritative.
+
+With no `PharosContext.sessionId` at all, replay falls back to its durable
+per-tab id and errors carry none — consistent, and nothing to join on either
+side.
+
+## Full version history
+
+- `0.6.0` — **published to npm as `@loxel.dev/pharos-browser`, and rrweb is no
+  longer bundled into every consumer.** Two changes, one release.
+
+  **Packaging.** Adds an `exports` map, `main`/`module`/`types`, `files`,
+  repository metadata and `publishConfig.access: public`, and a real build
+  (`bun build` emits `dist/`, with `rrweb` left external; `tsc -p
+  tsconfig.build.json` emits declarations beside it). Before this the package
+  pointed `module`/`types` straight at TypeScript source with no `exports`
+  map, so a bare specifier could not be resolved from outside the monorepo at
+  all — the reason `apps/alvita/frontend/vite.config.ts` carries an alias to
+  the source file. Driven by the first out-of-repo consumer, `qute-code`,
+  whose Docker build context cannot reach that directory. (The package was
+  `@pharos/browser` while it was monorepo-only.)
+
+  **BREAKING — the recorder moved off the root entry.** `startRecording`,
+  `startReplayUpload`, `resolveSessionId`, `SESSION_STORAGE_KEY` and
+  `SESSION_DROPS_KEY` are now imported from `@loxel.dev/pharos-browser/replay`,
+  and **`client.startReplay()` returns a promise** — it dynamic-imports the
+  recorder. Everything else, including the whole privacy surface and the
+  rrweb-free upload pieces, is unchanged on the root.
+
+  Why: `rrweb` is ~63 kB gzipped and was reachable from the root entry, so it
+  landed in every consumer's bundle whether or not anything recorded —
+  measured at **+204 kB raw / +63 kB gzip** on an application with replay
+  switched off. A dynamic import rather than a static one keeps the chunk in
+  the deployment, so enabling replay stays a configuration change rather than
+  a redeploy; it simply stops being downloaded by applications that never use
+  it. A test now asserts the root does **not** re-export the recorder, because
+  adding that back is a one-line "convenience" that silently undoes all of it.
+
+  The README's "zero runtime dependencies" claim was also stale and is
+  corrected: `rrweb` has been a dependency since the recorder shipped.
+- `0.5.2` — **stops shipping most checkpoint segments twice** (#793 follow-up).
+  A segment shipped by the unload path while still OPEN — which a
+  `visibilitychange` to hidden does on an ordinary tab switch the page
+  survives — then closed normally and was shipped AGAIN, in full, under the
+  same `trigger.at`: measured on real data, nearly every segment reached the
+  server twice, one `unloaded: true` and one `unloaded: false`, roughly
+  doubling ingest and storage for always-on recording. `onSegmentClosed` now
+  suppresses the close when the segment has not grown, and ships it when it
+  has (the closed segment is a superset, and the server supersedes the partial
+  copy). No API change; no export added or removed. The server half —
+  idempotence on `(applicationId, sessionId, checkpoint, trigger.at)` — is in
+  `infrastructure/persistence/replay_store.lox`, and is the half that is
+  load-bearing: a window persisted to IndexedDB and drained on a later page
+  load can arrive after a fresher copy, which no client can suppress.
+  (Always-on recording itself shipped in #873 without a version entry; this
+  is the first bump since.)
+- `0.5.1` — replay-upload correctness fixes (slice B2 review, #793).
+  `droppedWindows` is now cumulative **across page loads**, carried in
+  `sessionStorage` beside the durable session id and scoped to it — the
+  per-page-load count it used to send was silently reduced to the worst single
+  load by the server's `max()` merge. A window persisted by a **tab switch**
+  is drained and POSTed when the tab becomes visible again instead of waiting
+  for a full page load. Adds `PharosBrowserClient.startReplay()` and a
+  `console.warn` from `attachReplay` when replay and errors would be reported
+  under different session ids. No existing behaviour is removed; every
+  `0.5.0` export is unchanged.
+- `0.5.0` — session-replay upload (slice B2, #793): `startReplayUpload()` —
+  gzip + a base64 JSON envelope to `POST /api/v1/client/replay`, IndexedDB
+  rest for windows triggered during unload (drained on the next start, 24 h
+  local TTL) and a `stop()` that clears it, a durable per-tab `sessionId`, and
+  one cumulative `droppedWindows` covering delivery failures, quota evictions
+  and B1's two fail-closed window drops, plus local-storage failures. Adds
+  `createUploadSink`,
+  `encodeWindow`, `postEnvelope`, `envelopeMetaFor`, `MAX_WINDOW_BYTES`,
+  `persistWindow`/`drainPersisted`/`clearPersisted`/`LOCAL_TTL_MS`,
+  `createDropLedger`, `resolveSessionId`, and `RecorderOptions.onWindowDropped`
+  (additive; without it B1's drops stay silent as before). No existing
+  behaviour changes.
+- `0.4.0` — session-replay recorder (slice B1, #793): `startRecording()` with
+  a pluggable sink, rrweb 2.1.1 driven entirely from the privacy policy, a
+  checkpoint-segmented ring buffer with a 30 MB ceiling, activation-mode
+  capture with no key identity, error-driven windows with de-duplication, an
+  unload flush on `pagehide`/`visibilitychange`, and self-degradation under
+  long tasks. Adds `attachReplay()`/`detachReplay()` to `PharosBrowserClient`.
+  No network code — upload lands in slice B2.
+- `0.3.0` — session-replay privacy contract (#793): `pharos-exclude`/
+  `pharos-mask` markers, field-sensitivity detection, and attribute/URL/
+  `style` scrubbing, plus `collectRecordedStrings` for verifying what a
+  recorder would send. `collectRecordedStrings`, `masksValue`, and
+  `scrubAttribute` change observable behavior.
+- `0.2.0` — error reporting: `captureException`, auto-capture of `window`
+  `"error"`/`"unhandledrejection"` events (default on, `init({errors: false})`
+  to opt out), and `parseStack` (V8 + Firefox stack-trace parsing).
+- `0.1.0` — initial release: bootstrap + SSE stream, `flag`/`on`/`identify`/`close`.