refactor: resolve all 24 CRITICAL cognitive complexity issues (S3776) — 0 criticals remaining

SessionReporter.ts (57→orchestrated): 10 helper methods extracted
VisionGate.ts (54+17→all<15): BFS flood-fill + pixel computation helpers
GhostVisualizer.ts (34+32+19→all<15): heatmap grid, char patterns, thick dot
SemanticMapper.ts (32→helpers): role lookup + selector building
ActionExecutor.ts (30+18+16+16→all<15): guard clauses + early returns
PageStateCollector.ts (23+21+20+16→all<15): collection functions decomposed
FingerprintGenerator.ts (23+16→helpers): validation + weighted pick
BrowserManager.ts (19→helpers): resolve/attach/try launch helpers
InteractionReliability.ts (18→helpers): node matching extracted
AXTreeDiffer.ts (17→helpers): change detection extracted
ArtifactBuilder.ts (17→helpers): frame formatting extracted
SessionSnapshot.ts (17→helpers): storage restoration + type fix
PerceptionStack.ts (16→helpers): bug/screenshot layers
RulesEngine.ts (16→helpers): overlap/clipping detection

Fix: SessionSnapshot.ts type annotation (string[][] → Array<[string,string]>)
Bump to v4.1.0. 917/917 tests passing.

Author: AVANT-ICONIC

AGENTS.md

@@ -80,18 +80,14 @@ radar tasks                       # Show current radar tasks
 
 SonarQube dashboard (local): http://localhost:7372/dashboard?id=talox
 
-### Current Status (2026-04-15) — v4.0.2
+### Current Status (2026-04-15) — v4.1.0
 
-- **318 total issues** (318 src, 0 test blockers)
+- **~294 total issues** (all src, 0 test blockers)
 - Quality gate: **OK**
 - **0 BLOCKER** — all test assertions fixed
-- **24 CRITICAL** — cognitive complexity >15 (S3776)
-- **62 MAJOR** — code smells
-- **232 MINOR** — code smells
-- Worst complexity hotspots:
-  - `SessionReporter.ts:175` (57), `VisionGate.ts:206` (54), `GhostVisualizer.ts:240` (34)
-  - `SemanticMapper.ts:241` (32), `ActionExecutor.ts:228` (30), `GhostVisualizer.ts:361` (32)
-  - `FingerprintGenerator.ts:603` (23), `PageStateCollector.ts:417` (23)
+- **0 CRITICAL** — all cognitive complexity refactored below 15
+- **~62 MAJOR** — code smells
+- **~232 MINOR** — code smells
 
 ## Build & Test
 

CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.0] - 2026-04-15
+
+### Changed
+
+- **24 CRITICAL cognitive complexity issues resolved** (SonarQube S3776) — all functions now under complexity 15:
+  - `SessionReporter.ts` (57→orchestrated helpers): `toMarkdown()` split into 10 focused methods
+  - `VisionGate.ts` (54→9, 17→8): `mergeAdjacentRegions()` extracted to BFS flood-fill helpers, `generateDiffHeatmap()` extracted pixel computation
+  - `GhostVisualizer.ts` (34→helpers, 32→helpers, 19→helpers): heatmap grid, character patterns, thick dot rendering extracted
+  - `SemanticMapper.ts` (32→helpers): role lookup and selector building extracted
+  - `ActionExecutor.ts` (30, 18, 16, 16 → all <15): 4 functions refactored with guard clauses and early returns
+  - `PageStateCollector.ts` (23, 21, 20, 16 → all <15): 4 collection functions decomposed
+  - `FingerprintGenerator.ts` (23→helpers, 16→helpers): validation and weighted pick decomposed
+  - `BrowserManager.ts` (19→helpers): launch logic split into resolve/attach/try helpers
+  - `InteractionReliability.ts` (18→helpers): node matching extracted
+  - `AXTreeDiffer.ts` (17→helpers): change detection extracted
+  - `ArtifactBuilder.ts` (17→helpers): frame formatting extracted
+  - `SessionSnapshot.ts` (17→helpers): storage restoration extracted, type annotation fix
+  - `PerceptionStack.ts` (16→helpers): bug/screenshot layers extracted
+  - `RulesEngine.ts` (16→helpers): overlap/clipping detection extracted
+
+### Fixed
+
+- `SessionSnapshot.ts`: Fixed incorrect type annotation in `restoreStorage()` callback (`string[][]` → `Array<[string, string]>`)
+
 ## [4.0.2] - 2026-04-15
 
 ### Fixed

README.md

@@ -29,7 +29,7 @@
   <img src="https://img.shields.io/badge/Playwright-Chromium-45ba4b?style=flat-square&logo=playwright&logoColor=white" alt="Playwright" />
   <img src="https://img.shields.io/badge/Node.js-18+-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js" />
   <img src="https://img.shields.io/badge/License-AGPL--3.0--only-0d9488?style=flat-square&logo=opensourceinitiative&logoColor=white" alt="AGPL-3.0-only" />
-  <img src="https://img.shields.io/badge/version-4.0.2-0d9488?style=flat-square" alt="version" />
+  <img src="https://img.shields.io/badge/version-4.1.0-0d9488?style=flat-square" alt="version" />
 </p>
 
 <p align="center">

package.json

@@ -1,6 +1,6 @@
 {
   "name": "talox",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "Local browser runtime for agents. Persistent profiles, deep observability, structured state contracts, and resilient interaction for real-world web UIs.",
   "type": "module",
   "main": "dist/index.js",

src/core/AXTreeDiffer.ts

@@ -36,6 +36,57 @@ export class AXTreeDiffer {
 		}
 		return map;
 	}
+	private detectNodeChanges(beforeNode: TaloxNode, afterNode: TaloxNode): AXTreeChange[] {
+		const changes: AXTreeChange[] = [];
+		const beforePos = beforeNode.boundingBox;
+		const afterPos = afterNode.boundingBox;
+		const distance = this.computeDistance({ x: beforePos.x, y: beforePos.y }, { x: afterPos.x, y: afterPos.y });
+
+		if (distance > 30) {
+			const direction = this.getMovementDirection(beforePos, afterPos);
+			changes.push({
+				type: "moved",
+				nodeId: afterNode.id,
+				role: afterNode.role,
+				name: afterNode.name,
+				description: `"${afterNode.name}" moved ${direction}`,
+				previousPosition: beforePos,
+				currentPosition: afterPos,
+			});
+		}
+
+		if (beforeNode.name !== afterNode.name) {
+			changes.push({
+				type: "changed",
+				nodeId: afterNode.id,
+				role: afterNode.role,
+				name: afterNode.name,
+				description: `Text in "${afterNode.role}" changed from "${beforeNode.name}" to "${afterNode.name}"`,
+				previousValue: beforeNode.name,
+				currentValue: afterNode.name,
+			});
+		}
+
+		if (
+			beforeNode.attributes &&
+			afterNode.attributes &&
+			JSON.stringify(beforeNode.attributes) !== JSON.stringify(afterNode.attributes)
+		) {
+			const changedAttrs = this.getChangedAttributes(beforeNode.attributes, afterNode.attributes);
+			if (changedAttrs.length > 0) {
+				changes.push({
+					type: "changed",
+					nodeId: afterNode.id,
+					role: afterNode.role,
+					name: afterNode.name,
+					description: `Attributes of "${afterNode.name}" changed: ${changedAttrs.join(", ")}`,
+				});
+			}
+		}
+
+		return changes;
+	}
+
 	diff(before: TaloxPageState, after: TaloxPageState): AXTreeDiffResult {
 		const changes: AXTreeChange[] = [];
 		const beforeMap = this.getNodeMap(before.nodes);
@@ -58,52 +109,7 @@ export class AXTreeDiffer {
 			}
 
 			matchedIds.add(afterNode.id);
-
-			const beforePos = beforeNode.boundingBox;
-			const afterPos = afterNode.boundingBox;
-			const distance = this.computeDistance({ x: beforePos.x, y: beforePos.y }, { x: afterPos.x, y: afterPos.y });
-
-			if (distance > 30) {
-				const direction = this.getMovementDirection(beforePos, afterPos);
-				changes.push({
-					type: "moved",
-					nodeId: afterNode.id,
-					role: afterNode.role,
-					name: afterNode.name,
-					description: `"${afterNode.name}" moved ${direction}`,
-					previousPosition: beforePos,
-					currentPosition: afterPos,
-				});
-			}
-
-			if (beforeNode.name !== afterNode.name) {
-				changes.push({
-					type: "changed",
-					nodeId: afterNode.id,
-					role: afterNode.role,
-					name: afterNode.name,
-					description: `Text in "${afterNode.role}" changed from "${beforeNode.name}" to "${afterNode.name}"`,
-					previousValue: beforeNode.name,
-					currentValue: afterNode.name,
-				});
-			}
-
-			if (
-				beforeNode.attributes &&
-				afterNode.attributes &&
-				JSON.stringify(beforeNode.attributes) !== JSON.stringify(afterNode.attributes)
-			) {
-				const changedAttrs = this.getChangedAttributes(beforeNode.attributes, afterNode.attributes);
-				if (changedAttrs.length > 0) {
-					changes.push({
-						type: "changed",
-						nodeId: afterNode.id,
-						role: afterNode.role,
-						name: afterNode.name,
-						description: `Attributes of "${afterNode.name}" changed: ${changedAttrs.join(", ")}`,
-					});
-				}
-			}
+			changes.push(...this.detectNodeChanges(beforeNode, afterNode));
 		}
 
 		for (const beforeNode of before.nodes) {

src/core/ArtifactBuilder.ts

@@ -202,6 +202,31 @@ export class ArtifactBuilder {
 		return prettyPrint ? JSON.stringify(exportData, null, 2) : JSON.stringify(exportData);
 	}
 
+	private formatFrameDetails(frame: ActionFrame, lines: string[]): void {
+		if (Object.keys(frame.details).length > 0) {
+			lines.push("  Details:");
+			for (const [key, value] of Object.entries(frame.details)) {
+				lines.push(`    ${key}: ${JSON.stringify(value)}`);
+			}
+		}
+	}
+
+	private formatFrameVisualContext(vc: VisualContext, lines: string[]): void {
+		const posParts: string[] = [];
+		if (vc.mouseX !== undefined && vc.mouseY !== undefined) {
+			posParts.push(`Mouse: (${vc.mouseX}, ${vc.mouseY})`);
+		}
+		if (vc.viewportWidth !== undefined && vc.viewportHeight !== undefined) {
+			posParts.push(`Viewport: ${vc.viewportWidth}x${vc.viewportHeight}`);
+		}
+		if (vc.scrollPosition !== undefined) {
+			posParts.push(`Scroll: ${vc.scrollPosition}`);
+		}
+		if (posParts.length > 0) {
+			lines.push(`  Visual: ${posParts.join(" | ")}`);
+		}
+	}
+
 	exportAsText(options: ExportOptions = {}): string {
 		const { includeVisualContext = true, includePayloads = true } = options;
 		const frames = this.toActionFrames();
@@ -225,28 +250,12 @@ export class ArtifactBuilder {
 			lines.push(`[Frame ${frame.frameIndex}] ${timeStr}${durationStr} | ${frame.action}`);
 			lines.push(`  Type: ${frame.type}`);
 
-			if (includePayloads && Object.keys(frame.details).length > 0) {
-				lines.push("  Details:");
-				for (const [key, value] of Object.entries(frame.details)) {
-					lines.push(`    ${key}: ${JSON.stringify(value)}`);
-				}
+			if (includePayloads) {
+				this.formatFrameDetails(frame, lines);
 			}
 
 			if (includeVisualContext && frame.visualContext) {
-				const vc = frame.visualContext;
-				const posParts: string[] = [];
-				if (vc.mouseX !== undefined && vc.mouseY !== undefined) {
-					posParts.push(`Mouse: (${vc.mouseX}, ${vc.mouseY})`);
-				}
-				if (vc.viewportWidth !== undefined && vc.viewportHeight !== undefined) {
-					posParts.push(`Viewport: ${vc.viewportWidth}x${vc.viewportHeight}`);
-				}
-				if (vc.scrollPosition !== undefined) {
-					posParts.push(`Scroll: ${vc.scrollPosition}`);
-				}
-				if (posParts.length > 0) {
-					lines.push(`  Visual: ${posParts.join(" | ")}`);
-				}
+				this.formatFrameVisualContext(frame.visualContext, lines);
 			}
 
 			lines.push("");

src/core/BrowserManager.ts

@@ -292,41 +292,27 @@ export class BrowserManager {
 		this.config = { ...this.config, ...config };
 	}
 
-	async launch(
-		profile: TaloxProfile,
-		_headed?: boolean,
-		browserType?: BrowserType,
-		extraOptions?: any,
-	): Promise<BrowserContext> {
-		let actualBrowserType = browserType || this.config.browser.preferred;
-
-		// Skip autoDetect on macOS - just use chrome channel directly
-		if (process.platform !== "darwin") {
-			if (this.config.browser.autoDetect) {
-				actualBrowserType = await this.autoDetectBrowser();
-			}
-		}
+	private attachCloseHandler(ctx: BrowserContext): void {
+		ctx.on("close", () => {
+			this.contexts.delete(ctx);
+			if (this.context === ctx) this.context = null;
+		});
+	}
 
-		// Use Patchright for stealth mode (adaptive behavior)
-		const isAdaptive = false;
-
-		let launcher: any;
-		if (isAdaptive) {
-			// Patchright: patched Playwright driver that fixes CDP Runtime.enable leak,
-			// removes --enable-automation flag, and patches other detection vectors at
-			// the driver level — no JS injection needed for these signals.
-			// Only Chromium is supported by Patchright; other browser types fall back to standard.
-			launcher =
-				actualBrowserType === "chromium" ? patchrightChromium : ({ firefox, webkit }[actualBrowserType] ?? chromium);
-		} else {
-			launcher = {
-				chromium: chromium,
-				firefox: firefox,
-				webkit: webkit,
-			}[actualBrowserType];
+	private resolveLauncher(actualBrowserType: BrowserType, _isAdaptive: boolean): any {
+		// Patchright: patched Playwright driver that fixes CDP Runtime.enable leak,
+		// removes --enable-automation flag, and patches other detection vectors at
+		// the driver level — no JS injection needed for these signals.
+		// Only Chromium is supported by Patchright; other browser types fall back to standard.
+		if (_isAdaptive) {
+			return actualBrowserType === "chromium"
+				? patchrightChromium
+				: ({ firefox, webkit }[actualBrowserType] ?? chromium);
 		}
+		return { chromium, firefox, webkit }[actualBrowserType];
+	}
 
-		// Resolve effective headless value — extraOptions can override (e.g. observe mode forces false)
+	private buildLaunchOptions(extraOptions: any): any {
 		const effectiveHeadless =
 			extraOptions?.headless !== undefined ? extraOptions.headless : this.config.browser.headless;
 
@@ -342,37 +328,49 @@ export class BrowserManager {
 			...extraOptions,
 		};
 
-		// Proxy support
 		if (this.config.browser.proxy) {
 			launchOptions.proxy = this.config.browser.proxy;
 		}
 
+		return launchOptions;
+	}
+
+	private async tryLaunchContext(launcher: any, userDataDir: string, launchOptions: any): Promise<BrowserContext> {
+		const ctx = (await launcher.launchPersistentContext(userDataDir, launchOptions)) as BrowserContext;
+		this.contexts.add(ctx);
+		this.attachCloseHandler(ctx);
+		return ctx;
+	}
+
+	async launch(
+		profile: TaloxProfile,
+		_headed?: boolean,
+		browserType?: BrowserType,
+		extraOptions?: any,
+	): Promise<BrowserContext> {
+		let actualBrowserType = browserType || this.config.browser.preferred;
+
+		// Skip autoDetect on macOS - just use chrome channel directly
+		if (process.platform !== "darwin") {
+			if (this.config.browser.autoDetect) {
+				actualBrowserType = await this.autoDetectBrowser();
+			}
+		}
+
+		const launcher = this.resolveLauncher(actualBrowserType, false);
+		const launchOptions = this.buildLaunchOptions(extraOptions);
+
 		// Do not force chrome channel, as it conflicts if the user has Chrome open.
 		// Use Playwright's bundled Chromium instead.
 
 		try {
-			this.context = (await launcher.launchPersistentContext(profile.userDataDir, launchOptions)) as BrowserContext;
-			this.contexts.add(this.context!);
-
-			// Remove from registry when closed
-			const ctx = this.context!;
-			ctx.on("close", () => {
-				this.contexts.delete(ctx);
-				if (this.context === ctx) this.context = null;
-			});
+			this.context = await this.tryLaunchContext(launcher, profile.userDataDir, launchOptions);
 		} catch (error: any) {
 			// Fallback: try without channel if it failed
 			if (launchOptions.channel === "chrome") {
 				delete launchOptions.channel;
 				try {
-					this.context = (await launcher.launchPersistentContext(profile.userDataDir, launchOptions)) as BrowserContext;
-					this.contexts.add(this.context!);
-					// Attach close handler for fallback context too
-					const fallbackCtx = this.context!;
-					fallbackCtx.on("close", () => {
-						this.contexts.delete(fallbackCtx);
-						if (this.context === fallbackCtx) this.context = null;
-					});
+					this.context = await this.tryLaunchContext(launcher, profile.userDataDir, launchOptions);
 				} catch (fallbackError: any) {
 					console.error("[DEBUG] Playwright Headed Error:", fallbackError);
 					throw new Error(`Browser launch failed for ${actualBrowserType}. Please ensure Chrome is installed.`);