@agent-native/dispatch 0.31.13 → 0.31.15

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

@@ -183,6 +183,9 @@ describe("WorkspaceAppKeepAlive", () => {
     clientState.actionQueryParams.length = 0;
     clientState.actionQueryOptions.length = 0;
     clientState.workspaceApps = null;
+    clientState.legacyMutateAsync.mockImplementation(async () => ({
+      startUrl: "about:blank",
+    }));
     clientState.legacyMutateAsync.mockClear();
     clientState.legacyMutateError = null;
     clientState.legacyErrorMutateAsync.mockReset();
@@ -469,6 +472,101 @@ describe("WorkspaceAppKeepAlive", () => {
     );
   });
 
+  it("reports trusted child routes to the standalone Dispatch host", async () => {
+    clientState.legacyMutateAsync.mockResolvedValue({
+      startUrl: "https://design.example.test/_agent-native/embed",
+    });
+    clientState.suppressFrameLoad = true;
+    const onChildRouteChange = vi.fn();
+
+    await act(async () => {
+      root.render(
+        <WorkspaceAppFrame
+          app={{
+            id: "design",
+            name: "Design",
+            path: "/",
+            url: "https://design.example.test",
+          }}
+          onChildRouteChange={onChildRouteChange}
+        />,
+      );
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    const iframe = container.querySelector<HTMLIFrameElement>("iframe");
+    expect(iframe).not.toBeNull();
+    if (!iframe) throw new Error("Workspace app iframe was not rendered");
+
+    const frameWindow = iframe.contentWindow;
+    expect(frameWindow).not.toBeNull();
+    if (!frameWindow) throw new Error("Workspace app frame window is missing");
+
+    await act(async () => {
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          data: {
+            type: "agent-native:workspace-app-route",
+            path: "/foobar?mode=edit#canvas",
+          },
+          origin: "https://design.example.test",
+          source: frameWindow,
+        }),
+      );
+      await Promise.resolve();
+    });
+
+    expect(onChildRouteChange).toHaveBeenCalledWith(
+      "/apps/design/foobar?mode=edit#canvas",
+    );
+
+    await act(async () => {
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          data: {
+            type: "agent-native:workspace-app-route",
+            path: "/ignored",
+          },
+          origin: "https://evil.example.test",
+          source: frameWindow,
+        }),
+      );
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          data: {
+            type: "agent-native:workspace-app-route",
+            path: "/ignored",
+          },
+          origin: "https://design.example.test",
+          source: {} as Window,
+        }),
+      );
+      await Promise.resolve();
+    });
+
+    expect(onChildRouteChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("seeds a standalone iframe from its initial Dispatch route", async () => {
+    await act(async () => {
+      root.render(
+        <WorkspaceAppFrame
+          app={{ id: "design", name: "Design", path: "/design" }}
+          initialPath="/foobar?mode=edit#canvas"
+        />,
+      );
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(clientState.legacyMutateAsync).toHaveBeenCalledWith({
+      app: "design",
+      path: "/foobar?mode=edit#canvas",
+      chrome: "minimal",
+    });
+  });
+
   it("clears the embed error after a direct fallback iframe loads", async () => {
     clientState.legacyMutateError = new Error("Restore request failed");
     clientState.legacyErrorMutateAsync.mockRejectedValue(

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

@@ -11,6 +11,7 @@ import {
   useActionQuery,
 } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
+import { AGENT_NATIVE_WORKSPACE_APP_ROUTE_MESSAGE_TYPE } from "@agent-native/core/client/navigation";
 import { withBuilderUtmTrackingParams } from "@agent-native/core/shared/builder-link-tracking";
 import {
   IconAlertTriangle,
@@ -34,6 +35,7 @@ import {
   isWorkspaceSsoApp,
   navigateToWorkspaceApp,
   shouldOpenWorkspaceAppInTopWindow,
+  workspaceAppRouteForChildPath,
   workspaceAppDirectHref,
   workspaceAppEmbedTarget,
   workspaceAppHref,
@@ -251,6 +253,10 @@ interface WorkspaceAppFrameProps {
   navigateToTopWindow?: (href: string) => boolean | void;
   /** Chat-first app tabs use their own route while standalone hosts use app metadata. */
   embedPath?: string;
+  /** Standalone Dispatch routes seed the iframe once from their initial suffix. */
+  initialPath?: string;
+  /** Standalone Dispatch hosts mirror child route changes into the shell URL. */
+  onChildRouteChange?: (path: string) => void;
   /** Chat-first app surfaces own the parent chat rail around the iframe. */
   chatSidebar?: boolean;
   copy?: ChatFirstCopy;
@@ -260,6 +266,8 @@ export function WorkspaceAppFrame({
   app,
   navigateToTopWindow = navigateToWorkspaceApp,
   embedPath,
+  initialPath,
+  onChildRouteChange,
   chatSidebar = false,
   copy = defaultChatFirstCopy,
 }: WorkspaceAppFrameProps) {
@@ -315,27 +323,36 @@ export function WorkspaceAppFrame({
         embedPath,
       );
     }
+    if (initialPath !== undefined) {
+      return workspaceAppDirectHref(
+        { path: app.path, url: app.url },
+        initialPath,
+      );
+    }
 
     const target = workspaceAppEmbedTarget({
       path: app.path ?? "",
       url: app.url,
     });
     return target.url ?? target.path ?? null;
-  }, [app.path, app.url, embedPath]);
+  }, [app.path, app.url, embedPath, initialPath]);
   const openInTopWindow = shouldOpenWorkspaceAppInTopWindow();
-  const topWindowSsoAttemptKey = `${app.id}\u0000${app.path ?? ""}\u0000${app.url ?? ""}\u0000${embedPath ?? ""}\u0000${embedAttempt}`;
+  const topWindowSsoAttemptKey = `${app.id}\u0000${app.path ?? ""}\u0000${app.url ?? ""}\u0000${embedPath ?? ""}\u0000${initialPath ?? ""}\u0000${embedAttempt}`;
   const topWindowSsoAttemptedRef = useRef<string | null>(null);
   const embedInput = useMemo<EmbedSessionInput | null>(() => {
     if (embedPath !== undefined) {
       return buildChatFirstEmbedSessionInput(app.id, embedPath);
     }
+    if (initialPath !== undefined) {
+      return buildChatFirstEmbedSessionInput(app.id, initialPath);
+    }
     if (!appHref) return null;
     return {
       app: app.id,
       ...workspaceAppEmbedTarget({ path: app.path ?? "", url: app.url }),
       chrome: "minimal",
     };
-  }, [app.id, app.path, app.url, appHref, embedPath]);
+  }, [app.id, app.path, app.url, appHref, embedPath, initialPath]);
 
   useEffect(() => {
     if (openInTopWindow && useWorkspaceSso && embedInput) {
@@ -425,7 +442,7 @@ export function WorkspaceAppFrame({
         setEmbedUrl(
           workspaceAppDirectHref(
             { path: app.path ?? "", url: app.url },
-            embedPath ?? "/",
+            initialPath ?? embedPath ?? "/",
           ),
         );
         setEmbedError(error);
@@ -441,6 +458,7 @@ export function WorkspaceAppFrame({
     createWorkspaceSsoEmbedSession.mutateAsync,
     embedInput,
     embedPath,
+    initialPath,
     embedAttempt,
     openInTopWindow,
     navigateToTopWindow,
@@ -464,6 +482,48 @@ export function WorkspaceAppFrame({
       window.removeEventListener("message", handleEmbedSessionExpired);
   }, [embedUrl]);
 
+  useEffect(() => {
+    if (!onChildRouteChange || !embedUrl) return;
+
+    const frame = embedFrameRef.current;
+    if (!frame) return;
+
+    let expectedOrigin: string;
+    try {
+      expectedOrigin = new URL(embedUrl, window.location.href).origin;
+    } catch {
+      return;
+    }
+
+    const handleWorkspaceAppRoute = (event: MessageEvent) => {
+      if (
+        event.source !== frame.contentWindow ||
+        event.origin !== expectedOrigin
+      ) {
+        return;
+      }
+      const message = event.data as {
+        type?: unknown;
+        path?: unknown;
+      } | null;
+      if (
+        message?.type !== AGENT_NATIVE_WORKSPACE_APP_ROUTE_MESSAGE_TYPE ||
+        typeof message.path !== "string"
+      ) {
+        return;
+      }
+
+      const route = workspaceAppRouteForChildPath(
+        { id: app.id, path: app.path ?? "", url: app.url },
+        message.path,
+      );
+      if (route) onChildRouteChange(route);
+    };
+
+    window.addEventListener("message", handleWorkspaceAppRoute);
+    return () => window.removeEventListener("message", handleWorkspaceAppRoute);
+  }, [app.id, app.path, app.url, embedUrl, onChildRouteChange]);
+
   useEffect(() => {
     postThemeToFrame();
   }, [embedUrl, postThemeToFrame]);
@@ -514,9 +574,13 @@ export function WorkspaceAppFrame({
 export function WorkspaceAppHost({
   appId,
   navigateToTopWindow = navigateToWorkspaceApp,
+  initialPath,
+  onChildRouteChange,
 }: {
   appId?: string;
   navigateToTopWindow?: (href: string) => boolean | void;
+  initialPath?: string;
+  onChildRouteChange?: (path: string) => void;
 }) {
   const t = useT();
   const workspaceAppsQuery = useActionQuery<WorkspaceAppSummary[]>(
@@ -702,6 +766,8 @@ export function WorkspaceAppHost({
         <WorkspaceAppFrame
           app={app}
           navigateToTopWindow={navigateToTopWindow}
+          initialPath={initialPath}
+          onChildRouteChange={onChildRouteChange}
         />
       </div>
     </div>

package/src/lib/catch-all-target.spec.ts

@@ -12,6 +12,14 @@ describe("resolveCatchAllTarget", () => {
     ).toBe("/todo");
   });
 
+  it("keeps the legacy mounted path for normalized agent IDs", () => {
+    expect(
+      resolveCatchAllTarget("clips", {
+        workspaceApps: [{ id: "clips", path: "/videos" }],
+      }),
+    ).toBe("/videos");
+  });
+
   it("falls back to the built-in template URL when no workspace manifest exists", () => {
     expect(
       resolveCatchAllTarget("forms", {

package/src/lib/catch-all-target.ts

@@ -116,9 +116,11 @@ export async function resolveServerCatchAllTarget(
   appId: string,
 ): Promise<string | null> {
   if (!import.meta.env.SSR) return null;
-  const { getBuiltinAgents, loadWorkspaceAppsManifest } =
+  const { getBuiltinAgents, loadWorkspaceAppsManifest, normalizeAgentId } =
     await import("@agent-native/core/server/agent-discovery");
-  return resolveCatchAllTarget(appId, {
+  // Dispatch receives legacy route segments before discovery normalizes the
+  // manifest IDs, so normalize the lookup key at this boundary as well.
+  return resolveCatchAllTarget(normalizeAgentId(appId), {
     workspaceApps: loadWorkspaceAppsManifest(),
     builtinAgents: getBuiltinAgents("dispatch"),
   });

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

@@ -8,6 +8,8 @@ import {
   isWorkspaceSsoApp,
   mergeChatFirstWorkspaceApps,
   workspaceAppIdFromRoute,
+  workspaceAppInitialPathFromSplat,
+  workspaceAppRouteForChildPath,
   workspaceAppDirectHref,
   workspaceAppRoute,
 } from "./workspace-apps";
@@ -29,6 +31,44 @@ describe("workspace app routes", () => {
     expect(workspaceAppIdFromRoute("/apps/mail/inbox")).toBe("mail");
   });
 
+  it("preserves the initial app suffix for a standalone deep link", () => {
+    expect(
+      workspaceAppInitialPathFromSplat("inbox", "?view=unread", "#top"),
+    ).toBe("/inbox?view=unread#top");
+    expect(workspaceAppInitialPathFromSplat(undefined, "", "")).toBeUndefined();
+  });
+
+  it("maps child routes to shareable Dispatch app routes", () => {
+    expect(
+      workspaceAppRouteForChildPath(
+        { id: "design", path: "/", url: "https://design.example.test" },
+        "/foobar?mode=edit#canvas",
+      ),
+    ).toBe("/apps/design/foobar?mode=edit#canvas");
+    expect(
+      workspaceAppRouteForChildPath(
+        {
+          id: "internal-design",
+          path: "/design",
+          url: "https://workspace.example.test/design",
+        },
+        "/design/foobar",
+      ),
+    ).toBe("/apps/internal-design/foobar");
+    expect(
+      workspaceAppRouteForChildPath(
+        { id: "design", path: "/", url: "https://design.example.test" },
+        "//evil.example/route",
+      ),
+    ).toBeNull();
+    expect(
+      workspaceAppDirectHref(
+        { path: "/", url: "https://design.example.test" },
+        "/foobar?mode=edit#canvas",
+      ),
+    ).toBe("https://design.example.test/foobar?mode=edit#canvas");
+  });
+
   it("identifies Dispatch regardless of casing or surrounding whitespace", () => {
     expect(isDispatchWorkspaceAppId(" Dispatch ")).toBe(true);
     expect(isDispatchWorkspaceAppId("dispatch-tools")).toBe(false);

package/src/lib/workspace-apps.ts

@@ -149,6 +149,86 @@ export function workspaceAppRoute(appId: string): string {
   return `/apps/${encodeURIComponent(appId)}`;
 }
 
+function normalizeWorkspaceAppRoutePath(rawPath: string): URL | null {
+  if (
+    typeof rawPath !== "string" ||
+    !rawPath.startsWith("/") ||
+    rawPath.startsWith("//") ||
+    /[\u0000-\u001f\u007f]/.test(rawPath)
+  ) {
+    return null;
+  }
+
+  try {
+    return new URL(rawPath, "https://agent-native.invalid");
+  } catch {
+    // coercion-ok: malformed child routes are ignored by the host.
+    return null;
+  }
+}
+
+function normalizedWorkspaceAppMountPath(rawPath: string): string {
+  const pathname = rawPath.split(/[?#]/, 1)[0] ?? rawPath;
+  const normalized = `/${pathname.replace(/^[/\\]+/, "")}`;
+  return normalized.replace(/\/+$/, "") || "/";
+}
+
+function workspaceAppMountPath(
+  app: Pick<WorkspaceAppSummary, "path" | "url">,
+): string {
+  const rawUrl = app.url?.trim();
+  if (rawUrl) {
+    try {
+      const parsed = new URL(rawUrl);
+      if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+        return normalizedWorkspaceAppMountPath(parsed.pathname);
+      }
+      // coercion-ok: invalid URL falls back to app path.
+    } catch {
+      // Fall through to the mounted path when optional URL metadata is invalid.
+    }
+  }
+  return normalizedWorkspaceAppMountPath(app.path?.trim() || "/");
+}
+
+/**
+ * Convert a child app route into Dispatch's shareable workspace-app route.
+ * Mounted workspace apps may report their full mount path, while hosted apps
+ * normally report only the app-local path, so accept both forms here.
+ */
+export function workspaceAppRouteForChildPath(
+  app: Pick<WorkspaceAppSummary, "id" | "path" | "url">,
+  childPath: string,
+): string | null {
+  const parsed = normalizeWorkspaceAppRoutePath(childPath);
+  if (!parsed) return null;
+
+  const mountPath = workspaceAppMountPath(app);
+  const relativePathname =
+    mountPath !== "/" &&
+    (parsed.pathname === mountPath ||
+      parsed.pathname.startsWith(`${mountPath}/`))
+      ? parsed.pathname.slice(mountPath.length) || "/"
+      : parsed.pathname;
+  const routePath = workspaceAppRoute(app.id);
+  const suffix = relativePathname === "/" ? "" : relativePathname;
+  return `${routePath}${suffix}${parsed.search}${parsed.hash}`;
+}
+
+export function workspaceAppInitialPathFromSplat(
+  routeSplat: string | undefined,
+  search: string,
+  hash: string,
+): string | undefined {
+  const pathname = routeSplat?.trim()
+    ? `/${routeSplat.trim().replace(/^[/\\]+/, "")}`
+    : "/";
+  const parsed = normalizeWorkspaceAppRoutePath(`${pathname}${search}${hash}`);
+  if (!parsed) return undefined;
+  const path = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  return path === "/" ? undefined : path;
+}
+
 export function workspaceAppIdFromRoute(pathname: string): string | null {
   const match = pathname.match(/^\/apps\/([^/]+)(?:\/|$)/);
   if (!match) return null;

package/src/routes/index.spec.ts

@@ -1,3 +1,4 @@
+import { matchRoutes } from "react-router";
 import { describe, expect, it } from "vitest";
 
 import { dispatchRoutes } from "./index.js";
@@ -19,6 +20,7 @@ describe("Dispatch route registration", () => {
     expect(paths).toContain("operations");
     expect(paths).toContain("admin");
     expect(paths).toContain("agents");
+    expect(paths).toContain("apps/:appId/*");
     expect(paths.indexOf("chat")).toBeLessThan(paths.indexOf(":appId"));
     expect(paths.indexOf("chat/:threadId")).toBeLessThan(
       paths.indexOf(":appId"),
@@ -36,4 +38,12 @@ describe("Dispatch route registration", () => {
     expect(adminPaths).not.toContain("apps/:appId");
     expect(adminPaths.indexOf("operations")).toBeGreaterThanOrEqual(0);
   });
+
+  it("matches both workspace-app roots and nested deep links", () => {
+    for (const path of ["/apps/design", "/apps/design/foobar"]) {
+      expect(matchRoutes(dispatchRoutes, path)?.at(-1)?.route.path).toBe(
+        "apps/:appId/*",
+      );
+    }
+  });
 });

package/src/routes/index.ts

@@ -62,7 +62,7 @@ export const dispatchRoutes: RouteConfig = [
   route("metrics", "./pages/metrics.js"),
   route("operations", "./pages/operations.js"),
   route("apps", "./pages/apps.js"),
-  route("apps/:appId", "./pages/apps.$appId.js"),
+  route("apps/:appId/*", "./pages/apps.$appId.js"),
   route("new-app", "./pages/new-app.js"),
   route("vault", "./pages/vault.js"),
   route("integrations", "./pages/integrations.js"),

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

@@ -5,15 +5,22 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const routeState = vi.hoisted(() => ({
   appId: "mail",
+  routeSplat: undefined as string | undefined,
+  location: { pathname: "/apps/mail", search: "", hash: "" },
   hostProps: null as {
     appId?: string;
     navigateToTopWindow?: (href: string) => boolean | void;
+    initialPath?: string;
+    onChildRouteChange?: (path: string) => void;
   } | null,
   navigateToWorkspaceApp: vi.fn(() => true),
+  navigate: vi.fn(),
 }));
 
 vi.mock("react-router", () => ({
-  useParams: () => ({ appId: routeState.appId }),
+  useParams: () => ({ appId: routeState.appId, "*": routeState.routeSplat }),
+  useLocation: () => routeState.location,
+  useNavigate: () => routeState.navigate,
 }));
 
 vi.mock("../../components/workspace-app-host", () => ({
@@ -25,6 +32,14 @@ vi.mock("../../components/workspace-app-host", () => ({
 
 vi.mock("../../lib/workspace-apps", () => ({
   navigateToWorkspaceApp: routeState.navigateToWorkspaceApp,
+  workspaceAppInitialPathFromSplat: (
+    routeSplat: string | undefined,
+    search: string,
+    hash: string,
+  ) =>
+    routeSplat || search || hash
+      ? `/${routeSplat ?? ""}${search}${hash}`
+      : undefined,
 }));
 
 import WorkspaceAppRoute from "./apps.$appId";
@@ -36,8 +51,11 @@ describe("WorkspaceAppRoute", () => {
   beforeEach(() => {
     vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
     routeState.appId = "mail";
+    routeState.routeSplat = undefined;
+    routeState.location = { pathname: "/apps/mail", search: "", hash: "" };
     routeState.hostProps = null;
     routeState.navigateToWorkspaceApp.mockClear();
+    routeState.navigate.mockClear();
     container = document.createElement("div");
     document.body.appendChild(container);
     root = createRoot(container);
@@ -63,4 +81,35 @@ describe("WorkspaceAppRoute", () => {
 
     expect(routeState.navigateToWorkspaceApp).toHaveBeenCalledWith("/mail");
   });
+
+  it("keeps the iframe synchronized with standalone deep-link navigation", async () => {
+    routeState.routeSplat = "foobar";
+    routeState.location = {
+      pathname: "/apps/mail/foobar",
+      search: "?view=all",
+      hash: "#top",
+    };
+
+    await act(async () => {
+      root.render(<WorkspaceAppRoute />);
+    });
+
+    expect(routeState.hostProps?.initialPath).toBe("/foobar?view=all#top");
+
+    routeState.routeSplat = "sent";
+    routeState.location = {
+      pathname: "/apps/mail/sent",
+      search: "",
+      hash: "",
+    };
+    await act(async () => {
+      root.render(<WorkspaceAppRoute />);
+    });
+
+    expect(routeState.hostProps?.initialPath).toBe("/sent");
+    routeState.hostProps?.onChildRouteChange?.("/apps/mail/archive");
+    expect(routeState.navigate).toHaveBeenCalledWith("/apps/mail/archive", {
+      replace: true,
+    });
+  });
 });

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

@@ -1,7 +1,11 @@
-import { useParams } from "react-router";
+import { useCallback } from "react";
+import { useLocation, useNavigate, useParams } from "react-router";
 
 import { WorkspaceAppHost } from "../../components/workspace-app-host";
-import { navigateToWorkspaceApp } from "../../lib/workspace-apps";
+import {
+  navigateToWorkspaceApp,
+  workspaceAppInitialPathFromSplat,
+} from "../../lib/workspace-apps";
 
 export function navigateWorkspaceAppFromRoute(href: string): boolean {
   return navigateToWorkspaceApp(href);
@@ -12,11 +16,30 @@ export function meta() {
 }
 
 export default function WorkspaceAppRoute() {
-  const { appId } = useParams();
+  const params = useParams();
+  const { appId } = params;
+  const location = useLocation();
+  const navigate = useNavigate();
+  const initialPath = workspaceAppInitialPathFromSplat(
+    params["*"],
+    location.search,
+    location.hash,
+  );
+  const onChildRouteChange = useCallback(
+    (path: string) => {
+      const currentPath = `${location.pathname}${location.search}${location.hash}`;
+      if (path === currentPath) return;
+      void navigate(path, { replace: true });
+    },
+    [location.hash, location.pathname, location.search, navigate],
+  );
+
   return (
     <WorkspaceAppHost
       appId={appId}
       navigateToTopWindow={navigateWorkspaceAppFromRoute}
+      initialPath={initialPath}
+      onChildRouteChange={onChildRouteChange}
     />
   );
 }