Opt-in document loads for same-origin redirects and navigate()

[everton-dgn]

I maintain a multilingual app where /en/* and /es/* share an origin. We load a new document when the locale changes so the document language and rendered content stay together. Same-locale navigation stays in the router.

The awkward case is a redirect returned by an action or query. I catch it in a root useBeforeLeave, call preventDefault(), then location.replace(). The root guard subscribes first. A later page guard can cancel router navigation, but cannot undo that call to location.replace().

Here is a reduced example for @solidjs/router 2.0.0-next.38:

import { action, createRouter, useAction, useNavigate } from "@solidjs/router";
import { redirect } from "@solidjs/web";

const switchLocale = action(
  async () => redirect("/es/destination"),
  "switch-locale"
);

function Start() {
  const submit = useAction(switchLocale);
  const navigate = useNavigate();
  return (
    <>
      <button onClick={() => submit()}>Action redirect</button>
      <button onClick={() => navigate("/es/destination")}>Navigate</button>
    </>
  );
}

export const Router = createRouter({
  routes: [
    { path: "/en/start", component: Start },
    { path: "/es/destination", component: () => <p>Destination</p> }
  ]
});

Mount <Router /> at /en/start. In Vitest/jsdom, the action rendered the destination through replaceState; direct navigation used pushState. A root-relative query redirect also rendered the destination in the same router. For this locale change, I need a document load. I'd like to keep returning a redirect Response so the action can also serve a plain form POST, rather than make client code handle a returned URL.

Would an optional hook such as documentNavigation: (url: URL) => boolean fit here? The name is just a sketch. It would choose a document load after leave guards accept, before starting the destination transition. For an English document, my predicate would accept /es/* and keep /en/* in the router.

The load should preserve the navigation's effective push/replace policy, including one inherited from a pending navigation. An optional plugin could keep unused behavior out of the bundle; its cost would need measurement. A per-redirect signal is another option, but the redirect() helper lives in @solidjs/web, and choosing the signal requires knowing the current document's locale.

There are already useful escape hatches:

• Anchors can use target="_self" or rel="external", as discussed in #304.
• Direct application code can call location.assign() or location.replace().
• For back/forward, a wrapper around browserHistory().init can reload the selected entry instead of notifying the router. My jsdom test confirmed that a page guard can block the traversal, and that acceptance calls a mocked reload callback without rendering the destination. A custom adapter needs scrollRestoration: true to retain the default restoration behavior.

Replacing history.set alone is too late: the router calls it when the transition settles.

These checks ran against dc1e0b0, with solid-js and @solidjs/web 2.0.0-rc.14. Real-browser coverage is still needed for document loads, chained redirects and guard retry, plus back/forward preserving the selected entry.