The best way to control Claude Code, Codex and more from any computer or phone
fix(preview): explain invalid URLs and locators (#23396)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Nov 2, 2026 at 18:32 UTC
6e58094f740e5366dce4333a3a6320c43a278931
5 files changed
+57
-4
packages/contracts/src/preview.test.ts
+42
-1
@@ -1,7 +1,13 @@
1
import { Schema } from "effect";
2
import { describe, expect, it } from "vite-plus/test";
3
4
-import { PreviewAutomationHost, PreviewAutomationStatus } from "./previewAutomation.ts";
4
+import { EnvironmentId, ThreadId } from "./baseSchemas.ts";
5
+import {
6
+ PreviewAutomationHost,
7
+ PreviewAutomationInvalidSelectorError,
8
+ PreviewAutomationStatus,
9
+} from "./previewAutomation.ts";
10
+import { ProviderInstanceId } from "./providerInstance.ts";
11
12
const decodeAutomationHost = Schema.decodeUnknownSync(PreviewAutomationHost);
13
const decodeAutomationStatus = Schema.decodeUnknownSync(PreviewAutomationStatus);
@@ -42,3 +48,38 @@ describe("PreviewAutomationStatus", () => {
48
).toEqual({ width: 412, height: 915 });
49
});
50
});
51
+
52
+describe("PreviewAutomationInvalidSelectorError", () => {
53
+ const invalidSelector = (selectorKind: "locator" | "selector") =>
54
+ new PreviewAutomationInvalidSelectorError({
55
+ operation: "click",
56
+ environmentId: EnvironmentId.make("environment-1"),
57
+ threadId: ThreadId.make("thread-1"),
58
+ providerSessionId: "session-1",
59
+ providerInstanceId: ProviderInstanceId.make("claude"),
60
+ clientId: "desktop",
61
+ connectionId: "connection-1",
62
+ requestId: "request-1",
63
+ timeoutMs: 15_000,
64
+ remoteTag: "Error",
65
+ remoteMessageLength: 0,
66
+ cause: null,
67
+ selectorKind,
68
+ selectorLength: 42,
69
+ });
70
+
71
+ it("tells agents which locator forms are accepted and where CSS goes", () => {
72
+ const { message } = invalidSelector("locator");
73
+ expect(message).toContain("aria-ref=");
74
+ expect(message).toMatch(/role/);
75
+ expect(message).toMatch(/text/);
76
+ expect(message).toMatch(/CSS[^.]*\bselector\b/);
77
+ });
78
+
79
+ it("points an invalid CSS selector at the locator alternative", () => {
80
+ const { message } = invalidSelector("selector");
81
+ expect(message).toMatch(/CSS/);
82
+ expect(message).toMatch(/\blocator\b/);
83
+ expect(message).toContain("aria-ref=");
84
+ });
85
+});
packages/contracts/src/preview.ts
+1
-1
@@ -376,7 +376,7 @@ export class PreviewInvalidUrlError extends Schema.TaggedError<PreviewInvalidUrl
376
) {
377
override get message() {
378
const protocol = this.protocol === undefined ? "" : `: ${this.protocol}`;
379
- return `Invalid preview URL (${this.reason}${protocol}; input length ${this.inputLength}).`;
379
+ return `Invalid preview URL (${this.reason}${protocol}; input length ${this.inputLength}). Use an http(s) URL or a schemeless host such as localhost:5173. With preview_open, omit url when creating a new tab to open a blank tab.`;
380
}
381
}
382
packages/contracts/src/previewAutomation.ts
+5
-1
@@ -840,7 +840,11 @@ export class PreviewAutomationInvalidSelectorError extends Schema.TaggedError<Pr
840
if (this.staleRef)
841
return "This element ref is stale. Navigation, dialogs, and new snapshots replace refs; take a fresh snapshot and use its refs.";
842
if (this.selectorKind !== undefined && this.selectorLength !== undefined) {
843
- return `Preview automation ${this.operation} received an invalid ${this.selectorKind} (${this.selectorLength} characters).`;
843
+ const guidance =
844
+ this.selectorKind === "locator"
845
+ ? "Use aria-ref=<ref> from the latest snapshot or a Playwright role/text selector; put CSS in selector."
846
+ : "selector takes CSS; use locator for aria-ref=<ref>, role, or text targets.";
847
+ return `Preview automation ${this.operation} received an invalid ${this.selectorKind} (${this.selectorLength} characters). ${guidance}`;
848
}
849
return `Preview automation ${this.operation} received an invalid selector.`;
850
}
packages/shared/src/preview.test.ts
+8
@@ -149,6 +149,14 @@ describe("resolveSearchUrlTemplate", () => {
149
});
150
151
describe("normalizePreviewUrl", () => {
152
+ it("tells agents how to open a blank tab and which URLs are accepted", () => {
153
+ expect(() => normalizePreviewUrl("about:blank")).toThrow(
154
+ /preview_open, omit url when creating a new tab[^.]*blank tab/i,
155
+ );
156
+ expect(() => normalizePreviewUrl("about:blank")).toThrow(/http\(s\)/i);
157
+ expect(() => normalizePreviewUrl("about:blank")).toThrow(/schemeless host/i);
158
+ });
159
+
160
it("rejects unparseable input without retaining credentials or tokens", () => {
161
const rawUrl = "https://user:password@example.com:bad/path?access_token=secret#fragment";
162
try {
packages/shared/src/preview.ts
+1
-1
@@ -66,7 +66,7 @@ export class PreviewUrlNormalizationError extends Schema.TaggedError<PreviewUrlN
66
) {
67
override get message(): string {
68
const protocol = this.protocol === undefined ? "" : `: ${this.protocol}`;
69
- return `Invalid preview URL (${this.reason}${protocol}; input length ${this.inputLength}).`;
69
+ return `Invalid preview URL (${this.reason}${protocol}; input length ${this.inputLength}). Use an http(s) URL or a schemeless host such as localhost:5173. With preview_open, omit url when creating a new tab to open a blank tab.`;
70
}
71
}
72