@loxel.dev/pharos-browser 0.6.0 → 0.8.0

package/README.md

@@ -127,8 +127,10 @@ targeting rules — send nothing if no rule reads it.
 
 ```typescript
 // Synchronous, no network call — the value was computed server-side and is
-// already here. Your default is returned until the bootstrap lands, and for
-// any key Pharos does not know.
+// already here. Your default is returned until the bootstrap lands, for any
+// key Pharos does not know, and for a value whose type disagrees with your
+// default — a flag sent as the string "false" is not a boolean, and reading
+// it through a boolean gate would otherwise turn the gate ON.
 if (client.flag("new-nav", false)) {
   renderNewNav();
 }
@@ -154,6 +156,13 @@ await client.identify({
 });
 ```
 
+The new user's flags arrive with it, so `identify()` fires `change` the same
+way a server push does — a component that mounted while the user was
+anonymous re-renders against the identified bucket without the app arranging
+anything. If the re-bootstrap fails it still rejects (catch it), and the
+client schedules a reconnect rather than leaving live updates dead until a
+page reload.
+
 ### Shut down
 
 ```typescript
@@ -318,6 +327,124 @@ you can verify what a recorder would send before turning one on.
 
 ## Version history
 
+- `0.8.0` — **`identify()` tells you the flags changed, and a failed one no
+  longer kills live updates** (#788).
+
+  `identify()` swaps the whole flags map and emitted nothing, so a component
+  that rendered against the anonymous bootstrap kept that value for the life
+  of its mount while the server evaluated the real user's bucket on every
+  request. It now emits `change` with the new payload. If its bootstrap
+  rejects it still rejects — an app awaiting it on login has to see that —
+  but it now also schedules a reconnect, where before the stream was left
+  dead with nothing pending and nothing reported. Reconnects back off
+  exponentially (1 s doubling to a 30 s ceiling, reset by a delivered `flags`
+  push) instead of re-bootstrapping every second for the length of an outage.
+
+  `flag(key, default)` now **returns your default when the stored value's
+  type disagrees with it**. It was a cast (`as T`), so a flag delivered as the
+  string `"false"` read as ON through a boolean gate. `null`/`undefined`
+  defaults opt out of the check, since `typeof` describes the absence of a
+  value for both.
+
+  **The replay sensitive-field word list is no longer English-only** (#823).
+  It now carries the common Spanish, French, German, Portuguese, Japanese and
+  Chinese spellings of the same fields, and normalization folds accents
+  instead of deleting them (`contraseña` → `contrasena`, `Straße` →
+  `strasse`) — without which every accented entry would have missed by a
+  character. A localised app previously got essentially nothing from this
+  layer. Annotating `autocomplete` is still the recommended integration step:
+  it is language-independent and is checked first.
+
+  **Why MINOR:** `change` now fires on a path where it did not, a
+  type-mismatched flag stops being returned, and a localised app's fields are
+  masked where they were recorded — so a pinned `collectRecordedStrings`
+  snapshot will differ. Every move is in the safe direction, but a consumer
+  sees different behaviour either way.
+
+- `0.7.0` — **a marker on a shadow host now protects its shadow root** (#821),
+  and the verification helper sees what the recorder sees (#822).
+
+  `hasMarkerAncestor` walked `parentElement`, which is `null` at a shadow
+  boundary, so `pharos-mask`/`pharos-exclude` on a web component's host
+  protected nothing inside it — while rrweb recorded that content regardless.
+  Established empirically before the fix: rrweb captures shadow-root text
+  unconditionally (no recorder option gates it), and `maskTextHook` *is*
+  invoked for those nodes, so the decision function was the sole failure
+  point. The walk now re-roots through `getRootNode()`/`.host`, bounded
+  against a malformed tree.
+
+  `collectRecordedStrings` did not traverse shadow DOM either. That was not a
+  compensating margin — **the auditor's blind spot lined up exactly with the
+  recorder's leak surface**, so an app could run the helper, get a clean
+  report, and be shipping shadow-root content. It now traverses, and
+  `pathOf()` renders a boundary crossing as `>>>` rather than truncating the
+  path to `''` (which was indistinguishable from a root-level row).
+
+  **Why MINOR, not PATCH:** two consumer-visible outputs change. Content
+  inside a marked shadow host is now masked where it previously shipped in
+  the clear, and `collectRecordedStrings` reports strings it previously
+  omitted — so a pinned audit snapshot will differ. Both changes are in the
+  safe direction, but a consumer sees different output either way.
+
+  `STRUCTURAL_ATTRS` is unchanged in membership and is now derived from a
+  justification map: each entry declares a `kind` — `closed-enumeration`
+  (which must name its finite vocabulary) or `cost-tradeoff` (which must
+  carry `meetsImpossibilityBar: false`). `class` is recorded honestly as the
+  second kind. The gate cannot verify a claim's truth; that stays human
+  review.
+
+  **The first round of that fix only reached the FULL SNAPSHOT.** rrweb
+  decides whether to consult `maskTextFn` in `needMaskingText`, which returns
+  "nothing to mask" for any node that is not an element and has no parent
+  *element* — and a text node whose parent is a `ShadowRoot` is exactly that.
+  So on the **incremental** streams (`characterData`, `childList` adds) the
+  decision function was never called at all and a **marked** host still
+  shipped `shadowRoot.textContent = user.name` in the clear once recording had
+  started. An element-wrapped `<p>` inside the same shadow root did not
+  reproduce it (rrweb takes its element branch there), which is how it
+  shipped. The recorder now post-processes both streams through the same
+  policy, and applies it over rrweb's answer in the snapshot too — in the
+  masking direction only, never unmasking.
+
+  **`pharos-exclude` across a shadow boundary shipped attributes.** rrweb's
+  `isBlocked` uses `closest()`, which does not cross a boundary, so an add
+  into an excluded host's shadow root was not dropped — and the scrub pass
+  judges a serialized node through a detached surrogate that by construction
+  has no host and no ancestry. Measured: `<p title="SECRET">TEXT</p>` appended
+  into an excluded host's shadow root shipped its `title` verbatim while its
+  text was masked. Such adds are now dropped, judged against the **live**
+  parent the mutation names by id.
+
+  **Snapshot noise to expect on your first re-run:** shadow roots almost
+  always contain a `<style>`, and `collectRecordedStrings` now reaches it and
+  reports its CSS text as an ordinary text row. That is not a leak — author
+  CSS is not user content — but a pinned audit snapshot will grow by more than
+  the app's own strings.
+
+  **Still not covered:**
+  - **Closed shadow roots**, which rrweb cannot reach either (`n.shadowRoot`
+    is `null`), so neither the recorder nor the helper sees them.
+  - **The full snapshot's own answer for a bare shadow text node is rrweb's,
+    not the policy's**, and it flips on the host's shape:
+    `needMaskingText` returns `false` for an element with no child nodes, so
+    whether a shadow subtree inherits masking depends on whether the host
+    happens to have light-DOM children. The policy is now applied over the
+    top, but only ever to mask MORE — so an **unmarked** host's bare shadow
+    text can be masked in the snapshot while `collectRecordedStrings` reports
+    it. The report is the truthful one: the recorder ships that string
+    verbatim on the incremental stream.
+  - **An excluded host's shadow subtree can still leave structural traces.**
+    Content is dropped, but rrweb's mirror holds nodes this SDK removed from
+    the `adds` stream, so a later `removes` entry can carry their ids. Ids and
+    tree shape, never text or attributes.
+  - Light-DOM content projected through a native `<slot>` is **no longer**
+    on this list: it was measured and is covered. A slotted node is an
+    ordinary light-DOM child of the host — rrweb serializes it under the host
+    and the helper reaches it via `el.children` — so the two agree with no
+    slot-specific handling, and a marker on the host governs it through
+    ordinary light-DOM ancestry. There is a test for it so it does not have to
+    be re-derived.
+
 - `0.6.0` — **first npm release, as `@loxel.dev/pharos-browser`.** Ships built
   output with an `exports` map, so it resolves as an ordinary package.
 

package/TECHNICAL-DETAILS.md

@@ -185,14 +185,23 @@ documented in full in
 - `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).
+  endpoint never sent), and for a stored value whose `typeof` disagrees with
+  `defaultValue`'s — the string `"false"` is not a boolean and must not read
+  as one. A `null`/`undefined` default opts out of that check, because
+  `typeof` describes the absence of a value for both and checking against it
+  would return the default unconditionally.
 - `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.
+  (login, plan change), not per-render. It **fires `"change"`** with the new
+  `{version, flags}` once the stream is back up: it replaced the flags map,
+  and a consumer that only watched `"change"` would otherwise render the
+  previous context's values for the life of its mount. A rejected bootstrap
+  **schedules a reconnect** as well as rejecting, so a failure here costs the
+  call, not the session's live updates.
 - `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
@@ -295,10 +304,19 @@ 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.
+re-bootstraps to mint a fresh token and reconnect. The same schedule covers a
+rejected `identify()`, which is otherwise the one way to end up with no
+stream and no `EventSource` left to report an error.
+
+Retries **back off exponentially**: 1 s, doubling to a 30 s ceiling. It is a
+delay cap rather than an attempt cap — giving up entirely would leave a tab
+permanently stale after an outage it survived — and the ramp is reset by a
+**delivered `flags` push**, not by a successful bootstrap, so a stream that
+opens and dies before sending anything keeps backing off instead of flapping
+at the floor delay. Against a Pharos that is present-but-down this is the
+difference between one request per second per open tab and two per minute.
+There is still no queue and no jitter; `flag()` keeps serving the last-known
+values throughout, and the next successful reconnect resyncs from scratch.
 
 Only payloads with `version >= current` are applied; stale (older-version)
 pushes are ignored. An equal-version push (e.g. the replay a fresh stream

package/dist/{index-bc4bw3ba.js → index-temc0wzg.js}

@@ -1,3 +1,11 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // src/privacy/mask.ts
 var MASK_TOKEN = "••••";
 function maskText(_text) {
@@ -7,12 +15,23 @@ function maskText(_text) {
 // src/privacy/markers.ts
 var EXCLUDE_CLASS = "pharos-exclude";
 var MASK_CLASS = "pharos-mask";
+var MAX_HOPS = 1000;
 function hasMarkerAncestor(el, cls) {
   let node = el;
+  let hops = 0;
   while (node) {
     if (node.classList?.contains(cls))
       return true;
-    node = node.parentElement;
+    const parentEl = node.parentElement;
+    if (parentEl) {
+      node = parentEl;
+    } else {
+      const root = node.getRootNode();
+      node = typeof ShadowRoot !== "undefined" && root instanceof ShadowRoot ? root.host : null;
+    }
+    hops += 1;
+    if (hops > MAX_HOPS)
+      return true;
   }
   return false;
 }
@@ -89,11 +108,101 @@ var SENSITIVE_WORDS = [
   "cvc",
   "iban",
   "passport",
-  "driverslicense"
+  "driverslicense",
+  "contrasena",
+  "contrasenya",
+  "usuario",
+  "secreto",
+  "correo",
+  "movil",
+  "nombre",
+  "apellido",
+  "direccion",
+  "codigopostal",
+  "nacimiento",
+  "cumpleanos",
+  "dni",
+  "seguridadsocial",
+  "tarjeta",
+  "motdepasse",
+  "utilisateur",
+  "identifiant",
+  "courriel",
+  "prenom",
+  "nomdefamille",
+  "adresse",
+  "codepostal",
+  "naissance",
+  "anniversaire",
+  "securitesociale",
+  "carteidentite",
+  "permisconduire",
+  "passwort",
+  "kennwort",
+  "benutzer",
+  "benutzername",
+  "vorname",
+  "nachname",
+  "familienname",
+  "anschrift",
+  "strasse",
+  "postleitzahl",
+  "geburt",
+  "kreditkarte",
+  "kontonummer",
+  "steuernummer",
+  "sozialversicherung",
+  "ausweis",
+  "senha",
+  "palavrapasse",
+  "correio",
+  "sobrenome",
+  "nomecompleto",
+  "endereco",
+  "nascimento",
+  "cartao",
+  "cpf",
+  "cnpj",
+  "パスワード",
+  "メール",
+  "電話",
+  "氏名",
+  "名前",
+  "住所",
+  "生年月日",
+  "誕生日",
+  "郵便番号",
+  "クレジットカード",
+  "マイナンバー",
+  "密码",
+  "密碼",
+  "口令",
+  "邮箱",
+  "郵箱",
+  "邮件",
+  "郵件",
+  "电话",
+  "手机",
+  "手機",
+  "姓名",
+  "地址",
+  "生日",
+  "出生日期",
+  "邮编",
+  "身份证",
+  "身份證",
+  "信用卡",
+  "银行卡"
 ];
 var NAME_ATTRS = ["name", "id", "aria-label"];
-function normalize(value) {
-  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+function foldDiacritics(value) {
+  return value.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").normalize("NFC").replace(/ß/g, "ss");
+}
+function normalForms(value) {
+  const folded = foldDiacritics(value);
+  const ascii = folded.replace(/[^a-z0-9]/g, "");
+  const script = folded.replace(/[^\p{L}\p{N}]/gu, "");
+  return ascii === script ? [ascii] : [ascii, script];
 }
 function isSensitiveField(el) {
   if (el.tagName.toLowerCase() === "input") {
@@ -112,9 +221,10 @@ function isSensitiveField(el) {
     const raw = el.getAttribute(attr);
     if (!raw)
       continue;
-    const normalized = normalize(raw);
-    if (SENSITIVE_WORDS.some((word) => normalized.includes(word)))
-      return true;
+    for (const normalized of normalForms(raw)) {
+      if (SENSITIVE_WORDS.some((word) => normalized.includes(word)))
+        return true;
+    }
   }
   return false;
 }
@@ -841,4 +951,4 @@ async function clearPersisted(indexedDB = defaultFactory()) {
   }
 }
 
-export { MASK_TOKEN, maskText, EXCLUDE_CLASS, MASK_CLASS, shouldExclude, shouldMaskByMarker, isSensitiveField, scrubUrl, scrubAttribute, decide, masksValue, MAX_BUFFER_BYTES, RECORDER_DEFAULTS, resolveConfig, ACTIVATION_EVENT_TAG, attachInteractions, EVENT_TYPE_FULL_SNAPSHOT, EVENT_TYPE_META, beginsWithSnapshot, ReplayBuffer, createDropLedger, MAX_WINDOW_BYTES, encodeWindow, randomSessionId, postEnvelope, envelopeMetaFor, encodeForUpload, createUploadSink, LOCAL_TTL_MS, quotaDroppedWindows, resetQuotaDroppedWindows, isQuotaExceeded, persistWindow, drainPersisted, clearPersisted };
+export { __require, MASK_TOKEN, maskText, EXCLUDE_CLASS, MASK_CLASS, shouldExclude, shouldMaskByMarker, isSensitiveField, scrubUrl, scrubAttribute, decide, masksValue, MAX_BUFFER_BYTES, RECORDER_DEFAULTS, resolveConfig, ACTIVATION_EVENT_TAG, attachInteractions, EVENT_TYPE_FULL_SNAPSHOT, EVENT_TYPE_META, beginsWithSnapshot, ReplayBuffer, createDropLedger, MAX_WINDOW_BYTES, encodeWindow, randomSessionId, postEnvelope, envelopeMetaFor, encodeForUpload, createUploadSink, LOCAL_TTL_MS, quotaDroppedWindows, resetQuotaDroppedWindows, isQuotaExceeded, persistWindow, drainPersisted, clearPersisted };

package/dist/{wire-992wvzs1.js → index-xs32mrd9.js}

@@ -26,8 +26,7 @@ import {
   resolveConfig,
   scrubAttribute,
   scrubUrl
-} from "./index-bc4bw3ba.js";
-import"./index-c3taa3cg.js";
+} from "./index-temc0wzg.js";
 
 // src/replay/recorder.ts
 import { record } from "rrweb";
@@ -146,8 +145,34 @@ function isStyleDiff(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var SERIALIZED_ELEMENT = 2;
+var SERIALIZED_TEXT = 3;
 var SOURCE_MUTATION = 0;
 var SOURCE_INPUT = 5;
+function shadowHostOf(node) {
+  if (node && typeof ShadowRoot !== "undefined" && node instanceof ShadowRoot)
+    return node.host;
+  return null;
+}
+function governingElementOfTextNode(node) {
+  if (!node)
+    return null;
+  return node.parentElement ?? shadowHostOf(node.parentNode);
+}
+function governingElementOfParent(parent) {
+  if (!parent)
+    return null;
+  if (parent.nodeType === 1)
+    return parent;
+  return shadowHostOf(parent);
+}
+function addLandsInExcludedSubtree(parent) {
+  if (!parent)
+    return true;
+  const el = governingElementOfParent(parent);
+  if (el)
+    return decide(el) === "exclude";
+  return false;
+}
 function shouldMaskTextOf(el) {
   if (!el)
     return true;
@@ -271,14 +296,33 @@ function scrubSerializedNode(node, doc) {
       scrubSerializedNode(child, doc);
   }
 }
+function maskUnjudgedShadowText(node, ctx) {
+  const children = node.childNodes;
+  if (!children)
+    return;
+  let host;
+  for (const child of children) {
+    if (child.type === SERIALIZED_TEXT && child.isShadow === true && typeof child.textContent === "string") {
+      if (host === undefined) {
+        const live = typeof node.id === "number" ? ctx.resolveNode(node.id) : null;
+        host = live && live.nodeType === 1 ? live : null;
+      }
+      if (shouldMaskTextOf(host))
+        child.textContent = maskText(child.textContent);
+    }
+    maskUnjudgedShadowText(child, ctx);
+  }
+}
 function scrubEventAttributes(event, ctx) {
   const e = event;
   const data = e.data;
   if (!data)
     return event;
   const node = data.node;
-  if (node && typeof node === "object")
+  if (node && typeof node === "object") {
     scrubSerializedNode(node, ctx.doc);
+    maskUnjudgedShadowText(node, ctx);
+  }
   if (data.source === SOURCE_INPUT && typeof data.text === "string") {
     const live = ctx.resolveNode(data.id);
     const el = live && live.nodeType === 1 ? live : null;
@@ -286,11 +330,34 @@ function scrubEventAttributes(event, ctx) {
   }
   if (data.source !== SOURCE_MUTATION)
     return event;
+  const texts = data.texts;
+  if (Array.isArray(texts)) {
+    for (const entry of texts) {
+      if (typeof entry?.value !== "string")
+        continue;
+      if (shouldMaskTextOf(governingElementOfTextNode(ctx.resolveNode(entry.id)))) {
+        entry.value = maskText(entry.value);
+      }
+    }
+  }
   const adds = data.adds;
   if (Array.isArray(adds)) {
-    for (const add of adds) {
-      if (add?.node)
-        scrubSerializedNode(add.node, ctx.doc);
+    for (let i = adds.length - 1;i >= 0; i--) {
+      const add = adds[i];
+      if (!add?.node)
+        continue;
+      const parent = typeof add.parentId === "number" ? ctx.resolveNode(add.parentId) : null;
+      if (addLandsInExcludedSubtree(parent)) {
+        adds.splice(i, 1);
+        continue;
+      }
+      if (add.node.type === SERIALIZED_TEXT && typeof add.node.textContent === "string") {
+        if (shouldMaskTextOf(governingElementOfParent(parent))) {
+          add.node.textContent = maskText(add.node.textContent);
+        }
+      }
+      scrubSerializedNode(add.node, ctx.doc);
+      maskUnjudgedShadowText(add.node, ctx);
     }
   }
   const attributes = data.attributes;
@@ -918,9 +985,5 @@ function startReplayUpload(opts) {
     }
   };
 }
-export {
-  SESSION_DROPS_KEY,
-  SESSION_STORAGE_KEY,
-  resolveSessionId,
-  startReplayUpload
-};
+
+export { startRecording, SESSION_STORAGE_KEY, resolveSessionId, SESSION_DROPS_KEY, startReplayUpload };

package/dist/index.d.ts

@@ -62,6 +62,7 @@ export declare class PharosBrowserClient {
     private listeners;
     private closed;
     private reconnectTimer;
+    private reconnectAttempts;
     private errorsEnabled;
     private errorTarget;
     private replayHandle;
@@ -80,11 +81,22 @@ export declare class PharosBrowserClient {
      * request): the browser sees this as an error and keeps retrying the same
      * dead token forever. Heuristic: when the source has settled into CLOSED
      * (its terminal state — EventSource does not reach CLOSED on a retryable
-     * drop), re-bootstrap once after a short backoff to mint a fresh token,
-     * then reconnect the stream. This is intentionally simple — no queue, no
-     * exponential ramp — matching the brief's "don't over-engineer" guidance.
+     * drop), re-bootstrap after a backoff to mint a fresh token, then reconnect
+     * the stream. Still no queue and no jitter — the one thing it is not simple
+     * about is the ramp, for the reason on `scheduleReconnect`.
      */
     private maybeReconnect;
+    /**
+     * Arms the single pending reconnect, backing off exponentially from
+     * `RECONNECT_BACKOFF_MS` to `MAX_RECONNECT_BACKOFF_MS`.
+     *
+     * The ramp is not decoration: against a Pharos that is present-but-down
+     * every re-bootstrap fails and re-arms this timer, so a fixed delay is a
+     * request per second per open tab for the length of the outage — load
+     * arriving exactly when the server can least take it. `reconnectAttempts`
+     * is reset by a delivered `flags` push, not here.
+     */
+    private scheduleReconnect;
     private onWindowError;
     private onUnhandledRejection;
     private registerErrorListeners;
@@ -206,14 +218,41 @@ export declare class PharosBrowserClient {
     startReplay(options?: Omit<ReplayUploadOptions, "endpoint" | "appKey">): Promise<ReplayUploadHandle | null>;
     /** Stops routing errors into the recorder. Does not stop the recorder itself. */
     detachReplay(): void;
-    /** Synchronous flag lookup; falls back to defaultValue for unknown keys. */
+    /**
+     * Synchronous flag lookup; falls back to defaultValue for an unknown key,
+     * and for a value of a different type than the default (issue #788).
+     *
+     * `as T` was a cast, not a check, so a flag whose value arrived as the
+     * STRING `"false"` — truthy — read as ON through a boolean gate, while the
+     * dashboard, the payload and the code all looked right. The default carries
+     * the type the caller is prepared to handle, so a value that disagrees with
+     * it is a misconfiguration the default is the safe answer to.
+     *
+     * `null`/`undefined` defaults opt out: `typeof` describes the ABSENCE of a
+     * value for both, so checking against them would turn `flag(key, null)`
+     * into "always null" and stop returning the server's answer at all.
+     */
     flag<T>(key: string, defaultValue: T): T;
     /** Subscribes to "change" (a new flags payload was applied) or "error". Returns an unsubscribe function. */
     on(event: PharosEvent, cb: Listener): () => void;
     private emit;
     /**
      * Re-identifies as a new context: closes the current stream, re-bootstraps
-     * (a full round trip — flags plus a fresh streamToken), and reconnects.
+     * (a full round trip — flags plus a fresh streamToken), reconnects, and
+     * emits `change`.
+     *
+     * THE `change` IS NOT OPTIONAL (issue #788). Replacing the flags map is the
+     * whole point of this call, and the SSE handler is the only other thing that
+     * emits — so without this a component that rendered against the anonymous
+     * bootstrap kept that value for the life of its mount, while the server
+     * evaluated the real user's bucket on every request. That is not a corner
+     * case: it is every authenticated page load that mounts before login.
+     *
+     * REJECTS, AND STILL SCHEDULES A RECONNECT. An app awaiting this on login
+     * has to be able to see it fail, so the error propagates; but it was also
+     * the only way to lose the stream permanently — `eventSource` left `null`
+     * with nothing pending, since `maybeReconnect` runs only from an
+     * `es.onerror` and there is no `es` any more.
      */
     identify(context: PharosContext): Promise<void>;
     /** Closes the stream, stops any pending reconnect, and unregisters auto-capture. Terminal — construct a new client to resume. */

package/dist/index.js

@@ -7,6 +7,7 @@ import {
   MAX_BUFFER_BYTES,
   MAX_WINDOW_BYTES,
   RECORDER_DEFAULTS,
+  __require,
   beginsWithSnapshot,
   clearPersisted,
   createDropLedger,
@@ -27,10 +28,7 @@ import {
   scrubUrl,
   shouldExclude,
   shouldMaskByMarker
-} from "./index-bc4bw3ba.js";
-import {
-  __require
-} from "./index-c3taa3cg.js";
+} from "./index-temc0wzg.js";
 
 // src/stack.ts
 var MAX_FRAMES = 50;
@@ -71,17 +69,74 @@ function parseStack(stack) {
   return frames;
 }
 // src/privacy/collect.ts
-var STRUCTURAL_ATTRS = new Set(["class", "type", "contenteditable"]);
+var STRUCTURAL_ATTR_JUSTIFICATIONS = {
+  type: {
+    kind: "closed-enumeration",
+    claim: "The `type` attribute's value space is a fixed, closed enumeration defined by the HTML Living Standard, scoped per element. No element accepts an application-supplied free-text value there — an out-of-vocabulary `type` is simply not a recognized state.",
+    vocabulary: [
+      "text",
+      "button",
+      "checkbox",
+      "color",
+      "date",
+      "datetime-local",
+      "email",
+      "file",
+      "hidden",
+      "image",
+      "month",
+      "number",
+      "password",
+      "radio",
+      "range",
+      "reset",
+      "search",
+      "submit",
+      "tel",
+      "time",
+      "url",
+      "week",
+      "1",
+      "a",
+      "A",
+      "i",
+      "I"
+    ]
+  },
+  contenteditable: {
+    kind: "closed-enumeration",
+    claim: "The `contenteditable` attribute's value space is a closed enumeration defined by the HTML Living Standard. Any other string is not a recognized keyword state, so this attribute cannot carry free text.",
+    vocabulary: ["true", "false", "plaintext-only", "inherit", ""]
+  },
+  class: {
+    kind: "cost-tradeoff",
+    claim: "class has no closed vocabulary and CAN carry templated content in principle, so it does not clear the content-impossibility bar the enumeration entries clear. It is kept anyway as a stated cost/benefit call: every element has a class attribute, and treating it as content would drown every snapshot in noise.",
+    meetsImpossibilityBar: false
+  }
+};
+var STRUCTURAL_ATTRS = new Set(Object.keys(STRUCTURAL_ATTR_JUSTIFICATIONS));
+var MAX_PATH_HOPS = 1000;
 function pathOf(el, root) {
   const parts = [];
   let node = el;
+  let hops = 0;
   while (node && node !== root) {
     const parent = node.parentElement;
-    if (!parent)
+    if (parent) {
+      const index = Array.prototype.indexOf.call(parent.children, node) + 1;
+      parts.unshift(`${node.tagName.toLowerCase()}:nth-child(${index})`);
+      node = parent;
+    } else {
+      const shadowRoot = node.getRootNode();
+      if (!(typeof ShadowRoot !== "undefined" && shadowRoot instanceof ShadowRoot))
+        break;
+      const index = Array.prototype.indexOf.call(shadowRoot.children, node) + 1;
+      parts.unshift(">>>", `${node.tagName.toLowerCase()}:nth-child(${index})`);
+      node = shadowRoot.host;
+    }
+    hops += 1;
+    if (hops > MAX_PATH_HOPS)
       break;
-    const index = Array.prototype.indexOf.call(parent.children, node) + 1;
-    parts.unshift(`${node.tagName.toLowerCase()}:nth-child(${index})`);
-    node = parent;
   }
   return parts.join(" > ");
 }
@@ -92,8 +147,8 @@ function collectRecordedStrings(root) {
     if (decision === "exclude")
       return;
     const path = pathOf(el, root);
+    const valueIsMasked = masksValue(el);
     if (decision === "record" || decision === "mask") {
-      const valueIsMasked = masksValue(el);
       for (const attr of Array.from(el.attributes)) {
         const name = attr.name.toLowerCase();
         if (STRUCTURAL_ATTRS.has(name))
@@ -119,6 +174,22 @@ function collectRecordedStrings(root) {
     }
     for (const child of Array.from(el.children))
       visit(child);
+    if (el.shadowRoot) {
+      const shadowPath = path ? `${path} > >>>` : ">>>";
+      for (const child of Array.from(el.shadowRoot.childNodes)) {
+        if (child.nodeType === 1) {
+          visit(child);
+          continue;
+        }
+        if (child.nodeType !== 3)
+          continue;
+        if (decision !== "record" || valueIsMasked)
+          continue;
+        const text = (child.textContent ?? "").trim();
+        if (text)
+          out.push({ value: text, path: shadowPath, origin: "text" });
+      }
+    }
   };
   visit(root);
   return out;
@@ -203,6 +274,7 @@ function sanitizeAttrs(attrs) {
   return out;
 }
 var RECONNECT_BACKOFF_MS = 1000;
+var MAX_RECONNECT_BACKOFF_MS = 30000;
 function buildBootstrapBody(context) {
   const { contextKey, application, release, sessionId, attributes } = context;
   const pharos = { contextKey };
@@ -230,6 +302,7 @@ class PharosBrowserClient {
   };
   closed = false;
   reconnectTimer = null;
+  reconnectAttempts = 0;
   errorsEnabled;
   errorTarget;
   replayHandle = null;
@@ -290,6 +363,7 @@ class PharosBrowserClient {
         }
         this.flags = payload.flags ?? {};
         this.version = payload.version;
+        this.reconnectAttempts = 0;
         this.emit("change", payload);
       } catch (err) {
         this.emit("error", err);
@@ -302,16 +376,21 @@ class PharosBrowserClient {
     this.eventSource = es;
   }
   maybeReconnect(es) {
-    if (this.closed || this.reconnectTimer)
-      return;
     if (es.readyState !== 2)
       return;
+    this.scheduleReconnect();
+  }
+  scheduleReconnect() {
+    if (this.closed || this.reconnectTimer)
+      return;
+    const delay = Math.min(RECONNECT_BACKOFF_MS * 2 ** this.reconnectAttempts, MAX_RECONNECT_BACKOFF_MS);
+    this.reconnectAttempts += 1;
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null;
       if (this.closed)
         return;
       this.identify(this.context).catch((err) => this.emit("error", err));
-    }, RECONNECT_BACKOFF_MS);
+    }, delay);
   }
   onWindowError = (event) => {
     const e = event;
@@ -400,7 +479,7 @@ class PharosBrowserClient {
   async startReplay(options = {}) {
     if (this.closed)
       return null;
-    const { startReplayUpload } = await import("./wire-992wvzs1.js");
+    const { startReplayUpload } = await import("./wire-90whxzan.js");
     if (this.closed)
       return null;
     const handle = startReplayUpload({
@@ -423,10 +502,13 @@ class PharosBrowserClient {
     this.replayErrorListeners = null;
   }
   flag(key, defaultValue) {
-    if (Object.prototype.hasOwnProperty.call(this.flags, key)) {
-      return this.flags[key];
+    if (!Object.prototype.hasOwnProperty.call(this.flags, key))
+      return defaultValue;
+    const value = this.flags[key];
+    if (defaultValue !== null && defaultValue !== undefined && typeof value !== typeof defaultValue) {
+      return defaultValue;
     }
-    return defaultValue;
+    return value;
   }
   on(event, cb) {
     this.listeners[event].add(cb);
@@ -447,9 +529,15 @@ class PharosBrowserClient {
       this.eventSource.close();
       this.eventSource = null;
     }
-    await this.bootstrap();
+    try {
+      await this.bootstrap();
+    } catch (err) {
+      this.scheduleReconnect();
+      throw err;
+    }
     if (!this.closed) {
       this.connectStream();
+      this.emit("change", { version: this.version, flags: this.flags });
     }
   }
   close() {
@@ -471,34 +559,34 @@ class PharosBrowserClient {
   }
 }
 export {
-  ACTIVATION_EVENT_TAG,
-  EXCLUDE_CLASS,
-  LOCAL_TTL_MS,
-  MASK_CLASS,
-  MASK_TOKEN,
-  MAX_BUFFER_BYTES,
-  MAX_WINDOW_BYTES,
-  PharosBrowserClient,
-  RECORDER_DEFAULTS,
-  beginsWithSnapshot,
-  clearPersisted,
-  collectRecordedStrings,
-  createDropLedger,
-  createUploadSink,
-  decide,
-  drainPersisted,
-  encodeWindow,
-  envelopeMetaFor,
-  isSensitiveField,
-  maskText,
-  masksValue,
-  persistWindow,
-  postEnvelope,
-  quotaDroppedWindows,
-  resetQuotaDroppedWindows,
-  resolveConfig,
-  scrubAttribute,
-  scrubUrl,
+  shouldMaskByMarker,
   shouldExclude,
-  shouldMaskByMarker
+  scrubUrl,
+  scrubAttribute,
+  resolveConfig,
+  resetQuotaDroppedWindows,
+  quotaDroppedWindows,
+  postEnvelope,
+  persistWindow,
+  masksValue,
+  maskText,
+  isSensitiveField,
+  envelopeMetaFor,
+  encodeWindow,
+  drainPersisted,
+  decide,
+  createUploadSink,
+  createDropLedger,
+  collectRecordedStrings,
+  clearPersisted,
+  beginsWithSnapshot,
+  RECORDER_DEFAULTS,
+  PharosBrowserClient,
+  MAX_WINDOW_BYTES,
+  MAX_BUFFER_BYTES,
+  MASK_TOKEN,
+  MASK_CLASS,
+  LOCAL_TTL_MS,
+  EXCLUDE_CLASS,
+  ACTIVATION_EVENT_TAG
 };

package/dist/privacy/collect.d.ts

@@ -4,5 +4,16 @@ export interface RecordedString {
     origin: 'text' | 'value' | 'attribute';
     attribute?: string;
 }
+type StructuralAttrJustification = {
+    readonly kind: 'closed-enumeration';
+    readonly claim: string;
+    readonly vocabulary: readonly string[];
+} | {
+    readonly kind: 'cost-tradeoff';
+    readonly claim: string;
+    readonly meetsImpossibilityBar: false;
+};
+export declare const STRUCTURAL_ATTR_JUSTIFICATIONS: Readonly<Record<string, StructuralAttrJustification>>;
 export declare const STRUCTURAL_ATTRS: Set<string>;
 export declare function collectRecordedStrings(root: Element): RecordedString[];
+export {};

package/dist/replay/index.js

@@ -1,8 +1,15 @@
-import"../index-c3taa3cg.js";
-export {
+import {
   SESSION_DROPS_KEY,
   SESSION_STORAGE_KEY,
   resolveSessionId,
   startRecording,
   startReplayUpload
+} from "../index-xs32mrd9.js";
+import"../index-temc0wzg.js";
+export {
+  startReplayUpload,
+  startRecording,
+  resolveSessionId,
+  SESSION_STORAGE_KEY,
+  SESSION_DROPS_KEY
 };

package/dist/replay/privacy-hooks.d.ts

@@ -43,6 +43,8 @@ export interface SerializedNode {
     tagName?: string;
     attributes?: Record<string, unknown>;
     childNodes?: SerializedNode[];
+    /** rrweb-snapshot's text payload — present on `type === SERIALIZED_TEXT`. */
+    textContent?: string;
     id?: number;
     [key: string]: unknown;
 }

package/dist/wire-90whxzan.js

@@ -0,0 +1,13 @@
+import {
+  SESSION_DROPS_KEY,
+  SESSION_STORAGE_KEY,
+  resolveSessionId,
+  startReplayUpload
+} from "./index-xs32mrd9.js";
+import"./index-temc0wzg.js";
+export {
+  startReplayUpload,
+  resolveSessionId,
+  SESSION_STORAGE_KEY,
+  SESSION_DROPS_KEY
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loxel.dev/pharos-browser",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Browser client for Pharos — server-evaluated feature flags, error capture, and session replay.",
   "license": "MIT",
   "type": "module",
@@ -45,7 +45,8 @@
     "access": "public"
   },
   "scripts": {
-    "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun run typecheck && bun test",
     "build": "bun build src/index.ts src/replay/index.ts --outdir dist --root src --splitting --target browser --format esm --external rrweb && bun run build:types",
     "build:types": "tsc -p tsconfig.build.json",
     "prepublishOnly": "bun run build"

package/dist/index-c3taa3cg.js

@@ -1,9 +0,0 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined")
-    return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
-export { __require };