fix(preview): classify click lookup failures on the error type

A free function picked hidden/disabled/ambiguous and defaulted
ambiguous matches to 0. The policy now lives on
PreviewAutomationTargetNotFoundError.fromLookupFailure, and
ambiguous requires an explicit match count.

Author: gbarros-dev

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

@@ -2867,5 +2867,17 @@ describe("Preview automation diagnostics", () => {
     expect(hidden.message).not.toContain("secret");
     expect(disabled.message).not.toContain("secret");
     expect(ambiguous.message).not.toContain("secret");
+
+    const fromAmbiguous = PreviewManager.PreviewAutomationTargetNotFoundError.fromLookupFailure({
+      operation: "click",
+      tabId: "tab_1",
+      selectorKind: "locator",
+      selectorLength: selector.length,
+      failureKind: "ambiguous",
+      matchCount: 3,
+    });
+    expect(fromAmbiguous).toBeInstanceOf(PreviewManager.PreviewAutomationTargetAmbiguousError);
+    expect(fromAmbiguous.message).toContain("matched 3 elements");
+    expect(fromAmbiguous.message).not.toContain("secret");
   });
 });

apps/desktop/src/preview/Manager.ts

@@ -2994,8 +2994,12 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       | { invalidSelector: true; message: string }
       | {
           notFound: true;
-          failureKind: "missing" | "hidden" | "disabled" | "ambiguous";
-          matchCount?: number;
+          failureKind: "missing" | "hidden" | "disabled";
+        }
+      | {
+          notFound: true;
+          failureKind: "ambiguous";
+          matchCount: number;
         }
     >(
       tabId,
@@ -3041,12 +3045,13 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       });
     }
     if ("notFound" in point) {
-      return yield* raiseAutomationTargetLookupError({
+      return yield* PreviewAutomationTargetNotFoundError.fromLookupFailure({
         operation: "click",
         tabId,
         ...automationSelectorDiagnostics(input),
-        failureKind: point.failureKind,
-        ...(point.matchCount === undefined ? {} : { matchCount: point.matchCount }),
+        ...(point.failureKind === "ambiguous"
+          ? { failureKind: "ambiguous", matchCount: point.matchCount }
+          : { failureKind: point.failureKind }),
       });
     }
     return point;
@@ -3700,6 +3705,38 @@ export class PreviewAutomationTargetNotFoundError extends Schema.TaggedErrorClas
   "PreviewAutomationTargetNotFoundError",
   PreviewAutomationTargetLookupFields,
 ) {
+  static fromLookupFailure(
+    input: {
+      readonly operation: string;
+      readonly tabId: string;
+      readonly selectorKind: PreviewAutomationSelectorKind;
+      readonly selectorLength?: number;
+    } & (
+      | { readonly failureKind: "ambiguous"; readonly matchCount: number }
+      | { readonly failureKind?: "missing" | "hidden" | "disabled" }
+    ),
+  ) {
+    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,
+      });
+    }
+    return new PreviewAutomationTargetNotFoundError(shared);
+  }
+
   override get message(): string {
     const target = previewAutomationTargetLabel(this.selectorKind, this.selectorLength);
     return `Preview automation ${this.operation} could not find ${target} in tab ${this.tabId}`;
@@ -3739,35 +3776,6 @@ export class PreviewAutomationTargetAmbiguousError extends Schema.TaggedErrorCla
   }
 }
 
-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",
   {