@loxel.dev/pharos-browser 0.7.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,40 @@ 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).
 

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-yabengpp.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) {
@@ -100,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") {
@@ -123,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;
 }
@@ -852,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-p2kvy6dd.js → index-xs32mrd9.js}

@@ -26,8 +26,7 @@ import {
   resolveConfig,
   scrubAttribute,
   scrubUrl
-} from "./index-yabengpp.js";
-import"./index-c3taa3cg.js";
+} from "./index-temc0wzg.js";
 
 // src/replay/recorder.ts
 import { record } from "rrweb";
@@ -986,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-yabengpp.js";
-import {
-  __require
-} from "./index-c3taa3cg.js";
+} from "./index-temc0wzg.js";
 
 // src/stack.ts
 var MAX_FRAMES = 50;
@@ -276,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 };
@@ -303,6 +302,7 @@ class PharosBrowserClient {
   };
   closed = false;
   reconnectTimer = null;
+  reconnectAttempts = 0;
   errorsEnabled;
   errorTarget;
   replayHandle = null;
@@ -363,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);
@@ -375,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;
@@ -473,7 +479,7 @@ class PharosBrowserClient {
   async startReplay(options = {}) {
     if (this.closed)
       return null;
-    const { startReplayUpload } = await import("./wire-p2kvy6dd.js");
+    const { startReplayUpload } = await import("./wire-90whxzan.js");
     if (this.closed)
       return null;
     const handle = startReplayUpload({
@@ -496,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);
@@ -520,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() {
@@ -544,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/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/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.7.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 };