@spotify-confidence/session-recording 0.18.1 → 0.18.3

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.18.3](https://github.com/spotify/confidence-sdk-js/compare/session-recording-v0.18.2...session-recording-v0.18.3) (2026-07-06)
+
+
+### ✨ New Features
+
+* **sdk:** add assignmentOrigin to window API ([#396](https://github.com/spotify/confidence-sdk-js/issues/396)) ([9dd17d5](https://github.com/spotify/confidence-sdk-js/commit/9dd17d5f3af787e39406785f85f0d2e79703e656))
+
+
+### 📚 Documentation
+
+* **csr:** add debug logging section to README ([#395](https://github.com/spotify/confidence-sdk-js/issues/395)) ([6e6d1c3](https://github.com/spotify/confidence-sdk-js/commit/6e6d1c3c28460ef222f07fe053f2dc8d35fdc365))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @spotify-confidence/csr-common bumped to 0.18.2
+    * @spotify-confidence/csr-recorder bumped to 0.17.8
+
+## [0.18.2](https://github.com/spotify/confidence-sdk-js/compare/session-recording-v0.18.1...session-recording-v0.18.2) (2026-07-01)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @spotify-confidence/csr-common bumped to 0.18.1
+    * @spotify-confidence/csr-recorder bumped to 0.17.7
+
 ## [0.18.1](https://github.com/spotify/confidence-sdk-js/compare/session-recording-v0.18.0...session-recording-v0.18.1) (2026-07-01)
 
 

package/README.md

@@ -86,6 +86,9 @@ const recorder = initSessionRecorder({
 
   // Recording mode
   mode: 'automatic', // 'automatic' (default) or 'manual'
+
+  // Debug
+  debugLogger: msg => console.log(msg), // lifecycle/transport messages (default: off, or console.log when CSR_DEBUG is set in sessionStorage)
 });
 ```
 
@@ -112,6 +115,33 @@ const recorder = initSessionRecorder({
 
 See the [`@spotify-confidence/csr-recorder` README](../csr-recorder/README.md#route-parameterization) for the full list of default patterns.
 
+## Debug logging
+
+The SDK can emit one-line lifecycle and transport messages to help you verify your setup and diagnose issues.
+
+### Option 1: pass a logger
+
+```typescript
+const recorder = initSessionRecorder({
+  clientSecret: '<your-client-secret>',
+  debugLogger: msg => console.log(msg),
+});
+```
+
+All messages are prefixed with `[CSR]` — you can filter your browser console to quickly find them.
+
+### Option 2: sessionStorage flag
+
+If you can't (or don't want to) change code, open your browser DevTools console and run:
+
+```javascript
+sessionStorage.setItem('CSR_DEBUG', 'true');
+```
+
+Then reload the page. The SDK will detect the flag and log to `console.log` automatically. Remove it with `sessionStorage.removeItem('CSR_DEBUG')` when you're done.
+
+> **Tip:** We recommend enabling debug logging when first integrating the SDK. It lets you confirm that a session is established, events are flowing, and the backend is reachable — all before you open the Confidence dashboard.
+
 ## Manual mode
 
 Use `manual` mode to control when recording starts — useful for gating on user consent or feature flags.

package/dist/index.cjs

@@ -11179,14 +11179,16 @@ function observeFlags(onFlagWrite) {
 			_target[prop] = value;
 			onFlagWrite({
 				flagKey: prop,
-				variant: value.variant
+				variant: value.variant,
+				assignmentOrigin: value.assignmentOrigin ?? ""
 			});
 		}
 		return true;
 	} });
 	for (const [name, data] of Object.entries(existing)) if (data && typeof data.variant === "string") onFlagWrite({
 		flagKey: name,
-		variant: data.variant
+		variant: data.variant,
+		assignmentOrigin: data.assignmentOrigin ?? ""
 	});
 	return () => {
 		confidence.flags = { ...target };
@@ -13078,7 +13080,7 @@ function resolveMode(mode) {
 	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}`);\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");
+	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),
@@ -13153,7 +13155,7 @@ function writeCounter(counter) {
 }
 //#endregion
 //#region src/version.ts
-const SDK_VERSION = "0.18.1";
+const SDK_VERSION = "0.18.3";
 //#endregion
 //#region src/index.ts
 const DEFAULT_API_URL = "https://recording.confidence.dev";
@@ -13228,12 +13230,13 @@ function initSessionRecorder(options) {
 				}
 			};
 			stopRecorder = record(sendEvent, recordingConfig);
-			stopObservingFlags = observeFlags(({ flagKey, variant }) => {
+			stopObservingFlags = observeFlags(({ flagKey, variant, assignmentOrigin }) => {
 				const data = {
 					plugin: "csr:flagEvaluation",
 					payload: {
 						flagKey,
-						variant
+						variant,
+						assignmentOrigin
 					}
 				};
 				sendEvent?.({

package/dist/index.js

@@ -11160,14 +11160,16 @@ function observeFlags(onFlagWrite) {
 			_target[prop] = value;
 			onFlagWrite({
 				flagKey: prop,
-				variant: value.variant
+				variant: value.variant,
+				assignmentOrigin: value.assignmentOrigin ?? ""
 			});
 		}
 		return true;
 	} });
 	for (const [name, data] of Object.entries(existing)) if (data && typeof data.variant === "string") onFlagWrite({
 		flagKey: name,
-		variant: data.variant
+		variant: data.variant,
+		assignmentOrigin: data.assignmentOrigin ?? ""
 	});
 	return () => {
 		confidence.flags = { ...target };
@@ -13059,7 +13061,7 @@ function resolveMode(mode) {
 	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}`);\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");
+	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),
@@ -13134,7 +13136,7 @@ function writeCounter(counter) {
 }
 //#endregion
 //#region src/version.ts
-const SDK_VERSION = "0.18.1";
+const SDK_VERSION = "0.18.3";
 //#endregion
 //#region src/index.ts
 const DEFAULT_API_URL = "https://recording.confidence.dev";
@@ -13209,12 +13211,13 @@ function initSessionRecorder(options) {
 				}
 			};
 			stopRecorder = record(sendEvent, recordingConfig);
-			stopObservingFlags = observeFlags(({ flagKey, variant }) => {
+			stopObservingFlags = observeFlags(({ flagKey, variant, assignmentOrigin }) => {
 				const data = {
 					plugin: "csr:flagEvaluation",
 					payload: {
 						flagKey,
-						variant
+						variant,
+						assignmentOrigin
 					}
 				};
 				sendEvent?.({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spotify-confidence/session-recording",
   "license": "Apache-2.0",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "repository": {
     "type": "git",
     "url": "https://github.com/spotify/confidence-sdk-js.git",
@@ -35,8 +35,8 @@
     }
   },
   "dependencies": {
-    "@spotify-confidence/csr-common": "0.18.0",
-    "@spotify-confidence/csr-recorder": "0.17.6"
+    "@spotify-confidence/csr-common": "0.18.2",
+    "@spotify-confidence/csr-recorder": "0.17.8"
   },
   "module": "./dist/index.js",
   "exports": {

package/src/flag-observer.test.ts

@@ -11,62 +11,71 @@ describe('observeFlags', () => {
     const writes: FlagWrite[] = [];
     observeFlags(w => writes.push(w));
 
-    (window as any).__confidence.flags['my-flag'] = { variant: 'treatment-a' };
+    (window as any).__confidence.flags['my-flag'] = { variant: 'treatment-a', assignmentOrigin: 'rule-1' };
 
-    expect(writes).toEqual([{ flagKey: 'my-flag', variant: 'treatment-a' }]);
+    expect(writes).toEqual([{ flagKey: 'my-flag', variant: 'treatment-a', assignmentOrigin: 'rule-1' }]);
   });
 
   it('emits snapshot entries for pre-existing flags', () => {
     (window as any).__confidence = {
       flags: {
-        'flag-a': { variant: 'v1' },
-        'flag-b': { variant: 'v2' },
+        'flag-a': { variant: 'v1', assignmentOrigin: 'rule-a' },
+        'flag-b': { variant: 'v2', assignmentOrigin: 'rule-b' },
       },
     };
 
     const writes: FlagWrite[] = [];
     observeFlags(w => writes.push(w));
 
-    expect(writes).toContainEqual({ flagKey: 'flag-a', variant: 'v1' });
-    expect(writes).toContainEqual({ flagKey: 'flag-b', variant: 'v2' });
+    expect(writes).toContainEqual({ flagKey: 'flag-a', variant: 'v1', assignmentOrigin: 'rule-a' });
+    expect(writes).toContainEqual({ flagKey: 'flag-b', variant: 'v2', assignmentOrigin: 'rule-b' });
+  });
+
+  it('defaults assignmentOrigin to empty string when missing', () => {
+    const writes: FlagWrite[] = [];
+    observeFlags(w => writes.push(w));
+
+    (window as any).__confidence.flags['my-flag'] = { variant: 'treatment-a' };
+
+    expect(writes).toEqual([{ flagKey: 'my-flag', variant: 'treatment-a', assignmentOrigin: '' }]);
   });
 
   it('observes new writes after reading the snapshot', () => {
     (window as any).__confidence = {
-      flags: { existing: { variant: 'old' } },
+      flags: { existing: { variant: 'old', assignmentOrigin: 'rule-old' } },
     };
 
     const writes: FlagWrite[] = [];
     observeFlags(w => writes.push(w));
 
-    (window as any).__confidence.flags['new-flag'] = { variant: 'new' };
+    (window as any).__confidence.flags['new-flag'] = { variant: 'new', assignmentOrigin: 'rule-new' };
 
     expect(writes).toHaveLength(2);
-    expect(writes[0]).toEqual({ flagKey: 'existing', variant: 'old' });
-    expect(writes[1]).toEqual({ flagKey: 'new-flag', variant: 'new' });
+    expect(writes[0]).toEqual({ flagKey: 'existing', variant: 'old', assignmentOrigin: 'rule-old' });
+    expect(writes[1]).toEqual({ flagKey: 'new-flag', variant: 'new', assignmentOrigin: 'rule-new' });
   });
 
   it('cleanup replaces proxy with plain copy', () => {
     const writes: FlagWrite[] = [];
     const cleanup = observeFlags(w => writes.push(w));
 
-    (window as any).__confidence.flags['flag-a'] = { variant: 'v1' };
+    (window as any).__confidence.flags['flag-a'] = { variant: 'v1', assignmentOrigin: 'rule-1' };
     expect(writes).toHaveLength(1);
 
     cleanup();
 
-    (window as any).__confidence.flags['flag-b'] = { variant: 'v2' };
+    (window as any).__confidence.flags['flag-b'] = { variant: 'v2', assignmentOrigin: 'rule-2' };
     expect(writes).toHaveLength(1);
   });
 
   it('preserves data after cleanup', () => {
     observeFlags(() => {});
-    (window as any).__confidence.flags['my-flag'] = { variant: 'treatment' };
+    (window as any).__confidence.flags['my-flag'] = { variant: 'treatment', assignmentOrigin: 'rule-1' };
 
     const cleanup = observeFlags(() => {});
     cleanup();
 
-    expect((window as any).__confidence.flags['my-flag']).toEqual({ variant: 'treatment' });
+    expect((window as any).__confidence.flags['my-flag']).toEqual({ variant: 'treatment', assignmentOrigin: 'rule-1' });
   });
 
   it('ignores writes with missing variant', () => {

package/src/flag-observer.ts

@@ -1,18 +1,18 @@
-export type FlagWrite = { flagKey: string; variant: string };
+export type FlagWrite = { flagKey: string; variant: string; assignmentOrigin: string };
 export type FlagWriteCallback = (write: FlagWrite) => void;
 
 export function observeFlags(onFlagWrite: FlagWriteCallback): () => void {
   if (typeof window === 'undefined') return () => {};
 
   const confidence = ((window as any).__confidence ??= {});
-  const existing: Record<string, { variant: string }> = confidence.flags ?? {};
-  const target: Record<string, { variant: string }> = { ...existing };
+  const existing: Record<string, { variant: string; assignmentOrigin?: string }> = confidence.flags ?? {};
+  const target: Record<string, { variant: string; assignmentOrigin?: string }> = { ...existing };
 
   const proxy = new Proxy(target, {
     set(_target, prop, value) {
       if (typeof prop === 'string' && value && typeof value.variant === 'string') {
         _target[prop] = value;
-        onFlagWrite({ flagKey: prop, variant: value.variant });
+        onFlagWrite({ flagKey: prop, variant: value.variant, assignmentOrigin: value.assignmentOrigin ?? '' });
       }
       return true;
     },
@@ -22,7 +22,11 @@ export function observeFlags(onFlagWrite: FlagWriteCallback): () => void {
 
   for (const [name, data] of Object.entries(existing)) {
     if (data && typeof (data as any).variant === 'string') {
-      onFlagWrite({ flagKey: name, variant: (data as any).variant });
+      onFlagWrite({
+        flagKey: name,
+        variant: (data as any).variant,
+        assignmentOrigin: (data as any).assignmentOrigin ?? '',
+      });
     }
   }
 

package/src/index.ts

@@ -163,10 +163,10 @@ export function initSessionRecorder(options: InitSessionRecorderOptions): Sessio
 
       stopRecorder = record(sendEvent, recordingConfig);
 
-      stopObservingFlags = observeFlags(({ flagKey, variant }) => {
+      stopObservingFlags = observeFlags(({ flagKey, variant, assignmentOrigin }) => {
         const data: FlagEvaluationPluginData = {
           plugin: 'csr:flagEvaluation',
-          payload: { flagKey, variant },
+          payload: { flagKey, variant, assignmentOrigin },
         };
         sendEvent?.({
           type: RecordingEventType.Plugin,

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = '0.18.1';
+export const SDK_VERSION = '0.18.3';