Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
Rank tracking: trends & data exploration (#247)
Ben Senescu383531c5cd30
diff --git a/scripts/seed-rank-tracking.ts b/scripts/seed-rank-tracking.tsindex f6ba69be..11cd1cad 100644--- a/scripts/seed-rank-tracking.ts+++ b/scripts/seed-rank-tracking.ts@@ -1,248 +1,353 @@/**- * Seed the local D1 database with rank tracking data from DataForSEO.+ * Seed the local D1 database with synthetic rank-tracking history so the new+ * trends / data-exploration UI has something to show. Fully offline — no+ * DataForSEO key or network needed.+ *+ * What it creates:+ * - A both-devices config with ~20 keywords (volume / KD / CPC populated).+ * - ~16 weekly backdated check runs, each with desktop + mobile snapshots.+ * - Positions follow per-keyword trends (climbers, fallers, volatile, new,+ * lost) so the line charts, scorecards, and "Not in top N" band all have+ * realistic data — including keywords that drop out of the tracked depth.** Usage:- * pnpm seed:rank-tracking --domain=example.com [--projectId=xxx]+ * pnpm db:migrate:local # once — creates the local D1+ * pnpm seed:rank-tracking # seed demo data+ * pnpm seed:rank-tracking --domain=acme.com --runs=20 --keywords=30+ * pnpm seed:rank-tracking --projectId=<existing-project-uuid>+ *+ * Then view it:+ * env AUTH_MODE=local_noauth pnpm dev # then open Rank Tracking*- * Requires:- * - DATAFORSEO_API_KEY in .env.local or .env- * - Local D1 database (run `pnpm db:migrate:local` first)- * - At least one project in the database (start the dev server once)+ * With no --projectId, it bootstraps the local_noauth user/org/Default project+ * (the same identity `AUTH_MODE=local_noauth` uses) so the data is immediately+ * viewable. Re-running resets the demo config for the domain.*/import process from "node:process";import { getPlatformProxy } from "wrangler";import { drizzle } from "drizzle-orm/d1";-import { eq } from "drizzle-orm";-import {- DataforseoLabsApi,- DataforseoLabsGoogleRankedKeywordsLiveRequestInfo,-} from "dataforseo-client";+import { and, eq } from "drizzle-orm";import * as schema from "../src/db/schema";-import type { DomainRankedKeywordItem } from "../src/server/lib/dataforseo";-import { loadLocalEnv, parseArgs } from "./cli-utils";--loadLocalEnv();+import { parseArgs } from "./cli-utils";-const args = parseArgs(process.argv.slice(2));+const LOCAL_ADMIN_USER_ID = "local-admin";+const LOCAL_ADMIN_EMAIL = "admin@localhost";+const LOCAL_ORG_ID = `delegated-${LOCAL_ADMIN_USER_ID}`;+const LOCATION_CODE = 2840; // United States+const SERP_DEPTH = 20; // positions beyond this are stored null ("not in top 20")-await main();+type SeedDb = ReturnType<typeof drizzle<typeof schema>>;+type BatchStatement = Parameters<SeedDb["batch"]>[0][number];async function main() {- const domain = normalizeDomain(args.domain);- if (!domain) {- exitWithUsage("Missing --domain argument.");- }-- const apiKey = process.env.DATAFORSEO_API_KEY;- if (!apiKey) {- exitWithUsage("Missing DATAFORSEO_API_KEY. Set it in .env.local or .env.");- }+ const args = parseArgs(process.argv.slice(2));+ const domain = normalizeDomain(args.domain) ?? "acme-demo.com";+ const runs = clampInt(args.runs, 16, 2, 52);+ const keywordCount = clampInt(args.keywords, 20, 1, KEYWORDS.length);- console.log(`Setting up local D1 connection...`);+ console.log("Setting up local D1 connection...");const { env, dispose } = await getPlatformProxy<{ DB: D1Database }>();const db = drizzle(env.DB, { schema });try {- // Resolve project- const projectId = args.projectId ?? (await findFirstProject(db));- if (!projectId) {- exitWithUsage(- "No projects found in local DB. Start the dev server and create a project first.",- );+ const projectId = await resolveProject(db, args.projectId);+ console.log(`Using project ${projectId}`);++ // Reset any previous demo config for this domain (cascades runs/snapshots/+ // keywords) so re-running is clean.+ const removed = await db+ .delete(schema.rankTrackingConfigs)+ .where(+ and(+ eq(schema.rankTrackingConfigs.projectId, projectId),+ eq(schema.rankTrackingConfigs.domain, domain),+ ),+ )+ .returning({ id: schema.rankTrackingConfigs.id });+ if (removed.length > 0) {+ console.log(`Reset existing config for ${domain}.`);}- const existingProject = await db.query.projects.findFirst({- where: eq(schema.projects.id, projectId),- });- if (!existingProject) {- exitWithUsage(`Project ${projectId} not found in local DB.`);- }- console.log(`Using project: ${existingProject.name} (${projectId})`);-- // Check for existing config- const existingConfig = await db.query.rankTrackingConfigs.findFirst({- where: eq(schema.rankTrackingConfigs.domain, domain),- });- if (existingConfig) {- console.log(- `Rank tracking config already exists for ${domain} — skipping. Delete it manually to re-seed.`,- );- return;- }-- // Fetch top 50 keywords from DataForSEO- console.log(`Fetching top 50 keywords for ${domain} from DataForSEO...`);- const rankedItems = await fetchRankedKeywords(apiKey, domain, 50);- console.log(`Got ${rankedItems.length} ranked keywords.`);-- if (rankedItems.length === 0) {- console.log("No keywords found for this domain. Nothing to seed.");- return;- }-- // Map to keyword/position/url- const keywords = rankedItems- .map(mapKeywordItem)- .filter((k): k is NonNullable<typeof k> => k !== null);- console.log(`Mapped ${keywords.length} valid keywords.`);-- // Generate IDs+ const keywords = KEYWORDS.slice(0, keywordCount);+ const runDates = buildRunDates(runs);const configId = crypto.randomUUID();- const runId = crypto.randomUUID();- const now = new Date().toISOString();+ const newest = runDates[runDates.length - 1];- // Insert configawait db.insert(schema.rankTrackingConfigs).values({id: configId,projectId,domain,- locationCode: 2840,+ locationCode: LOCATION_CODE,languageCode: "en",- devices: "mobile",- serpDepth: 20,+ devices: "both",+ serpDepth: SERP_DEPTH,scheduleInterval: "weekly",isActive: true,- lastCheckedAt: now,+ lastCheckedAt: dbTimestamp(newest),+ createdAt: dbTimestamp(runDates[0]),});- console.log(`Created config for ${domain} (mobile, weekly).`);- // Insert keywords (batch individual statements to respect D1 bind limits)const keywordRows = keywords.map((k) => ({id: crypto.randomUUID(),configId,keyword: k.keyword,+ searchVolume: k.volume,+ keywordDifficulty: k.kd,+ cpc: k.cpc,+ metricsFetchedAt: dbTimestamp(newest),}));- const keywordStmts = keywordRows.map((row) =>- db.insert(schema.rankTrackingKeywords).values(row).onConflictDoNothing(),+ await batched(db, keywordRows, (row) =>+ db.insert(schema.rankTrackingKeywords).values(row),);- if (keywordStmts.length > 0) {- const [first, ...rest] = keywordStmts;- await db.batch([first, ...rest]);- }console.log(`Inserted ${keywordRows.length} keywords.`);- // Insert completed run- await db.insert(schema.rankCheckRuns).values({- id: runId,- configId,- projectId,- status: "completed",- keywordsTotal: keywordRows.length,- keywordsChecked: keywordRows.length,- completedAt: now,+ // One completed run per date; each run snapshots every keyword on both+ // devices.+ const runRows = runDates.map((date) => ({+ id: crypto.randomUUID(),+ date,+ }));+ await batched(db, runRows, (run) =>+ db.insert(schema.rankCheckRuns).values({+ id: run.id,+ configId,+ projectId,+ status: "completed" as const,+ keywordsTotal: keywordRows.length,+ keywordsChecked: keywordRows.length,+ startedAt: dbTimestamp(run.date),+ completedAt: dbTimestamp(run.date),+ }),+ );++ const snapshotValues: (typeof schema.rankSnapshots.$inferInsert)[] = [];+ runRows.forEach((run, runIndex) => {+ keywordRows.forEach((kw, kwIndex) => {+ const profile = KEYWORDS[kwIndex].profile;+ const rng = makeRng(kwIndex * 1000 + runIndex);+ const desktopRank = rankFor(profile, runIndex, runs, rng);+ const mobileRank =+ desktopRank === null ? null : desktopRank + 1 + (rng() - 0.5) * 1.2;+ const checkedAt = dbTimestamp(run.date);+ const path = `/${slugify(kw.keyword)}`;+ snapshotValues.push(+ snapshot(run.id, kw, "desktop", desktopRank, domain, path, checkedAt),+ snapshot(run.id, kw, "mobile", mobileRank, domain, path, checkedAt),+ );+ });});- console.log(`Created completed run.`);-- // Insert snapshots (mobile device)- const snapshotStmts = keywordRows.map((kw, i) =>- db- .insert(schema.rankSnapshots)- .values({- runId,- trackingKeywordId: kw.id,- keyword: kw.keyword,- device: "mobile" as const,- position: keywords[i].position,- url: keywords[i].url,- serpFeatures: null,- })- .onConflictDoNothing(),+ await batched(db, snapshotValues, (row) =>+ db.insert(schema.rankSnapshots).values(row),+ );+ console.log(+ `Inserted ${runRows.length} runs and ${snapshotValues.length} snapshots.`,);- if (snapshotStmts.length > 0) {- const [first, ...rest] = snapshotStmts;- await db.batch([first, ...rest]);- }- console.log(`Inserted ${keywordRows.length} snapshots.`);+ const start = runDates[0].toISOString().slice(0, 10);+ const end = newest.toISOString().slice(0, 10);console.log(- `\nDone! Seeded rank tracking for ${domain} with ${keywords.length} keywords.`,+ `\nDone. Seeded "${domain}" — ${keywordRows.length} keywords, ${runs} weekly checks (${start} → ${end}), desktop + mobile.`,);+ if (!args.projectId) {+ console.log(+ "\nView it:\n env AUTH_MODE=local_noauth pnpm dev\n → open Rank Tracking (the demo lives in the Default project).",+ );+ }} finally {await dispose();}}// ----------------------------------------------------------------------------// DataForSEO+// Project / local_noauth bootstrap// ----------------------------------------------------------------------------async function fetchRankedKeywords(- apiKey: string,- domain: string,- limit: number,-): Promise<DomainRankedKeywordItem[]> {- const api = new DataforseoLabsApi("https://api.dataforseo.com", {- fetch: (url: RequestInfo, init?: RequestInit) => {- const headers = new Headers(init?.headers);- headers.set("Authorization", `Basic ${apiKey}`);- return fetch(url, { ...init, headers });- },- });+async function resolveProject(+ db: SeedDb,+ projectIdArg: string | undefined,+): Promise<string> {+ if (projectIdArg) {+ const existing = await db.query.projects.findFirst({+ where: eq(schema.projects.id, projectIdArg),+ });+ if (!existing) {+ exit(`Project ${projectIdArg} not found in local DB.`);+ }+ return projectIdArg;+ }- const req = new DataforseoLabsGoogleRankedKeywordsLiveRequestInfo({- target: domain,- location_code: 2840,- language_code: "en",- limit,- order_by: ["keyword_data.keyword_info.search_volume,desc"],+ // Bootstrap the same user/org/Default project that AUTH_MODE=local_noauth+ // resolves, so the seeded data is viewable without signing up.+ await db+ .insert(schema.user)+ .values({+ id: LOCAL_ADMIN_USER_ID,+ name: "admin",+ email: LOCAL_ADMIN_EMAIL,+ emailVerified: true,+ })+ .onConflictDoNothing({ target: schema.user.id });++ await db+ .insert(schema.organization)+ .values({+ id: LOCAL_ORG_ID,+ name: "admin workspace",+ slug: `delegated-admin-${toHex(LOCAL_ADMIN_USER_ID)}`,+ createdAt: new Date(),+ })+ .onConflictDoNothing({ target: schema.organization.id });++ const existingDefault = await db.query.projects.findFirst({+ where: and(+ eq(schema.projects.organizationId, LOCAL_ORG_ID),+ eq(schema.projects.name, "Default"),+ ),+ });+ if (existingDefault) return existingDefault.id;++ const projectId = crypto.randomUUID();+ await db.insert(schema.projects).values({+ id: projectId,+ organizationId: LOCAL_ORG_ID,+ name: "Default",+ domain: null,});+ console.log("Bootstrapped local_noauth Default project.");+ return projectId;+}- const response = await api.googleRankedKeywordsLive([req]);+// ---------------------------------------------------------------------------+// Synthetic positions+// ---------------------------------------------------------------------------- if (!response || response.status_code !== 20000) {- throw new Error(- `DataForSEO error: ${response?.status_message ?? "unknown"}`,- );+type Profile =+ | "climber"+ | "faller"+ | "leader"+ | "volatile"+ | "steady_mid"+ | "newcomer"+ | "lost";++/** Continuous "true" desktop rank for a keyword at run `i` (0 = oldest). null =+ * not present (either not in the tracked depth yet, or dropped out). */+function rankFor(+ profile: Profile,+ i: number,+ runs: number,+ rng: () => number,+): number | null {+ const t = runs <= 1 ? 1 : i / (runs - 1); // 0..1 over the window+ const noise = rng() - 0.5;+ switch (profile) {+ case "climber":+ return 18 - 16 * t + noise * 1.5; // 18 → 2+ case "faller":+ return 3 + 22 * t + noise * 1.5; // 3 → 25 (drops out late)+ case "leader":+ return 2 + noise * 0.8; // hovers 1–3+ case "volatile":+ return 9 + Math.sin(i * 1.25) * 5 + noise * 3;+ case "steady_mid":+ return 12 + noise * 1.2; // ~11–13+ case "newcomer":+ return t < 0.4 ? null : 16 - 26 * (t - 0.4) + noise * 1.5; // appears, climbs+ case "lost":+ return t > 0.75 ? null : 7 + noise * 1.5; // ranks, then disappears}+}- const task = response.tasks?.[0];- if (!task || task.status_code !== 20000) {- throw new Error(- `DataForSEO task error: ${task?.status_message ?? "no task returned"}`,- );- }+/** Round a continuous rank and drop it to null when it falls past the depth. */+function toStored(rank: number | null): number | null {+ if (rank === null) return null;+ const r = Math.max(1, Math.round(rank));+ return r > SERP_DEPTH ? null : r;+}- return task.result?.[0]?.items ?? [];+function snapshot(+ runId: string,+ kw: { id: string; keyword: string },+ device: "desktop" | "mobile",+ rank: number | null,+ domain: string,+ path: string,+ checkedAt: string,+): typeof schema.rankSnapshots.$inferInsert {+ const position = toStored(rank);+ return {+ runId,+ trackingKeywordId: kw.id,+ keyword: kw.keyword,+ device,+ position,+ url: position === null ? null : `https://${domain}${path}`,+ serpFeatures: null,+ checkedAt,+ };}// ----------------------------------------------------------------------------// Mapping (mirrors DomainService.mapKeywordItem)+// Helpers// ----------------------------------------------------------------------------function mapKeywordItem(item: DomainRankedKeywordItem) {- const keywordData = item.keyword_data;- const rankedSerpElement = item.ranked_serp_element;- const serpItem = rankedSerpElement?.serp_item;-- const keyword = keywordData?.keyword ?? item.keyword;- if (!keyword) return null;+/** Weekly dates, oldest first, all at noon UTC (so local-time rendering can't+ * shift a point across a day boundary). */+function buildRunDates(runs: number): Date[] {+ const dates: Date[] = [];+ const base = new Date();+ base.setUTCHours(12, 0, 0, 0);+ for (let weeksAgo = runs - 1; weeksAgo >= 0; weeksAgo -= 1) {+ const d = new Date(base);+ d.setUTCDate(d.getUTCDate() - weeksAgo * 7);+ dates.push(d);+ }+ return dates;+}- const position =- serpItem?.rank_absolute ?? rankedSerpElement?.rank_absolute ?? null;- const url = serpItem?.url ?? rankedSerpElement?.url ?? null;+/** SQLite current_timestamp format (UTC): "YYYY-MM-DD HH:MM:SS". */+function dbTimestamp(d: Date): string {+ return d.toISOString().slice(0, 19).replace("T", " ");+}- return {- keyword: keyword.toLowerCase().trim(),- position: position != null ? Math.round(position) : null,- url,+/** Small seeded PRNG (mulberry32) so re-runs produce the same data. */+function makeRng(seed: number): () => number {+ let s = seed >>> 0;+ return () => {+ s = (s + 0x6d2b79f5) >>> 0;+ let t = Math.imul(s ^ (s >>> 15), 1 | s);+ t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;};}-// ----------------------------------------------------------------------------// DB helpers-// -----------------------------------------------------------------------------type SeedDb = ReturnType<typeof drizzle<typeof schema>>;+async function batched<T>(+ db: SeedDb,+ items: T[],+ buildStatement: (item: T) => BatchStatement,+): Promise<void> {+ const SIZE = 80; // statements per D1 batch transaction+ for (let i = 0; i < items.length; i += SIZE) {+ const chunk = items.slice(i, i + SIZE).map(buildStatement);+ const [first, ...rest] = chunk;+ if (!first) continue;+ await db.batch([first, ...rest]);+ }+}-async function findFirstProject(db: SeedDb): Promise<string | null> {- const row = await db.query.projects.findFirst();- return row?.id ?? null;+function slugify(value: string): string {+ return value+ .toLowerCase()+ .replace(/[^a-z0-9]+/g, "-")+ .replace(/^-|-$/g, "");}-// ----------------------------------------------------------------------------// CLI helpers-// ---------------------------------------------------------------------------+function toHex(value: string): string {+ return Array.from(new TextEncoder().encode(value), (b) =>+ b.toString(16).padStart(2, "0"),+ ).join("");+}function normalizeDomain(raw: string | undefined): string | undefined {if (!raw) return undefined;@@ -254,10 +359,167 @@ function normalizeDomain(raw: string | undefined): string | undefined {.replace(/^www\./u, "");}-function exitWithUsage(message: string): never {+function clampInt(+ raw: string | undefined,+ fallback: number,+ min: number,+ max: number,+): number {+ const n = raw ? Number.parseInt(raw, 10) : NaN;+ if (!Number.isFinite(n)) return fallback;+ return Math.min(max, Math.max(min, n));+}++function exit(message: string): never {console.error(message);- console.error(- "Usage: pnpm seed:rank-tracking --domain=example.com [--projectId=xxx]",- );process.exit(1);}++// ---------------------------------------------------------------------------+// Demo keyword set (keyword + metrics + trend profile)+// ---------------------------------------------------------------------------++const KEYWORDS: {+ keyword: string;+ volume: number;+ kd: number;+ cpc: number;+ profile: Profile;+}[] = [+ {+ keyword: "seo audit tool",+ volume: 18100,+ kd: 64,+ cpc: 9.4,+ profile: "climber",+ },+ {+ keyword: "best rank tracker",+ volume: 8100,+ kd: 58,+ cpc: 7.2,+ profile: "leader",+ },+ {+ keyword: "keyword research software",+ volume: 12100,+ kd: 71,+ cpc: 11.8,+ profile: "faller",+ },+ {+ keyword: "free backlink checker",+ volume: 27100,+ kd: 49,+ cpc: 4.1,+ profile: "volatile",+ },+ {+ keyword: "local seo services",+ volume: 6600,+ kd: 53,+ cpc: 14.2,+ profile: "newcomer",+ },+ {+ keyword: "google rank checker",+ volume: 9900,+ kd: 45,+ cpc: 5.6,+ profile: "steady_mid",+ },+ { keyword: "serp api", volume: 3600, kd: 41, cpc: 6.9, profile: "climber" },+ {+ keyword: "ai content optimization",+ volume: 2400,+ kd: 38,+ cpc: 8.3,+ profile: "newcomer",+ },+ {+ keyword: "technical seo checklist",+ volume: 4400,+ kd: 36,+ cpc: 3.2,+ profile: "leader",+ },+ {+ keyword: "competitor keyword analysis",+ volume: 2900,+ kd: 55,+ cpc: 10.1,+ profile: "lost",+ },+ {+ keyword: "domain authority checker",+ volume: 33100,+ kd: 62,+ cpc: 4.8,+ profile: "volatile",+ },+ {+ keyword: "on page seo tool",+ volume: 5400,+ kd: 47,+ cpc: 7.7,+ profile: "climber",+ },+ {+ keyword: "seo for startups",+ volume: 1900,+ kd: 29,+ cpc: 6.4,+ profile: "steady_mid",+ },+ {+ keyword: "rank tracking api",+ volume: 1300,+ kd: 34,+ cpc: 8.9,+ profile: "newcomer",+ },+ {+ keyword: "content gap analysis",+ volume: 2100,+ kd: 44,+ cpc: 9.1,+ profile: "faller",+ },+ {+ keyword: "mobile seo audit",+ volume: 1600,+ kd: 31,+ cpc: 5.0,+ profile: "leader",+ },+ {+ keyword: "schema markup generator",+ volume: 8800,+ kd: 39,+ cpc: 3.6,+ profile: "volatile",+ },+ {+ keyword: "search intent tool",+ volume: 1100,+ kd: 27,+ cpc: 7.0,+ profile: "climber",+ },+ {+ keyword: "seo reporting dashboard",+ volume: 2700,+ kd: 50,+ cpc: 12.5,+ profile: "lost",+ },+ {+ keyword: "indie hacker seo",+ volume: 720,+ kd: 22,+ cpc: 4.3,+ profile: "newcomer",+ },+];++await main();diff --git a/src/client/components/SegmentedToggle.tsx b/src/client/components/SegmentedToggle.tsxindex dc7dbe3f..303a9616 100644--- a/src/client/components/SegmentedToggle.tsx+++ b/src/client/components/SegmentedToggle.tsx@@ -10,21 +10,24 @@ export function SegmentedToggle<T extends string>({items,value,onChange,+ showLabels = false,}: {items: SegmentedToggleItem<T>[];value: T;onChange: (value: T) => void;+ showLabels?: boolean;}) {return (<div className="inline-flex rounded-lg bg-base-300 p-0.5">{items.map((item) => (<buttonkey={item.value}- className={`btn btn-xs px-2 ${value === item.value ? "bg-primary/20 text-primary shadow-sm" : "btn-ghost text-base-content/40"}`}+ className={`btn btn-xs gap-1.5 px-2 ${value === item.value ? "bg-primary/20 text-primary shadow-sm" : "btn-ghost text-base-content/40"}`}onClick={() => onChange(item.value)}title={item.label}>{item.icon}+ {showLabels && item.label}</button>))}</div>diff --git a/src/client/features/rank-tracking/ActionsMenu.tsx b/src/client/features/rank-tracking/ActionsMenu.tsxdeleted file mode 100644index 6b6c837d..00000000--- a/src/client/features/rank-tracking/ActionsMenu.tsx+++ /dev/null@@ -1,109 +0,0 @@-import { useState } from "react";-import {- Copy,- Download,- MoreHorizontal,- Play,- RefreshCw,- Sheet,-} from "lucide-react";--export function ActionsMenu({- onCheckNow,- onExport,- onExportToSheets,- onCopyKeywords,- onRefreshMetrics,- isRunning,- metricsRefreshing,- hasData,- checkDisabled,-}: {- onCheckNow: () => void;- onExport: () => void;- onExportToSheets: () => void;- onCopyKeywords: () => void;- onRefreshMetrics: () => void;- isRunning: boolean;- metricsRefreshing: boolean;- hasData: boolean;- checkDisabled?: boolean;-}) {- const [open, setOpen] = useState(false);- return (- <div className="relative">- <button- className="btn btn-ghost btn-sm gap-1"- onClick={() => setOpen((c) => !c)}- >- <MoreHorizontal className="size-4" />- </button>- {open && (- <>- <div className="fixed inset-0 z-40" onClick={() => setOpen(false)} />- <div className="absolute right-0 top-full mt-1 z-50 rounded-lg border border-base-300 bg-base-100 shadow-lg py-1 min-w-[160px]">- {!checkDisabled && (- <button- className="flex w-full items-center gap-2 px-3 py-2 text-sm hover:bg-base-200"- onClick={() => {- onCheckNow();- setOpen(false);- }}- disabled={isRunning}- >- <Play className="size-3.5" />- {isRunning ? "Running..." : "Check Now"}- </button>- )}- <button- className="flex w-full items-center gap-2 px-3 py-2 text-sm hover:bg-base-200"- onClick={() => {- onRefreshMetrics();- setOpen(false);- }}- disabled={metricsRefreshing || !hasData}- >- <RefreshCw- className={`size-3.5 ${metricsRefreshing ? "animate-spin" : ""}`}- />- {metricsRefreshing ? "Refreshing..." : "Refresh Metrics"}- </button>- <button- className="flex w-full items-center gap-2 px-3 py-2 text-sm hover:bg-base-200"- onClick={() => {- onExportToSheets();- setOpen(false);- }}- disabled={!hasData}- >- <Sheet className="size-3.5" />- Export to Sheets- </button>- <button- className="flex w-full items-center gap-2 px-3 py-2 text-sm hover:bg-base-200"- onClick={() => {- onExport();- setOpen(false);- }}- disabled={!hasData}- >- <Download className="size-3.5" />- Export CSV- </button>- <button- className="flex w-full items-center gap-2 px-3 py-2 text-sm hover:bg-base-200"- onClick={() => {- onCopyKeywords();- setOpen(false);- }}- disabled={!hasData}- >- <Copy className="size-3.5" />- Copy Keywords- </button>- </div>- </>- )}- </div>- );-}diff --git a/src/client/features/rank-tracking/KeywordTrendModal.tsx b/src/client/features/rank-tracking/KeywordTrendModal.tsxnew file mode 100644index 00000000..5a774592--- /dev/null+++ b/src/client/features/rank-tracking/KeywordTrendModal.tsx@@ -0,0 +1,398 @@+import { useMemo, useState } from "react";+import { Copy, Download, Loader2 } from "lucide-react";+import { toast } from "sonner";+import { useQuery } from "@tanstack/react-query";+import { Modal } from "@/client/components/Modal";+import { buildCsv, downloadCsv } from "@/client/lib/csv";+import { captureClientEvent } from "@/client/lib/posthog";+import { getRankKeywordHistory } from "@/serverFunctions/rank-tracking";+import type { RankKeywordHistoryPoint } from "@/serverFunctions/rank-tracking";+import { LOCATIONS } from "@/client/features/keywords/locations";+import { csvChange, DeviceRankCell } from "./RankTrackingTableParts";+import {+ RankTrendChart,+ TrendRangeToggle,+ type TrendSeries,+} from "./RankTrackingTrendChart";++const DEVICE_STYLE: Record<+ "desktop" | "mobile",+ { label: string; color: string }+> = {+ desktop: { label: "Desktop", color: "#2563eb" },+ mobile: { label: "Mobile", color: "#14b8a6" },+};++export interface KeywordTrendTarget {+ trackingKeywordId: string;+ keyword: string;+}++export function KeywordTrendModal({+ target,+ projectId,+ configId,+ domain,+ locationCode,+ serpDepth,+ onClose,+}: {+ target: KeywordTrendTarget;+ projectId: string;+ configId: string;+ domain: string;+ locationCode: number;+ serpDepth: number;+ onClose: () => void;+}) {+ const [sinceDays, setSinceDays] = useState(730);++ const { data: history, isLoading } = useQuery({+ queryKey: [+ "rankKeywordHistory",+ projectId,+ configId,+ target.trackingKeywordId,+ sinceDays,+ ],+ queryFn: () =>+ getRankKeywordHistory({+ data: {+ projectId,+ configId,+ trackingKeywordId: target.trackingKeywordId,+ sinceDays,+ },+ }),+ });++ const points = useMemo(() => history ?? [], [history]);+ const devices = useMemo(() => deriveDevices(points), [points]);++ // A single run yields one point per device, so for a both-devices config+ // `points.length` is 2 after one check. The trend only fills in once any one+ // device has 2+ checks, so gate the empty state on the per-device count.+ const maxPerDevice = useMemo(+ () =>+ devices.length === 0+ ? 0+ : Math.max(+ ...devices.map((d) => points.filter((p) => p.device === d).length),+ ),+ [points, devices],+ );++ const series: TrendSeries[] = devices.map((device) => ({+ dataKey: device,+ name: DEVICE_STYLE[device].label,+ color: DEVICE_STYLE[device].color,+ strokeDasharray: "4 3",+ }));++ const chartData = useMemo(+ () => buildChartData(points, serpDepth),+ [points, serpDepth],+ );++ // Keys ("<ts>:<device>") whose plotted point sits in the bottom band because+ // the real position was null — so the tooltip can say "Not in top N"+ // unambiguously even when a genuine position equals serpDepth.+ const bottomBandKeys = useMemo(() => {+ const keys = new Set<string>();+ for (const p of points) {+ if (p.position === null) {+ keys.add(`${new Date(p.checkedAt).getTime()}:${p.device}`);+ }+ }+ return keys;+ }, [points]);++ const historyRows = useMemo(() => buildHistoryRows(points), [points]);++ const exportRows = () =>+ historyRows.map((r) => [+ new Date(r.checkedAt).toISOString(),+ DEVICE_STYLE[r.device].label,+ r.position ?? "",+ csvChange(r.position, r.previousPosition),+ ]);++ const handleCopy = () => {+ const headers = ["Date", "Device", "Position", "Change vs previous"];+ void navigator.clipboard.writeText(buildCsv(headers, exportRows()));+ toast.success("Copied to clipboard");+ captureClientEvent("rank_tracking:keyword_trend_copy");+ };++ const handleExport = () => {+ const headers = ["Date", "Device", "Position", "Change vs previous"];+ downloadCsv(+ `rank-history-${slugify(target.keyword)}.csv`,+ buildCsv(headers, exportRows()),+ );+ captureClientEvent("rank_tracking:keyword_trend_export");+ };++ return (+ <Modal+ onClose={onClose}+ labelledBy="keyword-trend-title"+ maxWidth="max-w-3xl"+ >+ <div className="flex items-start justify-between gap-3">+ <div>+ <h3 id="keyword-trend-title" className="text-lg font-semibold">+ {target.keyword}+ </h3>+ <p className="text-xs text-base-content/60">+ {domain} · {LOCATIONS[locationCode] ?? "US"} ·+ Position over time+ </p>+ </div>+ <TrendRangeToggle value={sinceDays} onChange={setSinceDays} />+ </div>++ {isLoading ? (+ <div className="flex items-center justify-center py-16">+ <Loader2 className="size-5 animate-spin text-base-content/50" />+ </div>+ ) : maxPerDevice <= 1 ? (+ <EmptyState count={maxPerDevice} />+ ) : (+ <>+ <RankTrendChart+ data={chartData}+ series={series}+ serpDepth={serpDepth}+ showBottomBand+ renderTooltip={(label, entries) => (+ <ChartTooltip+ label={label}+ entries={entries}+ serpDepth={serpDepth}+ bottomBandKeys={bottomBandKeys}+ />+ )}+ />++ <div className="flex items-center justify-end gap-2">+ <button className="btn btn-ghost btn-xs gap-1" onClick={handleCopy}>+ <Copy className="size-3.5" />+ Copy+ </button>+ <button+ className="btn btn-ghost btn-xs gap-1"+ onClick={handleExport}+ >+ <Download className="size-3.5" />+ Export CSV+ </button>+ </div>++ <div className="max-h-64 overflow-auto rounded-lg border border-base-300">+ <table className="table table-sm">+ <thead className="sticky top-0 bg-base-100">+ <tr>+ <th>Date</th>+ {devices.length > 1 && <th>Device</th>}+ <th>Position</th>+ <th>Δ vs previous check</th>+ </tr>+ </thead>+ <tbody>+ {historyRows.map((r, idx) => {+ // No prior ranking to compare against (first check, or the+ // previous check was unranked): show the lone position as a+ // centered neutral pill so it doesn't look like a stray number+ // next to the "before → after" rows.+ const noPrevious =+ r.position !== null && r.previousPosition === null;+ return (+ <tr key={`${r.device}-${r.checkedAt}-${idx}`}>+ <td className="whitespace-nowrap text-xs">+ {new Date(r.checkedAt).toLocaleDateString()}+ </td>+ {devices.length > 1 && (+ <td className="text-xs">+ {DEVICE_STYLE[r.device].label}+ </td>+ )}+ <td>+ {r.position === null ? (+ <span className="text-base-content/40 text-xs">+ Not in top {serpDepth}+ </span>+ ) : (+ <span className="font-mono text-sm">+ {r.position}+ </span>+ )}+ </td>+ <td>+ {noPrevious ? (+ // Invisible placeholders matching the "before → after"+ // layout so the lone pill lines up under the position+ // badge column instead of floating.+ <span className="inline-flex items-center gap-1.5">+ <span className="w-6" aria-hidden />+ <span aria-hidden className="opacity-0">+ →+ </span>+ <span className="font-mono rounded bg-base-200 px-1.5 py-0.5 text-xs font-semibold text-base-content/70">+ {r.position}+ </span>+ </span>+ ) : (+ <DeviceRankCell+ result={{+ position: r.position,+ previousPosition: r.previousPosition,+ rankingUrl: null,+ serpFeatures: [],+ }}+ />+ )}+ </td>+ </tr>+ );+ })}+ </tbody>+ </table>+ </div>+ </>+ )}++ <div className="flex justify-end">+ <button className="btn btn-ghost btn-sm" onClick={onClose}>+ Close+ </button>+ </div>+ </Modal>+ );+}++function EmptyState({ count }: { count: number }) {+ return (+ <div className="rounded-lg border border-dashed border-base-300 p-10 text-center text-sm text-base-content/60">+ {count === 0+ ? "No history yet — run a check to start tracking position over time."+ : "Only 1 check so far — the trend chart fills in after the next check."}+ </div>+ );+}++function ChartTooltip({+ label,+ entries,+ serpDepth,+ bottomBandKeys,+}: {+ label: number;+ entries: Array<{ dataKey?: string | number; value: number | null }>;+ serpDepth: number;+ bottomBandKeys: Set<string>;+}) {+ return (+ <div className="rounded-md border border-base-300 bg-base-100 px-3 py-2 shadow-sm space-y-0.5">+ <p className="text-xs text-base-content/60">+ {new Date(label).toLocaleDateString("en-US", {+ month: "short",+ day: "numeric",+ year: "numeric",+ })}+ </p>+ {entries.map((e) => {+ const device =+ e.dataKey === "desktop" || e.dataKey === "mobile"+ ? DEVICE_STYLE[e.dataKey].label+ : String(e.dataKey ?? "");+ const inBottomBand = bottomBandKeys.has(`${label}:${e.dataKey}`);+ return (+ <p key={String(e.dataKey)} className="text-sm font-medium">+ {device}:{" "}+ {inBottomBand ? (+ <span className="text-base-content/60">+ Not in top {serpDepth}+ </span>+ ) : (+ e.value+ )}+ </p>+ );+ })}+ </div>+ );+}++// ---------------------------------------------------------------------------+// Data shaping+// ---------------------------------------------------------------------------++function deriveDevices(+ points: RankKeywordHistoryPoint[],+): Array<"desktop" | "mobile"> {+ const present = new Set(points.map((p) => p.device));+ return (["desktop", "mobile"] as const).filter((d) => present.has(d));+}++interface ChartRow extends Record<string, unknown> {+ checkedAt: number;+ desktop?: number;+ mobile?: number;+}++/**+ * Pivot flat rows into chart rows keyed by checkedAt (ms). A null position is+ * plotted at `serpDepth` so it renders inside the muted bottom band and the+ * line connects down to it (a drop), rather than leaving a silent gap.+ */+function buildChartData(+ points: RankKeywordHistoryPoint[],+ serpDepth: number,+): ChartRow[] {+ const byTime = new Map<number, ChartRow>();+ for (const p of points) {+ const ts = new Date(p.checkedAt).getTime();+ const row = byTime.get(ts) ?? { checkedAt: ts };+ row[p.device] = p.position === null ? serpDepth : p.position;+ byTime.set(ts, row);+ }+ return [...byTime.values()].toSorted((a, b) => a.checkedAt - b.checkedAt);+}++interface HistoryRow {+ device: "desktop" | "mobile";+ checkedAt: string;+ position: number | null;+ previousPosition: number | null;+}++/**+ * One row per snapshot (newest first) with the previous-check position for the+ * same device, so the Δ column can reuse DeviceRankCell's 4-case logic.+ */+function buildHistoryRows(points: RankKeywordHistoryPoint[]): HistoryRow[] {+ const prevByDevice = new Map<"desktop" | "mobile", number | null>();+ const rows: HistoryRow[] = [];+ // points are oldest-first; walk forward to capture the prior position.+ for (const p of points) {+ const hadPrevious = prevByDevice.has(p.device);+ rows.push({+ device: p.device,+ checkedAt: p.checkedAt,+ position: p.position,+ previousPosition: hadPrevious+ ? (prevByDevice.get(p.device) ?? null)+ : null,+ });+ prevByDevice.set(p.device, p.position);+ }+ return rows.toReversed();+}++function slugify(value: string): string {+ return value+ .toLowerCase()+ .replace(/[^a-z0-9]+/g, "-")+ .replace(/^-|-$/g, "");+}diff --git a/src/client/features/rank-tracking/RankTrackingColumns.tsx b/src/client/features/rank-tracking/RankTrackingColumns.tsxindex b9967532..818904bb 100644--- a/src/client/features/rank-tracking/RankTrackingColumns.tsx+++ b/src/client/features/rank-tracking/RankTrackingColumns.tsx@@ -100,17 +100,28 @@ const cpcColumn: ColumnDef<RankTrackingRow> = {sortingFn: nullsLastNumeric,};-const keywordColumn: ColumnDef<RankTrackingRow> = {- id: "keyword",- accessorKey: "keyword",- header: ({ column }) => (- <SortableHeader column={column} label="Keyword" id="keyword" />- ),- cell: ({ getValue }) => (- <span className="font-medium">{getValue<string>()}</span>- ),- sortingFn: "alphanumeric",-};+function makeKeywordColumn(+ onKeywordClick: (row: RankTrackingRow) => void,+): ColumnDef<RankTrackingRow> {+ return {+ id: "keyword",+ accessorKey: "keyword",+ header: ({ column }) => (+ <SortableHeader column={column} label="Keyword" id="keyword" />+ ),+ cell: ({ row }) => (+ <button+ type="button"+ className="font-medium text-left link link-hover decoration-dotted underline-offset-2"+ onClick={() => onKeywordClick(row.original)}+ title="View position history"+ >+ {row.original.keyword}+ </button>+ ),+ sortingFn: "alphanumeric",+ };+}function makeDeviceColumn(device: "desktop" | "mobile",@@ -178,11 +189,12 @@ export function useRankTrackingColumns(showMobile: boolean,domain: string,selectAnchorRef: MutableRefObject<SelectionAnchor | null>,+ onKeywordClick: (row: RankTrackingRow) => void,): ColumnDef<RankTrackingRow>[] {return useMemo(() => {const cols: ColumnDef<RankTrackingRow>[] = [makeSelectionColumn<RankTrackingRow>(selectAnchorRef),- keywordColumn,+ makeKeywordColumn(onKeywordClick),];if (showDesktop) {cols.push(makeDeviceColumn("desktop"));@@ -200,5 +212,5 @@ export function useRankTrackingColumns(cols.push(makeSerpColumn("mobile"));}return cols;- }, [showDesktop, showMobile, domain, selectAnchorRef]);+ }, [showDesktop, showMobile, domain, selectAnchorRef, onKeywordClick]);}diff --git a/src/client/features/rank-tracking/RankTrackingDetailHeader.tsx b/src/client/features/rank-tracking/RankTrackingDetailHeader.tsxnew file mode 100644index 00000000..4fea69fa--- /dev/null+++ b/src/client/features/rank-tracking/RankTrackingDetailHeader.tsx@@ -0,0 +1,110 @@+import { Monitor, Plus, Settings, Smartphone } from "lucide-react";+import { SegmentedToggle } from "@/client/components/SegmentedToggle";+import { LOCATIONS } from "@/client/features/keywords/locations";+import { devicesLabel, scheduleLabel } from "@/shared/rank-tracking";+import type {+ ComparePeriod,+ RankTrackingConfig,+} from "@/types/schemas/rank-tracking";++const COMPARE_PERIODS: ReadonlySet<string> = new Set([+ "1d",+ "7d",+ "30d",+ "90d",+]);+function isComparePeriod(v: string): v is ComparePeriod {+ return COMPARE_PERIODS.has(v);+}++export function RankTrackingDetailHeader({+ config,+ run,+ costEstimate,+ hasBothDevices,+ activeDevice,+ onActiveDeviceChange,+ comparePeriod,+ onComparePeriodChange,+ onEdit,+ onToggleAddKeywords,+}: {+ config: RankTrackingConfig;+ run: { lastCheckedAt: string } | null | undefined;+ costEstimate: { keywordCount: number; costUsd: number } | undefined;+ hasBothDevices: boolean;+ activeDevice: "desktop" | "mobile";+ onActiveDeviceChange: (v: "desktop" | "mobile") => void;+ comparePeriod: ComparePeriod;+ onComparePeriodChange: (v: ComparePeriod) => void;+ onEdit: () => void;+ onToggleAddKeywords: () => void;+}) {+ return (+ <div className="flex flex-col sm:flex-row sm:items-start justify-between gap-2 px-4 pt-4 pb-3">+ <div>+ <h2 className="text-lg font-semibold">{config.domain}</h2>+ <p className="text-xs text-base-content/60">+ {LOCATIONS[config.locationCode] ?? "US"} ·{" "}+ {devicesLabel(config.devices)} ·{" "}+ {scheduleLabel(config.scheduleInterval)}+ {run && (+ <>+ {" "}+ · Last: {new Date(run.lastCheckedAt).toLocaleDateString()}+ </>+ )}+ {costEstimate && costEstimate.keywordCount > 0 && (+ <> · ~${costEstimate.costUsd.toFixed(2)}/check</>+ )}+ </p>+ </div>+ <div className="flex flex-wrap items-center gap-2">+ {hasBothDevices && (+ <SegmentedToggle+ items={[+ {+ value: "desktop" as const,+ icon: <Monitor className="size-3.5" />,+ label: "Desktop",+ },+ {+ value: "mobile" as const,+ icon: <Smartphone className="size-3.5" />,+ label: "Mobile",+ },+ ]}+ value={activeDevice}+ onChange={onActiveDeviceChange}+ />+ )}+ <select+ className="select select-bordered select-sm text-xs w-auto"+ title="Comparison period"+ value={comparePeriod}+ onChange={(e) => {+ if (isComparePeriod(e.target.value))+ onComparePeriodChange(e.target.value);+ }}+ >+ <option value="1d">vs yesterday</option>+ <option value="7d">vs last week</option>+ <option value="30d">vs last month</option>+ <option value="90d">vs 90 days ago</option>+ </select>+ <div className="hidden sm:block h-6 w-px bg-base-300" />+ <button className="btn btn-outline btn-sm gap-1" onClick={onEdit}>+ <Settings className="size-3.5" />+ Configure+ </button>+ <button+ className="btn btn-primary btn-sm gap-1"+ onClick={onToggleAddKeywords}+ >+ <Plus className="size-3.5" />+ Add Keywords+ </button>+ </div>+ </div>+ );+}diff --git a/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx b/src/client/features/rank-tracking/RankTrackingDomainDetail.tsxindex 21ba8547..870f0217 100644--- a/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx+++ b/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx@@ -4,23 +4,22 @@ import { useQuery, useQueryClient } from "@tanstack/react-query";import { AutumnProvider, useCustomer } from "autumn-js/react";import {getLatestRankResults,+ getRankPositionMatrix,estimateRankCheckCost,} from "@/serverFunctions/rank-tracking";-import {- AlertTriangle,- ArrowLeft,- Loader2,- Monitor,- Plus,- Settings,- SlidersHorizontal,- Smartphone,-} from "lucide-react";+import { AlertTriangle, ArrowLeft } from "lucide-react";import { useSession } from "@/lib/auth-client";import { getCustomerPlanStatus } from "@/client/features/billing/plan-detection";import { captureClientEvent } from "@/client/lib/posthog";import { FreePlanAlert } from "./FreePlanAlert";+import { RankTrackingDetailHeader } from "./RankTrackingDetailHeader";+import { RankTrackingOverview } from "./RankTrackingOverview";import { RankTrackingTable } from "./RankTrackingTable";+import {+ countMatrixRuns,+ RankTrackingHistoryMatrix,+} from "./RankTrackingHistoryMatrix";+import { RankTrackingTableToolbar } from "./RankTrackingTableToolbar";import {exportRankTrackingCsv,exportRankTrackingToSheets,@@ -29,9 +28,6 @@ import type {RankTrackingConfig,ComparePeriod,} from "@/types/schemas/rank-tracking";-import { LOCATIONS } from "@/client/features/keywords/locations";-import { devicesLabel, scheduleLabel } from "@/shared/rank-tracking";-import { ActionsMenu } from "./ActionsMenu";import { AddKeywordsPanel } from "./AddKeywordsPanel";import {FilterPanel,@@ -41,19 +37,24 @@ import {type Filters,} from "./RankTrackingFilters";import { CheckConfirmModal } from "./CheckConfirmModal";-import { SegmentedToggle } from "@/client/components/SegmentedToggle";import { useMetricsRefresh } from "./useMetricsRefresh";import { useRankCheckTrigger } from "./useRankCheckTrigger";import { useRankRunPolling } from "./useRankRunPolling";-const COMPARE_PERIODS: ReadonlySet<string> = new Set([- "1d",- "7d",- "30d",- "90d",-]);-function isComparePeriod(v: string): v is ComparePeriod {- return COMPARE_PERIODS.has(v);+function deviceVisibility(+ devices: RankTrackingConfig["devices"],+ activeDevice: "desktop" | "mobile",+): { showDesktop: boolean; showMobile: boolean } {+ if (devices === "both") {+ return {+ showDesktop: activeDevice === "desktop",+ showMobile: activeDevice === "mobile",+ };+ }+ return {+ showDesktop: devices !== "mobile",+ showMobile: devices !== "desktop",+ };}export function RankTrackingDomainDetail(props: {@@ -98,6 +99,7 @@ function RankTrackingDomainDetailInner({const [activeDevice, setActiveDevice] = useState<"desktop" | "mobile">(config.devices === "mobile" ? "mobile" : "desktop",);+ const [viewMode, setViewMode] = useState<"table" | "history">("table");const { data: resultsData, isLoading: resultsLoading } = useQuery({queryKey: ["rankTrackingResults", projectId, config.id, comparePeriod],@@ -109,6 +111,17 @@ function RankTrackingDomainDetailInner({const latestRun = useRankRunPolling(projectId, config.id);+ // Also feeds the History toggle: the matrix view only earns its tab once+ // there are two checks to compare.+ const { data: matrixCells, isLoading: matrixLoading } = useQuery({+ queryKey: ["rankPositionMatrix", projectId, config.id, activeDevice],+ queryFn: () =>+ getRankPositionMatrix({+ data: { projectId, configId: config.id, device: activeDevice },+ }),+ });+ const historyAvailable = countMatrixRuns(matrixCells ?? []) >= 2;+const { data: costEstimate } = useQuery({queryKey: ["rankTrackingCostEstimate", projectId, config.id],queryFn: () =>@@ -169,18 +182,18 @@ function RankTrackingDomainDetailInner({const rows = resultsData?.rows;const run = resultsData?.run;const hasBothDevices = config.devices === "both";- const showDesktop = hasBothDevices- ? activeDevice === "desktop"- : config.devices !== "mobile";- const showMobile = hasBothDevices- ? activeDevice === "mobile"- : config.devices !== "desktop";+ const { showDesktop, showMobile } = deviceVisibility(+ config.devices,+ activeDevice,+ );const filtered = useMemo(() => applyFilters(rows ?? [], filters),[rows, filters],);const activeFilterCount = countActiveFilters(filters);const defaultSortId = showDesktop ? "desktopPosition" : "mobilePosition";+ // Fall back to the table if history disappears (e.g. device switch).+ const effectiveViewMode = historyAvailable ? viewMode : "table";return (<div className="space-y-3">@@ -216,39 +229,18 @@ function RankTrackingDomainDetailInner({{/* Results card */}<div className="flex-1 flex flex-col min-w-0 border border-base-300 rounded-xl bg-base-100 overflow-hidden">{/* Domain header */}- <div className="flex flex-col sm:flex-row sm:items-start justify-between gap-2 px-4 pt-4 pb-3">- <div>- <h2 className="text-lg font-semibold">{config.domain}</h2>- <p className="text-xs text-base-content/60">- {LOCATIONS[config.locationCode] ?? "US"} ·{" "}- {devicesLabel(config.devices)} ·{" "}- {scheduleLabel(config.scheduleInterval)}- {run && (- <>- {" "}- · Last:{" "}- {new Date(run.lastCheckedAt).toLocaleDateString()}- </>- )}- {costEstimate && costEstimate.keywordCount > 0 && (- <> · ~${costEstimate.costUsd.toFixed(2)}/check</>- )}- </p>- </div>- <div className="flex gap-2">- <button className="btn btn-outline btn-sm gap-1" onClick={onEdit}>- <Settings className="size-3.5" />- Configure- </button>- <button- className="btn btn-primary btn-sm gap-1"- onClick={() => setShowAddKeywords(!showAddKeywords)}- >- <Plus className="size-3.5" />- Add Keywords- </button>- </div>- </div>+ <RankTrackingDetailHeader+ config={config}+ run={run}+ costEstimate={costEstimate}+ hasBothDevices={hasBothDevices}+ activeDevice={activeDevice}+ onActiveDeviceChange={setActiveDevice}+ comparePeriod={comparePeriod}+ onComparePeriodChange={setComparePeriod}+ onEdit={onEdit}+ onToggleAddKeywords={() => setShowAddKeywords((c) => !c)}+ />{showAddKeywords && (<div className="px-4 pb-3">@@ -261,109 +253,54 @@ function RankTrackingDomainDetailInner({</div>)}- {/* Table toolbar */}- <div className="shrink-0 flex items-center gap-2 px-4 py-2 border-y border-base-300">- <button- className={`btn btn-ghost btn-sm gap-1.5 ${showFilters ? "btn-active" : ""}`}- onClick={() => setShowFilters((c) => !c)}- title="Toggle table filters"- >- <SlidersHorizontal className="size-3.5" />- Filters- {activeFilterCount > 0 && (- <span className="badge badge-xs badge-primary border-0 text-primary-content">- {activeFilterCount}- </span>- )}- </button>-- {isRunning && latestRun ? (- <div className="flex items-center gap-2 text-sm text-base-content/70">- <Loader2 className="size-3.5 animate-spin text-primary" />- <span>- {latestRun.status === "pending"- ? "Preparing..."- : `Getting rankings for ${latestRun.keywordsTotal || "?"} keyword${latestRun.keywordsTotal !== 1 ? "s" : ""}...`}{" "}- {latestRun.keywordsChecked}/{latestRun.keywordsTotal || "?"}- </span>- {latestRun.keywordsTotal > 0 && (- <progress- className="progress progress-primary w-24"- value={latestRun.keywordsChecked}- max={latestRun.keywordsTotal}- />- )}- </div>- ) : (- <span className="text-sm text-base-content/60">- {filtered.length} keywords- </span>- )}-- <div className="flex-1" />-- <select- className="select select-bordered select-sm text-xs w-auto"- value={comparePeriod}- onChange={(e) => {- if (isComparePeriod(e.target.value))- setComparePeriod(e.target.value);- }}- >- <option value="1d">Since yesterday</option>- <option value="7d">Since last week</option>- <option value="30d">Since last month</option>- <option value="90d">Since 90 days ago</option>- </select>-- {hasBothDevices && (- <SegmentedToggle- items={[- {- value: "desktop" as const,- icon: <Monitor className="size-3.5" />,- label: "Desktop",- },- {- value: "mobile" as const,- icon: <Smartphone className="size-3.5" />,- label: "Mobile",- },- ]}- value={activeDevice}- onChange={setActiveDevice}- />- )}-- <ActionsMenu- onCheckNow={() => {- const count = costEstimate?.keywordCount ?? rows?.length ?? 0;- if (count > 0) requestCheck(count);- }}- onRefreshMetrics={refreshMetrics}- metricsRefreshing={metricsRefreshing}- onExport={() =>- exportRankTrackingCsv(- filtered,- showDesktop,- showMobile,- config.domain,- )- }- onExportToSheets={() =>- exportRankTrackingToSheets(filtered, showDesktop, showMobile)- }- onCopyKeywords={() => {- void navigator.clipboard.writeText(- filtered.map((r) => r.keyword).join("\n"),- );- toast.success("Keywords copied to clipboard");- }}- isRunning={isBusy}- hasData={filtered.length > 0}- checkDisabled={isFreePlan}+ {/* Portfolio overview */}+ {(rows?.length ?? 0) > 0 && (+ <RankTrackingOverview+ rows={rows ?? []}+ device={activeDevice}+ projectId={projectId}+ configId={config.id}/>- </div>+ )}++ {/* Table toolbar */}+ <RankTrackingTableToolbar+ showFilters={showFilters}+ onToggleFilters={() => setShowFilters((c) => !c)}+ activeFilterCount={activeFilterCount}+ isRunning={isRunning}+ latestRun={latestRun}+ keywordCount={filtered.length}+ viewMode={effectiveViewMode}+ onViewModeChange={setViewMode}+ historyAvailable={historyAvailable}+ onExport={() =>+ exportRankTrackingCsv(+ filtered,+ showDesktop,+ showMobile,+ config.domain,+ )+ }+ onExportToSheets={() =>+ exportRankTrackingToSheets(filtered, showDesktop, showMobile)+ }+ onCopyKeywords={() => {+ void navigator.clipboard.writeText(+ filtered.map((r) => r.keyword).join("\n"),+ );+ toast.success("Keywords copied to clipboard");+ }}+ onCheckNow={() => {+ const count = costEstimate?.keywordCount ?? rows?.length ?? 0;+ if (count > 0) requestCheck(count);+ }}+ onRefreshMetrics={refreshMetrics}+ metricsRefreshing={metricsRefreshing}+ checkBusy={isBusy}+ checkDisabled={isFreePlan}+ hasData={filtered.length > 0}+ />{/* Filters panel */}{showFilters && (@@ -377,18 +314,31 @@ function RankTrackingDomainDetailInner({{/* Table */}<div className="p-4">- <RankTrackingTable- key={defaultSortId}- totalCount={rows?.length ?? 0}- rows={filtered}- resultsLoading={resultsLoading}- showDesktop={showDesktop}- showMobile={showMobile}- defaultSortId={defaultSortId}- domain={config.domain}- configId={config.id}- projectId={projectId}- />+ {effectiveViewMode === "history" ? (+ <RankTrackingHistoryMatrix+ cells={matrixCells ?? []}+ isLoading={matrixLoading}+ keywords={filtered.map((r) => ({+ trackingKeywordId: r.trackingKeywordId,+ keyword: r.keyword,+ }))}+ />+ ) : (+ <RankTrackingTable+ key={defaultSortId}+ totalCount={rows?.length ?? 0}+ rows={filtered}+ resultsLoading={resultsLoading}+ showDesktop={showDesktop}+ showMobile={showMobile}+ defaultSortId={defaultSortId}+ domain={config.domain}+ configId={config.id}+ projectId={projectId}+ locationCode={config.locationCode}+ serpDepth={config.serpDepth}+ />+ )}</div></div>diff --git a/src/client/features/rank-tracking/RankTrackingHistoryMatrix.tsx b/src/client/features/rank-tracking/RankTrackingHistoryMatrix.tsxnew file mode 100644index 00000000..4898402f--- /dev/null+++ b/src/client/features/rank-tracking/RankTrackingHistoryMatrix.tsx@@ -0,0 +1,145 @@+import { useMemo } from "react";+import { Loader2 } from "lucide-react";+import type { RankPositionMatrixCell } from "@/serverFunctions/rank-tracking";++/**+ * "By date" view: keyword rows × recent check columns, each cell the position+ * on that date with its change vs the previous check. This is the pivoted+ * history table users want for client reporting ("look — we won 5 positions").+ */+export function RankTrackingHistoryMatrix({+ cells,+ isLoading,+ keywords,+}: {+ cells: RankPositionMatrixCell[];+ isLoading: boolean;+ keywords: { trackingKeywordId: string; keyword: string }[];+}) {+ const { runs, cellByKeyword } = useMemo(() => buildMatrix(cells), [cells]);++ if (isLoading) {+ return (+ <div className="flex items-center justify-center p-8">+ <Loader2 className="size-5 animate-spin text-base-content/50" />+ </div>+ );+ }++ if (runs.length === 0 || keywords.length === 0) {+ return (+ <div className="rounded-xl border border-dashed border-base-300 p-10 text-center text-sm text-base-content/55">+ No history yet. Run a check to start building the timeline.+ </div>+ );+ }++ return (+ <div className="overflow-x-auto rounded-lg border border-base-300">+ <table className="table table-sm">+ <thead>+ <tr>+ {/* Unconstrained keyword column absorbs the slack when only a few+ check columns exist, so sparse history doesn't stretch oddly. */}+ <th className="sticky left-0 z-10 bg-base-100 w-full">Keyword</th>+ {runs.map((r) => (+ <th+ key={r.runId}+ className="w-24 whitespace-nowrap text-right text-xs font-medium text-base-content/60"+ >+ {formatDate(r.checkedAt)}+ </th>+ ))}+ </tr>+ </thead>+ <tbody>+ {keywords.map((kw) => {+ const byRun = cellByKeyword.get(kw.trackingKeywordId);+ return (+ <tr key={kw.trackingKeywordId}>+ <td className="sticky left-0 z-10 bg-base-100 whitespace-nowrap font-medium">+ {kw.keyword}+ </td>+ {runs.map((r, i) => {+ const position = byRun?.get(r.runId) ?? null;+ const previous =+ i > 0 ? (byRun?.get(runs[i - 1].runId) ?? null) : undefined;+ return (+ <td key={r.runId} className="text-right">+ <MatrixCell position={position} previous={previous} />+ </td>+ );+ })}+ </tr>+ );+ })}+ </tbody>+ </table>+ </div>+ );+}++function MatrixCell({+ position,+ previous,+}: {+ position: number | null;+ previous: number | null | undefined;+}) {+ if (position === null) {+ return <span className="text-base-content/30">—</span>;+ }+ // Only show a change arrow when both checks ranked (no subtracting through a+ // null, matching the rest of the rank-tracking UI).+ const change =+ previous != null && previous !== undefined ? previous - position : null;+ return (+ <span className="inline-flex items-center justify-end gap-1 font-mono text-xs">+ <span>{position}</span>+ {change != null && change > 0 && (+ <span className="text-success">▲{change}</span>+ )}+ {change != null && change < 0 && (+ <span className="text-warning">▼{-change}</span>+ )}+ </span>+ );+}++interface MatrixRun {+ runId: string;+ checkedAt: string;+}++/** Distinct completed runs in a matrix payload (= history columns). */+export function countMatrixRuns(cells: RankPositionMatrixCell[]): number {+ return new Set(cells.map((c) => c.runId)).size;+}++function buildMatrix(cells: RankPositionMatrixCell[]): {+ runs: MatrixRun[];+ cellByKeyword: Map<string, Map<string, number | null>>;+} {+ const runMap = new Map<string, string>(); // runId -> checkedAt+ const cellByKeyword = new Map<string, Map<string, number | null>>();+ for (const c of cells) {+ runMap.set(c.runId, c.checkedAt);+ let byRun = cellByKeyword.get(c.trackingKeywordId);+ if (!byRun) {+ byRun = new Map();+ cellByKeyword.set(c.trackingKeywordId, byRun);+ }+ byRun.set(c.runId, c.position);+ }+ const runs = [...runMap.entries()]+ .map(([runId, checkedAt]) => ({ runId, checkedAt }))+ .toSorted((a, b) => a.checkedAt.localeCompare(b.checkedAt));+ return { runs, cellByKeyword };+}++function formatDate(value: string): string {+ return new Date(value).toLocaleDateString("en-US", {+ month: "short",+ day: "numeric",+ });+}diff --git a/src/client/features/rank-tracking/RankTrackingOverview.tsx b/src/client/features/rank-tracking/RankTrackingOverview.tsxnew file mode 100644index 00000000..199087ca--- /dev/null+++ b/src/client/features/rank-tracking/RankTrackingOverview.tsx@@ -0,0 +1,293 @@+import { useMemo, useState } from "react";+import { Loader2 } from "lucide-react";+import { useQuery } from "@tanstack/react-query";+import {+ Area,+ AreaChart,+ CartesianGrid,+ Tooltip,+ XAxis,+ YAxis,+} from "recharts";+import type { TooltipContentProps } from "recharts";+import { getRankConfigTrend } from "@/serverFunctions/rank-tracking";+import type { RankTrackingRow } from "@/types/schemas/rank-tracking";+import { computeScorecards } from "./rankTrackingScorecards";+import {+ formatDateTick,+ TrendRangeToggle,+ useChartWidth,+} from "./RankTrackingTrendChart";++const BUCKETS = [+ { key: "top3", label: "Top 3", color: "#16a34a" },+ { key: "top4to10", label: "4–10", color: "#2563eb" },+ { key: "top11to20", label: "11–20", color: "#f59e0b" },+ { key: "notRanking", label: "Not in top 20", color: "#6b7280" },+] as const;++/** Narrowed recharts tooltip payload entry (typed `any` upstream). */+interface PayloadEntry {+ dataKey?: string | number;+ value?: number | string | null;+}++export function RankTrackingOverview({+ rows,+ device,+ projectId,+ configId,+}: {+ rows: RankTrackingRow[];+ device: "desktop" | "mobile";+ projectId: string;+ configId: string;+}) {+ const [sinceDays, setSinceDays] = useState(730);++ const scorecards = useMemo(+ () => computeScorecards(rows, device),+ [rows, device],+ );++ const { data: trend, isLoading: trendLoading } = useQuery({+ queryKey: ["rankConfigTrend", projectId, configId, device, sinceDays],+ queryFn: () =>+ getRankConfigTrend({+ data: { projectId, configId, device, sinceDays },+ }),+ });++ const chartData = useMemo(+ () =>+ (trend ?? []).map((p) => ({+ checkedAt: new Date(p.checkedAt).getTime(),+ top3: p.top3,+ top4to10: p.top4to10,+ top11to20: p.top11to20,+ notRanking: p.notRanking,+ })),+ [trend],+ );++ const { containerRef, width } = useChartWidth();++ return (+ <div className="px-4 pt-4 pb-4">+ <div className="grid items-start gap-3 lg:grid-cols-2">+ {/* All metrics in one card */}+ <div className="rounded-lg border border-base-300 bg-base-100 p-4">+ <div className="grid grid-cols-2 gap-x-4 gap-y-4 sm:grid-cols-3">+ <Scorecard+ label="Visibility"+ value={+ scorecards.visibility === null+ ? "-"+ : `${Math.round(scorecards.visibility)}%`+ }+ delta={scorecards.visibilityDelta}+ hint="of click potential"+ />+ <Scorecard+ label="Ranking"+ value={String(scorecards.ranking)}+ delta={scorecards.rankingDelta}+ hint={`of ${rows.length} tracked`}+ />+ <Scorecard+ label="In Top 3"+ value={String(scorecards.top3)}+ hint="of ranked keywords"+ />+ <Scorecard+ label="In Top 10"+ value={String(scorecards.top10)}+ hint="includes Top 3"+ />+ <Scorecard+ label="Improved / Declined"+ value={`${scorecards.improved} / ${scorecards.declined}`}+ hint="vs comparison period"+ />+ </div>+ </div>++ {/* Position distribution */}+ <div className="rounded-lg border border-base-300 p-3 space-y-2">+ <div className="flex items-center justify-between gap-2">+ <span className="text-sm font-medium">Position distribution</span>+ <TrendRangeToggle value={sinceDays} onChange={setSinceDays} />+ </div>++ <div className="flex flex-wrap gap-x-3 gap-y-1">+ {BUCKETS.map((b) => (+ <span+ key={b.key}+ className="inline-flex items-center gap-1 text-[11px] text-base-content/60"+ >+ <span+ className="size-2 rounded-sm"+ style={{ backgroundColor: b.color }}+ />+ {b.label}+ </span>+ ))}+ </div>++ {trendLoading ? (+ <div className="flex items-center justify-center p-8">+ <Loader2 className="size-4 animate-spin text-base-content/50" />+ </div>+ ) : chartData.length <= 1 ? (+ <div className="rounded-lg border border-dashed border-base-300 p-8 text-center text-xs text-base-content/60">+ {chartData.length === 0+ ? "No history yet — run a check to start tracking positions over time."+ : "Only 1 check so far — the trend fills in after the next check."}+ </div>+ ) : (+ <div+ ref={containerRef}+ className="w-full min-w-0"+ style={{ height: 180 }}+ >+ {width > 0 ? (+ <AreaChart+ width={width}+ height={180}+ data={chartData}+ margin={{ top: 8, right: 8, bottom: 0, left: 0 }}+ >+ <CartesianGrid+ strokeDasharray="3 3"+ stroke="currentColor"+ opacity={0.1}+ vertical={false}+ />+ <XAxis+ dataKey="checkedAt"+ type="number"+ scale="time"+ domain={["dataMin", "dataMax"]}+ tickFormatter={formatDateTick}+ tick={{ fontSize: 10, fill: "#888" }}+ tickLine={false}+ axisLine={false}+ minTickGap={32}+ />+ <YAxis+ allowDecimals={false}+ tick={{ fontSize: 10, fill: "#888" }}+ tickLine={false}+ axisLine={false}+ width={28}+ />+ <Tooltip+ content={(props: TooltipContentProps<number, string>) => {+ const { active, payload, label } = props;+ if (+ !active ||+ !payload?.length ||+ typeof label !== "number"+ ) {+ return null;+ }+ const byKey = new Map(+ payload.map((p: PayloadEntry) => [+ String(p.dataKey),+ typeof p.value === "number" ? p.value : 0,+ ]),+ );+ return (+ <DistributionTooltip label={label} byKey={byKey} />+ );+ }}+ cursor={{ stroke: "rgba(150,150,150,0.3)" }}+ />+ {BUCKETS.map((b) => (+ <Area+ key={b.key}+ type="monotone"+ dataKey={b.key}+ name={b.label}+ stackId="positions"+ stroke={b.color}+ fill={b.color}+ fillOpacity={0.7}+ isAnimationActive={false}+ />+ ))}+ </AreaChart>+ ) : null}+ </div>+ )}+ </div>+ </div>+ </div>+ );+}++function DistributionTooltip({+ label,+ byKey,+}: {+ label: number;+ byKey: Map<string, number>;+}) {+ return (+ <div className="rounded-md border border-base-300 bg-base-100 px-3 py-2 shadow-sm space-y-0.5">+ <p className="text-xs text-base-content/60">+ {new Date(label).toLocaleDateString("en-US", {+ month: "short",+ day: "numeric",+ year: "numeric",+ })}+ </p>+ {BUCKETS.map((b) => (+ <p key={b.key} className="text-xs flex items-center gap-1.5">+ <span+ className="size-2 rounded-sm"+ style={{ backgroundColor: b.color }}+ />+ <span className="text-base-content/60">{b.label}:</span>+ <span className="font-medium tabular-nums">+ {byKey.get(b.key) ?? 0}+ </span>+ </p>+ ))}+ </div>+ );+}++function Scorecard({+ label,+ value,+ delta,+ hint,+}: {+ label: string;+ value: string;+ delta?: number | null;+ hint?: string;+}) {+ return (+ <div className="min-w-0">+ <p className="text-xs text-base-content/55">{label}</p>+ <div className="flex items-baseline gap-1.5">+ <span className="text-xl font-semibold tabular-nums">{value}</span>+ {delta != null && delta !== 0 && (+ <span+ className={`text-xs font-medium ${+ delta > 0 ? "text-success" : "text-warning"+ }`}+ >+ {delta > 0 ? "▲" : "▼"}{" "}+ {Number.isInteger(delta)+ ? Math.abs(delta)+ : Math.abs(delta).toFixed(1)}+ </span>+ )}+ </div>+ {hint && <p className="text-[11px] text-base-content/45">{hint}</p>}+ </div>+ );+}diff --git a/src/client/features/rank-tracking/RankTrackingTable.tsx b/src/client/features/rank-tracking/RankTrackingTable.tsxindex a2181f4f..02531d32 100644--- a/src/client/features/rank-tracking/RankTrackingTable.tsx+++ b/src/client/features/rank-tracking/RankTrackingTable.tsx@@ -1,4 +1,4 @@-import { useRef, useState } from "react";+import { useCallback, useRef, useState } from "react";import { toast } from "sonner";import { FileDown, Loader2, Sheet, Trash2 } from "lucide-react";import { Modal } from "@/client/components/Modal";@@ -21,6 +21,10 @@ import { getStandardErrorMessage } from "@/client/lib/error-messages";import type { RankTrackingRow } from "@/types/schemas/rank-tracking";import { useRankTrackingColumns } from "./RankTrackingColumns";import { buildRankTrackingExport } from "./RankTrackingTableParts";+import {+ KeywordTrendModal,+ type KeywordTrendTarget,+} from "./KeywordTrendModal";import type { SelectionAnchor } from "@/client/components/table/tableSelection";export function RankTrackingTable({@@ -33,6 +37,8 @@ export function RankTrackingTable({domain,configId,projectId,+ locationCode,+ serpDepth,}: {totalCount: number;rows: RankTrackingRow[];@@ -43,16 +49,31 @@ export function RankTrackingTable({domain: string;configId: string;projectId: string;+ locationCode: number;+ serpDepth: number;}) {const queryClient = useQueryClient();const [showConfirm, setShowConfirm] = useState(false);+ const [trendTarget, setTrendTarget] = useState<KeywordTrendTarget | null>(+ null,+ );const selectAnchorRef = useRef<SelectionAnchor | null>(null);+ const handleKeywordClick = useCallback(+ (row: RankTrackingRow) =>+ setTrendTarget({+ trackingKeywordId: row.trackingKeywordId,+ keyword: row.keyword,+ }),+ [],+ );+const columns = useRankTrackingColumns(showDesktop,showMobile,domain,selectAnchorRef,+ handleKeywordClick,);const table = useAppTable({@@ -211,6 +232,18 @@ export function RankTrackingTable({</Modal>)}+ {trendTarget && (+ <KeywordTrendModal+ target={trendTarget}+ projectId={projectId}+ configId={configId}+ domain={domain}+ locationCode={locationCode}+ serpDepth={serpDepth}+ onClose={() => setTrendTarget(null)}+ />+ )}+<AppDataTable table={table} getCellClassName={() => "align-top"} /><p className="text-xs text-base-content/60 pt-2">{rows.length} of {totalCount} keywordsdiff --git a/src/client/features/rank-tracking/RankTrackingTableParts.tsx b/src/client/features/rank-tracking/RankTrackingTableParts.tsxindex cc804316..cb7ee71b 100644--- a/src/client/features/rank-tracking/RankTrackingTableParts.tsx+++ b/src/client/features/rank-tracking/RankTrackingTableParts.tsx@@ -160,7 +160,7 @@ export function CpcCell({ value }: { value: number | null }) {}/** Numeric change for CSV export — numbers bypass the CSV formula-injection sanitizer */-function csvChange(+export function csvChange(current: number | null,previous: number | null,): number | string {diff --git a/src/client/features/rank-tracking/RankTrackingTableToolbar.tsx b/src/client/features/rank-tracking/RankTrackingTableToolbar.tsxnew file mode 100644index 00000000..efbcecbe--- /dev/null+++ b/src/client/features/rank-tracking/RankTrackingTableToolbar.tsx@@ -0,0 +1,127 @@+import { CalendarDays, Loader2, SlidersHorizontal, Table } from "lucide-react";+import { SegmentedToggle } from "@/client/components/SegmentedToggle";+import { ExportMenu, MoreMenu } from "./ToolbarMenus";++export function RankTrackingTableToolbar({+ showFilters,+ onToggleFilters,+ activeFilterCount,+ isRunning,+ latestRun,+ keywordCount,+ viewMode,+ onViewModeChange,+ historyAvailable,+ onExport,+ onExportToSheets,+ onCopyKeywords,+ onCheckNow,+ onRefreshMetrics,+ metricsRefreshing,+ checkBusy,+ checkDisabled,+ hasData,+}: {+ showFilters: boolean;+ onToggleFilters: () => void;+ activeFilterCount: number;+ isRunning: boolean;+ latestRun:+ | { status: string; keywordsChecked: number; keywordsTotal: number }+ | null+ | undefined;+ keywordCount: number;+ viewMode: "table" | "history";+ onViewModeChange: (v: "table" | "history") => void;+ historyAvailable: boolean;+ onExport: () => void;+ onExportToSheets: () => void;+ onCopyKeywords: () => void;+ onCheckNow: () => void;+ onRefreshMetrics: () => void;+ metricsRefreshing: boolean;+ checkBusy: boolean;+ checkDisabled: boolean;+ hasData: boolean;+}) {+ return (+ <div className="shrink-0 flex flex-wrap items-center gap-2 px-4 py-2 border-y border-base-300">+ {/* History needs at least two checks to compare; until then the toggle+ would only offer a worse copy of the Latest table. */}+ {historyAvailable && (+ <SegmentedToggle+ showLabels+ items={[+ {+ value: "table" as const,+ icon: <Table className="size-3.5" />,+ label: "Latest",+ },+ {+ value: "history" as const,+ icon: <CalendarDays className="size-3.5" />,+ label: "History",+ },+ ]}+ value={viewMode}+ onChange={onViewModeChange}+ />+ )}++ <button+ className={`btn btn-ghost btn-sm gap-1.5 ${showFilters ? "btn-active" : ""}`}+ onClick={onToggleFilters}+ title="Toggle table filters"+ >+ <SlidersHorizontal className="size-3.5" />+ Filters+ {activeFilterCount > 0 && (+ <span className="badge badge-xs badge-primary border-0 text-primary-content">+ {activeFilterCount}+ </span>+ )}+ </button>++ {isRunning && latestRun ? (+ <div className="flex items-center gap-2 text-sm text-base-content/70">+ <Loader2 className="size-3.5 animate-spin text-primary" />+ <span>+ {latestRun.status === "pending"+ ? "Preparing..."+ : `Getting rankings for ${latestRun.keywordsTotal || "?"} keyword${latestRun.keywordsTotal !== 1 ? "s" : ""}...`}{" "}+ {latestRun.keywordsChecked}/{latestRun.keywordsTotal || "?"}+ </span>+ {latestRun.keywordsTotal > 0 && (+ <progress+ className="progress progress-primary w-24"+ value={latestRun.keywordsChecked}+ max={latestRun.keywordsTotal}+ />+ )}+ </div>+ ) : (+ <span className="text-sm text-base-content/60">+ {keywordCount} keywords+ </span>+ )}++ <div className="flex-1" />++ <ExportMenu+ onExport={onExport}+ onExportToSheets={onExportToSheets}+ onCopyKeywords={onCopyKeywords}+ hasData={hasData}+ />++ <MoreMenu+ onCheckNow={onCheckNow}+ checkBusy={checkBusy}+ checkDisabled={checkDisabled}+ onRefreshMetrics={onRefreshMetrics}+ metricsRefreshing={metricsRefreshing}+ hasData={hasData}+ />+ </div>+ );+}diff --git a/src/client/features/rank-tracking/RankTrackingTrendChart.tsx b/src/client/features/rank-tracking/RankTrackingTrendChart.tsxnew file mode 100644index 00000000..7987310f--- /dev/null+++ b/src/client/features/rank-tracking/RankTrackingTrendChart.tsx@@ -0,0 +1,213 @@+import { useCallback, useRef, useState, type ReactNode } from "react";+import {+ CartesianGrid,+ Line,+ LineChart,+ ReferenceArea,+ Tooltip,+ XAxis,+ YAxis,+} from "recharts";+import type { TooltipContentProps } from "recharts";++export interface TrendSeries {+ /** key into each data row holding the position value (1 = best, serpDepth = bottom band) */+ dataKey: string;+ name: string;+ color: string;+ /** dashed = device line where nulls are plotted in the bottom "not in top N" band */+ strokeDasharray?: string;+}++interface TooltipEntry {+ dataKey?: string | number;+ name?: string;+ value: number | null;+ color?: string;+}++/** Narrowed shape of a recharts tooltip payload entry (typed `any` upstream). */+interface RechartsPayloadEntry {+ dataKey?: string | number;+ name?: string;+ value?: number | string | null;+ color?: string;+}++/**+ * Shared inverted-axis line chart for rank trends. Y-axis is reversed so #1 is+ * pinned at the top and an improving line moves up. The very bottom of the+ * plot (= serpDepth) is a muted "Not in top {serpDepth}" band; callers plot+ * null positions at `serpDepth` so a drop reads as the line dipping into the+ * band rather than a silent gap.+ */+export function RankTrendChart({+ data,+ series,+ serpDepth,+ height = 224,+ renderTooltip,+ showBottomBand = false,+}: {+ data: Array<Record<string, unknown>>;+ series: TrendSeries[];+ serpDepth: number;+ height?: number;+ renderTooltip: (label: number, entries: TooltipEntry[]) => ReactNode;+ /** Show the muted "not in top {serpDepth}" band — only meaningful for a+ * single keyword's position line, not for an averaged value. */+ showBottomBand?: boolean;+}) {+ const { containerRef, width: chartWidth } = useChartWidth();++ return (+ <div className="space-y-1">+ <div className="flex items-center justify-between text-[11px] text-base-content/50">+ <span>Google position (1 = best)</span>+ <span className="inline-flex items-center gap-1">+ Better <span aria-hidden>↑</span>+ </span>+ </div>+ <div ref={containerRef} className="w-full min-w-0" style={{ height }}>+ {chartWidth > 0 ? (+ <LineChart+ width={chartWidth}+ height={height}+ data={data}+ margin={{ top: 8, right: 8, bottom: 0, left: 0 }}+ >+ <CartesianGrid+ strokeDasharray="3 3"+ stroke="currentColor"+ opacity={0.1}+ vertical={false}+ />+ {/* Muted bottom band: not in top {serpDepth} */}+ {showBottomBand && (+ <ReferenceArea+ y1={serpDepth - 0.5}+ y2={serpDepth}+ fill="currentColor"+ fillOpacity={0.06}+ ifOverflow="extendDomain"+ />+ )}+ <XAxis+ dataKey="checkedAt"+ type="number"+ scale="time"+ domain={["dataMin", "dataMax"]}+ tickFormatter={formatDateTick}+ tick={{ fontSize: 10, fill: "#888" }}+ tickLine={false}+ axisLine={false}+ minTickGap={32}+ />+ <YAxis+ reversed+ domain={[1, serpDepth]}+ allowDecimals={false}+ tick={{ fontSize: 10, fill: "#888" }}+ tickLine={false}+ axisLine={false}+ width={32}+ />+ <Tooltip+ content={(props: TooltipContentProps<number, string>) => {+ const { active, payload, label } = props;+ if (!active || !payload?.length || typeof label !== "number") {+ return null;+ }+ const entries: TooltipEntry[] = payload.map(+ (p: RechartsPayloadEntry) => ({+ dataKey: p.dataKey,+ name: p.name,+ value: typeof p.value === "number" ? p.value : null,+ color: p.color,+ }),+ );+ return renderTooltip(label, entries);+ }}+ cursor={{ stroke: "rgba(150,150,150,0.3)" }}+ />+ {series.map((s) => (+ <Line+ key={s.dataKey}+ type="monotone"+ dataKey={s.dataKey}+ name={s.name}+ stroke={s.color}+ strokeWidth={2}+ strokeDasharray={s.strokeDasharray}+ dot={{ r: 2 }}+ activeDot={{ r: 4 }}+ connectNulls={false}+ isAnimationActive={false}+ />+ ))}+ </LineChart>+ ) : null}+ </div>+ </div>+ );+}++export function formatDateTick(value: number): string {+ return new Date(value).toLocaleDateString("en-US", {+ month: "short",+ day: "numeric",+ });+}++/** Responsive chart width via ResizeObserver — recharts needs an explicit px+ * width. Uses a callback ref so it measures whenever the chart node mounts,+ * including after a loading state (an effect-on-mount would miss that and leave+ * the width stuck at 0). Shared by the line chart and the distribution chart. */+export function useChartWidth() {+ const [width, setWidth] = useState(0);+ const observerRef = useRef<ResizeObserver | null>(null);++ const containerRef = useCallback((el: HTMLDivElement | null) => {+ observerRef.current?.disconnect();+ observerRef.current = null;+ if (!el) return;+ setWidth(el.clientWidth);+ const observer = new ResizeObserver(() => setWidth(el.clientWidth));+ observer.observe(el);+ observerRef.current = observer;+ }, []);++ return { containerRef, width };+}++/** 30d / 90d / All range toggle shared by the modal and overview charts. */+const TREND_RANGES = [+ { label: "30d", sinceDays: 30 },+ { label: "90d", sinceDays: 90 },+ { label: "All", sinceDays: 730 },+] as const;++export function TrendRangeToggle({+ value,+ onChange,+}: {+ value: number;+ onChange: (sinceDays: number) => void;+}) {+ return (+ <div className="join">+ {TREND_RANGES.map((range) => (+ <button+ key={range.label}+ type="button"+ className={`btn btn-xs join-item ${+ value === range.sinceDays ? "btn-active" : "btn-ghost"+ }`}+ onClick={() => onChange(range.sinceDays)}+ >+ {range.label}+ </button>+ ))}+ </div>+ );+}diff --git a/src/client/features/rank-tracking/ToolbarMenus.tsx b/src/client/features/rank-tracking/ToolbarMenus.tsxnew file mode 100644index 00000000..41ab74f9--- /dev/null+++ b/src/client/features/rank-tracking/ToolbarMenus.tsx@@ -0,0 +1,165 @@+import { useState, type ReactNode } from "react";+import {+ ChevronDown,+ Copy,+ Download,+ FileDown,+ MoreHorizontal,+ Play,+ RefreshCw,+ Sheet,+} from "lucide-react";++function ToolbarMenu({+ label,+ icon,+ title,+ children,+}: {+ label?: string;+ icon?: ReactNode;+ title?: string;+ children: ReactNode;+}) {+ const [open, setOpen] = useState(false);+ return (+ <div className="relative">+ <button+ type="button"+ className={`btn btn-ghost btn-sm ${label ? "gap-1" : "btn-square"}`}+ onClick={() => setOpen((c) => !c)}+ title={title}+ aria-label={title ?? label}+ aria-haspopup="menu"+ aria-expanded={open}+ >+ {icon}+ {label}+ {label && <ChevronDown className="size-3.5 opacity-60" />}+ </button>+ {open && (+ <>+ <div className="fixed inset-0 z-40" onClick={() => setOpen(false)} />+ <div+ role="menu"+ className="absolute right-0 top-full mt-1 z-50 rounded-lg border border-base-300 bg-base-100 shadow-lg py-1 min-w-[230px]"+ onClick={() => setOpen(false)}+ >+ {children}+ </div>+ </>+ )}+ </div>+ );+}++function MenuItem({+ icon,+ label,+ description,+ onClick,+ disabled,+}: {+ icon: ReactNode;+ label: string;+ description?: string;+ onClick: () => void;+ disabled?: boolean;+}) {+ return (+ <button+ type="button"+ role="menuitem"+ className="flex w-full items-start gap-2 px-3 py-2 text-sm hover:bg-base-200 disabled:opacity-50"+ onClick={onClick}+ disabled={disabled}+ >+ <span className="mt-0.5 shrink-0">{icon}</span>+ <span className="flex flex-col items-start text-left">+ <span>{label}</span>+ {description && (+ <span className="text-xs text-base-content/50">{description}</span>+ )}+ </span>+ </button>+ );+}++export function MoreMenu({+ onCheckNow,+ checkBusy,+ checkDisabled,+ onRefreshMetrics,+ metricsRefreshing,+ hasData,+}: {+ onCheckNow: () => void;+ checkBusy: boolean;+ checkDisabled: boolean;+ onRefreshMetrics: () => void;+ metricsRefreshing: boolean;+ hasData: boolean;+}) {+ return (+ <ToolbarMenu+ icon={<MoreHorizontal className="size-4" />}+ title="More actions"+ >+ {!checkDisabled && (+ <MenuItem+ icon={<Play className="size-3.5" />}+ label={checkBusy ? "Running..." : "Check rankings"}+ description="Fetch current Google positions"+ onClick={onCheckNow}+ disabled={checkBusy}+ />+ )}+ <MenuItem+ icon={+ <RefreshCw+ className={`size-3.5 ${metricsRefreshing ? "animate-spin" : ""}`}+ />+ }+ label={metricsRefreshing ? "Refreshing..." : "Update keyword stats"}+ description="Volume, difficulty & CPC — not rankings"+ onClick={onRefreshMetrics}+ disabled={metricsRefreshing || !hasData}+ />+ </ToolbarMenu>+ );+}++export function ExportMenu({+ onExport,+ onExportToSheets,+ onCopyKeywords,+ hasData,+}: {+ onExport: () => void;+ onExportToSheets: () => void;+ onCopyKeywords: () => void;+ hasData: boolean;+}) {+ return (+ <ToolbarMenu label="Export" icon={<Download className="size-3.5" />}>+ <MenuItem+ icon={<Sheet className="size-3.5" />}+ label="Export to Sheets"+ onClick={onExportToSheets}+ disabled={!hasData}+ />+ <MenuItem+ icon={<FileDown className="size-3.5" />}+ label="Export CSV"+ onClick={onExport}+ disabled={!hasData}+ />+ <MenuItem+ icon={<Copy className="size-3.5" />}+ label="Copy keywords"+ onClick={onCopyKeywords}+ disabled={!hasData}+ />+ </ToolbarMenu>+ );+}diff --git a/src/client/features/rank-tracking/rankTrackingScorecards.test.ts b/src/client/features/rank-tracking/rankTrackingScorecards.test.tsnew file mode 100644index 00000000..80271f6e--- /dev/null+++ b/src/client/features/rank-tracking/rankTrackingScorecards.test.ts@@ -0,0 +1,91 @@+import { describe, expect, it } from "vitest";+import type {+ RankTrackingDeviceResult,+ RankTrackingRow,+} from "@/types/schemas/rank-tracking";+import { computeScorecards } from "./rankTrackingScorecards";++function device(+ position: number | null,+ previousPosition: number | null,+): RankTrackingDeviceResult {+ return { position, previousPosition, rankingUrl: null, serpFeatures: [] };+}++function row(+ desktop: RankTrackingDeviceResult,+ mobile: RankTrackingDeviceResult = device(null, null),+ searchVolume: number | null = null,+): RankTrackingRow {+ return {+ trackingKeywordId: crypto.randomUUID(),+ keyword: "kw",+ searchVolume,+ keywordDifficulty: null,+ cpc: null,+ desktop,+ mobile,+ };+}++describe("computeScorecards", () => {+ it("counts ranking keywords and the delta vs the comparison period", () => {+ const rows = [row(device(2, 5)), row(device(null, 8))];+ const result = computeScorecards(rows, "desktop");+ // Only one keyword currently ranks (position 2); two ranked previously.+ expect(result.ranking).toBe(1);+ expect(result.rankingDelta).toBe(-1);++ const empty = computeScorecards([row(device(null, null))], "desktop");+ expect(empty.ranking).toBe(0);+ expect(empty.rankingDelta).toBe(0);+ });++ it("counts Top 3 and Top 10 (Top 3 subset of Top 10)", () => {+ const rows = [+ row(device(1, null)),+ row(device(3, null)),+ row(device(9, null)),+ row(device(15, null)),+ ];+ const result = computeScorecards(rows, "desktop");+ expect(result.top3).toBe(2);+ expect(result.top10).toBe(3);+ });++ it("computes volume-weighted visibility (0–100%) and its delta", () => {+ // A single keyword at #1 captures the full click potential → 100%.+ const top = computeScorecards(+ [row(device(1, null), undefined, 1000)],+ "desktop",+ );+ expect(top.visibility).toBe(100);+ expect(top.visibilityDelta).toBe(100); // was unranked (0%), now 100%++ // Ranking but not found now → 0% visibility.+ const lost = computeScorecards(+ [row(device(null, 1), undefined, 1000)],+ "desktop",+ );+ expect(lost.visibility).toBe(0);++ // No volume anywhere → not computable.+ const noVolume = computeScorecards([row(device(1, 1))], "desktop");+ expect(noVolume.visibility).toBeNull();+ expect(noVolume.visibilityDelta).toBeNull();+ });++ it("classifies improved/declined with the 4-case null rules", () => {+ const rows = [+ row(device(2, 5)), // moved up -> improved+ row(device(8, 4)), // moved down -> declined+ row(device(3, null)), // new entry -> improved+ row(device(null, 6)), // lost ranking -> declined+ row(device(null, null)), // nothing -> neither+ row(device(7, 7)), // unchanged -> neither+ ];+ const result = computeScorecards(rows, "desktop");+ expect(result.improved).toBe(2);+ expect(result.declined).toBe(2);+ });+});diff --git a/src/client/features/rank-tracking/rankTrackingScorecards.ts b/src/client/features/rank-tracking/rankTrackingScorecards.tsnew file mode 100644index 00000000..8d128f39--- /dev/null+++ b/src/client/features/rank-tracking/rankTrackingScorecards.ts@@ -0,0 +1,107 @@+import type { RankTrackingRow } from "@/types/schemas/rank-tracking";++// Approximate organic CTR by position (index = position; aggregate industry+// curves). Only used to weight the visibility metric, so relative weights+// matter, not exact values. Positions past the list fall back to a small CTR.+const CTR_BY_POSITION = [+ 0, 0.28, 0.15, 0.1, 0.07, 0.05, 0.04, 0.033, 0.028, 0.024, 0.021, 0.018,+ 0.016, 0.014, 0.012, 0.011, 0.01, 0.009, 0.008, 0.007, 0.006,+];+const TOP_CTR = CTR_BY_POSITION[1];++function ctr(position: number | null): number {+ if (position === null || position < 1) return 0;+ return CTR_BY_POSITION[position] ?? 0.005;+}++interface Scorecards {+ /**+ * Volume-weighted, CTR-weighted share of click potential captured (0–100):+ * Σ(volume × CTR@position) ÷ Σ(volume × CTR@1). null if no volume data.+ */+ visibility: number | null;+ /** change in visibility (percentage points) vs the comparison period */+ visibilityDelta: number | null;+ /** keywords currently ranking (found within the tracked depth) */+ ranking: number;+ /** change in ranking-keyword count vs the comparison period */+ rankingDelta: number;+ top3: number;+ top10: number;+ improved: number;+ declined: number;+}++/**+ * Portfolio scorecards from the already-loaded latest results for one device.+ * `ranking` counts keywords found within the tracked depth (a non-null+ * position) — unlike an average, it correctly drops when keywords fall out.+ * Improved/declined use the same 4-case null rules as DeviceRankCell: a "new"+ * entry counts as improved, a "lost" ranking counts as declined, and we never+ * subtract through a null.+ */+export function computeScorecards(+ rows: RankTrackingRow[],+ device: "desktop" | "mobile",+): Scorecards {+ let countCurrent = 0;+ let countPrevious = 0;+ let top3 = 0;+ let top10 = 0;+ let improved = 0;+ let declined = 0;+ let visNumCurrent = 0;+ let visNumPrevious = 0;+ let visVolume = 0; // Σ volume over keywords with known volume++ for (const row of rows) {+ const { position, previousPosition } = row[device];++ if (position !== null) {+ countCurrent += 1;+ if (position <= 3) top3 += 1;+ if (position <= 10) top10 += 1;+ }+ if (previousPosition !== null) {+ countPrevious += 1;+ }++ if (row.searchVolume != null && row.searchVolume > 0) {+ visVolume += row.searchVolume;+ visNumCurrent += row.searchVolume * ctr(position);+ visNumPrevious += row.searchVolume * ctr(previousPosition);+ }++ // 4-case change classification (mirrors DeviceRankCell)+ if (position === null && previousPosition === null) {+ // nothing tracked — neither improved nor declined+ } else if (position === null) {+ declined += 1; // was ranking, now lost+ } else if (previousPosition === null) {+ improved += 1; // new entry+ } else if (previousPosition - position > 0) {+ improved += 1; // moved up+ } else if (previousPosition - position < 0) {+ declined += 1; // moved down+ }+ }++ const visibility =+ visVolume > 0 ? (visNumCurrent / (visVolume * TOP_CTR)) * 100 : null;+ const visibilityPrevious =+ visVolume > 0 ? (visNumPrevious / (visVolume * TOP_CTR)) * 100 : null;++ return {+ visibility,+ visibilityDelta:+ visibility !== null && visibilityPrevious !== null+ ? visibility - visibilityPrevious+ : null,+ ranking: countCurrent,+ rankingDelta: countCurrent - countPrevious,+ top3,+ top10,+ improved,+ declined,+ };+}diff --git a/src/server/features/rank-tracking/rankTrackingTimestamps.ts b/src/server/features/rank-tracking/rankTrackingTimestamps.tsnew file mode 100644index 00000000..a278c0d5--- /dev/null+++ b/src/server/features/rank-tracking/rankTrackingTimestamps.ts@@ -0,0 +1,3 @@+export function toSqliteTimestamp(date: Date): string {+ return date.toISOString().slice(0, 19).replace("T", " ");+}diff --git a/src/server/features/rank-tracking/repositories/RankTrackingRepository.ts b/src/server/features/rank-tracking/repositories/RankTrackingRepository.tsindex 5367790c..a9065169 100644--- a/src/server/features/rank-tracking/repositories/RankTrackingRepository.ts+++ b/src/server/features/rank-tracking/repositories/RankTrackingRepository.ts@@ -12,6 +12,9 @@ import {getLatestSnapshotsForKeywords,getSnapshotsBeforeDate,getEarliestSnapshotsForKeywords,+ getKeywordHistory,+ getConfigTrend,+ getPositionMatrix,} from "./snapshotQueries";const DB_BATCH_SIZE = 100;@@ -380,4 +383,7 @@ export const RankTrackingRepository = {getLatestSnapshotsForKeywords,getSnapshotsBeforeDate,getEarliestSnapshotsForKeywords,+ getKeywordHistory,+ getConfigTrend,+ getPositionMatrix,};diff --git a/src/server/features/rank-tracking/repositories/snapshotQueries.test.ts b/src/server/features/rank-tracking/repositories/snapshotQueries.test.tsnew file mode 100644index 00000000..2451a65d--- /dev/null+++ b/src/server/features/rank-tracking/repositories/snapshotQueries.test.ts@@ -0,0 +1,10 @@+import { describe, expect, it } from "vitest";+import { toSqliteTimestamp } from "@/server/features/rank-tracking/rankTrackingTimestamps";++describe("rank tracking snapshot queries", () => {+ it("formats comparison cutoffs like SQLite current_timestamp", () => {+ expect(toSqliteTimestamp(new Date("2026-06-09T12:34:56.789Z"))).toBe(+ "2026-06-09 12:34:56",+ );+ });+});diff --git a/src/server/features/rank-tracking/repositories/snapshotQueries.ts b/src/server/features/rank-tracking/repositories/snapshotQueries.tsindex 33b9b7b6..402d7241 100644--- a/src/server/features/rank-tracking/repositories/snapshotQueries.ts+++ b/src/server/features/rank-tracking/repositories/snapshotQueries.ts@@ -1,6 +1,141 @@-import { and, eq, inArray, lte, max, min } from "drizzle-orm";+import {+ and,+ asc,+ count,+ desc,+ eq,+ gte,+ inArray,+ lte,+ max,+ min,+ sql,+} from "drizzle-orm";import { db } from "@/db";import { rankCheckRuns, rankSnapshots } from "@/db/schema";+import { toSqliteTimestamp } from "@/server/features/rank-tracking/rankTrackingTimestamps";++function completedRunIdsForConfig(configId: string) {+ return db+ .select({ id: rankCheckRuns.id })+ .from(rankCheckRuns)+ .where(+ and(+ eq(rankCheckRuns.configId, configId),+ eq(rankCheckRuns.status, "completed"),+ ),+ );+}++function cutoffTimestamp(sinceDays: number): string {+ return toSqliteTimestamp(+ new Date(Date.now() - sinceDays * 24 * 60 * 60 * 1000),+ );+}++/**+ * Flat per-keyword position series across completed runs, ordered oldest first.+ * `null` position = checked but not found within serpDepth (a real event, not a+ * missing check). The client pivots these rows per device.+ */+export async function getKeywordHistory(+ configId: string,+ trackingKeywordId: string,+ sinceDays: number,+) {+ return db+ .select({+ device: rankSnapshots.device,+ checkedAt: rankSnapshots.checkedAt,+ position: rankSnapshots.position,+ })+ .from(rankSnapshots)+ .where(+ and(+ inArray(rankSnapshots.runId, completedRunIdsForConfig(configId)),+ eq(rankSnapshots.trackingKeywordId, trackingKeywordId),+ gte(rankSnapshots.checkedAt, cutoffTimestamp(sinceDays)),+ ),+ )+ .orderBy(asc(rankSnapshots.checkedAt));+}++/**+ * Per-run keyword-position distribution for one device, oldest first. Grouped+ * by runId (not checkedAt — snapshots in a run don't share an exact insert+ * time); the run's startedAt is the x-axis timestamp. The buckets are disjoint+ * and cover every tracked keyword: a position past 20, or null (not found in+ * the tracked depth), falls into "not ranking" (derived from `total`).+ */+export async function getConfigTrend(+ configId: string,+ device: "desktop" | "mobile",+ sinceDays: number,+) {+ return db+ .select({+ runId: rankSnapshots.runId,+ checkedAt: rankCheckRuns.startedAt,+ total: count(),+ top3: sql<number>`sum(case when ${rankSnapshots.position} between 1 and 3 then 1 else 0 end)`,+ top4to10: sql<number>`sum(case when ${rankSnapshots.position} between 4 and 10 then 1 else 0 end)`,+ top11to20: sql<number>`sum(case when ${rankSnapshots.position} between 11 and 20 then 1 else 0 end)`,+ })+ .from(rankSnapshots)+ .innerJoin(rankCheckRuns, eq(rankSnapshots.runId, rankCheckRuns.id))+ .where(+ and(+ eq(rankCheckRuns.configId, configId),+ eq(rankCheckRuns.status, "completed"),+ eq(rankCheckRuns.isSubsetRun, false),+ eq(rankSnapshots.device, device),+ gte(rankSnapshots.checkedAt, cutoffTimestamp(sinceDays)),+ ),+ )+ .groupBy(rankSnapshots.runId, rankCheckRuns.startedAt)+ .orderBy(asc(rankCheckRuns.startedAt));+}++/**+ * Recent per-keyword positions for one device as a flat list, for the "by date"+ * history matrix. Bounded to the last `runLimit` completed runs; the client+ * pivots these into keyword rows × run (date) columns.+ */+export async function getPositionMatrix(+ configId: string,+ device: "desktop" | "mobile",+ runLimit: number,+) {+ const recentRunIds = db+ .select({ id: rankCheckRuns.id })+ .from(rankCheckRuns)+ .where(+ and(+ eq(rankCheckRuns.configId, configId),+ eq(rankCheckRuns.status, "completed"),+ eq(rankCheckRuns.isSubsetRun, false),+ ),+ )+ .orderBy(desc(rankCheckRuns.startedAt))+ .limit(runLimit);++ return db+ .select({+ runId: rankSnapshots.runId,+ checkedAt: rankCheckRuns.startedAt,+ trackingKeywordId: rankSnapshots.trackingKeywordId,+ position: rankSnapshots.position,+ })+ .from(rankSnapshots)+ .innerJoin(rankCheckRuns, eq(rankSnapshots.runId, rankCheckRuns.id))+ .where(+ and(+ inArray(rankSnapshots.runId, recentRunIds),+ eq(rankSnapshots.device, device),+ ),+ )+ .orderBy(asc(rankCheckRuns.startedAt));+}/*** Pick one snapshot per keyword+device from completed runs, using SQL GROUP BYdiff --git a/src/server/features/rank-tracking/services/rankTrackingResults.ts b/src/server/features/rank-tracking/services/rankTrackingResults.tsindex 0e94427f..0fbaa8de 100644--- a/src/server/features/rank-tracking/services/rankTrackingResults.ts+++ b/src/server/features/rank-tracking/services/rankTrackingResults.ts@@ -1,4 +1,5 @@import { RankTrackingRepository } from "@/server/features/rank-tracking/repositories/RankTrackingRepository";+import { toSqliteTimestamp } from "@/server/features/rank-tracking/rankTrackingTimestamps";import { AppError } from "@/server/lib/errors";import type { ComparePeriod } from "@/types/schemas/rank-tracking";import type {@@ -42,9 +43,9 @@ export async function getLatestResults(// Get comparison snapshots from before the target dateconst days = PERIOD_DAYS[comparePeriod];- const targetDate = new Date(- Date.now() - days * 24 * 60 * 60 * 1000,- ).toISOString();+ const targetDate = toSqliteTimestamp(+ new Date(Date.now() - days * 24 * 60 * 60 * 1000),+ );const comparisonSnapshots =await RankTrackingRepository.getSnapshotsBeforeDate(configId, targetDate);diff --git a/src/serverFunctions/rank-tracking.ts b/src/serverFunctions/rank-tracking.tsindex aae52549..c77b4f3c 100644--- a/src/serverFunctions/rank-tracking.ts+++ b/src/serverFunctions/rank-tracking.ts@@ -19,8 +19,44 @@ import {addKeywordsSchema,removeKeywordsSchema,refreshMetricsSchema,+ getKeywordHistorySchema,+ getConfigTrendSchema,+ getPositionMatrixSchema,} from "@/types/schemas/rank-tracking";+export interface RankKeywordHistoryPoint {+ device: "desktop" | "mobile";+ checkedAt: string;+ position: number | null;+}++interface RankConfigTrendPoint {+ runId: string;+ checkedAt: string;+ top3: number;+ top4to10: number;+ top11to20: number;+ notRanking: number;+}++export interface RankPositionMatrixCell {+ runId: string;+ checkedAt: string;+ trackingKeywordId: string;+ position: number | null;+}++async function requireConfig(configId: string, projectId: string) {+ const config = await RankTrackingRepository.getConfigById({+ configId,+ projectId,+ });+ if (!config) {+ throw new AppError("INTERNAL_ERROR", "Rank tracking config not found");+ }+ return config;+}+export const getRankTrackingConfigs = createServerFn({ method: "POST" }).middleware(requireProjectContext).inputValidator((data: unknown) => getConfigsSchema.parse(data))@@ -251,3 +287,55 @@ export const refreshTrackingKeywordMetrics = createServerFn({ method: "POST" })return result;});++export const getRankKeywordHistory = createServerFn({ method: "POST" })+ .middleware(requireProjectContext)+ .inputValidator((data: unknown) => getKeywordHistorySchema.parse(data))+ .handler(async ({ data, context }): Promise<RankKeywordHistoryPoint[]> => {+ await requireConfig(data.configId, context.projectId);+ return RankTrackingRepository.getKeywordHistory(+ data.configId,+ data.trackingKeywordId,+ data.sinceDays,+ );+ });++export const getRankConfigTrend = createServerFn({ method: "POST" })+ .middleware(requireProjectContext)+ .inputValidator((data: unknown) => getConfigTrendSchema.parse(data))+ .handler(async ({ data, context }): Promise<RankConfigTrendPoint[]> => {+ await requireConfig(data.configId, context.projectId);+ const rows = await RankTrackingRepository.getConfigTrend(+ data.configId,+ data.device,+ data.sinceDays,+ );+ // SQLite sum()/count() can return strings; coerce and derive "not ranking"+ // (position > 20 or null) as the remainder so the buckets cover every kw.+ return rows.map((row) => {+ const top3 = Number(row.top3) || 0;+ const top4to10 = Number(row.top4to10) || 0;+ const top11to20 = Number(row.top11to20) || 0;+ const total = Number(row.total) || 0;+ return {+ runId: row.runId,+ checkedAt: row.checkedAt,+ top3,+ top4to10,+ top11to20,+ notRanking: Math.max(0, total - top3 - top4to10 - top11to20),+ };+ });+ });++export const getRankPositionMatrix = createServerFn({ method: "POST" })+ .middleware(requireProjectContext)+ .inputValidator((data: unknown) => getPositionMatrixSchema.parse(data))+ .handler(async ({ data, context }): Promise<RankPositionMatrixCell[]> => {+ await requireConfig(data.configId, context.projectId);+ return RankTrackingRepository.getPositionMatrix(+ data.configId,+ data.device,+ data.runLimit,+ );+ });diff --git a/src/types/schemas/rank-tracking.ts b/src/types/schemas/rank-tracking.tsindex 2fb176d4..8451b7d4 100644--- a/src/types/schemas/rank-tracking.ts+++ b/src/types/schemas/rank-tracking.ts@@ -114,3 +114,27 @@ export const refreshMetricsSchema = z.object({projectId: z.string().uuid(),configId: z.string().uuid(),});++const deviceEnum = z.enum(["desktop", "mobile"]);+const sinceDaysField = z.number().int().positive().max(730).default(365);++export const getKeywordHistorySchema = z.object({+ projectId: z.string().uuid(),+ configId: z.string().uuid(),+ trackingKeywordId: z.string().uuid(),+ sinceDays: sinceDaysField,+});++export const getConfigTrendSchema = z.object({+ projectId: z.string().uuid(),+ configId: z.string().uuid(),+ device: deviceEnum,+ sinceDays: sinceDaysField,+});++export const getPositionMatrixSchema = z.object({+ projectId: z.string().uuid(),+ configId: z.string().uuid(),+ device: deviceEnum,+ runLimit: z.number().int().positive().max(26).default(12),+});