pingdotgg · juliusmarminge · Jul 20, 2026 · Jul 13, 2026 · Jul 13, 2026 · Jul 13, 2026
diff --git a/apps/web/src/components/preview/PreviewView.test.tsx b/apps/web/src/components/preview/PreviewView.test.tsx
@@ -0,0 +1,194 @@
+import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { renderToStaticMarkup } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const mocks = vi.hoisted(() => ({
+ navigate: vi.fn(async (_tabId: string, _url: string): Promise<void> => undefined),
+ rememberPreviewUrl: vi.fn(),
+ readPreparedConnection: vi.fn(() => ({ httpBaseUrl: "http://172.25.85.75:3773" })),
+ submittedUrl: null as ((url: string) => void) | null,
+ emptyStateUrl: null as ((url: string) => void) | null,
+ showEmptyState: false,
+}));
+
+vi.mock("~/state/session", () => ({
+ readPreparedConnection: mocks.readPreparedConnection,
+}));
+
+vi.mock("~/composerDraftStore", () => ({
+ useComposerDraftStore: (
+ select: (store: { addPreviewAnnotation: () => void; addImage: () => void }) => unknown,
+ ) => select({ addPreviewAnnotation: vi.fn(), addImage: vi.fn() }),
+}));
+
+vi.mock("~/lib/previewAnnotation", () => ({
+ previewAnnotationScreenshotFile: vi.fn(),
+}));
+
+vi.mock("~/localApi", () => ({
+ ensureLocalApi: vi.fn(),
+}));
+
+vi.mock("~/previewStateStore", () => ({
+ rememberPreviewUrl: mocks.rememberPreviewUrl,
+ updatePreviewServerSnapshot: vi.fn(),
+ useThreadPreviewState: () => ({
+ activeTabId: "tab-1",
+ desktopByTabId: {
+ "tab-1": {
+ canGoBack: false,
+ canGoForward: false,
+ loading: false,
+ zoomFactor: 1,
+ controller: "none",
+ },
+ },
+ recentlySeenUrls: [],
+ sessions: mocks.showEmptyState
+ ? {}
+ : {
+ "tab-1": {
+ threadId: "thread-1",
+ tabId: "tab-1",
+ navStatus: {
+ _tag: "Success",
+ url: "http://example.com/",
+ title: "Example",
+ },
+ canGoBack: false,
+ canGoForward: false,
+ updatedAt: "2026-07-13T00:00:00.000Z",
+ },
+ },
+ }),
+}));
+
+vi.mock("~/state/environments", () => ({
+ useEnvironment: () => ({ label: "WSL" }),
+ useEnvironmentHttpBaseUrl: () => "http://172.25.85.75:3773",
+}));
+
+vi.mock("~/state/preview", () => ({
+ previewEnvironment: { open: {}, resize: {} },
+}));
+
+vi.mock("~/state/use-atom-command", () => ({
+ useAtomCommand: () => vi.fn(),
+}));
+
+vi.mock("~/browser/browserRecording", () => ({
+ startBrowserRecording: vi.fn(),
+ stopBrowserRecording: vi.fn(),
+ useActiveBrowserRecordingTabId: () => null,
+}));
+
+vi.mock("~/browser/browserSurfaceStore", () => ({
+ useBrowserSurfaceStore: (
+ select: (state: { byTabId: Record<string, { rect?: unknown }> }) => unknown,
+ ) => select({ byTabId: {} }),
+}));
+
+vi.mock("~/components/ui/toast", () => ({
+ stackedThreadToast: vi.fn(),
+ toastManager: { add: vi.fn() },
+}));
+
+vi.mock("./previewBridge", () => ({
+ previewBridge: { navigate: mocks.navigate },
+}));
+
+vi.mock("./PreviewChromeRow", () => ({
+ PreviewChromeRow: (props: { onSubmit: (url: string) => void }) => {
+ mocks.submittedUrl = props.onSubmit;
+ return null;
+ },
+}));
+
+vi.mock("./PreviewEmptyState", () => ({
+ PreviewEmptyState: (props: { onOpenUrl: (url: string) => void }) => {
+ mocks.emptyStateUrl = props.onOpenUrl;
+ return null;
+ },
+}));
+vi.mock("./PreviewMoreMenu", () => ({ PreviewMoreMenu: () => null }));
+vi.mock("./PreviewUnreachable", () => ({ PreviewUnreachable: () => null }));
+vi.mock("./ZoomIndicator", () => ({ ZoomIndicator: () => null }));
+vi.mock("./AgentBrowserCursor", () => ({ AgentBrowserCursor: () => null }));
+vi.mock("~/browser/BrowserSurfaceSlot", () => ({ BrowserSurfaceSlot: () => null }));
+vi.mock("./useLoadingProgress", () => ({ useLoadingProgress: () => 0 }));
+vi.mock("./usePreviewSession", () => ({ usePreviewSession: vi.fn() }));
+
+import { PreviewView } from "./PreviewView";
+
+describe("PreviewView navigation", () => {
+ beforeEach(() => {
+ mocks.navigate.mockClear();
+ mocks.rememberPreviewUrl.mockClear();
+ mocks.readPreparedConnection.mockClear();
+ mocks.submittedUrl = null;
+ mocks.emptyStateUrl = null;
+ mocks.showEmptyState = false;
+ });
+
+ it.each([
+ [
+ "https://localhost:8000/dashboard?mode=test#top",
+ "https://localhost:8000/dashboard?mode=test#top",
+ ],
+ ["localhost:5173/app", "http://localhost:5173/app"],
+ ])("preserves a direct localhost URL in a WSL environment", async (submitted, expected) => {
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.submittedUrl).not.toBeNull();
+ mocks.submittedUrl?.(submitted);
+
+ await vi.waitFor(() => expect(mocks.navigate).toHaveBeenCalledWith("tab-1", expected));
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ expected,
+ );
+ });
+
+ it("maps an empty-state localhost server onto the WSL host", async () => {
+ mocks.showEmptyState = true;
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.emptyStateUrl).not.toBeNull();
+ mocks.emptyStateUrl?.("http://localhost:5173/app?mode=test#top");
+
+ await vi.waitFor(() =>
+ expect(mocks.navigate).toHaveBeenCalledWith(
+ "tab-1",
+ "http://172.25.85.75:5173/app?mode=test#top",
+ ),
+ );
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ "http://172.25.85.75:5173/app?mode=test#top",
+ );
+ });
+});
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
@@ -7,6 +7,7 @@ import {
  type PreviewViewportSetting,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { normalizePreviewUrl } from "@t3tools/shared/preview";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useComposerDraftStore } from "~/composerDraftStore";
@@ -112,27 +113,44 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  tabId ? (state.byTabId[tabId]?.rect ?? null) : null,
  );
 
+ const navigateToResolvedUrl = useCallback(
+ async (resolvedUrl: string) => {
+ if (tabId && previewBridge) {
+ // Drive the webview imperatively; `usePreviewBridge` mirrors the
+ // resolved URL back to the server so other clients stay in sync.
+ await previewBridge.navigate(tabId, resolvedUrl);
+ rememberPreviewUrl(threadRef, resolvedUrl);
+ } else {
+ await openPreviewSession({
+ openPreview: open,
+ threadRef,
+ url: resolvedUrl,
+ });
+ }
+ },
+ [open, tabId, threadRef],
+ );
+
  const handleSubmitUrl = useCallback(
  async (next: string) => {
  try {
- const resolvedUrl = resolveDiscoveredServerUrl(threadRef.environmentId, next);
- if (tabId && previewBridge) {
- // Drive the webview imperatively; `usePreviewBridge` mirrors the
- // resolved URL back to the server so other clients stay in sync.
- await previewBridge.navigate(tabId, resolvedUrl);
- rememberPreviewUrl(threadRef, resolvedUrl);
- } else {
- await openPreviewSession({
- openPreview: open,
- threadRef,
- url: resolvedUrl,
- });
- }
+ await navigateToResolvedUrl(normalizePreviewUrl(next));
  } catch {
  // Server-side `failed` event renders the unreachable view.
  }
  },
- [open, tabId, threadRef],
+ [navigateToResolvedUrl],
+ );
+
+ const handleOpenServerUrl = useCallback(
+ async (next: string) => {
+ try {
+ await navigateToResolvedUrl(resolveDiscoveredServerUrl(threadRef.environmentId, next));
+ } catch {
+ // Server-side `failed` event renders the unreachable view.
+ }
+ },
+ [navigateToResolvedUrl, threadRef.environmentId],
  );
 
  const handleRefresh = useCallback(() => {
@@ -613,7 +631,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  environmentId={threadRef.environmentId}
  configuredUrls={configuredUrls}
  recentlySeenUrls={previewState.recentlySeenUrls}
- onOpenUrl={(next) => void handleSubmitUrl(next)}
+ onOpenUrl={(next) => void handleOpenServerUrl(next)}
  />
  ) : null}
  {snapshot && desktopOverlay ? (

diff --git a/apps/web/src/components/preview/PreviewView.test.tsx b/apps/web/src/components/preview/PreviewView.test.tsx
@@ -0,0 +1,194 @@
+import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { renderToStaticMarkup } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const mocks = vi.hoisted(() => ({
+ navigate: vi.fn(async (_tabId: string, _url: string): Promise<void> => undefined),
+ rememberPreviewUrl: vi.fn(),
+ readPreparedConnection: vi.fn(() => ({ httpBaseUrl: "http://172.25.85.75:3773" })),
+ submittedUrl: null as ((url: string) => void) | null,
+ emptyStateUrl: null as ((url: string) => void) | null,
+ showEmptyState: false,
+}));
+
+vi.mock("~/state/session", () => ({
+ readPreparedConnection: mocks.readPreparedConnection,
+}));
+
+vi.mock("~/composerDraftStore", () => ({
+ useComposerDraftStore: (
+ select: (store: { addPreviewAnnotation: () => void; addImage: () => void }) => unknown,
+ ) => select({ addPreviewAnnotation: vi.fn(), addImage: vi.fn() }),
+}));
+
+vi.mock("~/lib/previewAnnotation", () => ({
+ previewAnnotationScreenshotFile: vi.fn(),
+}));
+
+vi.mock("~/localApi", () => ({
+ ensureLocalApi: vi.fn(),
+}));
+
+vi.mock("~/previewStateStore", () => ({
+ rememberPreviewUrl: mocks.rememberPreviewUrl,
+ updatePreviewServerSnapshot: vi.fn(),
+ useThreadPreviewState: () => ({
+ activeTabId: "tab-1",
+ desktopByTabId: {
+ "tab-1": {
+ canGoBack: false,
+ canGoForward: false,
+ loading: false,
+ zoomFactor: 1,
+ controller: "none",
+ },
+ },
+ recentlySeenUrls: [],
+ sessions: mocks.showEmptyState
+ ? {}
+ : {
+ "tab-1": {
+ threadId: "thread-1",
+ tabId: "tab-1",
+ navStatus: {
+ _tag: "Success",
+ url: "http://example.com/",
+ title: "Example",
+ },
+ canGoBack: false,
+ canGoForward: false,
+ updatedAt: "2026-07-13T00:00:00.000Z",
+ },
+ },
+ }),
+}));
+
+vi.mock("~/state/environments", () => ({
+ useEnvironment: () => ({ label: "WSL" }),
+ useEnvironmentHttpBaseUrl: () => "http://172.25.85.75:3773",
+}));
+
+vi.mock("~/state/preview", () => ({
+ previewEnvironment: { open: {}, resize: {} },
+}));
+
+vi.mock("~/state/use-atom-command", () => ({
+ useAtomCommand: () => vi.fn(),
+}));
+
+vi.mock("~/browser/browserRecording", () => ({
+ startBrowserRecording: vi.fn(),
+ stopBrowserRecording: vi.fn(),
+ useActiveBrowserRecordingTabId: () => null,
+}));
+
+vi.mock("~/browser/browserSurfaceStore", () => ({
+ useBrowserSurfaceStore: (
+ select: (state: { byTabId: Record<string, { rect?: unknown }> }) => unknown,
+ ) => select({ byTabId: {} }),
+}));
+
+vi.mock("~/components/ui/toast", () => ({
+ stackedThreadToast: vi.fn(),
+ toastManager: { add: vi.fn() },
+}));
+
+vi.mock("./previewBridge", () => ({
+ previewBridge: { navigate: mocks.navigate },
+}));
+
+vi.mock("./PreviewChromeRow", () => ({
+ PreviewChromeRow: (props: { onSubmit: (url: string) => void }) => {
+ mocks.submittedUrl = props.onSubmit;
+ return null;
+ },
+}));
+
+vi.mock("./PreviewEmptyState", () => ({
+ PreviewEmptyState: (props: { onOpenUrl: (url: string) => void }) => {
+ mocks.emptyStateUrl = props.onOpenUrl;
+ return null;
+ },
+}));
+vi.mock("./PreviewMoreMenu", () => ({ PreviewMoreMenu: () => null }));
+vi.mock("./PreviewUnreachable", () => ({ PreviewUnreachable: () => null }));
+vi.mock("./ZoomIndicator", () => ({ ZoomIndicator: () => null }));
+vi.mock("./AgentBrowserCursor", () => ({ AgentBrowserCursor: () => null }));
+vi.mock("~/browser/BrowserSurfaceSlot", () => ({ BrowserSurfaceSlot: () => null }));
+vi.mock("./useLoadingProgress", () => ({ useLoadingProgress: () => 0 }));
+vi.mock("./usePreviewSession", () => ({ usePreviewSession: vi.fn() }));
+
+import { PreviewView } from "./PreviewView";
+
+describe("PreviewView navigation", () => {
+ beforeEach(() => {
+ mocks.navigate.mockClear();
+ mocks.rememberPreviewUrl.mockClear();
+ mocks.readPreparedConnection.mockClear();
+ mocks.submittedUrl = null;
+ mocks.emptyStateUrl = null;
+ mocks.showEmptyState = false;
+ });
+
+ it.each([
+ [
+ "https://localhost:8000/dashboard?mode=test#top",
+ "https://localhost:8000/dashboard?mode=test#top",
+ ],
+ ["localhost:5173/app", "http://localhost:5173/app"],
+ ])("preserves a direct localhost URL in a WSL environment", async (submitted, expected) => {
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.submittedUrl).not.toBeNull();
+ mocks.submittedUrl?.(submitted);
+
+ await vi.waitFor(() => expect(mocks.navigate).toHaveBeenCalledWith("tab-1", expected));
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ expected,
+ );
+ });
+
+ it("maps an empty-state localhost server onto the WSL host", async () => {
+ mocks.showEmptyState = true;
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.emptyStateUrl).not.toBeNull();
+ mocks.emptyStateUrl?.("http://localhost:5173/app?mode=test#top");
+
+ await vi.waitFor(() =>
+ expect(mocks.navigate).toHaveBeenCalledWith(
+ "tab-1",
+ "http://172.25.85.75:5173/app?mode=test#top",
+ ),
+ );
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ "http://172.25.85.75:5173/app?mode=test#top",
+ );
+ });
+});
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
@@ -7,6 +7,7 @@ import {
  type PreviewViewportSetting,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { normalizePreviewUrl } from "@t3tools/shared/preview";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useComposerDraftStore } from "~/composerDraftStore";
@@ -112,27 +113,44 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  tabId ? (state.byTabId[tabId]?.rect ?? null) : null,
  );
 
+ const navigateToResolvedUrl = useCallback(
+ async (resolvedUrl: string) => {
+ if (tabId && previewBridge) {
+ // Drive the webview imperatively; `usePreviewBridge` mirrors the
+ // resolved URL back to the server so other clients stay in sync.
+ await previewBridge.navigate(tabId, resolvedUrl);
+ rememberPreviewUrl(threadRef, resolvedUrl);
+ } else {
+ await openPreviewSession({
+ openPreview: open,
+ threadRef,
+ url: resolvedUrl,
+ });
+ }
+ },
+ [open, tabId, threadRef],
+ );
+
  const handleSubmitUrl = useCallback(
  async (next: string) => {
  try {
- const resolvedUrl = resolveDiscoveredServerUrl(threadRef.environmentId, next);
- if (tabId && previewBridge) {
- // Drive the webview imperatively; `usePreviewBridge` mirrors the
- // resolved URL back to the server so other clients stay in sync.
- await previewBridge.navigate(tabId, resolvedUrl);
- rememberPreviewUrl(threadRef, resolvedUrl);
- } else {
- await openPreviewSession({
- openPreview: open,
- threadRef,
- url: resolvedUrl,
- });
- }
+ await navigateToResolvedUrl(normalizePreviewUrl(next));
  } catch {
  // Server-side `failed` event renders the unreachable view.
  }
  },
- [open, tabId, threadRef],
+ [navigateToResolvedUrl],
+ );
+
+ const handleOpenServerUrl = useCallback(
+ async (next: string) => {
+ try {
+ await navigateToResolvedUrl(resolveDiscoveredServerUrl(threadRef.environmentId, next));
+ } catch {
+ // Server-side `failed` event renders the unreachable view.
+ }
+ },
+ [navigateToResolvedUrl, threadRef.environmentId],
  );
 
  const handleRefresh = useCallback(() => {
@@ -613,7 +631,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  environmentId={threadRef.environmentId}
  configuredUrls={configuredUrls}
  recentlySeenUrls={previewState.recentlySeenUrls}
- onOpenUrl={(next) => void handleSubmitUrl(next)}
+ onOpenUrl={(next) => void handleOpenServerUrl(next)}
  />
  ) : null}
  {snapshot && desktopOverlay ? (

diff --git a/apps/web/src/components/preview/PreviewView.test.tsx b/apps/web/src/components/preview/PreviewView.test.tsx
@@ -0,0 +1,194 @@
+import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { renderToStaticMarkup } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const mocks = vi.hoisted(() => ({
+ navigate: vi.fn(async (_tabId: string, _url: string): Promise<void> => undefined),
+ rememberPreviewUrl: vi.fn(),
+ readPreparedConnection: vi.fn(() => ({ httpBaseUrl: "http://172.25.85.75:3773" })),
+ submittedUrl: null as ((url: string) => void) | null,
+ emptyStateUrl: null as ((url: string) => void) | null,
+ showEmptyState: false,
+}));
+
+vi.mock("~/state/session", () => ({
+ readPreparedConnection: mocks.readPreparedConnection,
+}));
+
+vi.mock("~/composerDraftStore", () => ({
+ useComposerDraftStore: (
+ select: (store: { addPreviewAnnotation: () => void; addImage: () => void }) => unknown,
+ ) => select({ addPreviewAnnotation: vi.fn(), addImage: vi.fn() }),
+}));
+
+vi.mock("~/lib/previewAnnotation", () => ({
+ previewAnnotationScreenshotFile: vi.fn(),
+}));
+
+vi.mock("~/localApi", () => ({
+ ensureLocalApi: vi.fn(),
+}));
+
+vi.mock("~/previewStateStore", () => ({
+ rememberPreviewUrl: mocks.rememberPreviewUrl,
+ updatePreviewServerSnapshot: vi.fn(),
+ useThreadPreviewState: () => ({
+ activeTabId: "tab-1",
+ desktopByTabId: {
+ "tab-1": {
+ canGoBack: false,
+ canGoForward: false,
+ loading: false,
+ zoomFactor: 1,
+ controller: "none",
+ },
+ },
+ recentlySeenUrls: [],
+ sessions: mocks.showEmptyState
+ ? {}
+ : {
+ "tab-1": {
+ threadId: "thread-1",
+ tabId: "tab-1",
+ navStatus: {
+ _tag: "Success",
+ url: "http://example.com/",
+ title: "Example",
+ },
+ canGoBack: false,
+ canGoForward: false,
+ updatedAt: "2026-07-13T00:00:00.000Z",
+ },
+ },
+ }),
+}));
+
+vi.mock("~/state/environments", () => ({
+ useEnvironment: () => ({ label: "WSL" }),
+ useEnvironmentHttpBaseUrl: () => "http://172.25.85.75:3773",
+}));
+
+vi.mock("~/state/preview", () => ({
+ previewEnvironment: { open: {}, resize: {} },
+}));
+
+vi.mock("~/state/use-atom-command", () => ({
+ useAtomCommand: () => vi.fn(),
+}));
+
+vi.mock("~/browser/browserRecording", () => ({
+ startBrowserRecording: vi.fn(),
+ stopBrowserRecording: vi.fn(),
+ useActiveBrowserRecordingTabId: () => null,
+}));
+
+vi.mock("~/browser/browserSurfaceStore", () => ({
+ useBrowserSurfaceStore: (
+ select: (state: { byTabId: Record<string, { rect?: unknown }> }) => unknown,
+ ) => select({ byTabId: {} }),
+}));
+
+vi.mock("~/components/ui/toast", () => ({
+ stackedThreadToast: vi.fn(),
+ toastManager: { add: vi.fn() },
+}));
+
+vi.mock("./previewBridge", () => ({
+ previewBridge: { navigate: mocks.navigate },
+}));
+
+vi.mock("./PreviewChromeRow", () => ({
+ PreviewChromeRow: (props: { onSubmit: (url: string) => void }) => {
+ mocks.submittedUrl = props.onSubmit;
+ return null;
+ },
+}));
+
+vi.mock("./PreviewEmptyState", () => ({
+ PreviewEmptyState: (props: { onOpenUrl: (url: string) => void }) => {
+ mocks.emptyStateUrl = props.onOpenUrl;
+ return null;
+ },
+}));
+vi.mock("./PreviewMoreMenu", () => ({ PreviewMoreMenu: () => null }));
+vi.mock("./PreviewUnreachable", () => ({ PreviewUnreachable: () => null }));
+vi.mock("./ZoomIndicator", () => ({ ZoomIndicator: () => null }));
+vi.mock("./AgentBrowserCursor", () => ({ AgentBrowserCursor: () => null }));
+vi.mock("~/browser/BrowserSurfaceSlot", () => ({ BrowserSurfaceSlot: () => null }));
+vi.mock("./useLoadingProgress", () => ({ useLoadingProgress: () => 0 }));
+vi.mock("./usePreviewSession", () => ({ usePreviewSession: vi.fn() }));
+
+import { PreviewView } from "./PreviewView";
+
+describe("PreviewView navigation", () => {
+ beforeEach(() => {
+ mocks.navigate.mockClear();
+ mocks.rememberPreviewUrl.mockClear();
+ mocks.readPreparedConnection.mockClear();
+ mocks.submittedUrl = null;
+ mocks.emptyStateUrl = null;
+ mocks.showEmptyState = false;
+ });
+
+ it.each([
+ [
+ "https://localhost:8000/dashboard?mode=test#top",
+ "https://localhost:8000/dashboard?mode=test#top",
+ ],
+ ["localhost:5173/app", "http://localhost:5173/app"],
+ ])("preserves a direct localhost URL in a WSL environment", async (submitted, expected) => {
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.submittedUrl).not.toBeNull();
+ mocks.submittedUrl?.(submitted);
+
+ await vi.waitFor(() => expect(mocks.navigate).toHaveBeenCalledWith("tab-1", expected));
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ expected,
+ );
+ });
+
+ it("maps an empty-state localhost server onto the WSL host", async () => {
+ mocks.showEmptyState = true;
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.emptyStateUrl).not.toBeNull();
+ mocks.emptyStateUrl?.("http://localhost:5173/app?mode=test#top");
+
+ await vi.waitFor(() =>
+ expect(mocks.navigate).toHaveBeenCalledWith(
+ "tab-1",
+ "http://172.25.85.75:5173/app?mode=test#top",
+ ),
+ );
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ "http://172.25.85.75:5173/app?mode=test#top",
+ );
+ });
+});
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
@@ -7,6 +7,7 @@ import {
  type PreviewViewportSetting,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { normalizePreviewUrl } from "@t3tools/shared/preview";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useComposerDraftStore } from "~/composerDraftStore";
@@ -112,27 +113,44 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  tabId ? (state.byTabId[tabId]?.rect ?? null) : null,
  );
 
+ const navigateToResolvedUrl = useCallback(
+ async (resolvedUrl: string) => {
+ if (tabId && previewBridge) {
+ // Drive the webview imperatively; `usePreviewBridge` mirrors the
+ // resolved URL back to the server so other clients stay in sync.
+ await previewBridge.navigate(tabId, resolvedUrl);
+ rememberPreviewUrl(threadRef, resolvedUrl);
+ } else {
+ await openPreviewSession({
+ openPreview: open,
+ threadRef,
+ url: resolvedUrl,
+ });
+ }
+ },
+ [open, tabId, threadRef],
+ );
+
  const handleSubmitUrl = useCallback(
  async (next: string) => {
  try {
- const resolvedUrl = resolveDiscoveredServerUrl(threadRef.environmentId, next);
- if (tabId && previewBridge) {
- // Drive the webview imperatively; `usePreviewBridge` mirrors the
- // resolved URL back to the server so other clients stay in sync.
- await previewBridge.navigate(tabId, resolvedUrl);
- rememberPreviewUrl(threadRef, resolvedUrl);
- } else {
- await openPreviewSession({
- openPreview: open,
- threadRef,
- url: resolvedUrl,
- });
- }
+ await navigateToResolvedUrl(normalizePreviewUrl(next));
  } catch {
  // Server-side `failed` event renders the unreachable view.
  }
  },
- [open, tabId, threadRef],
+ [navigateToResolvedUrl],
+ );
+
+ const handleOpenServerUrl = useCallback(
+ async (next: string) => {
+ try {
+ await navigateToResolvedUrl(resolveDiscoveredServerUrl(threadRef.environmentId, next));
+ } catch {
+ // Server-side `failed` event renders the unreachable view.
+ }
+ },
+ [navigateToResolvedUrl, threadRef.environmentId],
  );
 
  const handleRefresh = useCallback(() => {
@@ -613,7 +631,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  environmentId={threadRef.environmentId}
  configuredUrls={configuredUrls}
  recentlySeenUrls={previewState.recentlySeenUrls}
- onOpenUrl={(next) => void handleSubmitUrl(next)}
+ onOpenUrl={(next) => void handleOpenServerUrl(next)}
  />
  ) : null}
  {snapshot && desktopOverlay ? (

diff --git a/apps/web/src/components/preview/PreviewView.test.tsx b/apps/web/src/components/preview/PreviewView.test.tsx
@@ -0,0 +1,194 @@
+import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { renderToStaticMarkup } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const mocks = vi.hoisted(() => ({
+ navigate: vi.fn(async (_tabId: string, _url: string): Promise<void> => undefined),
+ rememberPreviewUrl: vi.fn(),
+ readPreparedConnection: vi.fn(() => ({ httpBaseUrl: "http://172.25.85.75:3773" })),
+ submittedUrl: null as ((url: string) => void) | null,
+ emptyStateUrl: null as ((url: string) => void) | null,
+ showEmptyState: false,
+}));
+
+vi.mock("~/state/session", () => ({
+ readPreparedConnection: mocks.readPreparedConnection,
+}));
+
+vi.mock("~/composerDraftStore", () => ({
+ useComposerDraftStore: (
+ select: (store: { addPreviewAnnotation: () => void; addImage: () => void }) => unknown,
+ ) => select({ addPreviewAnnotation: vi.fn(), addImage: vi.fn() }),
+}));
+
+vi.mock("~/lib/previewAnnotation", () => ({
+ previewAnnotationScreenshotFile: vi.fn(),
+}));
+
+vi.mock("~/localApi", () => ({
+ ensureLocalApi: vi.fn(),
+}));
+
+vi.mock("~/previewStateStore", () => ({
+ rememberPreviewUrl: mocks.rememberPreviewUrl,
+ updatePreviewServerSnapshot: vi.fn(),
+ useThreadPreviewState: () => ({
+ activeTabId: "tab-1",
+ desktopByTabId: {
+ "tab-1": {
+ canGoBack: false,
+ canGoForward: false,
+ loading: false,
+ zoomFactor: 1,
+ controller: "none",
+ },
+ },
+ recentlySeenUrls: [],
+ sessions: mocks.showEmptyState
+ ? {}
+ : {
+ "tab-1": {
+ threadId: "thread-1",
+ tabId: "tab-1",
+ navStatus: {
+ _tag: "Success",
+ url: "http://example.com/",
+ title: "Example",
+ },
+ canGoBack: false,
+ canGoForward: false,
+ updatedAt: "2026-07-13T00:00:00.000Z",
+ },
+ },
+ }),
+}));
+
+vi.mock("~/state/environments", () => ({
+ useEnvironment: () => ({ label: "WSL" }),
+ useEnvironmentHttpBaseUrl: () => "http://172.25.85.75:3773",
+}));
+
+vi.mock("~/state/preview", () => ({
+ previewEnvironment: { open: {}, resize: {} },
+}));
+
+vi.mock("~/state/use-atom-command", () => ({
+ useAtomCommand: () => vi.fn(),
+}));
+
+vi.mock("~/browser/browserRecording", () => ({
+ startBrowserRecording: vi.fn(),
+ stopBrowserRecording: vi.fn(),
+ useActiveBrowserRecordingTabId: () => null,
+}));
+
+vi.mock("~/browser/browserSurfaceStore", () => ({
+ useBrowserSurfaceStore: (
+ select: (state: { byTabId: Record<string, { rect?: unknown }> }) => unknown,
+ ) => select({ byTabId: {} }),
+}));
+
+vi.mock("~/components/ui/toast", () => ({
+ stackedThreadToast: vi.fn(),
+ toastManager: { add: vi.fn() },
+}));
+
+vi.mock("./previewBridge", () => ({
+ previewBridge: { navigate: mocks.navigate },
+}));
+
+vi.mock("./PreviewChromeRow", () => ({
+ PreviewChromeRow: (props: { onSubmit: (url: string) => void }) => {
+ mocks.submittedUrl = props.onSubmit;
+ return null;
+ },
+}));
+
+vi.mock("./PreviewEmptyState", () => ({
+ PreviewEmptyState: (props: { onOpenUrl: (url: string) => void }) => {
+ mocks.emptyStateUrl = props.onOpenUrl;
+ return null;
+ },
+}));
+vi.mock("./PreviewMoreMenu", () => ({ PreviewMoreMenu: () => null }));
+vi.mock("./PreviewUnreachable", () => ({ PreviewUnreachable: () => null }));
+vi.mock("./ZoomIndicator", () => ({ ZoomIndicator: () => null }));
+vi.mock("./AgentBrowserCursor", () => ({ AgentBrowserCursor: () => null }));
+vi.mock("~/browser/BrowserSurfaceSlot", () => ({ BrowserSurfaceSlot: () => null }));
+vi.mock("./useLoadingProgress", () => ({ useLoadingProgress: () => 0 }));
+vi.mock("./usePreviewSession", () => ({ usePreviewSession: vi.fn() }));
+
+import { PreviewView } from "./PreviewView";
+
+describe("PreviewView navigation", () => {
+ beforeEach(() => {
+ mocks.navigate.mockClear();
+ mocks.rememberPreviewUrl.mockClear();
+ mocks.readPreparedConnection.mockClear();
+ mocks.submittedUrl = null;
+ mocks.emptyStateUrl = null;
+ mocks.showEmptyState = false;
+ });
+
+ it.each([
+ [
+ "https://localhost:8000/dashboard?mode=test#top",
+ "https://localhost:8000/dashboard?mode=test#top",
+ ],
+ ["localhost:5173/app", "http://localhost:5173/app"],
+ ])("preserves a direct localhost URL in a WSL environment", async (submitted, expected) => {
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.submittedUrl).not.toBeNull();
+ mocks.submittedUrl?.(submitted);
+
+ await vi.waitFor(() => expect(mocks.navigate).toHaveBeenCalledWith("tab-1", expected));
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ expected,
+ );
+ });
+
+ it("maps an empty-state localhost server onto the WSL host", async () => {
+ mocks.showEmptyState = true;
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.emptyStateUrl).not.toBeNull();
+ mocks.emptyStateUrl?.("http://localhost:5173/app?mode=test#top");
+
+ await vi.waitFor(() =>
+ expect(mocks.navigate).toHaveBeenCalledWith(
+ "tab-1",
+ "http://172.25.85.75:5173/app?mode=test#top",
+ ),
+ );
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ "http://172.25.85.75:5173/app?mode=test#top",
+ );
+ });
+});
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
@@ -7,6 +7,7 @@ import {
  type PreviewViewportSetting,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { normalizePreviewUrl } from "@t3tools/shared/preview";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useComposerDraftStore } from "~/composerDraftStore";
@@ -112,27 +113,44 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  tabId ? (state.byTabId[tabId]?.rect ?? null) : null,
  );
 
+ const navigateToResolvedUrl = useCallback(
+ async (resolvedUrl: string) => {
+ if (tabId && previewBridge) {
+ // Drive the webview imperatively; `usePreviewBridge` mirrors the
+ // resolved URL back to the server so other clients stay in sync.
+ await previewBridge.navigate(tabId, resolvedUrl);
+ rememberPreviewUrl(threadRef, resolvedUrl);
+ } else {
+ await openPreviewSession({
+ openPreview: open,
+ threadRef,
+ url: resolvedUrl,
+ });
+ }
+ },
+ [open, tabId, threadRef],
+ );
+
  const handleSubmitUrl = useCallback(
  async (next: string) => {
  try {
- const resolvedUrl = resolveDiscoveredServerUrl(threadRef.environmentId, next);
- if (tabId && previewBridge) {
- // Drive the webview imperatively; `usePreviewBridge` mirrors the
- // resolved URL back to the server so other clients stay in sync.
- await previewBridge.navigate(tabId, resolvedUrl);
- rememberPreviewUrl(threadRef, resolvedUrl);
- } else {
- await openPreviewSession({
- openPreview: open,
- threadRef,
- url: resolvedUrl,
- });
- }
+ await navigateToResolvedUrl(normalizePreviewUrl(next));
  } catch {
  // Server-side `failed` event renders the unreachable view.
  }
  },
- [open, tabId, threadRef],
+ [navigateToResolvedUrl],
+ );
+
+ const handleOpenServerUrl = useCallback(
+ async (next: string) => {
+ try {
+ await navigateToResolvedUrl(resolveDiscoveredServerUrl(threadRef.environmentId, next));
+ } catch {
+ // Server-side `failed` event renders the unreachable view.
+ }
+ },
+ [navigateToResolvedUrl, threadRef.environmentId],
  );
 
  const handleRefresh = useCallback(() => {
@@ -613,7 +631,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  environmentId={threadRef.environmentId}
  configuredUrls={configuredUrls}
  recentlySeenUrls={previewState.recentlySeenUrls}
- onOpenUrl={(next) => void handleSubmitUrl(next)}
+ onOpenUrl={(next) => void handleOpenServerUrl(next)}
  />
  ) : null}
  {snapshot && desktopOverlay ? (

diff --git a/apps/web/src/components/preview/PreviewView.test.tsx b/apps/web/src/components/preview/PreviewView.test.tsx
@@ -0,0 +1,194 @@
+import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { renderToStaticMarkup } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const mocks = vi.hoisted(() => ({
+ navigate: vi.fn(async (_tabId: string, _url: string): Promise<void> => undefined),
+ rememberPreviewUrl: vi.fn(),
+ readPreparedConnection: vi.fn(() => ({ httpBaseUrl: "http://172.25.85.75:3773" })),
+ submittedUrl: null as ((url: string) => void) | null,
+ emptyStateUrl: null as ((url: string) => void) | null,
+ showEmptyState: false,
+}));
+
+vi.mock("~/state/session", () => ({
+ readPreparedConnection: mocks.readPreparedConnection,
+}));
+
+vi.mock("~/composerDraftStore", () => ({
+ useComposerDraftStore: (
+ select: (store: { addPreviewAnnotation: () => void; addImage: () => void }) => unknown,
+ ) => select({ addPreviewAnnotation: vi.fn(), addImage: vi.fn() }),
+}));
+
+vi.mock("~/lib/previewAnnotation", () => ({
+ previewAnnotationScreenshotFile: vi.fn(),
+}));
+
+vi.mock("~/localApi", () => ({
+ ensureLocalApi: vi.fn(),
+}));
+
+vi.mock("~/previewStateStore", () => ({
+ rememberPreviewUrl: mocks.rememberPreviewUrl,
+ updatePreviewServerSnapshot: vi.fn(),
+ useThreadPreviewState: () => ({
+ activeTabId: "tab-1",
+ desktopByTabId: {
+ "tab-1": {
+ canGoBack: false,
+ canGoForward: false,
+ loading: false,
+ zoomFactor: 1,
+ controller: "none",
+ },
+ },
+ recentlySeenUrls: [],
+ sessions: mocks.showEmptyState
+ ? {}
+ : {
+ "tab-1": {
+ threadId: "thread-1",
+ tabId: "tab-1",
+ navStatus: {
+ _tag: "Success",
+ url: "http://example.com/",
+ title: "Example",
+ },
+ canGoBack: false,
+ canGoForward: false,
+ updatedAt: "2026-07-13T00:00:00.000Z",
+ },
+ },
+ }),
+}));
+
+vi.mock("~/state/environments", () => ({
+ useEnvironment: () => ({ label: "WSL" }),
+ useEnvironmentHttpBaseUrl: () => "http://172.25.85.75:3773",
+}));
+
+vi.mock("~/state/preview", () => ({
+ previewEnvironment: { open: {}, resize: {} },
+}));
+
+vi.mock("~/state/use-atom-command", () => ({
+ useAtomCommand: () => vi.fn(),
+}));
+
+vi.mock("~/browser/browserRecording", () => ({
+ startBrowserRecording: vi.fn(),
+ stopBrowserRecording: vi.fn(),
+ useActiveBrowserRecordingTabId: () => null,
+}));
+
+vi.mock("~/browser/browserSurfaceStore", () => ({
+ useBrowserSurfaceStore: (
+ select: (state: { byTabId: Record<string, { rect?: unknown }> }) => unknown,
+ ) => select({ byTabId: {} }),
+}));
+
+vi.mock("~/components/ui/toast", () => ({
+ stackedThreadToast: vi.fn(),
+ toastManager: { add: vi.fn() },
+}));
+
+vi.mock("./previewBridge", () => ({
+ previewBridge: { navigate: mocks.navigate },
+}));
+
+vi.mock("./PreviewChromeRow", () => ({
+ PreviewChromeRow: (props: { onSubmit: (url: string) => void }) => {
+ mocks.submittedUrl = props.onSubmit;
+ return null;
+ },
+}));
+
+vi.mock("./PreviewEmptyState", () => ({
+ PreviewEmptyState: (props: { onOpenUrl: (url: string) => void }) => {
+ mocks.emptyStateUrl = props.onOpenUrl;
+ return null;
+ },
+}));
+vi.mock("./PreviewMoreMenu", () => ({ PreviewMoreMenu: () => null }));
+vi.mock("./PreviewUnreachable", () => ({ PreviewUnreachable: () => null }));
+vi.mock("./ZoomIndicator", () => ({ ZoomIndicator: () => null }));
+vi.mock("./AgentBrowserCursor", () => ({ AgentBrowserCursor: () => null }));
+vi.mock("~/browser/BrowserSurfaceSlot", () => ({ BrowserSurfaceSlot: () => null }));
+vi.mock("./useLoadingProgress", () => ({ useLoadingProgress: () => 0 }));
+vi.mock("./usePreviewSession", () => ({ usePreviewSession: vi.fn() }));
+
+import { PreviewView } from "./PreviewView";
+
+describe("PreviewView navigation", () => {
+ beforeEach(() => {
+ mocks.navigate.mockClear();
+ mocks.rememberPreviewUrl.mockClear();
+ mocks.readPreparedConnection.mockClear();
+ mocks.submittedUrl = null;
+ mocks.emptyStateUrl = null;
+ mocks.showEmptyState = false;
+ });
+
+ it.each([
+ [
+ "https://localhost:8000/dashboard?mode=test#top",
+ "https://localhost:8000/dashboard?mode=test#top",
+ ],
+ ["localhost:5173/app", "http://localhost:5173/app"],
+ ])("preserves a direct localhost URL in a WSL environment", async (submitted, expected) => {
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.submittedUrl).not.toBeNull();
+ mocks.submittedUrl?.(submitted);
+
+ await vi.waitFor(() => expect(mocks.navigate).toHaveBeenCalledWith("tab-1", expected));
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ expected,
+ );
+ });
+
+ it("maps an empty-state localhost server onto the WSL host", async () => {
+ mocks.showEmptyState = true;
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.emptyStateUrl).not.toBeNull();
+ mocks.emptyStateUrl?.("http://localhost:5173/app?mode=test#top");
+
+ await vi.waitFor(() =>
+ expect(mocks.navigate).toHaveBeenCalledWith(
+ "tab-1",
+ "http://172.25.85.75:5173/app?mode=test#top",
+ ),
+ );
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ "http://172.25.85.75:5173/app?mode=test#top",
+ );
+ });
+});
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
@@ -7,6 +7,7 @@ import {
  type PreviewViewportSetting,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { normalizePreviewUrl } from "@t3tools/shared/preview";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useComposerDraftStore } from "~/composerDraftStore";
@@ -112,27 +113,44 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  tabId ? (state.byTabId[tabId]?.rect ?? null) : null,
  );
 
+ const navigateToResolvedUrl = useCallback(
+ async (resolvedUrl: string) => {
+ if (tabId && previewBridge) {
+ // Drive the webview imperatively; `usePreviewBridge` mirrors the
+ // resolved URL back to the server so other clients stay in sync.
+ await previewBridge.navigate(tabId, resolvedUrl);
+ rememberPreviewUrl(threadRef, resolvedUrl);
+ } else {
+ await openPreviewSession({
+ openPreview: open,
+ threadRef,
+ url: resolvedUrl,
+ });
+ }
+ },
+ [open, tabId, threadRef],
+ );
+
  const handleSubmitUrl = useCallback(
  async (next: string) => {
  try {
- const resolvedUrl = resolveDiscoveredServerUrl(threadRef.environmentId, next);
- if (tabId && previewBridge) {
- // Drive the webview imperatively; `usePreviewBridge` mirrors the
- // resolved URL back to the server so other clients stay in sync.
- await previewBridge.navigate(tabId, resolvedUrl);
- rememberPreviewUrl(threadRef, resolvedUrl);
- } else {
- await openPreviewSession({
- openPreview: open,
- threadRef,
- url: resolvedUrl,
- });
- }
+ await navigateToResolvedUrl(normalizePreviewUrl(next));
  } catch {
  // Server-side `failed` event renders the unreachable view.
  }
  },
- [open, tabId, threadRef],
+ [navigateToResolvedUrl],
+ );
+
+ const handleOpenServerUrl = useCallback(
+ async (next: string) => {
+ try {
+ await navigateToResolvedUrl(resolveDiscoveredServerUrl(threadRef.environmentId, next));
+ } catch {
+ // Server-side `failed` event renders the unreachable view.
+ }
+ },
+ [navigateToResolvedUrl, threadRef.environmentId],
  );
 
  const handleRefresh = useCallback(() => {
@@ -613,7 +631,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  environmentId={threadRef.environmentId}
  configuredUrls={configuredUrls}
  recentlySeenUrls={previewState.recentlySeenUrls}
- onOpenUrl={(next) => void handleSubmitUrl(next)}
+ onOpenUrl={(next) => void handleOpenServerUrl(next)}
  />
  ) : null}
  {snapshot && desktopOverlay ? (

diff --git a/apps/web/src/components/preview/PreviewView.test.tsx b/apps/web/src/components/preview/PreviewView.test.tsx
@@ -0,0 +1,194 @@
+import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { renderToStaticMarkup } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const mocks = vi.hoisted(() => ({
+ navigate: vi.fn(async (_tabId: string, _url: string): Promise<void> => undefined),
+ rememberPreviewUrl: vi.fn(),
+ readPreparedConnection: vi.fn(() => ({ httpBaseUrl: "http://172.25.85.75:3773" })),
+ submittedUrl: null as ((url: string) => void) | null,
+ emptyStateUrl: null as ((url: string) => void) | null,
+ showEmptyState: false,
+}));
+
+vi.mock("~/state/session", () => ({
+ readPreparedConnection: mocks.readPreparedConnection,
+}));
+
+vi.mock("~/composerDraftStore", () => ({
+ useComposerDraftStore: (
+ select: (store: { addPreviewAnnotation: () => void; addImage: () => void }) => unknown,
+ ) => select({ addPreviewAnnotation: vi.fn(), addImage: vi.fn() }),
+}));
+
+vi.mock("~/lib/previewAnnotation", () => ({
+ previewAnnotationScreenshotFile: vi.fn(),
+}));
+
+vi.mock("~/localApi", () => ({
+ ensureLocalApi: vi.fn(),
+}));
+
+vi.mock("~/previewStateStore", () => ({
+ rememberPreviewUrl: mocks.rememberPreviewUrl,
+ updatePreviewServerSnapshot: vi.fn(),
+ useThreadPreviewState: () => ({
+ activeTabId: "tab-1",
+ desktopByTabId: {
+ "tab-1": {
+ canGoBack: false,
+ canGoForward: false,
+ loading: false,
+ zoomFactor: 1,
+ controller: "none",
+ },
+ },
+ recentlySeenUrls: [],
+ sessions: mocks.showEmptyState
+ ? {}
+ : {
+ "tab-1": {
+ threadId: "thread-1",
+ tabId: "tab-1",
+ navStatus: {
+ _tag: "Success",
+ url: "http://example.com/",
+ title: "Example",
+ },
+ canGoBack: false,
+ canGoForward: false,
+ updatedAt: "2026-07-13T00:00:00.000Z",
+ },
+ },
+ }),
+}));
+
+vi.mock("~/state/environments", () => ({
+ useEnvironment: () => ({ label: "WSL" }),
+ useEnvironmentHttpBaseUrl: () => "http://172.25.85.75:3773",
+}));
+
+vi.mock("~/state/preview", () => ({
+ previewEnvironment: { open: {}, resize: {} },
+}));
+
+vi.mock("~/state/use-atom-command", () => ({
+ useAtomCommand: () => vi.fn(),
+}));
+
+vi.mock("~/browser/browserRecording", () => ({
+ startBrowserRecording: vi.fn(),
+ stopBrowserRecording: vi.fn(),
+ useActiveBrowserRecordingTabId: () => null,
+}));
+
+vi.mock("~/browser/browserSurfaceStore", () => ({
+ useBrowserSurfaceStore: (
+ select: (state: { byTabId: Record<string, { rect?: unknown }> }) => unknown,
+ ) => select({ byTabId: {} }),
+}));
+
+vi.mock("~/components/ui/toast", () => ({
+ stackedThreadToast: vi.fn(),
+ toastManager: { add: vi.fn() },
+}));
+
+vi.mock("./previewBridge", () => ({
+ previewBridge: { navigate: mocks.navigate },
+}));
+
+vi.mock("./PreviewChromeRow", () => ({
+ PreviewChromeRow: (props: { onSubmit: (url: string) => void }) => {
+ mocks.submittedUrl = props.onSubmit;
+ return null;
+ },
+}));
+
+vi.mock("./PreviewEmptyState", () => ({
+ PreviewEmptyState: (props: { onOpenUrl: (url: string) => void }) => {
+ mocks.emptyStateUrl = props.onOpenUrl;
+ return null;
+ },
+}));
+vi.mock("./PreviewMoreMenu", () => ({ PreviewMoreMenu: () => null }));
+vi.mock("./PreviewUnreachable", () => ({ PreviewUnreachable: () => null }));
+vi.mock("./ZoomIndicator", () => ({ ZoomIndicator: () => null }));
+vi.mock("./AgentBrowserCursor", () => ({ AgentBrowserCursor: () => null }));
+vi.mock("~/browser/BrowserSurfaceSlot", () => ({ BrowserSurfaceSlot: () => null }));
+vi.mock("./useLoadingProgress", () => ({ useLoadingProgress: () => 0 }));
+vi.mock("./usePreviewSession", () => ({ usePreviewSession: vi.fn() }));
+
+import { PreviewView } from "./PreviewView";
+
+describe("PreviewView navigation", () => {
+ beforeEach(() => {
+ mocks.navigate.mockClear();
+ mocks.rememberPreviewUrl.mockClear();
+ mocks.readPreparedConnection.mockClear();
+ mocks.submittedUrl = null;
+ mocks.emptyStateUrl = null;
+ mocks.showEmptyState = false;
+ });
+
+ it.each([
+ [
+ "https://localhost:8000/dashboard?mode=test#top",
+ "https://localhost:8000/dashboard?mode=test#top",
+ ],
+ ["localhost:5173/app", "http://localhost:5173/app"],
+ ])("preserves a direct localhost URL in a WSL environment", async (submitted, expected) => {
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.submittedUrl).not.toBeNull();
+ mocks.submittedUrl?.(submitted);
+
+ await vi.waitFor(() => expect(mocks.navigate).toHaveBeenCalledWith("tab-1", expected));
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ expected,
+ );
+ });
+
+ it("maps an empty-state localhost server onto the WSL host", async () => {
+ mocks.showEmptyState = true;
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.emptyStateUrl).not.toBeNull();
+ mocks.emptyStateUrl?.("http://localhost:5173/app?mode=test#top");
+
+ await vi.waitFor(() =>
+ expect(mocks.navigate).toHaveBeenCalledWith(
+ "tab-1",
+ "http://172.25.85.75:5173/app?mode=test#top",
+ ),
+ );
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ "http://172.25.85.75:5173/app?mode=test#top",
+ );
+ });
+});
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
@@ -7,6 +7,7 @@ import {
  type PreviewViewportSetting,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { normalizePreviewUrl } from "@t3tools/shared/preview";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useComposerDraftStore } from "~/composerDraftStore";
@@ -112,27 +113,44 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  tabId ? (state.byTabId[tabId]?.rect ?? null) : null,
  );
 
+ const navigateToResolvedUrl = useCallback(
+ async (resolvedUrl: string) => {
+ if (tabId && previewBridge) {
+ // Drive the webview imperatively; `usePreviewBridge` mirrors the
+ // resolved URL back to the server so other clients stay in sync.
+ await previewBridge.navigate(tabId, resolvedUrl);
+ rememberPreviewUrl(threadRef, resolvedUrl);
+ } else {
+ await openPreviewSession({
+ openPreview: open,
+ threadRef,
+ url: resolvedUrl,
+ });
+ }
+ },
+ [open, tabId, threadRef],
+ );
+
  const handleSubmitUrl = useCallback(
  async (next: string) => {
  try {
- const resolvedUrl = resolveDiscoveredServerUrl(threadRef.environmentId, next);
- if (tabId && previewBridge) {
- // Drive the webview imperatively; `usePreviewBridge` mirrors the
- // resolved URL back to the server so other clients stay in sync.
- await previewBridge.navigate(tabId, resolvedUrl);
- rememberPreviewUrl(threadRef, resolvedUrl);
- } else {
- await openPreviewSession({
- openPreview: open,
- threadRef,
- url: resolvedUrl,
- });
- }
+ await navigateToResolvedUrl(normalizePreviewUrl(next));
  } catch {
  // Server-side `failed` event renders the unreachable view.
  }
  },
- [open, tabId, threadRef],
+ [navigateToResolvedUrl],
+ );
+
+ const handleOpenServerUrl = useCallback(
+ async (next: string) => {
+ try {
+ await navigateToResolvedUrl(resolveDiscoveredServerUrl(threadRef.environmentId, next));
+ } catch {
+ // Server-side `failed` event renders the unreachable view.
+ }
+ },
+ [navigateToResolvedUrl, threadRef.environmentId],
  );
 
  const handleRefresh = useCallback(() => {
@@ -613,7 +631,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  environmentId={threadRef.environmentId}
  configuredUrls={configuredUrls}
  recentlySeenUrls={previewState.recentlySeenUrls}
- onOpenUrl={(next) => void handleSubmitUrl(next)}
+ onOpenUrl={(next) => void handleOpenServerUrl(next)}
  />
  ) : null}
  {snapshot && desktopOverlay ? (

diff --git a/apps/web/src/components/preview/PreviewView.test.tsx b/apps/web/src/components/preview/PreviewView.test.tsx
@@ -0,0 +1,194 @@
+import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { renderToStaticMarkup } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const mocks = vi.hoisted(() => ({
+ navigate: vi.fn(async (_tabId: string, _url: string): Promise<void> => undefined),
+ rememberPreviewUrl: vi.fn(),
+ readPreparedConnection: vi.fn(() => ({ httpBaseUrl: "http://172.25.85.75:3773" })),
+ submittedUrl: null as ((url: string) => void) | null,
+ emptyStateUrl: null as ((url: string) => void) | null,
+ showEmptyState: false,
+}));
+
+vi.mock("~/state/session", () => ({
+ readPreparedConnection: mocks.readPreparedConnection,
+}));
+
+vi.mock("~/composerDraftStore", () => ({
+ useComposerDraftStore: (
+ select: (store: { addPreviewAnnotation: () => void; addImage: () => void }) => unknown,
+ ) => select({ addPreviewAnnotation: vi.fn(), addImage: vi.fn() }),
+}));
+
+vi.mock("~/lib/previewAnnotation", () => ({
+ previewAnnotationScreenshotFile: vi.fn(),
+}));
+
+vi.mock("~/localApi", () => ({
+ ensureLocalApi: vi.fn(),
+}));
+
+vi.mock("~/previewStateStore", () => ({
+ rememberPreviewUrl: mocks.rememberPreviewUrl,
+ updatePreviewServerSnapshot: vi.fn(),
+ useThreadPreviewState: () => ({
+ activeTabId: "tab-1",
+ desktopByTabId: {
+ "tab-1": {
+ canGoBack: false,
+ canGoForward: false,
+ loading: false,
+ zoomFactor: 1,
+ controller: "none",
+ },
+ },
+ recentlySeenUrls: [],
+ sessions: mocks.showEmptyState
+ ? {}
+ : {
+ "tab-1": {
+ threadId: "thread-1",
+ tabId: "tab-1",
+ navStatus: {
+ _tag: "Success",
+ url: "http://example.com/",
+ title: "Example",
+ },
+ canGoBack: false,
+ canGoForward: false,
+ updatedAt: "2026-07-13T00:00:00.000Z",
+ },
+ },
+ }),
+}));
+
+vi.mock("~/state/environments", () => ({
+ useEnvironment: () => ({ label: "WSL" }),
+ useEnvironmentHttpBaseUrl: () => "http://172.25.85.75:3773",
+}));
+
+vi.mock("~/state/preview", () => ({
+ previewEnvironment: { open: {}, resize: {} },
+}));
+
+vi.mock("~/state/use-atom-command", () => ({
+ useAtomCommand: () => vi.fn(),
+}));
+
+vi.mock("~/browser/browserRecording", () => ({
+ startBrowserRecording: vi.fn(),
+ stopBrowserRecording: vi.fn(),
+ useActiveBrowserRecordingTabId: () => null,
+}));
+
+vi.mock("~/browser/browserSurfaceStore", () => ({
+ useBrowserSurfaceStore: (
+ select: (state: { byTabId: Record<string, { rect?: unknown }> }) => unknown,
+ ) => select({ byTabId: {} }),
+}));
+
+vi.mock("~/components/ui/toast", () => ({
+ stackedThreadToast: vi.fn(),
+ toastManager: { add: vi.fn() },
+}));
+
+vi.mock("./previewBridge", () => ({
+ previewBridge: { navigate: mocks.navigate },
+}));
+
+vi.mock("./PreviewChromeRow", () => ({
+ PreviewChromeRow: (props: { onSubmit: (url: string) => void }) => {
+ mocks.submittedUrl = props.onSubmit;
+ return null;
+ },
+}));
+
+vi.mock("./PreviewEmptyState", () => ({
+ PreviewEmptyState: (props: { onOpenUrl: (url: string) => void }) => {
+ mocks.emptyStateUrl = props.onOpenUrl;
+ return null;
+ },
+}));
+vi.mock("./PreviewMoreMenu", () => ({ PreviewMoreMenu: () => null }));
+vi.mock("./PreviewUnreachable", () => ({ PreviewUnreachable: () => null }));
+vi.mock("./ZoomIndicator", () => ({ ZoomIndicator: () => null }));
+vi.mock("./AgentBrowserCursor", () => ({ AgentBrowserCursor: () => null }));
+vi.mock("~/browser/BrowserSurfaceSlot", () => ({ BrowserSurfaceSlot: () => null }));
+vi.mock("./useLoadingProgress", () => ({ useLoadingProgress: () => 0 }));
+vi.mock("./usePreviewSession", () => ({ usePreviewSession: vi.fn() }));
+
+import { PreviewView } from "./PreviewView";
+
+describe("PreviewView navigation", () => {
+ beforeEach(() => {
+ mocks.navigate.mockClear();
+ mocks.rememberPreviewUrl.mockClear();
+ mocks.readPreparedConnection.mockClear();
+ mocks.submittedUrl = null;
+ mocks.emptyStateUrl = null;
+ mocks.showEmptyState = false;
+ });
+
+ it.each([
+ [
+ "https://localhost:8000/dashboard?mode=test#top",
+ "https://localhost:8000/dashboard?mode=test#top",
+ ],
+ ["localhost:5173/app", "http://localhost:5173/app"],
+ ])("preserves a direct localhost URL in a WSL environment", async (submitted, expected) => {
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.submittedUrl).not.toBeNull();
+ mocks.submittedUrl?.(submitted);
+
+ await vi.waitFor(() => expect(mocks.navigate).toHaveBeenCalledWith("tab-1", expected));
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ expected,
+ );
+ });
+
+ it("maps an empty-state localhost server onto the WSL host", async () => {
+ mocks.showEmptyState = true;
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.emptyStateUrl).not.toBeNull();
+ mocks.emptyStateUrl?.("http://localhost:5173/app?mode=test#top");
+
+ await vi.waitFor(() =>
+ expect(mocks.navigate).toHaveBeenCalledWith(
+ "tab-1",
+ "http://172.25.85.75:5173/app?mode=test#top",
+ ),
+ );
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ "http://172.25.85.75:5173/app?mode=test#top",
+ );
+ });
+});
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
@@ -7,6 +7,7 @@ import {
  type PreviewViewportSetting,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { normalizePreviewUrl } from "@t3tools/shared/preview";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useComposerDraftStore } from "~/composerDraftStore";
@@ -112,27 +113,44 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  tabId ? (state.byTabId[tabId]?.rect ?? null) : null,
  );
 
+ const navigateToResolvedUrl = useCallback(
+ async (resolvedUrl: string) => {
+ if (tabId && previewBridge) {
+ // Drive the webview imperatively; `usePreviewBridge` mirrors the
+ // resolved URL back to the server so other clients stay in sync.
+ await previewBridge.navigate(tabId, resolvedUrl);
+ rememberPreviewUrl(threadRef, resolvedUrl);
+ } else {
+ await openPreviewSession({
+ openPreview: open,
+ threadRef,
+ url: resolvedUrl,
+ });
+ }
+ },
+ [open, tabId, threadRef],
+ );
+
  const handleSubmitUrl = useCallback(
  async (next: string) => {
  try {
- const resolvedUrl = resolveDiscoveredServerUrl(threadRef.environmentId, next);
- if (tabId && previewBridge) {
- // Drive the webview imperatively; `usePreviewBridge` mirrors the
- // resolved URL back to the server so other clients stay in sync.
- await previewBridge.navigate(tabId, resolvedUrl);
- rememberPreviewUrl(threadRef, resolvedUrl);
- } else {
- await openPreviewSession({
- openPreview: open,
- threadRef,
- url: resolvedUrl,
- });
- }
+ await navigateToResolvedUrl(normalizePreviewUrl(next));
  } catch {
  // Server-side `failed` event renders the unreachable view.
  }
  },
- [open, tabId, threadRef],
+ [navigateToResolvedUrl],
+ );
+
+ const handleOpenServerUrl = useCallback(
+ async (next: string) => {
+ try {
+ await navigateToResolvedUrl(resolveDiscoveredServerUrl(threadRef.environmentId, next));
+ } catch {
+ // Server-side `failed` event renders the unreachable view.
+ }
+ },
+ [navigateToResolvedUrl, threadRef.environmentId],
  );
 
  const handleRefresh = useCallback(() => {
@@ -613,7 +631,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  environmentId={threadRef.environmentId}
  configuredUrls={configuredUrls}
  recentlySeenUrls={previewState.recentlySeenUrls}
- onOpenUrl={(next) => void handleSubmitUrl(next)}
+ onOpenUrl={(next) => void handleOpenServerUrl(next)}
  />
  ) : null}
  {snapshot && desktopOverlay ? (

diff --git a/apps/web/src/components/preview/PreviewView.test.tsx b/apps/web/src/components/preview/PreviewView.test.tsx
@@ -0,0 +1,194 @@
+import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { renderToStaticMarkup } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const mocks = vi.hoisted(() => ({
+ navigate: vi.fn(async (_tabId: string, _url: string): Promise<void> => undefined),
+ rememberPreviewUrl: vi.fn(),
+ readPreparedConnection: vi.fn(() => ({ httpBaseUrl: "http://172.25.85.75:3773" })),
+ submittedUrl: null as ((url: string) => void) | null,
+ emptyStateUrl: null as ((url: string) => void) | null,
+ showEmptyState: false,
+}));
+
+vi.mock("~/state/session", () => ({
+ readPreparedConnection: mocks.readPreparedConnection,
+}));
+
+vi.mock("~/composerDraftStore", () => ({
+ useComposerDraftStore: (
+ select: (store: { addPreviewAnnotation: () => void; addImage: () => void }) => unknown,
+ ) => select({ addPreviewAnnotation: vi.fn(), addImage: vi.fn() }),
+}));
+
+vi.mock("~/lib/previewAnnotation", () => ({
+ previewAnnotationScreenshotFile: vi.fn(),
+}));
+
+vi.mock("~/localApi", () => ({
+ ensureLocalApi: vi.fn(),
+}));
+
+vi.mock("~/previewStateStore", () => ({
+ rememberPreviewUrl: mocks.rememberPreviewUrl,
+ updatePreviewServerSnapshot: vi.fn(),
+ useThreadPreviewState: () => ({
+ activeTabId: "tab-1",
+ desktopByTabId: {
+ "tab-1": {
+ canGoBack: false,
+ canGoForward: false,
+ loading: false,
+ zoomFactor: 1,
+ controller: "none",
+ },
+ },
+ recentlySeenUrls: [],
+ sessions: mocks.showEmptyState
+ ? {}
+ : {
+ "tab-1": {
+ threadId: "thread-1",
+ tabId: "tab-1",
+ navStatus: {
+ _tag: "Success",
+ url: "http://example.com/",
+ title: "Example",
+ },
+ canGoBack: false,
+ canGoForward: false,
+ updatedAt: "2026-07-13T00:00:00.000Z",
+ },
+ },
+ }),
+}));
+
+vi.mock("~/state/environments", () => ({
+ useEnvironment: () => ({ label: "WSL" }),
+ useEnvironmentHttpBaseUrl: () => "http://172.25.85.75:3773",
+}));
+
+vi.mock("~/state/preview", () => ({
+ previewEnvironment: { open: {}, resize: {} },
+}));
+
+vi.mock("~/state/use-atom-command", () => ({
+ useAtomCommand: () => vi.fn(),
+}));
+
+vi.mock("~/browser/browserRecording", () => ({
+ startBrowserRecording: vi.fn(),
+ stopBrowserRecording: vi.fn(),
+ useActiveBrowserRecordingTabId: () => null,
+}));
+
+vi.mock("~/browser/browserSurfaceStore", () => ({
+ useBrowserSurfaceStore: (
+ select: (state: { byTabId: Record<string, { rect?: unknown }> }) => unknown,
+ ) => select({ byTabId: {} }),
+}));
+
+vi.mock("~/components/ui/toast", () => ({
+ stackedThreadToast: vi.fn(),
+ toastManager: { add: vi.fn() },
+}));
+
+vi.mock("./previewBridge", () => ({
+ previewBridge: { navigate: mocks.navigate },
+}));
+
+vi.mock("./PreviewChromeRow", () => ({
+ PreviewChromeRow: (props: { onSubmit: (url: string) => void }) => {
+ mocks.submittedUrl = props.onSubmit;
+ return null;
+ },
+}));
+
+vi.mock("./PreviewEmptyState", () => ({
+ PreviewEmptyState: (props: { onOpenUrl: (url: string) => void }) => {
+ mocks.emptyStateUrl = props.onOpenUrl;
+ return null;
+ },
+}));
+vi.mock("./PreviewMoreMenu", () => ({ PreviewMoreMenu: () => null }));
+vi.mock("./PreviewUnreachable", () => ({ PreviewUnreachable: () => null }));
+vi.mock("./ZoomIndicator", () => ({ ZoomIndicator: () => null }));
+vi.mock("./AgentBrowserCursor", () => ({ AgentBrowserCursor: () => null }));
+vi.mock("~/browser/BrowserSurfaceSlot", () => ({ BrowserSurfaceSlot: () => null }));
+vi.mock("./useLoadingProgress", () => ({ useLoadingProgress: () => 0 }));
+vi.mock("./usePreviewSession", () => ({ usePreviewSession: vi.fn() }));
+
+import { PreviewView } from "./PreviewView";
+
+describe("PreviewView navigation", () => {
+ beforeEach(() => {
+ mocks.navigate.mockClear();
+ mocks.rememberPreviewUrl.mockClear();
+ mocks.readPreparedConnection.mockClear();
+ mocks.submittedUrl = null;
+ mocks.emptyStateUrl = null;
+ mocks.showEmptyState = false;
+ });
+
+ it.each([
+ [
+ "https://localhost:8000/dashboard?mode=test#top",
+ "https://localhost:8000/dashboard?mode=test#top",
+ ],
+ ["localhost:5173/app", "http://localhost:5173/app"],
+ ])("preserves a direct localhost URL in a WSL environment", async (submitted, expected) => {
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.submittedUrl).not.toBeNull();
+ mocks.submittedUrl?.(submitted);
+
+ await vi.waitFor(() => expect(mocks.navigate).toHaveBeenCalledWith("tab-1", expected));
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ expected,
+ );
+ });
+
+ it("maps an empty-state localhost server onto the WSL host", async () => {
+ mocks.showEmptyState = true;
+ renderToStaticMarkup(
+ <PreviewView
+ threadRef={{
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ }}
+ tabId="tab-1"
+ visible
+ />,
+ );
+
+ expect(mocks.emptyStateUrl).not.toBeNull();
+ mocks.emptyStateUrl?.("http://localhost:5173/app?mode=test#top");
+
+ await vi.waitFor(() =>
+ expect(mocks.navigate).toHaveBeenCalledWith(
+ "tab-1",
+ "http://172.25.85.75:5173/app?mode=test#top",
+ ),
+ );
+ expect(mocks.rememberPreviewUrl).toHaveBeenCalledWith(
+ {
+ environmentId: "environment-1",
+ threadId: "thread-1",
+ },
+ "http://172.25.85.75:5173/app?mode=test#top",
+ );
+ });
+});
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
@@ -7,6 +7,7 @@ import {
  type PreviewViewportSetting,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { normalizePreviewUrl } from "@t3tools/shared/preview";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useComposerDraftStore } from "~/composerDraftStore";
@@ -112,27 +113,44 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  tabId ? (state.byTabId[tabId]?.rect ?? null) : null,
  );
 
+ const navigateToResolvedUrl = useCallback(
+ async (resolvedUrl: string) => {
+ if (tabId && previewBridge) {
+ // Drive the webview imperatively; `usePreviewBridge` mirrors the
+ // resolved URL back to the server so other clients stay in sync.
+ await previewBridge.navigate(tabId, resolvedUrl);
+ rememberPreviewUrl(threadRef, resolvedUrl);
+ } else {
+ await openPreviewSession({
+ openPreview: open,
+ threadRef,
+ url: resolvedUrl,
+ });
+ }
+ },
+ [open, tabId, threadRef],
+ );
+
  const handleSubmitUrl = useCallback(
  async (next: string) => {
  try {
- const resolvedUrl = resolveDiscoveredServerUrl(threadRef.environmentId, next);
- if (tabId && previewBridge) {
- // Drive the webview imperatively; `usePreviewBridge` mirrors the
- // resolved URL back to the server so other clients stay in sync.
- await previewBridge.navigate(tabId, resolvedUrl);
- rememberPreviewUrl(threadRef, resolvedUrl);
- } else {
- await openPreviewSession({
- openPreview: open,
- threadRef,
- url: resolvedUrl,
- });
- }
+ await navigateToResolvedUrl(normalizePreviewUrl(next));
  } catch {
  // Server-side `failed` event renders the unreachable view.
  }
  },
- [open, tabId, threadRef],
+ [navigateToResolvedUrl],
+ );
+
+ const handleOpenServerUrl = useCallback(
+ async (next: string) => {
+ try {
+ await navigateToResolvedUrl(resolveDiscoveredServerUrl(threadRef.environmentId, next));
+ } catch {
+ // Server-side `failed` event renders the unreachable view.
+ }
+ },
+ [navigateToResolvedUrl, threadRef.environmentId],
  );
 
  const handleRefresh = useCallback(() => {
@@ -613,7 +631,7 @@ export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls,
  environmentId={threadRef.environmentId}
  configuredUrls={configuredUrls}
  recentlySeenUrls={previewState.recentlySeenUrls}
- onOpenUrl={(next) => void handleSubmitUrl(next)}
+ onOpenUrl={(next) => void handleOpenServerUrl(next)}
  />
  ) : null}
  {snapshot && desktopOverlay ? (