fix(mobile): a pairing link fills the open Add environment form instead of stacking another (#26052)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: juliusmarminge

apps/mobile/src/App.tsx

@@ -52,7 +52,7 @@ import { OverlayPortalHost } from "./components/ui/OverlayPortal";
 import { shouldHandleAppLink, restoreDraftLinkState } from "./lib/appLinking";
 import { hasCloudPublicConfig } from "./features/cloud/publicConfig";
 import { takeScheduledTaskNewLink } from "./features/settings/scheduled-task-editor-state";
-import { startDevAutoConnect } from "./features/connection/devAutoConnect";
+import { pairingFormLinkAction, startDevAutoConnect } from "./features/connection/devAutoConnect";
 import {
   resolvePendingNewTaskPromptLink,
   takeNewTaskPromptLink,
@@ -129,6 +129,10 @@ const appLinking = {
   ): ReturnType<typeof getActionFromState> =>
     // Our router handles the selection; React Navigation's type only lists its own actions.
     (workspaceDetailLinkAction(state) as ReturnType<typeof getActionFromState>) ??
+    pairingFormLinkAction(
+      state,
+      rootNavigationRef.isReady() ? rootNavigationRef.getRootState() : undefined,
+    ) ??
     getActionFromState(state, options),
   getStateFromPath: getAppStateFromPath,
 };

apps/mobile/src/features/connection/devAutoConnect.test.ts

@@ -1,6 +1,21 @@
+import * as NodeModule from "node:module";
 import type { NavigationState, PartialState } from "@react-navigation/native";
 import { expect, it, vi } from "vite-plus/test";
 
+const requireFromNative = NodeModule.createRequire(
+  NodeModule.createRequire(import.meta.url).resolve("@react-navigation/native/package.json"),
+);
+const requireFromCore = NodeModule.createRequire(
+  requireFromNative.resolve("@react-navigation/core/package.json"),
+);
+const { getActionFromState, getStateFromPath } = requireFromNative("@react-navigation/core") as {
+  readonly getActionFromState: typeof import("@react-navigation/native").getActionFromState;
+  readonly getStateFromPath: typeof import("@react-navigation/native").getStateFromPath;
+};
+const { StackRouter } = requireFromCore("@react-navigation/routers") as {
+  readonly StackRouter: typeof import("@react-navigation/native").StackRouter;
+};
+
 const harness = vi.hoisted(() => ({
   pair: vi.fn(),
   goBack: vi.fn(),
@@ -20,7 +35,12 @@ const harness = vi.hoisted(() => ({
   deferred: null as Array<() => void> | null,
 }));
 
-vi.mock("@react-navigation/native", () => ({ StackActions: { replace: vi.fn() } }));
+vi.mock("@react-navigation/native", () => ({
+  StackActions: { replace: vi.fn() },
+  CommonActions: {
+    replaceParams: (params: object) => ({ type: "REPLACE_PARAMS", payload: { params } }),
+  },
+}));
 vi.mock("../../state/use-remote-environment-registry", () => ({
   pairEnvironment: harness.pair,
 }));
@@ -47,6 +67,7 @@ import { appAtomRegistry } from "../../state/atom-registry";
 import {
   autoConnectReport,
   devAutoConnectAttemptAtom,
+  pairingFormLinkAction,
   startDevAutoConnect,
 } from "./devAutoConnect";
 
@@ -191,3 +212,45 @@ it("a success that waited for navigation leaves a newer link's form open", async
   expect(harness.goBack).not.toHaveBeenCalled();
   expect(harness.dispatch).not.toHaveBeenCalled();
 });
+
+it("a pairing link fills the pairing form already on screen instead of stacking a second one", () => {
+  const linking = {
+    initialRouteName: "Home",
+    screens: {
+      Home: "",
+      Settings: "settings",
+      SettingsEnvironmentNew: "settings/environment-new",
+      ConnectionsNew: "connections/new",
+    },
+  };
+  const router = StackRouter({});
+  const options = {
+    routeNames: Object.keys(linking.screens),
+    routeParamList: {},
+    routeGetIdList: {},
+  };
+  // Settings > Environments > Add environment, as the user opened it.
+  const open = router.getRehydratedState(
+    {
+      index: 2,
+      routes: [{ name: "Home" }, { name: "Settings" }, { name: "SettingsEnvironmentNew" }],
+    },
+    options,
+  );
+  const link = getStateFromPath(
+    `connections/new?pairingUrl=${encodeURIComponent(PAIRING_URL)}`,
+    linking,
+  )!;
+  const action = pairingFormLinkAction(link, open) ?? getActionFromState(link, linking)!;
+  const next = router.getStateForAction(open, { target: open.key, ...action }, options);
+
+  expect(next?.routes.map((route) => route.name)).toEqual([
+    "Home",
+    "Settings",
+    "SettingsEnvironmentNew",
+  ]);
+  expect(next?.routes.at(-1)).toMatchObject({
+    key: open.routes[2]!.key,
+    params: { pairingUrl: PAIRING_URL },
+  });
+});

apps/mobile/src/features/connection/devAutoConnect.ts

@@ -1,5 +1,5 @@
 import type { NavigationState, PartialState } from "@react-navigation/native";
-import { StackActions } from "@react-navigation/native";
+import { CommonActions, StackActions } from "@react-navigation/native";
 import type { EnvironmentId } from "@t3tools/contracts";
 import { Atom } from "effect/reactivity";
 
@@ -97,3 +97,22 @@ export function startDevAutoConnect(
   }
   return state;
 }
+
+/**
+ * A pairing link that lands on an open pairing form fills that form. React Navigation would push
+ * `ConnectionsNew` over the Settings page's `SettingsEnvironmentNew`, stacking two copies of the
+ * same form. The form keys on the link's pairing URL, so new params remount it with the prefill.
+ */
+export function pairingFormLinkAction(
+  link: PartialState<NavigationState>,
+  current: NavigationState | undefined,
+) {
+  const linked = findLinkedRoute(link, PAIRING_FORM_ROUTES);
+  const open = current?.routes[current.index];
+  if (!linked || !current || !open || !PAIRING_FORM_ROUTES.includes(open.name)) return undefined;
+  return {
+    ...CommonActions.replaceParams(linked.params ?? {}),
+    source: open.key,
+    target: current.key,
+  };
+}