From ae7712238eb9a8e6e12b4039a9fdb358109cbb68 Mon Sep 17 00:00:00 2001
From: Ben Senescu <44480372+bensenescu@users.noreply.github.com>
Date: Mon, 30 Mar 2026 13:38:08 -0400
Subject: [PATCH] refactor: use TanStack Form everywhere (#49)

* refactor: move lighthouse audits to dataforseo (#43)

* refactor: move lighthouse audits to dataforseo

* chore: remove obsolete audit settings modal

* refactor: rename psi flows to lighthouse

* save

* refactor: simplify audit lighthouse storage flow

* fix: separate lighthouse metrics from actionable audits

* refactor: remove redundant audit project inputs

* feat: redesign lighthouse issues screen with score gauges and table layout

Replace flat score cards with circular SVG gauges, condense metrics into
a compact grid, and switch issue list from cards to an expandable table
with fixed column widths.


* test: harden lighthouse regression coverage

* fix: restore project-scoped audit inputs

* refactor: simplify lighthouse payload handling

* refactor: inline lighthouse server handlers

* refactor: share audit workflow types

* refactor: simplify lighthouse payload flows

* save

* refactor: drop project pagespeed api key

* fix: restore lighthouse issues loading with resilient project context

* fix: restore audit issues back navigation

* refactor: simplify project context and lighthouse error handling

* fix: tolerate DataForSEO lighthouse payload drift

* refactor: route audit lighthouse through dataforseo client

---------


* refactor: unify app forms with TanStack Form

Replace bespoke field and submit error state so validation, async submit handling, and router-synced inputs behave consistently across the app.

* fix: remove dead code from ci check

* fix: delay required form errors until input interaction

* fix: preserve detailed DataForSEO error messages

* fix: sanitize internal errors and delay domain validation

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../features/audit/launch/LaunchFormCard.tsx  | 157 +++---
 .../features/audit/launch/LaunchView.tsx      |   5 -
 src/client/features/audit/launch/types.ts     |  30 +-
 .../audit/launch/useLaunchController.ts       | 162 +++---
 src/client/features/auth/AuthPage.tsx         |  20 +-
 .../backlinks/BacklinksSearchCard.tsx         | 468 +++++++++---------
 .../features/domain/DomainOverviewPage.tsx    |   5 -
 .../domain/components/DomainSearchCard.tsx    | 201 +++-----
 .../domainOverviewControllerInternals.ts      |  94 ++--
 .../domain/useDomainOverviewController.ts     | 172 +++++--
 .../keywords/hooks/useKeywordControlsForm.ts  |  65 ++-
 .../page/KeywordResearchSearchBar.tsx         |  53 +-
 .../state/keywordControllerActions.ts         | 142 +-----
 .../state/keywordControllerInternals.ts       |  68 +++
 .../state/useKeywordResearchController.ts     | 200 ++++----
 src/client/lib/error-messages.test.ts         |  18 +
 src/client/lib/error-messages.ts              |   1 +
 src/client/lib/forms.ts                       |  81 +++
 src/routes/_auth.sign-in.tsx                  |   2 +-
 src/routes/_auth.sign-up.tsx                  |   6 +-
 .../features/domain/services/DomainService.ts |   7 +-
 src/server/lib/dataforseo.ts                  | 111 +++--
 src/server/lib/domainUtils.ts                 |  44 ++
 src/server/lib/errors.test.ts                 |  21 +
 src/server/lib/errors.ts                      |   3 +-
 25 files changed, 1131 insertions(+), 1005 deletions(-)
 create mode 100644 src/client/features/keywords/state/keywordControllerInternals.ts
 create mode 100644 src/client/lib/error-messages.test.ts
 create mode 100644 src/client/lib/forms.ts
 create mode 100644 src/server/lib/domainUtils.ts
 create mode 100644 src/server/lib/errors.test.ts

diff --git a/src/client/features/audit/launch/LaunchFormCard.tsx b/src/client/features/audit/launch/LaunchFormCard.tsx
index 3ac3a65..2e0cea1 100644
--- a/src/client/features/audit/launch/LaunchFormCard.tsx
+++ b/src/client/features/audit/launch/LaunchFormCard.tsx
@@ -1,29 +1,17 @@
-import type { FormEvent } from "react";
 import { Loader2 } from "lucide-react";
 import {
   MAX_PAGES_LIMIT,
   MIN_PAGES,
-  type LaunchFormApi,
-  type LaunchState,
 } from "@/client/features/audit/launch/types";
+import type { useLaunchController } from "@/client/features/audit/launch/useLaunchController";
+import { getFieldError, getFormError } from "@/client/lib/forms";
 
-export function LaunchFormCard({
-  launchForm,
-  state,
-  setState,
-  isPending,
-  onSubmit,
-  onRunLighthouseToggle,
-  commitMaxPagesInput,
-}: {
-  launchForm: LaunchFormApi;
-  state: LaunchState;
-  setState: React.Dispatch<React.SetStateAction<LaunchState>>;
-  isPending: boolean;
-  onSubmit: (event: FormEvent) => void;
-  onRunLighthouseToggle: (checked: boolean) => void;
+type Props = {
+  launchForm: ReturnType<typeof useLaunchController>["launchForm"];
   commitMaxPagesInput: () => number;
-}) {
+};
+
+export function LaunchFormCard({ commitMaxPagesInput, launchForm }: Props) {
   return (
     <div className="card bg-base-100 border border-base-300">
       <div className="card-body gap-4">
@@ -31,65 +19,68 @@ export function LaunchFormCard({
 
         <form
           className="grid grid-cols-1 gap-3 lg:grid-cols-12 lg:items-center"
-          onSubmit={onSubmit}
+          onSubmit={(event) => {
+            event.preventDefault();
+            void launchForm.handleSubmit();
+          }}
         >
-          <label
-            className={`input input-bordered w-full lg:col-span-9 ${state.urlError ? "input-error" : ""}`}
-          >
-            <launchForm.Field name="url">
-              {(field) => (
-                <input
-                  placeholder="https://example.com"
-                  value={field.state.value}
-                  onChange={(event) => {
-                    field.handleChange(event.target.value);
-                    if (state.urlError)
-                      setState((prev) => ({ ...prev, urlError: null }));
-                  }}
-                />
-              )}
-            </launchForm.Field>
-          </label>
+          <launchForm.Field name="url">
+            {(field) => {
+              const urlError = getFieldError(field.state.meta.errors);
 
-          <button
-            type="submit"
-            className="btn btn-primary btn-sm w-full lg:col-span-3"
-            disabled={isPending}
-          >
-            {isPending ? (
-              <>
-                <Loader2 className="size-4 animate-spin" /> Starting...
-              </>
-            ) : (
-              "Start Audit"
+              return (
+                <label
+                  className={`input input-bordered w-full lg:col-span-9 ${urlError ? "input-error" : ""}`}
+                >
+                  <input
+                    placeholder="https://example.com"
+                    value={field.state.value}
+                    onChange={(event) => {
+                      field.handleChange(event.target.value);
+                      if (launchForm.state.errorMap.onSubmit) {
+                        launchForm.setErrorMap({ onSubmit: undefined });
+                      }
+                    }}
+                  />
+                </label>
+              );
+            }}
+          </launchForm.Field>
+
+          <launchForm.Subscribe selector={(state) => state.isSubmitting}>
+            {(isSubmitting) => (
+              <button
+                type="submit"
+                className="btn btn-primary btn-sm w-full lg:col-span-3"
+                disabled={isSubmitting}
+              >
+                {isSubmitting ? (
+                  <>
+                    <Loader2 className="size-4 animate-spin" /> Starting...
+                  </>
+                ) : (
+                  "Start Audit"
+                )}
+              </button>
             )}
-          </button>
+          </launchForm.Subscribe>
 
           <div className="grid w-full grid-cols-1 gap-4 md:grid-cols-2 lg:col-span-12 lg:items-start">
             <LaunchOptions
               launchForm={launchForm}
               commitMaxPagesInput={commitMaxPagesInput}
             />
-            <LighthouseOptions
-              launchForm={launchForm}
-              onRunLighthouseToggle={onRunLighthouseToggle}
-            />
+            <LighthouseOptions launchForm={launchForm} />
           </div>
         </form>
 
-        <LaunchErrors state={state} />
+        <LaunchErrors launchForm={launchForm} />
       </div>
     </div>
   );
 }
 
-function LaunchOptions({
-  launchForm,
-  commitMaxPagesInput,
-}: {
-  launchForm: LaunchFormApi;
-  commitMaxPagesInput: () => number;
-}) {
+function LaunchOptions({ launchForm, commitMaxPagesInput }: Props) {
   return (
     <div className="rounded-lg border border-base-300 bg-base-200/20 p-3 space-y-2">
       <label className="text-xs font-medium uppercase tracking-wide text-base-content/60">
@@ -109,6 +100,9 @@ function LaunchOptions({
                 const next = event.target.value;
                 if (!/^\d*$/.test(next)) return;
                 field.handleChange(next);
+                if (launchForm.state.errorMap.onSubmit) {
+                  launchForm.setErrorMap({ onSubmit: undefined });
+                }
               }}
               onBlur={commitMaxPagesInput}
             />
@@ -122,13 +116,7 @@ function LaunchOptions({
   );
 }
 
-function LighthouseOptions({
-  launchForm,
-  onRunLighthouseToggle,
-}: {
-  launchForm: LaunchFormApi;
-  onRunLighthouseToggle: (checked: boolean) => void;
-}) {
+function LighthouseOptions({ launchForm }: Pick<Props, "launchForm">) {
   return (
     <div className="rounded-lg border border-base-300 bg-base-200/20 p-3 space-y-2">
       <label className="label cursor-pointer justify-start gap-2 p-0">
@@ -138,7 +126,7 @@ function LighthouseOptions({
               type="checkbox"
               className="toggle toggle-sm toggle-primary"
               checked={Boolean(field.state.value)}
-              onChange={(event) => onRunLighthouseToggle(event.target.checked)}
+              onChange={(event) => field.handleChange(event.target.checked)}
             />
           )}
         </launchForm.Field>
@@ -184,17 +172,30 @@ function LighthouseOptions({
   );
 }
 
-function LaunchErrors({ state }: { state: LaunchState }) {
+function LaunchErrors({ launchForm }: Pick<Props, "launchForm">) {
   return (
     <div className="space-y-2">
-      {state.urlError ? (
-        <p className="text-sm text-error">{state.urlError}</p>
-      ) : null}
-      {state.startError ? (
-        <div className="alert alert-error py-2">
-          <span className="text-sm">{state.startError}</span>
-        </div>
-      ) : null}
+      <launchForm.Field name="url">
+        {(field) => {
+          const urlError = getFieldError(field.state.meta.errors);
+
+          return urlError ? (
+            <p className="text-sm text-error">{urlError}</p>
+          ) : null;
+        }}
+      </launchForm.Field>
+
+      <launchForm.Subscribe selector={(state) => state.errorMap.onSubmit}>
+        {(submitError) => {
+          const errorMessage = getFormError(submitError);
+
+          return errorMessage ? (
+            <div className="alert alert-error py-2">
+              <span className="text-sm">{errorMessage}</span>
+            </div>
+          ) : null;
+        }}
+      </launchForm.Subscribe>
     </div>
   );
 }
diff --git a/src/client/features/audit/launch/LaunchView.tsx b/src/client/features/audit/launch/LaunchView.tsx
index 55c7241..0b74cfb 100644
--- a/src/client/features/audit/launch/LaunchView.tsx
+++ b/src/client/features/audit/launch/LaunchView.tsx
@@ -18,11 +18,6 @@ export function LaunchView({
 
         <LaunchFormCard
           launchForm={controller.launchForm}
-          state={controller.state}
-          setState={controller.setState}
-          isPending={controller.startMutation.isPending}
-          onSubmit={controller.handleSubmit}
-          onRunLighthouseToggle={controller.onRunLighthouseToggle}
           commitMaxPagesInput={controller.commitMaxPagesInput}
         />
 
diff --git a/src/client/features/audit/launch/types.ts b/src/client/features/audit/launch/types.ts
index 110db51..ad45ca5 100644
--- a/src/client/features/audit/launch/types.ts
+++ b/src/client/features/audit/launch/types.ts
@@ -1,22 +1,16 @@
-import { useForm } from "@tanstack/react-form";
-
-export type LaunchState = {
-  urlError: string | null;
-  startError: string | null;
-};
-
 export const MIN_PAGES = 10;
 export const MAX_PAGES_LIMIT = 10_000;
 
-export function useLaunchForm() {
-  return useForm({
-    defaultValues: {
-      url: "",
-      maxPagesInput: "50",
-      runLighthouse: false,
-      lighthouseMode: "auto" as "auto" | "all",
-    },
-  });
-}
+export type LaunchFormValues = {
+  url: string;
+  maxPagesInput: string;
+  runLighthouse: boolean;
+  lighthouseMode: "auto" | "all";
+};
 
-export type LaunchFormApi = ReturnType<typeof useLaunchForm>;
+export const DEFAULT_LAUNCH_FORM_VALUES: LaunchFormValues = {
+  url: "",
+  maxPagesInput: "50",
+  runLighthouse: false,
+  lighthouseMode: "auto",
+};
diff --git a/src/client/features/audit/launch/useLaunchController.ts b/src/client/features/audit/launch/useLaunchController.ts
index 37ef45a..724778b 100644
--- a/src/client/features/audit/launch/useLaunchController.ts
+++ b/src/client/features/audit/launch/useLaunchController.ts
@@ -1,4 +1,4 @@
-import { useState, type FormEvent } from "react";
+import { useForm } from "@tanstack/react-form";
 import { useMutation, useQuery } from "@tanstack/react-query";
 import { toast } from "sonner";
 import {
@@ -7,13 +7,36 @@ import {
   startAudit,
 } from "@/serverFunctions/audit";
 import {
+  DEFAULT_LAUNCH_FORM_VALUES,
   MAX_PAGES_LIMIT,
   MIN_PAGES,
-  useLaunchForm,
-  type LaunchState,
+  type LaunchFormValues,
 } from "@/client/features/audit/launch/types";
+import {
+  createFormValidationErrors,
+  shouldValidateFieldOnChange,
+} from "@/client/lib/forms";
 import { getStandardErrorMessage } from "@/client/lib/error-messages";
 
+function getLaunchValidationErrors(
+  value: LaunchFormValues,
+  shouldValidateUntouchedField: boolean,
+) {
+  if (value.url.trim()) {
+    return null;
+  }
+
+  if (!shouldValidateUntouchedField) {
+    return null;
+  }
+
+  return createFormValidationErrors({
+    fields: {
+      url: "Please enter a URL.",
+    },
+  });
+}
+
 export function useLaunchController({
   projectId,
   onAuditStarted,
@@ -21,12 +44,6 @@ export function useLaunchController({
   projectId: string;
   onAuditStarted: (auditId: string) => void;
 }) {
-  const launchForm = useLaunchForm();
-  const [state, setState] = useState<LaunchState>({
-    urlError: null,
-    startError: null,
-  });
-
   const historyQuery = useQuery({
     queryKey: ["audit-history", projectId],
     queryFn: () => getAuditHistory({ data: { projectId } }),
@@ -36,74 +53,54 @@ export function useLaunchController({
     historyRefetch: historyQuery.refetch,
   });
 
-  const applyMaxPages = (value: number) => {
-    const safeValue = Number.isFinite(value)
-      ? Math.max(MIN_PAGES, Math.min(MAX_PAGES_LIMIT, Math.round(value)))
-      : MIN_PAGES;
-    launchForm.setFieldValue("maxPagesInput", String(safeValue));
-    return safeValue;
-  };
+  const launchForm = useForm({
+    defaultValues: DEFAULT_LAUNCH_FORM_VALUES,
+    validators: {
+      onChange: ({ formApi, value }) =>
+        getLaunchValidationErrors(
+          value,
+          shouldValidateFieldOnChange(formApi, "url"),
+        ),
+      onSubmit: ({ value }) => getLaunchValidationErrors(value, true),
+    },
+    onSubmit: async ({ formApi, value }) => {
+      const effectiveMaxPages = commitMaxPagesInput(launchForm);
+      formApi.setErrorMap({ onSubmit: undefined });
 
-  const commitMaxPagesInput = () => {
-    const maxPagesInput = launchForm.state.values.maxPagesInput;
-    if (!maxPagesInput) return applyMaxPages(MIN_PAGES);
-    return applyMaxPages(Number.parseInt(maxPagesInput, 10));
-  };
+      if (effectiveMaxPages > 500) {
+        const confirmed = window.confirm(
+          `You are about to crawl ${effectiveMaxPages.toLocaleString()} pages. This is okay, but it may take a while. Continue?`,
+        );
+        if (!confirmed) {
+          return;
+        }
+      }
 
-  const handleStart = () => {
-    const launchValues = launchForm.state.values;
-    const effectiveMaxPages = commitMaxPagesInput();
-    setState((prev) => ({ ...prev, startError: null }));
-
-    if (!launchValues.url.trim()) {
-      return setState((prev) => ({ ...prev, urlError: "Please enter a URL." }));
-    }
-
-    if (effectiveMaxPages > 500) {
-      const confirmed = window.confirm(
-        `You are about to crawl ${effectiveMaxPages.toLocaleString()} pages. This is okay, but it may take a while. Continue?`,
-      );
-      if (!confirmed) return;
-    }
-
-    startMutation.mutate(
-      {
-        projectId,
-        startUrl: launchValues.url,
-        maxPages: effectiveMaxPages,
-        lighthouseStrategy: launchValues.runLighthouse
-          ? launchValues.lighthouseMode
-          : "none",
-      },
-      {
-        onSuccess: (result) => {
-          setState({ urlError: null, startError: null });
-          toast.success("Audit started!");
-          onAuditStarted(result.auditId);
-        },
-        onError: (error) => {
-          setState((prev) => ({
-            ...prev,
-            startError: getStandardErrorMessage(error, "Failed to start audit"),
-          }));
-        },
-      },
-    );
-  };
+      try {
+        const result = await startMutation.mutateAsync({
+          projectId,
+          startUrl: value.url,
+          maxPages: effectiveMaxPages,
+          lighthouseStrategy: value.runLighthouse
+            ? value.lighthouseMode
+            : "none",
+        });
+        toast.success("Audit started!");
+        onAuditStarted(result.auditId);
+      } catch (error) {
+        formApi.setErrorMap({
+          onSubmit: createFormValidationErrors({
+            form: getStandardErrorMessage(error, "Failed to start audit"),
+          }),
+        });
+      }
+    },
+  });
 
   return {
     launchForm,
-    state,
-    setState,
     historyQuery,
-    startMutation,
-    commitMaxPagesInput,
-    handleSubmit: (event: FormEvent) => {
-      event.preventDefault();
-      handleStart();
-    },
-    onRunLighthouseToggle: (checked: boolean) =>
-      handleRunLighthouseToggle(checked, launchForm),
+    commitMaxPagesInput: () => commitMaxPagesInput(launchForm),
     deleteAudit: (auditId: string) => deleteMutation.mutate(auditId),
   };
 }
@@ -136,9 +133,24 @@ function useLaunchMutations({
   return { startMutation, deleteMutation };
 }
 
-function handleRunLighthouseToggle(
-  checked: boolean,
-  launchForm: ReturnType<typeof useLaunchForm>,
+function applyMaxPages(
+  launchForm: {
+    setFieldValue: (field: "maxPagesInput", value: string) => void;
+  },
+  value: number,
 ) {
-  launchForm.setFieldValue("runLighthouse", checked);
+  const safeValue = Number.isFinite(value)
+    ? Math.max(MIN_PAGES, Math.min(MAX_PAGES_LIMIT, Math.round(value)))
+    : MIN_PAGES;
+  launchForm.setFieldValue("maxPagesInput", String(safeValue));
+  return safeValue;
+}
+
+function commitMaxPagesInput(launchForm: {
+  state: { values: { maxPagesInput: string } };
+  setFieldValue: (field: "maxPagesInput", value: string) => void;
+}) {
+  const maxPagesInput = launchForm.state.values.maxPagesInput;
+  if (!maxPagesInput) return applyMaxPages(launchForm, MIN_PAGES);
+  return applyMaxPages(launchForm, Number.parseInt(maxPagesInput, 10));
 }
diff --git a/src/client/features/auth/AuthPage.tsx b/src/client/features/auth/AuthPage.tsx
index e609627..7339eb1 100644
--- a/src/client/features/auth/AuthPage.tsx
+++ b/src/client/features/auth/AuthPage.tsx
@@ -2,6 +2,10 @@ import { z } from "zod";
 import { normalizeAuthRedirect } from "@/lib/auth-redirect";
 import { useSession } from "@/lib/auth-client";
 import { isHostedClientAuthMode } from "@/lib/auth-mode";
+import {
+  getFieldError as getSharedFieldError,
+  getFormError as getSharedFormError,
+} from "@/client/lib/forms";
 
 export const authRedirectSearchSchema = z.object({
   redirect: z.string().optional(),
@@ -19,20 +23,12 @@ export function useAuthPageState(redirect: string | undefined) {
   };
 }
 
-export function getFieldError(errors: unknown[]) {
-  const first = errors[0];
-  if (typeof first === "string") return first;
-  if (first && typeof first === "object" && "message" in first)
-    return String((first as { message: unknown }).message);
-  return null;
+export function getFieldError(errors: readonly unknown[]) {
+  return getSharedFieldError(errors);
 }
 
-export function getFormError(error: unknown): string | null {
-  if (!error) return null;
-  if (typeof error === "string") return error;
-  if (typeof error === "object" && "form" in error)
-    return String((error as { form: unknown }).form);
-  return null;
+export function getFormError(error: unknown) {
+  return getSharedFormError(error);
 }
 
 export function AuthPageCard({
diff --git a/src/client/features/backlinks/BacklinksSearchCard.tsx b/src/client/features/backlinks/BacklinksSearchCard.tsx
index ca696b2..8cc5a9e 100644
--- a/src/client/features/backlinks/BacklinksSearchCard.tsx
+++ b/src/client/features/backlinks/BacklinksSearchCard.tsx
@@ -1,5 +1,11 @@
+import { useEffect, useState } from "react";
+import { useForm } from "@tanstack/react-form";
 import { Search } from "lucide-react";
-import { useEffect, useState, type FormEvent } from "react";
+import {
+  createFormValidationErrors,
+  getFieldError,
+  shouldValidateFieldOnChange,
+} from "@/client/lib/forms";
 import type { BacklinksSearchState } from "./backlinksPageTypes";
 import { resolveBacklinksSearchScope } from "./backlinksSearchScope";
 
@@ -8,12 +14,23 @@ type SearchDraft = Pick<
   "target" | "scope" | "subdomains" | "indirect" | "excludeInternal" | "status"
 >;
 
-function toBacklinksStatus(value: string): SearchDraft["status"] {
-  if (value === "live" || value === "lost" || value === "all") {
-    return value;
+function getBacklinksValidationErrors(
+  value: SearchDraft,
+  shouldValidateUntouchedField: boolean,
+) {
+  if (value.target.trim()) {
+    return null;
   }
 
-  return "live";
+  if (!shouldValidateUntouchedField) {
+    return null;
+  }
+
+  return createFormValidationErrors({
+    fields: {
+      target: "Enter a domain or URL to analyze.",
+    },
+  });
 }
 
 export function BacklinksSearchCard({
@@ -27,90 +44,221 @@ export function BacklinksSearchCard({
   isFetching: boolean;
   onSubmit: (values: SearchDraft) => void;
 }) {
-  const [targetInput, setTargetInput] = useState(initialValues.target);
-  const [scope, setScope] = useState(initialValues.scope);
-  const [includeSubdomains, setIncludeSubdomains] = useState(
-    initialValues.subdomains,
-  );
-  const [includeIndirectLinks, setIncludeIndirectLinks] = useState(
-    initialValues.indirect,
-  );
-  const [excludeInternalBacklinks, setExcludeInternalBacklinks] = useState(
-    initialValues.excludeInternal,
-  );
-  const [status, setStatus] = useState(initialValues.status);
   const [showAdvanced, setShowAdvanced] = useState(false);
-  const [formError, setFormError] = useState<string | null>(null);
   const [userSelectedScope, setUserSelectedScope] = useState(false);
+  const form = useForm({
+    defaultValues: initialValues,
+    validators: {
+      onChange: ({ formApi, value }) =>
+        getBacklinksValidationErrors(
+          value,
+          shouldValidateFieldOnChange(formApi, "target"),
+        ),
+      onSubmit: ({ value }) => getBacklinksValidationErrors(value, true),
+    },
+    onSubmit: ({ value }) => {
+      const target = value.target.trim();
+      onSubmit({
+        ...value,
+        target,
+        scope: resolveBacklinksSearchScope({
+          target,
+          selectedScope: value.scope,
+          userSelectedScope,
+        }),
+      });
+    },
+  });
 
   useEffect(() => {
-    setTargetInput(initialValues.target);
-    setScope(initialValues.scope);
-    setIncludeSubdomains(initialValues.subdomains);
-    setIncludeIndirectLinks(initialValues.indirect);
-    setExcludeInternalBacklinks(initialValues.excludeInternal);
-    setStatus(initialValues.status);
-    setFormError(null);
+    form.reset(initialValues);
     setUserSelectedScope(false);
-  }, [initialValues]);
-
-  const handleSubmit = (event: FormEvent) => {
-    event.preventDefault();
-
-    const target = targetInput.trim();
-    if (!target) {
-      setFormError("Enter a domain or URL to analyze.");
-      return;
-    }
-
-    setFormError(null);
-    onSubmit({
-      target,
-      scope: resolveBacklinksSearchScope({
-        target,
-        selectedScope: scope,
-        userSelectedScope,
-      }),
-      subdomains: includeSubdomains,
-      indirect: includeIndirectLinks,
-      excludeInternal: excludeInternalBacklinks,
-      status,
-    });
-  };
+  }, [form, initialValues]);
 
   return (
     <div className="card bg-base-100 border border-base-300">
       <div className="card-body gap-4">
-        <form className="space-y-3" onSubmit={handleSubmit}>
-          <SearchControls
-            formError={formError}
-            isFetching={isFetching}
-            onScopeChange={setScope}
-            onStatusChange={(value) => setStatus(toBacklinksStatus(value))}
-            onTargetInputChange={setTargetInput}
-            setFormError={setFormError}
-            scope={scope}
-            status={status}
-            targetInput={targetInput}
-            userSelectedScope={userSelectedScope}
-            onUserSelectedScopeChange={setUserSelectedScope}
-          />
-          <SearchToggles
-            includeSubdomains={includeSubdomains}
-            onIncludeSubdomainsChange={setIncludeSubdomains}
-            showAdvanced={showAdvanced}
-            toggleAdvanced={() => setShowAdvanced((current) => !current)}
-          />
+        <form
+          className="space-y-3"
+          onSubmit={(event) => {
+            event.preventDefault();
+            void form.handleSubmit();
+          }}
+        >
+          <div className="space-y-3">
+            <div className="grid grid-cols-1 gap-3 lg:grid-cols-12">
+              <form.Field name="target">
+                {(field) => {
+                  const targetError = getFieldError(field.state.meta.errors);
+
+                  return (
+                    <label
+                      className={`input input-bordered lg:col-span-8 flex items-center gap-2 ${targetError ? "input-error" : ""}`}
+                    >
+                      <Search className="size-4 text-base-content/60" />
+                      <input
+                        placeholder="Enter a domain or URL"
+                        value={field.state.value}
+                        onChange={(event) => {
+                          const nextTarget = event.target.value;
+                          field.handleChange(nextTarget);
+                          if (!userSelectedScope) {
+                            form.setFieldValue(
+                              "scope",
+                              resolveBacklinksSearchScope({
+                                target: nextTarget,
+                                selectedScope: form.state.values.scope,
+                                userSelectedScope: false,
+                              }),
+                            );
+                          }
+                        }}
+                      />
+                    </label>
+                  );
+                }}
+              </form.Field>
+
+              <form.Field name="status">
+                {(field) => (
+                  <select
+                    className="select select-bordered lg:col-span-2"
+                    value={field.state.value}
+                    onChange={(event) =>
+                      field.handleChange(
+                        event.target.value === "lost"
+                          ? "lost"
+                          : event.target.value === "all"
+                            ? "all"
+                            : "live",
+                      )
+                    }
+                  >
+                    <option value="live">Live links</option>
+                    <option value="lost">Lost links</option>
+                    <option value="all">All links</option>
+                  </select>
+                )}
+              </form.Field>
+
+              <form.Subscribe selector={(state) => state.isSubmitting}>
+                {(isSubmitting) => (
+                  <button
+                    type="submit"
+                    className="btn btn-primary lg:col-span-2"
+                    disabled={isFetching || isSubmitting}
+                  >
+                    {isFetching || isSubmitting ? "Loading..." : "Search"}
+                  </button>
+                )}
+              </form.Subscribe>
+            </div>
+
+            <form.Field name="target">
+              {(field) => {
+                const targetError = getFieldError(field.state.meta.errors);
+
+                return targetError ? (
+                  <p className="text-sm text-error">{targetError}</p>
+                ) : null;
+              }}
+            </form.Field>
+
+            <div className="flex items-center gap-1">
+              <form.Field name="scope">
+                {(field) => (
+                  <>
+                    <button
+                      type="button"
+                      className={`btn btn-xs ${field.state.value === "domain" ? "btn-soft" : "btn-ghost"}`}
+                      onClick={() => {
+                        setUserSelectedScope(true);
+                        field.handleChange("domain");
+                      }}
+                    >
+                      Site-wide
+                    </button>
+                    <button
+                      type="button"
+                      className={`btn btn-xs ${field.state.value === "page" ? "btn-soft" : "btn-ghost"}`}
+                      onClick={() => {
+                        setUserSelectedScope(true);
+                        field.handleChange("page");
+                      }}
+                    >
+                      Exact page
+                    </button>
+                  </>
+                )}
+              </form.Field>
+            </div>
+          </div>
+
+          <div className="flex flex-wrap items-center gap-3">
+            <form.Field name="subdomains">
+              {(field) => (
+                <label className="label cursor-pointer gap-2 py-0">
+                  <input
+                    type="checkbox"
+                    className="checkbox checkbox-sm"
+                    checked={field.state.value}
+                    onChange={(event) =>
+                      field.handleChange(event.target.checked)
+                    }
+                  />
+                  <span className="label-text">Include subdomains</span>
+                </label>
+              )}
+            </form.Field>
+
+            <button
+              type="button"
+              className="btn btn-ghost btn-sm"
+              onClick={() => setShowAdvanced((current) => !current)}
+            >
+              {showAdvanced ? "Hide advanced" : "Show advanced"}
+            </button>
+          </div>
+
           {showAdvanced ? (
-            <AdvancedSearchOptions
-              excludeInternalBacklinks={excludeInternalBacklinks}
-              includeIndirectLinks={includeIndirectLinks}
-              onExcludeInternalChange={setExcludeInternalBacklinks}
-              onIncludeIndirectChange={setIncludeIndirectLinks}
-            />
+            <div className="grid grid-cols-1 gap-3 rounded-xl border border-base-300 bg-base-200/40 p-4 text-sm md:grid-cols-2">
+              <form.Field name="indirect">
+                {(field) => (
+                  <label className="label cursor-pointer justify-start gap-3 py-0">
+                    <input
+                      type="checkbox"
+                      className="checkbox checkbox-sm"
+                      checked={field.state.value}
+                      onChange={(event) =>
+                        field.handleChange(event.target.checked)
+                      }
+                    />
+                    <span className="label-text">Include indirect links</span>
+                  </label>
+                )}
+              </form.Field>
+
+              <form.Field name="excludeInternal">
+                {(field) => (
+                  <label className="label cursor-pointer justify-start gap-3 py-0">
+                    <input
+                      type="checkbox"
+                      className="checkbox checkbox-sm"
+                      checked={field.state.value}
+                      onChange={(event) =>
+                        field.handleChange(event.target.checked)
+                      }
+                    />
+                    <span className="label-text">
+                      Exclude internal backlinks
+                    </span>
+                  </label>
+                )}
+              </form.Field>
+            </div>
           ) : null}
         </form>
-        {formError ? <p className="text-sm text-error">{formError}</p> : null}
+
         {errorMessage ? (
           <div className="rounded-lg border border-error/30 bg-error/10 p-3 text-sm text-error">
             {errorMessage}
@@ -120,169 +268,3 @@ export function BacklinksSearchCard({
     </div>
   );
 }
-
-function SearchControls({
-  formError,
-  isFetching,
-  onScopeChange,
-  onStatusChange,
-  onTargetInputChange,
-  onUserSelectedScopeChange,
-  setFormError,
-  scope,
-  status,
-  targetInput,
-  userSelectedScope,
-}: {
-  formError: string | null;
-  isFetching: boolean;
-  onScopeChange: (value: BacklinksSearchState["scope"]) => void;
-  onStatusChange: (value: string) => void;
-  onTargetInputChange: (value: string) => void;
-  onUserSelectedScopeChange: (value: boolean) => void;
-  setFormError: (value: string | null) => void;
-  scope: BacklinksSearchState["scope"];
-  status: BacklinksSearchState["status"];
-  targetInput: string;
-  userSelectedScope: boolean;
-}) {
-  return (
-    <div className="space-y-3">
-      <div className="grid grid-cols-1 gap-3 lg:grid-cols-12">
-        <label
-          className={`input input-bordered lg:col-span-8 flex items-center gap-2 ${formError ? "input-error" : ""}`}
-        >
-          <Search className="size-4 text-base-content/60" />
-          <input
-            placeholder={
-              scope === "page"
-                ? "Enter a page URL or domain"
-                : "Enter a domain or URL"
-            }
-            value={targetInput}
-            onChange={(event) => {
-              const nextTarget = event.target.value;
-              onTargetInputChange(nextTarget);
-              if (!userSelectedScope) {
-                onScopeChange(
-                  resolveBacklinksSearchScope({
-                    target: nextTarget,
-                    selectedScope: scope,
-                    userSelectedScope: false,
-                  }),
-                );
-              }
-              if (formError) setFormError(null);
-            }}
-          />
-        </label>
-        <select
-          className="select select-bordered lg:col-span-2"
-          value={status}
-          onChange={(event) => onStatusChange(event.target.value)}
-        >
-          <option value="live">Live links</option>
-          <option value="lost">Lost links</option>
-          <option value="all">All links</option>
-        </select>
-        <button
-          type="submit"
-          className="btn btn-primary lg:col-span-2"
-          disabled={isFetching}
-        >
-          {isFetching ? "Loading..." : "Search"}
-        </button>
-      </div>
-      <div className="flex items-center gap-1">
-        <button
-          type="button"
-          className={`btn btn-xs ${scope === "domain" ? "btn-soft" : "btn-ghost"}`}
-          onClick={() => {
-            onUserSelectedScopeChange(true);
-            onScopeChange("domain");
-          }}
-        >
-          Site-wide
-        </button>
-        <button
-          type="button"
-          className={`btn btn-xs ${scope === "page" ? "btn-soft" : "btn-ghost"}`}
-          onClick={() => {
-            onUserSelectedScopeChange(true);
-            onScopeChange("page");
-          }}
-        >
-          Exact page
-        </button>
-      </div>
-    </div>
-  );
-}
-
-function SearchToggles({
-  includeSubdomains,
-  onIncludeSubdomainsChange,
-  showAdvanced,
-  toggleAdvanced,
-}: {
-  includeSubdomains: boolean;
-  onIncludeSubdomainsChange: (checked: boolean) => void;
-  showAdvanced: boolean;
-  toggleAdvanced: () => void;
-}) {
-  return (
-    <div className="flex flex-wrap items-center gap-3">
-      <label className="label cursor-pointer gap-2 py-0">
-        <input
-          type="checkbox"
-          className="checkbox checkbox-sm"
-          checked={includeSubdomains}
-          onChange={(event) => onIncludeSubdomainsChange(event.target.checked)}
-        />
-        <span className="label-text">Include subdomains</span>
-      </label>
-      <button
-        type="button"
-        className="btn btn-ghost btn-sm"
-        onClick={toggleAdvanced}
-      >
-        {showAdvanced ? "Hide advanced" : "Show advanced"}
-      </button>
-    </div>
-  );
-}
-
-function AdvancedSearchOptions({
-  excludeInternalBacklinks,
-  includeIndirectLinks,
-  onExcludeInternalChange,
-  onIncludeIndirectChange,
-}: {
-  excludeInternalBacklinks: boolean;
-  includeIndirectLinks: boolean;
-  onExcludeInternalChange: (checked: boolean) => void;
-  onIncludeIndirectChange: (checked: boolean) => void;
-}) {
-  return (
-    <div className="grid grid-cols-1 gap-3 rounded-xl border border-base-300 bg-base-200/40 p-4 text-sm md:grid-cols-2">
-      <label className="label cursor-pointer justify-start gap-3 py-0">
-        <input
-          type="checkbox"
-          className="checkbox checkbox-sm"
-          checked={includeIndirectLinks}
-          onChange={(event) => onIncludeIndirectChange(event.target.checked)}
-        />
-        <span className="label-text">Include indirect links</span>
-      </label>
-      <label className="label cursor-pointer justify-start gap-3 py-0">
-        <input
-          type="checkbox"
-          className="checkbox checkbox-sm"
-          checked={excludeInternalBacklinks}
-          onChange={(event) => onExcludeInternalChange(event.target.checked)}
-        />
-        <span className="label-text">Exclude internal backlinks</span>
-      </label>
-    </div>
-  );
-}
diff --git a/src/client/features/domain/DomainOverviewPage.tsx b/src/client/features/domain/DomainOverviewPage.tsx
index 99b8a1b..e27bd2d 100644
--- a/src/client/features/domain/DomainOverviewPage.tsx
+++ b/src/client/features/domain/DomainOverviewPage.tsx
@@ -57,16 +57,11 @@ export function DomainOverviewPage({
 
         <DomainSearchCard
           controlsForm={state.controlsForm}
-          domainError={state.domainError}
-          overviewError={state.overviewError}
           isLoading={state.isLoading}
           onSubmit={state.handleSearchSubmit}
           onSortChange={(sort) =>
             state.applySort(sort, getDefaultSortOrder(sort))
           }
-          onDomainInput={() => {
-            if (state.domainError) state.setDomainError(null);
-          }}
         />
 
         {state.isLoading ? (
diff --git a/src/client/features/domain/components/DomainSearchCard.tsx b/src/client/features/domain/components/DomainSearchCard.tsx
index 1a1c4e0..f816af7 100644
--- a/src/client/features/domain/components/DomainSearchCard.tsx
+++ b/src/client/features/domain/components/DomainSearchCard.tsx
@@ -1,81 +1,22 @@
-import type { ComponentType, FormEvent, ReactNode } from "react";
+import type { FormEvent } from "react";
 import { AlertCircle, Search } from "lucide-react";
+import { getFieldError, getFormError } from "@/client/lib/forms";
+import type { useDomainOverviewController } from "@/client/features/domain/useDomainOverviewController";
 import { toSortMode } from "@/client/features/domain/utils";
 import type { DomainSortMode } from "@/client/features/domain/types";
 
-type FieldHost = {
-  Field: ComponentType<{
-    name: "domain" | "sort" | "subdomains";
-    children: (field: unknown) => ReactNode;
-  }>;
-};
-
-type TextField = {
-  state: { value: string };
-  handleChange: (value: string) => void;
-};
-
-type SortField = {
-  state: { value: DomainSortMode };
-  handleChange: (value: DomainSortMode) => void;
-};
-
-type ToggleField = {
-  state: { value: boolean };
-  handleChange: (value: boolean) => void;
-};
-
-function isTextField(field: unknown): field is TextField {
-  if (!field || typeof field !== "object") return false;
-  const candidate = field as {
-    state?: { value?: unknown };
-    handleChange?: unknown;
-  };
-  return (
-    typeof candidate.handleChange === "function" &&
-    typeof candidate.state?.value === "string"
-  );
-}
-
-function isSortField(field: unknown): field is SortField {
-  if (!isTextField(field)) return false;
-  return (
-    field.state.value === "rank" ||
-    field.state.value === "traffic" ||
-    field.state.value === "volume"
-  );
-}
-
-function isToggleField(field: unknown): field is ToggleField {
-  if (!field || typeof field !== "object") return false;
-  const candidate = field as {
-    state?: { value?: unknown };
-    handleChange?: unknown;
-  };
-  return (
-    typeof candidate.handleChange === "function" &&
-    typeof candidate.state?.value === "boolean"
-  );
-}
-
 type Props = {
-  controlsForm: FieldHost;
-  domainError: string | null;
-  overviewError: string | null;
+  controlsForm: ReturnType<typeof useDomainOverviewController>["controlsForm"];
   isLoading: boolean;
   onSubmit: (event: FormEvent) => void;
   onSortChange: (sort: DomainSortMode) => void;
-  onDomainInput: () => void;
 };
 
 export function DomainSearchCard({
   controlsForm,
-  domainError,
-  overviewError,
   isLoading,
   onSubmit,
   onSortChange,
-  onDomainInput,
 }: Props) {
   return (
     <div className="card bg-base-100 border border-base-300">
@@ -84,88 +25,96 @@ export function DomainSearchCard({
           className="grid grid-cols-1 gap-3 lg:grid-cols-12"
           onSubmit={onSubmit}
         >
-          <label
-            className={`input input-bordered lg:col-span-8 flex items-center gap-2 ${domainError ? "input-error" : ""}`}
-          >
-            <Search className="size-4 text-base-content/60" />
-            <controlsForm.Field name="domain">
-              {(field) => {
-                if (!isTextField(field)) return null;
-                return (
+          <controlsForm.Field name="domain">
+            {(field) => {
+              const domainError = getFieldError(field.state.meta.errors);
+
+              return (
+                <label
+                  className={`input input-bordered lg:col-span-8 flex items-center gap-2 ${domainError ? "input-error" : ""}`}
+                >
+                  <Search className="size-4 text-base-content/60" />
                   <input
                     placeholder="Enter a domain (e.g. coolify.io or example.com/blog)"
                     value={field.state.value}
-                    onChange={(e) => {
-                      field.handleChange(e.target.value);
-                      onDomainInput();
-                    }}
+                    onChange={(event) => field.handleChange(event.target.value)}
                     aria-invalid={domainError ? true : undefined}
                     aria-describedby={
                       domainError ? "domain-input-error" : undefined
                     }
                   />
-                );
-              }}
-            </controlsForm.Field>
-          </label>
-
-          <controlsForm.Field name="sort">
-            {(field) => {
-              if (!isSortField(field)) return null;
-              return (
-                <select
-                  className="select select-bordered lg:col-span-2"
-                  value={field.state.value}
-                  onChange={(e) => {
-                    const next = toSortMode(e.target.value) ?? "rank";
-                    field.handleChange(next);
-                    onSortChange(next);
-                  }}
-                >
-                  <option value="rank">By Rank</option>
-                  <option value="traffic">By Traffic</option>
-                  <option value="volume">By Volume</option>
-                </select>
+                </label>
               );
             }}
           </controlsForm.Field>
 
-          <button
-            type="submit"
-            className="btn btn-primary lg:col-span-2"
-            disabled={isLoading}
-          >
-            {isLoading ? "Loading..." : "Search"}
-          </button>
+          <controlsForm.Field name="sort">
+            {(field) => (
+              <select
+                className="select select-bordered lg:col-span-2"
+                value={field.state.value}
+                onChange={(event) => {
+                  const next = toSortMode(event.target.value) ?? "rank";
+                  field.handleChange(next);
+                  onSortChange(next);
+                }}
+              >
+                <option value="rank">By Rank</option>
+                <option value="traffic">By Traffic</option>
+                <option value="volume">By Volume</option>
+              </select>
+            )}
+          </controlsForm.Field>
+
+          <controlsForm.Subscribe selector={(state) => state.isSubmitting}>
+            {(isSubmitting) => (
+              <button
+                type="submit"
+                className="btn btn-primary lg:col-span-2"
+                disabled={isLoading || isSubmitting}
+              >
+                {isLoading || isSubmitting ? "Loading..." : "Search"}
+              </button>
+            )}
+          </controlsForm.Subscribe>
         </form>
 
-        {domainError ? (
-          <p id="domain-input-error" className="text-sm text-error">
-            {domainError}
-          </p>
-        ) : null}
+        <controlsForm.Field name="domain">
+          {(field) => {
+            const domainError = getFieldError(field.state.meta.errors);
 
-        {overviewError ? (
-          <div className="rounded-lg border border-error/30 bg-error/10 p-3 text-sm text-error flex items-start gap-2">
-            <AlertCircle className="size-4 shrink-0 mt-0.5" />
-            <span>{overviewError}</span>
-          </div>
-        ) : null}
+            return domainError ? (
+              <p id="domain-input-error" className="text-sm text-error">
+                {domainError}
+              </p>
+            ) : null;
+          }}
+        </controlsForm.Field>
+
+        <controlsForm.Subscribe selector={(state) => state.errorMap.onSubmit}>
+          {(submitError) => {
+            const errorMessage = getFormError(submitError);
+
+            return errorMessage ? (
+              <div className="rounded-lg border border-error/30 bg-error/10 p-3 text-sm text-error flex items-start gap-2">
+                <AlertCircle className="size-4 shrink-0 mt-0.5" />
+                <span>{errorMessage}</span>
+              </div>
+            ) : null;
+          }}
+        </controlsForm.Subscribe>
 
         <div className="flex flex-wrap items-center gap-3">
           <label className="label cursor-pointer gap-2 py-0">
             <controlsForm.Field name="subdomains">
-              {(field) => {
-                if (!isToggleField(field)) return null;
-                return (
-                  <input
-                    type="checkbox"
-                    className="checkbox checkbox-sm"
-                    checked={field.state.value}
-                    onChange={(e) => field.handleChange(e.target.checked)}
-                  />
-                );
-              }}
+              {(field) => (
+                <input
+                  type="checkbox"
+                  className="checkbox checkbox-sm"
+                  checked={field.state.value}
+                  onChange={(event) => field.handleChange(event.target.checked)}
+                />
+              )}
             </controlsForm.Field>
             <span className="label-text">Include subdomains</span>
           </label>
diff --git a/src/client/features/domain/domainOverviewControllerInternals.ts b/src/client/features/domain/domainOverviewControllerInternals.ts
index 5d18723..a316631 100644
--- a/src/client/features/domain/domainOverviewControllerInternals.ts
+++ b/src/client/features/domain/domainOverviewControllerInternals.ts
@@ -45,6 +45,11 @@ type DomainControlsFormAccess = {
       sort: DomainSortMode;
     };
   };
+  reset: (values: {
+    domain: string;
+    subdomains: boolean;
+    sort: DomainSortMode;
+  }) => void;
   setFieldValue: (
     field: "domain" | "subdomains" | "sort",
     updater: string | boolean,
@@ -152,10 +157,11 @@ export function useOverviewDataState({
       setSelectedKeywords((prev) => {
         if (
           visibleKeywords.length > 0 &&
-          visibleKeywords.every((k) => prev.has(k))
+          visibleKeywords.every((keyword) => prev.has(keyword))
         ) {
           return new Set();
         }
+
         return new Set(visibleKeywords);
       });
     },
@@ -174,9 +180,11 @@ export function useSyncRouteState({
   navigate: DomainNavigate;
 }) {
   useEffect(() => {
-    controlsForm.setFieldValue("domain", searchState.domain);
-    controlsForm.setFieldValue("subdomains", searchState.subdomains);
-    controlsForm.setFieldValue("sort", searchState.sort);
+    controlsForm.reset({
+      domain: searchState.domain,
+      subdomains: searchState.subdomains,
+      sort: searchState.sort,
+    });
     setPendingSearch(searchState.search);
   }, [controlsForm, searchState, setPendingSearch]);
 
@@ -217,13 +225,7 @@ export function useSyncRouteState({
   }, [navigate]);
 }
 
-export function useDomainLookupMutation({
-  setOverview,
-  setOverviewError,
-}: {
-  setOverview: (value: DomainOverviewData) => void;
-  setOverviewError: (value: string | null) => void;
-}) {
+export function useDomainLookupMutation() {
   return useMutation({
     mutationFn: (data: {
       domain: string;
@@ -231,20 +233,11 @@ export function useDomainLookupMutation({
       locationCode: number;
       languageCode: string;
     }) => getDomainOverview({ data }),
-    onError: (error) => {
-      setOverviewError(getStandardErrorMessage(error, "Lookup failed."));
-    },
-    onSuccess: (response) => {
-      setOverview(response);
-      if (!response.hasData) toast.info("Not enough data for this domain");
-    },
   });
 }
 
 export function useSearchRunner({
   controlsForm,
-  setDomainError,
-  setOverviewError,
   setPendingSearch,
   setSearchParams,
   domainMutation,
@@ -255,20 +248,18 @@ export function useSearchRunner({
   currentSortOrder,
 }: {
   controlsForm: ControlsFormLike;
-  setDomainError: (value: string | null) => void;
-  setOverviewError: (value: string | null) => void;
   setPendingSearch: (value: string) => void;
   setSearchParams: (
     updates: Record<string, string | boolean | undefined>,
   ) => void;
-  domainMutation: ReturnType<typeof useDomainLookupMutation>["mutate"];
+  domainMutation: ReturnType<typeof useDomainLookupMutation>;
   addSearch: (item: Omit<DomainSearchHistoryItem, "timestamp">) => void;
   setOverview: (value: DomainOverviewData) => void;
-  setSelectedKeywords: (value: Set<string>) => void;
+  setSelectedKeywords: Dispatch<SetStateAction<Set<string>>>;
   currentState: SearchState;
   currentSortOrder: SortOrder;
 }) {
-  return (params?: Partial<SearchState>) => {
+  return async (params?: Partial<SearchState>) => {
     const values = controlsForm.state.values;
     const rawTarget = params?.domain ?? values.domain;
     const activeSubdomains = params?.subdomains ?? values.subdomains;
@@ -276,22 +267,12 @@ export function useSearchRunner({
     const activeOrder = params?.order ?? currentSortOrder;
     const activeTab = params?.tab ?? currentState.tab;
     const activeSearch = params?.search ?? currentState.search;
-
-    if (!rawTarget.trim()) {
-      setDomainError("Please enter a domain");
-      return;
-    }
-
     const target = normalizeDomainTarget(rawTarget);
+
     if (!target) {
-      setDomainError(
-        "Please enter a valid URL or domain (e.g. browserbase.com)",
-      );
       return;
     }
 
-    setDomainError(null);
-    setOverviewError(null);
     setPendingSearch(activeSearch);
     controlsForm.setFieldValue("domain", target);
     controlsForm.setFieldValue("subdomains", activeSubdomains);
@@ -306,29 +287,30 @@ export function useSearchRunner({
       search: activeSearch.trim() || undefined,
     });
 
-    domainMutation(
-      {
+    try {
+      const response = await domainMutation.mutateAsync({
         domain: target,
         includeSubdomains: activeSubdomains,
         locationCode: 2840,
         languageCode: "en",
-      },
-      {
-        onSuccess: (response) => {
-          setOverview(response);
-          setSelectedKeywords(new Set());
-          addSearch({
-            domain: target,
-            subdomains: activeSubdomains,
-            sort: activeSort,
-            tab: activeTab,
-            search: activeSearch.trim() || undefined,
-          });
-        },
-        onError: (error) => {
-          setOverviewError(getStandardErrorMessage(error, "Lookup failed."));
-        },
-      },
-    );
+      });
+
+      setOverview(response);
+      setSelectedKeywords(new Set());
+      addSearch({
+        domain: target,
+        subdomains: activeSubdomains,
+        sort: activeSort,
+        tab: activeTab,
+        search: activeSearch.trim() || undefined,
+      });
+
+      if (!response.hasData) {
+        toast.info("Not enough data for this domain");
+      }
+      return null;
+    } catch (error) {
+      return getStandardErrorMessage(error, "Lookup failed.");
+    }
   };
 }
diff --git a/src/client/features/domain/useDomainOverviewController.ts b/src/client/features/domain/useDomainOverviewController.ts
index 05c1a3f..1e919ed 100644
--- a/src/client/features/domain/useDomainOverviewController.ts
+++ b/src/client/features/domain/useDomainOverviewController.ts
@@ -1,16 +1,21 @@
 import { useCallback, useEffect, useState, type FormEvent } from "react";
-import { type QueryClient } from "@tanstack/react-query";
 import { useForm } from "@tanstack/react-form";
+import { type QueryClient } from "@tanstack/react-query";
 import {
   useDomainSearchHistory,
   type DomainSearchHistoryItem,
 } from "@/client/hooks/useDomainSearchHistory";
 import {
   getDefaultSortOrder,
+  normalizeDomainTarget,
   resolveSortOrder,
   toSortOrderSearchParam,
   toSortSearchParam,
 } from "@/client/features/domain/utils";
+import {
+  createFormValidationErrors,
+  shouldValidateFieldOnChange,
+} from "@/client/lib/forms";
 import type {
   DomainControlsValues,
   DomainOverviewData,
@@ -37,8 +42,60 @@ type Params = {
   searchState: SearchState;
 };
 
-function useDomainControlsForm(defaultValues: DomainControlsValues) {
-  return useForm({ defaultValues });
+type DomainControlsFormApi = {
+  state: {
+    values: DomainControlsValues;
+  };
+  handleSubmit: () => Promise<unknown>;
+  reset: (values: DomainControlsValues) => void;
+  setFieldValue: (
+    field: keyof DomainControlsValues,
+    value: string | boolean,
+  ) => void;
+};
+
+function getDomainSearchValidationErrors(value: DomainControlsValues) {
+  if (!value.domain.trim()) {
+    return createFormValidationErrors({
+      fields: {
+        domain: "Please enter a domain",
+      },
+    });
+  }
+
+  if (!normalizeDomainTarget(value.domain)) {
+    return createFormValidationErrors({
+      fields: {
+        domain: "Please enter a valid URL or domain (e.g. browserbase.com)",
+      },
+    });
+  }
+
+  return null;
+}
+
+function getDomainSearchChangeValidationErrors(
+  value: DomainControlsValues,
+  shouldValidateUntouchedField: boolean,
+  shouldValidateFormat: boolean,
+) {
+  if (!value.domain.trim()) {
+    if (!shouldValidateUntouchedField) {
+      return null;
+    }
+
+    return createFormValidationErrors({
+      fields: {
+        domain: "Please enter a domain",
+      },
+    });
+  }
+
+  if (!shouldValidateFormat) {
+    return null;
+  }
+
+  return getDomainSearchValidationErrors(value);
 }
 
 export function useDomainOverviewController({
@@ -47,18 +104,11 @@ export function useDomainOverviewController({
   navigate,
   searchState,
 }: Params) {
-  const [domainError, setDomainError] = useState<string | null>(null);
-  const [overviewError, setOverviewError] = useState<string | null>(null);
   const [pendingSearch, setPendingSearch] = useState(searchState.search);
   const [overview, setOverview] = useState<DomainOverviewData | null>(null);
   const [selectedKeywords, setSelectedKeywords] = useState<Set<string>>(
     new Set(),
   );
-  const controlsForm = useDomainControlsForm({
-    domain: searchState.domain,
-    subdomains: searchState.subdomains,
-    sort: searchState.sort,
-  });
   const { history, isLoaded, addSearch, clearHistory, removeHistoryItem } =
     useDomainSearchHistory(projectId);
 
@@ -76,11 +126,41 @@ export function useDomainOverviewController({
     [navigate],
   );
 
-  useSyncRouteState({ controlsForm, searchState, setPendingSearch, navigate });
-  const domainMutation = useDomainLookupMutation({
-    setOverview,
-    setOverviewError,
+  const controlsForm = useForm({
+    defaultValues: {
+      domain: searchState.domain,
+      subdomains: searchState.subdomains,
+      sort: searchState.sort,
+    },
+    validators: {
+      onChange: ({ formApi, value }) =>
+        getDomainSearchChangeValidationErrors(
+          value,
+          shouldValidateFieldOnChange(formApi, "domain"),
+          formApi.state.submissionAttempts > 0,
+        ),
+      onSubmit: ({ value }) => getDomainSearchValidationErrors(value),
+    },
+    onSubmit: async ({ formApi, value }) => {
+      const submitError = await runSearch({
+        domain: value.domain,
+        subdomains: value.subdomains,
+        sort: value.sort,
+        order: currentSortOrder,
+        tab: searchState.tab,
+        search: searchState.search,
+      });
+
+      formApi.setErrorMap({
+        onSubmit: submitError
+          ? createFormValidationErrors({ form: submitError })
+          : undefined,
+      });
+    },
   });
+
+  useSyncRouteState({ controlsForm, searchState, setPendingSearch, navigate });
+  const domainMutation = useDomainLookupMutation();
   const saveMutation = useSaveKeywordsMutation({ projectId, queryClient });
   const dataState = useOverviewDataState({
     overview,
@@ -94,29 +174,32 @@ export function useDomainOverviewController({
     setSearchParams({ search: pendingSearch.trim() || undefined });
   }, [pendingSearch, setSearchParams]);
 
-  const handlers = useDomainControllerHandlers({
+  const runSearch = useSearchRunner({
+    controlsForm,
+    setPendingSearch,
+    setSearchParams,
+    domainMutation,
     addSearch,
+    setOverview: (value) => setOverview(value),
+    setSelectedKeywords,
+    currentState: searchState,
+    currentSortOrder,
+  });
+
+  const handlers = useDomainControllerHandlers({
     controlsForm,
     currentSortOrder,
     currentState: searchState,
     dataState,
-    domainMutation: domainMutation.mutate,
     projectId,
+    runSearch,
     saveMutation,
     selectedKeywords,
-    setDomainError,
-    setOverview,
-    setOverviewError,
-    setPendingSearch,
     setSearchParams,
-    setSelectedKeywords,
   });
 
   return {
     controlsForm,
-    domainError,
-    setDomainError,
-    overviewError,
     isLoading: domainMutation.isPending,
     overview,
     history,
@@ -134,39 +217,27 @@ export function useDomainOverviewController({
 }
 
 function useDomainControllerHandlers({
-  addSearch,
   controlsForm,
   currentSortOrder,
   currentState,
   dataState,
-  domainMutation,
   projectId,
+  runSearch,
   saveMutation,
   selectedKeywords,
-  setDomainError,
-  setOverview,
-  setOverviewError,
-  setPendingSearch,
   setSearchParams,
-  setSelectedKeywords,
 }: {
-  addSearch: (item: Omit<DomainSearchHistoryItem, "timestamp">) => void;
-  controlsForm: ReturnType<typeof useDomainControlsForm>;
+  controlsForm: DomainControlsFormApi;
   currentSortOrder: SortOrder;
   currentState: SearchState;
   dataState: ReturnType<typeof useOverviewDataState>;
-  domainMutation: ReturnType<typeof useDomainLookupMutation>["mutate"];
   projectId: string;
+  runSearch: ReturnType<typeof useSearchRunner>;
   saveMutation: ReturnType<typeof useSaveKeywordsMutation>;
   selectedKeywords: Set<string>;
-  setDomainError: (value: string | null) => void;
-  setOverview: (value: DomainOverviewData | null) => void;
-  setOverviewError: (value: string | null) => void;
-  setPendingSearch: (value: string) => void;
   setSearchParams: (
     updates: Record<string, string | number | boolean | undefined>,
   ) => void;
-  setSelectedKeywords: (value: Set<string>) => void;
 }) {
   const applySort = useCallback(
     (nextSort: DomainSortMode, nextOrder: SortOrder) => {
@@ -200,22 +271,13 @@ function useDomainControllerHandlers({
       projectId,
     });
 
-  const runSearch = useSearchRunner({
-    controlsForm,
-    setDomainError,
-    setOverviewError,
-    setPendingSearch,
-    setSearchParams,
-    domainMutation,
-    addSearch,
-    setOverview: (value) => setOverview(value),
-    setSelectedKeywords,
-    currentState,
-    currentSortOrder,
-  });
-
   const handleHistorySelect = (item: DomainSearchHistoryItem) => {
-    runSearch({
+    controlsForm.reset({
+      domain: item.domain,
+      subdomains: item.subdomains,
+      sort: item.sort,
+    });
+    void runSearch({
       domain: item.domain,
       subdomains: item.subdomains,
       sort: item.sort,
@@ -227,7 +289,7 @@ function useDomainControllerHandlers({
 
   const handleSearchSubmit = (event: FormEvent) => {
     event.preventDefault();
-    runSearch();
+    void controlsForm.handleSubmit();
   };
 
   return {
diff --git a/src/client/features/keywords/hooks/useKeywordControlsForm.ts b/src/client/features/keywords/hooks/useKeywordControlsForm.ts
index 1ca66e6..5ad1dac 100644
--- a/src/client/features/keywords/hooks/useKeywordControlsForm.ts
+++ b/src/client/features/keywords/hooks/useKeywordControlsForm.ts
@@ -1,9 +1,14 @@
-import { useForm } from "@tanstack/react-form";
 import { useEffect } from "react";
-import type {
-  KeywordMode,
-  ResultLimit,
+import { useForm } from "@tanstack/react-form";
+import {
+  createFormValidationErrors,
+  shouldValidateFieldOnChange,
+} from "@/client/lib/forms";
+import {
+  type KeywordMode,
+  type ResultLimit,
 } from "@/client/features/keywords/keywordResearchTypes";
+import { parseKeywordInput } from "@/client/features/keywords/state/keywordControllerActions";
 
 type UseKeywordControlsFormInput = {
   keywordInput: string;
@@ -12,7 +17,36 @@ type UseKeywordControlsFormInput = {
   keywordMode: KeywordMode;
 };
 
-export function useKeywordControlsForm(input: UseKeywordControlsFormInput) {
+type KeywordControlsValues = {
+  keyword: string;
+  locationCode: number;
+  resultLimit: ResultLimit;
+  mode: KeywordMode;
+};
+
+function getKeywordSearchValidationErrors(
+  value: KeywordControlsValues,
+  shouldValidateUntouchedField: boolean,
+) {
+  if (parseKeywordInput(value.keyword).length > 0) {
+    return null;
+  }
+
+  if (!shouldValidateUntouchedField) {
+    return null;
+  }
+
+  return createFormValidationErrors({
+    fields: {
+      keyword: "Please enter at least one keyword.",
+    },
+  });
+}
+
+export function useKeywordControlsForm(
+  input: UseKeywordControlsFormInput,
+  onSubmit: (value: KeywordControlsValues) => void,
+) {
   const form = useForm({
     defaultValues: {
       keyword: input.keywordInput,
@@ -20,13 +54,26 @@ export function useKeywordControlsForm(input: UseKeywordControlsFormInput) {
       resultLimit: input.resultLimit,
       mode: input.keywordMode,
     },
+    validators: {
+      onChange: ({ formApi, value }) =>
+        getKeywordSearchValidationErrors(
+          value,
+          shouldValidateFieldOnChange(formApi, "keyword"),
+        ),
+      onSubmit: ({ value }) => getKeywordSearchValidationErrors(value, true),
+    },
+    onSubmit: ({ value }) => {
+      onSubmit(value);
+    },
   });
 
   useEffect(() => {
-    form.setFieldValue("keyword", input.keywordInput);
-    form.setFieldValue("locationCode", input.locationCode);
-    form.setFieldValue("resultLimit", input.resultLimit);
-    form.setFieldValue("mode", input.keywordMode);
+    form.reset({
+      keyword: input.keywordInput,
+      locationCode: input.locationCode,
+      resultLimit: input.resultLimit,
+      mode: input.keywordMode,
+    });
   }, [
     form,
     input.keywordInput,
diff --git a/src/client/features/keywords/page/KeywordResearchSearchBar.tsx b/src/client/features/keywords/page/KeywordResearchSearchBar.tsx
index 7e3b842..10a4b10 100644
--- a/src/client/features/keywords/page/KeywordResearchSearchBar.tsx
+++ b/src/client/features/keywords/page/KeywordResearchSearchBar.tsx
@@ -1,4 +1,5 @@
 import { Search } from "lucide-react";
+import { getFieldError } from "@/client/lib/forms";
 import {
   isResultLimit,
   normalizeKeywordMode,
@@ -12,8 +13,7 @@ type Props = {
 };
 
 export function KeywordResearchSearchBar({ controller }: Props) {
-  const { controlsForm, handleSearchSubmit, isLoading, searchInputError } =
-    controller;
+  const { controlsForm, handleSearchSubmit, isLoading } = controller;
 
   return (
     <div className="shrink-0 px-4 md:px-6 pt-4 pb-2 max-w-8xl mx-auto w-full">
@@ -21,24 +21,25 @@ export function KeywordResearchSearchBar({ controller }: Props) {
         className="bg-base-100 border border-base-300 rounded-xl px-4 py-3 flex flex-wrap items-center gap-2"
         onSubmit={handleSearchSubmit}
       >
-        <label
-          className={`input input-bordered input-sm flex items-center gap-2 flex-1 min-w-0 max-w-md ${searchInputError ? "input-error" : ""}`}
-        >
-          <Search className="size-3.5 shrink-0 text-base-content/50" />
-          <controlsForm.Field name="keyword">
-            {(field) => (
-              <input
-                className="grow min-w-0"
-                placeholder="Enter Keyword"
-                value={field.state.value}
-                onChange={(event) => {
-                  field.handleChange(event.target.value);
-                  if (searchInputError) controller.setSearchInputError(null);
-                }}
-              />
-            )}
-          </controlsForm.Field>
-        </label>
+        <controlsForm.Field name="keyword">
+          {(field) => {
+            const keywordError = getFieldError(field.state.meta.errors);
+
+            return (
+              <label
+                className={`input input-bordered input-sm flex items-center gap-2 flex-1 min-w-0 max-w-md ${keywordError ? "input-error" : ""}`}
+              >
+                <Search className="size-3.5 shrink-0 text-base-content/50" />
+                <input
+                  className="grow min-w-0"
+                  placeholder="Enter Keyword"
+                  value={field.state.value}
+                  onChange={(event) => field.handleChange(event.target.value)}
+                />
+              </label>
+            );
+          }}
+        </controlsForm.Field>
 
         <controlsForm.Field name="locationCode">
           {(field) => (
@@ -102,9 +103,15 @@ export function KeywordResearchSearchBar({ controller }: Props) {
           {isLoading ? "Searching..." : "Search"}
         </button>
       </form>
-      {searchInputError ? (
-        <p className="mt-2 text-sm text-error">{searchInputError}</p>
-      ) : null}
+      <controlsForm.Field name="keyword">
+        {(field) => {
+          const keywordError = getFieldError(field.state.meta.errors);
+
+          return keywordError ? (
+            <p className="mt-2 text-sm text-error">{keywordError}</p>
+          ) : null;
+        }}
+      </controlsForm.Field>
     </div>
   );
 }
diff --git a/src/client/features/keywords/state/keywordControllerActions.ts b/src/client/features/keywords/state/keywordControllerActions.ts
index 1062d14..5d33250 100644
--- a/src/client/features/keywords/state/keywordControllerActions.ts
+++ b/src/client/features/keywords/state/keywordControllerActions.ts
@@ -1,57 +1,11 @@
-import { type FormEvent } from "react";
 import { toast } from "sonner";
-import { DEFAULT_LOCATION_CODE } from "@/client/features/keywords/locations";
 import { buildCsv, downloadCsv } from "@/client/lib/csv";
 import { getStandardErrorMessage } from "@/client/lib/error-messages";
-import type {
-  KeywordMode,
-  ResultLimit,
-} from "@/client/features/keywords/keywordResearchTypes";
 import { getLanguageCode } from "@/client/features/keywords/utils";
 import type { KeywordResearchRow } from "@/types/keywords";
 import type { SortDir, SortField } from "@/client/features/keywords/components";
 import type { KeywordResearchControllerInput } from "./useKeywordResearchController";
 
-type ControlsFormLike = {
-  state: {
-    values: {
-      keyword: string;
-      locationCode: number;
-      resultLimit: ResultLimit;
-      mode: KeywordMode;
-    };
-  };
-};
-
-type RunSearchLike = (
-  args: {
-    projectId: string;
-    keywords: string[];
-    locationCode: number;
-    resultLimit: ResultLimit;
-    mode: KeywordMode;
-  },
-  options: {
-    onSuccess: (seedKeyword: string, nextRows: KeywordResearchRow[]) => void;
-  },
-) => void;
-
-type SearchActionParams = {
-  controlsForm: ControlsFormLike;
-  input: KeywordResearchControllerInput;
-  beginSearch: (seedKeyword: string, locationCode: number) => void;
-  runSearch: RunSearchLike;
-  clearSelection: () => void;
-  setSelectedKeyword: (keyword: KeywordResearchRow | null) => void;
-  setSerpKeyword: (keyword: string | null) => void;
-  setSerpPage: (page: number) => void;
-  setSearchInputError: (error: string | null) => void;
-  setSearchParams: (
-    updates: Record<string, string | number | boolean | undefined>,
-  ) => void;
-  setPreferredLocationCode: (locationCode: number) => void;
-};
-
 type SaveExportActionParams = {
   selectedRows: Set<string>;
   filteredRows: KeywordResearchRow[];
@@ -71,7 +25,14 @@ type SaveExportActionParams = {
   setShowSaveDialog: (show: boolean) => void;
 };
 
-function getNextSortParams(
+export function parseKeywordInput(value: string) {
+  return value
+    .split(/[\n,]/)
+    .map((keyword) => keyword.trim())
+    .filter(Boolean);
+}
+
+export function getNextSortParams(
   currentField: SortField,
   currentDirection: SortDir,
   targetField: SortField,
@@ -86,93 +47,6 @@ function getNextSortParams(
   };
 }
 
-export function useSearchActions(params: SearchActionParams) {
-  const {
-    controlsForm,
-    input,
-    beginSearch,
-    runSearch,
-    clearSelection,
-    setSelectedKeyword,
-    setSerpKeyword,
-    setSerpPage,
-    setSearchInputError,
-    setSearchParams,
-    setPreferredLocationCode,
-  } = params;
-
-  const onSearch = (
-    overrides?: Partial<{
-      keyword: string;
-      locationCode: number;
-    }>,
-  ) => {
-    const values = controlsForm.state.values;
-    const inputKeyword = overrides?.keyword ?? values.keyword;
-    const activeLocation = overrides?.locationCode ?? values.locationCode;
-    const activeResultLimit = values.resultLimit;
-    const activeMode = values.mode;
-    const keywords = inputKeyword
-      .split(/[\n,]/)
-      .map((keyword) => keyword.trim())
-      .filter(Boolean);
-
-    if (keywords.length === 0) {
-      setSearchInputError("Please enter at least one keyword.");
-      return;
-    }
-
-    setSearchInputError(null);
-    setPreferredLocationCode(activeLocation);
-    setSearchParams({
-      q: inputKeyword,
-      loc:
-        input.hasExplicitLocationCode ||
-        activeLocation !== DEFAULT_LOCATION_CODE
-          ? activeLocation
-          : undefined,
-      kLimit: activeResultLimit === 150 ? undefined : activeResultLimit,
-      mode: activeMode === "auto" ? undefined : activeMode,
-    });
-
-    setSelectedKeyword(null);
-    clearSelection();
-    setSerpKeyword(null);
-    beginSearch(keywords[0], activeLocation);
-
-    runSearch(
-      {
-        projectId: input.projectId,
-        keywords,
-        locationCode: activeLocation,
-        resultLimit: activeResultLimit,
-        mode: activeMode,
-      },
-      {
-        onSuccess: (seedKeyword, nextRows) => {
-          if (nextRows.length === 0) {
-            setSerpKeyword(null);
-            return;
-          }
-          setSerpKeyword(seedKeyword);
-          setSerpPage(0);
-        },
-      },
-    );
-  };
-
-  const handleSearchSubmit = (event: FormEvent) => {
-    event.preventDefault();
-    onSearch();
-  };
-
-  const toggleSort = (field: SortField) => {
-    setSearchParams(getNextSortParams(input.sortField, input.sortDir, field));
-  };
-
-  return { onSearch, handleSearchSubmit, toggleSort };
-}
-
 export function useSaveAndExportActions(params: SaveExportActionParams) {
   const {
     selectedRows,
diff --git a/src/client/features/keywords/state/keywordControllerInternals.ts b/src/client/features/keywords/state/keywordControllerInternals.ts
new file mode 100644
index 0000000..9abbbad
--- /dev/null
+++ b/src/client/features/keywords/state/keywordControllerInternals.ts
@@ -0,0 +1,68 @@
+import { useNavigate } from "@tanstack/react-router";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+import { usePreferredKeywordLocation } from "@/client/features/keywords/hooks/usePreferredKeywordLocation";
+import { saveKeywords } from "@/serverFunctions/keywords";
+import type { KeywordResearchRow } from "@/types/keywords";
+import type { KeywordResearchControllerInput } from "./useKeywordResearchController";
+
+export function useResolvedKeywordLocation(
+  input: KeywordResearchControllerInput,
+) {
+  const { preferredLocationCode, setPreferredLocationCode } =
+    usePreferredKeywordLocation();
+  const locationCode =
+    !input.hasExplicitLocationCode && input.keywordInput === ""
+      ? preferredLocationCode
+      : input.locationCode;
+
+  return { locationCode, setPreferredLocationCode };
+}
+
+export function useKeywordUiState() {
+  const [showFilters, setShowFilters] = useState(false);
+  const [selectedKeyword, setSelectedKeyword] =
+    useState<KeywordResearchRow | null>(null);
+  const [showSaveDialog, setShowSaveDialog] = useState(false);
+  const [mobileTab, setMobileTab] = useState<"keywords" | "serp">("keywords");
+
+  return {
+    mobileTab,
+    selectedKeyword,
+    setMobileTab,
+    setSelectedKeyword,
+    setShowFilters,
+    setShowSaveDialog,
+    showFilters,
+    showSaveDialog,
+  };
+}
+
+export function useKeywordSearchParams() {
+  const navigate = useNavigate({ from: "/p/$projectId/keywords" });
+
+  return (updates: Record<string, string | number | boolean | undefined>) => {
+    void navigate({
+      search: (prev) => ({ ...prev, ...updates }),
+      replace: true,
+    });
+  };
+}
+
+export function useKeywordSaveMutation(projectId: string) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: {
+      projectId: string;
+      keywords: string[];
+      locationCode: number;
+      languageCode: string;
+    }) => saveKeywords({ data }),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: ["savedKeywords", projectId],
+      });
+    },
+  });
+}
diff --git a/src/client/features/keywords/state/useKeywordResearchController.ts b/src/client/features/keywords/state/useKeywordResearchController.ts
index 459dd22..dd3a67a 100644
--- a/src/client/features/keywords/state/useKeywordResearchController.ts
+++ b/src/client/features/keywords/state/useKeywordResearchController.ts
@@ -1,9 +1,6 @@
-import { useNavigate } from "@tanstack/react-router";
-import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { useCallback, useState } from "react";
+import { useCallback, type FormEvent } from "react";
 import { useKeywordControlsForm } from "@/client/features/keywords/hooks/useKeywordControlsForm";
 import { useKeywordFiltering } from "@/client/features/keywords/hooks/useKeywordFiltering";
-import { usePreferredKeywordLocation } from "@/client/features/keywords/hooks/usePreferredKeywordLocation";
 import { useLocalKeywordFilters } from "@/client/features/keywords/hooks/useLocalKeywordFilters";
 import { useKeywordResearchData } from "@/client/features/keywords/hooks/useKeywordResearchData";
 import { useKeywordSelection } from "@/client/features/keywords/hooks/useKeywordSelection";
@@ -13,13 +10,20 @@ import {
   type KeywordMode,
   type ResultLimit,
 } from "@/client/features/keywords/keywordResearchTypes";
-import { saveKeywords } from "@/serverFunctions/keywords";
+import { DEFAULT_LOCATION_CODE } from "@/client/features/keywords/locations";
 import type { KeywordResearchRow } from "@/types/keywords";
 import type { SortDir, SortField } from "@/client/features/keywords/components";
 import {
+  getNextSortParams,
+  parseKeywordInput,
   useSaveAndExportActions,
-  useSearchActions,
 } from "./keywordControllerActions";
+import {
+  useKeywordSaveMutation,
+  useKeywordSearchParams,
+  useKeywordUiState,
+  useResolvedKeywordLocation,
+} from "./keywordControllerInternals";
 import { useKeywordOverviewState } from "./useKeywordOverviewState";
 
 export type KeywordResearchControllerInput = {
@@ -37,20 +41,38 @@ export function useKeywordResearchController(
   input: KeywordResearchControllerInput,
 ) {
   const state = useKeywordControllerState(input);
+  const controlsForm = state.controlsForm;
+  const setSearchParams = state.setSearchParams;
 
-  const { onSearch, handleSearchSubmit, toggleSort } = useSearchActions({
-    controlsForm: state.controlsForm,
-    input,
-    beginSearch: state.beginSearch,
-    runSearch: state.runSearch,
-    clearSelection: state.clearSelection,
-    setSelectedKeyword: state.setSelectedKeyword,
-    setSerpKeyword: state.setSerpKeyword,
-    setSerpPage: state.setSerpPage,
-    setSearchInputError: state.setSearchInputError,
-    setSearchParams: state.setSearchParams,
-    setPreferredLocationCode: state.setPreferredLocationCode,
-  });
+  const onSearch = useCallback(
+    (overrides?: Partial<{ keyword: string; locationCode: number }>) => {
+      if (overrides?.keyword !== undefined) {
+        controlsForm.setFieldValue("keyword", overrides.keyword);
+      }
+
+      if (overrides?.locationCode !== undefined) {
+        controlsForm.setFieldValue("locationCode", overrides.locationCode);
+      }
+
+      void controlsForm.handleSubmit();
+    },
+    [controlsForm],
+  );
+
+  const handleSearchSubmit = useCallback(
+    (event: FormEvent) => {
+      event.preventDefault();
+      void controlsForm.handleSubmit();
+    },
+    [controlsForm],
+  );
+
+  const toggleSort = useCallback(
+    (field: SortField) => {
+      setSearchParams(getNextSortParams(input.sortField, input.sortDir, field));
+    },
+    [input.sortDir, input.sortField, setSearchParams],
+  );
 
   const { handleSaveKeywords, confirmSave, exportCsv } =
     useSaveAndExportActions({
@@ -71,7 +93,7 @@ export function useKeywordResearchController(
     state.setSerpPage(0);
   };
 
-  return buildControllerOutput({
+  return {
     activeFilterCount: state.activeFilterCount,
     activeSerpKeyword: state.activeSerpKeyword,
     clearHistory: state.clearHistory,
@@ -100,7 +122,6 @@ export function useKeywordResearchController(
     resetFilters: state.resetFilters,
     rows: state.rows,
     searchedKeyword: state.searchedKeyword,
-    searchInputError: state.searchInputError,
     selectedRows: state.selectedRows,
     serpError: state.serpError,
     serpLoading: state.serpLoading,
@@ -108,7 +129,6 @@ export function useKeywordResearchController(
     serpQuery: state.serpQuery,
     serpResults: state.serpResults,
     setMobileTab: state.setMobileTab,
-    setSearchInputError: state.setSearchInputError,
     setSerpPage: state.setSerpPage,
     setShowFilters: state.setShowFilters,
     setShowSaveDialog: state.setShowSaveDialog,
@@ -121,18 +141,13 @@ export function useKeywordResearchController(
     toggleRowSelection: state.toggleRowSelection,
     toggleSort,
     SERP_PAGE_SIZE: state.SERP_PAGE_SIZE,
-  });
+  };
 }
 
 function useKeywordControllerState(input: KeywordResearchControllerInput) {
   const uiState = useKeywordUiState();
   const { locationCode, setPreferredLocationCode } =
     useResolvedKeywordLocation(input);
-
-  const controlsForm = useKeywordControlsForm({
-    ...input,
-    locationCode,
-  });
   const {
     filtersForm,
     values: filterValues,
@@ -177,6 +192,56 @@ function useKeywordControllerState(input: KeywordResearchControllerInput) {
   const setSearchParams = useKeywordSearchParams();
   const saveMutation = useKeywordSaveMutation(input.projectId);
 
+  const controlsForm = useKeywordControlsForm(
+    {
+      ...input,
+      locationCode,
+    },
+    (value) => {
+      const keywords = parseKeywordInput(value.keyword);
+      const activeLocation = value.locationCode;
+      const activeResultLimit = value.resultLimit;
+      const activeMode = value.mode;
+
+      setPreferredLocationCode(activeLocation);
+      setSearchParams({
+        q: value.keyword,
+        loc:
+          input.hasExplicitLocationCode ||
+          activeLocation !== DEFAULT_LOCATION_CODE
+            ? activeLocation
+            : undefined,
+        kLimit: activeResultLimit === 150 ? undefined : activeResultLimit,
+        mode: activeMode === "auto" ? undefined : activeMode,
+      });
+
+      uiState.setSelectedKeyword(null);
+      clearSelection();
+      setSerpKeyword(null);
+      beginSearch(keywords[0] ?? "", activeLocation);
+
+      runSearch(
+        {
+          projectId: input.projectId,
+          keywords,
+          locationCode: activeLocation,
+          resultLimit: activeResultLimit,
+          mode: activeMode,
+        },
+        {
+          onSuccess: (seedKeyword, nextRows) => {
+            if (nextRows.length === 0) {
+              setSerpKeyword(null);
+              return;
+            }
+            setSerpKeyword(seedKeyword);
+            setSerpPage(0);
+          },
+        },
+      );
+    },
+  );
+
   const { filteredRows, activeFilterCount } = useKeywordFiltering({
     rows,
     filters: filterValues,
@@ -195,7 +260,7 @@ function useKeywordControllerState(input: KeywordResearchControllerInput) {
       keywordMode: input.keywordMode,
     });
 
-  return buildKeywordControllerState({
+  return {
     activeFilterCount,
     activeSerpKeyword,
     beginSearch,
@@ -221,7 +286,6 @@ function useKeywordControllerState(input: KeywordResearchControllerInput) {
     resetFilters,
     rows,
     searchedKeyword,
-    searchInputError: uiState.searchInputError,
     selectedKeyword: uiState.selectedKeyword,
     selectedRows,
     saveMutation,
@@ -235,7 +299,6 @@ function useKeywordControllerState(input: KeywordResearchControllerInput) {
     serpQuery,
     serpResults,
     setMobileTab: uiState.setMobileTab,
-    setSearchInputError: uiState.setSearchInputError,
     setSerpPage,
     setShowFilters: uiState.setShowFilters,
     setShowSaveDialog: uiState.setShowSaveDialog,
@@ -245,80 +308,5 @@ function useKeywordControllerState(input: KeywordResearchControllerInput) {
     toggleAllRows,
     toggleRowSelection,
     SERP_PAGE_SIZE,
-  });
-}
-
-function useResolvedKeywordLocation(input: KeywordResearchControllerInput) {
-  const { preferredLocationCode, setPreferredLocationCode } =
-    usePreferredKeywordLocation();
-  const locationCode =
-    !input.hasExplicitLocationCode && input.keywordInput === ""
-      ? preferredLocationCode
-      : input.locationCode;
-
-  return { locationCode, setPreferredLocationCode };
-}
-
-function useKeywordUiState() {
-  const [showFilters, setShowFilters] = useState(false);
-  const [selectedKeyword, setSelectedKeyword] =
-    useState<KeywordResearchRow | null>(null);
-  const [searchInputError, setSearchInputError] = useState<string | null>(null);
-  const [showSaveDialog, setShowSaveDialog] = useState(false);
-  const [mobileTab, setMobileTab] = useState<"keywords" | "serp">("keywords");
-
-  return {
-    mobileTab,
-    searchInputError,
-    selectedKeyword,
-    setMobileTab,
-    setSearchInputError,
-    setSelectedKeyword,
-    setShowFilters,
-    setShowSaveDialog,
-    showFilters,
-    showSaveDialog,
   };
 }
-
-function useKeywordSearchParams() {
-  const navigate = useNavigate({ from: "/p/$projectId/keywords" });
-
-  return useCallback(
-    (updates: Record<string, string | number | boolean | undefined>) => {
-      void navigate({
-        search: (prev) => ({ ...prev, ...updates }),
-        replace: true,
-      });
-    },
-    [navigate],
-  );
-}
-
-function useKeywordSaveMutation(projectId: string) {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: (data: {
-      projectId: string;
-      keywords: string[];
-      locationCode: number;
-      languageCode: string;
-    }) => saveKeywords({ data }),
-    onSuccess: () => {
-      void queryClient.invalidateQueries({
-        queryKey: ["savedKeywords", projectId],
-      });
-    },
-  });
-}
-
-function buildControllerOutput<T extends Record<string, unknown>>(state: T): T {
-  return state;
-}
-
-function buildKeywordControllerState<T extends Record<string, unknown>>(
-  state: T,
-): T {
-  return state;
-}
diff --git a/src/client/lib/error-messages.test.ts b/src/client/lib/error-messages.test.ts
new file mode 100644
index 0000000..d8bdf6f
--- /dev/null
+++ b/src/client/lib/error-messages.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { getStandardErrorMessage } from "@/client/lib/error-messages";
+
+describe("getStandardErrorMessage", () => {
+  it("maps known error codes to standard copy", () => {
+    expect(getStandardErrorMessage(new Error("PAYMENT_REQUIRED"))).toBe(
+      "An active hosted subscription is required before you can use OpenSEO.",
+    );
+  });
+
+  it("returns custom messages when the error is not a shared code", () => {
+    expect(
+      getStandardErrorMessage(
+        new Error("DataForSEO task missing billing metadata. Response: {...}"),
+      ),
+    ).toBe("DataForSEO task missing billing metadata. Response: {...}");
+  });
+});
diff --git a/src/client/lib/error-messages.ts b/src/client/lib/error-messages.ts
index d1705d0..57c7bc9 100644
--- a/src/client/lib/error-messages.ts
+++ b/src/client/lib/error-messages.ts
@@ -28,6 +28,7 @@ export function getStandardErrorMessage(
 ): string {
   if (!(error instanceof Error)) return fallback;
   if (isErrorCode(error.message)) return STANDARD_MESSAGES[error.message];
+  if (error.message) return error.message;
   return fallback;
 }
 
diff --git a/src/client/lib/forms.ts b/src/client/lib/forms.ts
new file mode 100644
index 0000000..38fb20c
--- /dev/null
+++ b/src/client/lib/forms.ts
@@ -0,0 +1,81 @@
+type FormValidationErrors = {
+  form?: string;
+  fields?: Record<string, string>;
+} | null;
+
+type FieldValidationFormApi<TField extends string> = {
+  state: {
+    submissionAttempts: number;
+  };
+  getFieldMeta: (field: TField) =>
+    | {
+        isTouched?: boolean;
+      }
+    | undefined;
+};
+
+export function createFormValidationErrors({
+  fields,
+  form,
+}: {
+  fields?: Record<string, string | null | undefined>;
+  form?: string | null | undefined;
+}): FormValidationErrors {
+  const normalizedFields: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(fields ?? {})) {
+    if (typeof value === "string") {
+      normalizedFields[key] = value;
+    }
+  }
+
+  if (!form && Object.keys(normalizedFields).length === 0) {
+    return null;
+  }
+
+  return {
+    fields:
+      Object.keys(normalizedFields).length > 0 ? normalizedFields : undefined,
+    form: form ?? undefined,
+  };
+}
+
+export function getFormError(error: unknown): string | null {
+  if (typeof error === "string") {
+    return error;
+  }
+
+  if (
+    error &&
+    typeof error === "object" &&
+    "form" in error &&
+    typeof error.form === "string"
+  ) {
+    return error.form;
+  }
+
+  if (
+    error &&
+    typeof error === "object" &&
+    "message" in error &&
+    typeof error.message === "string"
+  ) {
+    return error.message;
+  }
+
+  return null;
+}
+
+export function getFieldError(errors: readonly unknown[]) {
+  return getFormError(errors[0]);
+}
+
+export function shouldValidateFieldOnChange<TField extends string>(
+  formApi: FieldValidationFormApi<TField>,
+  field: TField,
+) {
+  return (
+    formApi.state.submissionAttempts > 0 ||
+    Boolean(formApi.getFieldMeta(field)?.isTouched)
+  );
+}
diff --git a/src/routes/_auth.sign-in.tsx b/src/routes/_auth.sign-in.tsx
index d0352bb..600b057 100644
--- a/src/routes/_auth.sign-in.tsx
+++ b/src/routes/_auth.sign-in.tsx
@@ -85,7 +85,7 @@ function SignInPage() {
       } catch {
         formApi.setErrorMap({
           onSubmit: {
-            form: "We couldn't sign you in right now. Please try again.",
+            form: "Unable to sign in right now. Please try again.",
             fields: {},
           },
         });
diff --git a/src/routes/_auth.sign-up.tsx b/src/routes/_auth.sign-up.tsx
index c93e722..71f13db 100644
--- a/src/routes/_auth.sign-up.tsx
+++ b/src/routes/_auth.sign-up.tsx
@@ -44,7 +44,7 @@ export const Route = createFileRoute("/_auth/sign-up")({
 function getHelperText(isHostedMode: boolean) {
   return isHostedMode
     ? "Create your OpenSEO account."
-    : "Account creation isn't available right now.";
+    : "Account creation is only available when AUTH_MODE=hosted.";
 }
 
 function SignUpPage() {
@@ -85,7 +85,7 @@ function SignUpPage() {
         if (result.error) {
           formApi.setErrorMap({
             onSubmit: {
-              form: result.error.message || "We couldn't create your account.",
+              form: result.error.message || "Unable to create account.",
               fields: {},
             },
           });
@@ -99,7 +99,7 @@ function SignUpPage() {
       } catch {
         formApi.setErrorMap({
           onSubmit: {
-            form: "We couldn't create your account right now. Please try again.",
+            form: "Unable to create account right now. Please try again.",
             fields: {},
           },
         });
diff --git a/src/server/features/domain/services/DomainService.ts b/src/server/features/domain/services/DomainService.ts
index 54d7a0d..88c8ce3 100644
--- a/src/server/features/domain/services/DomainService.ts
+++ b/src/server/features/domain/services/DomainService.ts
@@ -1,13 +1,10 @@
-import {
-  normalizeDomainInput,
-  toRelativePath,
-  type DomainRankedKeywordItem,
-} from "@/server/lib/dataforseo";
+import { type DomainRankedKeywordItem } from "@/server/lib/dataforseo";
 import { sortBy } from "remeda";
 import { buildCacheKey, getCached, setCached } from "@/server/lib/r2-cache";
 import { z } from "zod";
 import type { BillingCustomerContext } from "@/server/billing/subscription";
 import { createDataforseoClient } from "@/server/lib/dataforseoClient";
+import { normalizeDomainInput, toRelativePath } from "@/server/lib/domainUtils";
 
 /** Domain overview data is refreshed every 12 hours. */
 const DOMAIN_OVERVIEW_TTL_SECONDS = 12 * 60 * 60;
diff --git a/src/server/lib/dataforseo.ts b/src/server/lib/dataforseo.ts
index de07bb1..b7e9dca 100644
--- a/src/server/lib/dataforseo.ts
+++ b/src/server/lib/dataforseo.ts
@@ -7,7 +7,6 @@ import {
   DataforseoLabsGoogleRankedKeywordsLiveRequestInfo,
 } from "dataforseo-client";
 import { env } from "cloudflare:workers";
-import { getDomain } from "tldts";
 import type { DataforseoApiResponse } from "@/server/lib/dataforseoCost";
 import { AppError } from "@/server/lib/errors";
 import {
@@ -50,6 +49,7 @@ function createAuthenticatedFetch() {
 }
 
 const API_BASE = "https://api.dataforseo.com";
+const MAX_DATAFORSEO_ERROR_PAYLOAD_LENGTH = 1600;
 
 function getLabsApi() {
   return new DataforseoLabsApi(API_BASE, { fetch: createAuthenticatedFetch() });
@@ -68,14 +68,23 @@ async function postDataforseo(
     body: JSON.stringify(payload),
   });
 
+  const rawText = await response.text();
+
   if (!response.ok) {
     throw new AppError(
       "INTERNAL_ERROR",
-      `DataForSEO HTTP ${response.status} on ${path}`,
+      `DataForSEO HTTP ${response.status} on ${path}. Response: ${formatDataforseoErrorPayload(rawText)}`,
     );
   }
 
-  return await response.json();
+  try {
+    return JSON.parse(rawText);
+  } catch {
+    throw new AppError(
+      "INTERNAL_ERROR",
+      `DataForSEO ${path} returned a non-JSON response. Response: ${formatDataforseoErrorPayload(rawText)}`,
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -87,14 +96,49 @@ async function postDataforseo(
  * Throws a descriptive error on failure. Returns the first task.
  */
 type DataforseoTaskLike = {
+  id?: string;
   status_code?: number;
   status_message?: string;
   path?: string[];
   cost?: number;
   result_count?: number | null;
+  data?: unknown;
   result?: DataforseoTask["result"];
 };
 
+function formatDataforseoErrorPayload(value: unknown): string {
+  const text =
+    typeof value === "string"
+      ? value
+      : (() => {
+          try {
+            return JSON.stringify(value);
+          } catch {
+            return String(value);
+          }
+        })();
+
+  return text.length > MAX_DATAFORSEO_ERROR_PAYLOAD_LENGTH
+    ? `${text.slice(0, MAX_DATAFORSEO_ERROR_PAYLOAD_LENGTH)}... [truncated]`
+    : text;
+}
+
+function getTaskDebugPayload(task: DataforseoTaskLike) {
+  return {
+    id: task.id ?? null,
+    status_code: task.status_code ?? null,
+    status_message: task.status_message ?? null,
+    path: task.path ?? null,
+    cost: task.cost ?? null,
+    result_count: task.result_count ?? null,
+    data: task.data ?? null,
+    result_length: Array.isArray(task.result) ? task.result.length : null,
+    result_preview: Array.isArray(task.result)
+      ? (task.result[0] ?? null)
+      : null,
+  };
+}
+
 function assertOk<T extends DataforseoTaskLike>(
   response: {
     status_code?: number;
@@ -127,9 +171,22 @@ function assertOk<T extends DataforseoTaskLike>(
 
   const parsedTask = successfulDataforseoTaskSchema.safeParse(task);
   if (!parsedTask.success) {
+    const issueSummary = parsedTask.error.issues
+      .slice(0, 5)
+      .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "task";
+        return `${path}: ${issue.message}`;
+      })
+      .join("; ");
+    const responseSummary = formatDataforseoErrorPayload({
+      status_code: response.status_code ?? null,
+      status_message: response.status_message ?? null,
+      task: getTaskDebugPayload(task),
+    });
+
     throw new AppError(
       "INTERNAL_ERROR",
-      "DataForSEO task missing billing metadata",
+      `DataForSEO task missing billing metadata (${issueSummary}). Response: ${responseSummary}`,
     );
   }
 
@@ -323,49 +380,3 @@ export async function fetchLiveSerpItemsRaw(
     billing: buildTaskBilling(task),
   };
 }
-
-// ---------------------------------------------------------------------------
-// Domain utility functions (unchanged)
-// ---------------------------------------------------------------------------
-
-export function toRelativePath(url: string | null | undefined): string | null {
-  if (!url) return null;
-
-  try {
-    const parsed = new URL(url);
-    return `${parsed.pathname}${parsed.search}` || "/";
-  } catch {
-    return null;
-  }
-}
-
-export function normalizeDomainInput(
-  input: string,
-  includeSubdomains: boolean,
-): string {
-  const trimmed = input.trim().toLowerCase();
-  if (!trimmed) {
-    throw new AppError("VALIDATION_ERROR", "Domain is required");
-  }
-
-  const withProtocol = /^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(trimmed)
-    ? trimmed
-    : `https://${trimmed}`;
-
-  let host: string;
-  try {
-    host = new URL(withProtocol).hostname.toLowerCase().replace(/^www\./, "");
-  } catch {
-    throw new AppError("VALIDATION_ERROR", "Domain is invalid");
-  }
-
-  if (!host) {
-    throw new AppError("VALIDATION_ERROR", "Domain is invalid");
-  }
-
-  if (includeSubdomains) {
-    return host;
-  }
-
-  return getDomain(host) ?? host;
-}
diff --git a/src/server/lib/domainUtils.ts b/src/server/lib/domainUtils.ts
new file mode 100644
index 0000000..4223f94
--- /dev/null
+++ b/src/server/lib/domainUtils.ts
@@ -0,0 +1,44 @@
+import { getDomain } from "tldts";
+import { AppError } from "@/server/lib/errors";
+
+export function toRelativePath(url: string | null | undefined): string | null {
+  if (!url) return null;
+
+  try {
+    const parsed = new URL(url);
+    return `${parsed.pathname}${parsed.search}` || "/";
+  } catch {
+    return null;
+  }
+}
+
+export function normalizeDomainInput(
+  input: string,
+  includeSubdomains: boolean,
+): string {
+  const trimmed = input.trim().toLowerCase();
+  if (!trimmed) {
+    throw new AppError("VALIDATION_ERROR", "Domain is required");
+  }
+
+  const withProtocol = /^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(trimmed)
+    ? trimmed
+    : `https://${trimmed}`;
+
+  let host: string;
+  try {
+    host = new URL(withProtocol).hostname.toLowerCase().replace(/^www\./, "");
+  } catch {
+    throw new AppError("VALIDATION_ERROR", "Domain is invalid");
+  }
+
+  if (!host) {
+    throw new AppError("VALIDATION_ERROR", "Domain is invalid");
+  }
+
+  if (includeSubdomains) {
+    return host;
+  }
+
+  return getDomain(host) ?? host;
+}
diff --git a/src/server/lib/errors.test.ts b/src/server/lib/errors.test.ts
new file mode 100644
index 0000000..361d2fe
--- /dev/null
+++ b/src/server/lib/errors.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { AppError, toClientError } from "@/server/lib/errors";
+
+describe("toClientError", () => {
+  it("sanitizes detailed internal error messages", () => {
+    const error = toClientError(
+      new AppError(
+        "INTERNAL_ERROR",
+        "DataForSEO task missing billing metadata (path: Invalid input). Response: {...}",
+      ),
+    );
+
+    expect(error.message).toBe("INTERNAL_ERROR");
+  });
+
+  it("keeps public error codes unchanged", () => {
+    const error = toClientError(new AppError("PAYMENT_REQUIRED"));
+
+    expect(error.message).toBe("PAYMENT_REQUIRED");
+  });
+});
diff --git a/src/server/lib/errors.ts b/src/server/lib/errors.ts
index be685d4..e6e4b0c 100644
--- a/src/server/lib/errors.ts
+++ b/src/server/lib/errors.ts
@@ -23,5 +23,6 @@ function toErrorCode(error: unknown): ErrorCode {
 }
 
 export function toClientError(error: unknown): Error {
-  return new Error(toErrorCode(error));
+  const appError = asAppError(error);
+  return new Error(appError?.code ?? toErrorCode(error));
 }