Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

perf(competitors): send head-to-head as per-engine summaries and load runs on demand (#923) (#942)

Gökhan Geyik106c5ff3cdf1
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/competitors/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/competitors/page.tsx
index a0903f654..14747211d 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/competitors/page.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/competitors/page.tsx
@@ -9,10 +9,10 @@ import { getCompetitors, addCompetitor, deleteCompetitor } from '@/lib/actions/c
import {
getCompetitorComparison,
getHeadToHeadComparison,
+ getHeadToHeadRuns,
type CompetitorComparisonData,
- type HeadToHeadData,
- type HeadToHeadPromptRow,
} from '@/lib/actions/tracking';
+import type { HeadToHeadData, HeadToHeadGroup, HeadToHeadRun } from '@/lib/head-to-head';
import { getFaviconUrl } from '@/lib/favicon';
import { MODEL_LABELS } from '@/config/platform-labels';
import type { Competitor } from '@/types';
@@ -466,76 +466,40 @@ interface PromptComparisonGroup {
promptId: string;
promptText: string;
promptCategory?: string;
- rows: HeadToHeadData['promptRows'];
+ groups: HeadToHeadGroup[];
+ runs: number;
+ latestAt: string;
avgBrandScore: number;
avgCompetitorScore: number;
avgDiff: number;
}
-function groupH2HByPrompt(rows: HeadToHeadData['promptRows']): PromptComparisonGroup[] {
- const map = new Map<string, HeadToHeadData['promptRows']>();
- for (const r of rows) {
- const arr = map.get(r.promptId) || [];
- arr.push(r);
- map.set(r.promptId, arr);
+/** Fold engine groups into one row per prompt, weighting each engine by its runs. */
+function groupH2HByPrompt(groups: HeadToHeadGroup[]): PromptComparisonGroup[] {
+ const map = new Map<string, HeadToHeadGroup[]>();
+ for (const g of groups) {
+ const arr = map.get(g.promptId) || [];
+ arr.push(g);
+ map.set(g.promptId, arr);
}
- return Array.from(map.entries()).map(([promptId, items]) => {
- const avgB = Math.round(items.reduce((s, r) => s + r.brandScore, 0) / items.length);
- const avgC = Math.round(items.reduce((s, r) => s + r.competitorScore, 0) / items.length);
- return {
- promptId,
- promptText: items[0].promptText,
- promptCategory: items[0].promptCategory,
- rows: items,
- avgBrandScore: avgB,
- avgCompetitorScore: avgC,
- avgDiff: avgB - avgC,
- };
- });
-}
-
-interface ModelComparisonGroup {
- key: string;
- platform: string;
- modelUsed: string;
- region?: string;
- rows: HeadToHeadPromptRow[];
- latest: HeadToHeadPromptRow;
- avgBrandScore: number;
- avgCompetitorScore: number;
- avgDiff: number;
-}
-
-function groupH2HByModel(rows: HeadToHeadPromptRow[]): ModelComparisonGroup[] {
- const map = new Map<string, HeadToHeadPromptRow[]>();
- for (const r of rows) {
- const key = `${r.platform}|${r.modelUsed ?? ''}|${r.region ?? ''}`;
- const arr = map.get(key) || [];
- arr.push(r);
- map.set(key, arr);
- }
-
return Array.from(map.entries())
- .map(([key, items]) => {
- const sorted = [...items].sort(
- (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
- );
- const latest = sorted[0];
- const avgB = Math.round(sorted.reduce((s, r) => s + r.brandScore, 0) / sorted.length);
- const avgC = Math.round(sorted.reduce((s, r) => s + r.competitorScore, 0) / sorted.length);
+ .map(([promptId, items]) => {
+ const runs = items.reduce((s, g) => s + g.runs, 0);
+ const avgB = Math.round(items.reduce((s, g) => s + g.brandScore * g.runs, 0) / runs);
+ const avgC = Math.round(items.reduce((s, g) => s + g.competitorScore * g.runs, 0) / runs);
return {
- key,
- platform: latest.platform,
- modelUsed: latest.modelUsed,
- region: latest.region,
- rows: sorted,
- latest,
+ promptId,
+ promptText: items[0].promptText,
+ promptCategory: items[0].promptCategory,
+ groups: [...items].sort((a, b) => b.brandScore - a.brandScore),
+ runs,
+ latestAt: items.reduce((max, g) => (g.latestAt > max ? g.latestAt : max), ''),
avgBrandScore: avgB,
avgCompetitorScore: avgC,
avgDiff: avgB - avgC,
- } satisfies ModelComparisonGroup;
+ };
})
- .sort((a, b) => b.avgBrandScore - a.avgBrandScore);
+ .sort((a, b) => b.latestAt.localeCompare(a.latestAt));
}
function formatTimestamp(iso: string): string {
@@ -546,23 +510,61 @@ function formatTimestamp(iso: string): string {
});
}
+type LoadRuns = (group: HeadToHeadGroup, limit: number) => Promise<HeadToHeadRun[]>;
+
+const RUN_HISTORY_LIMIT = 50;
+
function ModelSubGroup({
group,
expanded,
onToggle,
- onViewRow,
+ onViewResult,
+ loadRuns,
brandName,
competitorName,
}: {
- group: ModelComparisonGroup;
+ group: HeadToHeadGroup;
expanded: boolean;
onToggle: () => void;
- onViewRow: (row: HeadToHeadPromptRow) => void;
+ onViewResult: (resultId: string) => void;
+ loadRuns: LoadRuns;
brandName: string;
competitorName: string;
}) {
const t = useTranslations('competitors');
- const hasHistory = group.rows.length > 1;
+ const hasHistory = group.runs > 1;
+ const [runs, setRuns] = useState<HeadToHeadRun[] | null>(null);
+ const [runsFailed, setRunsFailed] = useState(false);
+ const [openingLatest, setOpeningLatest] = useState(false);
+
+ useEffect(() => {
+ if (!expanded || !hasHistory || runs !== null) return;
+ let cancelled = false;
+ setRunsFailed(false);
+ loadRuns(group, RUN_HISTORY_LIMIT)
+ .then((loaded) => {
+ if (!cancelled) setRuns(loaded);
+ })
+ .catch(() => {
+ if (!cancelled) setRunsFailed(true);
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [expanded, hasHistory, runs, group, loadRuns]);
+
+ const viewLatest = async () => {
+ if (openingLatest) return;
+ setOpeningLatest(true);
+ try {
+ const [latest] = runs ?? (await loadRuns(group, 1));
+ if (latest) onViewResult(latest.resultId);
+ } catch {
+ toast.error(t('h2h.loadError'));
+ } finally {
+ setOpeningLatest(false);
+ }
+ };
return (
<div className="rounded-md border bg-background/50">
@@ -596,35 +598,41 @@ function ModelSubGroup({
</Badge>
)}
<span className="text-[10px] text-muted-foreground tabular-nums ml-1">
- {group.rows.length} run{group.rows.length !== 1 ? 's' : ''}
+ {group.runs} run{group.runs !== 1 ? 's' : ''}
</span>
</div>
<div className="flex items-center gap-4 shrink-0">
<div className="text-right">
<p className="text-[10px] text-muted-foreground">{t('h2h.you')}</p>
- <p className="text-xs font-semibold tabular-nums">{group.avgBrandScore}%</p>
+ <p className="text-xs font-semibold tabular-nums">{Math.round(group.brandScore)}%</p>
</div>
<div className="text-right">
<p className="text-[10px] text-muted-foreground">{t('h2h.them')}</p>
- <p className="text-xs font-semibold tabular-nums">{group.avgCompetitorScore}%</p>
+ <p className="text-xs font-semibold tabular-nums">
+ {Math.round(group.competitorScore)}%
+ </p>
</div>
<div className="text-right min-w-[48px]">
<p className="text-[10px] text-muted-foreground">{t('h2h.diff')}</p>
- <DiffBadge diff={group.avgDiff} />
+ <DiffBadge diff={Math.round(group.brandScore) - Math.round(group.competitorScore)} />
</div>
- <SentimentBadge sentiment={group.latest.sentiment} />
<Button
variant="ghost"
size="icon"
className="h-7 w-7"
title="View latest AI response"
+ disabled={openingLatest}
onClick={(e) => {
e.stopPropagation();
- onViewRow(group.latest);
+ void viewLatest();
}}
aria-label="View latest AI response"
>
- <Eye className="h-3.5 w-3.5" />
+ {openingLatest ? (
+ <Loader2 className="h-3.5 w-3.5 animate-spin" />
+ ) : (
+ <Eye className="h-3.5 w-3.5" />
+ )}
</Button>
</div>
</div>
@@ -634,54 +642,62 @@ function ModelSubGroup({
<p className="text-[10px] uppercase tracking-wide text-muted-foreground font-medium mb-1.5">
Previous runs
</p>
- <Table>
- <TableHeader>
- <TableRow>
- <TableHead className="text-[10px] h-7">Date</TableHead>
- <TableHead className="text-[10px] h-7 text-center">{brandName}</TableHead>
- <TableHead className="text-[10px] h-7 text-center">{competitorName}</TableHead>
- <TableHead className="text-[10px] h-7 text-center">{t('h2h.diff')}</TableHead>
- <TableHead className="text-[10px] h-7 text-center">Sentiment</TableHead>
- <TableHead className="text-[10px] h-7 w-[60px]" />
- </TableRow>
- </TableHeader>
- <TableBody>
- {group.rows.map((row) => (
- <TableRow key={row.resultId} className="hover:bg-muted/30">
- <TableCell className="text-xs text-muted-foreground py-1.5">
- {formatTimestamp(row.createdAt)}
- </TableCell>
- <TableCell className="text-center py-1.5 text-xs font-semibold tabular-nums">
- {Math.round(row.brandScore)}%
- </TableCell>
- <TableCell className="text-center py-1.5 text-xs font-semibold tabular-nums">
- {Math.round(row.competitorScore)}%
- </TableCell>
- <TableCell className="text-center py-1.5">
- <DiffBadge diff={Math.round(row.brandScore - row.competitorScore)} />
- </TableCell>
- <TableCell className="text-center py-1.5">
- <SentimentBadge sentiment={row.sentiment} />
- </TableCell>
- <TableCell className="text-center py-1.5">
- <Button
- variant="ghost"
- size="icon"
- className="h-6 w-6"
- title="View AI response"
- onClick={(e) => {
- e.stopPropagation();
- onViewRow(row);
- }}
- aria-label="View AI response"
- >
- <Eye className="h-3 w-3" />
- </Button>
- </TableCell>
+ {runsFailed ? (
+ <p className="py-2 text-xs text-muted-foreground">{t('h2h.loadError')}</p>
+ ) : runs === null ? (
+ <div className="flex justify-center py-3">
+ <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
+ </div>
+ ) : (
+ <Table>
+ <TableHeader>
+ <TableRow>
+ <TableHead className="text-[10px] h-7">Date</TableHead>
+ <TableHead className="text-[10px] h-7 text-center">{brandName}</TableHead>
+ <TableHead className="text-[10px] h-7 text-center">{competitorName}</TableHead>
+ <TableHead className="text-[10px] h-7 text-center">{t('h2h.diff')}</TableHead>
+ <TableHead className="text-[10px] h-7 text-center">Sentiment</TableHead>
+ <TableHead className="text-[10px] h-7 w-[60px]" />
</TableRow>
- ))}
- </TableBody>
- </Table>
+ </TableHeader>
+ <TableBody>
+ {runs.map((row) => (
+ <TableRow key={row.resultId} className="hover:bg-muted/30">
+ <TableCell className="text-xs text-muted-foreground py-1.5">
+ {formatTimestamp(row.createdAt)}
+ </TableCell>
+ <TableCell className="text-center py-1.5 text-xs font-semibold tabular-nums">
+ {Math.round(row.brandScore)}%
+ </TableCell>
+ <TableCell className="text-center py-1.5 text-xs font-semibold tabular-nums">
+ {Math.round(row.competitorScore)}%
+ </TableCell>
+ <TableCell className="text-center py-1.5">
+ <DiffBadge diff={Math.round(row.brandScore - row.competitorScore)} />
+ </TableCell>
+ <TableCell className="text-center py-1.5">
+ <SentimentBadge sentiment={row.sentiment} />
+ </TableCell>
+ <TableCell className="text-center py-1.5">
+ <Button
+ variant="ghost"
+ size="icon"
+ className="h-6 w-6"
+ title="View AI response"
+ onClick={(e) => {
+ e.stopPropagation();
+ onViewResult(row.resultId);
+ }}
+ aria-label="View AI response"
+ >
+ <Eye className="h-3 w-3" />
+ </Button>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ )}
</div>
)}
</div>
@@ -689,18 +705,20 @@ function ModelSubGroup({
}
function PromptComparisonGrouped({
- rows,
+ groups: engineGroups,
brandName,
competitorName,
- onViewRow,
+ onViewResult,
+ loadRuns,
}: {
- rows: HeadToHeadData['promptRows'];
+ groups: HeadToHeadGroup[];
brandName: string;
competitorName: string;
- onViewRow: (row: HeadToHeadPromptRow) => void;
+ onViewResult: (resultId: string) => void;
+ loadRuns: LoadRuns;
}) {
const t = useTranslations('competitors');
- const groups = groupH2HByPrompt(rows);
+ const groups = groupH2HByPrompt(engineGroups);
const [expanded, setExpanded] = useState<Set<string>>(new Set());
const [expandedModels, setExpandedModels] = useState<Set<string>>(new Set());
@@ -732,7 +750,7 @@ function PromptComparisonGrouped({
<div className="space-y-2">
{groups.map((group) => {
const isOpen = expanded.has(group.promptId);
- const modelGroups = groupH2HByModel(group.rows);
+ const modelGroups = group.groups;
return (
<div key={group.promptId} className="rounded-lg border overflow-hidden">
{/* Group Header */}
@@ -764,8 +782,8 @@ function PromptComparisonGrouped({
)}
<span className="text-[11px] text-muted-foreground">
{modelGroups.length} platform
- {modelGroups.length !== 1 ? 's' : ''} · {group.rows.length} result
- {group.rows.length !== 1 ? 's' : ''}
+ {modelGroups.length !== 1 ? 's' : ''} · {group.runs} result
+ {group.runs !== 1 ? 's' : ''}
</span>
</div>
</div>
@@ -789,14 +807,15 @@ function PromptComparisonGrouped({
{isOpen && (
<div className="border-t px-3 py-2 space-y-1.5 bg-muted/10">
{modelGroups.map((mg) => {
- const compositeKey = `${group.promptId}::${mg.key}`;
+ const compositeKey = `${group.promptId}::${mg.rawPlatform ?? ''}|${mg.rawModelUsed ?? ''}|${mg.region ?? ''}`;
return (
<ModelSubGroup
key={compositeKey}
group={mg}
expanded={expandedModels.has(compositeKey)}
onToggle={() => toggleModel(compositeKey)}
- onViewRow={onViewRow}
+ onViewResult={onViewResult}
+ loadRuns={loadRuns}
brandName={brandName}
competitorName={competitorName}
/>
@@ -816,14 +835,14 @@ function PromptComparisonGrouped({
interface GapStrengthGroup {
promptId: string;
promptText: string;
- items: HeadToHeadData['gaps'];
+ items: HeadToHeadGroup[];
avgBrandScore: number;
avgCompetitorScore: number;
avgDiff: number;
}
-function groupGapStrengthByPrompt(items: HeadToHeadData['gaps']): GapStrengthGroup[] {
- const map = new Map<string, HeadToHeadData['gaps']>();
+function groupGapStrengthByPrompt(items: HeadToHeadGroup[]): GapStrengthGroup[] {
+ const map = new Map<string, HeadToHeadGroup[]>();
for (const item of items) {
const arr = map.get(item.promptId) || [];
arr.push(item);
@@ -847,13 +866,7 @@ function groupGapStrengthByPrompt(items: HeadToHeadData['gaps']): GapStrengthGro
.sort((a, b) => a.avgDiff - b.avgDiff);
}
-function GapStrengthList({
- items,
- type,
-}: {
- items: HeadToHeadData['gaps'];
- type: 'gap' | 'strength';
-}) {
+function GapStrengthList({ items, type }: { items: HeadToHeadGroup[]; type: 'gap' | 'strength' }) {
const t = useTranslations('competitors');
const isGap = type === 'gap';
const groups = groupGapStrengthByPrompt(items);
@@ -950,9 +963,9 @@ function GapStrengthList({
) : (
<span className="text-xs text-muted-foreground">—</span>
)}
- {!hasMultiple && group.items[0].createdAt && (
+ {!hasMultiple && group.items[0].latestAt && (
<span className="text-muted-foreground">
- {new Date(group.items[0].createdAt).toLocaleDateString(undefined, {
+ {new Date(group.items[0].latestAt).toLocaleDateString(undefined, {
day: 'numeric',
month: 'short',
year: 'numeric',
@@ -1000,9 +1013,9 @@ function GapStrengthList({
<span className="tabular-nums text-muted-foreground">
{t('h2h.them')}: {Math.round(item.competitorScore)}%
</span>
- {item.createdAt && (
+ {item.latestAt && (
<span className="text-muted-foreground whitespace-nowrap">
- {new Date(item.createdAt).toLocaleDateString(undefined, {
+ {new Date(item.latestAt).toLocaleDateString(undefined, {
day: 'numeric',
month: 'short',
})}
@@ -1026,10 +1039,12 @@ function HeadToHeadSection({
data,
brandName,
competitorName,
+ loadRuns,
}: {
data: HeadToHeadData;
brandName: string;
competitorName: string;
+ loadRuns: LoadRuns;
}) {
const t = useTranslations('competitors');
const router = useRouter();
@@ -1118,10 +1133,11 @@ function HeadToHeadSection({
</CardHeader>
<CardContent className="pt-0">
<PromptComparisonGrouped
- rows={data.promptRows}
+ groups={data.groups}
brandName={brandName}
competitorName={competitorName}
- onViewRow={(row) => router.push(`/dashboard/insights/${row.resultId}`)}
+ onViewResult={(resultId) => router.push(`/dashboard/insights/${resultId}`)}
+ loadRuns={loadRuns}
/>
</CardContent>
</Card>
@@ -1198,6 +1214,24 @@ export default function CompetitorsPage() {
}
}, [selectedCompetitorId, loadH2H]);
+ const loadRuns = useCallback(
+ (group: HeadToHeadGroup, limit: number) => {
+ if (!brand || !selectedCompetitorId) return Promise.resolve([]);
+ return getHeadToHeadRuns(
+ brand.id,
+ selectedCompetitorId,
+ {
+ promptId: group.promptId,
+ rawPlatform: group.rawPlatform,
+ rawModelUsed: group.rawModelUsed,
+ region: group.region ?? null,
+ },
+ limit,
+ );
+ },
+ [brand, selectedCompetitorId],
+ );
+
if (isCloud && !canUse('competitor_tracking')) {
return <PlanGateOverlay />;
}
@@ -1342,11 +1376,12 @@ export default function CompetitorsPage() {
<div className="flex items-center justify-center py-16">
<Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
</div>
- ) : h2hData && h2hData.promptRows.length > 0 ? (
+ ) : h2hData && h2hData.groups.length > 0 ? (
<HeadToHeadSection
data={h2hData}
brandName={brand.name}
competitorName={selectedCompetitor?.name ?? ''}
+ loadRuns={loadRuns}
/>
) : (
<Card>
diff --git a/web/src/lib/actions/tracking.ts b/web/src/lib/actions/tracking.ts
index 9836f6ee5..7f045ec56 100644
--- a/web/src/lib/actions/tracking.ts
+++ b/web/src/lib/actions/tracking.ts
@@ -28,6 +28,14 @@ import { getPromptSuggestions } from '@/lib/actions/prompt-suggestions';
import { aggregatePromptVolumeClusters } from '@/lib/prompt-volume-clusters';
import { percentageChange } from '@/lib/metrics';
import { PLATFORM_LABELS } from '@/config/platform-labels';
+import {
+ aggregateHeadToHead,
+ competitorScoreIn,
+ emptyHeadToHead,
+ type HeadToHeadData,
+ type HeadToHeadResultRow,
+ type HeadToHeadRun,
+} from '@/lib/head-to-head';
/** Round to one decimal place (keeps sub-1 averages visible instead of flooring to 0). */
function roundTo1(n: number): number {
@@ -2633,46 +2641,11 @@ export async function getVisibilityRateTrend(
// ─── Head-to-Head Competitor Comparison ─────────────────────────────────────
-export interface HeadToHeadPromptRow {
- resultId: string;
- promptId: string;
- promptText: string;
- promptCategory?: string;
- brandScore: number;
- competitorScore: number;
- diff: number;
- platform: string;
- modelUsed: string;
- region?: string;
- response: string;
- citations: Citation[];
- sentiment: Sentiment;
- brandMentionCount: number;
- brandCitationCount: number;
- compMentionCount: number;
- compCitationCount: number;
- createdAt: string;
-}
-
-export interface HeadToHeadPlatformRow {
- platform: string;
- brandScore: number;
- competitorScore: number;
- diff: number;
-}
-
-export interface HeadToHeadData {
- promptRows: HeadToHeadPromptRow[];
- platformRows: HeadToHeadPlatformRow[];
- brandAvg: number;
- competitorAvg: number;
- gaps: HeadToHeadPromptRow[];
- strengths: HeadToHeadPromptRow[];
-}
-
/**
- * Compare a brand vs a single competitor prompt-by-prompt.
- * Returns per-prompt scores, per-platform breakdown, gaps and strengths.
+ * Compare a brand vs a single competitor (#923): one summary per (prompt,
+ * engine, model, region), the per-engine breakdown, and the largest gaps and
+ * strengths. A group's individual runs load separately via
+ * `getHeadToHeadRuns`, so no answer text is sent up front.
*/
export async function getHeadToHeadComparison(
brandId: string,
@@ -2682,132 +2655,79 @@ export async function getHeadToHeadComparison(
// #155 — head-to-head comparisons are a Competitors-tab feature, which
// also lives under Insights — same isolation rule applies here.
+ // Still a single page of raw results (PostgREST caps it at 1,000), so
+ // large brands are summarised from their newest answers only; #923 moves
+ // this onto the daily rollups.
const { data: results, error } = await supabase
.from('prompt_results')
- .select('*')
+ .select(
+ 'prompt_id, platform, model_used, region, visibility_score, competitor_mentions, created_at',
+ )
.eq('brand_id', brandId)
.neq('platform', 'chatgpt-shopping')
- .order('created_at', { ascending: false });
+ .order('created_at', { ascending: false })
+ .order('id', { ascending: false });
if (error) throw new Error(error.message);
- const rows = (results ?? []) as Record<string, unknown>[];
- if (rows.length === 0) {
- return {
- promptRows: [],
- platformRows: [],
- brandAvg: 0,
- competitorAvg: 0,
- gaps: [],
- strengths: [],
- };
- }
+ const rows = (results ?? []) as HeadToHeadResultRow[];
+ if (rows.length === 0) return emptyHeadToHead();
- const promptIds = [...new Set(rows.map((r) => r.prompt_id as string))];
+ const promptIds = [...new Set(rows.map((r) => r.prompt_id).filter((id): id is string => !!id))];
const { data: promptData } =
promptIds.length > 0
? await supabase.from('prompts').select('id, text, category').in('id', promptIds)
: { data: [] };
- const promptMap = new Map(
+ const prompts = new Map(
(promptData ?? []).map((p) => [
- p.id,
- {
- text: p.text as string,
- category: (p.category as string | null) ?? undefined,
- },
+ p.id as string,
+ { text: p.text as string, category: (p.category as string | null) ?? undefined },
]),
);
- const promptRows: HeadToHeadPromptRow[] = [];
-
- type PlatAgg = {
- brandTotal: number;
- brandCount: number;
- compTotal: number;
- compCount: number;
- };
- const platMap = new Map<string, PlatAgg>();
-
- let brandTotalScore = 0;
- let brandCount = 0;
- let compTotalScore = 0;
- let compCount = 0;
-
- for (const row of rows) {
- const brandScore = row.visibility_score as number;
- const platform = resolveProvider(
- row.model_used as string | null,
- row.platform as string | null,
- );
- const mentions = (row.competitor_mentions as CompetitorMention[] | null) ?? [];
- const comp = mentions.find((cm) => cm.competitor_id === competitorId);
- const compScore = comp?.visibility_score ?? 0;
-
- const pm = promptMap.get(row.prompt_id as string);
-
- const modelUsed = (row.model_used as string | null) ?? '';
-
- promptRows.push({
- resultId: row.id as string,
- promptId: row.prompt_id as string,
- promptText: pm?.text ?? '',
- promptCategory: pm?.category,
- brandScore,
- competitorScore: compScore,
- diff: brandScore - compScore,
- platform,
- modelUsed,
- region: (row.region as string | null) ?? undefined,
- response: (row.response as string) ?? '',
- citations: (row.citations as Citation[]) ?? [],
- sentiment: (row.sentiment as Sentiment) ?? 'neutral',
- brandMentionCount: row.mention_count as number,
- brandCitationCount: row.citation_count as number,
- compMentionCount: comp?.mention_count ?? 0,
- compCitationCount: comp?.citation_count ?? 0,
- createdAt: row.created_at as string,
- });
-
- brandTotalScore += brandScore;
- brandCount += 1;
- if (comp) {
- compTotalScore += compScore;
- compCount += 1;
- }
-
- const pa = platMap.get(platform) ?? {
- brandTotal: 0,
- brandCount: 0,
- compTotal: 0,
- compCount: 0,
- };
- pa.brandTotal += brandScore;
- pa.brandCount += 1;
- if (comp) {
- pa.compTotal += compScore;
- pa.compCount += 1;
- }
- platMap.set(platform, pa);
- }
-
- const platformRows: HeadToHeadPlatformRow[] = [...platMap.entries()]
- .map(([platform, a]) => {
- const bs = a.brandCount > 0 ? Math.round(a.brandTotal / a.brandCount) : 0;
- const cs = a.compCount > 0 ? Math.round(a.compTotal / a.compCount) : 0;
- return { platform, brandScore: bs, competitorScore: cs, diff: bs - cs };
- })
- .sort((a, b) => a.platform.localeCompare(b.platform));
+ return aggregateHeadToHead(rows, competitorId, prompts, resolveProvider);
+}
- const brandAvg = brandCount > 0 ? Math.round(brandTotalScore / brandCount) : 0;
- const competitorAvg = compCount > 0 ? Math.round(compTotalScore / compCount) : 0;
+/**
+ * The individual runs behind one head-to-head group, newest first, loaded when
+ * the user opens the group. Bounded by `limit` (max 100).
+ */
+export async function getHeadToHeadRuns(
+ brandId: string,
+ competitorId: string,
+ group: {
+ promptId: string;
+ rawPlatform: string | null;
+ rawModelUsed: string | null;
+ region: string | null;
+ },
+ limit = 50,
+): Promise<HeadToHeadRun[]> {
+ const supabase = await dbClient();
- const sorted = [...promptRows].sort((a, b) => a.diff - b.diff);
- const gaps = sorted.filter((r) => r.diff < 0).slice(0, 10);
- const strengths = sorted
- .filter((r) => r.diff > 0)
- .reverse()
- .slice(0, 10);
+ let query = supabase
+ .from('prompt_results')
+ .select('id, created_at, visibility_score, sentiment, competitor_mentions')
+ .eq('brand_id', brandId)
+ .eq('prompt_id', group.promptId);
+ query = group.rawPlatform ? query.eq('platform', group.rawPlatform) : query.is('platform', null);
+ query = group.rawModelUsed
+ ? query.eq('model_used', group.rawModelUsed)
+ : query.is('model_used', null);
+ query = group.region ? query.eq('region', group.region) : query.is('region', null);
+
+ const { data, error } = await query
+ .order('created_at', { ascending: false })
+ .order('id', { ascending: false })
+ .limit(Math.min(Math.max(limit, 1), 100));
+ if (error) throw new Error(error.message);
- return { promptRows, platformRows, brandAvg, competitorAvg, gaps, strengths };
+ return (data ?? []).map((row) => ({
+ resultId: row.id as string,
+ createdAt: row.created_at as string,
+ brandScore: (row.visibility_score as number | null) ?? 0,
+ competitorScore: competitorScoreIn(row.competitor_mentions, competitorId) ?? 0,
+ sentiment: ((row.sentiment as Sentiment | null) ?? 'neutral') as Sentiment,
+ }));
}
// ─── Insights Metric Breakdown (Root-Cause Drilldown) ─────────────────────────
diff --git a/web/src/lib/head-to-head.test.ts b/web/src/lib/head-to-head.test.ts
new file mode 100644
index 000000000..dcb9b324a
--- /dev/null
+++ b/web/src/lib/head-to-head.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it } from 'vitest';
+
+import { aggregateHeadToHead, competitorScoreIn, type HeadToHeadResultRow } from './head-to-head';
+
+const COMP = 'comp-1';
+const prompts = new Map([
+ ['p1', { text: 'best crm for startups', category: 'comparison' }],
+ ['p2', { text: 'how to pick a crm' }],
+]);
+const provider = (model: string | null, platform: string | null) =>
+ platform === 'chatgpt' ? 'ChatGPT' : (model ?? 'Unknown');
+
+function row(overrides: Partial<HeadToHeadResultRow>): HeadToHeadResultRow {
+ return {
+ prompt_id: 'p1',
+ platform: 'chatgpt',
+ model_used: null,
+ region: 'US',
+ visibility_score: 0,
+ competitor_mentions: [],
+ created_at: '2026-10-01T00:00:00Z',
+ ...overrides,
+ };
+}
+
+const mention = (score: number, id = COMP) => [{ competitor_id: id, visibility_score: score }];
+
+describe('competitorScoreIn', () => {
+ it('returns the score when the competitor is listed, 0 when listed without one', () => {
+ expect(competitorScoreIn(mention(40), COMP)).toBe(40);
+ expect(competitorScoreIn([{ competitor_id: COMP }], COMP)).toBe(0);
+ });
+
+ it('returns null when the answer does not list the competitor', () => {
+ expect(competitorScoreIn(mention(40, 'other'), COMP)).toBeNull();
+ expect(competitorScoreIn(null, COMP)).toBeNull();
+ });
+});
+
+describe('aggregateHeadToHead', () => {
+ it('returns one group per prompt, engine, model and region, averaged over its runs', () => {
+ const data = aggregateHeadToHead(
+ [
+ row({ visibility_score: 60, competitor_mentions: mention(20) }),
+ row({
+ visibility_score: 40,
+ competitor_mentions: mention(40),
+ created_at: '2026-10-02T00:00:00Z',
+ }),
+ row({ region: 'GB', visibility_score: 10, competitor_mentions: mention(50) }),
+ ],
+ COMP,
+ prompts,
+ provider,
+ );
+
+ expect(data.groups).toHaveLength(2);
+ const us = data.groups.find((g) => g.region === 'US')!;
+ expect(us).toMatchObject({
+ promptId: 'p1',
+ promptText: 'best crm for startups',
+ promptCategory: 'comparison',
+ platform: 'ChatGPT',
+ rawPlatform: 'chatgpt',
+ rawModelUsed: null,
+ runs: 2,
+ brandScore: 50,
+ competitorScore: 30,
+ diff: 20,
+ latestAt: '2026-10-02T00:00:00Z',
+ });
+ });
+
+ it('carries no answer text or citations', () => {
+ const data = aggregateHeadToHead([row({ visibility_score: 10 })], COMP, prompts, provider);
+ expect(Object.keys(data.groups[0])).not.toContain('response');
+ expect(Object.keys(data.groups[0])).not.toContain('citations');
+ });
+
+ it('counts a missing competitor as 0 in groups but leaves it out of the overall average', () => {
+ const data = aggregateHeadToHead(
+ [
+ row({ visibility_score: 50, competitor_mentions: mention(30) }),
+ row({ visibility_score: 50, competitor_mentions: [] }),
+ ],
+ COMP,
+ prompts,
+ provider,
+ );
+ expect(data.groups[0].competitorScore).toBe(15);
+ expect(data.competitorAvg).toBe(30);
+ expect(data.brandAvg).toBe(50);
+ });
+
+ it('breaks results down by display provider', () => {
+ const data = aggregateHeadToHead(
+ [
+ row({ platform: 'chatgpt', visibility_score: 80, competitor_mentions: mention(20) }),
+ row({
+ platform: null,
+ model_used: 'Gemini',
+ visibility_score: 20,
+ competitor_mentions: mention(60),
+ }),
+ ],
+ COMP,
+ prompts,
+ provider,
+ );
+ expect(data.platformRows).toEqual([
+ { platform: 'ChatGPT', brandScore: 80, competitorScore: 20, diff: 60 },
+ { platform: 'Gemini', brandScore: 20, competitorScore: 60, diff: -40 },
+ ]);
+ });
+
+ it('ranks gaps and strengths by group average, worst and best first', () => {
+ const data = aggregateHeadToHead(
+ [
+ row({ prompt_id: 'p1', visibility_score: 10, competitor_mentions: mention(60) }),
+ row({ prompt_id: 'p2', visibility_score: 30, competitor_mentions: mention(40) }),
+ row({
+ prompt_id: 'p2',
+ region: 'GB',
+ visibility_score: 90,
+ competitor_mentions: mention(10),
+ }),
+ row({
+ prompt_id: 'p1',
+ region: 'GB',
+ visibility_score: 20,
+ competitor_mentions: mention(20),
+ }),
+ ],
+ COMP,
+ prompts,
+ provider,
+ );
+ expect(data.gaps.map((g) => [g.promptId, g.diff])).toEqual([
+ ['p1', -50],
+ ['p2', -10],
+ ]);
+ expect(data.strengths.map((g) => [g.promptId, g.diff])).toEqual([['p2', 80]]);
+ });
+
+ it('counts results without a prompt in the averages but not as a group', () => {
+ const data = aggregateHeadToHead(
+ [row({ prompt_id: null, visibility_score: 90 }), row({ visibility_score: 10 })],
+ COMP,
+ prompts,
+ provider,
+ );
+ expect(data.groups).toHaveLength(1);
+ expect(data.brandAvg).toBe(50);
+ });
+});
diff --git a/web/src/lib/head-to-head.ts b/web/src/lib/head-to-head.ts
new file mode 100644
index 000000000..6bd8fa659
--- /dev/null
+++ b/web/src/lib/head-to-head.ts
@@ -0,0 +1,180 @@
+/**
+ * Head-to-head aggregation for the Competitors page (#923).
+ *
+ * A plain module rather than part of `lib/actions/tracking.ts`, because that
+ * file is `'use server'` and its runtime exports must be async server actions.
+ *
+ * The page used to receive one row per tracked answer — answer text and
+ * citations included — and group them in the browser. On large brands that is
+ * hundreds of thousands of rows. It now receives one summary per (prompt,
+ * engine, model, region) and loads a group's individual runs only when the
+ * user opens it.
+ */
+
+import type { Sentiment } from '@/types';
+
+/** One (prompt, engine, model, region) combination, averaged over its runs. */
+export interface HeadToHeadGroup {
+ promptId: string;
+ promptText: string;
+ promptCategory?: string;
+ /** Display provider, e.g. "ChatGPT". */
+ platform: string;
+ /** Raw `prompt_results.platform`, used to load this group's runs. */
+ rawPlatform: string | null;
+ modelUsed: string;
+ rawModelUsed: string | null;
+ region?: string;
+ runs: number;
+ brandScore: number;
+ competitorScore: number;
+ diff: number;
+ latestAt: string;
+}
+
+/** One tracked answer inside a group, loaded on demand. */
+export interface HeadToHeadRun {
+ resultId: string;
+ createdAt: string;
+ brandScore: number;
+ competitorScore: number;
+ sentiment: Sentiment;
+}
+
+export interface HeadToHeadPlatformRow {
+ platform: string;
+ brandScore: number;
+ competitorScore: number;
+ diff: number;
+}
+
+export interface HeadToHeadData {
+ groups: HeadToHeadGroup[];
+ platformRows: HeadToHeadPlatformRow[];
+ brandAvg: number;
+ competitorAvg: number;
+ gaps: HeadToHeadGroup[];
+ strengths: HeadToHeadGroup[];
+}
+
+/** The `prompt_results` columns the aggregation reads. */
+export interface HeadToHeadResultRow {
+ prompt_id: string | null;
+ platform: string | null;
+ model_used: string | null;
+ region: string | null;
+ visibility_score: number | null;
+ competitor_mentions: unknown;
+ created_at: string;
+}
+
+interface CompetitorMention {
+ competitor_id?: string;
+ visibility_score?: number;
+}
+
+const GAP_STRENGTH_LIMIT = 10;
+
+export function emptyHeadToHead(): HeadToHeadData {
+ return { groups: [], platformRows: [], brandAvg: 0, competitorAvg: 0, gaps: [], strengths: [] };
+}
+
+/** The competitor's score in one answer, or null when the answer doesn't list it. */
+export function competitorScoreIn(mentions: unknown, competitorId: string): number | null {
+ if (!Array.isArray(mentions)) return null;
+ const hit = (mentions as CompetitorMention[]).find((m) => m?.competitor_id === competitorId);
+ return hit ? (hit.visibility_score ?? 0) : null;
+}
+
+export function aggregateHeadToHead(
+ rows: HeadToHeadResultRow[],
+ competitorId: string,
+ prompts: Map<string, { text: string; category?: string }>,
+ resolveProvider: (modelUsed: string | null, platform: string | null) => string,
+): HeadToHeadData {
+ type GroupAcc = Omit<HeadToHeadGroup, 'brandScore' | 'competitorScore' | 'diff'> & {
+ brandTotal: number;
+ compTotal: number;
+ };
+ type Totals = { brandTotal: number; brandCount: number; compTotal: number; compCount: number };
+ const newTotals = (): Totals => ({ brandTotal: 0, brandCount: 0, compTotal: 0, compCount: 0 });
+
+ const groups = new Map<string, GroupAcc>();
+ const byProvider = new Map<string, Totals>();
+ const overall = newTotals();
+
+ for (const row of rows) {
+ const brandScore = row.visibility_score ?? 0;
+ const compScore = competitorScoreIn(row.competitor_mentions, competitorId);
+ const provider = resolveProvider(row.model_used, row.platform);
+
+ // Averages over answers that list the competitor, as before: an answer
+ // from before the competitor was added says nothing about it.
+ const providerTotals = byProvider.get(provider) ?? newTotals();
+ byProvider.set(provider, providerTotals);
+ for (const totals of [overall, providerTotals]) {
+ totals.brandTotal += brandScore;
+ totals.brandCount += 1;
+ if (compScore !== null) {
+ totals.compTotal += compScore;
+ totals.compCount += 1;
+ }
+ }
+
+ // Results without a prompt still count towards the averages above.
+ if (!row.prompt_id) continue;
+ const key = [row.prompt_id, row.platform ?? '', row.model_used ?? '', row.region ?? ''].join(
+ '\u0000',
+ );
+ const group = groups.get(key) ?? {
+ promptId: row.prompt_id,
+ promptText: prompts.get(row.prompt_id)?.text ?? '',
+ promptCategory: prompts.get(row.prompt_id)?.category,
+ platform: provider,
+ rawPlatform: row.platform,
+ modelUsed: row.model_used ?? '',
+ rawModelUsed: row.model_used,
+ region: row.region ?? undefined,
+ runs: 0,
+ latestAt: row.created_at,
+ brandTotal: 0,
+ compTotal: 0,
+ };
+ // Group averages count a missing competitor as 0, as the page always did.
+ group.runs += 1;
+ group.brandTotal += brandScore;
+ group.compTotal += compScore ?? 0;
+ if (row.created_at > group.latestAt) group.latestAt = row.created_at;
+ groups.set(key, group);
+ }
+
+ const groupList: HeadToHeadGroup[] = [...groups.values()].map(
+ ({ brandTotal, compTotal, ...g }) => {
+ const brandScore = brandTotal / g.runs;
+ const competitorScore = compTotal / g.runs;
+ return { ...g, brandScore, competitorScore, diff: brandScore - competitorScore };
+ },
+ );
+
+ const avg = (total: number, count: number) => (count > 0 ? Math.round(total / count) : 0);
+ const platformRows = [...byProvider.entries()]
+ .map(([platform, a]) => {
+ const brandScore = avg(a.brandTotal, a.brandCount);
+ const competitorScore = avg(a.compTotal, a.compCount);
+ return { platform, brandScore, competitorScore, diff: brandScore - competitorScore };
+ })
+ .sort((a, b) => a.platform.localeCompare(b.platform));
+
+ const byDiff = [...groupList].sort((a, b) => a.diff - b.diff);
+ return {
+ groups: groupList,
+ platformRows,
+ brandAvg: avg(overall.brandTotal, overall.brandCount),
+ competitorAvg: avg(overall.compTotal, overall.compCount),
+ gaps: byDiff.filter((g) => g.diff < 0).slice(0, GAP_STRENGTH_LIMIT),
+ strengths: byDiff
+ .filter((g) => g.diff > 0)
+ .reverse()
+ .slice(0, GAP_STRENGTH_LIMIT),
+ };
+}