@agent-native/dispatch 0.29.0 → 0.29.2

package/src/components/workspace-app-host.spec.tsx

@@ -25,6 +25,7 @@ const clientState = vi.hoisted(() => {
     legacyMutateAsync,
     legacyMutateError: null as Error | null,
     legacyErrorMutateAsync,
+    inBuilderFrame: false,
     frameLoadHandler: null as (() => void) | null,
     suppressFrameLoad: false,
     theme: "dark" as "dark" | "light",
@@ -81,6 +82,10 @@ vi.mock("@agent-native/core/client/feature-flags", () => ({
   useFeatureFlag: () => clientState.workspaceSsoEnabled,
 }));
 
+vi.mock("@agent-native/core/client/host", () => ({
+  isInBuilderFrame: () => clientState.inBuilderFrame,
+}));
+
 vi.mock("@agent-native/core/client/hooks", () => ({
   useActionMutation: (name: string) => {
     clientState.actionNames.push(name);
@@ -156,6 +161,7 @@ describe("WorkspaceAppKeepAlive", () => {
     clientState.legacyMutateAsync.mockClear();
     clientState.legacyMutateError = null;
     clientState.legacyErrorMutateAsync.mockReset();
+    clientState.inBuilderFrame = false;
     clientState.frameLoadHandler = null;
     clientState.suppressFrameLoad = false;
     clientState.workspaceSsoMutateAsync.mockClear();
@@ -166,6 +172,14 @@ describe("WorkspaceAppKeepAlive", () => {
   afterEach(() => {
     act(() => root.unmount());
     container.remove();
+    Object.defineProperty(window, "parent", {
+      configurable: true,
+      value: window,
+    });
+    Object.defineProperty(window, "top", {
+      configurable: true,
+      value: window,
+    });
     vi.unstubAllGlobals();
   });
 
@@ -354,6 +368,110 @@ describe("WorkspaceAppKeepAlive", () => {
     ).toBe("Workspace SSO is temporarily unavailable");
   });
 
+  it("opens the app in the top window when Dispatch is inside an iframe", async () => {
+    const topWindow = { location: { href: "" } } as unknown as Window;
+    const expectedUrl = new URL("/mail", window.location.href).href;
+    Object.defineProperty(window, "parent", {
+      configurable: true,
+      value: {},
+    });
+    Object.defineProperty(window, "top", {
+      configurable: true,
+      value: topWindow,
+    });
+
+    await act(async () => {
+      root.render(
+        <WorkspaceAppFrame app={{ id: "mail", name: "Mail", path: "/mail" }} />,
+      );
+      await Promise.resolve();
+    });
+
+    expect(topWindow.location.href).toBe(expectedUrl);
+    expect(clientState.legacyMutateAsync).not.toHaveBeenCalled();
+    expect(container.querySelector("iframe")).toBeNull();
+  });
+
+  it("falls back to the embedded app when top-window navigation is blocked", async () => {
+    const navigateToTopWindow = vi.fn(() => false);
+    Object.defineProperty(window, "parent", {
+      configurable: true,
+      value: {},
+    });
+
+    await act(async () => {
+      root.render(
+        <WorkspaceAppFrame
+          app={{ id: "mail", name: "Mail", path: "/mail" }}
+          navigateToTopWindow={navigateToTopWindow}
+        />,
+      );
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(navigateToTopWindow).toHaveBeenCalledWith("/mail");
+    expect(clientState.legacyMutateAsync).toHaveBeenCalledWith({
+      app: "mail",
+      path: "/mail",
+      chrome: "minimal",
+    });
+    expect(container.querySelector("iframe")).not.toBeNull();
+  });
+
+  it("preserves a chat-first deep route in the top window when embedded", async () => {
+    const topWindow = { location: { href: "" } } as unknown as Window;
+    const embedPath = "/emails?status=failed#latest";
+    const expectedUrl = new URL(
+      "/mail/emails?status=failed#latest",
+      window.location.href,
+    ).href;
+    Object.defineProperty(window, "parent", {
+      configurable: true,
+      value: {},
+    });
+    Object.defineProperty(window, "top", {
+      configurable: true,
+      value: topWindow,
+    });
+
+    await act(async () => {
+      root.render(
+        <WorkspaceAppFrame
+          app={{ id: "mail", name: "Mail", path: "/mail" }}
+          embedPath={embedPath}
+        />,
+      );
+      await Promise.resolve();
+    });
+
+    expect(topWindow.location.href).toBe(expectedUrl);
+    expect(clientState.legacyMutateAsync).not.toHaveBeenCalled();
+    expect(container.querySelector("iframe")).toBeNull();
+  });
+
+  it("opens the app in the top window for a Builder webview", async () => {
+    const topWindow = { location: { href: "" } } as unknown as Window;
+    const expectedUrl = new URL("/mail", window.location.href).href;
+    clientState.inBuilderFrame = true;
+    Object.defineProperty(window, "top", {
+      configurable: true,
+      value: topWindow,
+    });
+
+    await act(async () => {
+      root.render(
+        <WorkspaceAppFrame app={{ id: "mail", name: "Mail", path: "/mail" }} />,
+      );
+      await Promise.resolve();
+    });
+
+    expect(topWindow.location.href).toBe(expectedUrl);
+    expect(clientState.legacyMutateAsync).not.toHaveBeenCalled();
+    expect(container.querySelector("iframe")).toBeNull();
+  });
+
   it("evicts the oldest inactive app after reaching the keep-alive limit", async () => {
     await act(async () => {
       root.render(<WorkspaceAppKeepAlive activeAppId="mail" />);

package/src/components/workspace-app-host.tsx

@@ -31,6 +31,8 @@ import { Link } from "react-router";
 import { isEmbedSessionExpiredMessage } from "../lib/embed-session-recovery";
 import {
   mergeChatFirstWorkspaceApps,
+  navigateToWorkspaceApp,
+  shouldOpenWorkspaceAppInTopWindow,
   workspaceAppDirectHref,
   workspaceAppEmbedTarget,
   workspaceAppHref,
@@ -244,6 +246,7 @@ export interface WorkspaceAppFrameApp {
 
 interface WorkspaceAppFrameProps {
   app: WorkspaceAppFrameApp;
+  navigateToTopWindow?: (href: string) => boolean | void;
   /** Chat-first app tabs use their own route while standalone hosts use app metadata. */
   embedPath?: string;
   /** Chat-first app surfaces own the parent chat rail around the iframe. */
@@ -253,6 +256,7 @@ interface WorkspaceAppFrameProps {
 
 export function WorkspaceAppFrame({
   app,
+  navigateToTopWindow = navigateToWorkspaceApp,
   embedPath,
   chatSidebar = false,
   copy = defaultChatFirstCopy,
@@ -269,6 +273,8 @@ export function WorkspaceAppFrame({
   const [embedError, setEmbedError] = useState<Error | null>(null);
   const [isDirectFallback, setIsDirectFallback] = useState(false);
   const [embedAttempt, setEmbedAttempt] = useState(0);
+  const [topWindowNavigationFailed, setTopWindowNavigationFailed] =
+    useState(false);
   const embedFrameRef = useRef<HTMLIFrameElement>(null);
   const postThemeToFrame = useCallback(() => {
     embedFrameRef.current?.contentWindow?.postMessage(
@@ -299,6 +305,21 @@ export function WorkspaceAppFrame({
     path: app.path ?? "",
     url: app.url,
   });
+  const topWindowHref = useMemo(() => {
+    if (embedPath !== undefined) {
+      return workspaceAppDirectHref(
+        { path: app.path, url: app.url },
+        embedPath,
+      );
+    }
+
+    const target = workspaceAppEmbedTarget({
+      path: app.path ?? "",
+      url: app.url,
+    });
+    return target.url ?? target.path ?? null;
+  }, [app.path, app.url, embedPath]);
+  const openInTopWindow = shouldOpenWorkspaceAppInTopWindow();
   const embedInput = useMemo<EmbedSessionInput | null>(() => {
     if (embedPath !== undefined) {
       return buildChatFirstEmbedSessionInput(app.id, embedPath);
@@ -312,7 +333,26 @@ export function WorkspaceAppFrame({
   }, [app.id, app.path, app.url, appHref, embedPath]);
 
   useEffect(() => {
-    if (!embedInput) return;
+    if (!openInTopWindow) {
+      setTopWindowNavigationFailed(false);
+      return;
+    }
+    if (!topWindowHref) {
+      setTopWindowNavigationFailed(true);
+      return;
+    }
+
+    let didNavigate = false;
+    try {
+      didNavigate = navigateToTopWindow(topWindowHref) !== false;
+    } catch {
+      didNavigate = false;
+    }
+    setTopWindowNavigationFailed(!didNavigate);
+  }, [navigateToTopWindow, openInTopWindow, topWindowHref]);
+
+  useEffect(() => {
+    if (!embedInput || (openInTopWindow && !topWindowNavigationFailed)) return;
     let cancelled = false;
     setEmbedUrl(null);
     setEmbedError(null);
@@ -359,6 +399,8 @@ export function WorkspaceAppFrame({
     embedInput,
     embedPath,
     embedAttempt,
+    openInTopWindow,
+    topWindowNavigationFailed,
     workspaceSsoEnabled,
   ]);
 
@@ -424,7 +466,13 @@ export function WorkspaceAppFrame({
   );
 }
 
-export function WorkspaceAppHost({ appId }: { appId?: string }) {
+export function WorkspaceAppHost({
+  appId,
+  navigateToTopWindow = navigateToWorkspaceApp,
+}: {
+  appId?: string;
+  navigateToTopWindow?: (href: string) => boolean | void;
+}) {
   const t = useT();
   const workspaceAppsQuery = useActionQuery<WorkspaceAppSummary[]>(
     "list-workspace-apps",
@@ -575,7 +623,10 @@ export function WorkspaceAppHost({ appId }: { appId?: string }) {
       className="flex h-full min-h-0 flex-col bg-background"
     >
       <div className="min-h-0 flex-1 bg-muted/20">
-        <WorkspaceAppFrame app={app} />
+        <WorkspaceAppFrame
+          app={app}
+          navigateToTopWindow={navigateToTopWindow}
+        />
       </div>
     </div>
   );

package/src/components/workspace-app-search.tsx

@@ -21,7 +21,7 @@ export function WorkspaceAppSearch({
     defaultValue: "Search apps",
   });
   const placeholder = t("dispatch.pages.searchAppsPlaceholder", {
-    defaultValue: "Search by name or description",
+    defaultValue: "Search apps",
   });
 
   return (

package/src/lib/workspace-apps.test.ts

@@ -1,6 +1,8 @@
-import { describe, expect, it } from "vitest";
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it } from "vitest";
 
 import {
+  navigateToWorkspaceApp,
   workspaceAppDirectHref,
   workspaceAppEmbedTarget,
 } from "./workspace-apps";
@@ -62,3 +64,70 @@ describe("workspaceAppDirectHref", () => {
     );
   });
 });
+
+describe("navigateToWorkspaceApp", () => {
+  afterEach(() => {
+    Object.defineProperty(window, "parent", {
+      configurable: true,
+      value: window,
+    });
+    Object.defineProperty(window, "top", {
+      configurable: true,
+      value: window,
+    });
+  });
+
+  it("uses the top window when Dispatch is embedded", () => {
+    const topWindow = { location: { href: "" } } as unknown as Window;
+    Object.defineProperty(window, "parent", {
+      configurable: true,
+      value: {},
+    });
+    Object.defineProperty(window, "top", {
+      configurable: true,
+      value: topWindow,
+    });
+
+    navigateToWorkspaceApp("/mail");
+
+    expect(topWindow.location.href).toBe(
+      new URL("/mail", window.location.href).href,
+    );
+  });
+
+  it("reports when the embedded top window rejects navigation", () => {
+    const location = {} as Location;
+    Object.defineProperty(location, "href", {
+      configurable: true,
+      set: () => {
+        throw new Error("Top navigation is blocked");
+      },
+    });
+    const topWindow = { location } as unknown as Window;
+    Object.defineProperty(window, "parent", {
+      configurable: true,
+      value: {},
+    });
+    Object.defineProperty(window, "top", {
+      configurable: true,
+      value: topWindow,
+    });
+
+    expect(navigateToWorkspaceApp("/mail")).toBe(false);
+  });
+
+  it("rejects non-http navigation targets", () => {
+    const topWindow = { location: { href: "" } } as unknown as Window;
+    Object.defineProperty(window, "parent", {
+      configurable: true,
+      value: {},
+    });
+    Object.defineProperty(window, "top", {
+      configurable: true,
+      value: topWindow,
+    });
+
+    expect(navigateToWorkspaceApp("javascript:alert(1)")).toBe(false);
+    expect(topWindow.location.href).toBe("");
+  });
+});

package/src/lib/workspace-apps.ts

@@ -1,4 +1,5 @@
 import { CHAT_FIRST_DEFAULT_APP_IDS } from "@agent-native/core/client/chat-first";
+import { isInBuilderFrame } from "@agent-native/core/client/host";
 import { withBuilderUtmTrackingParams } from "@agent-native/core/shared/builder-link-tracking";
 
 import { CANONICAL_WORKSPACE_SSO_APP_ORIGINS } from "../shared/workspace-sso";
@@ -158,6 +159,29 @@ export function isPendingBuilderHref(app: WorkspaceAppSummary): boolean {
   return app.status === "pending" && !!app.builderUrl;
 }
 
+export function shouldOpenWorkspaceAppInTopWindow(): boolean {
+  if (typeof window === "undefined") return false;
+  return isInBuilderFrame() || window.parent !== window;
+}
+
+export function navigateToWorkspaceApp(href: string): boolean {
+  if (typeof window === "undefined") return false;
+
+  try {
+    const targetUrl = new URL(href, window.location.href);
+    if (targetUrl.protocol !== "http:" && targetUrl.protocol !== "https:") {
+      return false;
+    }
+    const targetWindow =
+      shouldOpenWorkspaceAppInTopWindow() && window.top ? window.top : window;
+    targetWindow.location.href = targetUrl.href;
+    return true;
+  } catch {
+    // coercion-ok: a blocked top-window assignment is an expected fallback signal.
+    return false;
+  }
+}
+
 /**
  * Keep the chat-first rail useful before a workspace manifest is populated.
  * Mounted workspace rows still win, so custom names and routes remain the

package/src/routes/pages/$appId.spec.tsx

@@ -0,0 +1,115 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const routeState = vi.hoisted(() => ({
+  navigateToWorkspaceApp: vi.fn(() => false),
+}));
+
+vi.mock("@agent-native/core/client/api-path", () => ({
+  appPath: (path: string) => path,
+}));
+
+vi.mock("@agent-native/core/client/hooks", () => ({
+  useActionQuery: () => ({
+    data: [
+      {
+        id: "mail",
+        name: "Mail",
+        path: "/mail",
+        url: null,
+        status: "ready",
+      },
+    ],
+    isError: false,
+    isLoading: false,
+    refetch: vi.fn(),
+  }),
+}));
+
+vi.mock("@agent-native/core/client/i18n", () => ({
+  useT: () => (key: string) => key,
+}));
+
+vi.mock("@agent-native/core/shared/builder-link-tracking", () => ({
+  withBuilderUtmTrackingParams: (href: string) => href,
+}));
+
+vi.mock("react-router", () => ({
+  Link: ({ children }: { children: React.ReactNode }) => <a>{children}</a>,
+  Navigate: () => null,
+  redirect: (target: string) => target,
+  useParams: () => ({ appId: "mail" }),
+}));
+
+vi.mock("../../components/action-query-error", () => ({
+  ActionQueryError: ({ onRetry }: { onRetry: () => unknown }) => (
+    <button data-navigation-retry onClick={onRetry}>
+      retry
+    </button>
+  ),
+}));
+
+vi.mock("../../components/dispatch-shell", () => ({
+  DispatchShell: ({ children }: { children: React.ReactNode }) => (
+    <div data-dispatch-shell>{children}</div>
+  ),
+}));
+
+vi.mock("../../lib/catch-all-target", () => ({
+  resolveServerCatchAllTarget: vi.fn(),
+}));
+
+vi.mock("../../lib/workspace-apps", () => ({
+  navigateToWorkspaceApp: routeState.navigateToWorkspaceApp,
+  workspaceAppHref: (app: { path?: string | null }) => app.path ?? null,
+}));
+
+vi.mock("../../components/ui/badge", () => ({ Badge: () => null }));
+vi.mock("../../components/ui/button", () => ({
+  Button: ({ children }: { children: React.ReactNode }) => (
+    <button>{children}</button>
+  ),
+}));
+vi.mock("../../components/ui/spinner", () => ({ Spinner: () => null }));
+
+import WorkspaceAppCatchAllRoute from "./$appId";
+
+describe("WorkspaceAppCatchAllRoute", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    routeState.navigateToWorkspaceApp.mockClear();
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  });
+
+  it("shows a retryable error when navigation cannot reach the target", async () => {
+    await act(async () => {
+      root.render(<WorkspaceAppCatchAllRoute />);
+      await Promise.resolve();
+    });
+
+    expect(routeState.navigateToWorkspaceApp).toHaveBeenCalledWith("/mail");
+    expect(container.querySelector("[data-navigation-retry]")).not.toBeNull();
+
+    await act(async () => {
+      container
+        .querySelector<HTMLButtonElement>("[data-navigation-retry]")
+        ?.click();
+      await Promise.resolve();
+    });
+
+    expect(routeState.navigateToWorkspaceApp).toHaveBeenCalledTimes(2);
+  });
+});

package/src/routes/pages/$appId.tsx

@@ -7,7 +7,7 @@ import {
   IconArrowUpRight,
   IconClockHour4,
 } from "@tabler/icons-react";
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useState } from "react";
 import {
   Link,
   Navigate,
@@ -24,6 +24,7 @@ import { Button } from "../../components/ui/button";
 import { Spinner } from "../../components/ui/spinner";
 import { resolveServerCatchAllTarget } from "../../lib/catch-all-target";
 import {
+  navigateToWorkspaceApp,
   workspaceAppHref,
   type WorkspaceAppSummary,
 } from "../../lib/workspace-apps";
@@ -111,12 +112,18 @@ export default function WorkspaceAppCatchAllRoute() {
   );
   const href = app ? workspaceAppHref(app) : null;
   const isSelfReference = appId === "dispatch";
+  const hasApp = app !== null;
+  const appIsPending = app?.status === "pending";
+  const [navigationFailed, setNavigationFailed] = useState(false);
 
   useEffect(() => {
     if (isSelfReference) return;
-    if (!app || app.status === "pending" || !href) return;
-    window.location.assign(href);
-  }, [app, href, isSelfReference]);
+    if (!hasApp || appIsPending || !href) {
+      setNavigationFailed(false);
+      return;
+    }
+    setNavigationFailed(!navigateToWorkspaceApp(href));
+  }, [appIsPending, hasApp, href, isSelfReference]);
 
   if (isSelfReference) {
     return <Navigate to={appPath("/overview")} replace />;
@@ -136,7 +143,23 @@ export default function WorkspaceAppCatchAllRoute() {
     );
   }
 
-  if ((isLoading && !app) || (app && app.status !== "pending" && href)) {
+  if (navigationFailed && href) {
+    return (
+      <DispatchShell
+        title={t("dispatch.pages.dataLoadFailed")}
+        description={t("dispatch.pages.pageNotFoundDescription")}
+      >
+        <ActionQueryError
+          onRetry={() => setNavigationFailed(!navigateToWorkspaceApp(href))}
+        />
+      </DispatchShell>
+    );
+  }
+
+  if (
+    (isLoading && !app) ||
+    (app && app.status !== "pending" && href && !navigationFailed)
+  ) {
     return (
       <div className="flex h-screen w-full items-center justify-center">
         <Spinner className="size-8" />

package/src/routes/pages/apps.$appId.spec.tsx

@@ -0,0 +1,66 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const routeState = vi.hoisted(() => ({
+  appId: "mail",
+  hostProps: null as {
+    appId?: string;
+    navigateToTopWindow?: (href: string) => boolean | void;
+  } | null,
+  navigateToWorkspaceApp: vi.fn(() => true),
+}));
+
+vi.mock("react-router", () => ({
+  useParams: () => ({ appId: routeState.appId }),
+}));
+
+vi.mock("../../components/workspace-app-host", () => ({
+  WorkspaceAppHost: (props: typeof routeState.hostProps) => {
+    routeState.hostProps = props;
+    return <div data-workspace-app-id={props?.appId} />;
+  },
+}));
+
+vi.mock("../../lib/workspace-apps", () => ({
+  navigateToWorkspaceApp: routeState.navigateToWorkspaceApp,
+}));
+
+import WorkspaceAppRoute from "./apps.$appId";
+
+describe("WorkspaceAppRoute", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    routeState.appId = "mail";
+    routeState.hostProps = null;
+    routeState.navigateToWorkspaceApp.mockClear();
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  });
+
+  it("passes the route app id and top-window helper to the workspace host", async () => {
+    await act(async () => {
+      root.render(<WorkspaceAppRoute />);
+    });
+
+    expect(routeState.hostProps?.appId).toBe("mail");
+    expect(routeState.hostProps?.navigateToTopWindow).toEqual(
+      expect.any(Function),
+    );
+
+    routeState.hostProps?.navigateToTopWindow?.("/mail");
+
+    expect(routeState.navigateToWorkspaceApp).toHaveBeenCalledWith("/mail");
+  });
+});

package/src/routes/pages/apps.$appId.tsx

@@ -1,6 +1,11 @@
 import { useParams } from "react-router";
 
 import { WorkspaceAppHost } from "../../components/workspace-app-host";
+import { navigateToWorkspaceApp } from "../../lib/workspace-apps";
+
+export function navigateWorkspaceAppFromRoute(href: string): boolean {
+  return navigateToWorkspaceApp(href);
+}
 
 export function meta() {
   return [{ title: "Workspace app - Dispatch" }];
@@ -8,5 +13,10 @@ export function meta() {
 
 export default function WorkspaceAppRoute() {
   const { appId } = useParams();
-  return <WorkspaceAppHost appId={appId} />;
+  return (
+    <WorkspaceAppHost
+      appId={appId}
+      navigateToTopWindow={navigateWorkspaceAppFromRoute}
+    />
+  );
 }