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.

feat(action-center): show where each signal happened and filter signals by platform (#1058)

Cihan9889144c96c3
diff --git a/web/messages/en.json b/web/messages/en.json
index cb56aac5d..7403de96e 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -246,6 +246,7 @@
"impact": "Impact",
"status": "Status",
"source": "Source",
+ "platform": "Platform",
"all": "All",
"search": "Search signals…",
"clear": "Clear filters"
@@ -260,6 +261,10 @@
"status": "Status",
"actions": "Actions"
},
+ "where": {
+ "platforms": "Tracked on {names}",
+ "locations": "Tracked in {names}"
+ },
"status": {
"new": "New",
"acknowledged": "Acknowledged",
@@ -428,39 +433,39 @@
},
"topic_gap": {
"title": "Partial coverage of {name}",
- "description": "You appear on part of this topic’s prompts."
+ "description": "You appear on {to}% of its {prompts, plural, one {# prompt} other {# prompts}}."
},
"topic_uncovered": {
"title": "Barely present in {name}",
- "description": "You appear on few of this topic’s prompts."
+ "description": "You appear on {to}% of its {prompts, plural, one {# prompt} other {# prompts}}."
},
"topic_slipping": {
"title": "Coverage slipping in {name}",
- "description": "Your coverage of this topic is starting to fall."
+ "description": "You now appear on {to}% of its {prompts, plural, one {# prompt} other {# prompts}}, slipping from {from}%."
},
"topic_drop": {
"title": "Coverage dropped in {name}",
- "description": "Your coverage of this topic fell significantly."
+ "description": "You now appear on {to}% of its {prompts, plural, one {# prompt} other {# prompts}}, down from {from}%."
},
"platform_slipping": {
"title": "Visibility slipping on {name}",
- "description": "Your mention rate on this platform is starting to fall."
+ "description": "Your mention rate slipped from {from}% to {to}% against the week before."
},
"platform_drop": {
"title": "Visibility dropped on {name}",
- "description": "Your mention rate on this platform fell significantly."
+ "description": "Your mention rate fell from {from}% to {to}% against the week before."
},
"country_gap": {
"title": "Weak in {name}",
- "description": "You are far less visible here than in your strongest region."
+ "description": "You are mentioned in {to}% of answers here, against {from}% in {best}."
},
"competitor_leads": {
"title": "{name} is mentioned far more than you",
- "description": "This competitor is named a multiple of your count."
+ "description": "Mentioned {to, plural, one {# time} other {# times}} this week, against your {from}."
},
"competitor_momentum": {
"title": "{name} is gaining fast",
- "description": "This competitor’s mentions grew sharply against the week before."
+ "description": "Mentions rose from {from} to {to} against the week before."
},
"competitor_topic_lead": {
"title": "A competitor leads {name}",
@@ -476,23 +481,23 @@
},
"authority_citation_gap": {
"title": "Rarely beside {name}",
- "description": "This source is cited widely, and rarely in answers that name you."
+ "description": "Cited in {answers, plural, one {# answer} other {# answers}} this week; you are named in only {withBrand} of them."
},
"third_party_citation_gap": {
"title": "{name} could reference your pages",
- "description": "This source is cited when answers discuss you, and does not reference your own pages."
+ "description": "Cited in {answers, plural, one {# answer} other {# answers}} this week, {withBrand} of them naming you."
},
"third_party_presence_gap": {
"title": "Absent from answers citing {name}",
- "description": "Answers citing this source never name your brand."
+ "description": "Cited in {answers, plural, one {# answer} other {# answers}} across {prompts, plural, one {# prompt} other {# prompts}} this week; none of them name you."
},
"competitor_cited_source": {
"title": "{name} cites competitors, not you",
- "description": "This source appears in answers naming competitors, and never in yours."
+ "description": "Cited in {answers, plural, one {# answer} other {# answers}} this week. Competitors alone are named in {competitorOnly} of them; you in none."
},
"competitor_winning_source": {
"title": "Competitors win {name}",
- "description": "Competitors appear across several prompts citing this source; you never do."
+ "description": "Cited in {answers, plural, one {# answer} other {# answers}} across {prompts, plural, one {# prompt} other {# prompts}} this week. Competitors alone are named in {competitorOnly} of them; you in none."
},
"page_citation_slipping": {
"title": "Citations slipping on {targets}",
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/action-center/signals/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/action-center/signals/page.tsx
index 82908892b..e92cbb0e0 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/action-center/signals/page.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/action-center/signals/page.tsx
@@ -25,6 +25,8 @@ import {
type SignalStatus,
} from '@/lib/signals/registry';
import { signalAffected, signalTexts } from '@/lib/signals/display';
+import { isOnPlatform, locationName, platformName } from '@/lib/signals/names';
+import { getAIProviderDisplayName, type AIProviderKey } from '@/components/ai-provider-avatar';
import { ActionCenterTabs } from '@/components/action-center/action-center-tabs';
import { isSuperseded, SignalTable } from '@/components/action-center/signal-table';
import { SignalDrawer } from '@/components/action-center/signal-drawer';
@@ -50,10 +52,25 @@ const SIGNAL_EXPORT_HEADERS = [
'impact',
'status',
'sources',
+ 'platforms',
+ 'locations',
'detected',
'last_detected',
];
+// The engines the Platform filter can name, in the order it lists them.
+const PLATFORM_FILTERS: readonly AIProviderKey[] = [
+ 'openai',
+ 'googleAio',
+ 'googleAiMode',
+ 'google',
+ 'perplexity',
+ 'copilot',
+ 'anthropic',
+ 'xai',
+ 'meta',
+];
+
const KpiSparkline = dynamic(() => import('@/components/action-center/kpi-sparkline'), {
ssr: false,
loading: () => <Skeleton className="h-8 w-[110px]" />,
@@ -107,6 +124,7 @@ function SignalsContent({ brand }: { brand: Brand }) {
const [impact, setImpact] = useState<SignalImpact | 'all'>('all');
const [status, setStatus] = useState<SignalStatus | 'all'>('all');
const [source, setSource] = useState<SignalSource | 'all'>('all');
+ const [platform, setPlatform] = useState<AIProviderKey | 'all'>('all');
const [search, setSearch] = useState('');
// Filters and search live in the URL (#896) so a refresh keeps them and a
@@ -120,6 +138,9 @@ function SignalsContent({ brand }: { brand: Brand }) {
setImpact(readUrlChoice<SignalImpact | 'all'>('impact', ['all', ...SIGNAL_IMPACTS], 'all'));
setStatus(readUrlChoice<SignalStatus | 'all'>('status', ['all', ...SIGNAL_STATUSES], 'all'));
setSource(readUrlChoice<SignalSource | 'all'>('source', ['all', ...SIGNAL_SOURCES], 'all'));
+ setPlatform(
+ readUrlChoice<AIProviderKey | 'all'>('platform', ['all', ...PLATFORM_FILTERS], 'all'),
+ );
setSearch(readUrlParam('q'));
setUrlRead(true);
}, []);
@@ -130,13 +151,20 @@ function SignalsContent({ brand }: { brand: Brand }) {
const timer = setTimeout(
() =>
writeUrlParams(
- { range: datePreset, category, impact, status, source, q: search.trim() },
- { range: '30d', category: 'all', impact: 'all', status: 'all', source: 'all' },
+ { range: datePreset, category, impact, status, source, platform, q: search.trim() },
+ {
+ range: '30d',
+ category: 'all',
+ impact: 'all',
+ status: 'all',
+ source: 'all',
+ platform: 'all',
+ },
),
300,
);
return () => clearTimeout(timer);
- }, [urlRead, datePreset, category, impact, status, source, search]);
+ }, [urlRead, datePreset, category, impact, status, source, platform, search]);
const [selected, setSelected] = useState<Signal | null>(null);
const [busyId, setBusyId] = useState<string | null>(null);
@@ -199,16 +227,33 @@ function SignalsContent({ brand }: { brand: Brand }) {
if (impact !== 'all' && signal.impact !== impact) return false;
if (status !== 'all' && signal.status !== status) return false;
if (source !== 'all' && !signal.source.includes(source)) return false;
+ if (platform !== 'all' && !isOnPlatform(signal.where.platforms, platform)) return false;
if (needle) {
const texts = signalTexts(signal, tTexts);
const affected = signalAffected(signal, t);
+ const where = [
+ ...signal.where.platforms.map(platformName),
+ ...signal.where.regions.map(locationName),
+ ].join(' ');
const haystack =
- `${texts.title} ${texts.description} ${affected.detail ?? ''}`.toLowerCase();
+ `${texts.title} ${texts.description} ${affected.detail ?? ''} ${where}`.toLowerCase();
if (!haystack.includes(needle)) return false;
}
return true;
});
- }, [signals, category, impact, status, source, search, tTexts, t]);
+ }, [signals, category, impact, status, source, platform, search, tTexts, t]);
+
+ // Only the engines this window's signals are about, plus a picked one that
+ // has none, so the filter never offers an empty choice it can't explain.
+ const platformOptions = useMemo(
+ () =>
+ PLATFORM_FILTERS.filter(
+ (family) =>
+ family === platform ||
+ (signals ?? []).some((signal) => isOnPlatform(signal.where.platforms, family)),
+ ).map((family) => ({ value: family, label: getAIProviderDisplayName(family) })),
+ [signals, platform],
+ );
const handleExportCsv = useCallback(() => {
if (visible.length === 0) return;
@@ -219,6 +264,8 @@ function SignalsContent({ brand }: { brand: Brand }) {
impact: t(`impact.${signal.impact}`),
status: isSuperseded(signal) ? t('superseded') : t(`status.${signal.status}`),
sources: signal.source.map((item) => t(`sources.${item}`)).join(', '),
+ platforms: signal.where.platforms.map(platformName).join(', '),
+ locations: signal.where.regions.map(locationName).join(', '),
detected: signal.detectedAt,
last_detected: signal.lastDetectedAt,
}));
@@ -271,13 +318,19 @@ function SignalsContent({ brand }: { brand: Brand }) {
}, [windowDays]);
const hasActiveFilters =
- category !== 'all' || impact !== 'all' || status !== 'all' || source !== 'all' || search !== '';
+ category !== 'all' ||
+ impact !== 'all' ||
+ status !== 'all' ||
+ source !== 'all' ||
+ platform !== 'all' ||
+ search !== '';
const clearFilters = () => {
setCategory('all');
setImpact('all');
setStatus('all');
setSource('all');
+ setPlatform('all');
setSearch('');
};
@@ -441,6 +494,13 @@ function SignalsContent({ brand }: { brand: Brand }) {
options={SIGNAL_SOURCES.map((v) => ({ value: v, label: t(`sources.${v}`) }))}
allLabel={t('filters.all')}
/>
+ <FilterSelect
+ label={t('filters.platform')}
+ value={platform}
+ onChange={(v) => setPlatform(v as AIProviderKey | 'all')}
+ options={platformOptions}
+ allLabel={t('filters.all')}
+ />
<div className="relative">
<Search className="pointer-events-none absolute left-2.5 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" />
<Input
diff --git a/web/src/components/action-center/signal-table.test.tsx b/web/src/components/action-center/signal-table.test.tsx
new file mode 100644
index 000000000..c268438c7
--- /dev/null
+++ b/web/src/components/action-center/signal-table.test.tsx
@@ -0,0 +1,81 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { NextIntlClientProvider } from 'next-intl';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import messages from '../../../messages/en.json';
+import { SignalWhereLine } from './signal-table';
+
+(
+ globalThis as typeof globalThis & {
+ IS_REACT_ACT_ENVIRONMENT: boolean;
+ }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+
+function render(node: React.ReactNode) {
+ act(() => {
+ root.render(
+ <NextIntlClientProvider locale="en" messages={messages} timeZone="UTC">
+ {node}
+ </NextIntlClientProvider>,
+ );
+ });
+}
+
+beforeEach(() => {
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ root = createRoot(container);
+});
+
+afterEach(() => {
+ act(() => root.unmount());
+ container.remove();
+});
+
+describe('SignalWhereLine', () => {
+ it('shows one icon per engine and the first locations, and names them all for screen readers', () => {
+ render(
+ <SignalWhereLine
+ where={{
+ platforms: [
+ 'chatgpt-web',
+ 'chatgpt',
+ 'gemini-web',
+ 'google-aio',
+ 'perplexity-web',
+ 'grok-web',
+ ],
+ regions: ['US', 'GB', 'DE'],
+ }}
+ />,
+ );
+ // The ChatGPT app and its API share one icon; four shown, one more counted.
+ const icons = [...container.querySelectorAll('[aria-hidden="true"] > [title]')];
+ expect(icons.map((icon) => icon.getAttribute('title'))).toEqual([
+ 'ChatGPT',
+ 'Gemini',
+ 'Google AI Overview',
+ 'Perplexity',
+ ]);
+ expect(container.textContent).toContain('+1');
+ expect(container.textContent).toContain('US · GB +1');
+ expect(container.querySelector('.sr-only')?.textContent).toBe(
+ 'Tracked on ChatGPT, ChatGPT API, Gemini, Google AI Overview, Perplexity, Grok · Tracked in United States, United Kingdom, Germany',
+ );
+ });
+
+ it('says nothing when Affected already names the one place, or there is none', () => {
+ render(
+ <SignalWhereLine
+ where={{ platforms: ['gemini-web'], regions: [] }}
+ besides={['Gemini', null]}
+ />,
+ );
+ expect(container.textContent).toBe('');
+ render(<SignalWhereLine where={{ platforms: [], regions: [] }} />);
+ expect(container.textContent).toBe('');
+ });
+});
diff --git a/web/src/components/action-center/signal-table.tsx b/web/src/components/action-center/signal-table.tsx
index 18035a37f..060a842fb 100644
--- a/web/src/components/action-center/signal-table.tsx
+++ b/web/src/components/action-center/signal-table.tsx
@@ -23,6 +23,7 @@ import {
Quote,
Wrench,
} from 'lucide-react';
+import { AIProviderAvatar, type AIProviderKey } from '@/components/ai-provider-avatar';
import { Badge } from '@/components/ui/badge';
import {
DropdownMenu,
@@ -48,6 +49,8 @@ import {
type SignalStatus,
} from '@/lib/signals/registry';
import { signalAffected, signalTexts } from '@/lib/signals/display';
+import { locationName, platformFamily, platformName } from '@/lib/signals/names';
+import type { SignalWhere } from '@/lib/signals/where';
import { formatRelative } from '@/lib/format-relative';
import { cn } from '@/lib/utils';
@@ -184,6 +187,86 @@ export function SignalKindIcon({
return <Icon className={className} />;
}
+const MAX_PLATFORM_ICONS = 4;
+const MAX_LOCATIONS = 2;
+
+/**
+ * Where a signal happened (AC-002), as one line under Affected: an icon per
+ * engine, then the location codes, with every platform and location named on
+ * hover. A line rather than its own column, because the table is already as
+ * wide as the page beside a pinned sidebar. Signals about a competitor, a
+ * domain or the whole brand have no place of their own and show nothing, and
+ * neither does a signal whose one place Affected already names ("Gemini").
+ */
+export function SignalWhereLine({
+ where,
+ besides = [],
+}: {
+ where: SignalWhere;
+ /** What the cell already says, so a lone platform or location isn't repeated. */
+ besides?: (string | null)[];
+}) {
+ const t = useTranslations('actionCenter.signalsPage');
+ const places = [...where.platforms.map(platformName), ...where.regions.map(locationName)];
+ if (places.length === 0 || (places.length === 1 && besides.includes(places[0]))) return null;
+
+ // Engines sharing one icon (the ChatGPT app and its API) show it once.
+ const engines = new Map<string, { family: AIProviderKey | null; names: string[] }>();
+ for (const slug of where.platforms) {
+ const family = platformFamily(slug);
+ const key = family ?? slug;
+ const entry = engines.get(key) ?? { family, names: [] };
+ entry.names.push(platformName(slug));
+ engines.set(key, entry);
+ }
+ const shown = [...engines.entries()].slice(0, MAX_PLATFORM_ICONS);
+ const hidden = engines.size - shown.length;
+ const platformNames = [...engines.values()].flatMap((engine) => engine.names).join(', ');
+ const locationNames = where.regions.map(locationName).join(', ');
+ const locations = where.regions.slice(0, MAX_LOCATIONS);
+ const label = [
+ platformNames && t('where.platforms', { names: platformNames }),
+ locationNames && t('where.locations', { names: locationNames }),
+ ]
+ .filter(Boolean)
+ .join(' · ');
+
+ return (
+ <div className="mt-1 flex min-w-0 items-center gap-1 overflow-hidden" title={label}>
+ <span className="sr-only">{label}</span>
+ {shown.map(([key, { family, names }]) =>
+ family ? (
+ <span key={key} aria-hidden="true" className="flex shrink-0">
+ <AIProviderAvatar provider={family} className="h-4 w-4 shrink-0" />
+ </span>
+ ) : (
+ <span key={key} aria-hidden="true" className="min-w-0 truncate text-xs">
+ {names[0]}
+ </span>
+ ),
+ )}
+ {hidden > 0 && (
+ <span aria-hidden="true" className="shrink-0 text-xs text-muted-foreground">
+ +{hidden}
+ </span>
+ )}
+ {locations.length > 0 && (
+ <span
+ aria-hidden="true"
+ className={cn(
+ 'min-w-0 truncate text-xs text-muted-foreground',
+ engines.size > 0 && 'ml-1',
+ )}
+ >
+ {locations.join(' · ')}
+ {where.regions.length > locations.length &&
+ ` +${where.regions.length - locations.length}`}
+ </span>
+ )}
+ </div>
+ );
+}
+
export function SignalTable({
signals,
onSelect,
@@ -256,6 +339,10 @@ export function SignalTable({
{affected.detail && (
<p className="truncate text-xs text-muted-foreground">{affected.detail}</p>
)}
+ <SignalWhereLine
+ where={signal.where}
+ besides={[affected.label, affected.detail]}
+ />
</TableCell>
<TableCell>
<p className="text-xs tabular-nums">
diff --git a/web/src/lib/actions/signals.ts b/web/src/lib/actions/signals.ts
index d24f41c54..74b7b81de 100644
--- a/web/src/lib/actions/signals.ts
+++ b/web/src/lib/actions/signals.ts
@@ -18,6 +18,7 @@ import type {
SignalStatus,
} from '@/lib/signals/registry';
import { SIGNAL_ROW_COLUMNS, mapSignalRows, type Signal, type SignalRow } from '@/lib/signals/map';
+import type { PromptPlace } from '@/lib/signals/where';
export type { Signal } from '@/lib/signals/map';
@@ -37,6 +38,9 @@ export interface SignalFilters {
* PostgREST 1000-row cap) rather than paged: per-brand signal counts are
* tens — the detectors' own thresholds and dedup bound them — and search
* plus pagination happen client-side over composed titles anyway.
+ *
+ * The brand's prompts are read alongside, so each signal can say which
+ * platforms and locations it is about (AC-002).
*/
export async function getSignals(brandId: string, filters: SignalFilters): Promise<Signal[]> {
const supabase = await createClient();
@@ -54,10 +58,44 @@ export async function getSignals(brandId: string, filters: SignalFilters): Promi
if (filters.status) query = query.eq('status', filters.status);
if (filters.source) query = query.contains('source', [filters.source]);
- const { data, error } = await query;
+ const [{ data, error }, prompts] = await Promise.all([query, getPromptPlaces(supabase, brandId)]);
if (error) throw new Error(error.message);
- return mapSignalRows((data ?? []) as SignalRow[]);
+ return mapSignalRows((data ?? []) as SignalRow[], prompts);
+}
+
+/**
+ * Where each of the brand's prompts is tracked, by id. Paged, because a
+ * brand can hold more prompts than one PostgREST response carries. A failed
+ * read costs the Where line, not the page, so it is logged and the page
+ * shows signals without it.
+ */
+async function getPromptPlaces(
+ supabase: Awaited<ReturnType<typeof createClient>>,
+ brandId: string,
+): Promise<Map<string, PromptPlace>> {
+ const places = new Map<string, PromptPlace>();
+ for (let from = 0; ; from += 1000) {
+ const { data, error } = await supabase
+ .from('prompts')
+ .select('id, platforms, regions, topic_id, is_active, prompt_sets!inner(brand_id)')
+ .eq('prompt_sets.brand_id', brandId)
+ .order('id')
+ .range(from, from + 999);
+ if (error) {
+ console.error('[signals] prompt places read failed:', error.message);
+ return new Map();
+ }
+ for (const row of data ?? []) {
+ places.set(row.id, {
+ platforms: row.platforms ?? [],
+ regions: row.regions ?? [],
+ topicId: row.topic_id,
+ isActive: row.is_active,
+ });
+ }
+ if ((data ?? []).length < 1000) return places;
+ }
}
export interface SignalsSummary {
diff --git a/web/src/lib/signals/display.test.ts b/web/src/lib/signals/display.test.ts
new file mode 100644
index 000000000..c8faf1eda
--- /dev/null
+++ b/web/src/lib/signals/display.test.ts
@@ -0,0 +1,125 @@
+import { createTranslator } from 'next-intl';
+import { describe, expect, it } from 'vitest';
+import messages from '../../../messages/en.json';
+import type { Signal } from './map';
+import { NO_WHERE } from './where';
+import { signalAffected, signalTexts } from './display';
+
+// The real English copy, behind the plain (key, values) shape the display
+// helpers take from useTranslations.
+function translator(namespace: 'actionCenter.signalTexts' | 'actionCenter.signalsPage') {
+ const t = createTranslator({ locale: 'en', messages, namespace });
+ return (key: string, values?: Record<string, string | number>) =>
+ t(key as Parameters<typeof t>[0], values);
+}
+const tTexts = translator('actionCenter.signalTexts');
+const tPage = translator('actionCenter.signalsPage');
+
+const signal = (over: Partial<Signal>): Signal => ({
+ id: 's1',
+ category: 'visibility',
+ kind: 'platform_drop',
+ impact: 'high',
+ status: 'new',
+ source: ['ai_results'],
+ detectedAt: '2026-10-08T10:53:00Z',
+ lastDetectedAt: '2026-10-08T10:53:00Z',
+ resolvedAt: null,
+ previousValue: null,
+ currentValue: null,
+ changeValue: null,
+ payload: {},
+ kpiKeys: [],
+ actionId: null,
+ where: NO_WHERE,
+ ...over,
+});
+
+describe('signalTexts', () => {
+ it('names the platform and says how far its mention rate fell', () => {
+ const drop = signal({
+ payload: {
+ entity: 'platforms',
+ platform: 'gemini-web',
+ targets: [{ id: 'gemini-web', label: 'gemini-web' }],
+ },
+ previousValue: 34,
+ currentValue: 18,
+ changeValue: -16,
+ });
+ expect(signalTexts(drop, tTexts)).toEqual({
+ title: 'Visibility dropped on Gemini',
+ description: 'Your mention rate fell from 34% to 18% against the week before.',
+ });
+ expect(signalAffected(drop, tPage)).toEqual({ label: 'Gemini', detail: null });
+ });
+
+ it('names the weak country and the strongest one beside it', () => {
+ const gap = signal({
+ kind: 'country_gap',
+ payload: {
+ entity: 'regions',
+ region: 'JP',
+ bestRegion: 'US',
+ targets: [{ id: 'JP', label: 'JP' }],
+ },
+ previousValue: 22.5,
+ currentValue: 3.1,
+ });
+ expect(signalTexts(gap, tTexts)).toEqual({
+ title: 'Weak in Japan',
+ description: 'You are mentioned in 3.1% of answers here, against 22.5% in United States.',
+ });
+ });
+
+ it("spells out a source's answers instead of the unlabeled 0 → 251 +167", () => {
+ const source = signal({
+ category: 'competitor',
+ kind: 'competitor_winning_source',
+ payload: {
+ entity: 'sources',
+ domain: 'yotpo.com',
+ prompts: 6,
+ results: 251,
+ targets: [{ id: 'yotpo.com', label: 'yotpo.com' }],
+ },
+ previousValue: 0,
+ currentValue: 251,
+ changeValue: 167,
+ });
+ expect(signalTexts(source, tTexts).description).toBe(
+ 'Cited in 251 answers across 6 prompts this week. Competitors alone are named in 167 of them; you in none.',
+ );
+ });
+
+ it("gives a topic's coverage against its prompt count", () => {
+ const topic = signal({
+ kind: 'topic_drop',
+ payload: {
+ entity: 'topics',
+ topicName: 'AEO',
+ prompts: 12,
+ targets: [{ id: 't1', label: 'AEO' }],
+ },
+ previousValue: 50,
+ currentValue: 25,
+ });
+ expect(signalTexts(topic, tTexts)).toEqual({
+ title: 'Coverage dropped in AEO',
+ description: 'You now appear on 25% of its 12 prompts, down from 50%.',
+ });
+ });
+
+ it('names both models a platform gap compares', () => {
+ const gap = signal({
+ kind: 'platform_gap',
+ payload: { platform: 'chatgpt-web', bestPlatform: 'gpt-5-6' },
+ previousValue: 30,
+ currentValue: 3.8,
+ });
+ expect(signalTexts(gap, tTexts)).toEqual({
+ title: 'Weak on ChatGPT',
+ description: 'You are visible in 30% of ChatGPT (gpt-5-6) answers, but only 3.8% on ChatGPT.',
+ });
+ });
+});
diff --git a/web/src/lib/signals/display.ts b/web/src/lib/signals/display.ts
index 875cfe385..22e09332e 100644
--- a/web/src/lib/signals/display.ts
+++ b/web/src/lib/signals/display.ts
@@ -1,5 +1,6 @@
import type { Signal } from '@/lib/actions/signals';
import { isLibrarySignalKind } from '@/lib/signals/registry';
+import { locationName, platformName, targetName } from '@/lib/signals/names';
/**
* Composes the display strings a signal row shows from `kind` + `payload`.
@@ -16,22 +17,37 @@ function str(payload: Record<string, unknown>, key: string): string {
}
/**
- * A library signal's copy: what it is about, named from its targets.
+ * A library signal's copy: what it is about, named from its targets, and the
+ * measured fact behind it.
*
* The V1 library's detectors all write the same shape — an entity and a list
- * of targets — so their copy needs two values: how many ("11 prompts") for a
- * finding about a group, and which one ("gemini-web", a topic, a domain) for a
- * finding about a single thing.
+ * of targets — so their titles need two values: how many ("11 prompts") for a
+ * finding about a group, and which one (a platform, a topic, a domain) for a
+ * finding about a single thing. Descriptions also carry the row's numbers, so
+ * a row says what was measured rather than only what kind of finding it is
+ * (AC-002). Each family stores its numbers in the same three columns with
+ * its own meaning, named here once.
*/
function librarySignalTexts(signal: Signal, t: Translator): { title: string; description: string } {
const p = signal.payload ?? {};
const targets = Array.isArray(p.targets) ? (p.targets as Array<{ label?: string }>) : [];
const entity = str(p, 'entity');
const count = entity === '' ? 0 : Math.max(targets.length, Number(signal.currentValue ?? 0));
- const values = {
+ const values: Record<string, string | number> = {
targets: entity ? t(`targets.${entity}`, { count }) : '',
- name: targets[0]?.label ?? '',
+ name: targetName(entity, targets[0]?.label ?? ''),
+ from: signal.previousValue ?? 0,
+ to: signal.currentValue ?? 0,
+ prompts: Number(p.prompts ?? 0),
};
+ if (entity === 'regions') values.best = locationName(str(p, 'bestRegion'));
+ if (entity === 'sources') {
+ // ae_citation_sources: answers citing the domain, those naming the brand,
+ // and those naming only competitors, over the last week.
+ values.answers = signal.currentValue ?? 0;
+ values.withBrand = signal.previousValue ?? 0;
+ values.competitorOnly = signal.changeValue ?? 0;
+ }
return {
title: t(`${signal.kind}.title`, values),
description: t(`${signal.kind}.description`, values),
@@ -48,8 +64,8 @@ export function signalTexts(signal: Signal, t: Translator): { title: string; des
return { from: signal.previousValue ?? 0, to: signal.currentValue ?? 0 };
case 'platform_gap':
return {
- platform: str(p, 'platform'),
- best: str(p, 'bestPlatform'),
+ platform: platformName(str(p, 'platform')),
+ best: platformName(str(p, 'bestPlatform')),
rate: signal.currentValue ?? 0,
bestRate: signal.previousValue ?? 0,
};
@@ -62,7 +78,7 @@ export function signalTexts(signal: Signal, t: Translator): { title: string; des
case 'prompt_gain':
return { prompt: str(p, 'promptText'), gain: signal.changeValue ?? 0 };
case 'new_engine':
- return { platform: str(p, 'platform') };
+ return { platform: platformName(str(p, 'platform')) };
case 'lost_citations':
return { prompt: str(p, 'promptText') };
case 'first_citation':
@@ -110,10 +126,12 @@ export function signalAffected(
const targets = Array.isArray(p.targets) ? (p.targets as Array<{ label?: string }>) : [];
const entity = str(p, 'entity');
const count = Math.max(targets.length, Number(signal.currentValue ?? 0));
- if (targets.length === 1) return { label: targets[0]?.label ?? '', detail: null };
+ if (targets.length === 1) {
+ return { label: targetName(entity, targets[0]?.label ?? ''), detail: null };
+ }
return {
label: entity ? t(`affected.${entity}`, { count }) : '',
- detail: targets[0]?.label ?? null,
+ detail: targets[0]?.label ? targetName(entity, targets[0].label) : null,
};
}
switch (signal.kind) {
@@ -121,14 +139,14 @@ export function signalAffected(
case 'visibility_slipping':
return { label: t('affected.allPrompts'), detail: null };
case 'platform_gap':
- return { label: t('affected.platform'), detail: str(p, 'platform') };
+ return { label: t('affected.platform'), detail: platformName(str(p, 'platform')) };
case 'competitor_citation_gap':
return { label: t('affected.competitor'), detail: str(p, 'competitorName') };
case 'prompt_gain':
case 'lost_citations':
return { label: t('affected.prompts', { count: 1 }), detail: str(p, 'promptText') };
case 'new_engine':
- return { label: t('affected.platform'), detail: str(p, 'platform') };
+ return { label: t('affected.platform'), detail: platformName(str(p, 'platform')) };
case 'first_citation':
return { label: t('affected.urls', { count: 1 }), detail: str(p, 'label') || str(p, 'url') };
case 'competitor_surge':
diff --git a/web/src/lib/signals/map.ts b/web/src/lib/signals/map.ts
index f43f5703d..dcb5061e5 100644
--- a/web/src/lib/signals/map.ts
+++ b/web/src/lib/signals/map.ts
@@ -6,6 +6,7 @@ import {
type SignalSource,
type SignalStatus,
} from './registry';
+import { NO_WHERE, signalWhere, type PromptPlace, type SignalWhere } from './where';
/**
* Row → domain mapping for signals, shared by every server action that
@@ -30,6 +31,8 @@ export interface Signal {
payload: Record<string, unknown>;
kpiKeys: string[];
actionId: string | null;
+ /** The platforms and locations the signal is about; empty when it has none. */
+ where: SignalWhere;
}
export interface SignalRow {
@@ -54,8 +57,12 @@ export const SIGNAL_ROW_COLUMNS =
'id, category, kind, impact, status, source, detected_at, last_detected_at, resolved_at, previous_value, current_value, change_value, payload, kpi_keys, action_id';
/** Maps rows, silently skipping unknown kinds (a detector removed from the
- * registry must not take down a page). */
-export function mapSignalRows(rows: SignalRow[]): Signal[] {
+ * registry must not take down a page). Without the brand's prompts, `where`
+ * holds only what the payload itself names. */
+export function mapSignalRows(
+ rows: SignalRow[],
+ prompts: ReadonlyMap<string, PromptPlace> = new Map(),
+): Signal[] {
return rows
.filter((row) => isSignalKind(row.kind))
.map((row) => ({
@@ -74,5 +81,6 @@ export function mapSignalRows(rows: SignalRow[]): Signal[] {
payload: row.payload ?? {},
kpiKeys: row.kpi_keys ?? [],
actionId: row.action_id,
+ where: row.payload ? signalWhere(row.payload, prompts) : NO_WHERE,
}));
}
diff --git a/web/src/lib/signals/names.test.ts b/web/src/lib/signals/names.test.ts
new file mode 100644
index 000000000..47804407b
--- /dev/null
+++ b/web/src/lib/signals/names.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { isOnPlatform, locationName, platformFamily, platformName, targetName } from './names';
+
+describe('platformName', () => {
+ it('names the tracked apps the way people know them', () => {
+ expect(platformName('gemini-web')).toBe('Gemini');
+ expect(platformName('google-aio')).toBe('Google AI Overview');
+ expect(platformName('google-aimode')).toBe('Google AI Mode');
+ expect(platformName('chatgpt-web')).toBe('ChatGPT');
+ expect(platformName('copilot-web')).toBe('Microsoft Copilot');
+ });
+
+ it('tells an API model apart from the app of the same engine', () => {
+ expect(platformName('chatgpt')).toBe('ChatGPT API');
+ expect(platformName('claude')).toBe('Claude API');
+ });
+
+ it('keeps a model id only as a qualifier', () => {
+ expect(platformName('gpt-5-6')).toBe('ChatGPT (gpt-5-6)');
+ expect(platformName('claude-sonnet-4-6')).toBe('Claude (claude-sonnet-4-6)');
+ });
+
+ it("leaves a slug it doesn't know as it is, rather than calling it ChatGPT", () => {
+ expect(platformName('deepseek-web')).toBe('deepseek-web');
+ expect(platformFamily('deepseek-web')).toBeNull();
+ expect(platformFamily('gemini')).toBe('google');
+ });
+});
+
+describe('locationName and targetName', () => {
+ it('names countries and US states', () => {
+ expect(locationName('JP')).toBe('Japan');
+ expect(locationName('US-CA')).toBe('California');
+ });
+
+ it('names platform and region targets, and leaves other labels alone', () => {
+ expect(targetName('platforms', 'gemini-web')).toBe('Gemini');
+ expect(targetName('regions', 'GB')).toBe('United Kingdom');
+ expect(targetName('topics', 'AEO')).toBe('AEO');
+ });
+});
+
+describe('isOnPlatform', () => {
+ it("matches an engine's app, API and models, and never an unknown slug", () => {
+ expect(isOnPlatform(['chatgpt'], 'openai')).toBe(true);
+ expect(isOnPlatform(['gpt-5-6'], 'openai')).toBe(true);
+ expect(isOnPlatform(['gemini-web', 'google-aio'], 'googleAio')).toBe(true);
+ expect(isOnPlatform(['gemini-web'], 'googleAio')).toBe(false);
+ expect(isOnPlatform(['deepseek-web'], 'openai')).toBe(false);
+ expect(isOnPlatform([], 'openai')).toBe(false);
+ });
+});
diff --git a/web/src/lib/signals/names.ts b/web/src/lib/signals/names.ts
new file mode 100644
index 000000000..0e6ff8ba2
--- /dev/null
+++ b/web/src/lib/signals/names.ts
@@ -0,0 +1,85 @@
+import {
+ getAIProviderDisplayName,
+ resolveAIProvider,
+ type AIProviderKey,
+} from '@/components/ai-provider-avatar';
+import { MODEL_PROVIDER_LABELS, PLATFORM_LABELS } from '@/config/platform-labels';
+import { regionLabel } from '@/lib/region';
+
+/**
+ * Human names for the platforms and locations signals store as slugs and
+ * codes (AC-001/AC-002): no raw `gemini-web` or `JP` in the Action Center.
+ */
+
+// The scraped apps and the generic engine slugs, as PLATFORM_LABELS lists
+// them, without its model entries.
+const PLATFORM_SLUGS = new Set([
+ 'chatgpt-web',
+ 'google-aio',
+ 'google-aimode',
+ 'gemini-web',
+ 'perplexity-web',
+ 'copilot-web',
+ 'grok-web',
+ 'perplexity',
+ 'copilot',
+ 'grok',
+ 'meta-ai',
+ 'google-ai-overviews',
+ 'google-ai-mode',
+]);
+
+// API models tracked beside the scraped apps of the same engine: "ChatGPT
+// API" next to "ChatGPT", never two plain "ChatGPT"s.
+const API_PLATFORMS = new Set(['chatgpt', 'gemini', 'claude']);
+
+const MODEL_PREFIXES = ['gpt-', 'claude-', 'gemini-', 'grok-', 'sonar', 'llama-'];
+
+function isModel(slug: string): boolean {
+ return slug in MODEL_PROVIDER_LABELS || MODEL_PREFIXES.some((prefix) => slug.startsWith(prefix));
+}
+
+/**
+ * The engine a platform or model belongs to (`gemini-web` and `gemini` are
+ * both Google's Gemini), or null for a slug we don't know — the shared
+ * resolver would call it ChatGPT.
+ */
+export function platformFamily(slug: string): AIProviderKey | null {
+ if (PLATFORM_SLUGS.has(slug) || API_PLATFORMS.has(slug) || isModel(slug)) {
+ return resolveAIProvider(slug);
+ }
+ return null;
+}
+
+/**
+ * A platform's human name: `gemini-web` → "Gemini", `google-aio` → "Google AI
+ * Overview". A model id (the platform-gap signal compares models) keeps the
+ * id as a qualifier, `gpt-5-6` → "ChatGPT (gpt-5-6)", since two models of one
+ * engine would otherwise read the same. An unknown slug stays as it is rather
+ * than borrowing another engine's name.
+ */
+export function platformName(slug: string): string {
+ const family = platformFamily(slug);
+ if (!family) return PLATFORM_LABELS[slug] ?? slug;
+ const name = getAIProviderDisplayName(family);
+ if (PLATFORM_SLUGS.has(slug)) return name;
+ if (API_PLATFORMS.has(slug)) return `${name} API`;
+ return `${name} (${slug})`;
+}
+
+/** Whether a signal's place includes an engine, for the Platform filter. */
+export function isOnPlatform(platforms: readonly string[], family: AIProviderKey): boolean {
+ return platforms.some((slug) => platformFamily(slug) === family);
+}
+
+/** A location's human name: `US` → "United States", `US-CA` → "California". */
+export function locationName(code: string): string {
+ return regionLabel(code);
+}
+
+/** The label a library target shows, named for people rather than for storage. */
+export function targetName(entity: string, label: string): string {
+ if (entity === 'platforms') return platformName(label);
+ if (entity === 'regions') return locationName(label);
+ return label;
+}
diff --git a/web/src/lib/signals/where.test.ts b/web/src/lib/signals/where.test.ts
new file mode 100644
index 000000000..d6fcb4d74
--- /dev/null
+++ b/web/src/lib/signals/where.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { NO_WHERE, signalWhere, type PromptPlace } from './where';
+
+const prompts = new Map<string, PromptPlace>([
+ [
+ 'p1',
+ { platforms: ['chatgpt-web', 'google-aio'], regions: ['US'], topicId: 't1', isActive: true },
+ ],
+ [
+ 'p2',
+ {
+ platforms: ['chatgpt-web', 'chatgpt-shopping'],
+ regions: ['US', 'GB'],
+ topicId: 't1',
+ isActive: true,
+ },
+ ],
+ ['p3', { platforms: ['gemini-web'], regions: [], topicId: 't2', isActive: true }],
+ // Paused: still a prompt's own place, but no longer part of its topic's measure.
+ ['p4', { platforms: ['grok-web'], regions: ['DE'], topicId: 't1', isActive: false }],
+]);
+
+describe('signalWhere', () => {
+ it('takes a platform or a location the payload names, without reading prompts', () => {
+ expect(signalWhere({ entity: 'platforms', platform: 'gemini-web' }, prompts)).toEqual({
+ platforms: ['gemini-web'],
+ regions: [],
+ });
+ expect(signalWhere({ entity: 'regions', region: 'JP', bestRegion: 'US' }, prompts)).toEqual({
+ platforms: [],
+ regions: ['JP'],
+ });
+ });
+
+ it("reads a prompt signal's place from its prompt", () => {
+ expect(signalWhere({ promptId: 'p1', promptText: 'best tracker' }, prompts)).toEqual({
+ platforms: ['chatgpt-web', 'google-aio'],
+ regions: ['US'],
+ });
+ });
+
+ it('joins several prompts, most common first, and leaves shopping out', () => {
+ expect(signalWhere({ promptIds: ['p2', 'p1'] }, prompts)).toEqual({
+ platforms: ['chatgpt-web', 'google-aio'],
+ regions: ['US', 'GB'],
+ });
+ expect(
+ signalWhere({ entity: 'prompts', targets: [{ id: 'p3' }, { id: 'p1' }] }, prompts),
+ ).toEqual({ platforms: ['chatgpt-web', 'gemini-web', 'google-aio'], regions: ['US'] });
+ });
+
+ it("reads a topic signal's place from the topic's tracked prompts, not its paused ones", () => {
+ expect(
+ signalWhere({ entity: 'topics', targets: [{ id: 't1', label: 'AEO' }] }, prompts),
+ ).toEqual({ platforms: ['chatgpt-web', 'google-aio'], regions: ['US', 'GB'] });
+ });
+
+ it('has no place for a competitor, a source domain, or a prompt it cannot find', () => {
+ expect(signalWhere({ competitorName: 'Profound' }, prompts)).toBe(NO_WHERE);
+ expect(signalWhere({ entity: 'sources', targets: [{ id: 'yotpo.com' }] }, prompts)).toBe(
+ NO_WHERE,
+ );
+ expect(signalWhere({ promptId: 'deleted' }, prompts)).toBe(NO_WHERE);
+ expect(signalWhere({ promptId: 'p4' }, prompts)).toEqual({
+ platforms: ['grok-web'],
+ regions: ['DE'],
+ });
+ });
+});
diff --git a/web/src/lib/signals/where.ts b/web/src/lib/signals/where.ts
new file mode 100644
index 000000000..a5c99c834
--- /dev/null
+++ b/web/src/lib/signals/where.ts
@@ -0,0 +1,95 @@
+/**
+ * Where a signal happened: the AI platforms and tracked locations it is about
+ * (AC-002).
+ *
+ * Signal rows have no platform or location columns. A few kinds name theirs
+ * in the payload: a platform whose visibility fell, the weakest country. The
+ * prompt and topic kinds are about prompts, and a prompt's own platforms and
+ * locations are where it was measured, so those are read from the prompts.
+ * That is where a prompt is tracked, which can be wider than where the change
+ * itself happened; the list says "Tracked on" for that reason. Kinds about a
+ * competitor, a source domain or the whole brand have no place of their own
+ * and stay empty.
+ */
+
+export interface SignalWhere {
+ /** Platform or model slugs as stored (`gemini-web`, `gpt-5-6`), most common first. */
+ platforms: string[];
+ /** Location codes (`US`, `US-CA`), most common first. Empty when untargeted. */
+ regions: string[];
+}
+
+/** Where one prompt is tracked, the topic it belongs to, and whether it still runs. */
+export interface PromptPlace {
+ platforms: string[];
+ regions: string[];
+ topicId: string | null;
+ isActive: boolean;
+}
+
+export const NO_WHERE: SignalWhere = { platforms: [], regions: [] };
+
+// Shopping answers never feed a signal (the detectors skip them), so the
+// platform would only be noise beside the engines that did.
+const IGNORED_PLATFORMS = new Set(['chatgpt-shopping']);
+
+function str(value: unknown): string | null {
+ return typeof value === 'string' && value !== '' ? value : null;
+}
+
+function targetIds(payload: Record<string, unknown>): string[] {
+ const targets = Array.isArray(payload.targets) ? (payload.targets as { id?: unknown }[]) : [];
+ return targets.map((target) => str(target?.id)).filter((id): id is string => id !== null);
+}
+
+/** Values ordered by how many of the counted items carry them, then by name. */
+function byFrequency(values: string[]): string[] {
+ const counts = new Map<string, number>();
+ for (const value of values) counts.set(value, (counts.get(value) ?? 0) + 1);
+ return [...counts.entries()]
+ .sort(([a, x], [b, y]) => y - x || a.localeCompare(b))
+ .map(([value]) => value);
+}
+
+/** The prompts a signal is about, by id: its own prompt, its list, or its prompt targets. */
+function promptIdsOf(payload: Record<string, unknown>): string[] {
+ const own = str(payload.promptId);
+ if (own) return [own];
+ if (Array.isArray(payload.promptIds)) {
+ return payload.promptIds.map(str).filter((id): id is string => id !== null);
+ }
+ return payload.entity === 'prompts' ? targetIds(payload) : [];
+}
+
+export function signalWhere(
+ payload: Record<string, unknown>,
+ prompts: ReadonlyMap<string, PromptPlace>,
+): SignalWhere {
+ const platform = str(payload.platform);
+ const region = str(payload.region);
+ if (platform || region) {
+ return { platforms: platform ? [platform] : [], regions: region ? [region] : [] };
+ }
+
+ let places: PromptPlace[] = [];
+ if (payload.entity === 'topics') {
+ // A topic is measured over its tracked prompts; a paused one ran nowhere.
+ const topics = new Set(targetIds(payload));
+ places = [...prompts.values()].filter(
+ (p) => p.isActive && p.topicId !== null && topics.has(p.topicId),
+ );
+ } else {
+ places = promptIdsOf(payload)
+ .map((id) => prompts.get(id))
+ .filter((p): p is PromptPlace => p !== undefined);
+ }
+ if (places.length === 0) return NO_WHERE;
+
+ // Each prompt counts a platform once, so "most common" means most prompts.
+ return {
+ platforms: byFrequency(
+ places.flatMap((p) => [...new Set(p.platforms)].filter((x) => !IGNORED_PLATFORMS.has(x))),
+ ),
+ regions: byFrequency(places.flatMap((p) => [...new Set(p.regions)])),
+ };
+}