@spotify-confidence/csr-common 0.18.2 → 0.18.4

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.18.4](https://github.com/spotify/confidence-sdk-js/compare/csr-common-v0.18.3...csr-common-v0.18.4) (2026-08-05)
+
+
+### ✨ New Features
+
+* **csr-common:** optional eventId identity on custom event payloads ([#428](https://github.com/spotify/confidence-sdk-js/issues/428)) ([f49970a](https://github.com/spotify/confidence-sdk-js/commit/f49970a4ccd34cbfbdef7729df19a256f077fced))
+
+## [0.18.3](https://github.com/spotify/confidence-sdk-js/compare/csr-common-v0.18.2...csr-common-v0.18.3) (2026-07-16)
+
+
+### 🐛 Bug Fixes
+
+* **csr:** attempt to detect worker load failures caused by CSP ([#409](https://github.com/spotify/confidence-sdk-js/issues/409)) ([d0e38dc](https://github.com/spotify/confidence-sdk-js/commit/d0e38dc746bc571ee020d09f8922acb14ae7d7ae))
+
+
+### ✨ New Features
+
+* **csr:** blob: URL fallback when data: worker is blocked by CSP ([#410](https://github.com/spotify/confidence-sdk-js/issues/410)) ([52b56db](https://github.com/spotify/confidence-sdk-js/commit/52b56db4988b72a60d92517162773fca0d01eebb))
+
 ## [0.18.2](https://github.com/spotify/confidence-sdk-js/compare/csr-common-v0.18.1...csr-common-v0.18.2) (2026-07-06)
 
 

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { i as ClientContext, n as Frame, o as UserAgentContext } from "./types-D-hZGAw0.cjs";
+import { i as ClientContext, n as Frame, o as UserAgentContext } from "./types-CtBIVgp2.cjs";
 
 //#region src/events.d.ts
 /**
@@ -64,6 +64,7 @@ declare enum MouseInteractions {
 type RageClickCustomData = {
   tag: "csr:rageClick";
   payload: {
+    eventId?: string;
     targetId: number;
     clickCount: number;
     durationMs: number;
@@ -74,6 +75,7 @@ type RageClickCustomData = {
 type FormFieldReEditCustomData = {
   tag: "csr:formFieldReEdit";
   payload: {
+    eventId?: string;
     targetId: number;
     editCount: number;
     element?: ElementDescriptor;
@@ -83,6 +85,7 @@ type FormFieldReEditCustomData = {
 type ScrollBackCustomData = {
   tag: "csr:scrollBack";
   payload: {
+    eventId?: string;
     scrollBackPx: number;
     fromY: number;
     toY: number;
@@ -98,6 +101,7 @@ type ElementDescriptor = {
 type ClickCustomData = {
   tag: "csr:click";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -106,6 +110,7 @@ type ClickCustomData = {
 type InputCustomData = {
   tag: "csr:input";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -116,6 +121,7 @@ type InputCustomData = {
 type DeadClickCustomData = {
   tag: "csr:deadClick";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -124,12 +130,14 @@ type DeadClickCustomData = {
 type TabUnfocusCustomData = {
   tag: "csr:tabUnfocus";
   payload: {
+    eventId?: string;
     pathname?: string;
   };
 };
 type TabRefocusCustomData = {
   tag: "csr:tabRefocus";
   payload: {
+    eventId?: string;
     awayDurationMs: number;
     pathname?: string;
   };
@@ -142,7 +150,9 @@ type RouteChangePayload = {
 };
 type RouteChangeCustomData = {
   tag: "csr:routeChange";
-  payload: RouteChangePayload;
+  payload: RouteChangePayload & {
+    eventId?: string;
+  };
 };
 /**
 * Plugin event data emitted by the recorder for tab visibility changes.
@@ -211,18 +221,21 @@ type FlagEvaluationPluginData = {
 type ErrorMessageCustomData = {
   tag: "csr:errorMessage";
   payload: {
+    eventId?: string;
     text: string;
   };
 };
 type DialogOpenedCustomData = {
   tag: "csr:dialogOpened";
   payload: {
+    eventId?: string;
     content: string[];
   };
 };
 type IdleGapCustomData = {
   tag: "csr:idleGap";
   payload: {
+    eventId?: string;
     visibleGapS: number;
     totalGapS: number;
     hiddenS: number;
@@ -232,6 +245,7 @@ type IdleGapCustomData = {
 type AwayGapCustomData = {
   tag: "csr:awayGap";
   payload: {
+    eventId?: string;
     totalGapS: number;
     hiddenS: number;
   };
@@ -239,6 +253,11 @@ type AwayGapCustomData = {
 /**
 * Closed union of every Custom event we emit. Add a new variant here when
 * introducing a new tag — emitting an unregistered tag is a TS error.
+*
+* Every payload carries an optional `eventId`: a per-event identity stamped
+* at emission by the analyzer (uuid). It is inert metadata — players ignore
+* it — and exists so downstream review tooling can reference and remove
+* individual generated events without patching untyped data.
 */
 type CustomEventData = ClickCustomData | InputCustomData | RageClickCustomData | FormFieldReEditCustomData | ScrollBackCustomData | DeadClickCustomData | TabUnfocusCustomData | TabRefocusCustomData | RouteChangeCustomData | ErrorMessageCustomData | DialogOpenedCustomData | IdleGapCustomData | AwayGapCustomData;
 /**

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { i as ClientContext, n as Frame, o as UserAgentContext } from "./types-D-hZGAw0.js";
+import { i as ClientContext, n as Frame, o as UserAgentContext } from "./types-CtBIVgp2.js";
 
 //#region src/events.d.ts
 /**
@@ -64,6 +64,7 @@ declare enum MouseInteractions {
 type RageClickCustomData = {
   tag: "csr:rageClick";
   payload: {
+    eventId?: string;
     targetId: number;
     clickCount: number;
     durationMs: number;
@@ -74,6 +75,7 @@ type RageClickCustomData = {
 type FormFieldReEditCustomData = {
   tag: "csr:formFieldReEdit";
   payload: {
+    eventId?: string;
     targetId: number;
     editCount: number;
     element?: ElementDescriptor;
@@ -83,6 +85,7 @@ type FormFieldReEditCustomData = {
 type ScrollBackCustomData = {
   tag: "csr:scrollBack";
   payload: {
+    eventId?: string;
     scrollBackPx: number;
     fromY: number;
     toY: number;
@@ -98,6 +101,7 @@ type ElementDescriptor = {
 type ClickCustomData = {
   tag: "csr:click";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -106,6 +110,7 @@ type ClickCustomData = {
 type InputCustomData = {
   tag: "csr:input";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -116,6 +121,7 @@ type InputCustomData = {
 type DeadClickCustomData = {
   tag: "csr:deadClick";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -124,12 +130,14 @@ type DeadClickCustomData = {
 type TabUnfocusCustomData = {
   tag: "csr:tabUnfocus";
   payload: {
+    eventId?: string;
     pathname?: string;
   };
 };
 type TabRefocusCustomData = {
   tag: "csr:tabRefocus";
   payload: {
+    eventId?: string;
     awayDurationMs: number;
     pathname?: string;
   };
@@ -142,7 +150,9 @@ type RouteChangePayload = {
 };
 type RouteChangeCustomData = {
   tag: "csr:routeChange";
-  payload: RouteChangePayload;
+  payload: RouteChangePayload & {
+    eventId?: string;
+  };
 };
 /**
 * Plugin event data emitted by the recorder for tab visibility changes.
@@ -211,18 +221,21 @@ type FlagEvaluationPluginData = {
 type ErrorMessageCustomData = {
   tag: "csr:errorMessage";
   payload: {
+    eventId?: string;
     text: string;
   };
 };
 type DialogOpenedCustomData = {
   tag: "csr:dialogOpened";
   payload: {
+    eventId?: string;
     content: string[];
   };
 };
 type IdleGapCustomData = {
   tag: "csr:idleGap";
   payload: {
+    eventId?: string;
     visibleGapS: number;
     totalGapS: number;
     hiddenS: number;
@@ -232,6 +245,7 @@ type IdleGapCustomData = {
 type AwayGapCustomData = {
   tag: "csr:awayGap";
   payload: {
+    eventId?: string;
     totalGapS: number;
     hiddenS: number;
   };
@@ -239,6 +253,11 @@ type AwayGapCustomData = {
 /**
 * Closed union of every Custom event we emit. Add a new variant here when
 * introducing a new tag — emitting an unregistered tag is a TS error.
+*
+* Every payload carries an optional `eventId`: a per-event identity stamped
+* at emission by the analyzer (uuid). It is inert metadata — players ignore
+* it — and exists so downstream review tooling can reference and remove
+* individual generated events without patching untyped data.
 */
 type CustomEventData = ClickCustomData | InputCustomData | RageClickCustomData | FormFieldReEditCustomData | ScrollBackCustomData | DeadClickCustomData | TabUnfocusCustomData | TabRefocusCustomData | RouteChangeCustomData | ErrorMessageCustomData | DialogOpenedCustomData | IdleGapCustomData | AwayGapCustomData;
 /**

package/dist/{types-D-hZGAw0.d.cts → types-CtBIVgp2.d.cts}

@@ -92,6 +92,8 @@ interface CreateUploaderOptions {
   * Worker messages are forwarded over the port and tagged so you can tell them apart.
   */
   debugLogger?: (msg: string) => void;
+  /** @internal Override the welcome-handshake timeout for testing. */
+  _welcomeTimeoutMs?: number;
 }
 /** Internal: wire-level frame. Session-id is implicit (Transport is session-bound at open). */
 interface Frame {

package/dist/{types-D-hZGAw0.d.ts → types-CtBIVgp2.d.ts}

@@ -92,6 +92,8 @@ interface CreateUploaderOptions {
   * Worker messages are forwarded over the port and tagged so you can tell them apart.
   */
   debugLogger?: (msg: string) => void;
+  /** @internal Override the welcome-handshake timeout for testing. */
+  _welcomeTimeoutMs?: number;
 }
 /** Internal: wire-level frame. Session-id is implicit (Transport is session-bound at open). */
 interface Frame {

package/dist/uploader/index.cjs

@@ -57,6 +57,7 @@ const STORAGE_TAB_ID = "csr:tabId";
 const STORAGE_SESSION = "csr:session";
 const STORAGE_COUNTER = "csr:counter";
 const DEFAULT_SESSION_TTL_MS = 1800 * 1e3;
+const WELCOME_TIMEOUT_MS = 1e4;
 async function createUploader(opts) {
 	const log = opts.debugLogger;
 	const sessionTtlMs = opts.sessionTtlMs ?? DEFAULT_SESSION_TTL_MS;
@@ -65,7 +66,9 @@ async function createUploader(opts) {
 	const counterHint = readCounter();
 	const mode = resolveMode(opts.workerMode ?? "auto");
 	log?.(`tab: createUploader mode=${mode} tabId=${tabId} sessionHint=${sessionHint?.id ?? "(none)"} counterHint=${counterHint}`);
-	const port = await openWorkerPort(mode, opts.clientSecret, opts.workerUrl);
+	const workerName = mode === "shared" ? await hashSecret(opts.clientSecret) : void 0;
+	const { port, urlScheme } = await openWorkerPort(mode, opts.workerUrl, workerName, log);
+	log?.(`tab: worker loaded via ${urlScheme}${urlScheme === "blob" ? " (fallback — cross-tab sharing unavailable)" : ""}`);
 	let phase = "awaiting-welcome";
 	let sessionId = null;
 	let sessionToken = null;
@@ -125,7 +128,17 @@ async function createUploader(opts) {
 		debugLogs: log !== void 0
 	});
 	log?.("tab: hello sent, awaiting welcome");
-	const welcome = await welcomePromise;
+	const timeoutMs = opts._welcomeTimeoutMs ?? WELCOME_TIMEOUT_MS;
+	let welcomeTimer;
+	const welcomeDeadline = new Promise((_, reject) => {
+		port.onError((err) => reject(err));
+		welcomeTimer = setTimeout(() => reject(/* @__PURE__ */ new Error(`uploader: welcome timeout. The worker did not respond within ${timeoutMs / 1e3}s. This may indicate a CSP policy blocking the worker script from loading. Check your browser console for errors.`)), timeoutMs);
+	});
+	welcomeDeadline.catch(() => {});
+	const welcome = await Promise.race([welcomePromise.then((msg) => {
+		clearTimeout(welcomeTimer);
+		return msg;
+	}), welcomeDeadline]);
 	log?.(welcome.type === "welcome" ? `tab: welcome (${"sessionId" in welcome.result ? `sessionId=${welcome.result.sessionId}` : "skipRecording"})` : `tab: dead reason=${welcome.reason}`);
 	if (welcome.type === "dead") throw new Error(`uploader: ${welcome.reason}`);
 	if ("skipRecording" in welcome.result) {
@@ -195,37 +208,101 @@ function resolveMode(mode) {
 	if (mode === "auto") return typeof SharedWorker !== "undefined" ? "shared" : "dedicated";
 	return mode;
 }
-async function openWorkerPort(mode, clientSecret, workerUrl) {
-	const url = workerUrl ?? toDataUrl("//#region src/uploader/worker/web-socket-transport.ts\n/**\n* WebSocket-backed Transport. Internal retry policy: clean server-initiated close after the\n* first successful open → reconnect and resume; abrupt close (or any close before the first\n* open) → fire `onClose` and stop. Frames received while a (re)connect is in progress are\n* buffered and flushed on open.\n*\n* `ready()` resolves on the first successful open and rejects on close-before-open. Callers\n* should await it before treating the Transport as live, so a failure to open can be caught\n* (e.g. 4404 unknown session) and recovered from.\n*/\nvar WebSocketTransport = class {\n	url;\n	ws = null;\n	onCloseCb = null;\n	onStateChangeCb = null;\n	intentionallyClosed = false;\n	dead = false;\n	/** Frames buffered while a (re)connect is in progress. */\n	pending = [];\n	readyPromise;\n	constructor(url) {\n		this.url = url;\n		this.readyPromise = new Promise((resolve, reject) => {\n			this.connect(false, resolve, reject);\n		});\n		this.readyPromise.catch(() => {});\n	}\n	ready() {\n		return this.readyPromise;\n	}\n	send(frame) {\n		if (this.dead || this.intentionallyClosed) return;\n		if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify(frame));\n		else this.pending.push(frame);\n	}\n	close(reason = \"transport-close\") {\n		this.intentionallyClosed = true;\n		this.ws?.close(1e3, reason);\n	}\n	onClose(cb) {\n		this.onCloseCb = cb;\n	}\n	onStateChange(cb) {\n		this.onStateChangeCb = cb;\n	}\n	connect(isReconnect, onReady, onReadyFail) {\n		const ws = new WebSocket(this.url);\n		this.ws = ws;\n		let opened = false;\n		ws.onopen = () => {\n			opened = true;\n			onReady?.();\n			if (isReconnect) this.onStateChangeCb?.({ connected: true });\n			while (this.pending.length > 0) {\n				const f = this.pending.shift();\n				ws.send(JSON.stringify(f));\n			}\n		};\n		ws.onclose = (event) => {\n			if (this.intentionallyClosed) return;\n			if (!opened) {\n				const reason = `${isReconnect ? \"reconnect\" : \"initial\"}-failed code=${event.code}`;\n				if (onReadyFail) {\n					onReadyFail(new Error(reason));\n					this.dead = true;\n				} else this.die(reason);\n				return;\n			}\n			if (event.wasClean && (event.code === 1e3 || event.code === 1001)) {\n				this.onStateChangeCb?.({ connected: false });\n				this.connect(true);\n			} else this.die(`close code=${event.code} wasClean=${event.wasClean}`);\n		};\n	}\n	die(reason) {\n		this.dead = true;\n		this.onCloseCb?.({ reason });\n	}\n};\n//#endregion\n//#region src/uploader/worker/csr-client.ts\n/**\n* Single Client implementation that talks to the recording backend's REST + WS protocol.\n* Both dev-server and prod implement the same protocol, so we don't need polymorphism here yet.\n*/\nvar CsrClient = class {\n	apiUrl;\n	clientSecret;\n	context;\n	websocketUrl;\n	log;\n	forceRecord;\n	constructor(apiUrl, clientSecret, context, websocketUrl, log = () => {}, forceRecord) {\n		this.apiUrl = apiUrl;\n		this.clientSecret = clientSecret;\n		this.context = context;\n		this.websocketUrl = websocketUrl;\n		this.log = log;\n		this.forceRecord = forceRecord;\n	}\n	async initSession() {\n		const url = `${this.trimSlash(this.apiUrl)}/v1/sessions:initSession`;\n		this.log(`fetch POST ${url}`);\n		const res = await fetch(url, {\n			method: \"POST\",\n			headers: { \"Content-Type\": \"application/json\" },\n			body: JSON.stringify({\n				clientSecret: this.clientSecret,\n				...this.context && Object.keys(this.context).length > 0 ? { context: this.context } : {},\n				...this.forceRecord ? { forceRecord: true } : {}\n			})\n		});\n		if (!res.ok) throw new Error(`init-session failed: HTTP ${res.status}`);\n		const data = await res.json();\n		if (data.skipRecording) return { skipRecording: true };\n		if (!data.sessionId || !data.sessionToken) throw new Error(\"init-session response missing sessionId or sessionToken\");\n		return {\n			sessionId: data.sessionId,\n			sessionToken: data.sessionToken\n		};\n	}\n	async openTransport(sessionToken) {\n		const wsBase = this.websocketUrl ?? `${this.toWsScheme(this.trimSlash(this.apiUrl))}/sessions/stream`;\n		const url = `${wsBase}${wsBase.includes(\"?\") ? \"&\" : \"?\"}session_token=${encodeURIComponent(sessionToken)}`;\n		this.log(`WebSocket connect ${url.replace(/session_token=[^&]*/, \"session_token=[REDACTED]\")}`);\n		const transport = new WebSocketTransport(url);\n		await transport.ready();\n		return transport;\n	}\n	trimSlash(s) {\n		return s.endsWith(\"/\") ? s.slice(0, -1) : s;\n	}\n	toWsScheme(base) {\n		if (base.startsWith(\"https://\")) return `wss://${base.slice(8)}`;\n		if (base.startsWith(\"http://\")) return `ws://${base.slice(7)}`;\n		return base;\n	}\n};\n//#endregion\n//#region src/uploader/worker/core.ts\nconst IDLE_GRACE_MS = 5e3;\nlet state = { phase: \"init\" };\nconst ports = [];\nlet idleTimer = null;\nfunction cancelIdleTimer() {\n	if (idleTimer !== null) {\n		clearTimeout(idleTimer);\n		idleTimer = null;\n	}\n}\nfunction log(msg) {\n	for (const handle of ports) if (handle.debugLogs) handle.port.postMessage({\n		type: \"log\",\n		msg\n	});\n}\n/**\n* The first hello \"locks in\" the session's apiUrl/clientSecret. Any later tab arriving\n* with different values is misconfigured — we reject it rather than silently using the\n* locked values. In SharedWorker mode the `name = hash(clientSecret)` scoping already\n* prevents secret-mismatch from sharing a worker, but this defends against the dedicated\n* path and against future bugs.\n*/\nlet lockedConfig = null;\nfunction registerPort(adapter) {\n	cancelIdleTimer();\n	const handle = {\n		port: adapter,\n		hello: null,\n		debugLogs: false\n	};\n	ports.push(handle);\n	adapter.onmessage((data) => {\n		handleMessage(handle, data);\n	});\n}\nfunction handleMessage(handle, message) {\n	switch (message.type) {\n		case \"hello\":\n			handle.hello = message;\n			handle.debugLogs = message.debugLogs ?? false;\n			if (rejectIfIncompatible(handle)) return;\n			if (state.phase !== \"dead\" && state.phase !== \"skipping\") detectDuplicateTab(handle);\n			onHello(handle);\n			return;\n		case \"frame\":\n			onFrame(message.frame);\n			return;\n		case \"bye\":\n			onBye(handle);\n			return;\n		default: break;\n	}\n}\n/**\n* Reject hellos whose `apiUrl`/`clientSecret` don't match the values established by the\n* first hello. Returns true if the port was rejected (caller should not continue\n* processing this hello).\n*/\nfunction rejectIfIncompatible(handle) {\n	if (lockedConfig === null) return false;\n	const incoming = handle.hello;\n	if (incoming.apiUrl === lockedConfig.apiUrl && incoming.websocketUrl === lockedConfig.websocketUrl && incoming.clientSecret === lockedConfig.clientSecret) return false;\n	handle.port.postMessage({\n		type: \"dead\",\n		reason: \"incompatible-options: apiUrl/websocketUrl/clientSecret differ from the worker session\"\n	});\n	const idx = ports.indexOf(handle);\n	if (idx >= 0) ports.splice(idx, 1);\n	return true;\n}\n/**\n* If another already-connected port has the same `tabId`, this hello is from a duplicate\n* tab (browser \"Duplicate\" command clones sessionStorage). Mint a fresh `tabId` so the two\n* tabs don't collide on the same `(sessionId, tabId)` Recording. The new tabId is returned\n* to the tab in `welcome` so it can update its own state and sessionStorage.\n*/\nfunction detectDuplicateTab(handle) {\n	const tabId = handle.hello.tabId;\n	if (!ports.some((p) => p !== handle && p.hello?.tabId === tabId)) return;\n	const fresh = crypto.randomUUID();\n	handle.newTabId = fresh;\n	handle.hello.tabId = fresh;\n}\nfunction onHello(handle) {\n	switch (state.phase) {\n		case \"init\":\n			lockedConfig = {\n				apiUrl: handle.hello.apiUrl,\n				websocketUrl: handle.hello.websocketUrl,\n				clientSecret: handle.hello.clientSecret\n			};\n			log(`hello received apiUrl=${handle.hello.apiUrl} websocketUrl=${handle.hello.websocketUrl ?? \"(derive)\"} sessionIdHint=${handle.hello.sessionIdHint ?? \"(none)\"}`);\n			state = { phase: \"initializing\" };\n			initializeSession(handle.hello).then(flushPendingWelcomes);\n			return;\n		case \"initializing\": return;\n		case \"active\":\n			sendActiveWelcome(handle, state.sessionId, state.sessionToken);\n			return;\n		case \"idle\": {\n			const { client, sessionId, sessionToken } = state;\n			state = { phase: \"initializing\" };\n			resumeTransport(client, sessionId, sessionToken).then(flushPendingWelcomes);\n			return;\n		}\n		case \"skipping\":\n			if (handle.hello.forceRecord) {\n				log(\"forceRecord set; re-initializing from skipping state\");\n				state = { phase: \"initializing\" };\n				initializeSession(handle.hello).then(flushPendingWelcomes);\n				return;\n			}\n			handle.port.postMessage({\n				type: \"welcome\",\n				result: { skipRecording: true }\n			});\n			return;\n		case \"dead\":\n			handle.port.postMessage({\n				type: \"dead\",\n				reason: state.reason\n			});\n			return;\n		default: break;\n	}\n}\nasync function initializeSession(firstHello) {\n	const client = new CsrClient(firstHello.apiUrl, firstHello.clientSecret, firstHello.context, firstHello.websocketUrl, log, firstHello.forceRecord);\n	if (firstHello.sessionIdHint && firstHello.sessionTokenHint) {\n		log(`adopting sessionIdHint=${firstHello.sessionIdHint}`);\n		try {\n			const transport = await client.openTransport(firstHello.sessionTokenHint);\n			wireTransport(transport);\n			state = {\n				phase: \"active\",\n				client,\n				transport,\n				sessionId: firstHello.sessionIdHint,\n				sessionToken: firstHello.sessionTokenHint\n			};\n			log(\"hint adopted; transport open\");\n			if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n			return;\n		} catch (err) {\n			log(`hint rejected (${String(err)}); falling back to fresh init`);\n		}\n	}\n	let result;\n	try {\n		result = await client.initSession();\n	} catch (err) {\n		log(`init-session threw: ${String(err)}`);\n		transitionToDead(`init-session-failed: ${String(err)}`);\n		return;\n	}\n	if (\"skipRecording\" in result) {\n		log(\"init-session: skipRecording\");\n		state = { phase: \"skipping\" };\n		return;\n	}\n	log(`init-session ok sessionId=${result.sessionId}`);\n	let transport;\n	try {\n		transport = await client.openTransport(result.sessionToken);\n	} catch (err) {\n		log(`openTransport threw: ${String(err)}`);\n		transitionToDead(`open-transport-failed: ${String(err)}`);\n		return;\n	}\n	wireTransport(transport);\n	log(\"transport open; session active\");\n	state = {\n		phase: \"active\",\n		client,\n		transport,\n		sessionId: result.sessionId,\n		sessionToken: result.sessionToken\n	};\n	if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n}\nasync function resumeTransport(client, sessionId, sessionToken) {\n	log(\"resuming transport from idle\");\n	let transport;\n	try {\n		transport = await client.openTransport(sessionToken);\n	} catch (err) {\n		log(`resume-transport threw: ${String(err)}`);\n		transitionToDead(`resume-transport-failed: ${String(err)}`);\n		return;\n	}\n	wireTransport(transport);\n	log(\"transport resumed\");\n	state = {\n		phase: \"active\",\n		client,\n		transport,\n		sessionId,\n		sessionToken\n	};\n	if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n}\nfunction wireTransport(transport) {\n	transport.onClose((info) => {\n		if (state.phase !== \"active\") return;\n		transitionToDead(info.reason);\n	});\n	transport.onStateChange((info) => {\n		if (state.phase !== \"active\") return;\n		for (const handle of ports) handle.port.postMessage({\n			type: \"state\",\n			connected: info.connected\n		});\n	});\n}\nfunction transitionToDead(reason) {\n	state = {\n		phase: \"dead\",\n		reason\n	};\n	for (const handle of ports) handle.port.postMessage({\n		type: \"dead\",\n		reason\n	});\n}\nfunction flushPendingWelcomes() {\n	for (const handle of ports) {\n		if (handle.hello === null) continue;\n		if (state.phase === \"active\") sendActiveWelcome(handle, state.sessionId, state.sessionToken);\n		else if (state.phase === \"skipping\") handle.port.postMessage({\n			type: \"welcome\",\n			result: { skipRecording: true }\n		});\n		else if (state.phase === \"dead\") handle.port.postMessage({\n			type: \"dead\",\n			reason: state.reason\n		});\n	}\n}\nfunction sendActiveWelcome(handle, currentSessionId, currentSessionToken) {\n	const hint = handle.hello?.sessionIdHint;\n	const adopted = hint !== void 0 && hint !== currentSessionId;\n	const newTabId = handle.newTabId;\n	handle.port.postMessage({\n		type: \"welcome\",\n		result: {\n			sessionId: currentSessionId,\n			sessionToken: currentSessionToken\n		},\n		adoptedFromSessionId: adopted ? hint : void 0,\n		newTabId,\n		resetCounter: adopted || newTabId !== void 0\n	});\n}\nfunction onFrame(frame) {\n	if (state.phase !== \"active\") return;\n	state.transport.send(frame);\n}\nfunction onBye(handle) {\n	const idx = ports.indexOf(handle);\n	if (idx >= 0) ports.splice(idx, 1);\n	if (ports.length === 0 && state.phase === \"active\") {\n		log(`last tab disconnected; closing transport in ${IDLE_GRACE_MS}ms`);\n		idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n	}\n}\nfunction enterIdle() {\n	idleTimer = null;\n	if (state.phase !== \"active\" || ports.length > 0) return;\n	log(\"idle timeout; closing transport\");\n	state.transport.close(\"idle\");\n	state = {\n		phase: \"idle\",\n		client: state.client,\n		sessionId: state.sessionId,\n		sessionToken: state.sessionToken\n	};\n}\n//#endregion\n//#region src/uploader/worker/entry.ts\nconst SharedWorkerScopeCtor = globalThis.SharedWorkerGlobalScope;\nif (typeof SharedWorkerScopeCtor === \"function\" && self instanceof SharedWorkerScopeCtor) self.onconnect = (event) => {\n	const port = event.ports[0];\n	port.start();\n	registerPort(adaptMessagePort(port));\n};\nelse registerPort(adaptDedicatedSelf());\nfunction adaptMessagePort(port) {\n	return {\n		postMessage: (message) => port.postMessage(message),\n		onmessage: (cb) => {\n			port.onmessage = (e) => cb(e.data);\n		}\n	};\n}\nfunction adaptDedicatedSelf() {\n	const ws = self;\n	return {\n		postMessage: (message) => ws.postMessage(message),\n		onmessage: (cb) => {\n			ws.onmessage = (e) => cb(e.data);\n		}\n	};\n}\n//#endregion\n");
-	if (mode === "shared") {
-		const options = {
-			name: await hashSecret(clientSecret),
-			type: "module",
-			extendedLifetime: true
-		};
-		const worker = new SharedWorker(url, options);
-		worker.port.start();
+async function openWorkerPort(mode, workerUrl, workerName, log) {
+	if (workerUrl) return {
+		port: createWorker(mode, workerUrl, workerName),
+		urlScheme: "custom"
+	};
+	const dataUrl = toDataUrl(workerScript);
+	try {
+		const port = createWorker(mode, dataUrl, workerName);
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		const asyncErr = port.getBufferedError();
+		if (asyncErr) throw asyncErr;
 		return {
-			postMessage: (m) => worker.port.postMessage(m),
-			setHandler: (cb) => {
-				worker.port.onmessage = (e) => cb(e.data);
-			}
+			port,
+			urlScheme: "data"
 		};
+	} catch (_dataErr) {
+		log?.("tab: data: worker blocked, falling back to blob: URL (dedicated mode)");
+		const blobUrl = toBlobUrl(workerScript);
+		try {
+			return {
+				port: createDedicatedWorker(blobUrl),
+				urlScheme: "blob"
+			};
+		} catch (blobErr) {
+			const hint = "Your Content Security Policy blocks both `data:` and `blob:` in `worker-src`. To fix this, either add `blob:` to your `worker-src` directive, or use the `workerUrl` option to serve the worker script from your own origin.";
+			log?.(`tab: worker-load-failed: ${hint}`);
+			throw new Error(`worker-load-failed: ${hint}`, blobErr instanceof Error ? { cause: blobErr } : void 0);
+		}
 	}
+}
+function createWorker(mode, url, workerName) {
+	if (mode === "shared") return createSharedWorker(url, workerName);
+	return createDedicatedWorker(url);
+}
+function createSharedWorker(url, name) {
+	const options = {
+		name,
+		type: "module",
+		extendedLifetime: true
+	};
+	const worker = new SharedWorker(url, options);
+	let errorCb = null;
+	let bufferedError = null;
+	worker.onerror = (e) => {
+		const err = workerLoadError(e, url);
+		if (errorCb) errorCb(err);
+		else bufferedError = err;
+	};
+	worker.port.start();
+	return {
+		postMessage: (m) => worker.port.postMessage(m),
+		setHandler: (cb) => {
+			worker.port.onmessage = (e) => cb(e.data);
+		},
+		onError: (cb) => {
+			errorCb = cb;
+			if (bufferedError) cb(bufferedError);
+		},
+		getBufferedError: () => bufferedError
+	};
+}
+function createDedicatedWorker(url) {
 	const worker = new Worker(url, { type: "module" });
+	let errorCb = null;
+	let bufferedError = null;
+	worker.onerror = (e) => {
+		const err = workerLoadError(e, url);
+		if (errorCb) errorCb(err);
+		else bufferedError = err;
+	};
 	return {
 		postMessage: (m) => worker.postMessage(m),
 		setHandler: (cb) => {
 			worker.onmessage = (e) => cb(e.data);
-		}
+		},
+		onError: (cb) => {
+			errorCb = cb;
+			if (bufferedError) cb(bufferedError);
+		},
+		getBufferedError: () => bufferedError
 	};
 }
+function workerLoadError(cause, url) {
+	const msg = `worker-load-failed: ${url.startsWith("data:") ? "This is likely caused by a Content Security Policy (CSP) that blocks `data:` in `worker-src`. To fix this, either add `data:` to your `worker-src` directive, or use the `workerUrl` option to serve the worker script from your own origin." : `Failed to load the worker script from ${url}. Check that the URL is reachable and that your CSP \`worker-src\` directive allows it.`}`;
+	return new Error(msg, cause instanceof Error ? { cause } : void 0);
+}
 function toDataUrl(script) {
 	const bytes = new TextEncoder().encode(script);
 	let binary = "";
 	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
 	return `data:application/javascript;base64,${btoa(binary)}`;
 }
+function toBlobUrl(script) {
+	return URL.createObjectURL(new Blob([script], { type: "application/javascript" }));
+}
 async function hashSecret(secret) {
 	const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret));
 	return Array.from(new Uint8Array(buf)).slice(0, 8).map((b) => b.toString(16).padStart(2, "0")).join("");

package/dist/uploader/index.d.cts

@@ -1,4 +1,4 @@
-import { a as ContextValue, i as ClientContext, o as UserAgentContext, r as Uploader, s as collectUserAgentContext, t as CreateUploaderOptions } from "../types-D-hZGAw0.cjs";
+import { a as ContextValue, i as ClientContext, o as UserAgentContext, r as Uploader, s as collectUserAgentContext, t as CreateUploaderOptions } from "../types-CtBIVgp2.cjs";
 
 //#region src/uploader/create-uploader.d.ts
 declare function createUploader(opts: CreateUploaderOptions): Promise<Uploader | null>;

package/dist/uploader/index.d.ts

@@ -1,4 +1,4 @@
-import { a as ContextValue, i as ClientContext, o as UserAgentContext, r as Uploader, s as collectUserAgentContext, t as CreateUploaderOptions } from "../types-D-hZGAw0.js";
+import { a as ContextValue, i as ClientContext, o as UserAgentContext, r as Uploader, s as collectUserAgentContext, t as CreateUploaderOptions } from "../types-CtBIVgp2.js";
 
 //#region src/uploader/create-uploader.d.ts
 declare function createUploader(opts: CreateUploaderOptions): Promise<Uploader | null>;

package/dist/uploader/index.js

@@ -33,6 +33,7 @@ const STORAGE_TAB_ID = "csr:tabId";
 const STORAGE_SESSION = "csr:session";
 const STORAGE_COUNTER = "csr:counter";
 const DEFAULT_SESSION_TTL_MS = 1800 * 1e3;
+const WELCOME_TIMEOUT_MS = 1e4;
 async function createUploader(opts) {
 	const log = opts.debugLogger;
 	const sessionTtlMs = opts.sessionTtlMs ?? DEFAULT_SESSION_TTL_MS;
@@ -41,7 +42,9 @@ async function createUploader(opts) {
 	const counterHint = readCounter();
 	const mode = resolveMode(opts.workerMode ?? "auto");
 	log?.(`tab: createUploader mode=${mode} tabId=${tabId} sessionHint=${sessionHint?.id ?? "(none)"} counterHint=${counterHint}`);
-	const port = await openWorkerPort(mode, opts.clientSecret, opts.workerUrl);
+	const workerName = mode === "shared" ? await hashSecret(opts.clientSecret) : void 0;
+	const { port, urlScheme } = await openWorkerPort(mode, opts.workerUrl, workerName, log);
+	log?.(`tab: worker loaded via ${urlScheme}${urlScheme === "blob" ? " (fallback — cross-tab sharing unavailable)" : ""}`);
 	let phase = "awaiting-welcome";
 	let sessionId = null;
 	let sessionToken = null;
@@ -101,7 +104,17 @@ async function createUploader(opts) {
 		debugLogs: log !== void 0
 	});
 	log?.("tab: hello sent, awaiting welcome");
-	const welcome = await welcomePromise;
+	const timeoutMs = opts._welcomeTimeoutMs ?? WELCOME_TIMEOUT_MS;
+	let welcomeTimer;
+	const welcomeDeadline = new Promise((_, reject) => {
+		port.onError((err) => reject(err));
+		welcomeTimer = setTimeout(() => reject(/* @__PURE__ */ new Error(`uploader: welcome timeout. The worker did not respond within ${timeoutMs / 1e3}s. This may indicate a CSP policy blocking the worker script from loading. Check your browser console for errors.`)), timeoutMs);
+	});
+	welcomeDeadline.catch(() => {});
+	const welcome = await Promise.race([welcomePromise.then((msg) => {
+		clearTimeout(welcomeTimer);
+		return msg;
+	}), welcomeDeadline]);
 	log?.(welcome.type === "welcome" ? `tab: welcome (${"sessionId" in welcome.result ? `sessionId=${welcome.result.sessionId}` : "skipRecording"})` : `tab: dead reason=${welcome.reason}`);
 	if (welcome.type === "dead") throw new Error(`uploader: ${welcome.reason}`);
 	if ("skipRecording" in welcome.result) {
@@ -171,37 +184,101 @@ function resolveMode(mode) {
 	if (mode === "auto") return typeof SharedWorker !== "undefined" ? "shared" : "dedicated";
 	return mode;
 }
-async function openWorkerPort(mode, clientSecret, workerUrl) {
-	const url = workerUrl ?? toDataUrl("//#region src/uploader/worker/web-socket-transport.ts\n/**\n* WebSocket-backed Transport. Internal retry policy: clean server-initiated close after the\n* first successful open → reconnect and resume; abrupt close (or any close before the first\n* open) → fire `onClose` and stop. Frames received while a (re)connect is in progress are\n* buffered and flushed on open.\n*\n* `ready()` resolves on the first successful open and rejects on close-before-open. Callers\n* should await it before treating the Transport as live, so a failure to open can be caught\n* (e.g. 4404 unknown session) and recovered from.\n*/\nvar WebSocketTransport = class {\n	url;\n	ws = null;\n	onCloseCb = null;\n	onStateChangeCb = null;\n	intentionallyClosed = false;\n	dead = false;\n	/** Frames buffered while a (re)connect is in progress. */\n	pending = [];\n	readyPromise;\n	constructor(url) {\n		this.url = url;\n		this.readyPromise = new Promise((resolve, reject) => {\n			this.connect(false, resolve, reject);\n		});\n		this.readyPromise.catch(() => {});\n	}\n	ready() {\n		return this.readyPromise;\n	}\n	send(frame) {\n		if (this.dead || this.intentionallyClosed) return;\n		if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify(frame));\n		else this.pending.push(frame);\n	}\n	close(reason = \"transport-close\") {\n		this.intentionallyClosed = true;\n		this.ws?.close(1e3, reason);\n	}\n	onClose(cb) {\n		this.onCloseCb = cb;\n	}\n	onStateChange(cb) {\n		this.onStateChangeCb = cb;\n	}\n	connect(isReconnect, onReady, onReadyFail) {\n		const ws = new WebSocket(this.url);\n		this.ws = ws;\n		let opened = false;\n		ws.onopen = () => {\n			opened = true;\n			onReady?.();\n			if (isReconnect) this.onStateChangeCb?.({ connected: true });\n			while (this.pending.length > 0) {\n				const f = this.pending.shift();\n				ws.send(JSON.stringify(f));\n			}\n		};\n		ws.onclose = (event) => {\n			if (this.intentionallyClosed) return;\n			if (!opened) {\n				const reason = `${isReconnect ? \"reconnect\" : \"initial\"}-failed code=${event.code}`;\n				if (onReadyFail) {\n					onReadyFail(new Error(reason));\n					this.dead = true;\n				} else this.die(reason);\n				return;\n			}\n			if (event.wasClean && (event.code === 1e3 || event.code === 1001)) {\n				this.onStateChangeCb?.({ connected: false });\n				this.connect(true);\n			} else this.die(`close code=${event.code} wasClean=${event.wasClean}`);\n		};\n	}\n	die(reason) {\n		this.dead = true;\n		this.onCloseCb?.({ reason });\n	}\n};\n//#endregion\n//#region src/uploader/worker/csr-client.ts\n/**\n* Single Client implementation that talks to the recording backend's REST + WS protocol.\n* Both dev-server and prod implement the same protocol, so we don't need polymorphism here yet.\n*/\nvar CsrClient = class {\n	apiUrl;\n	clientSecret;\n	context;\n	websocketUrl;\n	log;\n	forceRecord;\n	constructor(apiUrl, clientSecret, context, websocketUrl, log = () => {}, forceRecord) {\n		this.apiUrl = apiUrl;\n		this.clientSecret = clientSecret;\n		this.context = context;\n		this.websocketUrl = websocketUrl;\n		this.log = log;\n		this.forceRecord = forceRecord;\n	}\n	async initSession() {\n		const url = `${this.trimSlash(this.apiUrl)}/v1/sessions:initSession`;\n		this.log(`fetch POST ${url}`);\n		const res = await fetch(url, {\n			method: \"POST\",\n			headers: { \"Content-Type\": \"application/json\" },\n			body: JSON.stringify({\n				clientSecret: this.clientSecret,\n				...this.context && Object.keys(this.context).length > 0 ? { context: this.context } : {},\n				...this.forceRecord ? { forceRecord: true } : {}\n			})\n		});\n		if (!res.ok) throw new Error(`init-session failed: HTTP ${res.status}`);\n		const data = await res.json();\n		if (data.skipRecording) return { skipRecording: true };\n		if (!data.sessionId || !data.sessionToken) throw new Error(\"init-session response missing sessionId or sessionToken\");\n		return {\n			sessionId: data.sessionId,\n			sessionToken: data.sessionToken\n		};\n	}\n	async openTransport(sessionToken) {\n		const wsBase = this.websocketUrl ?? `${this.toWsScheme(this.trimSlash(this.apiUrl))}/sessions/stream`;\n		const url = `${wsBase}${wsBase.includes(\"?\") ? \"&\" : \"?\"}session_token=${encodeURIComponent(sessionToken)}`;\n		this.log(`WebSocket connect ${url.replace(/session_token=[^&]*/, \"session_token=[REDACTED]\")}`);\n		const transport = new WebSocketTransport(url);\n		await transport.ready();\n		return transport;\n	}\n	trimSlash(s) {\n		return s.endsWith(\"/\") ? s.slice(0, -1) : s;\n	}\n	toWsScheme(base) {\n		if (base.startsWith(\"https://\")) return `wss://${base.slice(8)}`;\n		if (base.startsWith(\"http://\")) return `ws://${base.slice(7)}`;\n		return base;\n	}\n};\n//#endregion\n//#region src/uploader/worker/core.ts\nconst IDLE_GRACE_MS = 5e3;\nlet state = { phase: \"init\" };\nconst ports = [];\nlet idleTimer = null;\nfunction cancelIdleTimer() {\n	if (idleTimer !== null) {\n		clearTimeout(idleTimer);\n		idleTimer = null;\n	}\n}\nfunction log(msg) {\n	for (const handle of ports) if (handle.debugLogs) handle.port.postMessage({\n		type: \"log\",\n		msg\n	});\n}\n/**\n* The first hello \"locks in\" the session's apiUrl/clientSecret. Any later tab arriving\n* with different values is misconfigured — we reject it rather than silently using the\n* locked values. In SharedWorker mode the `name = hash(clientSecret)` scoping already\n* prevents secret-mismatch from sharing a worker, but this defends against the dedicated\n* path and against future bugs.\n*/\nlet lockedConfig = null;\nfunction registerPort(adapter) {\n	cancelIdleTimer();\n	const handle = {\n		port: adapter,\n		hello: null,\n		debugLogs: false\n	};\n	ports.push(handle);\n	adapter.onmessage((data) => {\n		handleMessage(handle, data);\n	});\n}\nfunction handleMessage(handle, message) {\n	switch (message.type) {\n		case \"hello\":\n			handle.hello = message;\n			handle.debugLogs = message.debugLogs ?? false;\n			if (rejectIfIncompatible(handle)) return;\n			if (state.phase !== \"dead\" && state.phase !== \"skipping\") detectDuplicateTab(handle);\n			onHello(handle);\n			return;\n		case \"frame\":\n			onFrame(message.frame);\n			return;\n		case \"bye\":\n			onBye(handle);\n			return;\n		default: break;\n	}\n}\n/**\n* Reject hellos whose `apiUrl`/`clientSecret` don't match the values established by the\n* first hello. Returns true if the port was rejected (caller should not continue\n* processing this hello).\n*/\nfunction rejectIfIncompatible(handle) {\n	if (lockedConfig === null) return false;\n	const incoming = handle.hello;\n	if (incoming.apiUrl === lockedConfig.apiUrl && incoming.websocketUrl === lockedConfig.websocketUrl && incoming.clientSecret === lockedConfig.clientSecret) return false;\n	handle.port.postMessage({\n		type: \"dead\",\n		reason: \"incompatible-options: apiUrl/websocketUrl/clientSecret differ from the worker session\"\n	});\n	const idx = ports.indexOf(handle);\n	if (idx >= 0) ports.splice(idx, 1);\n	return true;\n}\n/**\n* If another already-connected port has the same `tabId`, this hello is from a duplicate\n* tab (browser \"Duplicate\" command clones sessionStorage). Mint a fresh `tabId` so the two\n* tabs don't collide on the same `(sessionId, tabId)` Recording. The new tabId is returned\n* to the tab in `welcome` so it can update its own state and sessionStorage.\n*/\nfunction detectDuplicateTab(handle) {\n	const tabId = handle.hello.tabId;\n	if (!ports.some((p) => p !== handle && p.hello?.tabId === tabId)) return;\n	const fresh = crypto.randomUUID();\n	handle.newTabId = fresh;\n	handle.hello.tabId = fresh;\n}\nfunction onHello(handle) {\n	switch (state.phase) {\n		case \"init\":\n			lockedConfig = {\n				apiUrl: handle.hello.apiUrl,\n				websocketUrl: handle.hello.websocketUrl,\n				clientSecret: handle.hello.clientSecret\n			};\n			log(`hello received apiUrl=${handle.hello.apiUrl} websocketUrl=${handle.hello.websocketUrl ?? \"(derive)\"} sessionIdHint=${handle.hello.sessionIdHint ?? \"(none)\"}`);\n			state = { phase: \"initializing\" };\n			initializeSession(handle.hello).then(flushPendingWelcomes);\n			return;\n		case \"initializing\": return;\n		case \"active\":\n			sendActiveWelcome(handle, state.sessionId, state.sessionToken);\n			return;\n		case \"idle\": {\n			const { client, sessionId, sessionToken } = state;\n			state = { phase: \"initializing\" };\n			resumeTransport(client, sessionId, sessionToken).then(flushPendingWelcomes);\n			return;\n		}\n		case \"skipping\":\n			if (handle.hello.forceRecord) {\n				log(\"forceRecord set; re-initializing from skipping state\");\n				state = { phase: \"initializing\" };\n				initializeSession(handle.hello).then(flushPendingWelcomes);\n				return;\n			}\n			handle.port.postMessage({\n				type: \"welcome\",\n				result: { skipRecording: true }\n			});\n			return;\n		case \"dead\":\n			handle.port.postMessage({\n				type: \"dead\",\n				reason: state.reason\n			});\n			return;\n		default: break;\n	}\n}\nasync function initializeSession(firstHello) {\n	const client = new CsrClient(firstHello.apiUrl, firstHello.clientSecret, firstHello.context, firstHello.websocketUrl, log, firstHello.forceRecord);\n	if (firstHello.sessionIdHint && firstHello.sessionTokenHint) {\n		log(`adopting sessionIdHint=${firstHello.sessionIdHint}`);\n		try {\n			const transport = await client.openTransport(firstHello.sessionTokenHint);\n			wireTransport(transport);\n			state = {\n				phase: \"active\",\n				client,\n				transport,\n				sessionId: firstHello.sessionIdHint,\n				sessionToken: firstHello.sessionTokenHint\n			};\n			log(\"hint adopted; transport open\");\n			if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n			return;\n		} catch (err) {\n			log(`hint rejected (${String(err)}); falling back to fresh init`);\n		}\n	}\n	let result;\n	try {\n		result = await client.initSession();\n	} catch (err) {\n		log(`init-session threw: ${String(err)}`);\n		transitionToDead(`init-session-failed: ${String(err)}`);\n		return;\n	}\n	if (\"skipRecording\" in result) {\n		log(\"init-session: skipRecording\");\n		state = { phase: \"skipping\" };\n		return;\n	}\n	log(`init-session ok sessionId=${result.sessionId}`);\n	let transport;\n	try {\n		transport = await client.openTransport(result.sessionToken);\n	} catch (err) {\n		log(`openTransport threw: ${String(err)}`);\n		transitionToDead(`open-transport-failed: ${String(err)}`);\n		return;\n	}\n	wireTransport(transport);\n	log(\"transport open; session active\");\n	state = {\n		phase: \"active\",\n		client,\n		transport,\n		sessionId: result.sessionId,\n		sessionToken: result.sessionToken\n	};\n	if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n}\nasync function resumeTransport(client, sessionId, sessionToken) {\n	log(\"resuming transport from idle\");\n	let transport;\n	try {\n		transport = await client.openTransport(sessionToken);\n	} catch (err) {\n		log(`resume-transport threw: ${String(err)}`);\n		transitionToDead(`resume-transport-failed: ${String(err)}`);\n		return;\n	}\n	wireTransport(transport);\n	log(\"transport resumed\");\n	state = {\n		phase: \"active\",\n		client,\n		transport,\n		sessionId,\n		sessionToken\n	};\n	if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n}\nfunction wireTransport(transport) {\n	transport.onClose((info) => {\n		if (state.phase !== \"active\") return;\n		transitionToDead(info.reason);\n	});\n	transport.onStateChange((info) => {\n		if (state.phase !== \"active\") return;\n		for (const handle of ports) handle.port.postMessage({\n			type: \"state\",\n			connected: info.connected\n		});\n	});\n}\nfunction transitionToDead(reason) {\n	state = {\n		phase: \"dead\",\n		reason\n	};\n	for (const handle of ports) handle.port.postMessage({\n		type: \"dead\",\n		reason\n	});\n}\nfunction flushPendingWelcomes() {\n	for (const handle of ports) {\n		if (handle.hello === null) continue;\n		if (state.phase === \"active\") sendActiveWelcome(handle, state.sessionId, state.sessionToken);\n		else if (state.phase === \"skipping\") handle.port.postMessage({\n			type: \"welcome\",\n			result: { skipRecording: true }\n		});\n		else if (state.phase === \"dead\") handle.port.postMessage({\n			type: \"dead\",\n			reason: state.reason\n		});\n	}\n}\nfunction sendActiveWelcome(handle, currentSessionId, currentSessionToken) {\n	const hint = handle.hello?.sessionIdHint;\n	const adopted = hint !== void 0 && hint !== currentSessionId;\n	const newTabId = handle.newTabId;\n	handle.port.postMessage({\n		type: \"welcome\",\n		result: {\n			sessionId: currentSessionId,\n			sessionToken: currentSessionToken\n		},\n		adoptedFromSessionId: adopted ? hint : void 0,\n		newTabId,\n		resetCounter: adopted || newTabId !== void 0\n	});\n}\nfunction onFrame(frame) {\n	if (state.phase !== \"active\") return;\n	state.transport.send(frame);\n}\nfunction onBye(handle) {\n	const idx = ports.indexOf(handle);\n	if (idx >= 0) ports.splice(idx, 1);\n	if (ports.length === 0 && state.phase === \"active\") {\n		log(`last tab disconnected; closing transport in ${IDLE_GRACE_MS}ms`);\n		idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n	}\n}\nfunction enterIdle() {\n	idleTimer = null;\n	if (state.phase !== \"active\" || ports.length > 0) return;\n	log(\"idle timeout; closing transport\");\n	state.transport.close(\"idle\");\n	state = {\n		phase: \"idle\",\n		client: state.client,\n		sessionId: state.sessionId,\n		sessionToken: state.sessionToken\n	};\n}\n//#endregion\n//#region src/uploader/worker/entry.ts\nconst SharedWorkerScopeCtor = globalThis.SharedWorkerGlobalScope;\nif (typeof SharedWorkerScopeCtor === \"function\" && self instanceof SharedWorkerScopeCtor) self.onconnect = (event) => {\n	const port = event.ports[0];\n	port.start();\n	registerPort(adaptMessagePort(port));\n};\nelse registerPort(adaptDedicatedSelf());\nfunction adaptMessagePort(port) {\n	return {\n		postMessage: (message) => port.postMessage(message),\n		onmessage: (cb) => {\n			port.onmessage = (e) => cb(e.data);\n		}\n	};\n}\nfunction adaptDedicatedSelf() {\n	const ws = self;\n	return {\n		postMessage: (message) => ws.postMessage(message),\n		onmessage: (cb) => {\n			ws.onmessage = (e) => cb(e.data);\n		}\n	};\n}\n//#endregion\n");
-	if (mode === "shared") {
-		const options = {
-			name: await hashSecret(clientSecret),
-			type: "module",
-			extendedLifetime: true
-		};
-		const worker = new SharedWorker(url, options);
-		worker.port.start();
+async function openWorkerPort(mode, workerUrl, workerName, log) {
+	if (workerUrl) return {
+		port: createWorker(mode, workerUrl, workerName),
+		urlScheme: "custom"
+	};
+	const dataUrl = toDataUrl(workerScript);
+	try {
+		const port = createWorker(mode, dataUrl, workerName);
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		const asyncErr = port.getBufferedError();
+		if (asyncErr) throw asyncErr;
 		return {
-			postMessage: (m) => worker.port.postMessage(m),
-			setHandler: (cb) => {
-				worker.port.onmessage = (e) => cb(e.data);
-			}
+			port,
+			urlScheme: "data"
 		};
+	} catch (_dataErr) {
+		log?.("tab: data: worker blocked, falling back to blob: URL (dedicated mode)");
+		const blobUrl = toBlobUrl(workerScript);
+		try {
+			return {
+				port: createDedicatedWorker(blobUrl),
+				urlScheme: "blob"
+			};
+		} catch (blobErr) {
+			const hint = "Your Content Security Policy blocks both `data:` and `blob:` in `worker-src`. To fix this, either add `blob:` to your `worker-src` directive, or use the `workerUrl` option to serve the worker script from your own origin.";
+			log?.(`tab: worker-load-failed: ${hint}`);
+			throw new Error(`worker-load-failed: ${hint}`, blobErr instanceof Error ? { cause: blobErr } : void 0);
+		}
 	}
+}
+function createWorker(mode, url, workerName) {
+	if (mode === "shared") return createSharedWorker(url, workerName);
+	return createDedicatedWorker(url);
+}
+function createSharedWorker(url, name) {
+	const options = {
+		name,
+		type: "module",
+		extendedLifetime: true
+	};
+	const worker = new SharedWorker(url, options);
+	let errorCb = null;
+	let bufferedError = null;
+	worker.onerror = (e) => {
+		const err = workerLoadError(e, url);
+		if (errorCb) errorCb(err);
+		else bufferedError = err;
+	};
+	worker.port.start();
+	return {
+		postMessage: (m) => worker.port.postMessage(m),
+		setHandler: (cb) => {
+			worker.port.onmessage = (e) => cb(e.data);
+		},
+		onError: (cb) => {
+			errorCb = cb;
+			if (bufferedError) cb(bufferedError);
+		},
+		getBufferedError: () => bufferedError
+	};
+}
+function createDedicatedWorker(url) {
 	const worker = new Worker(url, { type: "module" });
+	let errorCb = null;
+	let bufferedError = null;
+	worker.onerror = (e) => {
+		const err = workerLoadError(e, url);
+		if (errorCb) errorCb(err);
+		else bufferedError = err;
+	};
 	return {
 		postMessage: (m) => worker.postMessage(m),
 		setHandler: (cb) => {
 			worker.onmessage = (e) => cb(e.data);
-		}
+		},
+		onError: (cb) => {
+			errorCb = cb;
+			if (bufferedError) cb(bufferedError);
+		},
+		getBufferedError: () => bufferedError
 	};
 }
+function workerLoadError(cause, url) {
+	const msg = `worker-load-failed: ${url.startsWith("data:") ? "This is likely caused by a Content Security Policy (CSP) that blocks `data:` in `worker-src`. To fix this, either add `data:` to your `worker-src` directive, or use the `workerUrl` option to serve the worker script from your own origin." : `Failed to load the worker script from ${url}. Check that the URL is reachable and that your CSP \`worker-src\` directive allows it.`}`;
+	return new Error(msg, cause instanceof Error ? { cause } : void 0);
+}
 function toDataUrl(script) {
 	const bytes = new TextEncoder().encode(script);
 	let binary = "";
 	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
 	return `data:application/javascript;base64,${btoa(binary)}`;
 }
+function toBlobUrl(script) {
+	return URL.createObjectURL(new Blob([script], { type: "application/javascript" }));
+}
 async function hashSecret(secret) {
 	const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret));
 	return Array.from(new Uint8Array(buf)).slice(0, 8).map((b) => b.toString(16).padStart(2, "0")).join("");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spotify-confidence/csr-common",
   "license": "Apache-2.0",
-  "version": "0.18.2",
+  "version": "0.18.4",
   "repository": {
     "type": "git",
     "url": "https://github.com/spotify/confidence-sdk-js.git",

package/src/events.ts

@@ -65,6 +65,7 @@ export enum MouseInteractions {
 export type RageClickCustomData = {
   tag: 'csr:rageClick';
   payload: {
+    eventId?: string;
     targetId: number;
     clickCount: number;
     durationMs: number;
@@ -76,6 +77,7 @@ export type RageClickCustomData = {
 export type FormFieldReEditCustomData = {
   tag: 'csr:formFieldReEdit';
   payload: {
+    eventId?: string;
     targetId: number;
     editCount: number;
     element?: ElementDescriptor;
@@ -86,6 +88,7 @@ export type FormFieldReEditCustomData = {
 export type ScrollBackCustomData = {
   tag: 'csr:scrollBack';
   payload: {
+    eventId?: string;
     scrollBackPx: number;
     fromY: number;
     toY: number;
@@ -103,6 +106,7 @@ export type ElementDescriptor = {
 export type ClickCustomData = {
   tag: 'csr:click';
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -112,6 +116,7 @@ export type ClickCustomData = {
 export type InputCustomData = {
   tag: 'csr:input';
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -123,6 +128,7 @@ export type InputCustomData = {
 export type DeadClickCustomData = {
   tag: 'csr:deadClick';
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -132,6 +138,7 @@ export type DeadClickCustomData = {
 export type TabUnfocusCustomData = {
   tag: 'csr:tabUnfocus';
   payload: {
+    eventId?: string;
     pathname?: string;
   };
 };
@@ -139,6 +146,7 @@ export type TabUnfocusCustomData = {
 export type TabRefocusCustomData = {
   tag: 'csr:tabRefocus';
   payload: {
+    eventId?: string;
     awayDurationMs: number;
     pathname?: string;
   };
@@ -154,7 +162,9 @@ export type RouteChangePayload = {
 
 export type RouteChangeCustomData = {
   tag: 'csr:routeChange';
-  payload: RouteChangePayload;
+  // Intersected rather than added to RouteChangePayload so the plugin-event
+  // shape (RouteChangePluginData) stays free of analyzer identity.
+  payload: RouteChangePayload & { eventId?: string };
 };
 
 /**
@@ -231,6 +241,7 @@ export type FlagEvaluationPluginData = {
 export type ErrorMessageCustomData = {
   tag: 'csr:errorMessage';
   payload: {
+    eventId?: string;
     text: string;
   };
 };
@@ -238,6 +249,7 @@ export type ErrorMessageCustomData = {
 export type DialogOpenedCustomData = {
   tag: 'csr:dialogOpened';
   payload: {
+    eventId?: string;
     content: string[];
   };
 };
@@ -245,6 +257,7 @@ export type DialogOpenedCustomData = {
 export type IdleGapCustomData = {
   tag: 'csr:idleGap';
   payload: {
+    eventId?: string;
     visibleGapS: number;
     totalGapS: number;
     hiddenS: number;
@@ -255,6 +268,7 @@ export type IdleGapCustomData = {
 export type AwayGapCustomData = {
   tag: 'csr:awayGap';
   payload: {
+    eventId?: string;
     totalGapS: number;
     hiddenS: number;
   };
@@ -263,6 +277,11 @@ export type AwayGapCustomData = {
 /**
  * Closed union of every Custom event we emit. Add a new variant here when
  * introducing a new tag — emitting an unregistered tag is a TS error.
+ *
+ * Every payload carries an optional `eventId`: a per-event identity stamped
+ * at emission by the analyzer (uuid). It is inert metadata — players ignore
+ * it — and exists so downstream review tooling can reference and remove
+ * individual generated events without patching untyped data.
  */
 export type CustomEventData =
   | ClickCustomData

package/src/uploader/create-uploader.test.ts

@@ -0,0 +1,312 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { CreateUploaderOptions } from './types';
+
+vi.mock('./worker/worker-script', () => ({
+  workerScript: 'console.log("worker")',
+}));
+
+const DEFAULTS: CreateUploaderOptions = {
+  apiUrl: 'https://api.example',
+  clientSecret: 'secret',
+};
+
+function fakeSessionStorage(): Storage {
+  const store: Record<string, string> = {};
+  return {
+    getItem: (key: string) => store[key] ?? null,
+    setItem: (key: string, value: string) => {
+      store[key] = value;
+    },
+    removeItem: (key: string) => {
+      delete store[key];
+    },
+    clear: () => Object.keys(store).forEach(k => delete store[k]),
+    get length() {
+      return Object.keys(store).length;
+    },
+    key: (i: number) => Object.keys(store)[i] ?? null,
+  };
+}
+
+class StubWorker {
+  onerror: ((e: Event) => void) | null = null;
+  onmessage: ((e: MessageEvent) => void) | null = null;
+  postMessage() {}
+}
+
+function installWorkerStubs(opts?: { workerThrows?: boolean; sharedWorkerThrows?: boolean }) {
+  (globalThis as Record<string, unknown>).Worker = opts?.workerThrows
+    ? class {
+        constructor() {
+          throw new DOMException('Blocked', 'SecurityError');
+        }
+      }
+    : StubWorker;
+
+  if (opts?.sharedWorkerThrows) {
+    (globalThis as Record<string, unknown>).SharedWorker = class {
+      constructor() {
+        throw new DOMException('Blocked', 'SecurityError');
+      }
+    };
+  } else {
+    (globalThis as Record<string, unknown>).SharedWorker = class {
+      onerror: ((e: Event) => void) | null = null;
+      port = {
+        start() {},
+        onmessage: null as ((e: MessageEvent) => void) | null,
+        postMessage() {},
+      };
+    };
+  }
+}
+
+function tick() {
+  return new Promise(r => setTimeout(r, 0));
+}
+
+describe('createUploader', () => {
+  const blobUrls: string[] = [];
+
+  beforeEach(() => {
+    globalThis.sessionStorage = fakeSessionStorage();
+
+    if (!globalThis.crypto) {
+      (globalThis as Record<string, unknown>).crypto = {};
+    }
+    if (!globalThis.crypto.randomUUID) {
+      globalThis.crypto.randomUUID = () =>
+        '00000000-0000-0000-0000-000000000000' as `${string}-${string}-${string}-${string}-${string}`;
+    }
+    if (!globalThis.crypto.subtle?.digest) {
+      (globalThis.crypto as Record<string, unknown>).subtle = {
+        digest: async () => new ArrayBuffer(32),
+      };
+    }
+
+    vi.spyOn(URL, 'createObjectURL').mockImplementation(() => {
+      const url = `blob:http://localhost/${blobUrls.length}`;
+      blobUrls.push(url);
+      return url;
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    blobUrls.length = 0;
+    delete (globalThis as Record<string, unknown>).SharedWorker;
+  });
+
+  async function loadCreateUploader() {
+    vi.resetModules();
+    // .js extension is required by Node16 module resolution for dynamic imports
+    // (static `import` lines work without it because the package is CJS — see package.json).
+    // eslint-disable-next-line es/no-dynamic-import
+    const mod = await import('./create-uploader.js');
+    return mod.createUploader;
+  }
+
+  describe('blob: fallback', () => {
+    it('uses data: URL when Worker constructor succeeds', async () => {
+      installWorkerStubs();
+
+      const createUploader = await loadCreateUploader();
+      const logs: string[] = [];
+      createUploader({ ...DEFAULTS, workerMode: 'dedicated', debugLogger: m => logs.push(m) });
+      await tick();
+
+      expect(blobUrls).toHaveLength(0);
+      expect(logs.some(l => l.includes('via data'))).toBe(true);
+    });
+
+    it('falls back to blob: when data: Worker throws', async () => {
+      let constructedUrl: string | undefined;
+      (globalThis as Record<string, unknown>).Worker = class {
+        onerror: ((e: Event) => void) | null = null;
+        onmessage: ((e: MessageEvent) => void) | null = null;
+        postMessage() {}
+        constructor(url: string) {
+          if (url.startsWith('data:')) {
+            throw new DOMException('Blocked', 'SecurityError');
+          }
+          constructedUrl = url;
+        }
+      };
+      delete (globalThis as Record<string, unknown>).SharedWorker;
+
+      const createUploader = await loadCreateUploader();
+      const logs: string[] = [];
+      createUploader({ ...DEFAULTS, workerMode: 'dedicated', debugLogger: m => logs.push(m) });
+      await tick();
+
+      expect(blobUrls).toHaveLength(1);
+      expect(constructedUrl).toBe(blobUrls[0]);
+      expect(logs.some(l => l.includes('falling back to blob:'))).toBe(true);
+      expect(logs.some(l => l.includes('via blob'))).toBe(true);
+    });
+
+    it('falls back to blob: dedicated worker when SharedWorker data: throws', async () => {
+      (globalThis as Record<string, unknown>).SharedWorker = class {
+        constructor() {
+          throw new DOMException('Blocked', 'SecurityError');
+        }
+      };
+      let constructedUrl: string | undefined;
+      (globalThis as Record<string, unknown>).Worker = class {
+        onerror: ((e: Event) => void) | null = null;
+        onmessage: ((e: MessageEvent) => void) | null = null;
+        postMessage() {}
+        constructor(url: string) {
+          constructedUrl = url;
+        }
+      };
+
+      const createUploader = await loadCreateUploader();
+      const logs: string[] = [];
+      createUploader({ ...DEFAULTS, workerMode: 'shared', debugLogger: m => logs.push(m) });
+      await tick();
+
+      expect(blobUrls).toHaveLength(1);
+      expect(constructedUrl).toBe(blobUrls[0]);
+      expect(logs.some(l => l.includes('falling back to blob:'))).toBe(true);
+    });
+
+    it('falls back to blob: when SharedWorker onerror fires asynchronously (Chrome CSP)', async () => {
+      let constructedUrl: string | undefined;
+      (globalThis as Record<string, unknown>).SharedWorker = class {
+        onerror: ((e: Event) => void) | null = null;
+        port = {
+          start() {},
+          onmessage: null as ((e: MessageEvent) => void) | null,
+          postMessage() {},
+        };
+        constructor() {
+          setTimeout(() => this.onerror?.(new Event('error')), 0);
+        }
+      };
+      (globalThis as Record<string, unknown>).Worker = class {
+        onerror: ((e: Event) => void) | null = null;
+        onmessage: ((e: MessageEvent) => void) | null = null;
+        postMessage() {}
+        constructor(url: string) {
+          constructedUrl = url;
+        }
+      };
+
+      const createUploader = await loadCreateUploader();
+      const logs: string[] = [];
+      // Await the full async chain: openWorkerPort detects the async onerror,
+      // falls back to blob, then createUploader eventually hits the welcome timeout.
+      const p = createUploader({
+        ...DEFAULTS,
+        workerMode: 'shared',
+        debugLogger: m => logs.push(m),
+        _welcomeTimeoutMs: 50,
+      });
+      await expect(p).rejects.toThrow(/welcome timeout/);
+
+      expect(blobUrls).toHaveLength(1);
+      expect(constructedUrl).toBe(blobUrls[0]);
+      expect(logs.some(l => l.includes('falling back to blob:'))).toBe(true);
+    });
+
+    it('throws with CSP hint when both data: and blob: are blocked', async () => {
+      (globalThis as Record<string, unknown>).Worker = class {
+        constructor() {
+          throw new DOMException('Blocked', 'SecurityError');
+        }
+      };
+      delete (globalThis as Record<string, unknown>).SharedWorker;
+
+      const createUploader = await loadCreateUploader();
+
+      await expect(createUploader({ ...DEFAULTS, workerMode: 'dedicated' })).rejects.toThrow(/worker-src/);
+    });
+
+    it('logs CSP hint via debugLogger when both data: and blob: are blocked', async () => {
+      (globalThis as Record<string, unknown>).Worker = class {
+        constructor() {
+          throw new DOMException('Blocked', 'SecurityError');
+        }
+      };
+      delete (globalThis as Record<string, unknown>).SharedWorker;
+
+      const createUploader = await loadCreateUploader();
+      const logs: string[] = [];
+
+      await expect(
+        createUploader({ ...DEFAULTS, workerMode: 'dedicated', debugLogger: m => logs.push(m) }),
+      ).rejects.toThrow();
+      expect(logs.some(l => l.includes('worker-load-failed') && l.includes('worker-src'))).toBe(true);
+    });
+
+    it('does not fall back when a custom workerUrl is provided', async () => {
+      (globalThis as Record<string, unknown>).Worker = class {
+        constructor() {
+          throw new Error('custom URL not found');
+        }
+      };
+      delete (globalThis as Record<string, unknown>).SharedWorker;
+
+      const createUploader = await loadCreateUploader();
+
+      await expect(
+        createUploader({ ...DEFAULTS, workerMode: 'dedicated', workerUrl: 'https://cdn.example/worker.js' }),
+      ).rejects.toThrow();
+      expect(blobUrls).toHaveLength(0);
+    });
+  });
+
+  describe('worker load failure (async error)', () => {
+    it('throws with CSP hint when dedicated Worker fires onerror', async () => {
+      (globalThis as Record<string, unknown>).Worker = class {
+        onerror: ((e: Event) => void) | null = null;
+        onmessage: ((e: MessageEvent) => void) | null = null;
+        postMessage() {}
+        constructor() {
+          setTimeout(() => this.onerror?.(new Event('error')), 5);
+        }
+      };
+      delete (globalThis as Record<string, unknown>).SharedWorker;
+
+      const createUploader = await loadCreateUploader();
+
+      await expect(createUploader({ ...DEFAULTS, workerMode: 'dedicated' })).rejects.toThrow(/worker-src/);
+    });
+
+    it('throws with CSP hint when SharedWorker fires onerror', async () => {
+      (globalThis as Record<string, unknown>).SharedWorker = class {
+        onerror: ((e: Event) => void) | null = null;
+        port = {
+          start() {},
+          onmessage: null as ((e: MessageEvent) => void) | null,
+          postMessage() {},
+        };
+        constructor() {
+          setTimeout(() => this.onerror?.(new Event('error')), 5);
+        }
+      };
+
+      const createUploader = await loadCreateUploader();
+
+      await expect(createUploader({ ...DEFAULTS, workerMode: 'shared' })).rejects.toThrow(/worker-src/);
+    });
+  });
+
+  describe('welcome timeout', () => {
+    it('rejects when the worker never sends a welcome', async () => {
+      (globalThis as Record<string, unknown>).Worker = class {
+        onerror: ((e: Event) => void) | null = null;
+        onmessage: ((e: MessageEvent) => void) | null = null;
+        postMessage() {}
+      };
+      delete (globalThis as Record<string, unknown>).SharedWorker;
+
+      const createUploader = await loadCreateUploader();
+
+      await expect(createUploader({ ...DEFAULTS, workerMode: 'dedicated', _welcomeTimeoutMs: 50 })).rejects.toThrow(
+        /welcome timeout/,
+      );
+    });
+  });
+});

package/src/uploader/create-uploader.ts

@@ -6,10 +6,12 @@ const STORAGE_TAB_ID = 'csr:tabId';
 const STORAGE_SESSION = 'csr:session';
 const STORAGE_COUNTER = 'csr:counter';
 const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000;
+const WELCOME_TIMEOUT_MS = 10_000;
 
 interface PortLike {
   postMessage(m: unknown): void;
   setHandler(cb: (data: unknown) => void): void;
+  onError(cb: (err: Error) => void): void;
 }
 
 interface WelcomeMessage {
@@ -49,7 +51,11 @@ export async function createUploader(opts: CreateUploaderOptions): Promise<Uploa
     } counterHint=${counterHint}`,
   );
 
-  const port = await openWorkerPort(mode, opts.clientSecret, opts.workerUrl);
+  const workerName = mode === 'shared' ? await hashSecret(opts.clientSecret) : undefined;
+  const { port, urlScheme } = await openWorkerPort(mode, opts.workerUrl, workerName, log);
+  log?.(
+    `tab: worker loaded via ${urlScheme}${urlScheme === 'blob' ? ' (fallback — cross-tab sharing unavailable)' : ''}`,
+  );
 
   // State accessible to both the message handler (for post-welcome state/dead messages)
   // and the post-welcome setup code below. Mutable so welcome can populate them.
@@ -118,14 +124,36 @@ export async function createUploader(opts: CreateUploaderOptions): Promise<Uploa
   });
   log?.('tab: hello sent, awaiting welcome');
 
-  const welcome = await welcomePromise;
+  const timeoutMs = opts._welcomeTimeoutMs ?? WELCOME_TIMEOUT_MS;
+  let welcomeTimer: ReturnType<typeof setTimeout> | undefined;
+  const welcomeDeadline = new Promise<never>((_, reject) => {
+    port.onError(err => reject(err));
+    welcomeTimer = setTimeout(
+      () =>
+        reject(
+          new Error(
+            'uploader: welcome timeout. The worker did not respond within ' +
+              `${timeoutMs / 1000}s. This may indicate a CSP policy blocking ` +
+              'the worker script from loading. Check your browser console for errors.',
+          ),
+        ),
+      timeoutMs,
+    );
+  });
+  welcomeDeadline.catch(() => {});
+  const welcome = await Promise.race([
+    welcomePromise.then(msg => {
+      clearTimeout(welcomeTimer);
+      return msg;
+    }),
+    welcomeDeadline,
+  ]);
   log?.(
     welcome.type === 'welcome'
       ? `tab: welcome (${'sessionId' in welcome.result ? `sessionId=${welcome.result.sessionId}` : 'skipRecording'})`
       : `tab: dead reason=${welcome.reason}`,
   );
   if (welcome.type === 'dead') {
-    // Worker died before establishing a session — surface the reason instead of swallowing it as `null`.
     throw new Error(`uploader: ${welcome.reason}`);
   }
   if ('skipRecording' in welcome.result) {
@@ -211,44 +239,117 @@ function resolveMode(mode: 'shared' | 'dedicated' | 'auto'): 'shared' | 'dedicat
   return mode;
 }
 
+type UrlScheme = 'data' | 'blob' | 'custom';
+
+interface InternalPort extends PortLike {
+  getBufferedError(): Error | null;
+}
+
 async function openWorkerPort(
   mode: 'shared' | 'dedicated',
-  clientSecret: string,
   workerUrl: string | undefined,
-): Promise<PortLike> {
-  // Default to a content-derived data URL: identical across tabs (so SharedWorker
-  // sharing works) and self-contained (no infrastructure for SDK consumers).
-  const url = workerUrl ?? toDataUrl(workerScript);
-
-  if (mode === 'shared') {
-    const name = await hashSecret(clientSecret);
-    // `extendedLifetime` keeps the SharedWorker alive across top-level navigations on
-    // Chrome 139+. No-op everywhere else. Cast required because the option isn't in the
-    // standard SharedWorker type yet.
-    const options = {
-      name,
-      type: 'module',
-      extendedLifetime: true,
-    } as WorkerOptions;
-    const worker = new SharedWorker(url, options);
-    worker.port.start();
-    return {
-      postMessage: m => worker.port.postMessage(m),
-      setHandler: cb => {
-        worker.port.onmessage = (e: MessageEvent) => cb(e.data);
-      },
-    };
+  workerName: string | undefined,
+  log: ((msg: string) => void) | undefined,
+): Promise<{ port: PortLike; urlScheme: UrlScheme }> {
+  if (workerUrl) {
+    return { port: createWorker(mode, workerUrl, workerName), urlScheme: 'custom' };
+  }
+
+  const dataUrl = toDataUrl(workerScript);
+  try {
+    const port = createWorker(mode, dataUrl, workerName);
+    // Chrome's SharedWorker doesn't throw synchronously for CSP blocks — it fires
+    // onerror asynchronously. Yield one macrotask to let it fire, then check.
+    await new Promise(resolve => setTimeout(resolve, 0));
+    const asyncErr = port.getBufferedError();
+    if (asyncErr) throw asyncErr;
+    return { port, urlScheme: 'data' };
+  } catch (_dataErr) {
+    log?.('tab: data: worker blocked, falling back to blob: URL (dedicated mode)');
+    const blobUrl = toBlobUrl(workerScript);
+    try {
+      return { port: createDedicatedWorker(blobUrl), urlScheme: 'blob' };
+    } catch (blobErr) {
+      const hint =
+        'Your Content Security Policy blocks both `data:` and `blob:` in `worker-src`. ' +
+        'To fix this, either add `blob:` to your `worker-src` directive, or ' +
+        'use the `workerUrl` option to serve the worker script from your own origin.';
+      log?.(`tab: worker-load-failed: ${hint}`);
+      throw new Error(`worker-load-failed: ${hint}`, blobErr instanceof Error ? { cause: blobErr } : undefined);
+    }
   }
+}
+
+function createWorker(mode: 'shared' | 'dedicated', url: string, workerName: string | undefined): InternalPort {
+  if (mode === 'shared') return createSharedWorker(url, workerName!);
+  return createDedicatedWorker(url);
+}
+
+function createSharedWorker(url: string, name: string): InternalPort {
+  const options = {
+    name,
+    type: 'module',
+    extendedLifetime: true,
+  } as WorkerOptions;
+  const worker = new SharedWorker(url, options);
+  let errorCb: ((err: Error) => void) | null = null;
+  let bufferedError: Error | null = null;
 
+  worker.onerror = e => {
+    const err = workerLoadError(e, url);
+    if (errorCb) errorCb(err);
+    else bufferedError = err;
+  };
+  worker.port.start();
+  return {
+    postMessage: m => worker.port.postMessage(m),
+    setHandler: cb => {
+      worker.port.onmessage = (e: MessageEvent) => cb(e.data);
+    },
+    onError: cb => {
+      errorCb = cb;
+      if (bufferedError) cb(bufferedError);
+    },
+    getBufferedError: () => bufferedError,
+  };
+}
+
+function createDedicatedWorker(url: string): InternalPort {
   const worker = new Worker(url, { type: 'module' });
+  let errorCb: ((err: Error) => void) | null = null;
+  let bufferedError: Error | null = null;
+
+  worker.onerror = e => {
+    const err = workerLoadError(e, url);
+    if (errorCb) errorCb(err);
+    else bufferedError = err;
+  };
   return {
     postMessage: m => worker.postMessage(m),
     setHandler: cb => {
       worker.onmessage = (e: MessageEvent) => cb(e.data);
     },
+    onError: cb => {
+      errorCb = cb;
+      if (bufferedError) cb(bufferedError);
+    },
+    getBufferedError: () => bufferedError,
   };
 }
 
+function workerLoadError(cause: unknown, url: string): Error {
+  const isDataUrl = url.startsWith('data:');
+  const hint = isDataUrl
+    ? 'This is likely caused by a Content Security Policy (CSP) that blocks `data:` in ' +
+      '`worker-src`. To fix this, either add `data:` to your `worker-src` directive, or ' +
+      'use the `workerUrl` option to serve the worker script from your own origin.'
+    : `Failed to load the worker script from ${url}. Check that the URL is reachable and ` +
+      'that your CSP `worker-src` directive allows it.';
+
+  const msg = `worker-load-failed: ${hint}`;
+  return new Error(msg, cause instanceof Error ? { cause } : undefined);
+}
+
 function toDataUrl(script: string): string {
   // UTF-8-safe base64. The worker bundle is ASCII today but esbuild may emit non-ASCII
   // identifiers if the source ever contains them; this avoids `btoa` choking.
@@ -258,6 +359,10 @@ function toDataUrl(script: string): string {
   return `data:application/javascript;base64,${btoa(binary)}`;
 }
 
+function toBlobUrl(script: string): string {
+  return URL.createObjectURL(new Blob([script], { type: 'application/javascript' }));
+}
+
 async function hashSecret(secret: string): Promise<string> {
   const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(secret));
   return Array.from(new Uint8Array(buf))

package/src/uploader/types.ts

@@ -59,6 +59,8 @@ export interface CreateUploaderOptions {
    * Worker messages are forwarded over the port and tagged so you can tell them apart.
    */
   debugLogger?: (msg: string) => void;
+  /** @internal Override the welcome-handshake timeout for testing. */
+  _welcomeTimeoutMs?: number;
 }
 
 // --- Internal types: used across the worker / tab pieces, not part of the public API. ---