@neta-art/cohub 1.10.0 → 1.10.1

package/dist/debugger.d.ts

@@ -0,0 +1,198 @@
+//#region src/debugger.d.ts
+type CohubConsoleLevel = "debug" | "error" | "info" | "log" | "trace" | "warn";
+type CohubNetworkKind = "eventsource" | "fetch" | "resource" | "websocket" | "xhr";
+type CohubNetworkPhase = "abort" | "close" | "error" | "line" | "message" | "open" | "request" | "response" | "timeout";
+interface CohubDebuggerOptions {
+  enabled?: boolean;
+  maxConsoleEntries?: number;
+  maxNetworkEntries?: number;
+  maxPayloadBytes?: number;
+  maxLineBytes?: number;
+  captureHeaders?: boolean;
+  captureRequestBody?: boolean;
+  captureResponseBody?: boolean;
+  redactHeaders?: string[];
+}
+interface CohubDebuggerHandle {
+  exportLog: () => CohubDebugLogPackage;
+  exportHar: () => CohubDebugHar;
+  clear: () => void;
+  stop: () => void;
+}
+interface CohubDebugLogPackage {
+  version: 1;
+  exportedAt: string;
+  startedAt: string;
+  userAgent?: string;
+  url?: string;
+  options: Required<CohubDebuggerOptions>;
+  console: CohubConsoleEntry[];
+  network: CohubNetworkEntry[];
+  dropped: {
+    console: number;
+    network: number;
+  };
+}
+interface CohubConsoleEntry {
+  id: number;
+  at: string;
+  elapsedMs: number;
+  level: CohubConsoleLevel;
+  args: SerializedValue[];
+  stack?: string;
+}
+interface CohubNetworkEntry {
+  id: number;
+  connectionId: string;
+  at: string;
+  elapsedMs: number;
+  kind: CohubNetworkKind;
+  phase: CohubNetworkPhase;
+  method?: string;
+  url: string;
+  status?: number;
+  statusText?: string;
+  durationMs?: number;
+  requestHeaders?: Record<string, string>;
+  responseHeaders?: Record<string, string>;
+  direction?: "incoming" | "outgoing";
+  source?: "instrumentation" | "performance";
+  initiatorType?: string;
+  lineNumber?: number;
+  sizeBytes?: number;
+  truncated?: boolean;
+  eventName?: string;
+  payload?: SerializedValue | string;
+  error?: string;
+  close?: {
+    code: number;
+    reason: string;
+    wasClean: boolean;
+  };
+}
+interface CohubDebugHar {
+  log: {
+    version: "1.2";
+    creator: {
+      name: "@neta-art/cohub/debugger";
+      version: string;
+    };
+    browser?: {
+      name: string;
+      version: string;
+    };
+    pages: HarPage[];
+    entries: HarEntry[];
+    _cohub?: {
+      exportedAt: string;
+      startedAt: string;
+      dropped: {
+        console: number;
+        network: number;
+      };
+    };
+  };
+}
+interface HarPage {
+  startedDateTime: string;
+  id: string;
+  title: string;
+  pageTimings: {
+    onContentLoad: number;
+    onLoad: number;
+  };
+}
+interface HarEntry {
+  pageref: string;
+  startedDateTime: string;
+  time: number;
+  request: HarRequest;
+  response: HarResponse;
+  cache: Record<string, never>;
+  timings: HarTimings;
+  serverIPAddress: string;
+  connection: string;
+  _resourceType: string;
+  _cohubConnectionId: string;
+  _cohubKind: CohubNetworkKind;
+  _cohubSource?: "instrumentation" | "performance";
+  _cohubEntries: CohubNetworkEntry[];
+  _cohubMessages?: HarCohubMessage[];
+  _webSocketMessages?: HarWebSocketMessage[];
+}
+interface HarRequest {
+  method: string;
+  url: string;
+  httpVersion: string;
+  cookies: HarCookie[];
+  headers: HarNameValuePair[];
+  queryString: HarNameValuePair[];
+  headersSize: number;
+  bodySize: number;
+  postData?: HarPostData;
+}
+interface HarResponse {
+  status: number;
+  statusText: string;
+  httpVersion: string;
+  cookies: HarCookie[];
+  headers: HarNameValuePair[];
+  content: HarContent;
+  redirectURL: string;
+  headersSize: number;
+  bodySize: number;
+}
+interface HarNameValuePair {
+  name: string;
+  value: string;
+}
+interface HarCookie extends HarNameValuePair {
+  path?: string;
+  domain?: string;
+  expires?: string | null;
+  httpOnly?: boolean;
+  secure?: boolean;
+}
+interface HarPostData {
+  mimeType: string;
+  text: string;
+  params: HarNameValuePair[];
+}
+interface HarContent {
+  size: number;
+  mimeType: string;
+  text?: string;
+  encoding?: string;
+}
+interface HarTimings {
+  blocked: number;
+  dns: number;
+  connect: number;
+  send: number;
+  wait: number;
+  receive: number;
+  ssl: number;
+}
+interface HarCohubMessage {
+  time: string;
+  direction?: "incoming" | "outgoing";
+  lineNumber?: number;
+  eventName?: string;
+  data: string;
+}
+interface HarWebSocketMessage {
+  type: "receive" | "send";
+  time: number;
+  opcode: number;
+  data: string;
+}
+type SerializedValue = null | boolean | number | string | SerializedValue[] | {
+  [key: string]: SerializedValue;
+};
+declare function startCohubDebugger(options?: CohubDebuggerOptions): CohubDebuggerHandle;
+declare function exportCohubDebugLog(): CohubDebugLogPackage;
+declare function exportCohubDebugHar(): CohubDebugHar;
+declare function clearCohubDebugLog(): void;
+declare function stopCohubDebugger(): void;
+//#endregion
+export { CohubConsoleEntry, CohubConsoleLevel, CohubDebugHar, CohubDebugLogPackage, CohubDebuggerHandle, CohubDebuggerOptions, CohubNetworkEntry, CohubNetworkKind, CohubNetworkPhase, HarCohubMessage, HarContent, HarCookie, HarEntry, HarNameValuePair, HarPage, HarPostData, HarRequest, HarResponse, HarTimings, HarWebSocketMessage, SerializedValue, clearCohubDebugLog, exportCohubDebugHar, exportCohubDebugLog, startCohubDebugger, stopCohubDebugger };

package/dist/debugger.js

@@ -0,0 +1,1120 @@
+//#region src/debugger.ts
+const DEFAULT_OPTIONS = {
+	enabled: true,
+	maxConsoleEntries: 1e3,
+	maxNetworkEntries: 5e3,
+	maxPayloadBytes: 64 * 1024,
+	maxLineBytes: 16 * 1024,
+	captureHeaders: true,
+	captureRequestBody: true,
+	captureResponseBody: true,
+	redactHeaders: [
+		"authorization",
+		"cookie",
+		"set-cookie",
+		"x-api-key"
+	]
+};
+const consoleLevels = [
+	"debug",
+	"error",
+	"info",
+	"log",
+	"trace",
+	"warn"
+];
+const globalKey = "__cohubDebuggerState__";
+const textEncoder = new TextEncoder();
+function startCohubDebugger(options = {}) {
+	const state = getOrCreateState(options);
+	state.options = normalizeOptions({
+		...state.options,
+		...options
+	});
+	if (state.installed || !state.options.enabled) return createHandle(state);
+	installConsoleCollector(state);
+	installFetchCollector(state);
+	installXhrCollector(state);
+	installEventSourceCollector(state);
+	installWebSocketCollector(state);
+	installPerformanceCollector(state);
+	state.installed = true;
+	return createHandle(state);
+}
+function exportCohubDebugLog() {
+	return createLogPackage(getOrCreateState());
+}
+function exportCohubDebugHar() {
+	return createHarPackage(getOrCreateState());
+}
+function clearCohubDebugLog() {
+	const state = getOrCreateState();
+	state.consoleBuffer.clear();
+	state.networkBuffer.clear();
+}
+function stopCohubDebugger() {
+	const state = getExistingState();
+	if (!state?.installed) return;
+	for (const level of consoleLevels) {
+		const original = state.originals.console[level];
+		if (original) console[level] = original;
+	}
+	if (state.originals.fetch) globalThis.fetch = state.originals.fetch;
+	if (state.originals.XMLHttpRequest) globalThis.XMLHttpRequest = state.originals.XMLHttpRequest;
+	if (state.originals.xhrOpen && state.originals.xhrSend && state.originals.xhrSetRequestHeader && globalThis.XMLHttpRequest) {
+		XMLHttpRequest.prototype.open = state.originals.xhrOpen;
+		XMLHttpRequest.prototype.send = state.originals.xhrSend;
+		XMLHttpRequest.prototype.setRequestHeader = state.originals.xhrSetRequestHeader;
+	}
+	if (state.originals.EventSource) globalThis.EventSource = state.originals.EventSource;
+	if (state.originals.WebSocket) globalThis.WebSocket = state.originals.WebSocket;
+	state.originals.performanceObserver?.disconnect();
+	state.originals.performanceObserver = void 0;
+	state.installed = false;
+}
+function installConsoleCollector(state) {
+	for (const level of consoleLevels) {
+		const original = console[level]?.bind(console);
+		if (!original) continue;
+		state.originals.console[level] = original;
+		console[level] = ((...args) => {
+			appendConsole(state, level, args);
+			original(...args);
+		});
+	}
+}
+function installFetchCollector(state) {
+	if (typeof globalThis.fetch !== "function") return;
+	const originalFetch = globalThis.fetch.bind(globalThis);
+	state.originals.fetch = globalThis.fetch;
+	globalThis.fetch = (async (input, init) => {
+		const connectionId = nextConnectionId(state, "fetch");
+		const startedAtMs = Date.now();
+		const requestInfo = normalizeFetchRequest(input, init, state.options);
+		appendNetwork(state, {
+			connectionId,
+			kind: "fetch",
+			phase: "request",
+			method: requestInfo.method,
+			url: requestInfo.url,
+			requestHeaders: requestInfo.headers,
+			payload: requestInfo.body,
+			sizeBytes: requestInfo.bodySizeBytes,
+			truncated: requestInfo.bodyTruncated
+		});
+		try {
+			const response = await originalFetch(input, init);
+			const durationMs = Date.now() - startedAtMs;
+			const responseHeaders = state.options.captureHeaders ? headersToRecord(response.headers, state.options) : void 0;
+			appendNetwork(state, {
+				connectionId,
+				kind: "fetch",
+				phase: "response",
+				method: requestInfo.method,
+				url: response.url || requestInfo.url,
+				status: response.status,
+				statusText: response.statusText,
+				durationMs,
+				responseHeaders
+			});
+			collectFetchResponseBody(state, connectionId, requestInfo.method, response.url || requestInfo.url, response);
+			return response;
+		} catch (error) {
+			appendNetwork(state, {
+				connectionId,
+				kind: "fetch",
+				phase: "error",
+				method: requestInfo.method,
+				url: requestInfo.url,
+				durationMs: Date.now() - startedAtMs,
+				error: errorToString(error)
+			});
+			throw error;
+		}
+	});
+}
+function installXhrCollector(state) {
+	if (typeof globalThis.XMLHttpRequest !== "function") return;
+	const metadata = /* @__PURE__ */ new WeakMap();
+	const originalOpen = XMLHttpRequest.prototype.open;
+	const originalSend = XMLHttpRequest.prototype.send;
+	const originalSetRequestHeader = XMLHttpRequest.prototype.setRequestHeader;
+	state.originals.XMLHttpRequest = globalThis.XMLHttpRequest;
+	state.originals.xhrOpen = originalOpen;
+	state.originals.xhrSend = originalSend;
+	state.originals.xhrSetRequestHeader = originalSetRequestHeader;
+	XMLHttpRequest.prototype.open = function open(method, url, async, username, password) {
+		metadata.set(this, {
+			id: nextConnectionId(state, "xhr"),
+			method: method.toUpperCase(),
+			url: String(url),
+			requestHeaders: {},
+			responseLineCount: 0,
+			lastResponseLength: 0,
+			pendingResponseLine: ""
+		});
+		return originalOpen.call(this, method, url, async ?? true, username, password);
+	};
+	XMLHttpRequest.prototype.setRequestHeader = function setRequestHeader(name, value) {
+		const meta = metadata.get(this);
+		if (meta) meta.requestHeaders[name] = value;
+		return originalSetRequestHeader.call(this, name, value);
+	};
+	XMLHttpRequest.prototype.send = function send(body) {
+		const meta = metadata.get(this);
+		if (meta) {
+			meta.startedAtMs = Date.now();
+			const bodyPreview = state.options.captureRequestBody ? serializeBodyPreview(body, state.options) : void 0;
+			appendNetwork(state, {
+				connectionId: meta.id,
+				kind: "xhr",
+				phase: "request",
+				method: meta.method,
+				url: meta.url,
+				requestHeaders: state.options.captureHeaders ? redactHeaderRecord(meta.requestHeaders, state.options) : void 0,
+				payload: bodyPreview?.payload,
+				sizeBytes: bodyPreview?.sizeBytes,
+				truncated: bodyPreview?.truncated
+			});
+			this.addEventListener("progress", () => {
+				collectXhrResponseLines(state, this, meta);
+			});
+			this.addEventListener("readystatechange", () => {
+				collectXhrResponseLines(state, this, meta);
+			});
+			this.addEventListener("loadend", () => {
+				collectXhrResponseLines(state, this, meta, true);
+				appendNetwork(state, {
+					connectionId: meta.id,
+					kind: "xhr",
+					phase: "response",
+					method: meta.method,
+					url: meta.url,
+					status: this.status,
+					statusText: this.statusText,
+					durationMs: meta.startedAtMs ? Date.now() - meta.startedAtMs : void 0,
+					responseHeaders: state.options.captureHeaders ? parseRawHeaders(this.getAllResponseHeaders(), state.options) : void 0,
+					payload: getXhrResponsePreview(this, state.options)
+				});
+			});
+			this.addEventListener("error", () => {
+				appendNetwork(state, {
+					connectionId: meta.id,
+					kind: "xhr",
+					phase: "error",
+					method: meta.method,
+					url: meta.url,
+					durationMs: meta.startedAtMs ? Date.now() - meta.startedAtMs : void 0
+				});
+			});
+			this.addEventListener("abort", () => {
+				appendNetwork(state, {
+					connectionId: meta.id,
+					kind: "xhr",
+					phase: "abort",
+					method: meta.method,
+					url: meta.url,
+					durationMs: meta.startedAtMs ? Date.now() - meta.startedAtMs : void 0
+				});
+			});
+			this.addEventListener("timeout", () => {
+				appendNetwork(state, {
+					connectionId: meta.id,
+					kind: "xhr",
+					phase: "timeout",
+					method: meta.method,
+					url: meta.url,
+					durationMs: meta.startedAtMs ? Date.now() - meta.startedAtMs : void 0
+				});
+			});
+		}
+		return originalSend.call(this, body ?? null);
+	};
+}
+function installEventSourceCollector(state) {
+	if (typeof globalThis.EventSource !== "function") return;
+	const OriginalEventSource = globalThis.EventSource;
+	state.originals.EventSource = OriginalEventSource;
+	const InstrumentedEventSource = function EventSource(url, eventSourceInitDict) {
+		const connectionId = nextConnectionId(state, "eventsource");
+		const source = new OriginalEventSource(url, eventSourceInitDict);
+		const sourceUrl = String(url);
+		let lineNumber = 0;
+		const listenerRecords = [];
+		const appendEventSourceMessage = (eventName, event) => {
+			appendLines(state, {
+				connectionId,
+				kind: "eventsource",
+				method: "GET",
+				url: sourceUrl,
+				direction: "incoming",
+				eventName,
+				text: event.data,
+				nextLineNumber: () => {
+					lineNumber += 1;
+					return lineNumber;
+				}
+			});
+		};
+		appendNetwork(state, {
+			connectionId,
+			kind: "eventsource",
+			phase: "request",
+			method: "GET",
+			url: sourceUrl,
+			payload: eventSourceInitDict ? serializeValue(eventSourceInitDict, state.options) : void 0
+		});
+		source.addEventListener("open", () => {
+			appendNetwork(state, {
+				connectionId,
+				kind: "eventsource",
+				phase: "open",
+				method: "GET",
+				url: sourceUrl
+			});
+		});
+		source.addEventListener("message", (event) => {
+			appendEventSourceMessage("message", event);
+		});
+		source.addEventListener("error", () => {
+			appendNetwork(state, {
+				connectionId,
+				kind: "eventsource",
+				phase: "error",
+				method: "GET",
+				url: sourceUrl
+			});
+		});
+		const originalAddEventListener = source.addEventListener.bind(source);
+		const originalRemoveEventListener = source.removeEventListener.bind(source);
+		source.addEventListener = ((type, listener, options) => {
+			if (!listener) return;
+			if (type === "open" || type === "message" || type === "error") return originalAddEventListener(type, listener, options);
+			const wrappedListener = (event) => {
+				if (event instanceof MessageEvent) appendEventSourceMessage(type, event);
+				if (typeof listener === "function") return listener.call(source, event);
+				return listener.handleEvent(event);
+			};
+			listenerRecords.push({
+				type,
+				listener,
+				options,
+				wrappedListener
+			});
+			return originalAddEventListener(type, wrappedListener, options);
+		});
+		source.removeEventListener = ((type, listener, options) => {
+			if (!listener) return;
+			const recordIndex = listenerRecords.findIndex((record) => record.type === type && record.listener === listener);
+			return originalRemoveEventListener(type, (recordIndex >= 0 ? listenerRecords.splice(recordIndex, 1)[0] : void 0)?.wrappedListener ?? listener, options);
+		});
+		return source;
+	};
+	InstrumentedEventSource.prototype = OriginalEventSource.prototype;
+	Object.defineProperty(InstrumentedEventSource, "CONNECTING", { value: OriginalEventSource.CONNECTING });
+	Object.defineProperty(InstrumentedEventSource, "OPEN", { value: OriginalEventSource.OPEN });
+	Object.defineProperty(InstrumentedEventSource, "CLOSED", { value: OriginalEventSource.CLOSED });
+	globalThis.EventSource = InstrumentedEventSource;
+}
+function installWebSocketCollector(state) {
+	if (typeof globalThis.WebSocket !== "function") return;
+	const OriginalWebSocket = globalThis.WebSocket;
+	state.originals.WebSocket = OriginalWebSocket;
+	const InstrumentedWebSocket = function WebSocket(url, protocols) {
+		const connectionId = nextConnectionId(state, "websocket");
+		const socket = protocols === void 0 ? new OriginalWebSocket(url) : new OriginalWebSocket(url, protocols);
+		const socketUrl = String(url);
+		let lineNumber = 0;
+		let userOnOpen = null;
+		let userOnMessage = null;
+		let userOnError = null;
+		let userOnClose = null;
+		appendNetwork(state, {
+			connectionId,
+			kind: "websocket",
+			phase: "request",
+			method: "GET",
+			url: socketUrl,
+			payload: protocols ? serializeValue({ protocols }, state.options) : void 0
+		});
+		socket.addEventListener("open", () => {
+			appendNetwork(state, {
+				connectionId,
+				kind: "websocket",
+				phase: "open",
+				method: "GET",
+				url: socketUrl
+			});
+		});
+		socket.addEventListener("message", (event) => {
+			appendWebSocketPayload(state, {
+				connectionId,
+				url: socketUrl,
+				direction: "incoming",
+				data: event.data,
+				nextLineNumber: () => {
+					lineNumber += 1;
+					return lineNumber;
+				}
+			});
+		});
+		socket.addEventListener("error", () => {
+			appendNetwork(state, {
+				connectionId,
+				kind: "websocket",
+				phase: "error",
+				method: "GET",
+				url: socketUrl
+			});
+		});
+		socket.addEventListener("close", (event) => {
+			appendNetwork(state, {
+				connectionId,
+				kind: "websocket",
+				phase: "close",
+				method: "GET",
+				url: socketUrl,
+				close: {
+					code: event.code,
+					reason: event.reason,
+					wasClean: event.wasClean
+				}
+			});
+		});
+		Object.defineProperties(socket, {
+			onopen: {
+				configurable: true,
+				enumerable: true,
+				get: () => userOnOpen,
+				set: (handler) => {
+					userOnOpen = typeof handler === "function" ? handler : null;
+				}
+			},
+			onmessage: {
+				configurable: true,
+				enumerable: true,
+				get: () => userOnMessage,
+				set: (handler) => {
+					userOnMessage = typeof handler === "function" ? handler : null;
+				}
+			},
+			onerror: {
+				configurable: true,
+				enumerable: true,
+				get: () => userOnError,
+				set: (handler) => {
+					userOnError = typeof handler === "function" ? handler : null;
+				}
+			},
+			onclose: {
+				configurable: true,
+				enumerable: true,
+				get: () => userOnClose,
+				set: (handler) => {
+					userOnClose = typeof handler === "function" ? handler : null;
+				}
+			}
+		});
+		socket.addEventListener("open", (event) => {
+			userOnOpen?.call(socket, event);
+		});
+		socket.addEventListener("message", (event) => {
+			userOnMessage?.call(socket, event);
+		});
+		socket.addEventListener("error", (event) => {
+			userOnError?.call(socket, event);
+		});
+		socket.addEventListener("close", (event) => {
+			userOnClose?.call(socket, event);
+		});
+		const originalSend = socket.send.bind(socket);
+		socket.send = (data) => {
+			appendWebSocketPayload(state, {
+				connectionId,
+				url: socketUrl,
+				direction: "outgoing",
+				data,
+				nextLineNumber: () => {
+					lineNumber += 1;
+					return lineNumber;
+				}
+			});
+			return originalSend(data);
+		};
+		return socket;
+	};
+	InstrumentedWebSocket.prototype = OriginalWebSocket.prototype;
+	Object.defineProperty(InstrumentedWebSocket, "CONNECTING", { value: OriginalWebSocket.CONNECTING });
+	Object.defineProperty(InstrumentedWebSocket, "OPEN", { value: OriginalWebSocket.OPEN });
+	Object.defineProperty(InstrumentedWebSocket, "CLOSING", { value: OriginalWebSocket.CLOSING });
+	Object.defineProperty(InstrumentedWebSocket, "CLOSED", { value: OriginalWebSocket.CLOSED });
+	globalThis.WebSocket = InstrumentedWebSocket;
+}
+function installPerformanceCollector(state) {
+	if (typeof performance === "undefined" || typeof PerformanceObserver === "undefined") return;
+	collectPerformanceResources(state, performance.getEntriesByType("resource"));
+	const observer = new PerformanceObserver((list) => {
+		collectPerformanceResources(state, list.getEntries());
+	});
+	try {
+		observer.observe({
+			type: "resource",
+			buffered: true
+		});
+		state.originals.performanceObserver = observer;
+	} catch {
+		observer.disconnect();
+	}
+}
+function collectPerformanceResources(state, entries) {
+	for (const entry of entries) {
+		if (!(entry instanceof PerformanceResourceTiming)) continue;
+		const key = `${entry.name}:${entry.startTime}:${entry.duration}`;
+		if (state.performanceResourceKeys.has(key)) continue;
+		state.performanceResourceKeys.add(key);
+		const initiatorType = entry.initiatorType || "resource";
+		const kind = resourceKindFromInitiator(initiatorType, entry.name);
+		appendNetwork(state, {
+			connectionId: nextConnectionId(state, "resource"),
+			kind,
+			phase: "response",
+			method: "GET",
+			url: entry.name,
+			status: entry.responseStatus || void 0,
+			durationMs: Math.round(entry.duration),
+			source: "performance",
+			initiatorType,
+			sizeBytes: Math.round(entry.encodedBodySize || entry.transferSize || entry.decodedBodySize || 0),
+			payload: serializeValue({
+				startTimeMs: Math.round(entry.startTime),
+				responseEndMs: Math.round(entry.responseEnd),
+				transferSize: entry.transferSize,
+				encodedBodySize: entry.encodedBodySize,
+				decodedBodySize: entry.decodedBodySize
+			}, state.options)
+		});
+	}
+}
+function resourceKindFromInitiator(initiatorType, url) {
+	if (initiatorType === "fetch") return "fetch";
+	if (initiatorType === "xmlhttprequest") return "xhr";
+	if (initiatorType === "eventsource") return "eventsource";
+	if (initiatorType === "websocket" || url.startsWith("ws")) return "websocket";
+	return "resource";
+}
+function collectFetchResponseBody(state, connectionId, method, url, response) {
+	if (!state.options.captureResponseBody || !response.body) return;
+	const clone = response.clone();
+	if ((clone.headers.get("content-type") ?? "").includes("text/event-stream")) {
+		collectReadableStreamLines(state, {
+			connectionId,
+			kind: "fetch",
+			method,
+			url,
+			response: clone
+		});
+		return;
+	}
+	clone.text().then((text) => {
+		appendNetwork(state, {
+			connectionId,
+			kind: "fetch",
+			phase: "line",
+			method,
+			url,
+			direction: "incoming",
+			lineNumber: 1,
+			payload: truncateText(text, state.options.maxPayloadBytes),
+			sizeBytes: byteLength(text),
+			truncated: byteLength(text) > state.options.maxPayloadBytes
+		});
+	}, () => {});
+}
+async function collectReadableStreamLines(state, details) {
+	const reader = details.response.body?.getReader();
+	if (!reader) return;
+	const decoder = new TextDecoder();
+	let buffered = "";
+	let lineNumber = 0;
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			buffered += decoder.decode(value, { stream: true });
+			const parts = buffered.split(/\r?\n/);
+			buffered = parts.pop() ?? "";
+			for (const line of parts) {
+				lineNumber += 1;
+				appendLine(state, {
+					connectionId: details.connectionId,
+					kind: details.kind,
+					method: details.method,
+					url: details.url,
+					direction: "incoming",
+					lineNumber,
+					text: line
+				});
+			}
+		}
+		buffered += decoder.decode();
+		if (buffered) {
+			lineNumber += 1;
+			appendLine(state, {
+				connectionId: details.connectionId,
+				kind: details.kind,
+				method: details.method,
+				url: details.url,
+				direction: "incoming",
+				lineNumber,
+				text: buffered
+			});
+		}
+	} catch (error) {
+		appendNetwork(state, {
+			connectionId: details.connectionId,
+			kind: details.kind,
+			phase: "error",
+			method: details.method,
+			url: details.url,
+			error: errorToString(error)
+		});
+	} finally {
+		reader.releaseLock();
+	}
+}
+function collectXhrResponseLines(state, xhr, meta, flush = false) {
+	if (!state.options.captureResponseBody) return;
+	if (!(xhr.getResponseHeader("content-type") ?? "").includes("text/event-stream")) return;
+	if (xhr.responseType && xhr.responseType !== "text") return;
+	const text = xhr.responseText;
+	if (text.length <= meta.lastResponseLength) return;
+	const nextChunk = text.slice(meta.lastResponseLength);
+	meta.lastResponseLength = text.length;
+	const parts = `${meta.pendingResponseLine}${nextChunk}`.split(/\r?\n/);
+	meta.pendingResponseLine = parts.pop() ?? "";
+	for (const line of parts) {
+		if (!line) continue;
+		appendLine(state, {
+			connectionId: meta.id,
+			kind: "xhr",
+			method: meta.method,
+			url: meta.url,
+			direction: "incoming",
+			lineNumber: nextXhrLineNumber(meta),
+			text: line
+		});
+	}
+	if (flush && meta.pendingResponseLine) {
+		const line = meta.pendingResponseLine;
+		meta.pendingResponseLine = "";
+		appendLine(state, {
+			connectionId: meta.id,
+			kind: "xhr",
+			method: meta.method,
+			url: meta.url,
+			direction: "incoming",
+			lineNumber: nextXhrLineNumber(meta),
+			text: line
+		});
+	}
+}
+function appendWebSocketPayload(state, details) {
+	if (typeof details.data === "string") {
+		appendLines(state, {
+			connectionId: details.connectionId,
+			kind: "websocket",
+			method: "GET",
+			url: details.url,
+			direction: details.direction,
+			text: details.data,
+			nextLineNumber: details.nextLineNumber
+		});
+		return;
+	}
+	const payload = serializeBodyPreview(details.data, state.options) ?? { payload: null };
+	appendNetwork(state, {
+		connectionId: details.connectionId,
+		kind: "websocket",
+		phase: "message",
+		method: "GET",
+		url: details.url,
+		direction: details.direction,
+		lineNumber: details.nextLineNumber(),
+		payload: payload.payload,
+		sizeBytes: payload.sizeBytes,
+		truncated: payload.truncated
+	});
+}
+function appendLines(state, details) {
+	for (const line of details.text.split(/\r?\n/)) appendLine(state, {
+		...details,
+		lineNumber: details.nextLineNumber(),
+		text: line
+	});
+}
+function appendLine(state, details) {
+	appendNetwork(state, {
+		connectionId: details.connectionId,
+		kind: details.kind,
+		phase: "line",
+		method: details.method,
+		url: details.url,
+		direction: details.direction,
+		lineNumber: details.lineNumber,
+		eventName: details.eventName,
+		payload: truncateText(details.text, state.options.maxLineBytes),
+		sizeBytes: byteLength(details.text),
+		truncated: byteLength(details.text) > state.options.maxLineBytes
+	});
+}
+function nextXhrLineNumber(meta) {
+	meta.responseLineCount += 1;
+	return meta.responseLineCount;
+}
+function normalizeFetchRequest(input, init, options) {
+	const request = typeof Request !== "undefined" && input instanceof Request ? input : void 0;
+	const method = (init?.method ?? request?.method ?? "GET").toUpperCase();
+	const url = typeof Request !== "undefined" && input instanceof Request ? input.url : typeof URL !== "undefined" && input instanceof URL ? input.href : String(input);
+	const headers = options.captureHeaders ? mergeHeaders(request?.headers, init?.headers, options) : void 0;
+	const bodyPreview = options.captureRequestBody ? serializeBodyPreview(init?.body, options) : void 0;
+	return {
+		method,
+		url,
+		headers,
+		body: bodyPreview?.payload,
+		bodySizeBytes: bodyPreview?.sizeBytes,
+		bodyTruncated: bodyPreview?.truncated
+	};
+}
+function getXhrResponsePreview(xhr, options) {
+	if (!options.captureResponseBody) return;
+	if (xhr.responseType && xhr.responseType !== "text") return serializeValue({
+		responseType: xhr.responseType,
+		note: "Non-text XHR response body was not captured."
+	}, options);
+	return truncateText(xhr.responseText, options.maxPayloadBytes);
+}
+function serializeBodyPreview(body, options) {
+	if (body == null) return;
+	if (typeof body === "string") return {
+		payload: truncateText(body, options.maxPayloadBytes),
+		sizeBytes: byteLength(body),
+		truncated: byteLength(body) > options.maxPayloadBytes
+	};
+	if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) {
+		const text = body.toString();
+		return {
+			payload: truncateText(text, options.maxPayloadBytes),
+			sizeBytes: byteLength(text),
+			truncated: byteLength(text) > options.maxPayloadBytes
+		};
+	}
+	if (typeof Blob !== "undefined" && body instanceof Blob) return {
+		payload: {
+			type: "Blob",
+			mimeType: body.type,
+			size: body.size
+		},
+		sizeBytes: body.size,
+		truncated: body.size > options.maxPayloadBytes
+	};
+	if (typeof FormData !== "undefined" && body instanceof FormData) return { payload: serializeFormData(body, options) };
+	if (typeof ArrayBuffer !== "undefined" && body instanceof ArrayBuffer) return {
+		payload: {
+			type: "ArrayBuffer",
+			byteLength: body.byteLength
+		},
+		sizeBytes: body.byteLength,
+		truncated: body.byteLength > options.maxPayloadBytes
+	};
+	if (ArrayBuffer.isView(body)) return {
+		payload: {
+			type: body.constructor.name,
+			byteLength: body.byteLength
+		},
+		sizeBytes: body.byteLength,
+		truncated: body.byteLength > options.maxPayloadBytes
+	};
+	return { payload: serializeValue(body, options) };
+}
+function serializeFormData(formData, options) {
+	const entries = [];
+	for (const [name, value] of formData.entries()) if (typeof value === "string") entries.push({
+		name,
+		value: truncateText(value, options.maxLineBytes)
+	});
+	else entries.push({
+		name,
+		value: serializeFormDataFileValue(value)
+	});
+	return {
+		type: "FormData",
+		entries
+	};
+}
+function serializeFormDataFileValue(value) {
+	return {
+		type: typeof File !== "undefined" && value instanceof File ? "File" : "Blob",
+		fileName: "name" in value && typeof value.name === "string" ? value.name : null,
+		mimeType: value.type,
+		size: value.size
+	};
+}
+function serializeValue(value, options, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value == null) return null;
+	if (typeof value === "string") return truncateText(value, options.maxPayloadBytes);
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	if (typeof value === "bigint") return `${value.toString()}n`;
+	if (typeof value === "symbol") return value.toString();
+	if (typeof value === "function") return `[Function ${value.name || "anonymous"}]`;
+	if (value instanceof Error) return {
+		name: value.name,
+		message: value.message,
+		stack: value.stack ?? null
+	};
+	if (value instanceof Date) return value.toISOString();
+	if (value instanceof RegExp) return value.toString();
+	if (typeof Blob !== "undefined" && value instanceof Blob) return {
+		type: "Blob",
+		mimeType: value.type,
+		size: value.size
+	};
+	if (typeof Element !== "undefined" && value instanceof Element) return {
+		type: "Element",
+		tagName: value.tagName.toLowerCase(),
+		id: value.id || null,
+		className: typeof value.className === "string" ? truncateText(value.className, options.maxLineBytes) : null
+	};
+	if (typeof value !== "object") return String(value);
+	if (seen.has(value)) return "[Circular]";
+	seen.add(value);
+	if (Array.isArray(value)) return value.slice(0, 100).map((item) => serializeValue(item, options, seen));
+	const output = {};
+	let count = 0;
+	for (const key of Object.keys(value)) {
+		if (count >= 100) {
+			output.__truncatedKeys = "Only the first 100 keys were captured.";
+			break;
+		}
+		count += 1;
+		try {
+			output[key] = serializeValue(value[key], options, seen);
+		} catch (error) {
+			output[key] = `[Unserializable: ${errorToString(error)}]`;
+		}
+	}
+	return output;
+}
+function appendConsole(state, level, args) {
+	state.consoleBuffer.push({
+		id: state.nextConsoleId,
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		elapsedMs: Date.now() - state.startedAtMs,
+		level,
+		args: args.map((arg) => serializeValue(arg, state.options)),
+		stack: level === "trace" ? (/* @__PURE__ */ new Error()).stack : void 0
+	});
+	state.nextConsoleId += 1;
+}
+function appendNetwork(state, entry) {
+	state.networkBuffer.push({
+		...entry,
+		id: state.nextNetworkId,
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		elapsedMs: Date.now() - state.startedAtMs
+	});
+	state.nextNetworkId += 1;
+}
+function createHandle(state) {
+	return {
+		exportLog: () => createLogPackage(state),
+		exportHar: () => createHarPackage(state),
+		clear: () => {
+			state.consoleBuffer.clear();
+			state.networkBuffer.clear();
+		},
+		stop: stopCohubDebugger
+	};
+}
+function createLogPackage(state) {
+	return {
+		version: 1,
+		exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		startedAt: state.startedAt,
+		userAgent: typeof navigator === "undefined" ? void 0 : navigator.userAgent,
+		url: typeof location === "undefined" ? void 0 : location.href,
+		options: state.options,
+		console: state.consoleBuffer.toArray(),
+		network: state.networkBuffer.toArray(),
+		dropped: {
+			console: state.consoleBuffer.getDropped(),
+			network: state.networkBuffer.getDropped()
+		}
+	};
+}
+function createHarPackage(state) {
+	const logPackage = createLogPackage(state);
+	const pageId = "page_1";
+	const entriesByConnection = /* @__PURE__ */ new Map();
+	for (const entry of logPackage.network) {
+		const entries = entriesByConnection.get(entry.connectionId) ?? [];
+		entries.push(entry);
+		entriesByConnection.set(entry.connectionId, entries);
+	}
+	return { log: {
+		version: "1.2",
+		creator: {
+			name: "@neta-art/cohub/debugger",
+			version: "1"
+		},
+		browser: logPackage.userAgent ? {
+			name: "Chrome",
+			version: logPackage.userAgent
+		} : void 0,
+		pages: [{
+			startedDateTime: logPackage.startedAt,
+			id: pageId,
+			title: logPackage.url ?? "Cohub",
+			pageTimings: {
+				onContentLoad: -1,
+				onLoad: -1
+			}
+		}],
+		entries: [...entriesByConnection.values()].map((entries) => createHarEntry(pageId, entries)),
+		_cohub: {
+			exportedAt: logPackage.exportedAt,
+			startedAt: logPackage.startedAt,
+			dropped: logPackage.dropped
+		}
+	} };
+}
+function createHarEntry(pageId, entries) {
+	const sortedEntries = [...entries].sort((a, b) => a.id - b.id);
+	const firstEntry = sortedEntries[0];
+	if (!firstEntry) throw new Error("Cannot create a HAR entry without network entries.");
+	const requestEntry = sortedEntries.find((entry) => entry.phase === "request") ?? firstEntry;
+	const responseEntry = [...sortedEntries].reverse().find((entry) => entry.phase === "response") ?? [...sortedEntries].reverse().find((entry) => entry.phase === "close") ?? [...sortedEntries].reverse().find((entry) => entry.phase === "error") ?? requestEntry;
+	const messageEntries = sortedEntries.filter((entry) => entry.phase === "line" || entry.phase === "message");
+	const requestBodyEntry = sortedEntries.find((entry) => entry.phase === "request" && entry.payload !== void 0);
+	const responseBodyEntry = [...messageEntries].reverse().find((entry) => entry.direction === "incoming");
+	const durationMs = Math.max(responseEntry.durationMs ?? responseEntry.elapsedMs - requestEntry.elapsedMs, 0);
+	const responseText = responseEntry.kind === "websocket" ? void 0 : messageEntries.filter((entry) => entry.direction !== "outgoing").map((entry) => payloadToText(entry.payload)).filter(Boolean).join("\n");
+	return {
+		pageref: pageId,
+		startedDateTime: requestEntry.at,
+		time: durationMs,
+		request: {
+			method: requestEntry.method ?? "GET",
+			url: requestEntry.url,
+			httpVersion: "HTTP/1.1",
+			cookies: [],
+			headers: headersRecordToHarPairs(requestEntry.requestHeaders),
+			queryString: queryStringToHarPairs(requestEntry.url),
+			headersSize: -1,
+			bodySize: requestBodyEntry?.sizeBytes ?? -1,
+			postData: requestBodyEntry?.payload === void 0 ? void 0 : {
+				mimeType: guessMimeType(requestEntry.requestHeaders),
+				text: payloadToText(requestBodyEntry.payload),
+				params: []
+			}
+		},
+		response: {
+			status: responseEntry.status ?? (responseEntry.kind === "websocket" ? 101 : 0),
+			statusText: responseEntry.statusText ?? responseStatusText(responseEntry),
+			httpVersion: "HTTP/1.1",
+			cookies: [],
+			headers: headersRecordToHarPairs(responseEntry.responseHeaders),
+			content: {
+				size: responseBodyEntry?.sizeBytes ?? responseEntry.sizeBytes ?? -1,
+				mimeType: guessMimeType(responseEntry.responseHeaders),
+				text: responseText || void 0
+			},
+			redirectURL: "",
+			headersSize: -1,
+			bodySize: responseBodyEntry?.sizeBytes ?? responseEntry.sizeBytes ?? -1
+		},
+		cache: {},
+		timings: {
+			blocked: -1,
+			dns: -1,
+			connect: -1,
+			send: 0,
+			wait: durationMs,
+			receive: 0,
+			ssl: -1
+		},
+		serverIPAddress: "",
+		connection: requestEntry.connectionId,
+		_resourceType: harResourceType(firstEntry),
+		_cohubConnectionId: requestEntry.connectionId,
+		_cohubKind: firstEntry.kind,
+		_cohubSource: firstEntry.source,
+		_cohubEntries: sortedEntries,
+		_cohubMessages: createCohubMessages(messageEntries),
+		_webSocketMessages: firstEntry.kind === "websocket" ? createWebSocketMessages(messageEntries) : void 0
+	};
+}
+function headersRecordToHarPairs(headers) {
+	return Object.entries(headers ?? {}).map(([name, value]) => ({
+		name,
+		value
+	}));
+}
+function queryStringToHarPairs(url) {
+	try {
+		return [...new URL(url, "http://localhost").searchParams.entries()].map(([name, value]) => ({
+			name,
+			value
+		}));
+	} catch {
+		return [];
+	}
+}
+function createCohubMessages(entries) {
+	return entries.map((entry) => ({
+		time: entry.at,
+		direction: entry.direction,
+		lineNumber: entry.lineNumber,
+		eventName: entry.eventName,
+		data: payloadToText(entry.payload)
+	}));
+}
+function createWebSocketMessages(entries) {
+	return entries.map((entry) => ({
+		type: entry.direction === "outgoing" ? "send" : "receive",
+		time: Date.parse(entry.at) / 1e3,
+		opcode: typeof entry.payload === "string" ? 1 : 2,
+		data: payloadToText(entry.payload)
+	}));
+}
+function responseStatusText(entry) {
+	if (entry.close) return `WebSocket closed ${entry.close.code}`;
+	if (entry.error) return entry.error;
+	return entry.status ? String(entry.status) : "";
+}
+function harResourceType(entry) {
+	if (entry.kind === "websocket") return "websocket";
+	if (entry.kind === "fetch") return "fetch";
+	if (entry.kind === "xhr") return "xhr";
+	if (entry.kind === "eventsource") return "eventsource";
+	return entry.initiatorType ?? "other";
+}
+function guessMimeType(headers) {
+	return Object.entries(headers ?? {}).find(([name]) => name.toLowerCase() === "content-type")?.[1] ?? "text/plain";
+}
+function payloadToText(payload) {
+	if (payload === void 0) return "";
+	if (typeof payload === "string") return payload;
+	return JSON.stringify(payload);
+}
+function createRingBuffer(capacity) {
+	const items = [];
+	let dropped = 0;
+	return {
+		push: (entry) => {
+			if (items.length >= capacity) {
+				items.shift();
+				dropped += 1;
+			}
+			items.push(entry);
+		},
+		clear: () => {
+			items.length = 0;
+			dropped = 0;
+		},
+		toArray: () => [...items],
+		getDropped: () => dropped
+	};
+}
+function getOrCreateState(options = {}) {
+	const globalRecord = globalThis;
+	if (globalRecord[globalKey]) return globalRecord[globalKey];
+	const normalizedOptions = normalizeOptions(options);
+	const startedAtMs = Date.now();
+	const state = {
+		options: normalizedOptions,
+		startedAtMs,
+		startedAt: new Date(startedAtMs).toISOString(),
+		consoleBuffer: createRingBuffer(normalizedOptions.maxConsoleEntries),
+		networkBuffer: createRingBuffer(normalizedOptions.maxNetworkEntries),
+		performanceResourceKeys: /* @__PURE__ */ new Set(),
+		nextConsoleId: 1,
+		nextNetworkId: 1,
+		nextConnectionId: 1,
+		originals: { console: {} },
+		installed: false
+	};
+	globalRecord[globalKey] = state;
+	return state;
+}
+function getExistingState() {
+	return globalThis[globalKey];
+}
+function normalizeOptions(options) {
+	return {
+		...DEFAULT_OPTIONS,
+		...options,
+		redactHeaders: options.redactHeaders ?? DEFAULT_OPTIONS.redactHeaders
+	};
+}
+function nextConnectionId(state, kind) {
+	const id = `${kind}-${state.nextConnectionId}`;
+	state.nextConnectionId += 1;
+	return id;
+}
+function headersToRecord(headers, options) {
+	const record = {};
+	headers.forEach((value, key) => {
+		record[key] = shouldRedactHeader(key, options) ? "[redacted]" : value;
+	});
+	return record;
+}
+function mergeHeaders(base, override, options) {
+	const merged = new Headers(base);
+	if (override) new Headers(override).forEach((value, key) => {
+		merged.set(key, value);
+	});
+	return headersToRecord(merged, options);
+}
+function redactHeaderRecord(headers, options) {
+	const redacted = {};
+	for (const [key, value] of Object.entries(headers)) redacted[key] = shouldRedactHeader(key, options) ? "[redacted]" : value;
+	return redacted;
+}
+function parseRawHeaders(rawHeaders, options) {
+	const record = {};
+	for (const line of rawHeaders.trim().split(/\r?\n/)) {
+		if (!line) continue;
+		const separatorIndex = line.indexOf(":");
+		if (separatorIndex < 0) continue;
+		const key = line.slice(0, separatorIndex).trim();
+		const value = line.slice(separatorIndex + 1).trim();
+		record[key] = shouldRedactHeader(key, options) ? "[redacted]" : value;
+	}
+	return record;
+}
+function shouldRedactHeader(key, options) {
+	const normalizedKey = key.toLowerCase();
+	return options.redactHeaders.some((header) => header.toLowerCase() === normalizedKey);
+}
+function truncateText(text, maxBytes) {
+	if (byteLength(text) <= maxBytes) return text;
+	let result = "";
+	let size = 0;
+	for (const char of text) {
+		const charSize = byteLength(char);
+		if (size + charSize > maxBytes) break;
+		result += char;
+		size += charSize;
+	}
+	return `${result}\n[truncated at ${maxBytes} bytes]`;
+}
+function byteLength(text) {
+	return textEncoder.encode(text).byteLength;
+}
+function errorToString(error) {
+	if (error instanceof Error) return `${error.name}: ${error.message}`;
+	return String(error);
+}
+//#endregion
+export { clearCohubDebugLog, exportCohubDebugHar, exportCohubDebugLog, startCohubDebugger, stopCohubDebugger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub",
-  "version": "1.10.0",
+  "version": "1.10.1",
   "description": "Cohub SDK for spaces, sessions, checkpoints, and realtime agent collaboration.",
   "license": "UNLICENSED",
   "private": false,
@@ -36,6 +36,10 @@
     "./websocket": {
       "types": "./dist/websocket.d.ts",
       "import": "./dist/websocket.js"
+    },
+    "./debugger": {
+      "types": "./dist/debugger.d.ts",
+      "import": "./dist/debugger.js"
     }
   },
   "types": "./dist/index.d.ts",