Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
Control keyword variants with a saved grouping preference (EVE-270) (#666)
Carter Smith2534bfdd4ad4
diff --git a/plugins/openseo/.claude-plugin/plugin.json b/plugins/openseo/.claude-plugin/plugin.jsonindex 8ffcc26a..8a92c657 100644--- a/plugins/openseo/.claude-plugin/plugin.json+++ b/plugins/openseo/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "openseo","displayName": "OpenSEO",- "version": "1.0.2",+ "version": "1.0.3","description": "Without good data, your agent gives generic advice. Keyword research, competitor research, backlinks, and site audits. All for $10/month.","author": {"name": "OpenSEO",diff --git a/plugins/openseo/.codex-plugin/plugin.json b/plugins/openseo/.codex-plugin/plugin.jsonindex ff9e24de..34e9ae32 100644--- a/plugins/openseo/.codex-plugin/plugin.json+++ b/plugins/openseo/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "openseo",- "version": "1.0.2",+ "version": "1.0.3","description": "Without good data, your agent gives generic advice. Keyword research, competitor research, backlinks, and site audits. All for $10/month.","author": {"name": "OpenSEO",diff --git a/plugins/openseo/.cursor-plugin/plugin.json b/plugins/openseo/.cursor-plugin/plugin.jsonindex 2d1201d2..d0cebede 100644--- a/plugins/openseo/.cursor-plugin/plugin.json+++ b/plugins/openseo/.cursor-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "openseo",- "version": "1.0.2",+ "version": "1.0.3","description": "SEO made simple. Research keywords and competitors, audit sites, track rankings, and use Search Console data from your agent.","author": {"name": "Every App, Inc",diff --git a/src/client/features/keywords/groupSharedVolumeRows.test.ts b/src/client/features/keywords/groupSharedVolumeRows.test.tsindex d42b0906..961f8c03 100644--- a/src/client/features/keywords/groupSharedVolumeRows.test.ts+++ b/src/client/features/keywords/groupSharedVolumeRows.test.ts@@ -1,6 +1,6 @@import { describe, expect, it } from "vitest";import type { KeywordResearchRow } from "@/types/keywords";-import { groupSharedVolumeRows, ungroupRows } from "./groupSharedVolumeRows";+import { groupSharedVolumeRows } from "./groupSharedVolumeRows";const SERIES = [{ year: 2026, month: 7, searchVolume: 110000 },@@ -21,25 +21,30 @@ function row(overrides: Partial<KeywordResearchRow>): KeywordResearchRow {}describe("groupSharedVolumeRows", () => {- it("folds rows with the same volume, CPC, and monthly series under the first", () => {+ it("keeps variants visible after their leader with their own metrics", () => {const rows = [row({ keyword: "caregiving" }),row({ keyword: "respite care", searchVolume: 165000 }),row({ keyword: "caregiver", keywordDifficulty: 45 }),];- const grouped = groupSharedVolumeRows(rows);+ const grouped = groupSharedVolumeRows(rows, undefined, true);expect(grouped.map((r) => r.keyword)).toEqual([- "caregiving",- "respite care",- ]);- expect(grouped[0].variants).toEqual([rows[2]]);- expect(ungroupRows(grouped).map((r) => r.keyword)).toEqual(["caregiving","caregiver","respite care",]);+ expect(grouped[1]).toEqual({+ ...rows[2],+ parentKeyword: "caregiving",+ });+ expect(grouped[0].parentKeyword).toBeNull();+ expect(grouped[2].parentKeyword).toBeNull();+ const ungrouped = groupSharedVolumeRows(rows, "caregiver", false);+ expect(ungrouped).toEqual(+ rows.map((keyword) => ({ ...keyword, parentKeyword: null })),+ );});it("leads a group with the searched keyword as typed", () => {@@ -48,10 +53,13 @@ describe("groupSharedVolumeRows", () => {row({ keyword: "caregiving" }),];- const [group] = groupSharedVolumeRows(rows, " Caregiving");+ const [group, child] = groupSharedVolumeRows(rows, " Caregiving", true);expect(group.keyword).toBe("caregiving");- expect(group.variants.map((r) => r.keyword)).toEqual(["caregiver"]);+ expect(child).toEqual({+ ...rows[0],+ parentKeyword: "caregiving",+ });});it("keeps rows apart when the shared number is a flat or low-volume bucket", () => {@@ -63,6 +71,6 @@ describe("groupSharedVolumeRows", () => {row({ keyword: "d", searchVolume: 90 }),];- expect(groupSharedVolumeRows(rows)).toHaveLength(4);+ expect(groupSharedVolumeRows(rows, undefined, true)).toHaveLength(4);});});diff --git a/src/client/features/keywords/groupSharedVolumeRows.ts b/src/client/features/keywords/groupSharedVolumeRows.tsindex 7d4ad123..790e3172 100644--- a/src/client/features/keywords/groupSharedVolumeRows.ts+++ b/src/client/features/keywords/groupSharedVolumeRows.ts@@ -1,8 +1,8 @@import type { KeywordResearchRow } from "@/types/keywords";-/** A results row plus the other keywords that report the same search volume. */+/** A visible keyword row, optionally indented beneath a shared-volume parent. */export type KeywordResearchDisplayRow = KeywordResearchRow & {- variants: KeywordResearchRow[];+ parentKeyword: string | null;};// Only group above this volume: bucketed low volumes (10, 20, ...) collide by@@ -27,42 +27,41 @@ function sharedVolumeKey(row: KeywordResearchRow): string | null {/*** Google Ads reports one volume for a whole close-variant group ("caregiving"* / "caregiver" / "caregivers"), so those rows all claim the same searches.- * Fold rows with an identical volume, CPC, and monthly series under the+ * Place rows with an identical volume, CPC, and monthly series after the* searched keyword when it is in the group, otherwise under the first one in* the given order. Display only: every keyword keeps its own metrics- * and stays in the data, so filters and exports still reach each variant.+ * when grouping is enabled. With grouping off, preserve the input order.*/export function groupSharedVolumeRows(rows: KeywordResearchRow[],- searchedKeyword?: string,+ searchedKeyword: string | undefined,+ groupKeywords: boolean,): KeywordResearchDisplayRow[] {+ if (!groupKeywords) {+ return rows.map((row) => ({ ...row, parentKeyword: null }));+ }// Row keywords are lowercase; the searched keyword arrives as typed.const seed = searchedKeyword?.trim().toLowerCase();- const groups = new Map<string, KeywordResearchDisplayRow>();- const result: KeywordResearchDisplayRow[] = [];+ const groups = new Map<string, KeywordResearchRow[]>();+ const result: KeywordResearchRow[][] = [];for (const row of rows) {const key = sharedVolumeKey(row);const group = key ? groups.get(key) : undefined;- if (group && row.keyword === seed) {- const { variants, ...leader } = group;- Object.assign(group, row, { variants: [leader, ...variants] });- continue;- }if (group) {- group.variants.push(row);+ if (row.keyword === seed) group.unshift(row);+ else group.push(row);continue;}- const displayRow = { ...row, variants: [] };- if (key) groups.set(key, displayRow);- result.push(displayRow);+ const newGroup = [row];+ if (key) groups.set(key, newGroup);+ result.push(newGroup);}- return result;-}--export function ungroupRows(- rows: KeywordResearchDisplayRow[],-): KeywordResearchRow[] {- return rows.flatMap(({ variants, ...row }) => [row, ...variants]);+ return result.flatMap((group) =>+ group.map((row, index) => ({+ ...row,+ parentKeyword: index === 0 ? null : group[0].keyword,+ })),+ );}diff --git a/src/client/features/keywords/hooks/useKeywordFiltering.ts b/src/client/features/keywords/hooks/useKeywordFiltering.tsindex 5d2488bf..a9c43e87 100644--- a/src/client/features/keywords/hooks/useKeywordFiltering.ts+++ b/src/client/features/keywords/hooks/useKeywordFiltering.ts@@ -74,31 +74,33 @@ export function applyKeywordFiltersAndSort(params: {export function useKeywordFiltering(params: {rows: KeywordResearchRow[];searchedKeyword: string;+ groupKeywords: boolean;filters: KeywordFilterValues;sortField: SortField;sortDir: SortDir;}) {// Group after filtering so a variant that passes the filters on its own// (say, a lower difficulty) is never hidden behind one that does not.- const filteredRows = useMemo(- () =>- groupSharedVolumeRows(- applyKeywordFiltersAndSort({- rows: params.rows,- filters: params.filters,- sortField: params.sortField,- sortDir: params.sortDir,- }),- params.searchedKeyword,- ),- [- params.filters,- params.rows,+ const filteredRows = useMemo(() => {+ const rows = applyKeywordFiltersAndSort({+ rows: params.rows,+ filters: params.filters,+ sortField: params.sortField,+ sortDir: params.sortDir,+ });+ return groupSharedVolumeRows(+ rows,params.searchedKeyword,- params.sortDir,- params.sortField,- ],- );+ params.groupKeywords,+ );+ }, [+ params.filters,+ params.groupKeywords,+ params.rows,+ params.searchedKeyword,+ params.sortDir,+ params.sortField,+ ]);const activeFilterCount = useMemo(() =>diff --git a/src/client/features/keywords/hooks/useKeywordResearchData.test.ts b/src/client/features/keywords/hooks/useKeywordResearchData.test.tsindex 7e414cb8..3b761696 100644--- a/src/client/features/keywords/hooks/useKeywordResearchData.test.ts+++ b/src/client/features/keywords/hooks/useKeywordResearchData.test.ts@@ -4,7 +4,10 @@ import { describe, expect, it, vi } from "vitest";// Workers-only bindings that don't resolve outside workerd.vi.mock("cloudflare:workers", () => ({ env: {} }));-import { buildKeywordResearchRequest } from "./useKeywordResearchData";+import {+ buildKeywordResearchRequest,+ buildKeywordResearchQueryKey,+} from "./useKeywordResearchData";const baseInput = {projectId: "project_1",@@ -13,14 +16,23 @@ const baseInput = {resultLimit: 150 as const,mode: "auto" as const,clickstream: false,+ groupKeywords: false,};describe("buildKeywordResearchRequest", () => {it("carries an explicitly selected location without a language", () => {const request = buildKeywordResearchRequest(baseInput);- expect(request).toMatchObject({ locationCode: 2704 });+ expect(request).toMatchObject({ locationCode: 2704, groupKeywords: false });expect(request).not.toHaveProperty("languageCode");+ const grouped = buildKeywordResearchRequest({+ ...baseInput,+ groupKeywords: true,+ });+ expect(grouped).toMatchObject({ groupKeywords: true });+ expect(buildKeywordResearchQueryKey(grouped)).not.toEqual(+ buildKeywordResearchQueryKey(request),+ );});it("leaves the location undefined for the server to resolve", () => {diff --git a/src/client/features/keywords/hooks/useKeywordResearchData.ts b/src/client/features/keywords/hooks/useKeywordResearchData.tsindex ede39ca6..7bd35606 100644--- a/src/client/features/keywords/hooks/useKeywordResearchData.ts+++ b/src/client/features/keywords/hooks/useKeywordResearchData.ts@@ -23,6 +23,7 @@ type KeywordResearchRequestInput = {resultLimit: ResultLimit;mode: KeywordMode;clickstream: boolean;+ groupKeywords: boolean;};type KeywordResearchQueryInput = KeywordResearchRequestInput & {@@ -37,6 +38,7 @@ type KeywordResearchRequest = {resultLimit: ResultLimit;mode: KeywordMode;clickstream: boolean;+ groupKeywords: boolean;};export const KEYWORD_RESEARCH_STALE_TIME_MS = 24 * 60 * 60 * 1000;@@ -56,6 +58,7 @@ export function buildKeywordResearchRequest(resultLimit: input.resultLimit,mode: input.mode,clickstream: input.clickstream,+ groupKeywords: input.groupKeywords,};}@@ -71,6 +74,7 @@ export function buildKeywordResearchQueryKey(request.resultLimit,request.mode,request.clickstream,+ request.groupKeywords,]: ["keywordResearch", "idle"];}@@ -84,6 +88,7 @@ export function keywordResearchQueryFn(request: KeywordResearchRequest) {resultLimit: request.resultLimit,mode: request.mode,clickstream: request.clickstream,+ groupKeywords: request.groupKeywords,},});}@@ -94,6 +99,7 @@ export function useKeywordResearchData() {const {clickstream,+ groupKeywords,displayedLocationCode,keywordInput,locationCode,@@ -110,8 +116,17 @@ export function useKeywordResearchData(projectId,resultLimit,clickstream,+ groupKeywords,}),- [clickstream, keywordInput, locationCode, mode, projectId, resultLimit],+ [+ clickstream,+ groupKeywords,+ keywordInput,+ locationCode,+ mode,+ projectId,+ resultLimit,+ ],);const queryKey = useMemo(() => buildKeywordResearchQueryKey(request),diff --git a/src/client/features/keywords/hooks/usePreferredKeywordGrouping.ts b/src/client/features/keywords/hooks/usePreferredKeywordGrouping.tsnew file mode 100644index 00000000..987c2ca0--- /dev/null+++ b/src/client/features/keywords/hooks/usePreferredKeywordGrouping.ts@@ -0,0 +1,46 @@+import { useEffect, useState } from "react";+import { z } from "zod";++const storageKey = (projectId: string) =>+ `keyword-preferred-grouping:${projectId}`;++export function loadPreferredGrouping(projectId: string): boolean {+ try {+ const raw = localStorage.getItem(storageKey(projectId));+ if (!raw) return false;+ return z.boolean().parse(JSON.parse(raw));+ } catch {+ return false;+ }+}++/** Like country selection, grouping is a per-project browser preference. */+export function usePreferredKeywordGrouping(projectId: string) {+ const [preference, setPreference] = useState(() => ({+ projectId,+ groupKeywords: loadPreferredGrouping(projectId),+ }));+ const groupKeywords =+ preference.projectId === projectId+ ? preference.groupKeywords+ : loadPreferredGrouping(projectId);++ useEffect(() => {+ if (preference.projectId === projectId) return;+ setPreference({ projectId, groupKeywords });+ }, [groupKeywords, preference.projectId, projectId]);++ function setGroupKeywords(nextGroupKeywords: boolean) {+ setPreference({ projectId, groupKeywords: nextGroupKeywords });+ try {+ localStorage.setItem(+ storageKey(projectId),+ JSON.stringify(nextGroupKeywords),+ );+ } catch {+ // Keep the current choice usable when browser storage is unavailable.+ }+ }++ return { groupKeywords, setGroupKeywords };+}diff --git a/src/client/features/keywords/page/KeywordResearchDesktopResults.tsx b/src/client/features/keywords/page/KeywordResearchDesktopResults.tsxindex 5789b843..3dc98e7e 100644--- a/src/client/features/keywords/page/KeywordResearchDesktopResults.tsx+++ b/src/client/features/keywords/page/KeywordResearchDesktopResults.tsx@@ -117,22 +117,27 @@ function DesktopTableCard({ controller }: Props) {sheetsExportRows,showFilters,} = controller;- const { page, pageSize, pageRows, setPage, setPageSize } =- useKeywordResearchPagination(filteredRows);- const keywordCount = filteredRows.reduce(- (count, row) => count + 1 + row.variants.length,- 0,- );+ const {+ page,+ pageSize,+ pageRows,+ setPage,+ setPageSize,+ start,+ end,+ totalPages,+ } = useKeywordResearchPagination(filteredRows);+ const keywordCount = filteredRows.length;const keywordCountLabel =selectedRows.size > 0- ? `${selectedRows.size} of ${filteredRows.length} selected`+ ? `${selectedRows.size} selected`: activeFilterCount > 0? `Showing ${keywordCount} of ${rows.length} keywords`: `Showing ${keywordCount} keywords`;const canExport = filteredRows.length > 0;- const selectedExportRows = filteredRows+ const selectedExportRows = rows.filter((row) => selectedRows.has(row.keyword)).map(keywordResearchExportRow);const handleExportToSheets = () => {@@ -160,7 +165,7 @@ function DesktopTableCard({ controller }: Props) {return (<div className="flex-1 flex flex-col min-w-0 border border-base-300 rounded-xl bg-base-100 overflow-hidden">- <div className="shrink-0 flex items-center gap-2 px-4 py-2 border-b border-base-300">+ <div className="shrink-0 flex flex-wrap items-center gap-2 px-4 py-2 border-b border-base-300"><buttonclassName={`btn btn-ghost btn-sm gap-1.5 ${showFilters ? "btn-active" : ""}`}onClick={() => controller.setShowFilters((current) => !current)}@@ -252,6 +257,9 @@ function DesktopTableCard({ controller }: Props) {/>{filteredRows.length > 0 ? (<KeywordResearchPagination+ start={start}+ end={end}+ totalPages={totalPages}page={page}pageSize={pageSize}totalCount={filteredRows.length}diff --git a/src/client/features/keywords/page/KeywordResearchDesktopTable.tsx b/src/client/features/keywords/page/KeywordResearchDesktopTable.tsxindex d033869e..2cc2ea6c 100644--- a/src/client/features/keywords/page/KeywordResearchDesktopTable.tsx+++ b/src/client/features/keywords/page/KeywordResearchDesktopTable.tsx@@ -35,25 +35,6 @@ type Props = {handleRowClick: (row: KeywordResearchRow) => void;};-/** The close variants that report the same search volume as the row above. */-function SharedVolumeVariants({- variants,-}: {- variants: KeywordResearchRow[];-}) {- if (variants.length === 0) return null;- const keywords = variants.map((variant) => variant.keyword).join(", ");-- return (- <span- className="block max-w-64 truncate text-xs font-normal text-base-content/50"- title={keywords}- >- {keywords}- </span>- );-}-const keywordColumnHelper = createColumnHelper<KeywordResearchDisplayRow>();export function KeywordResearchDesktopTable({@@ -91,14 +72,19 @@ export function KeywordResearchDesktopTable({/>),cell: ({ row }) => (- <div className="min-w-48 md:min-w-0">+ <div+ className={`min-w-48 md:min-w-0 ${row.original.parentKeyword ? "pl-4" : ""}`}+ ><span- className="block whitespace-normal break-words font-medium capitalize md:truncate"- title={row.original.keyword}+ className={`block whitespace-normal break-words capitalize md:truncate ${row.original.parentKeyword ? "font-normal" : "font-medium"}`}+ title={+ row.original.parentKeyword+ ? `${row.original.keyword}: matching reported volume with ${row.original.parentKeyword}. Shared volumes may overlap.`+ : row.original.keyword+ }>{row.original.keyword}</span>- <SharedVolumeVariants variants={row.original.variants} /></div>),meta: {@@ -117,7 +103,8 @@ export function KeywordResearchDesktopTable({className="justify-end"/>),- cell: ({ getValue }) => formatNumber(getValue()),+ cell: ({ row, getValue }) =>+ row.original.parentKeyword ? null : formatNumber(getValue()),meta: {headerClassName: "text-right",cellClassName:@@ -136,7 +123,8 @@ export function KeywordResearchDesktopTable({className="justify-end"/>),- cell: ({ getValue }) => {+ cell: ({ row, getValue }) => {+ if (row.original.parentKeyword) return null;const value = getValue();return value == null ? "-" : value.toFixed(2);},@@ -158,7 +146,8 @@ export function KeywordResearchDesktopTable({className="justify-end"/>),- cell: ({ getValue }) => {+ cell: ({ row, getValue }) => {+ if (row.original.parentKeyword) return null;const value = getValue();return value == null ? "-" : value.toFixed(2);},diff --git a/src/client/features/keywords/page/KeywordResearchMobileResults.tsx b/src/client/features/keywords/page/KeywordResearchMobileResults.tsxindex 62d9f215..ac6cfda5 100644--- a/src/client/features/keywords/page/KeywordResearchMobileResults.tsx+++ b/src/client/features/keywords/page/KeywordResearchMobileResults.tsx@@ -92,12 +92,17 @@ function MobileKeywordResults({ controller }: Props) {sheetsExportRows,showFilters,} = controller;- const { page, pageSize, pageRows, setPage, setPageSize } =- useKeywordResearchPagination(filteredRows);- const keywordCount = filteredRows.reduce(- (count, row) => count + 1 + row.variants.length,- 0,- );+ const {+ page,+ pageSize,+ pageRows,+ setPage,+ setPageSize,+ start,+ end,+ totalPages,+ } = useKeywordResearchPagination(filteredRows);+ const keywordCount = filteredRows.length;const keywordCountLabel =selectedRows.size > 0@@ -107,7 +112,7 @@ function MobileKeywordResults({ controller }: Props) {: `Showing ${keywordCount} keywords`;const canExport = filteredRows.length > 0;- const selectedExportRows = filteredRows+ const selectedExportRows = rows.filter((row) => selectedRows.has(row.keyword)).map(keywordResearchExportRow);const handleExportToSheets = () => {@@ -146,7 +151,7 @@ function MobileKeywordResults({ controller }: Props) {</div>) : null}- <div className="shrink-0 flex items-center gap-2 px-4 py-2 border-b border-base-300 bg-base-100">+ <div className="shrink-0 flex flex-wrap items-center gap-2 px-4 py-2 border-b border-base-300 bg-base-100"><buttonclassName={`btn btn-ghost btn-xs gap-1 ${showFilters ? "btn-active" : ""}`}onClick={() => controller.setShowFilters((current) => !current)}@@ -238,6 +243,9 @@ function MobileKeywordResults({ controller }: Props) {/>{filteredRows.length > 0 ? (<KeywordResearchPagination+ start={start}+ end={end}+ totalPages={totalPages}page={page}pageSize={pageSize}totalCount={filteredRows.length}diff --git a/src/client/features/keywords/page/KeywordResearchPagination.test.ts b/src/client/features/keywords/page/KeywordResearchPagination.test.tsnew file mode 100644index 00000000..f61475bf--- /dev/null+++ b/src/client/features/keywords/page/KeywordResearchPagination.test.ts@@ -0,0 +1,51 @@+import { expect, it } from "vitest";+import type { KeywordResearchDisplayRow } from "../groupSharedVolumeRows";+import { keywordResearchPageEnds } from "./KeywordResearchPagination";++function row(+ keyword: string,+ parentKeyword: string | null = null,+): KeywordResearchDisplayRow {+ return {+ keyword,+ parentKeyword,+ searchVolume: null,+ cpc: null,+ competition: null,+ keywordDifficulty: null,+ intent: "unknown",+ trend: [],+ };+}++it("keeps the boundary parent and all its children on the same page", () => {+ const rows = [+ ...Array.from({ length: 49 }, (_, index) => row(String(index))),+ row("parent"),+ row("child1", "parent"),+ row("child2", "parent"),+ ...Array.from({ length: 50 }, (_, index) => row(`next${index}`)),+ ];+ const ends = keywordResearchPageEnds(rows, 50);+ expect(ends).toEqual([52, 102]);+ const pages = ends.map((end, index) => rows.slice(ends[index - 1] ?? 0, end));+ expect(pages.flat()).toEqual(rows);+ expect(pages.every((page) => page[0].parentKeyword === null)).toBe(true);+});++it("allows an oversized family and retains ordinary boundaries with grouping off", () => {+ const rows = [+ row("parent"),+ row("one", "parent"),+ row("two", "parent"),+ row("next"),+ ];+ expect(keywordResearchPageEnds(rows, 2)).toEqual([3, 4]);+ expect(+ keywordResearchPageEnds(+ rows.map((item) => ({ ...item, parentKeyword: null })),+ 2,+ ),+ ).toEqual([2, 4]);+ expect(keywordResearchPageEnds([], 50)).toEqual([]);+});diff --git a/src/client/features/keywords/page/KeywordResearchPagination.tsx b/src/client/features/keywords/page/KeywordResearchPagination.tsxindex 06b74e4c..827d23ed 100644--- a/src/client/features/keywords/page/KeywordResearchPagination.tsx+++ b/src/client/features/keywords/page/KeywordResearchPagination.tsx@@ -1,6 +1,6 @@import { ChevronLeft, ChevronRight } from "lucide-react";import { useEffect, useMemo, useState } from "react";-import type { KeywordResearchRow } from "@/types/keywords";+import type { KeywordResearchDisplayRow } from "../groupSharedVolumeRows";const KEYWORD_RESEARCH_PAGE_SIZES = [50, 100, 300, 500] as const;const DEFAULT_KEYWORD_RESEARCH_PAGE_SIZE = 50;@@ -13,6 +13,9 @@ type Props = {page: number;pageSize: KeywordResearchPageSize;totalCount: number;+ totalPages: number;+ start: number;+ end: number;onPageChange: (page: number) => void;onPageSizeChange: (pageSize: KeywordResearchPageSize) => void;};@@ -21,13 +24,12 @@ export function KeywordResearchPagination({page,pageSize,totalCount,+ totalPages,+ start,+ end,onPageChange,onPageSizeChange,}: Props) {- const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));- const start = totalCount === 0 ? 0 : (page - 1) * pageSize + 1;- const end = Math.min(totalCount, page * pageSize);-return (<div className="flex flex-col gap-3 border-t border-base-300 px-4 py-3 sm:flex-row sm:items-center sm:justify-between"><div className="text-sm tabular-nums text-base-content/70">@@ -89,14 +91,36 @@ function parseKeywordResearchPageSize(value: string): KeywordResearchPageSize {);}-export function useKeywordResearchPagination<Row extends KeywordResearchRow>(- rows: Row[],+export function keywordResearchPageEnds(+ rows: KeywordResearchDisplayRow[],+ pageSize: number,+) {+ const ends: number[] = [];+ for (let start = 0; start < rows.length; ) {+ let end = Math.min(start + pageSize, rows.length);+ // Finish the last family before starting the next page.+ while (end < rows.length && rows[end].parentKeyword !== null) end++;+ ends.push(end);+ start = end;+ }+ return ends;+}++export function useKeywordResearchPagination(+ rows: KeywordResearchDisplayRow[],) {const [page, setPage] = useState(1);const [pageSize, setPageSize] = useState<KeywordResearchPageSize>(() =>getStoredKeywordResearchPageSize(),);- const totalPages = Math.max(1, Math.ceil(rows.length / pageSize));+ const pageEnds = useMemo(+ () => keywordResearchPageEnds(rows, pageSize),+ [rows, pageSize],+ );+ const totalPages = Math.max(1, pageEnds.length);+ const currentPage = Math.min(page, totalPages);+ const start = pageEnds[currentPage - 2] ?? 0;+ const end = pageEnds[currentPage - 1] ?? 0;useEffect(() => {setPage(1);@@ -106,13 +130,12 @@ export function useKeywordResearchPagination<Row extends KeywordResearchRow>(setPage((current) => Math.min(current, totalPages));}, [totalPages]);- const pageRows = useMemo(() => {- const start = (page - 1) * pageSize;- return rows.slice(start, start + pageSize);- }, [page, pageSize, rows]);+ const pageRows = useMemo(() => rows.slice(start, end), [start, end, rows]);return {- page,+ page: currentPage,+ start: rows.length === 0 ? 0 : start + 1,+ end,pageSize,pageRows,setPage,diff --git a/src/client/features/keywords/page/KeywordResearchSearchBar.tsx b/src/client/features/keywords/page/KeywordResearchSearchBar.tsxindex baf44ab3..6f9ab94c 100644--- a/src/client/features/keywords/page/KeywordResearchSearchBar.tsx+++ b/src/client/features/keywords/page/KeywordResearchSearchBar.tsx@@ -129,49 +129,65 @@ export function KeywordResearchSearchBar({ controller }: Props) {) : null;}}</controlsForm.Field>- <controlsForm.Field name="locationCode">- {(locationField) =>- isLabsLocationCode(locationField.state.value) ? (- <controlsForm.Field name="clickstream">- {(field) => (- <div className="flex items-center gap-2">- <label className="label cursor-pointer justify-start gap-2 p-0">- <input- type="checkbox"- className="toggle toggle-sm toggle-primary"- checked={field.state.value}- onChange={(event) =>- field.handleChange(event.target.checked)- }- />- <span className="text-sm font-medium text-base-content/80">- Clickstream-refined volumes- </span>- </label>- <div- className="tooltip tooltip-right"- data-tip="Google reports one combined search volume for similar keywords (e.g. 'seo tool' and 'seo tools'). Turn this on to estimate each keyword's own volume. Costs 2x the credits."- >- <Info className="size-3.5 text-base-content/50" />+ <div className="flex flex-wrap items-center gap-x-6 gap-y-2">+ <label className="label cursor-pointer justify-start gap-2 p-0">+ <input+ type="checkbox"+ role="switch"+ className="toggle toggle-sm toggle-primary"+ checked={controller.groupKeywords}+ onChange={(event) =>+ controller.setGroupKeywords(event.target.checked)+ }+ />+ <span className="text-sm font-medium text-base-content/80">+ Group keywords+ </span>+ </label>+ <controlsForm.Field name="locationCode">+ {(locationField) =>+ isLabsLocationCode(locationField.state.value) ? (+ <controlsForm.Field name="clickstream">+ {(field) => (+ <div className="flex items-center gap-2">+ <label className="label cursor-pointer justify-start gap-2 p-0">+ <input+ type="checkbox"+ className="toggle toggle-sm toggle-primary"+ checked={field.state.value}+ onChange={(event) =>+ field.handleChange(event.target.checked)+ }+ />+ <span className="text-sm font-medium text-base-content/80">+ Clickstream-refined volumes+ </span>+ </label>+ <div+ className="tooltip tooltip-right"+ data-tip="Google reports one combined search volume for similar keywords (e.g. 'seo tool' and 'seo tools'). Turn this on to estimate each keyword's own volume. Costs 2x the credits."+ >+ <Info className="size-3.5 text-base-content/50" />+ </div></div>- </div>- )}- </controlsForm.Field>- ) : (- <div- className="flex items-start gap-2 rounded-lg border border-info/30 bg-info/10 px-3 py-2 text-sm text-base-content/80"- role="status"- >- <Info className="mt-0.5 size-4 shrink-0 text-info" />- <span>- Keyword data for this country comes from Google Ads — search- volume, CPC, and trends are available, but difficulty and- intent are not.- </span>- </div>- )- }- </controlsForm.Field>+ )}+ </controlsForm.Field>+ ) : (+ <div+ className="flex items-start gap-2 rounded-lg border border-info/30 bg-info/10 px-3 py-2 text-sm text-base-content/80"+ role="status"+ >+ <Info className="mt-0.5 size-4 shrink-0 text-info" />+ <span>+ Keyword data for this country comes from Google Ads — search+ volume, CPC, and trends are available, but difficulty and+ intent are not.+ </span>+ </div>+ )+ }+ </controlsForm.Field>+ </div></div></div>);diff --git a/src/client/features/keywords/state/keywordControllerActions.ts b/src/client/features/keywords/state/keywordControllerActions.tsindex 90319910..04aad54b 100644--- a/src/client/features/keywords/state/keywordControllerActions.ts+++ b/src/client/features/keywords/state/keywordControllerActions.ts@@ -11,10 +11,7 @@ import type {ResultLimit,} from "@/client/features/keywords/keywordResearchTypes";import type { KeywordResearchControllerInput } from "./useKeywordResearchController";-import {- ungroupRows,- type KeywordResearchDisplayRow,-} from "@/client/features/keywords/groupSharedVolumeRows";+import type { KeywordResearchDisplayRow } from "@/client/features/keywords/groupSharedVolumeRows";export const KEYWORD_RESEARCH_HEADERS = ["Keyword",@@ -69,6 +66,7 @@ export function buildKeywordSearchKey(params: {resultLimit: ResultLimit;mode: KeywordMode;clickstream: boolean;+ groupKeywords: boolean;}) {return [parseKeywordInput(params.keyword).join(""),@@ -76,6 +74,7 @@ export function buildKeywordSearchKey(params: {params.resultLimit,params.mode,params.clickstream ? "cs" : "",+ params.groupKeywords ? "grouped" : "",].join("|");}@@ -149,7 +148,7 @@ export function useSaveAndExportActions(params: SaveExportActionParams) {};const sheetsExportRows: CsvValue[][] = useMemo(- () => ungroupRows(filteredRows).map(keywordResearchExportRow),+ () => filteredRows.map(keywordResearchExportRow),[filteredRows],);diff --git a/src/client/features/keywords/state/useKeywordResearchController.ts b/src/client/features/keywords/state/useKeywordResearchController.tsindex a272503e..a533c0e4 100644--- a/src/client/features/keywords/state/useKeywordResearchController.ts+++ b/src/client/features/keywords/state/useKeywordResearchController.ts@@ -4,6 +4,7 @@ import {type KeywordControlsValues,} from "@/client/features/keywords/hooks/useKeywordControlsForm";import { useKeywordFiltering } from "@/client/features/keywords/hooks/useKeywordFiltering";+import { usePreferredKeywordGrouping } from "@/client/features/keywords/hooks/usePreferredKeywordGrouping";import { useLocalKeywordFilters } from "@/client/features/keywords/hooks/useLocalKeywordFilters";import { useKeywordResearchData } from "@/client/features/keywords/hooks/useKeywordResearchData";import { useKeywordSelection } from "@/client/features/keywords/hooks/useKeywordSelection";@@ -52,6 +53,9 @@ export function useKeywordResearchController() {const { displayedLocationCode, locationCode, setPreferredLocationCode } =input;+ const { groupKeywords, setGroupKeywords } = usePreferredKeywordGrouping(+ input.projectId,+ );const {filtersForm,values: filterValues,@@ -111,6 +115,7 @@ export function useKeywordResearchController(resultLimit: input.resultLimit,mode: input.keywordMode,clickstream: input.clickstream,+ groupKeywords,},addSearch,);@@ -124,6 +129,7 @@ export function useKeywordResearchController(resultLimit: input.resultLimit,mode: input.keywordMode,clickstream: input.clickstream,+ groupKeywords,}): null;@@ -149,7 +155,7 @@ export function useKeywordResearchController(},);- // The URL is the source of truth for paid keyword research queries. This+ // The URL and saved grouping preference define keyword research queries. This// effect only resets UI state around a new query key; TanStack Query owns the// actual fetch, cache, dedupe, and error lifecycle.useEffect(() => {@@ -177,6 +183,7 @@ export function useKeywordResearchController(]);const { filteredRows, activeFilterCount } = useKeywordFiltering({+ groupKeywords,rows,searchedKeyword,filters: filterValues,@@ -236,6 +243,8 @@ export function useKeywordResearchController(};return {+ groupKeywords,+ setGroupKeywords,activeFilterCount,activeSerpKeyword,confirmSave,diff --git a/src/client/features/search-tabs/SearchTabStrip.tsx b/src/client/features/search-tabs/SearchTabStrip.tsxindex fddd5736..d96f3b34 100644--- a/src/client/features/search-tabs/SearchTabStrip.tsx+++ b/src/client/features/search-tabs/SearchTabStrip.tsx@@ -11,6 +11,7 @@ import {} from "@/client/features/keywords/hooks/useKeywordResearchData";import { getBacklinksOverview } from "@/serverFunctions/backlinks";import { getDomainOverview } from "@/serverFunctions/domain";+import { loadPreferredGrouping } from "@/client/features/keywords/hooks/usePreferredKeywordGrouping";export type { SearchTab } from "./types";type Props = {@@ -217,6 +218,7 @@ function getSearchTabQueryConfig(resultLimit: input.resultLimit,mode: input.mode,clickstream: input.clickstream,+ groupKeywords: loadPreferredGrouping(projectId),});return {diff --git a/src/server/features/keywords/services/research/research-data.ts b/src/server/features/keywords/services/research/research-data.tsindex c7508a71..eade4b2c 100644--- a/src/server/features/keywords/services/research/research-data.ts+++ b/src/server/features/keywords/services/research/research-data.ts@@ -19,6 +19,7 @@ type FetchResearchRowsParams = {resultLimit: number;source: KeywordSource;includeClickstreamData?: boolean;+ ignoreSynonyms?: boolean;// Attribute the DataForSEO spend to a specific feature (e.g. "agent");// defaults to the path-derived feature when omitted.creditFeature?: CreditFeature;@@ -126,6 +127,7 @@ async function fetchRelatedRows(limit: params.resultLimit,depth: 3,includeClickstreamData: params.includeClickstreamData,+ ignoreSynonyms: params.ignoreSynonyms,creditFeature: params.creditFeature,});@@ -156,6 +158,7 @@ export async function fetchResearchRowsBySource(languageCode: params.languageCode,limit: params.resultLimit,includeClickstreamData: params.includeClickstreamData,+ ignoreSynonyms: params.ignoreSynonyms,creditFeature: params.creditFeature,}),);@@ -168,6 +171,7 @@ export async function fetchResearchRowsBySource(languageCode: params.languageCode,limit: params.resultLimit,includeClickstreamData: params.includeClickstreamData,+ ignoreSynonyms: params.ignoreSynonyms,creditFeature: params.creditFeature,}),);diff --git a/src/server/features/keywords/services/research/research.test.ts b/src/server/features/keywords/services/research/research.test.tsindex 3cf56349..1a14e368 100644--- a/src/server/features/keywords/services/research/research.test.ts+++ b/src/server/features/keywords/services/research/research.test.ts@@ -60,8 +60,12 @@ it("keeps shared-volume keywords independently filterable through research and c"adult day care","care home",].map((keyword) => ({ ...seed, keyword, searchVolume: 500 }));- mocks.fetchRows.mockImplementation(async ({ source }) =>- source === "suggestions" ? [seed] : [opportunity, ...siblings],+ mocks.fetchRows.mockImplementation(async ({ source, ignoreSynonyms }) =>+ source === "suggestions"+ ? [seed]+ : ignoreSynonyms+ ? siblings+ : [opportunity, ...siblings],);const input = {projectId: "project_1",@@ -71,6 +75,7 @@ it("keeps shared-volume keywords independently filterable through research and cresultLimit: 150 as const,mode: "auto" as const,clickstream: false,+ groupKeywords: true,};const customer = {organizationId: "org_1",@@ -113,4 +118,19 @@ it("keeps shared-volume keywords independently filterable through research and csortDir: "asc",});expect(filtered).toEqual([opportunity]);+ for (const params of mocks.fetchRows.mock.calls.slice(0, 2)) {+ expect(params[0]).toMatchObject({ ignoreSynonyms: false });+ }+ const coreOnly = await research({ ...input, groupKeywords: false }, customer);+ // The thin core-only set also exercises the related-keywords fallback.+ expect(mocks.fetchRows).toHaveBeenCalledTimes(5);+ for (const params of mocks.fetchRows.mock.calls.slice(2)) {+ expect(params[0]).toMatchObject({ ignoreSynonyms: true });+ }+ expect(coreOnly.rows).not.toContainEqual(opportunity);+ expect(await research({ ...input, groupKeywords: false }, customer)).toEqual(+ coreOnly,+ );+ expect(await research(input, customer)).toEqual(fresh);+ expect(mocks.fetchRows).toHaveBeenCalledTimes(5);});diff --git a/src/server/features/keywords/services/research/research.ts b/src/server/features/keywords/services/research/research.tsindex 91a3ae40..4663126e 100644--- a/src/server/features/keywords/services/research/research.ts+++ b/src/server/features/keywords/services/research/research.ts@@ -84,6 +84,7 @@ async function fetchRowsFromSource(languageCode: input.languageCode,resultLimit: opts.resultLimit ?? input.resultLimit,includeClickstreamData: input.clickstream,+ ignoreSynonyms: !input.groupKeywords,creditFeature: opts.creditFeature,},billingCustomer,@@ -218,6 +219,7 @@ async function buildResearchCacheKey(mode,depth: 3,clickstream: input.clickstream,+ groupKeywords: input.groupKeywords,});}@@ -260,12 +262,12 @@ export async function research(const seedKeyword = uniqueKeywords[0];const provider = getKeywordDataProvider(input.locationCode);- // Labs source modes and clickstream refinement don't exist for- // Google-Ads-served countries; collapse both so equivalent requests share+ // Labs source modes, clickstream, and synonym filtering don't exist for+ // Google-Ads-served countries; normalize them so equivalent requests share// one cache entry.const effectiveInput: ResolvedResearchKeywordsInput =provider === "google_ads"- ? { ...input, mode: "auto", clickstream: false }+ ? { ...input, mode: "auto", clickstream: false, groupKeywords: false }: input;const mode = effectiveInput.mode ?? "auto";const cacheKey = await buildResearchCacheKey(diff --git a/src/server/lib/dataforseo/labs.test.ts b/src/server/lib/dataforseo/labs.test.tsnew file mode 100644index 00000000..5895acd1--- /dev/null+++ b/src/server/lib/dataforseo/labs.test.ts@@ -0,0 +1,52 @@+import { afterEach, expect, it, vi } from "vitest";+import {+ fetchRelatedKeywords,+ fetchKeywordSuggestions,+ fetchKeywordIdeas,+} from "./labs";++vi.mock("@/server/lib/runtime-env", () => ({+ getRequiredEnvValue: vi.fn(async () => "test-api-key"),+}));++afterEach(() => vi.unstubAllGlobals());++it("sends synonym filtering for every Labs research source and preserves omitted defaults", async () => {+ const fetchMock = vi.fn<typeof fetch>().mockImplementation(async (url) =>+ Response.json({+ status_code: 20000,+ tasks: [+ {+ status_code: 20000,+ path: new URL(url instanceof Request ? url.url : url).pathname+ .split("/")+ .filter(Boolean),+ cost: 0,+ result: [{ items: [] }],+ },+ ],+ }),+ );+ vi.stubGlobal("fetch", fetchMock);+ for (const fetchKeywords of [+ fetchRelatedKeywords,+ fetchKeywordSuggestions,+ fetchKeywordIdeas,+ ]) {+ for (const ignoreSynonyms of [true, false, undefined]) {+ await fetchKeywords({+ keyword: "caregiving",+ locationCode: 2840,+ languageCode: "en",+ limit: 150,+ ignoreSynonyms,+ });+ const body = fetchMock.mock.lastCall?.[1]?.body;+ if (typeof body !== "string")+ throw new Error("Expected JSON request body");+ expect(JSON.parse(body)).toEqual([+ expect.objectContaining({ ignore_synonyms: ignoreSynonyms ?? false }),+ ]);+ }+ }+});diff --git a/src/server/lib/dataforseo/labs.ts b/src/server/lib/dataforseo/labs.tsindex c3c5512b..4b555b4f 100644--- a/src/server/lib/dataforseo/labs.ts+++ b/src/server/lib/dataforseo/labs.ts@@ -151,6 +151,7 @@ export async function fetchRelatedKeywords(input: {limit: number;depth?: number;includeClickstreamData?: boolean;+ ignoreSynonyms?: boolean;}): Promise<DataforseoApiResponse<RelatedKeywordItem[]>> {const response = await dataforseoPost<DataforseoItemsTask<RelatedKeywordItem>@@ -161,6 +162,7 @@ export async function fetchRelatedKeywords(input: {language_code: input.languageCode,limit: input.limit,depth: input.depth ?? 3,+ ignore_synonyms: input.ignoreSynonyms ?? false,// Clickstream-refined volumes DOUBLE the request cost, so they are// opt-in — see specs/0004-keyword-data-source-routing.md.include_clickstream_data: input.includeClickstreamData ?? false,@@ -180,6 +182,7 @@ export async function fetchKeywordSuggestions(input: {languageCode: string;limit: number;includeClickstreamData?: boolean;+ ignoreSynonyms?: boolean;}): Promise<DataforseoApiResponse<LabsKeywordDataItem[]>> {const response = await dataforseoPost<DataforseoItemsTask<LabsKeywordDataItem>@@ -192,7 +195,7 @@ export async function fetchKeywordSuggestions(input: {include_clickstream_data: input.includeClickstreamData ?? false,include_serp_info: false,include_seed_keyword: true,- ignore_synonyms: false,+ ignore_synonyms: input.ignoreSynonyms ?? false,exact_match: false,},]);@@ -209,6 +212,7 @@ export async function fetchKeywordIdeas(input: {languageCode: string;limit: number;includeClickstreamData?: boolean;+ ignoreSynonyms?: boolean;}): Promise<DataforseoApiResponse<LabsKeywordDataItem[]>> {const response = await dataforseoPost<DataforseoItemsTask<LabsKeywordDataItem>@@ -220,7 +224,7 @@ export async function fetchKeywordIdeas(input: {limit: input.limit,include_clickstream_data: input.includeClickstreamData ?? false,include_serp_info: false,- ignore_synonyms: false,+ ignore_synonyms: input.ignoreSynonyms ?? false,closely_variants: false,},]);diff --git a/src/server/mcp/tools/research-keywords.ts b/src/server/mcp/tools/research-keywords.tsindex 757e4940..57f24e3b 100644--- a/src/server/mcp/tools/research-keywords.ts+++ b/src/server/mcp/tools/research-keywords.ts@@ -44,6 +44,12 @@ const inputSchema = {.describe("Refine search volumes with clickstream data, which disaggregates Google Ads' grouped close-variant volumes (plurals/misspellings). DOUBLES the credit cost of each seed. Default false (standard Google-Ads-derived volumes). No effect for countries served from Google Ads data.",),+ groupKeywords: z+ .boolean()+ .optional()+ .describe(+ "Include similar keyword variants that can share volume, CPC, and competition. Default false returns only core keywords (DataForSEO ignore_synonyms=true). True includes variants (ignore_synonyms=false). This filters keywords, not metric estimates. Do not sum shared volumes. No effect for countries served from Google Ads data.",+ ),} as const;type Args = z.infer<z.ZodObject<typeof inputSchema>>;@@ -138,6 +144,7 @@ export const researchKeywordsTool = {resultLimit: args.resultLimit ?? 150,mode: "auto",clickstream: args.includeClickstreamData ?? false,+ groupKeywords: args.groupKeywords ?? false,},context.billing,);diff --git a/src/types/schemas/keywords.ts b/src/types/schemas/keywords.tsindex b1ccfea6..71a4cde0 100644--- a/src/types/schemas/keywords.ts+++ b/src/types/schemas/keywords.ts@@ -29,6 +29,7 @@ export const researchKeywordsSchema = z.object({.default("auto"),// Clickstream-refined volumes double the DataForSEO request cost; opt-in.clickstream: z.boolean().optional().default(false),+ groupKeywords: z.boolean().optional().default(false),});export const savedKeywordMetricSchema = z.object({