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.

fix(signals): label each figure with the window its detector reads (#1069)

Cihan9767ed8e48db
diff --git a/web/messages/en.json b/web/messages/en.json
index 19068728a..8f06dec1a 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -463,8 +463,10 @@
"periods": {
"week_over_week": "Last 7 days against the 7 days before",
"fortnight_over_fortnight": "Last 14 days against the 14 days before",
+ "four_weeks_over_four_weeks": "Last 28 days against the 28 days before",
"last_7_days": "Last 7 days",
"last_fortnight": "Last 14 days",
+ "last_four_weeks": "Last 28 days",
"last_14_days": "Days with answers in the last 14 days",
"latest": "Latest data"
},
@@ -486,8 +488,8 @@
"cited_days": "Cited days"
},
"roles": {
- "before": "previous 7 days",
- "after": "last 7 days",
+ "before": "previous {days} days",
+ "after": "last {days} days",
"earlier": "earlier days",
"latest": "latest days",
"change": "change",
diff --git a/web/src/components/action-center/signal-detail-blocks.test.tsx b/web/src/components/action-center/signal-detail-blocks.test.tsx
index 48321d3a5..fb21f2bb5 100644
--- a/web/src/components/action-center/signal-detail-blocks.test.tsx
+++ b/web/src/components/action-center/signal-detail-blocks.test.tsx
@@ -107,6 +107,34 @@ describe('SignalChangeBlock', () => {
expect(container.textContent).toContain('Mentions · Profound · last 7 days31');
});
+ it('names the window of each figure a cross-channel finding mixes', () => {
+ render(
+ <SignalChangeBlock
+ signal={signal({
+ category: 'traffic',
+ kind: 'cross_channel_risk',
+ payload: {
+ entity: 'pages',
+ targets: [{ id: 'site' }],
+ clicksBefore: 900,
+ clicksNow: 600,
+ },
+ previousValue: 120,
+ currentValue: 80,
+ changeValue: -40,
+ })}
+ />,
+ );
+ const text = container.textContent ?? '';
+ expect(text).toContain('Last 14 days against the 14 days before');
+ expect(text).toContain('AI referral sessions · previous 14 days120');
+ expect(text).toContain('AI referral sessions · last 14 days80');
+ expect(text).toContain('Last 28 days against the 28 days before');
+ expect(text).toContain('Search clicks · previous 28 days900');
+ expect(text).toContain('Search clicks · last 28 days600');
+ expect(text).not.toContain('7 days');
+ });
+
it("names a source's counts rather than showing 0 → 251 +167", () => {
render(
<SignalChangeBlock
diff --git a/web/src/components/action-center/signal-detail-blocks.tsx b/web/src/components/action-center/signal-detail-blocks.tsx
index c8c87321a..05ea0fffd 100644
--- a/web/src/components/action-center/signal-detail-blocks.tsx
+++ b/web/src/components/action-center/signal-detail-blocks.tsx
@@ -11,9 +11,11 @@ import { crawlerName, locationName, platformFamily, platformName } from '@/lib/s
import { getPlatformName } from '@/lib/traffic-platforms';
import {
METRIC_UNITS,
+ PERIOD_DAYS,
signalChange,
signalLinks,
signalWhereFields,
+ type ChangePeriod,
type SignalFigure,
type WhereValue,
} from '@/lib/signals/detail';
@@ -493,7 +495,7 @@ export function SignalWhereBlock({ signal }: { signal: Signal }) {
);
}
-function useFigureText() {
+function useFigureText(period: ChangePeriod) {
const t = useTranslations('actionCenter.signalsPage.drawer.change');
const format = useFormatter();
@@ -525,7 +527,11 @@ function useFigureText() {
return [
t(`metrics.${figure.metric}`),
overTime && name ? name : null,
- t(`roles.${figure.role}`, { name: name || t('roles.unnamed') }),
+ t(`roles.${figure.role}`, {
+ name: name || t('roles.unnamed'),
+ // Only a before and an after say their days: "previous 14 days".
+ days: PERIOD_DAYS[period] ?? '',
+ }),
]
.filter(Boolean)
.join(' · ');
@@ -536,7 +542,6 @@ function useFigureText() {
export function SignalChangeBlock({ signal }: { signal: Signal }) {
const t = useTranslations('actionCenter.signalsPage.drawer');
- const { value, label } = useFigureText();
const change = signalChange(signal);
return (
@@ -553,46 +558,16 @@ export function SignalChangeBlock({ signal }: { signal: Signal }) {
</p>
<div className="mt-2 space-y-2">
{groupByMetric(change.figures).map((figures) => {
- const before = figures.find((f) => f.role === 'before' || f.role === 'earlier');
- const after = figures.find((f) => f.role === 'after' || f.role === 'latest');
- if (before && after) {
- // Days out of different totals have no meaningful difference.
- const delta =
- after.of === undefined
- ? { metric: after.metric, value: after.value - before.value }
- : { metric: after.metric, value: 0 };
- // A rise is good news for the brand's own numbers and bad news
- // for a competitor's.
- const good = delta.value >= 0 !== (after.subjectType === 'competitor');
- return (
- <div key={after.metric} className="flex flex-wrap items-center gap-2">
- <FigureBox label={label(before)} value={value(before)} />
- <ArrowRight className="h-3.5 w-3.5 text-muted-foreground" aria-hidden="true" />
- <FigureBox label={label(after)} value={value(after)} />
- {delta.value !== 0 && (
- <span
- className={cn(
- 'text-xs font-medium',
- good
- ? 'text-green-600 dark:text-green-400'
- : 'text-red-600 dark:text-red-400',
- )}
- >
- {value(delta, true)}
- </span>
- )}
- </div>
- );
- }
+ // A metric read over another window says which, above its row.
+ const period = figures[0].period ?? change.period;
return (
- <div key={figures[0].metric + figures[0].role} className="flex flex-wrap gap-2">
- {figures.map((figure) => (
- <FigureBox
- key={figure.role + (figure.subject ?? '')}
- label={label(figure)}
- value={value(figure, figure.role === 'change')}
- />
- ))}
+ <div key={figures[0].metric}>
+ {period !== change.period && (
+ <p className="mb-1 text-xs text-muted-foreground">
+ {t(`change.periods.${period}`)}
+ </p>
+ )}
+ <FigureRow figures={figures} period={period} />
</div>
);
})}
@@ -603,6 +578,51 @@ export function SignalChangeBlock({ signal }: { signal: Signal }) {
);
}
+/** One metric's figures: a before and an after with the difference, or side by side. */
+function FigureRow({ figures, period }: { figures: SignalFigure[]; period: ChangePeriod }) {
+ const { value, label } = useFigureText(period);
+ const before = figures.find((f) => f.role === 'before' || f.role === 'earlier');
+ const after = figures.find((f) => f.role === 'after' || f.role === 'latest');
+ if (before && after) {
+ // Days out of different totals have no meaningful difference.
+ const delta =
+ after.of === undefined
+ ? { metric: after.metric, value: after.value - before.value }
+ : { metric: after.metric, value: 0 };
+ // A rise is good news for the brand's own numbers and bad news for a
+ // competitor's.
+ const good = delta.value >= 0 !== (after.subjectType === 'competitor');
+ return (
+ <div className="flex flex-wrap items-center gap-2">
+ <FigureBox label={label(before)} value={value(before)} />
+ <ArrowRight className="h-3.5 w-3.5 text-muted-foreground" aria-hidden="true" />
+ <FigureBox label={label(after)} value={value(after)} />
+ {delta.value !== 0 && (
+ <span
+ className={cn(
+ 'text-xs font-medium',
+ good ? 'text-green-600 dark:text-green-400' : 'text-red-600 dark:text-red-400',
+ )}
+ >
+ {value(delta, true)}
+ </span>
+ )}
+ </div>
+ );
+ }
+ return (
+ <div className="flex flex-wrap gap-2">
+ {figures.map((figure) => (
+ <FigureBox
+ key={figure.role + (figure.subject ?? '')}
+ label={label(figure)}
+ value={value(figure, figure.role === 'change')}
+ />
+ ))}
+ </div>
+ );
+}
+
/** Figures of one metric together, in their order: one comparison per row. */
function groupByMetric(figures: SignalFigure[]): SignalFigure[][] {
const groups = new Map<string, SignalFigure[]>();
diff --git a/web/src/lib/mcp/server.ts b/web/src/lib/mcp/server.ts
index 98711641f..eb09fd173 100644
--- a/web/src/lib/mcp/server.ts
+++ b/web/src/lib/mcp/server.ts
@@ -954,7 +954,7 @@ export function createMcpServer(auth: McpAuthContext): McpServer {
'list_signals',
{
description:
- "List the signals the Action Center detected for a brand: measured changes such as a visibility drop, a competitor gaining citations or a page losing AI traffic. Newest first. Each signal carries its raw row (previous_value, current_value, change_value, payload, action_id) and, read from it: `where` (the prompt, topic, platforms with names, locations, domain, competitor or pages it is about; a field is null when no detector records it yet), `change` (labelled figures: metric, role such as before/after or you/competitor, value, unit and the period, e.g. 'week_over_week'; null when the signal records no figures), `evidence` (first and last detection, and app paths that show the underlying answers) and `used_by_actions` (the actions built on it). Prefer `change` over the raw value columns: their meaning differs per signal kind. Use this to explain why an action exists or what has changed recently.",
+ "List the signals the Action Center detected for a brand: measured changes such as a visibility drop, a competitor gaining citations or a page losing AI traffic. Newest first. Each signal carries its raw row (previous_value, current_value, change_value, payload, action_id) and, read from it: `where` (the prompt, topic, platforms with names, locations, domain, competitor or pages it is about; a field is null when no detector records it yet), `change` (labelled figures: metric, role such as before/after or you/competitor, value, unit and the period it covers, e.g. 'week_over_week', given per figure since one finding can mix windows; null when the signal records no figures), `evidence` (first and last detection, and app paths that show the underlying answers) and `used_by_actions` (the actions built on it). Prefer `change` over the raw value columns: their meaning differs per signal kind. Use this to explain why an action exists or what has changed recently.",
inputSchema: {
brand_id: relaxedUuid.describe('Brand UUID, from list_brands.'),
status: z
diff --git a/web/src/lib/signals/detail.test.ts b/web/src/lib/signals/detail.test.ts
index 50769b028..baf195550 100644
--- a/web/src/lib/signals/detail.test.ts
+++ b/web/src/lib/signals/detail.test.ts
@@ -280,6 +280,7 @@ describe('signalDetailForApi', () => {
subject: null,
subject_type: null,
of: null,
+ period: 'week_over_week',
});
});
});
@@ -596,6 +597,59 @@ describe('the AI-traffic windows', () => {
expect(signalChange(drop)?.period).toBe('fortnight_over_fortnight');
});
+ const crossChannel = signal({
+ category: 'traffic',
+ kind: 'cross_channel_risk',
+ payload: { entity: 'pages', targets: [{ id: 'site' }], clicksBefore: 900, clicksNow: 600 },
+ previousValue: 120,
+ currentValue: 80,
+ });
+ const trafficLoss = signal({
+ category: 'traffic',
+ kind: 'visibility_traffic_loss',
+ payload: { entity: 'pages', targets: [{ id: 'site' }], mentionsBefore: 40, mentionsNow: 25 },
+ previousValue: 120,
+ currentValue: 80,
+ });
+
+ it('gives a cross-channel finding the window each of its figures was read over', () => {
+ // AI sessions over 14 days, search clicks over Search Console's 28.
+ const risk = signalChange(crossChannel);
+ expect(risk?.period).toBe('fortnight_over_fortnight');
+ expect(risk?.figures.map((f) => f.period)).toEqual([
+ undefined,
+ undefined,
+ 'four_weeks_over_four_weeks',
+ 'four_weeks_over_four_weeks',
+ ]);
+ // AI sessions over 14 days, mentions over the library's 7.
+ const loss = signalChange(trafficLoss);
+ expect(loss?.period).toBe('fortnight_over_fortnight');
+ expect(loss?.figures.map((f) => f.period)).toEqual([
+ undefined,
+ undefined,
+ 'week_over_week',
+ 'week_over_week',
+ ]);
+ });
+
+ it("gives every figure's window to the MCP tools", () => {
+ const windows = (s: Signal) =>
+ signalDetailForApi(s, []).change?.figures.map((f) => `${f.metric}:${f.period}`);
+ expect(windows(crossChannel)).toEqual([
+ 'ai_sessions:fortnight_over_fortnight',
+ 'ai_sessions:fortnight_over_fortnight',
+ 'search_clicks:four_weeks_over_four_weeks',
+ 'search_clicks:four_weeks_over_four_weeks',
+ ]);
+ expect(windows(trafficLoss)).toEqual([
+ 'ai_sessions:fortnight_over_fortnight',
+ 'ai_sessions:fortnight_over_fortnight',
+ 'mentions:week_over_week',
+ 'mentions:week_over_week',
+ ]);
+ });
+
it('asks a site-wide finding where its visits come from, not which prompts', () => {
const site = signal({
category: 'traffic',
@@ -718,3 +772,27 @@ describe("an AI-traffic finding's pages", () => {
});
});
});
+
+describe('the Search Console windows', () => {
+ it('says the Search Console findings count queries over 28 days, not 7', () => {
+ const kinds = [
+ 'gsc_demand_gap',
+ 'search_ai_misalignment',
+ 'gsc_low_ctr',
+ 'gsc_risk',
+ 'gsc_decline',
+ ] as const;
+ for (const kind of kinds) {
+ const queries = signal({
+ category: 'traffic',
+ kind,
+ payload: { entity: 'queries', targets: [{ id: 'aeo tools' }, { id: 'aeo audit' }] },
+ currentValue: 2,
+ });
+ expect(signalChange(queries)).toEqual({
+ period: 'last_four_weeks',
+ figures: [{ metric: 'queries', role: 'total', value: 2 }],
+ });
+ }
+ });
+});
diff --git a/web/src/lib/signals/detail.ts b/web/src/lib/signals/detail.ts
index 56297e734..d63146bfe 100644
--- a/web/src/lib/signals/detail.ts
+++ b/web/src/lib/signals/detail.ts
@@ -93,18 +93,37 @@ export interface SignalFigure {
subjectType?: 'competitor' | 'platform' | 'location';
/** Out of how many, for a count of days: 9 of 11. */
of?: number;
+ /**
+ * Its own window, where it differs from the change's: a cross-channel
+ * finding sets 14 days of AI sessions beside 28 days of search clicks.
+ */
+ period?: ChangePeriod;
}
-/** The window the figures cover. The detectors all read 7-day windows. */
+/**
+ * The window the figures cover. The library's detectors read 7-day windows,
+ * AI traffic 14 (server signals/traffic-evidence.js) and Search Console 28
+ * (server signals/library/detect.js, `ctx.gsc`).
+ */
export type ChangePeriod =
| 'week_over_week'
/** The AI-traffic detector's windows (server signals/traffic-evidence.js). */
| 'fortnight_over_fortnight'
+ /** The Search Console detector's windows. */
+ | 'four_weeks_over_four_weeks'
| 'last_7_days'
| 'last_14_days'
| 'last_fortnight'
+ | 'last_four_weeks'
| 'latest';
+/** Days in each window of a before-and-after period: "previous 14 days". */
+export const PERIOD_DAYS: Partial<Record<ChangePeriod, number>> = {
+ week_over_week: 7,
+ fortnight_over_fortnight: 14,
+ four_weeks_over_four_weeks: 28,
+};
+
export interface SignalChange {
period: ChangePeriod;
figures: SignalFigure[];
@@ -115,7 +134,7 @@ function str(payload: Record<string, unknown>, key: string): string {
return typeof value === 'string' ? value : '';
}
-/** Kinds whose two values are the previous and the last 7 days of one metric. */
+/** Kinds whose two values are one metric's previous and last window. */
const WEEK_OVER_WEEK: Partial<Record<SignalKind, SignalMetric>> = {
sharp_drop: 'visibility_rate',
visibility_slipping: 'visibility_rate',
@@ -141,6 +160,15 @@ const AI_TRAFFIC_KINDS: ReadonlySet<string> = new Set([
'converting_page_slipping',
]);
+// Compared over the last 28 days against the 28 before (`ctx.gsc`).
+const SEARCH_CONSOLE_KINDS: ReadonlySet<string> = new Set([
+ 'gsc_demand_gap',
+ 'search_ai_misalignment',
+ 'gsc_low_ctr',
+ 'gsc_risk',
+ 'gsc_decline',
+]);
+
const COUNTED: Record<string, SignalMetric> = {
prompts: 'prompts',
pages: 'pages',
@@ -167,21 +195,26 @@ export function signalChange(signal: Signal): SignalChange | null {
{ metric: overTime, role: 'before', value: prev, ...about },
{ metric: overTime, role: 'after', value: cur, ...about },
];
- // The cross-channel findings say what fell beside the AI sessions.
+ // The cross-channel findings say what fell beside the AI sessions, each
+ // over the window it was read in: Search Console's 28 days, or the
+ // library's 7 for mentions (`ctx.dimensions`).
if (signal.kind === 'cross_channel_risk') {
+ const period = 'four_weeks_over_four_weeks';
figures.push(
- { metric: 'search_clicks', role: 'before', value: Number(p.clicksBefore ?? 0) },
- { metric: 'search_clicks', role: 'after', value: Number(p.clicksNow ?? 0) },
+ { metric: 'search_clicks', role: 'before', value: Number(p.clicksBefore ?? 0), period },
+ { metric: 'search_clicks', role: 'after', value: Number(p.clicksNow ?? 0), period },
);
}
if (signal.kind === 'visibility_traffic_loss') {
+ const period = 'week_over_week';
figures.push(
- { metric: 'mentions', role: 'before', value: Number(p.mentionsBefore ?? 0) },
- { metric: 'mentions', role: 'after', value: Number(p.mentionsNow ?? 0) },
+ { metric: 'mentions', role: 'before', value: Number(p.mentionsBefore ?? 0), period },
+ { metric: 'mentions', role: 'after', value: Number(p.mentionsNow ?? 0), period },
);
}
return {
- period: AI_TRAFFIC_KINDS.has(signal.kind) ? 'fortnight_over_fortnight' : 'week_over_week',
+ // AI sessions are always read over 14 days (`ctx.traffic`).
+ period: overTime === 'ai_sessions' ? 'fortnight_over_fortnight' : 'week_over_week',
figures,
};
}
@@ -337,10 +370,12 @@ export function signalChange(signal: Signal): SignalChange | null {
}
const counted = COUNTED[entity];
if (counted && cur !== null) {
- return {
- period: AI_TRAFFIC_KINDS.has(signal.kind) ? 'last_fortnight' : 'last_7_days',
- figures: [{ metric: counted, role: 'total', value: cur }],
- };
+ const period: ChangePeriod = AI_TRAFFIC_KINDS.has(signal.kind)
+ ? 'last_fortnight'
+ : SEARCH_CONSOLE_KINDS.has(signal.kind)
+ ? 'last_four_weeks'
+ : 'last_7_days';
+ return { period, figures: [{ metric: counted, role: 'total', value: cur }] };
}
return null;
}
@@ -1206,6 +1241,8 @@ export function signalDetailForApi(signal: Signal, actions: SignalActionRef[]) {
subject: f.subject ?? null,
subject_type: f.subjectType ?? null,
of: f.of ?? null,
+ // One finding can mix windows: each figure says which it covers.
+ period: f.period ?? change.period,
})),
},
evidence: {