@gscdump/analysis 0.37.3 → 0.37.4

package/dist/analyzer/index.mjs

@@ -5,7 +5,7 @@ import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
 import { num } from "@gscdump/engine/analysis-types";
 import { err, ok, unwrapResult } from "gscdump/result";
 import { between, date, extractDateRange, gsc, page, query } from "gscdump/query";
-import { MS_PER_DAY, daysAgo, toIsoDate } from "gscdump";
+import { MS_PER_DAY, daysAgoUtc, toIsoDate } from "gscdump/dates";
 import { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized } from "@gscdump/engine/resolver";
 function rowNumber(value) {
 	if (typeof value === "number") return Number.isFinite(value) ? value : 0;
@@ -514,13 +514,25 @@ function analyzeBrandSegmentation(keywords, options) {
 	const lowerBrandTerms = brandTerms.map((t) => t.toLowerCase());
 	const brand = [];
 	const nonBrand = [];
+	let brandClicks = 0;
+	let nonBrandClicks = 0;
+	let brandImpressions = 0;
+	let nonBrandImpressions = 0;
 	for (const row of keywords) {
-		if (num(row.impressions) < minImpressions) continue;
-		if (lowerBrandTerms.some((term) => row.query.toLowerCase().includes(term))) brand.push(row);
-		else nonBrand.push(row);
+		const impressions = num(row.impressions);
+		if (impressions < minImpressions) continue;
+		const clicks = num(row.clicks);
+		const query = row.query.toLowerCase();
+		if (lowerBrandTerms.some((term) => query.includes(term))) {
+			brand.push(row);
+			brandClicks += clicks;
+			brandImpressions += impressions;
+		} else {
+			nonBrand.push(row);
+			nonBrandClicks += clicks;
+			nonBrandImpressions += impressions;
+		}
 	}
-	const brandClicks = brand.reduce((sum, k) => sum + num(k.clicks), 0);
-	const nonBrandClicks = nonBrand.reduce((sum, k) => sum + num(k.clicks), 0);
 	const totalClicks = brandClicks + nonBrandClicks;
 	return {
 		brand,
@@ -529,8 +541,8 @@ function analyzeBrandSegmentation(keywords, options) {
 			brandClicks,
 			nonBrandClicks,
 			brandShare: totalClicks > 0 ? brandClicks / totalClicks : 0,
-			brandImpressions: brand.reduce((sum, k) => sum + num(k.impressions), 0),
-			nonBrandImpressions: nonBrand.reduce((sum, k) => sum + num(k.impressions), 0)
+			brandImpressions,
+			nonBrandImpressions
 		}
 	};
 }
@@ -679,15 +691,24 @@ function analyzeCannibalization(rows, options = {}) {
 	const results = [];
 	for (const [query, pages] of queryMap) {
 		if (pages.length < minPages) continue;
-		pages.sort((a, b) => b.clicks - a.clicks);
-		const positions = pages.map((p) => p.position);
-		const positionSpread = Math.max(...positions) - Math.min(...positions);
+		let minPosition = Number.POSITIVE_INFINITY;
+		let maxPosition = Number.NEGATIVE_INFINITY;
+		let totalClicks = 0;
+		let totalImpressions = 0;
+		for (const page of pages) {
+			minPosition = Math.min(minPosition, page.position);
+			maxPosition = Math.max(maxPosition, page.position);
+			totalClicks += page.clicks;
+			totalImpressions += page.impressions;
+		}
+		const positionSpread = maxPosition - minPosition;
 		if (positionSpread > maxPositionSpread) continue;
+		pages.sort((a, b) => b.clicks - a.clicks);
 		results.push({
 			query,
 			pages,
-			totalClicks: pages.reduce((sum, p) => sum + p.clicks, 0),
-			totalImpressions: pages.reduce((sum, p) => sum + p.impressions, 0),
+			totalClicks,
+			totalImpressions,
 			positionSpread
 		});
 	}
@@ -906,7 +927,7 @@ const changePointAnalyzer = defineAnalyzer({
 	id: "change-point",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(93);
+		const startDate = params.startDate ?? daysAgoUtc(93);
 		const minDays = 21;
 		const minSide = 7;
 		const threshold = params.threshold ?? 10;
@@ -1141,9 +1162,9 @@ function analyzeClustering(keywords, options = {}) {
 		}
 	}
 	if (clusterBy === "prefix" || clusterBy === "both") {
-		const unclustered = filtered.filter((kw) => !clusteredKeywords.has(kw.query));
 		const prefixMap = /* @__PURE__ */ new Map();
-		for (const kw of unclustered) {
+		for (const kw of filtered) {
+			if (clusteredKeywords.has(kw.query)) continue;
 			const prefix = extractWordPrefix(kw.query);
 			if (prefix) {
 				const existing = prefixMap.get(prefix);
@@ -1156,23 +1177,29 @@ function analyzeClustering(keywords, options = {}) {
 				type: "prefix",
 				keywords: kws
 			});
-			kws.forEach((kw) => clusteredKeywords.add(kw.query));
+			for (const kw of kws) clusteredKeywords.add(kw.query);
 		}
 	}
 	const clusters = [];
 	for (const [name, data] of clusterMap) {
 		if (data.keywords.length < minClusterSize) continue;
-		const totalClicks = data.keywords.reduce((sum, k) => sum + num(k.clicks), 0);
-		const totalImpressions = data.keywords.reduce((sum, k) => sum + num(k.impressions), 0);
-		const weightedPositionSum = data.keywords.reduce((sum, k) => {
-			const impressions = num(k.impressions);
-			return impressions > 0 ? sum + (num(k.position) - 1) * impressions : sum;
-		}, 0);
-		const positionWeight = data.keywords.reduce((sum, k) => {
+		let totalClicks = 0;
+		let totalImpressions = 0;
+		let weightedPositionSum = 0;
+		let positionWeight = 0;
+		let positionSum = 0;
+		for (const k of data.keywords) {
 			const impressions = num(k.impressions);
-			return impressions > 0 ? sum + impressions : sum;
-		}, 0);
-		const avgPosition = positionWeight > 0 ? weightedPositionSum / positionWeight + 1 : data.keywords.reduce((sum, k) => sum + num(k.position), 0) / data.keywords.length;
+			const position = num(k.position);
+			totalClicks += num(k.clicks);
+			totalImpressions += impressions;
+			positionSum += position;
+			if (impressions > 0) {
+				weightedPositionSum += (position - 1) * impressions;
+				positionWeight += impressions;
+			}
+		}
+		const avgPosition = positionWeight > 0 ? weightedPositionSum / positionWeight + 1 : positionSum / data.keywords.length;
 		clusters.push({
 			clusterName: name,
 			clusterType: data.type,
@@ -1295,19 +1322,6 @@ const clusteringAnalyzer = defineAnalyzer({
 		};
 	}
 });
-function calculateGini(values) {
-	if (values.length === 0) return 0;
-	const sorted = [...values].sort((a, b) => a - b);
-	const n = sorted.length;
-	const sum = sorted.reduce((a, b) => a + b, 0);
-	if (sum === 0) return 0;
-	let weightedSum = 0;
-	for (let i = 0; i < n; i++) weightedSum += (2 * (i + 1) - n - 1) * sorted[i];
-	return weightedSum / (n * sum);
-}
-function calculateHHI(shares) {
-	return shares.reduce((sum, share) => sum + (share * 100) ** 2, 0);
-}
 function analyzeConcentration(items, options = {}) {
 	const { topN = 10 } = options;
 	if (items.length === 0) return {
@@ -1320,11 +1334,18 @@ function analyzeConcentration(items, options = {}) {
 		riskLevel: "low"
 	};
 	const sorted = [...items].sort((a, b) => b.clicks - a.clicks);
-	const totalClicks = sorted.reduce((sum, item) => sum + item.clicks, 0);
-	const clickValues = sorted.map((i) => i.clicks);
-	const shares = totalClicks > 0 ? sorted.map((i) => i.clicks / totalClicks) : [];
-	const giniCoefficient = calculateGini(clickValues);
-	const hhi = calculateHHI(shares);
+	const n = sorted.length;
+	let totalClicks = 0;
+	let squaredClicks = 0;
+	let weightedSum = 0;
+	for (let i = 0; i < n; i++) {
+		const clicks = sorted[i].clicks;
+		totalClicks += clicks;
+		squaredClicks += clicks * clicks;
+		weightedSum += (n - 2 * i - 1) * clicks;
+	}
+	const giniCoefficient = totalClicks === 0 ? 0 : weightedSum / (n * totalClicks);
+	const hhi = totalClicks > 0 ? squaredClicks / (totalClicks * totalClicks) * 1e4 : 0;
 	const topNItems = sorted.slice(0, topN).map((item) => ({
 		key: item.key,
 		clicks: item.clicks,
@@ -1558,7 +1579,7 @@ const ctrAnomalyAnalyzer = defineAnalyzer({
 	id: "ctr-anomaly",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(93);
+		const startDate = params.startDate ?? daysAgoUtc(93);
 		const minDailyImpressions = params.minImpressions ?? 5;
 		const minRollingN = 14;
 		const zThreshold = params.threshold ?? 2;
@@ -2746,7 +2767,7 @@ const intentAtlasAnalyzer = defineAnalyzer({
 	id: "intent-atlas",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(90);
+		const startDate = params.startDate ?? daysAgoUtc(90);
 		const minQueryImpressions = params.minImpressions ?? 20;
 		const minClusterSize = params.minClusterSize ?? 3;
 		const minTokenImpressions = 50;
@@ -2970,22 +2991,23 @@ const keywordBreadthAnalyzer = defineAnalyzer({
 	}
 });
 function downsampleLogRank(points) {
-	const all = points.map((p) => ({
+	const toPoint = (p) => ({
 		rank: num(p.rank),
 		impressions: num(p.impressions),
 		clicks: num(p.clicks),
 		query: rowString(p.query)
-	}));
-	if (all.length <= 80) return all;
-	const top = all.slice(0, 10);
-	const rest = all.slice(10);
-	const stepped = [];
+	});
+	if (points.length <= 80) return points.map(toPoint);
+	const sampled = points.slice(0, 10).map(toPoint);
 	let nextThreshold = 1.15;
-	for (const p of rest) if (p.rank >= nextThreshold) {
-		stepped.push(p);
-		nextThreshold *= 1.15;
+	for (let i = 10; i < points.length; i++) {
+		const point = points[i];
+		if (num(point.rank) >= nextThreshold) {
+			sampled.push(toPoint(point));
+			nextThreshold *= 1.15;
+		}
 	}
-	return [...top, ...stepped];
+	return sampled;
 }
 const longTailAnalyzer = defineAnalyzer({
 	id: "long-tail",
@@ -4078,7 +4100,7 @@ const stlDecomposeAnalyzer = defineAnalyzer({
 	id: "stl-decompose",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(93);
+		const startDate = params.startDate ?? daysAgoUtc(93);
 		const minImpressions = params.minImpressions ?? 100;
 		const minDays = 21;
 		const metric = params.metric === "clicks" ? "clicks" : "impressions";
@@ -4327,7 +4349,7 @@ const survivalAnalyzer = defineAnalyzer({
 	id: "survival",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(183);
+		const startDate = params.startDate ?? daysAgoUtc(183);
 		const minImpressions = params.minImpressions ?? 5;
 		return {
 			sql: `
@@ -4472,7 +4494,7 @@ const survivalAnalyzer = defineAnalyzer({
 	reduceSql(rows, params) {
 		const arr = Array.isArray(rows) ? rows : [];
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(183);
+		const startDate = params.startDate ?? daysAgoUtc(183);
 		const windowDays = Math.round((new Date(endDate).getTime() - new Date(startDate).getTime()) / MS_PER_DAY) + 1;
 		const results = arr.map((r) => {
 			const curve = parseJsonRows(r.curveJson).map((p) => ({

package/dist/default-registry.mjs

@@ -5,7 +5,7 @@ import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
 import { num } from "@gscdump/engine/analysis-types";
 import { err, ok, unwrapResult } from "gscdump/result";
 import { between, date, extractDateRange, gsc, page, query } from "gscdump/query";
-import { MS_PER_DAY, daysAgo, toIsoDate } from "gscdump";
+import { MS_PER_DAY, daysAgoUtc, toIsoDate } from "gscdump/dates";
 import { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized } from "@gscdump/engine/resolver";
 function rowNumber(value) {
 	if (typeof value === "number") return Number.isFinite(value) ? value : 0;
@@ -514,13 +514,25 @@ function analyzeBrandSegmentation(keywords, options) {
 	const lowerBrandTerms = brandTerms.map((t) => t.toLowerCase());
 	const brand = [];
 	const nonBrand = [];
+	let brandClicks = 0;
+	let nonBrandClicks = 0;
+	let brandImpressions = 0;
+	let nonBrandImpressions = 0;
 	for (const row of keywords) {
-		if (num(row.impressions) < minImpressions) continue;
-		if (lowerBrandTerms.some((term) => row.query.toLowerCase().includes(term))) brand.push(row);
-		else nonBrand.push(row);
+		const impressions = num(row.impressions);
+		if (impressions < minImpressions) continue;
+		const clicks = num(row.clicks);
+		const query = row.query.toLowerCase();
+		if (lowerBrandTerms.some((term) => query.includes(term))) {
+			brand.push(row);
+			brandClicks += clicks;
+			brandImpressions += impressions;
+		} else {
+			nonBrand.push(row);
+			nonBrandClicks += clicks;
+			nonBrandImpressions += impressions;
+		}
 	}
-	const brandClicks = brand.reduce((sum, k) => sum + num(k.clicks), 0);
-	const nonBrandClicks = nonBrand.reduce((sum, k) => sum + num(k.clicks), 0);
 	const totalClicks = brandClicks + nonBrandClicks;
 	return {
 		brand,
@@ -529,8 +541,8 @@ function analyzeBrandSegmentation(keywords, options) {
 			brandClicks,
 			nonBrandClicks,
 			brandShare: totalClicks > 0 ? brandClicks / totalClicks : 0,
-			brandImpressions: brand.reduce((sum, k) => sum + num(k.impressions), 0),
-			nonBrandImpressions: nonBrand.reduce((sum, k) => sum + num(k.impressions), 0)
+			brandImpressions,
+			nonBrandImpressions
 		}
 	};
 }
@@ -679,15 +691,24 @@ function analyzeCannibalization(rows, options = {}) {
 	const results = [];
 	for (const [query, pages] of queryMap) {
 		if (pages.length < minPages) continue;
-		pages.sort((a, b) => b.clicks - a.clicks);
-		const positions = pages.map((p) => p.position);
-		const positionSpread = Math.max(...positions) - Math.min(...positions);
+		let minPosition = Number.POSITIVE_INFINITY;
+		let maxPosition = Number.NEGATIVE_INFINITY;
+		let totalClicks = 0;
+		let totalImpressions = 0;
+		for (const page of pages) {
+			minPosition = Math.min(minPosition, page.position);
+			maxPosition = Math.max(maxPosition, page.position);
+			totalClicks += page.clicks;
+			totalImpressions += page.impressions;
+		}
+		const positionSpread = maxPosition - minPosition;
 		if (positionSpread > maxPositionSpread) continue;
+		pages.sort((a, b) => b.clicks - a.clicks);
 		results.push({
 			query,
 			pages,
-			totalClicks: pages.reduce((sum, p) => sum + p.clicks, 0),
-			totalImpressions: pages.reduce((sum, p) => sum + p.impressions, 0),
+			totalClicks,
+			totalImpressions,
 			positionSpread
 		});
 	}
@@ -906,7 +927,7 @@ const changePointAnalyzer = defineAnalyzer({
 	id: "change-point",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(93);
+		const startDate = params.startDate ?? daysAgoUtc(93);
 		const minDays = 21;
 		const minSide = 7;
 		const threshold = params.threshold ?? 10;
@@ -1141,9 +1162,9 @@ function analyzeClustering(keywords, options = {}) {
 		}
 	}
 	if (clusterBy === "prefix" || clusterBy === "both") {
-		const unclustered = filtered.filter((kw) => !clusteredKeywords.has(kw.query));
 		const prefixMap = /* @__PURE__ */ new Map();
-		for (const kw of unclustered) {
+		for (const kw of filtered) {
+			if (clusteredKeywords.has(kw.query)) continue;
 			const prefix = extractWordPrefix(kw.query);
 			if (prefix) {
 				const existing = prefixMap.get(prefix);
@@ -1156,23 +1177,29 @@ function analyzeClustering(keywords, options = {}) {
 				type: "prefix",
 				keywords: kws
 			});
-			kws.forEach((kw) => clusteredKeywords.add(kw.query));
+			for (const kw of kws) clusteredKeywords.add(kw.query);
 		}
 	}
 	const clusters = [];
 	for (const [name, data] of clusterMap) {
 		if (data.keywords.length < minClusterSize) continue;
-		const totalClicks = data.keywords.reduce((sum, k) => sum + num(k.clicks), 0);
-		const totalImpressions = data.keywords.reduce((sum, k) => sum + num(k.impressions), 0);
-		const weightedPositionSum = data.keywords.reduce((sum, k) => {
-			const impressions = num(k.impressions);
-			return impressions > 0 ? sum + (num(k.position) - 1) * impressions : sum;
-		}, 0);
-		const positionWeight = data.keywords.reduce((sum, k) => {
+		let totalClicks = 0;
+		let totalImpressions = 0;
+		let weightedPositionSum = 0;
+		let positionWeight = 0;
+		let positionSum = 0;
+		for (const k of data.keywords) {
 			const impressions = num(k.impressions);
-			return impressions > 0 ? sum + impressions : sum;
-		}, 0);
-		const avgPosition = positionWeight > 0 ? weightedPositionSum / positionWeight + 1 : data.keywords.reduce((sum, k) => sum + num(k.position), 0) / data.keywords.length;
+			const position = num(k.position);
+			totalClicks += num(k.clicks);
+			totalImpressions += impressions;
+			positionSum += position;
+			if (impressions > 0) {
+				weightedPositionSum += (position - 1) * impressions;
+				positionWeight += impressions;
+			}
+		}
+		const avgPosition = positionWeight > 0 ? weightedPositionSum / positionWeight + 1 : positionSum / data.keywords.length;
 		clusters.push({
 			clusterName: name,
 			clusterType: data.type,
@@ -1295,19 +1322,6 @@ const clusteringAnalyzer = defineAnalyzer({
 		};
 	}
 });
-function calculateGini(values) {
-	if (values.length === 0) return 0;
-	const sorted = [...values].sort((a, b) => a - b);
-	const n = sorted.length;
-	const sum = sorted.reduce((a, b) => a + b, 0);
-	if (sum === 0) return 0;
-	let weightedSum = 0;
-	for (let i = 0; i < n; i++) weightedSum += (2 * (i + 1) - n - 1) * sorted[i];
-	return weightedSum / (n * sum);
-}
-function calculateHHI(shares) {
-	return shares.reduce((sum, share) => sum + (share * 100) ** 2, 0);
-}
 function analyzeConcentration(items, options = {}) {
 	const { topN = 10 } = options;
 	if (items.length === 0) return {
@@ -1320,11 +1334,18 @@ function analyzeConcentration(items, options = {}) {
 		riskLevel: "low"
 	};
 	const sorted = [...items].sort((a, b) => b.clicks - a.clicks);
-	const totalClicks = sorted.reduce((sum, item) => sum + item.clicks, 0);
-	const clickValues = sorted.map((i) => i.clicks);
-	const shares = totalClicks > 0 ? sorted.map((i) => i.clicks / totalClicks) : [];
-	const giniCoefficient = calculateGini(clickValues);
-	const hhi = calculateHHI(shares);
+	const n = sorted.length;
+	let totalClicks = 0;
+	let squaredClicks = 0;
+	let weightedSum = 0;
+	for (let i = 0; i < n; i++) {
+		const clicks = sorted[i].clicks;
+		totalClicks += clicks;
+		squaredClicks += clicks * clicks;
+		weightedSum += (n - 2 * i - 1) * clicks;
+	}
+	const giniCoefficient = totalClicks === 0 ? 0 : weightedSum / (n * totalClicks);
+	const hhi = totalClicks > 0 ? squaredClicks / (totalClicks * totalClicks) * 1e4 : 0;
 	const topNItems = sorted.slice(0, topN).map((item) => ({
 		key: item.key,
 		clicks: item.clicks,
@@ -1558,7 +1579,7 @@ const ctrAnomalyAnalyzer = defineAnalyzer({
 	id: "ctr-anomaly",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(93);
+		const startDate = params.startDate ?? daysAgoUtc(93);
 		const minDailyImpressions = params.minImpressions ?? 5;
 		const minRollingN = 14;
 		const zThreshold = params.threshold ?? 2;
@@ -2740,7 +2761,7 @@ const intentAtlasAnalyzer = defineAnalyzer({
 	id: "intent-atlas",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(90);
+		const startDate = params.startDate ?? daysAgoUtc(90);
 		const minQueryImpressions = params.minImpressions ?? 20;
 		const minClusterSize = params.minClusterSize ?? 3;
 		const minTokenImpressions = 50;
@@ -2964,22 +2985,23 @@ const keywordBreadthAnalyzer = defineAnalyzer({
 	}
 });
 function downsampleLogRank(points) {
-	const all = points.map((p) => ({
+	const toPoint = (p) => ({
 		rank: num(p.rank),
 		impressions: num(p.impressions),
 		clicks: num(p.clicks),
 		query: rowString(p.query)
-	}));
-	if (all.length <= 80) return all;
-	const top = all.slice(0, 10);
-	const rest = all.slice(10);
-	const stepped = [];
+	});
+	if (points.length <= 80) return points.map(toPoint);
+	const sampled = points.slice(0, 10).map(toPoint);
 	let nextThreshold = 1.15;
-	for (const p of rest) if (p.rank >= nextThreshold) {
-		stepped.push(p);
-		nextThreshold *= 1.15;
+	for (let i = 10; i < points.length; i++) {
+		const point = points[i];
+		if (num(point.rank) >= nextThreshold) {
+			sampled.push(toPoint(point));
+			nextThreshold *= 1.15;
+		}
 	}
-	return [...top, ...stepped];
+	return sampled;
 }
 const longTailAnalyzer = defineAnalyzer({
 	id: "long-tail",
@@ -4072,7 +4094,7 @@ const stlDecomposeAnalyzer = defineAnalyzer({
 	id: "stl-decompose",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(93);
+		const startDate = params.startDate ?? daysAgoUtc(93);
 		const minImpressions = params.minImpressions ?? 100;
 		const minDays = 21;
 		const metric = params.metric === "clicks" ? "clicks" : "impressions";
@@ -4321,7 +4343,7 @@ const survivalAnalyzer = defineAnalyzer({
 	id: "survival",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(183);
+		const startDate = params.startDate ?? daysAgoUtc(183);
 		const minImpressions = params.minImpressions ?? 5;
 		return {
 			sql: `
@@ -4466,7 +4488,7 @@ const survivalAnalyzer = defineAnalyzer({
 	reduceSql(rows, params) {
 		const arr = Array.isArray(rows) ? rows : [];
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(183);
+		const startDate = params.startDate ?? daysAgoUtc(183);
 		const windowDays = Math.round((new Date(endDate).getTime() - new Date(startDate).getTime()) / MS_PER_DAY) + 1;
 		const results = arr.map((r) => {
 			const curve = parseJsonRows(r.curveJson).map((p) => ({

package/dist/index.mjs

@@ -5,7 +5,7 @@ import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
 import { num, num as num$1 } from "@gscdump/engine/analysis-types";
 import { err, ok, unwrapResult } from "gscdump/result";
 import { between, date, extractDateRange, gsc, page, query } from "gscdump/query";
-import { MS_PER_DAY, daysAgo, toIsoDate } from "gscdump";
+import { MS_PER_DAY, daysAgoUtc, toIsoDate } from "gscdump/dates";
 import { buildExtrasQueries, buildTotalsSql, mergeExtras, pgResolverAdapter, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized } from "@gscdump/engine/resolver";
 import pluralize from "pluralize";
 import { ENGINE_QUERY_CAPABILITIES, createAttachedTableSource, createEngineQuerySource, queryComparisonRows, queryRows, rewriteForTableSource, runAnalyzerWithEngine, typedQuery } from "@gscdump/engine/source";
@@ -746,13 +746,25 @@ function analyzeBrandSegmentation(keywords, options) {
 	const lowerBrandTerms = brandTerms.map((t) => t.toLowerCase());
 	const brand = [];
 	const nonBrand = [];
+	let brandClicks = 0;
+	let nonBrandClicks = 0;
+	let brandImpressions = 0;
+	let nonBrandImpressions = 0;
 	for (const row of keywords) {
-		if (num$1(row.impressions) < minImpressions) continue;
-		if (lowerBrandTerms.some((term) => row.query.toLowerCase().includes(term))) brand.push(row);
-		else nonBrand.push(row);
+		const impressions = num$1(row.impressions);
+		if (impressions < minImpressions) continue;
+		const clicks = num$1(row.clicks);
+		const query = row.query.toLowerCase();
+		if (lowerBrandTerms.some((term) => query.includes(term))) {
+			brand.push(row);
+			brandClicks += clicks;
+			brandImpressions += impressions;
+		} else {
+			nonBrand.push(row);
+			nonBrandClicks += clicks;
+			nonBrandImpressions += impressions;
+		}
 	}
-	const brandClicks = brand.reduce((sum, k) => sum + num$1(k.clicks), 0);
-	const nonBrandClicks = nonBrand.reduce((sum, k) => sum + num$1(k.clicks), 0);
 	const totalClicks = brandClicks + nonBrandClicks;
 	return {
 		brand,
@@ -761,8 +773,8 @@ function analyzeBrandSegmentation(keywords, options) {
 			brandClicks,
 			nonBrandClicks,
 			brandShare: totalClicks > 0 ? brandClicks / totalClicks : 0,
-			brandImpressions: brand.reduce((sum, k) => sum + num$1(k.impressions), 0),
-			nonBrandImpressions: nonBrand.reduce((sum, k) => sum + num$1(k.impressions), 0)
+			brandImpressions,
+			nonBrandImpressions
 		}
 	};
 }
@@ -911,15 +923,24 @@ function analyzeCannibalization(rows, options = {}) {
 	const results = [];
 	for (const [query, pages] of queryMap) {
 		if (pages.length < minPages) continue;
-		pages.sort((a, b) => b.clicks - a.clicks);
-		const positions = pages.map((p) => p.position);
-		const positionSpread = Math.max(...positions) - Math.min(...positions);
+		let minPosition = Number.POSITIVE_INFINITY;
+		let maxPosition = Number.NEGATIVE_INFINITY;
+		let totalClicks = 0;
+		let totalImpressions = 0;
+		for (const page of pages) {
+			minPosition = Math.min(minPosition, page.position);
+			maxPosition = Math.max(maxPosition, page.position);
+			totalClicks += page.clicks;
+			totalImpressions += page.impressions;
+		}
+		const positionSpread = maxPosition - minPosition;
 		if (positionSpread > maxPositionSpread) continue;
+		pages.sort((a, b) => b.clicks - a.clicks);
 		results.push({
 			query,
 			pages,
-			totalClicks: pages.reduce((sum, p) => sum + p.clicks, 0),
-			totalImpressions: pages.reduce((sum, p) => sum + p.impressions, 0),
+			totalClicks,
+			totalImpressions,
 			positionSpread
 		});
 	}
@@ -1138,7 +1159,7 @@ const changePointAnalyzer = defineAnalyzer$1({
 	id: "change-point",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(93);
+		const startDate = params.startDate ?? daysAgoUtc(93);
 		const minDays = 21;
 		const minSide = 7;
 		const threshold = params.threshold ?? 10;
@@ -1373,9 +1394,9 @@ function analyzeClustering(keywords, options = {}) {
 		}
 	}
 	if (clusterBy === "prefix" || clusterBy === "both") {
-		const unclustered = filtered.filter((kw) => !clusteredKeywords.has(kw.query));
 		const prefixMap = /* @__PURE__ */ new Map();
-		for (const kw of unclustered) {
+		for (const kw of filtered) {
+			if (clusteredKeywords.has(kw.query)) continue;
 			const prefix = extractWordPrefix(kw.query);
 			if (prefix) {
 				const existing = prefixMap.get(prefix);
@@ -1388,23 +1409,29 @@ function analyzeClustering(keywords, options = {}) {
 				type: "prefix",
 				keywords: kws
 			});
-			kws.forEach((kw) => clusteredKeywords.add(kw.query));
+			for (const kw of kws) clusteredKeywords.add(kw.query);
 		}
 	}
 	const clusters = [];
 	for (const [name, data] of clusterMap) {
 		if (data.keywords.length < minClusterSize) continue;
-		const totalClicks = data.keywords.reduce((sum, k) => sum + num$1(k.clicks), 0);
-		const totalImpressions = data.keywords.reduce((sum, k) => sum + num$1(k.impressions), 0);
-		const weightedPositionSum = data.keywords.reduce((sum, k) => {
-			const impressions = num$1(k.impressions);
-			return impressions > 0 ? sum + (num$1(k.position) - 1) * impressions : sum;
-		}, 0);
-		const positionWeight = data.keywords.reduce((sum, k) => {
+		let totalClicks = 0;
+		let totalImpressions = 0;
+		let weightedPositionSum = 0;
+		let positionWeight = 0;
+		let positionSum = 0;
+		for (const k of data.keywords) {
 			const impressions = num$1(k.impressions);
-			return impressions > 0 ? sum + impressions : sum;
-		}, 0);
-		const avgPosition = positionWeight > 0 ? weightedPositionSum / positionWeight + 1 : data.keywords.reduce((sum, k) => sum + num$1(k.position), 0) / data.keywords.length;
+			const position = num$1(k.position);
+			totalClicks += num$1(k.clicks);
+			totalImpressions += impressions;
+			positionSum += position;
+			if (impressions > 0) {
+				weightedPositionSum += (position - 1) * impressions;
+				positionWeight += impressions;
+			}
+		}
+		const avgPosition = positionWeight > 0 ? weightedPositionSum / positionWeight + 1 : positionSum / data.keywords.length;
 		clusters.push({
 			clusterName: name,
 			clusterType: data.type,
@@ -1527,19 +1554,6 @@ const clusteringAnalyzer = defineAnalyzer$1({
 		};
 	}
 });
-function calculateGini(values) {
-	if (values.length === 0) return 0;
-	const sorted = [...values].sort((a, b) => a - b);
-	const n = sorted.length;
-	const sum = sorted.reduce((a, b) => a + b, 0);
-	if (sum === 0) return 0;
-	let weightedSum = 0;
-	for (let i = 0; i < n; i++) weightedSum += (2 * (i + 1) - n - 1) * sorted[i];
-	return weightedSum / (n * sum);
-}
-function calculateHHI(shares) {
-	return shares.reduce((sum, share) => sum + (share * 100) ** 2, 0);
-}
 function analyzeConcentration(items, options = {}) {
 	const { topN = 10 } = options;
 	if (items.length === 0) return {
@@ -1552,11 +1566,18 @@ function analyzeConcentration(items, options = {}) {
 		riskLevel: "low"
 	};
 	const sorted = [...items].sort((a, b) => b.clicks - a.clicks);
-	const totalClicks = sorted.reduce((sum, item) => sum + item.clicks, 0);
-	const clickValues = sorted.map((i) => i.clicks);
-	const shares = totalClicks > 0 ? sorted.map((i) => i.clicks / totalClicks) : [];
-	const giniCoefficient = calculateGini(clickValues);
-	const hhi = calculateHHI(shares);
+	const n = sorted.length;
+	let totalClicks = 0;
+	let squaredClicks = 0;
+	let weightedSum = 0;
+	for (let i = 0; i < n; i++) {
+		const clicks = sorted[i].clicks;
+		totalClicks += clicks;
+		squaredClicks += clicks * clicks;
+		weightedSum += (n - 2 * i - 1) * clicks;
+	}
+	const giniCoefficient = totalClicks === 0 ? 0 : weightedSum / (n * totalClicks);
+	const hhi = totalClicks > 0 ? squaredClicks / (totalClicks * totalClicks) * 1e4 : 0;
 	const topNItems = sorted.slice(0, topN).map((item) => ({
 		key: item.key,
 		clicks: item.clicks,
@@ -1790,7 +1811,7 @@ const ctrAnomalyAnalyzer = defineAnalyzer$1({
 	id: "ctr-anomaly",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(93);
+		const startDate = params.startDate ?? daysAgoUtc(93);
 		const minDailyImpressions = params.minImpressions ?? 5;
 		const minRollingN = 14;
 		const zThreshold = params.threshold ?? 2;
@@ -3304,7 +3325,7 @@ const intentAtlasAnalyzer = defineAnalyzer$1({
 	id: "intent-atlas",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(90);
+		const startDate = params.startDate ?? daysAgoUtc(90);
 		const minQueryImpressions = params.minImpressions ?? 20;
 		const minClusterSize = params.minClusterSize ?? 3;
 		const minTokenImpressions = 50;
@@ -3528,22 +3549,23 @@ const keywordBreadthAnalyzer = defineAnalyzer$1({
 	}
 });
 function downsampleLogRank(points) {
-	const all = points.map((p) => ({
+	const toPoint = (p) => ({
 		rank: num$1(p.rank),
 		impressions: num$1(p.impressions),
 		clicks: num$1(p.clicks),
 		query: rowString(p.query)
-	}));
-	if (all.length <= 80) return all;
-	const top = all.slice(0, 10);
-	const rest = all.slice(10);
-	const stepped = [];
+	});
+	if (points.length <= 80) return points.map(toPoint);
+	const sampled = points.slice(0, 10).map(toPoint);
 	let nextThreshold = 1.15;
-	for (const p of rest) if (p.rank >= nextThreshold) {
-		stepped.push(p);
-		nextThreshold *= 1.15;
+	for (let i = 10; i < points.length; i++) {
+		const point = points[i];
+		if (num$1(point.rank) >= nextThreshold) {
+			sampled.push(toPoint(point));
+			nextThreshold *= 1.15;
+		}
 	}
-	return [...top, ...stepped];
+	return sampled;
 }
 const longTailAnalyzer = defineAnalyzer$1({
 	id: "long-tail",
@@ -4632,7 +4654,7 @@ const stlDecomposeAnalyzer = defineAnalyzer$1({
 	id: "stl-decompose",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(93);
+		const startDate = params.startDate ?? daysAgoUtc(93);
 		const minImpressions = params.minImpressions ?? 100;
 		const minDays = 21;
 		const metric = params.metric === "clicks" ? "clicks" : "impressions";
@@ -4881,7 +4903,7 @@ const survivalAnalyzer = defineAnalyzer$1({
 	id: "survival",
 	buildSql(params) {
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(183);
+		const startDate = params.startDate ?? daysAgoUtc(183);
 		const minImpressions = params.minImpressions ?? 5;
 		return {
 			sql: `
@@ -5026,7 +5048,7 @@ const survivalAnalyzer = defineAnalyzer$1({
 	reduceSql(rows, params) {
 		const arr = Array.isArray(rows) ? rows : [];
 		const endDate = params.endDate ?? defaultEndDate();
-		const startDate = params.startDate ?? daysAgo(183);
+		const startDate = params.startDate ?? daysAgoUtc(183);
 		const windowDays = Math.round((new Date(endDate).getTime() - new Date(startDate).getTime()) / MS_PER_DAY) + 1;
 		const results = arr.map((r) => {
 			const curve = parseJsonRows(r.curveJson).map((p) => ({

package/dist/semantic/index.d.mts

@@ -1,4 +1,30 @@
-import { AnalysisQuerySource } from "@gscdump/engine/source";
+import { AnalysisQuerySource, QueryRow } from "@gscdump/engine/source";
+type ContentGapDevice = 'webgpu' | 'wasm';
+type ContentGapEmbeddingRole = 'query' | 'passage';
+type ContentGapExtractor = (texts: string[], opts: {
+  pooling: 'mean';
+  normalize: boolean;
+}) => Promise<{
+  data: Float32Array;
+  dims: number[];
+}>;
+interface EmbeddedContentGapTexts {
+  vectors: Float32Array[];
+  hits: number;
+  misses: number;
+}
+interface ContentGapEmbeddingCache {
+  getMany: (role: ContentGapEmbeddingRole, texts: string[]) => Promise<Map<string, Float32Array>>;
+  putMany: (role: ContentGapEmbeddingRole, entries: Array<[string, Float32Array]>) => Promise<void>;
+}
+declare function createMemoryContentGapCache(): ContentGapEmbeddingCache;
+interface ContentGapEmbeddingRuntime {
+  modelId: string;
+  queryPrefix: string;
+  selectDevice: (requested?: ContentGapDevice) => Promise<ContentGapDevice>;
+  loadExtractor: (device: ContentGapDevice) => Promise<ContentGapExtractor>;
+  embed: (extractor: ContentGapExtractor, role: ContentGapEmbeddingRole, texts: string[], transform: (text: string) => string, onProgress: (done: number, total: number) => void) => Promise<EmbeddedContentGapTexts>;
+}
 interface ContentGapQueryCandidate {
   query: string;
   impressions: number;
@@ -6,6 +32,18 @@ interface ContentGapQueryCandidate {
   avgPosition: number;
   currentUrl: string;
 }
+interface ContentGapInputOptions {
+  maxQueries: number;
+  maxUrls: number;
+  minImpressions: number;
+}
+type ExecuteSql = (sql: string, params?: unknown[]) => Promise<QueryRow[]>;
+type NormalizeUrl = (url: string) => string;
+declare function fetchContentGapInputs(executeSql: ExecuteSql, options: ContentGapInputOptions, normalizeUrl: NormalizeUrl, now?: () => number): Promise<{
+  queries: ContentGapQueryCandidate[];
+  urls: string[];
+  sqlMs: number;
+}>;
 interface ContentGapResult {
   query: string;
   impressions: number;
@@ -62,9 +100,18 @@ interface ContentGapAnalysis {
     modelId: string;
   };
 }
+interface ContentGapAnalyzer {
+  analyze: (source: AnalysisQuerySource, opts?: ContentGapOptions) => Promise<ContentGapAnalysis>;
+}
+interface CreateContentGapAnalyzerOptions {
+  embeddings?: ContentGapEmbeddingRuntime;
+  loadInputs?: typeof fetchContentGapInputs;
+  now?: () => number;
+}
 declare function normalizeUrl(u: string): string;
 declare function deriveUrlText(url: string): string;
 declare function cosineNormalized(a: Float32Array, b: Float32Array): number;
 declare function rankContentGaps(queries: ContentGapQueryCandidate[], urls: string[], queryEmbeddings: Float32Array[], urlEmbeddings: Float32Array[], minDivergence: number): ContentGapResult[];
+declare function createContentGapAnalyzer(opts?: CreateContentGapAnalyzerOptions): ContentGapAnalyzer;
 declare function analyzeContentGap(source: AnalysisQuerySource, opts?: ContentGapOptions): Promise<ContentGapAnalysis>;
-export { type ContentGapAnalysis, type ContentGapOptions, type ContentGapProgress, type ContentGapResult, ContentGapSourceUnsupportedError, analyzeContentGap, cosineNormalized, deriveUrlText, normalizeUrl, rankContentGaps };
+export { type ContentGapAnalysis, type ContentGapAnalyzer, type ContentGapEmbeddingCache, type ContentGapEmbeddingRuntime, type ContentGapOptions, type ContentGapProgress, type ContentGapResult, ContentGapSourceUnsupportedError, type CreateContentGapAnalyzerOptions, analyzeContentGap, cosineNormalized, createContentGapAnalyzer, createMemoryContentGapCache, deriveUrlText, normalizeUrl, rankContentGaps };

package/dist/semantic/index.mjs

@@ -2,59 +2,78 @@ const CONTENT_GAP_MODEL_ID = "Xenova/bge-base-en-v1.5";
 const CONTENT_GAP_QUERY_PREFIX = "Represent this sentence for searching relevant passages: ";
 const DB_NAME = "content-gap-embeddings";
 const STORE = "vectors";
-let dbPromise = null;
-function openDb() {
-	if (dbPromise != null) return dbPromise;
-	dbPromise = new Promise((resolve, reject) => {
-		const req = indexedDB.open(DB_NAME, 1);
-		req.onupgradeneeded = () => {
-			const db = req.result;
-			if (!db.objectStoreNames.contains(STORE)) db.createObjectStore(STORE);
-		};
-		req.onsuccess = () => resolve(req.result);
-		req.onerror = () => reject(req.error ?? /* @__PURE__ */ new Error("indexedDB open failed"));
-	});
-	return dbPromise;
-}
 function cacheKey(role, text) {
 	return `${CONTENT_GAP_MODEL_ID}|${role}|${text}`;
 }
-async function cacheGetMany(role, texts) {
-	const db = await openDb().catch(() => null);
-	if (db == null) return /* @__PURE__ */ new Map();
-	return new Promise((resolve) => {
-		const store = db.transaction(STORE, "readonly").objectStore(STORE);
-		const out = /* @__PURE__ */ new Map();
-		let pending = texts.length;
-		if (pending === 0) {
-			resolve(out);
-			return;
-		}
-		for (const t of texts) {
-			const req = store.get(cacheKey(role, t));
-			req.onsuccess = () => {
-				const v = req.result;
-				if (v instanceof Float32Array) out.set(t, v);
-				pending -= 1;
-				if (pending === 0) resolve(out);
-			};
-			req.onerror = () => {
-				pending -= 1;
-				if (pending === 0) resolve(out);
+function createIndexedDbContentGapCache() {
+	let dbPromise = null;
+	function openDb() {
+		if (dbPromise != null) return dbPromise;
+		dbPromise = new Promise((resolve, reject) => {
+			const req = indexedDB.open(DB_NAME, 1);
+			req.onupgradeneeded = () => {
+				const db = req.result;
+				if (!db.objectStoreNames.contains(STORE)) db.createObjectStore(STORE);
 			};
+			req.onsuccess = () => resolve(req.result);
+			req.onerror = () => reject(req.error ?? /* @__PURE__ */ new Error("indexedDB open failed"));
+		});
+		return dbPromise;
+	}
+	return {
+		async getMany(role, texts) {
+			const db = await openDb().catch(() => null);
+			if (db == null) return /* @__PURE__ */ new Map();
+			return new Promise((resolve) => {
+				const store = db.transaction(STORE, "readonly").objectStore(STORE);
+				const out = /* @__PURE__ */ new Map();
+				let pending = texts.length;
+				if (pending === 0) {
+					resolve(out);
+					return;
+				}
+				for (const text of texts) {
+					const req = store.get(cacheKey(role, text));
+					req.onsuccess = () => {
+						if (req.result instanceof Float32Array) out.set(text, req.result);
+						pending -= 1;
+						if (pending === 0) resolve(out);
+					};
+					req.onerror = () => {
+						pending -= 1;
+						if (pending === 0) resolve(out);
+					};
+				}
+			});
+		},
+		async putMany(role, entries) {
+			const db = await openDb().catch(() => null);
+			if (db == null) return;
+			await new Promise((resolve) => {
+				const tx = db.transaction(STORE, "readwrite");
+				for (const [text, vector] of entries) tx.objectStore(STORE).put(vector, cacheKey(role, text));
+				tx.oncomplete = () => resolve();
+				tx.onerror = () => resolve();
+				tx.onabort = () => resolve();
+			});
 		}
-	});
+	};
 }
-async function cachePutMany(role, entries) {
-	const db = await openDb().catch(() => null);
-	if (db == null) return;
-	await new Promise((resolve) => {
-		const tx = db.transaction(STORE, "readwrite");
-		for (const [text, vec] of entries) tx.objectStore(STORE).put(vec, cacheKey(role, text));
-		tx.oncomplete = () => resolve();
-		tx.onerror = () => resolve();
-		tx.onabort = () => resolve();
-	});
+function createMemoryContentGapCache() {
+	const values = /* @__PURE__ */ new Map();
+	return {
+		async getMany(role, texts) {
+			const out = /* @__PURE__ */ new Map();
+			for (const text of texts) {
+				const value = values.get(cacheKey(role, text));
+				if (value) out.set(text, value);
+			}
+			return out;
+		},
+		async putMany(role, entries) {
+			for (const [text, vector] of entries) values.set(cacheKey(role, text), vector);
+		}
+	};
 }
 async function embedRawBatch(extractor, texts, onProgress, batchSize = 32) {
 	const result = [];
@@ -91,8 +110,8 @@ async function loadContentGapExtractor(device) {
 		dtype: "fp32"
 	});
 }
-async function embedContentGapTexts(extractor, role, texts, transform, onProgress) {
-	const cached = await cacheGetMany(role, texts);
+async function embedContentGapTexts(extractor, role, texts, transform, onProgress, cache) {
+	const cached = await cache.getMany(role, texts);
 	const vectors = Array.from({ length: texts.length });
 	const missIdx = [];
 	const missTexts = [];
@@ -117,7 +136,7 @@ async function embedContentGapTexts(extractor, role, texts, transform, onProgres
 			vectors[i] = embedded[m];
 			toPersist.push([texts[i], embedded[m]]);
 		}
-		await cachePutMany(role, toPersist);
+		await cache.putMany(role, toPersist);
 	}
 	return {
 		vectors,
@@ -125,8 +144,19 @@ async function embedContentGapTexts(extractor, role, texts, transform, onProgres
 		misses
 	};
 }
-async function fetchContentGapInputs(executeSql, options, normalizeUrl) {
-	const t1 = performance.now();
+function createContentGapEmbeddingRuntime(cache = createIndexedDbContentGapCache()) {
+	return {
+		modelId: CONTENT_GAP_MODEL_ID,
+		queryPrefix: CONTENT_GAP_QUERY_PREFIX,
+		selectDevice: selectContentGapDevice,
+		loadExtractor: loadContentGapExtractor,
+		embed(extractor, role, texts, transform, onProgress) {
+			return embedContentGapTexts(extractor, role, texts, transform, onProgress, cache);
+		}
+	};
+}
+async function fetchContentGapInputs(executeSql, options, normalizeUrl, now = () => performance.now()) {
+	const t1 = now();
 	const queryRows = await executeSql(`
     WITH query_totals AS (
       SELECT query,
@@ -164,7 +194,7 @@ async function fetchContentGapInputs(executeSql, options, normalizeUrl) {
     ORDER BY impressions DESC
     LIMIT ?
   `, [Number(options.maxUrls)]);
-	const sqlMs = performance.now() - t1;
+	const sqlMs = now() - t1;
 	const queries = queryRows.map((row) => ({
 		query: String(row.query),
 		impressions: Number(row.impressions),
@@ -237,15 +267,25 @@ function rankContentGaps(queries, urls, queryEmbeddings, urlEmbeddings, minDiver
 		const qr = queries[i];
 		const qEmb = queryEmbeddings[i];
 		const currentIdx = urlIndex.get(qr.currentUrl);
-		const scored = Array.from({ length: urls.length });
-		for (let j = 0; j < urls.length; j++) scored[j] = {
-			url: urls[j],
-			similarity: cosineNormalized(qEmb, urlEmbeddings[j])
-		};
-		scored.sort((a, b) => b.similarity - a.similarity);
-		const currentSimilarity = currentIdx != null ? cosineNormalized(qEmb, urlEmbeddings[currentIdx]) : 0;
-		const suggestedUrl = scored[0].url;
-		const suggestedSimilarity = scored[0].similarity;
+		const top = [];
+		let currentSimilarity = 0;
+		for (let j = 0; j < urls.length; j++) {
+			const similarity = cosineNormalized(qEmb, urlEmbeddings[j]);
+			if (j === currentIdx) currentSimilarity = similarity;
+			let insertAt = top.length;
+			while (insertAt > 0 && similarity > top[insertAt - 1].similarity) insertAt--;
+			if (insertAt < 4) {
+				top.splice(insertAt, 0, {
+					url: urls[j],
+					similarity
+				});
+				if (top.length > 4) top.pop();
+			}
+		}
+		const suggested = top[0];
+		if (!suggested) continue;
+		const suggestedUrl = suggested.url;
+		const suggestedSimilarity = suggested.similarity;
 		if (suggestedUrl === qr.currentUrl) continue;
 		const divergence = suggestedSimilarity - currentSimilarity;
 		if (divergence < minDivergence) continue;
@@ -258,7 +298,7 @@ function rankContentGaps(queries, urls, queryEmbeddings, urlEmbeddings, minDiver
 			currentSimilarity,
 			suggestedUrl,
 			suggestedSimilarity,
-			alternatives: scored.slice(1, 4),
+			alternatives: top.slice(1),
 			divergence,
 			impact: qr.impressions * divergence
 		});
@@ -266,7 +306,7 @@ function rankContentGaps(queries, urls, queryEmbeddings, urlEmbeddings, minDiver
 	gaps.sort((a, b) => b.impact - a.impact);
 	return gaps;
 }
-async function analyzeContentGap(source, opts = {}) {
+async function runContentGapAnalysis(source, opts = {}, runtime) {
 	if (!source.executeSql) throw new ContentGapSourceUnsupportedError(source.name ?? "unknown");
 	const executeSql = source.executeSql.bind(source);
 	const { maxQueries = 1500, maxUrls = 400, minImpressions = 50, minDivergence = .12, device, onProgress } = opts;
@@ -274,24 +314,24 @@ async function analyzeContentGap(source, opts = {}) {
 		phase: "loading-model",
 		message: "Checking device..."
 	});
-	const t0 = performance.now();
-	const chosenDevice = await selectContentGapDevice(device);
+	const t0 = runtime.now();
+	const chosenDevice = await runtime.embeddings.selectDevice(device);
 	notify(onProgress, {
 		phase: "loading-model",
-		message: `Loading ${CONTENT_GAP_MODEL_ID} on ${chosenDevice} (~110MB, cached after first run)...`
+		message: `Loading ${runtime.embeddings.modelId} on ${chosenDevice} (~110MB, cached after first run)...`
 	});
-	const extractor = await loadContentGapExtractor(chosenDevice);
-	const modelMs = performance.now() - t0;
+	const extractor = await runtime.embeddings.loadExtractor(chosenDevice);
+	const modelMs = runtime.now() - t0;
 	notify(onProgress, {
 		phase: "fetching-data",
 		message: `Running SQL (device: ${chosenDevice})...`,
 		modelMs
 	});
-	const { queries, urls, sqlMs } = await fetchContentGapInputs(executeSql, {
+	const { queries, urls, sqlMs } = await runtime.loadInputs(executeSql, {
 		maxQueries,
 		maxUrls,
 		minImpressions
-	}, normalizeUrl);
+	}, normalizeUrl, runtime.now);
 	if (queries.length === 0 || urls.length === 0) {
 		notify(onProgress, {
 			phase: "done",
@@ -309,7 +349,7 @@ async function analyzeContentGap(source, opts = {}) {
 				cacheHits: 0,
 				totalInputs: 0,
 				device: chosenDevice,
-				modelId: CONTENT_GAP_MODEL_ID
+				modelId: runtime.embeddings.modelId
 			}
 		};
 	}
@@ -323,8 +363,8 @@ async function analyzeContentGap(source, opts = {}) {
 		modelMs,
 		sqlMs
 	});
-	const t2 = performance.now();
-	const queryEmbed = await embedContentGapTexts(extractor, "query", queryTexts, (t) => CONTENT_GAP_QUERY_PREFIX + t, (done, total) => {
+	const t2 = runtime.now();
+	const queryEmbed = await runtime.embeddings.embed(extractor, "query", queryTexts, (t) => runtime.embeddings.queryPrefix + t, (done, total) => {
 		notify(onProgress, {
 			phase: "embedding-queries",
 			message: `Embedding ${queryTexts.length} queries on ${chosenDevice}...`,
@@ -342,7 +382,7 @@ async function analyzeContentGap(source, opts = {}) {
 		modelMs,
 		sqlMs
 	});
-	const urlEmbed = await embedContentGapTexts(extractor, "passage", urlTexts, (t) => t, (done, total) => {
+	const urlEmbed = await runtime.embeddings.embed(extractor, "passage", urlTexts, (t) => t, (done, total) => {
 		notify(onProgress, {
 			phase: "embedding-urls",
 			message: `Embedding ${urls.length} URLs...`,
@@ -352,7 +392,7 @@ async function analyzeContentGap(source, opts = {}) {
 			sqlMs
 		});
 	});
-	const embedMs = performance.now() - t2;
+	const embedMs = runtime.now() - t2;
 	notify(onProgress, {
 		phase: "computing-gaps",
 		message: "Computing semantic similarities...",
@@ -360,9 +400,9 @@ async function analyzeContentGap(source, opts = {}) {
 		sqlMs,
 		embedMs
 	});
-	const t3 = performance.now();
+	const t3 = runtime.now();
 	const gaps = rankContentGaps(queries, urls, queryEmbed.vectors, urlEmbed.vectors, minDivergence);
-	const computeMs = performance.now() - t3;
+	const computeMs = runtime.now() - t3;
 	const totalHits = queryEmbed.hits + urlEmbed.hits;
 	const totalInputs = queryTexts.length + urls.length;
 	const cacheNote = totalHits > 0 ? ` · ${totalHits}/${totalInputs} cache hits` : "";
@@ -384,8 +424,21 @@ async function analyzeContentGap(source, opts = {}) {
 			cacheHits: totalHits,
 			totalInputs,
 			device: chosenDevice,
-			modelId: CONTENT_GAP_MODEL_ID
+			modelId: runtime.embeddings.modelId
 		}
 	};
 }
-export { ContentGapSourceUnsupportedError, analyzeContentGap, cosineNormalized, deriveUrlText, normalizeUrl, rankContentGaps };
+function createContentGapAnalyzer(opts = {}) {
+	const runtime = {
+		embeddings: opts.embeddings ?? createContentGapEmbeddingRuntime(),
+		loadInputs: opts.loadInputs ?? fetchContentGapInputs,
+		now: opts.now ?? (() => performance.now())
+	};
+	return { analyze(source, options) {
+		return runContentGapAnalysis(source, options, runtime);
+	} };
+}
+function analyzeContentGap(source, opts = {}) {
+	return createContentGapAnalyzer().analyze(source, opts);
+}
+export { ContentGapSourceUnsupportedError, analyzeContentGap, cosineNormalized, createContentGapAnalyzer, createMemoryContentGapCache, deriveUrlText, normalizeUrl, rankContentGaps };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/analysis",
   "type": "module",
-  "version": "0.37.3",
+  "version": "0.37.4",
   "description": "GSC analyzers — striking-distance, opportunity, movers, decay, brand, clustering, concentration, seasonality. Pure row-based + DuckDB-native.",
   "author": {
     "name": "Harlan Wilton",
@@ -76,9 +76,9 @@
   "dependencies": {
     "drizzle-orm": "1.0.0-rc.3",
     "pluralize": "^8.0.0",
-    "@gscdump/engine": "0.37.3",
-    "@gscdump/engine-gsc-api": "0.37.3",
-    "gscdump": "0.37.3"
+    "@gscdump/engine": "0.37.4",
+    "gscdump": "0.37.4",
+    "@gscdump/engine-gsc-api": "0.37.4"
   },
   "devDependencies": {
     "vitest": "^4.1.9"