fix(preview): name hidden, disabled, and ambiguous click failures

preview_click treated a hidden or disabled button as missing and leaked
the locator when it failed. Agents then spent turns guessing at chrome
they could already see.

Clicks now report hidden, disabled, or ambiguous targets without putting
the locator on the wire.

Author: gbarros-dev

apps/desktop/src/preview/Manager.test.ts

@@ -2839,4 +2839,33 @@ describe("Preview automation diagnostics", () => {
     expect(JSON.stringify(error)).not.toContain(selector);
     expect("locator" in error).toBe(false);
   });
+
+  it("names hidden, disabled, and ambiguous click failures without leaking the locator", () => {
+    const selector = "role=button[name='target-secret']";
+    const hidden = new PreviewManager.PreviewAutomationTargetHiddenError({
+      operation: "click",
+      tabId: "tab_1",
+      selectorKind: "locator",
+      selectorLength: selector.length,
+    });
+    const disabled = new PreviewManager.PreviewAutomationTargetDisabledError({
+      operation: "click",
+      tabId: "tab_1",
+      selectorKind: "locator",
+      selectorLength: selector.length,
+    });
+    const ambiguous = new PreviewManager.PreviewAutomationTargetAmbiguousError({
+      operation: "click",
+      tabId: "tab_1",
+      selectorKind: "locator",
+      selectorLength: selector.length,
+      matchCount: 3,
+    });
+    expect(hidden.message).toContain("not visible");
+    expect(disabled.message).toContain("disabled");
+    expect(ambiguous.message).toContain("matched 3 elements");
+    expect(hidden.message).not.toContain("secret");
+    expect(disabled.message).not.toContain("secret");
+    expect(ambiguous.message).not.toContain("secret");
+  });
 });

apps/desktop/src/preview/Manager.ts

@@ -2990,19 +2990,38 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       locator,
     );
     const point = yield* evaluateWithDebugger<
-      { x: number; y: number } | { invalidSelector: true; message: string } | { notFound: true }
+      | { x: number; y: number }
+      | { invalidSelector: true; message: string }
+      | {
+          notFound: true;
+          failureKind: "missing" | "hidden" | "disabled" | "ambiguous";
+          matchCount?: number;
+        }
     >(
       tabId,
       send,
       `(() => {
           try {
             const injected = globalThis.__t3PlaywrightInjected;
             const parsed = injected.parseSelector(${locatorJson});
-            const element = injected.querySelector(parsed, document, true);
-            if (!element) return { notFound: true };
+            let element;
+            try {
+              element = injected.querySelector(parsed, document, true);
+            } catch (error) {
+              const message = String(error);
+              if (message.toLowerCase().includes("strict mode")) {
+                const matches = injected.querySelectorAll
+                  ? injected.querySelectorAll(parsed, document)
+                  : [];
+                return { notFound: true, failureKind: "ambiguous", matchCount: matches.length || 2 };
+              }
+              throw error;
+            }
+            if (!element) return { notFound: true, failureKind: "missing" };
             const visible = injected.elementState(element, "visible");
             const enabled = injected.elementState(element, "enabled");
-            if (!visible.matches || !enabled.matches) return { notFound: true };
+            if (!visible.matches) return { notFound: true, failureKind: "hidden" };
+            if (!enabled.matches) return { notFound: true, failureKind: "disabled" };
             element.scrollIntoView({ block: "center", inline: "center" });
             const rect = element.getBoundingClientRect();
             return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
@@ -3022,10 +3041,12 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       });
     }
     if ("notFound" in point) {
-      return yield* new PreviewAutomationTargetNotFoundError({
+      return yield* raiseAutomationTargetLookupError({
         operation: "click",
         tabId,
         ...automationSelectorDiagnostics(input),
+        failureKind: point.failureKind,
+        ...(point.matchCount === undefined ? {} : { matchCount: point.matchCount }),
       });
     }
     return point;
@@ -3668,21 +3689,85 @@ export class PreviewAutomationEvaluationError extends Schema.TaggedErrorClass<Pr
   }
 }
 
+const PreviewAutomationTargetLookupFields = {
+  operation: Schema.String,
+  tabId: Schema.String,
+  selectorKind: PreviewAutomationSelectorKind,
+  selectorLength: Schema.optionalKey(Schema.Number),
+};
+
 export class PreviewAutomationTargetNotFoundError extends Schema.TaggedErrorClass<PreviewAutomationTargetNotFoundError>()(
   "PreviewAutomationTargetNotFoundError",
+  PreviewAutomationTargetLookupFields,
+) {
+  override get message(): string {
+    const target = previewAutomationTargetLabel(this.selectorKind, this.selectorLength);
+    return `Preview automation ${this.operation} could not find ${target} in tab ${this.tabId}`;
+  }
+}
+
+export class PreviewAutomationTargetHiddenError extends Schema.TaggedErrorClass<PreviewAutomationTargetHiddenError>()(
+  "PreviewAutomationTargetHiddenError",
+  PreviewAutomationTargetLookupFields,
+) {
+  override get message(): string {
+    const target = previewAutomationTargetLabel(this.selectorKind, this.selectorLength);
+    return `Preview automation ${this.operation} found ${target} in tab ${this.tabId}, but it is not visible`;
+  }
+}
+
+export class PreviewAutomationTargetDisabledError extends Schema.TaggedErrorClass<PreviewAutomationTargetDisabledError>()(
+  "PreviewAutomationTargetDisabledError",
+  PreviewAutomationTargetLookupFields,
+) {
+  override get message(): string {
+    const target = previewAutomationTargetLabel(this.selectorKind, this.selectorLength);
+    return `Preview automation ${this.operation} found ${target} in tab ${this.tabId}, but it is disabled`;
+  }
+}
+
+export class PreviewAutomationTargetAmbiguousError extends Schema.TaggedErrorClass<PreviewAutomationTargetAmbiguousError>()(
+  "PreviewAutomationTargetAmbiguousError",
   {
-    operation: Schema.String,
-    tabId: Schema.String,
-    selectorKind: PreviewAutomationSelectorKind,
-    selectorLength: Schema.optionalKey(Schema.Number),
+    ...PreviewAutomationTargetLookupFields,
+    matchCount: Schema.Number,
   },
 ) {
   override get message(): string {
     const target = previewAutomationTargetLabel(this.selectorKind, this.selectorLength);
-    return `Preview automation ${this.operation} could not find ${target} in tab ${this.tabId}`;
+    return `Preview automation ${this.operation} matched ${this.matchCount} elements for ${target} in tab ${this.tabId}`;
   }
 }
 
+const raiseAutomationTargetLookupError = (input: {
+  readonly operation: string;
+  readonly tabId: string;
+  readonly selectorKind: PreviewAutomationSelectorKind;
+  readonly selectorLength?: number;
+  readonly failureKind?: "missing" | "hidden" | "disabled" | "ambiguous";
+  readonly matchCount?: number;
+}) => {
+  const shared = {
+    operation: input.operation,
+    tabId: input.tabId,
+    selectorKind: input.selectorKind,
+    ...(input.selectorLength === undefined ? {} : { selectorLength: input.selectorLength }),
+  };
+  if (input.failureKind === "hidden") {
+    return new PreviewAutomationTargetHiddenError(shared);
+  }
+  if (input.failureKind === "disabled") {
+    return new PreviewAutomationTargetDisabledError(shared);
+  }
+  if (input.failureKind === "ambiguous") {
+    return new PreviewAutomationTargetAmbiguousError({
+      ...shared,
+      matchCount: input.matchCount ?? 0,
+    });
+  }
+  return new PreviewAutomationTargetNotFoundError(shared);
+};
+
 export class PreviewAutomationTargetNotEditableError extends Schema.TaggedErrorClass<PreviewAutomationTargetNotEditableError>()(
   "PreviewAutomationTargetNotEditableError",
   {
@@ -3798,6 +3883,9 @@ export const PreviewManagerError = Schema.Union([
   PreviewAutomationDebuggerAttachedError,
   PreviewAutomationEvaluationError,
   PreviewAutomationTargetNotFoundError,
+  PreviewAutomationTargetHiddenError,
+  PreviewAutomationTargetDisabledError,
+  PreviewAutomationTargetAmbiguousError,
   PreviewAutomationTargetNotEditableError,
   PreviewAutomationCoordinatesOutsideViewportError,
   PreviewAutomationInvalidSelectorError,

apps/web/src/components/preview/previewAutomationErrors.test.ts

@@ -0,0 +1,43 @@
+import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { PreviewAutomationOperationError } from "./previewAutomationErrors";
+
+describe("PreviewAutomationOperationError", () => {
+  const context = {
+    requestId: "request-1",
+    operation: "click" as const,
+    environmentId: EnvironmentId.make("environment-1"),
+    threadId: ThreadId.make("thread-1"),
+    tabId: "tab-1",
+  };
+
+  it("maps typed not-found failures to a visible/disabled/ambiguous reason", () => {
+    const hidden = PreviewAutomationOperationError.fromCause({
+      ...context,
+      cause: { _tag: "PreviewAutomationTargetHiddenError" },
+    });
+    const disabled = PreviewAutomationOperationError.fromCause({
+      ...context,
+      cause: { _tag: "PreviewAutomationTargetDisabledError" },
+    });
+    const ambiguous = PreviewAutomationOperationError.fromCause({
+      ...context,
+      cause: { _tag: "PreviewAutomationTargetAmbiguousError", matchCount: 3 },
+    });
+    const legacyHidden = PreviewAutomationOperationError.fromCause({
+      ...context,
+      cause: {
+        _tag: "PreviewAutomationTargetNotFoundError",
+        failureKind: "hidden",
+      },
+    });
+    expect(hidden.message).toContain("not visible");
+    expect(disabled.message).toContain("disabled");
+    expect(ambiguous.message).toContain("matched 3 elements");
+    expect(legacyHidden.message).toContain("not visible");
+    expect(hidden.message).not.toContain("secret");
+    expect(disabled.message).not.toContain("secret");
+    expect(ambiguous.message).not.toContain("secret");
+  });
+});

apps/web/src/components/preview/previewAutomationErrors.ts

@@ -134,6 +134,103 @@ export class PreviewAutomationTargetNotEditableHostError extends Schema.TaggedEr
   }
 }
 
+const PreviewAutomationTargetHostFields = {
+  requestId: TrimmedNonEmptyString,
+  operation: PreviewAutomationOperation,
+  environmentId: EnvironmentId,
+  threadId: ThreadId,
+  tabId: Schema.NullOr(PreviewTabId),
+  cause: Schema.Defect(),
+};
+
+const readTargetLookupKind = (
+  cause: unknown,
+): "missing" | "hidden" | "disabled" | "ambiguous" | null => {
+  if (typeof cause !== "object" || cause === null || !("_tag" in cause)) return null;
+  if (cause._tag === "PreviewAutomationTargetHiddenError") return "hidden";
+  if (cause._tag === "PreviewAutomationTargetDisabledError") return "disabled";
+  if (cause._tag === "PreviewAutomationTargetAmbiguousError") return "ambiguous";
+  if (cause._tag !== "PreviewAutomationTargetNotFoundError") return null;
+  if (
+    "failureKind" in cause &&
+    (cause.failureKind === "hidden" ||
+      cause.failureKind === "disabled" ||
+      cause.failureKind === "ambiguous")
+  ) {
+    return cause.failureKind;
+  }
+  return "missing";
+};
+
+const readAmbiguousMatchCount = (cause: unknown): number => {
+  if (
+    typeof cause === "object" &&
+    cause !== null &&
+    "matchCount" in cause &&
+    typeof cause.matchCount === "number" &&
+    Number.isInteger(cause.matchCount) &&
+    cause.matchCount >= 0
+  ) {
+    return cause.matchCount;
+  }
+  return 0;
+};
+
+export class PreviewAutomationTargetNotFoundHostError extends Schema.TaggedErrorClass<PreviewAutomationTargetNotFoundHostError>()(
+  "PreviewAutomationTargetNotFoundHostError",
+  PreviewAutomationTargetHostFields,
+) {
+  get responseTag() {
+    return "PreviewAutomationExecutionError" as const;
+  }
+
+  override get message(): string {
+    return `Preview automation ${this.operation} request ${this.requestId} could not find a target in tab ${this.tabId ?? "unassigned"}.`;
+  }
+}
+
+export class PreviewAutomationTargetHiddenHostError extends Schema.TaggedErrorClass<PreviewAutomationTargetHiddenHostError>()(
+  "PreviewAutomationTargetHiddenHostError",
+  PreviewAutomationTargetHostFields,
+) {
+  get responseTag() {
+    return "PreviewAutomationExecutionError" as const;
+  }
+
+  override get message(): string {
+    return `Preview automation ${this.operation} request ${this.requestId} found a target in tab ${this.tabId ?? "unassigned"}, but it is not visible.`;
+  }
+}
+
+export class PreviewAutomationTargetDisabledHostError extends Schema.TaggedErrorClass<PreviewAutomationTargetDisabledHostError>()(
+  "PreviewAutomationTargetDisabledHostError",
+  PreviewAutomationTargetHostFields,
+) {
+  get responseTag() {
+    return "PreviewAutomationExecutionError" as const;
+  }
+
+  override get message(): string {
+    return `Preview automation ${this.operation} request ${this.requestId} found a target in tab ${this.tabId ?? "unassigned"}, but it is disabled.`;
+  }
+}
+
+export class PreviewAutomationTargetAmbiguousHostError extends Schema.TaggedErrorClass<PreviewAutomationTargetAmbiguousHostError>()(
+  "PreviewAutomationTargetAmbiguousHostError",
+  {
+    ...PreviewAutomationTargetHostFields,
+    matchCount: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  },
+) {
+  get responseTag() {
+    return "PreviewAutomationExecutionError" as const;
+  }
+
+  override get message(): string {
+    return `Preview automation ${this.operation} request ${this.requestId} matched ${this.matchCount} elements in tab ${this.tabId ?? "unassigned"}.`;
+  }
+}
+
 const targetNotEditableDiagnostics = (
   cause: unknown,
 ): {
@@ -183,6 +280,26 @@ export class PreviewAutomationOperationError extends Schema.TaggedErrorClass<Pre
     input: PreviewAutomationOperationContext & { readonly cause: unknown },
   ): PreviewAutomationHostError {
     if (isPreviewAutomationHostError(input.cause)) return input.cause;
+    const lookupKind = readTargetLookupKind(input.cause);
+    if (lookupKind) {
+      const shared = {
+        requestId: input.requestId,
+        operation: input.operation,
+        environmentId: input.environmentId,
+        threadId: input.threadId,
+        tabId: input.tabId,
+        cause: input.cause,
+      };
+      if (lookupKind === "hidden") return new PreviewAutomationTargetHiddenHostError(shared);
+      if (lookupKind === "disabled") return new PreviewAutomationTargetDisabledHostError(shared);
+      if (lookupKind === "ambiguous") {
+        return new PreviewAutomationTargetAmbiguousHostError({
+          ...shared,
+          matchCount: readAmbiguousMatchCount(input.cause),
+        });
+      }
+      return new PreviewAutomationTargetNotFoundHostError(shared);
+    }
     const diagnostics = targetNotEditableDiagnostics(input.cause);
     return diagnostics
       ? new PreviewAutomationTargetNotEditableHostError({
@@ -211,6 +328,10 @@ export const PreviewAutomationHostError = Schema.Union([
   PreviewAutomationViewportTimeoutError,
   PreviewAutomationTargetUnavailableError,
   PreviewAutomationRecordingNotActiveError,
+  PreviewAutomationTargetNotFoundHostError,
+  PreviewAutomationTargetHiddenHostError,
+  PreviewAutomationTargetDisabledHostError,
+  PreviewAutomationTargetAmbiguousHostError,
   PreviewAutomationTargetNotEditableHostError,
   PreviewAutomationOperationError,
 ]);