@kubesense/kubesense-browser-core 1.7.0 → 2.0.0-beta.0

package/src/index.ts

@@ -1,16 +1,11 @@
-export type { Configuration, InitConfiguration, EndpointBuilder, ProxyFn } from './domain/configuration'
+export type { Configuration, InitConfiguration } from './domain/configuration'
 export type { RemoteSdkConfig, RemoteSdkConfigFeatures } from './domain/configuration'
 export {
-  validateAndBuildConfiguration,
+  BROWSER_CORE_SCHEMA,
   DefaultPrivacyLevel,
   TraceContextInjection,
   serializeConfiguration,
-  isSampleRate,
-  buildEndpointHost,
-  INTAKE_URL_PARAMETERS,
-  INTAKE_SITE_PROD,
-  INTAKE_SITE_STAGING,
-  isIntakeUrl,
+  isAllowedTrackingOrigins,
   SDK_CONFIG_CACHE_KEY,
   SDK_CONFIG_PATH,
   buildSdkConfigEndpoint,
@@ -19,18 +14,18 @@ export {
   parseSdkConfig,
   readBoolean,
   readEnum,
+  readNumberInRange,
   readSampleRate,
   readString,
+  readStringList,
   refreshSdkConfig,
   setCachedSdkConfig,
 } from './domain/configuration'
-export * from './domain/intakeSites'
 export type { TrackingConsentState } from './domain/trackingConsent'
 export { TrackingConsent, createTrackingConsentState } from './domain/trackingConsent'
 export {
   isExperimentalFeatureEnabled,
   addExperimentalFeatures,
-  resetExperimentalFeatures,
   getExperimentalFeatures,
   initFeatureFlags,
   ExperimentalFeature,
@@ -58,24 +53,37 @@ export {
   startTelemetry,
   addTelemetryDebug,
   addTelemetryError,
-  resetTelemetry,
   TelemetryService,
   TelemetryMetrics,
   addTelemetryConfiguration,
   addTelemetryUsage,
   addTelemetryMetrics,
 } from './domain/telemetry'
-export { monitored, monitor, callMonitored, setDebugMode, monitorError } from './tools/monitor'
 export type { Subscription } from './tools/observable'
 export { Observable, BufferedObservable } from './tools/observable'
-export type { SessionManager } from './domain/session/sessionManager'
-export { startSessionManager, stopSessionManager } from './domain/session/sessionManager'
+export type { SessionManager, SessionContext } from './domain/session/sessionManager'
+export {
+  startSessionManager,
+  startSessionManagerStub,
+  stopSessionManager,
+  getSessionEndClocks,
+} from './domain/session/sessionManager'
 export {
   SESSION_TIME_OUT_DELAY, // Exposed for tests
+  SESSION_EXPIRATION_DELAY,
   SESSION_NOT_TRACKED,
   SessionPersistence,
 } from './domain/session/sessionConstants'
-export type { BandwidthStats, HttpRequest, HttpRequestEvent, Payload, FlushEvent, FlushReason } from './transport'
+export type {
+  Batch,
+  BandwidthStats,
+  HttpRequest,
+  HttpRequestEvent,
+  Payload,
+  FlushEvent,
+  FlushReason,
+  UrgentFlushReason,
+} from './transport'
 export {
   createHttpRequest,
   canUseEventBridge,
@@ -89,56 +97,63 @@ export {
 export * from './tools/display'
 export type { Encoder, EncoderResult } from './tools/encoder'
 export { createIdentityEncoder } from './tools/encoder'
-export * from './tools/utils/urlPolyfill'
-export * from './tools/utils/timeUtils'
 export * from './tools/utils/arrayUtils'
+
 export * from './tools/serialisation/sanitize'
-export * from './tools/globalObject'
 export { AbstractLifeCycle } from './tools/abstractLifeCycle'
 export * from './domain/eventRateLimiter/createEventRateLimiter'
 export * from './tools/utils/browserDetection'
 export { sendToExtension } from './tools/sendToExtension'
 export { runOnReadyState, asyncRunOnReadyState } from './browser/runOnReadyState'
 export { getZoneJsOriginalValue } from './tools/getZoneJsOriginalValue'
-export type { InstrumentedMethodCall } from './tools/instrumentMethod'
-export { instrumentMethod, instrumentSetter } from './tools/instrumentMethod'
+export { mockable } from './tools/mockable'
+export type { InstrumentedMethodCall, InstrumentedConstructorCall } from './tools/instrumentMethod'
+export { instrumentMethod, instrumentConstructor, instrumentSetter } from './tools/instrumentMethod'
 export {
   computeRawError,
   getFileFromStackTraceString,
+  getStackTraceUrls,
   isError,
   NO_ERROR_STACK_PRESENT_MESSAGE,
+  DEFAULT_ERROR_TYPE,
 } from './domain/error/error'
 export { NonErrorPrefix } from './domain/error/error.types'
+export { buildDebugIdByUrl, getSourceCodeContext } from './domain/sourceCodeContext'
+export type { DebugIdEntry } from './domain/sourceCodeContext'
 export type { Context, ContextArray, ContextValue } from './tools/serialisation/context'
-export {
-  areCookiesAuthorized,
-  getCookie,
-  getInitCookie,
-  setCookie,
-  deleteCookie,
-  resetInitCookies,
-} from './browser/cookie'
-export type { CookieStore, WeakRef, WeakRefConstructor } from './browser/browser.types'
-export type { XhrCompleteContext, XhrStartContext } from './browser/xhrObservable'
+export { getCookie, getInitCookie, setCookie, deleteCookie, resetInitCookies } from './browser/cookie'
+export { isCookieStoreSupported } from './browser/cookieAccess'
+export type { WeakRef, WeakRefConstructor } from './browser/browser.types'
+export type { XhrCompleteContext, XhrStartContext, XhrContext } from './browser/xhrObservable'
 export { initXhrObservable } from './browser/xhrObservable'
 export type { FetchResolveContext, FetchStartContext, FetchContext } from './browser/fetchObservable'
-export { initFetchObservable, resetFetchObservable, ResponseBodyAction } from './browser/fetchObservable'
+export { initFetchObservable, ResponseBodyAction } from './browser/fetchObservable'
+export type {
+  WebSocketContext,
+  WebSocketConnectingContext,
+  WebSocketOpenContext,
+  WebSocketMessageInContext,
+  WebSocketMessageOutContext,
+  WebSocketClosedContext,
+} from './browser/webSocketObservable'
+export { initWebSocketObservable } from './browser/webSocketObservable'
+export { fetch } from './browser/fetch'
 export type { PageMayExitEvent } from './browser/pageMayExitObservable'
 export { createPageMayExitObservable, PageExitReason, isPageExitReason } from './browser/pageMayExitObservable'
 export * from './browser/addEventListener'
 export { requestIdleCallback } from './tools/requestIdleCallback'
 export * from './tools/taskQueue'
 export * from './tools/timer'
+export * from './tools/thenable'
 export type { ConsoleLog } from './domain/console/consoleObservable'
-export { initConsoleObservable, resetConsoleObservable } from './domain/console/consoleObservable'
-export type { BoundedBuffer } from './tools/boundedBuffer'
-export { createBoundedBuffer } from './tools/boundedBuffer'
+export { initConsoleObservable } from './domain/console/consoleObservable'
 export { catchUserErrors } from './tools/catchUserErrors'
 export type { ContextManager } from './domain/context/contextManager'
 export { createContextManager } from './domain/context/contextManager'
 export { defineContextMethod, bufferContextCalls } from './domain/context/defineContextMethod'
 export { storeContextManager, removeStorageListeners } from './domain/context/storeContextManager'
 export { startAccountContext, buildAccountContextManager } from './domain/contexts/accountContext'
+export { startTabContext } from './domain/contexts/tabContext'
 export { startGlobalContext, buildGlobalContextManager } from './domain/contexts/globalContext'
 export { startUserContext, buildUserContextManager } from './domain/contexts/userContext'
 export type { User } from './domain/contexts/userContext'
@@ -149,36 +164,37 @@ export type { ValueHistory, ValueHistoryEntry } from './tools/valueHistory'
 export { createValueHistory, CLEAR_OLD_VALUES_INTERVAL } from './tools/valueHistory'
 export { readBytesFromStream } from './tools/readBytesFromStream'
 export type { SessionState } from './domain/session/sessionState'
-export { STORAGE_POLL_DELAY } from './domain/session/sessionStore'
 export { SESSION_STORE_KEY } from './domain/session/storeStrategies/sessionStoreStrategy'
+export type { MemorySession } from './domain/session/storeStrategies/sessionInMemory'
+export { MEMORY_SESSION_STORE_KEY } from './domain/session/storeStrategies/sessionInMemory'
 export {
   willSyntheticsInjectRum,
-  getSyntheticsTestId,
-  getSyntheticsResultId,
+  getSyntheticsContext,
   isSyntheticsTest,
 } from './domain/synthetics/syntheticsWorkerValues'
+export type { SyntheticsContext } from './domain/synthetics/syntheticsWorkerValues'
 export { checkContext } from './domain/context/contextUtils'
 export * from './domain/resourceUtils'
 export * from './domain/bufferedData'
 export * from './tools/utils/polyfills'
 export * from './tools/utils/timezone'
-export * from './tools/utils/geolocation'
-export * from './tools/utils/geocoding'
+export * from './domain/geo/geolocation'
+export * from './domain/geo/geocoding'
 export * from './tools/utils/numberUtils'
 export * from './tools/utils/byteUtils'
 export * from './tools/utils/objectUtils'
 export * from './tools/utils/functionUtils'
 export * from './tools/serialisation/jsonStringify'
-export * from './tools/mergeInto'
+export * from './tools/serialisation/stringify'
 export * from './tools/utils/stringUtils'
 export * from './tools/matchOption'
 export * from './tools/utils/responseUtils'
-export * from './tools/utils/typeUtils'
 export type { RawError, RawErrorCause, ErrorWithCause, Csp } from './domain/error/error.types'
 export { ErrorHandling, ErrorSource } from './domain/error/error.types'
 export * from './domain/deflate'
 export * from './domain/connectivity'
 export * from './domain/userAgentData'
 export * from './tools/stackTrace/handlingStack'
-export * from './tools/abstractHooks'
-export * from './domain/tags'
+export * from './domain/tags'
+export { correctedChildSampleRate, isSampled, resetSampleDecisionCache, sampleUsingKnuthFactor } from './domain/sampler'
+export { startTelemetrySessionContext } from './domain/contexts/telemetrySessionContext'

package/src/tools/display.ts

@@ -1,56 +1,6 @@
 /* eslint-disable local-rules/disallow-side-effects */
-/**
- * Keep references on console methods to avoid triggering patched behaviors
- *
- * NB: in some setup, console could already be patched by another SDK.
- * In this case, some display messages can be sent by the other SDK
- * but we should be safe from infinite loop nonetheless.
- */
+import { createDisplay, DOCS_ORIGIN } from '@kubesense/kubesense-js-core/util'
 
-export const ConsoleApiName = {
-  log: 'log',
-  debug: 'debug',
-  info: 'info',
-  warn: 'warn',
-  error: 'error',
-} as const
+export const display = createDisplay('KubeSense Browser SDK:')
 
-export type ConsoleApiName = (typeof ConsoleApiName)[keyof typeof ConsoleApiName]
-
-interface Display {
-  debug: typeof console.debug
-  log: typeof console.log
-  info: typeof console.info
-  warn: typeof console.warn
-  error: typeof console.error
-}
-
-/**
- * When building JS bundles, some users might use a plugin[1] or configuration[2] to remove
- * "console.*" references. This causes some issue as we expect `console.*` to be defined.
- * As a workaround, let's use a variable alias, so those expressions won't be taken into account by
- * simple static analysis.
- *
- * [1]: https://babeljs.io/docs/babel-plugin-transform-remove-console/
- * [2]: https://github.com/terser/terser#compress-options (look for drop_console)
- */
-export const globalConsole = console
-
-export const originalConsoleMethods = {} as Display
-Object.keys(ConsoleApiName).forEach((name) => {
-  originalConsoleMethods[name as ConsoleApiName] = globalConsole[name as ConsoleApiName]
-})
-
-const PREFIX = 'KubeSense Browser SDK:'
-
-export const display: Display = {
-  debug: originalConsoleMethods.debug.bind(globalConsole, PREFIX),
-  log: originalConsoleMethods.log.bind(globalConsole, PREFIX),
-  info: originalConsoleMethods.info.bind(globalConsole, PREFIX),
-  warn: originalConsoleMethods.warn.bind(globalConsole, PREFIX),
-  error: originalConsoleMethods.error.bind(globalConsole, PREFIX),
-}
-
-export const DOCS_ORIGIN = 'https://docs.kubesense.ai'
 export const DOCS_TROUBLESHOOTING = `${DOCS_ORIGIN}/rum/browser/troubleshooting`
-export const MORE_DETAILS = 'More details:'

package/src/tools/experimentalFeatures.ts

@@ -14,11 +14,10 @@ import { objectHasValue } from './utils/objectUtils'
 
 // eslint-disable-next-line no-restricted-syntax
 export enum ExperimentalFeature {
+  // `session_replay_record_canvas` gated `sessionReplayCanvasRecording` until canvas recording became a
+  // regular option in 2.0.0. An application still passing it is unaffected: unknown flags are ignored.
   TRACK_INTAKE_REQUESTS = 'track_intake_requests',
-  USE_TREE_WALKER_FOR_ACTION_NAME = 'use_tree_walker_for_action_name',
-  FEATURE_OPERATION_VITAL = 'feature_operation_vital',
-  SHORT_SESSION_INVESTIGATION = 'short_session_investigation',
-  AVOID_FETCH_KEEPALIVE = 'avoid_fetch_keepalive',
+  TRACK_WEBSOCKETS = 'track_websockets',
 }
 
 const enabledExperimentalFeatures: Set<ExperimentalFeature> = new Set()

package/src/tools/getZoneJsOriginalValue.ts

@@ -1,6 +1,6 @@
-import { getGlobalObject } from './globalObject'
+import { globalObject } from '@kubesense/kubesense-js-core/util'
 
-export interface BrowserWindowWithZoneJs extends Window {
+export interface BrowserWindowWithZoneJs {
   Zone?: {
     // All Zone.js versions expose the __symbol__ method, but we observed that some website have a
     // 'Zone' global variable unrelated to Zone.js, so let's consider this method optional
@@ -26,7 +26,7 @@ export function getZoneJsOriginalValue<Target, Name extends keyof Target & strin
   target: Target,
   name: Name
 ): Target[Name] {
-  const browserWindow = getGlobalObject<BrowserWindowWithZoneJs>()
+  const browserWindow = globalObject as BrowserWindowWithZoneJs
   let original: Target[Name] | undefined
   if (browserWindow.Zone && typeof browserWindow.Zone.__symbol__ === 'function') {
     original = (target as any)[browserWindow.Zone.__symbol__(name)]

package/src/tools/instrumentMethod.ts

@@ -1,5 +1,5 @@
+import { callMonitored } from '@kubesense/kubesense-js-core/monitor'
 import { setTimeout } from './timer'
-import { callMonitored } from './monitor'
 import { noop } from './utils/functionUtils'
 import { createHandlingStack } from './stackTrace/handlingStack'
 
@@ -36,6 +36,35 @@ type PostCallCallback<TARGET extends { [key: string]: any }, METHOD extends keyo
   result: ReturnType<TARGET[METHOD]>
 ) => void
 
+type ConstructorParametersOf<CONSTRUCTOR> = CONSTRUCTOR extends new (...args: infer P) => any ? P : never
+type ConstructorInstanceOf<CONSTRUCTOR> = CONSTRUCTOR extends new (...args: any[]) => infer R ? R : never
+
+type AnyConstructor = abstract new (...args: any[]) => any
+
+/**
+ * Object passed to the callback of an instrumented constructor call. See `instrumentConstructor`
+ * for more info.
+ */
+export interface InstrumentedConstructorCall<CONSTRUCTOR> {
+  /**
+   * The parameters with which the constructor was called.
+   *
+   * Note: if needed, parameters can be mutated by the instrumentation
+   */
+  parameters: ConstructorParametersOf<CONSTRUCTOR>
+
+  /**
+   * Registers a callback that will be called after the original constructor is called, with the
+   * constructed instance passed as argument.
+   */
+  onPostCall: (callback: (result: ConstructorInstanceOf<CONSTRUCTOR>) => void) => void
+
+  /**
+   * The stack trace of the constructor call.
+   */
+  handlingStack?: string
+}
+
 /**
  * Instruments a method on a object, calling the given callback before the original method is
  * invoked. The callback receives an object with information about the method call.
@@ -57,6 +86,8 @@ type PostCallCallback<TARGET extends { [key: string]: any }, METHOD extends keyo
  * * if the event handler is set by a third party after us, we need to keep it in place when
  * removing ours.
  *
+ * To instrument a constructor @see {@link instrumentConstructor}.
+ *
  * @example
  *
  *  instrumentMethod(window, 'fetch', ({ target, parameters, onPostCall }) => {
@@ -88,40 +119,138 @@ export function instrumentMethod<TARGET extends { [key: string]: any }, METHOD e
   const instrumentation = function (this: TARGET): ReturnType<TARGET[METHOD]> {
     if (stopped) {
       // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
-      return original.apply(this, arguments as unknown as Parameters<TARGET[METHOD]>)
+      return original.apply(this, arguments)
     }
 
     const parameters = Array.from(arguments) as Parameters<TARGET[METHOD]>
 
-    let postCallCallback: PostCallCallback<TARGET, METHOD> | undefined
-
-    callMonitored(onPreCall, null, [
+    return notifyInstrumentation<InstrumentedMethodCall<TARGET, METHOD>, ReturnType<TARGET[METHOD]>>(
+      onPreCall,
       {
         target: this,
         parameters,
-        onPostCall: (callback) => {
-          postCallCallback = callback
-        },
         handlingStack: computeHandlingStack ? createHandlingStack('instrumented method') : undefined,
       },
-    ])
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call -- TARGET[METHOD] is any under the index signature; value is verified as a function above
+      () => original.apply(this, parameters)
+    )
+  } as TARGET[METHOD]
 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-    const result = original.apply(this, parameters)
+  const { stop: restoreOriginal } = replaceWithInstrumentation(targetPrototype, method, original, instrumentation)
 
-    if (postCallCallback) {
-      callMonitored(postCallCallback, null, [result])
-    }
+  return {
+    stop: () => {
+      stopped = true
+      restoreOriginal()
+    },
+  }
+}
 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    return result
+/**
+ * Instruments a constructor on an object (typically a global, e.g. `window.WebSocket`), calling the
+ * given callback before the original constructor is invoked. The callback receives an object with
+ * information about the constructor call, and can register an `onPostCall` callback to be notified
+ * with the constructed instance.
+ *
+ * Like `instrumentMethod`, this is a "good citizen" regarding third party instrumentations: stopping
+ * restores the original constructor unless a third party replaced it afterwards.
+ *
+ * The wrapper preserves the original prototype (so `instanceof` keeps working), the original
+ * `new.target` (so constructors that inspect it behave as if not instrumented), the original
+ * static members (e.g. `WebSocket.OPEN`), and `instance.constructor ===` so checks like
+ * `new WebSocket(url).constructor === WebSocket` stay true.
+ *
+ * @see {@link preserveConstructorShape} for limitations on static members preservation.
+ * @example
+ *
+ *  instrumentConstructor(window, 'WebSocket', ({ parameters, onPostCall }) => {
+ *    console.log('Before constructing WebSocket with parameters', parameters)
+ *
+ *    onPostCall((instance) => {
+ *      console.log('Constructed WebSocket instance', instance)
+ *    })
+ *  })
+ */
+export function instrumentConstructor<CONTAINER extends { [key: string]: any }, CONSTRUCTOR extends keyof CONTAINER>(
+  container: CONTAINER,
+  constructor: CONSTRUCTOR,
+  onPreCall: (this: null, callInfos: InstrumentedConstructorCall<CONTAINER[CONSTRUCTOR]>) => void,
+  { computeHandlingStack }: { computeHandlingStack?: boolean } = {}
+) {
+  const original = container[constructor]
+
+  if (typeof original !== 'function') {
+    return { stop: noop }
   }
 
-  targetPrototype[method] = instrumentation as TARGET[METHOD]
+  let stopped = false
+
+  const instrumentation = function (this: unknown): ConstructorInstanceOf<CONTAINER[CONSTRUCTOR]> {
+    // Bare `[[Call]]` (no `new`): delegate through `[[Call]]` and skip `onPreCall`. Otherwise we
+    // would notify instrumentation before the original rejects or returns, unlike the native
+    // constructor (e.g. `WebSocket(url)` or `class {}()` without `new`).
+    if (!new.target) {
+      return Reflect.apply(original, this, Array.from(arguments)) as ConstructorInstanceOf<CONTAINER[CONSTRUCTOR]>
+    }
+
+    // When `new` is used on this instrumented property, `new.target` is this wrapper. Passing
+    // it through to Reflect.construct would expose the wrong new.target inside the original
+    // body. If a subclass extends the wrapper, or a third party wraps us and their class is
+    // instantiated, `new.target` is that outer constructor and must be preserved.
+    const newTarget = new.target === instrumentation ? original : new.target
+
+    if (stopped) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return Reflect.construct(
+        original,
+        arguments as unknown as ConstructorParametersOf<CONTAINER[CONSTRUCTOR]>,
+        newTarget
+      )
+    }
+
+    const parameters = Array.from(arguments) as ConstructorParametersOf<CONTAINER[CONSTRUCTOR]>
+
+    return notifyInstrumentation<
+      InstrumentedConstructorCall<CONTAINER[CONSTRUCTOR]>,
+      ConstructorInstanceOf<CONTAINER[CONSTRUCTOR]>
+    >(
+      onPreCall,
+      {
+        parameters,
+        handlingStack: computeHandlingStack ? createHandlingStack('instrumented constructor') : undefined,
+      },
+      () =>
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        Reflect.construct(original, parameters, newTarget)
+    )
+  } as CONTAINER[CONSTRUCTOR]
+
+  const restorePrototypeConstructor = preserveConstructorShape(instrumentation, original)
+  const { stop: restoreOriginal } = replaceWithInstrumentation(container, constructor, original, instrumentation)
 
   return {
     stop: () => {
       stopped = true
+      restorePrototypeConstructor()
+      restoreOriginal()
+    },
+  }
+}
+
+/**
+ * Replaces `targetPrototype[method]` with the provided instrumentation and
+ * returns a `stop` function restoring the original (unless a third party replaced us afterwards).
+ */
+function replaceWithInstrumentation<TARGET extends { [key: string]: any }, METHOD extends keyof TARGET>(
+  targetPrototype: TARGET,
+  method: METHOD,
+  original: TARGET[METHOD],
+  instrumentation: TARGET[METHOD]
+) {
+  targetPrototype[method] = instrumentation
+
+  return {
+    stop: () => {
       // If the instrumentation has been removed by a third party, keep the last one
       if (targetPrototype[method] === instrumentation) {
         targetPrototype[method] = original
@@ -130,13 +259,94 @@ export function instrumentMethod<TARGET extends { [key: string]: any }, METHOD e
   }
 }
 
+/**
+ * Runs the pre-call callback (injecting the `onPostCall` registration), invokes the original
+ * method/constructor, then runs the registered post-call callback with the result.
+ *
+ * Note: the handling stack must be computed by the caller (at the topmost position of the call
+ * stack), so it is part of `baseCallInfo` rather than computed here.
+ */
+function notifyInstrumentation<CALL_INFO extends InstrumentationCallbacks<RESULT>, RESULT>(
+  onPreCall: (this: null, callInfo: CALL_INFO) => void,
+  baseCallInfo: Omit<CALL_INFO, 'onPostCall'>,
+  invokeOriginal: () => RESULT
+): RESULT {
+  let postCallCallback: ((result: RESULT) => void) | undefined
+
+  callMonitored(onPreCall, null, [
+    {
+      ...baseCallInfo,
+      onPostCall: (callback: (result: RESULT) => void) => {
+        postCallCallback = callback
+      },
+    } as CALL_INFO,
+  ])
+
+  const result = invokeOriginal()
+
+  if (postCallCallback) {
+    callMonitored(postCallCallback, null, [result])
+  }
+
+  return result
+}
+
+interface InstrumentationCallbacks<RESULT> {
+  onPostCall: (callback: (result: RESULT) => void) => void
+  handlingStack?: string
+}
+
+/**
+ * Copies the original constructor prototype and other static members onto the instrumentation, so that
+ * `instanceof` checks keep working and statics such as `WebSocket.OPEN` remain available while
+ * instrumented.
+ *
+ * Returns a function that restores `prototype.constructor` to its prior descriptor; call it
+ * before restoring the global property in `stop()`.
+ */
+function preserveConstructorShape(instrumentation: AnyConstructor, original: AnyConstructor): () => void {
+  /**
+   * Limitation: Only the original's *own* static members are copied. Statics inherited through the
+   * constructor's prototype chain (e.g. `class Child extends Parent` where `Parent` defines statics)
+   * are not preserved, since the instrumentation still inherits from `Function.prototype`. This is
+   * acceptable for the globals we instrument (e.g. `WebSocket`, whose own statics are the only ones
+   * that matter), but we would need to delegate the static prototype chain to support subclassed
+   * constructors with meaningful inherited statics.
+   */
+  for (const key of ([] as PropertyKey[]).concat(
+    Object.getOwnPropertyNames(original),
+    Object.getOwnPropertySymbols(original)
+  )) {
+    const descriptor = Object.getOwnPropertyDescriptor(original, key) as PropertyDescriptor
+    Object.defineProperty(instrumentation, key, descriptor)
+  }
+
+  /*
+   * Limitation: Repointing `constructor` on this shared prototype affects every instance whose
+   * `[[Prototype]]` is this object, including instances created before instrumentation, because
+   * `constructor` is inherited rather than snapshotted per instance. Code that held `original` (or
+   * whatever was in `prototype.constructor` before) as the canonical constructor and expects reference
+   * equality to that value for the lifetime of the page can observe a behavior change while RUM is
+   * active; restoring on `stop()` fixes this. In practice the SDK initializes as early as possible,
+   * which narrows the window where pre-instrument instances exist.
+   */
+  const { stop: restoreOriginalConstructor } = replaceWithInstrumentation(
+    original.prototype,
+    'constructor',
+    original.prototype.constructor,
+    instrumentation
+  )
+
+  return restoreOriginalConstructor
+}
+
 export function instrumentSetter<TARGET extends { [key: string]: any }, PROPERTY extends keyof TARGET>(
   targetPrototype: TARGET,
   property: PROPERTY,
   after: (target: TARGET, value: TARGET[PROPERTY]) => void
 ) {
   const originalDescriptor = Object.getOwnPropertyDescriptor(targetPrototype, property)
-  if (!originalDescriptor || !originalDescriptor.set || !originalDescriptor.configurable) {
+  if (!originalDescriptor?.set || !originalDescriptor.configurable) {
     return { stop: noop }
   }
 

package/src/tools/matchOption.ts

@@ -1,13 +1,7 @@
 import { display } from './display'
-import { getType } from './utils/typeUtils'
 
 export type MatchOption = string | RegExp | ((value: string) => boolean)
 
-export function isMatchOption(item: unknown): item is MatchOption {
-  const itemType = getType(item)
-  return itemType === 'string' || itemType === 'function' || item instanceof RegExp
-}
-
 /**
  * Returns true if value can be matched by at least one of the provided MatchOptions.
  * When comparing strings, setting useStartsWith to true will compare the value with the start of
@@ -19,6 +13,8 @@ export function matchList(list: MatchOption[], value: string, useStartsWith = fa
       if (typeof item === 'function') {
         return item(value)
       } else if (item instanceof RegExp) {
+        // Prevent stateful matching
+        item.lastIndex = 0
         return item.test(value)
       } else if (typeof item === 'string') {
         return useStartsWith ? value.startsWith(item) : item === value

package/src/tools/mockable.ts

@@ -0,0 +1,32 @@
+declare const __BUILD_ENV__SDK_VERSION__: string
+
+export const mockableReplacements = new Map<unknown, unknown>()
+
+/**
+ * Wraps a value to make it mockable in tests. In production builds, this is a no-op
+ * that returns the value as-is. In test builds, it checks if a mock replacement has
+ * been registered and returns that instead.
+ *
+ * @example
+ * // In source file:
+ * import { mockable } from '../tools/mockable'
+ * export function formatNavigationEntry(): string {
+ *   const navigationEntry = mockable(getNavigationEntry)()
+ *   ...
+ * }
+ *
+ * // In test file:
+ * import { replaceMockable } from '@kubesense/kubesense-browser-core/test'
+ * it('...', () => {
+ *   replaceMockable(getNavigationEntry, () => FAKE_NAVIGATION_ENTRY)
+ *   expect(formatNavigationEntry()).toEqual(...)
+ * })
+ */
+export function mockable<T>(value: T): T {
+  // In test builds, return a wrapper that checks for mocks at call time
+  if (__BUILD_ENV__SDK_VERSION__ === 'test' && mockableReplacements.has(value)) {
+    return mockableReplacements.get(value)! as T
+  }
+  // In production, return the value as-is
+  return value
+}