From 387121a97a485a19d73e1c748de255b56a58a1a4 Mon Sep 17 00:00:00 2001
From: Atif Ali <me@matifali.dev>
Date: Mon, 20 Apr 2026 08:26:00 +0000
Subject: [PATCH 1/4] fix(server): support serving mux under any path-rewriting
 reverse proxy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #2965.

Mux's SPA shell broke when served under a path-rewriting reverse proxy
(e.g. Coder path-based apps at `/@user/<ws>/apps/<slug>/`, nginx
`location /X/ { proxy_pass http://backend/; }`, Traefik StripPrefix,
k8s ingress rewrite-target) because:

1. The SPA fallback injected a hardcoded `\<base href="/"\>`, forcing
   Vite's relative asset URLs to resolve against the origin root and
   bypass the proxy (404 on e.g. `__vite-browser-external-*.css`).
2. `index.html` referenced `/manifest.json`, `/favicon.ico`, and
   `/apple-touch-icon.png` with absolute paths that always bypass `\<base\>`.
3. The service worker registered at `/service-worker.js` and cached
   `/` + `/index.html` with absolute paths.
4. The PWA manifest used absolute `start_url`/icon/shortcut URLs.

Prefix-stripping proxies hide the public prefix from the backend by
design, so no combination of `X-Forwarded-*` headers is guaranteed to
recover it. Instead, emit a **relative** `\<base href\>` that climbs from
the request URL back to the SPA root. The browser resolves relative
URLs (including `\<base\>`) against the document URL, so a correctly-sized
relative climb lands at the SPA root regardless of how the proxy maps
the public URL to the backend. This is the same technique code-server
uses for its `relativeRoot` helper (see
https://github.com/coder/code-server/blob/main/patches/base-path.diff).

The change is proxy-agnostic — Coder is just one consumer.

## Changes

- `src/node/orpc/server.ts`: inject `\<base href="__MUX_BASE_HREF__"\>` at
  startup, then per-request replace the placeholder with a relative
  climb computed from `req.url`.
- `index.html`: make `manifest`, `icon`, and `apple-touch-icon` hrefs
  relative so they honor `\<base\>`.
- `src/browser/main.tsx`: register the service worker via
  `new URL("service-worker.js", document.baseURI)` with a matching scope.
  `document.baseURI` honors `\<base\>`, so a single absolute URL covers
  every proxy configuration.
- `src/browser/contexts/ThemeContext.tsx`: use relative favicon paths
  when swapping between light/dark themes.
- `public/manifest.json`: use relative `start_url`, icon `src`, and
  shortcut URLs (manifest URLs resolve against the manifest's own URL).
- `public/service-worker.js`: cache `./` + `./index.html`.

## Validation

- New unit test `SPA shell uses a per-request relative \<base href\> that
  works under any path-stripping proxy` exercises `/`, single-segment,
  directory-style, and nested SPA routes with query strings.
- E2E simulation under four realistic proxy configurations (Coder
  path-app at root/depth-1/depth-2, generic nginx `/code/` prefix,
  direct origin at root/depth) confirms every asset — including the
  exact `__vite-browser-external-*` CSS/JS from the original bug —
  resolves and loads with HTTP 200.

> 🤖 This commit was created with the help of Coder Agents.
---
 index.html                            |  6 +--
 public/manifest.json                  |  8 +--
 public/service-worker.js              |  2 +-
 src/browser/contexts/ThemeContext.tsx |  4 +-
 src/browser/main.tsx                  |  8 ++-
 src/node/orpc/server.test.ts          | 64 +++++++++++++++++++++++-
 src/node/orpc/server.ts               | 70 ++++++++++++++++++++++++---
 7 files changed, 142 insertions(+), 20 deletions(-)

diff --git a/index.html b/index.html
index b3c5c65ee4..3d76070fd3 100644
--- a/index.html
+++ b/index.html
@@ -8,9 +8,9 @@
     />
     <meta name="description" content="Parallel agentic development with Electron + React" />
     <meta name="theme-color" content="#1e1e1e" />
-    <link rel="manifest" href="/manifest.json" crossorigin="use-credentials" vite-ignore />
-    <link rel="icon" href="/favicon.ico" data-theme-icon vite-ignore />
-    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" vite-ignore />
+    <link rel="manifest" href="manifest.json" crossorigin="use-credentials" vite-ignore />
+    <link rel="icon" href="favicon.ico" data-theme-icon vite-ignore />
+    <link rel="apple-touch-icon" sizes="180x180" href="apple-touch-icon.png" vite-ignore />
     <title>mux - coder multiplexer</title>
     <style>
       body {
diff --git a/public/manifest.json b/public/manifest.json
index a3be26a693..f8687b8638 100644
--- a/public/manifest.json
+++ b/public/manifest.json
@@ -2,20 +2,20 @@
   "name": "mux - coder multiplexer",
   "short_name": "mux",
   "description": "Parallel agentic development with Electron + React",
-  "start_url": "/",
+  "start_url": "./",
   "display": "standalone",
   "background_color": "#1e1e1e",
   "theme_color": "#1e1e1e",
   "orientation": "any",
   "icons": [
     {
-      "src": "/icon-192.png",
+      "src": "./icon-192.png",
       "sizes": "192x192",
       "type": "image/png",
       "purpose": "any maskable"
     },
     {
-      "src": "/icon-512.png",
+      "src": "./icon-512.png",
       "sizes": "512x512",
       "type": "image/png",
       "purpose": "any maskable"
@@ -27,7 +27,7 @@
       "name": "New Workspace",
       "short_name": "New",
       "description": "Create a new workspace",
-      "url": "/?action=new",
+      "url": "./?action=new",
       "icons": []
     }
   ]
diff --git a/public/service-worker.js b/public/service-worker.js
index 5bc7122d68..ff0334223b 100644
--- a/public/service-worker.js
+++ b/public/service-worker.js
@@ -1,6 +1,6 @@
 // mux Service Worker for PWA support
 const CACHE_NAME = "mux-v1";
-const urlsToCache = ["/", "/index.html"];
+const urlsToCache = ["./", "./index.html"];
 
 // Install event - cache core assets
 self.addEventListener("install", (event) => {
diff --git a/src/browser/contexts/ThemeContext.tsx b/src/browser/contexts/ThemeContext.tsx
index 2af138b7bf..25c0304449 100644
--- a/src/browser/contexts/ThemeContext.tsx
+++ b/src/browser/contexts/ThemeContext.tsx
@@ -67,8 +67,8 @@ const THEME_COLORS: Record<ThemeMode, string> = {
 };
 
 const FAVICON_BY_SCHEME: Record<"light" | "dark", string> = {
-  light: "/favicon.ico",
-  dark: "/favicon-dark.ico",
+  light: "favicon.ico",
+  dark: "favicon-dark.ico",
 };
 
 /** Map theme mode to CSS color-scheme value */
diff --git a/src/browser/main.tsx b/src/browser/main.tsx
index b3e6c1f879..51c64b0720 100644
--- a/src/browser/main.tsx
+++ b/src/browser/main.tsx
@@ -55,8 +55,14 @@ if ("serviceWorker" in navigator) {
     window.location.protocol === "http:" || window.location.protocol === "https:";
   if (isHttpProtocol) {
     window.addEventListener("load", () => {
+      // Resolve the SW URL and scope relative to the document's base URL so mux
+      // works when served under a path-rewriting reverse proxy. `document.baseURI`
+      // honors the `<base href>` the server emits, so a single absolute URL here
+      // covers every proxy configuration.
+      const serviceWorkerUrl = new URL("service-worker.js", document.baseURI).toString();
+      const serviceWorkerScope = new URL(".", document.baseURI).toString();
       navigator.serviceWorker
-        .register("/service-worker.js")
+        .register(serviceWorkerUrl, { scope: serviceWorkerScope })
         .then((registration) => {
           console.log("Service Worker registered:", registration);
         })
diff --git a/src/node/orpc/server.test.ts b/src/node/orpc/server.test.ts
index 33d564d091..630d97ecd6 100644
--- a/src/node/orpc/server.test.ts
+++ b/src/node/orpc/server.test.ts
@@ -175,7 +175,10 @@ describe("createOrpcServer", () => {
       expect(uiRes.status).toBe(200);
       const uiText = await uiRes.text();
       expect(uiText).toContain("mux");
-      expect(uiText).toContain('<base href="/"');
+      // `<base href>` is a relative climb from the document URL's directory
+      // back to the SPA root. `/some/spa/route` resolves against `.../some/spa/`,
+      // so needs two `../` hops.
+      expect(uiText).toContain('<base href="./../../"');
 
       const apiRes = await fetch(`${server.baseUrl}/api/not-a-real-route`);
       expect(apiRes.status).toBe(404);
@@ -215,8 +218,11 @@ describe("createOrpcServer", () => {
           expect(uiRes.status).toBe(200);
           const uiText = await uiRes.text();
 
+          // Both responses share the proxy URI template but have different
+          // relative base hrefs computed per-request.
+          expect(rootHtml).toContain('<base href="./"');
+          expect(uiText).toContain('<base href="./../../"');
           for (const html of [rootHtml, uiText]) {
-            expect(html).toContain('<base href="/"');
             expect(html).toContain("window.__MUX_PROXY_URI_TEMPLATE__ =");
             expect(html).toContain(
               'window.__MUX_PROXY_URI_TEMPLATE__ = "https://proxy-{{port}}.example.test/path\\u003c/script>";'
@@ -272,6 +278,60 @@ describe("createOrpcServer", () => {
     }
   });
 
+  test("SPA shell uses a per-request relative <base href> that works under any path-stripping proxy", async () => {
+    // <base href> is computed as a relative climb from the request URL back to
+    // the SPA root. This is proxy-agnostic: it works for direct access, for
+    // prefix-preserving proxies (the relative climb resolves correctly in the
+    // browser), and for prefix-stripping proxies (the backend only ever sees
+    // the stripped path, and the browser resolves <base> against the public
+    // document URL).
+    const stubContext: Partial<ORPCContext> = {};
+
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "mux-static-base-href-"));
+    const indexHtml =
+      "<!doctype html><html><head><title>mux</title></head><body><div>ok</div></body></html>";
+
+    let server: Awaited<ReturnType<typeof createOrpcServer>> | null = null;
+    try {
+      await fs.writeFile(path.join(tempDir, "index.html"), indexHtml, "utf-8");
+
+      server = await createOrpcServer({
+        host: "127.0.0.1",
+        port: 0,
+        context: stubContext as ORPCContext,
+        authToken: "test-token",
+        serveStatic: true,
+        staticDir: tempDir,
+      });
+
+      const cases: Array<{ url: string; expectedBaseHref: string }> = [
+        // Root request: no climb needed.
+        { url: "/", expectedBaseHref: "./" },
+        // Single-segment SPA routes: browser document URL directory == root, no climb.
+        { url: "/settings", expectedBaseHref: "./" },
+        // Trailing slash adds an empty segment, raising the depth by one.
+        { url: "/settings/", expectedBaseHref: "./../" },
+        // Nested SPA routes climb one level per intermediate directory segment.
+        { url: "/a/b", expectedBaseHref: "./../" },
+        { url: "/a/b/c", expectedBaseHref: "./../../" },
+        // Query strings are ignored for depth computation.
+        { url: "/a/b?x=1", expectedBaseHref: "./../" },
+      ];
+
+      for (const { url, expectedBaseHref } of cases) {
+        const res = await fetch(`${server.baseUrl}${url}`);
+        expect(res.status).toBe(200);
+        const html = await res.text();
+        const match = /<base href="([^"]+)"/.exec(html);
+        expect(match).not.toBeNull();
+        expect(match?.[1]).toBe(expectedBaseHref);
+      }
+    } finally {
+      await server?.close();
+      await fs.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
   test("does not apply origin validation to static and SPA fallback routes", async () => {
     // Static app shell must remain reachable even if proxy/header rewriting makes
     // request Origin values unexpected. API/WS/auth routes are validated separately.
diff --git a/src/node/orpc/server.ts b/src/node/orpc/server.ts
index 032203b70b..8edfd5bb68 100644
--- a/src/node/orpc/server.ts
+++ b/src/node/orpc/server.ts
@@ -113,14 +113,56 @@ function extractBearerToken(header: string | undefined): string | null {
   const token = header.slice(7).trim();
   return token.length ? token : null;
 }
-function injectBaseHref(indexHtml: string, baseHref: string): string {
+// Placeholder substituted per-request with the relative root for the current
+// request URL. Using a placeholder keeps the parse/serialize work out of the
+// hot path: we precompute the HTML with a placeholder once at startup and do a
+// single string replace per SPA shell response.
+const BASE_HREF_PLACEHOLDER = "__MUX_BASE_HREF__";
+
+function injectBaseHrefPlaceholder(indexHtml: string): string {
   // Avoid double-injecting if the HTML already has a base tag.
   if (/<base\b/i.test(indexHtml)) {
     return indexHtml;
   }
 
   // Insert immediately after the opening <head> tag (supports <head> and <head ...attrs>).
-  return indexHtml.replace(/<head[^>]*>/i, (match) => `${match}\n    <base href="${baseHref}" />`);
+  return indexHtml.replace(
+    /<head[^>]*>/i,
+    (match) => `${match}\n    <base href="${BASE_HREF_PLACEHOLDER}" />`
+  );
+}
+
+/**
+ * Compute the relative path that climbs from the current request URL back to
+ * the SPA root. This mirrors code-server's `relativeRoot` helper and makes mux
+ * work behind any path-rewriting reverse proxy without requiring the backend
+ * to know the public prefix. Because the browser resolves `<base href>`
+ * against the document URL, a relative climb of the right depth always lands
+ * at the SPA root regardless of whether the proxy preserves or strips a prefix.
+ *
+ * Examples (request URL → base href):
+ *   "/"                 -> "./"
+ *   "/settings"         -> "./"
+ *   "/settings/"        -> "./../"
+ *   "/a/b"              -> "./../"
+ *   "/a/b/"             -> "./../../"
+ */
+function computeBaseHrefForRequestUrl(requestUrl: string): string {
+  const pathOnly = requestUrl.split("?", 1)[0] ?? "/";
+  // Count path segments excluding the leading "/". A trailing slash counts as
+  // an empty final segment, which correctly raises the depth for directory-style
+  // URLs (e.g. `/a/b/` is at depth 2 from the root, not depth 1).
+  const segments = pathOnly.split("/").slice(1);
+  const depth = Math.max(0, segments.length - 1);
+  if (depth === 0) {
+    return "./";
+  }
+  return "./" + "../".repeat(depth);
+}
+
+function renderSpaShellForRequest(template: string, requestUrl: string): string {
+  const baseHref = computeBaseHrefForRequestUrl(requestUrl);
+  return template.replaceAll(BASE_HREF_PLACEHOLDER, baseHref);
 }
 
 function escapeJsonForHtmlScript(value: unknown): string {
@@ -560,15 +602,24 @@ export async function createOrpcServer({
   app.use(express.json({ limit: "50mb" }));
   app.use(express.urlencoded({ extended: false }));
 
-  let spaIndexHtml: string | null = null;
+  // Template for the SPA shell with a `__MUX_BASE_HREF__` placeholder in the
+  // injected `<base href>`. The placeholder is replaced per-request with a
+  // relative climb to the SPA root so mux works behind any path-rewriting
+  // reverse proxy (Coder path apps, nginx `proxy_pass http://backend/`, Traefik
+  // StripPrefix, k8s ingress rewrites, etc.) without requiring the backend to
+  // know the public prefix.
+  let spaIndexHtmlTemplate: string | null = null;
 
   // Static file serving (optional)
   if (serveStatic) {
     try {
       const indexHtmlPath = path.join(staticDir, "index.html");
       const indexHtml = await fs.readFile(indexHtmlPath, "utf8");
-      const indexHtmlWithBaseHref = injectBaseHref(indexHtml, "/");
-      spaIndexHtml = injectProxyUriTemplate(indexHtmlWithBaseHref, getBrowserProxyUriTemplate());
+      const indexHtmlWithBaseHref = injectBaseHrefPlaceholder(indexHtml);
+      spaIndexHtmlTemplate = injectProxyUriTemplate(
+        indexHtmlWithBaseHref,
+        getBrowserProxyUriTemplate()
+      );
     } catch (error) {
       log.error("Failed to read index.html for SPA fallback:", error);
     }
@@ -1350,9 +1401,14 @@ export async function createOrpcServer({
         return next();
       }
 
-      if (spaIndexHtml !== null) {
+      if (spaIndexHtmlTemplate !== null) {
+        // `req.url` is the path mux actually handles (after any upstream
+        // prefix-stripping reverse proxy). Using it here means the relative
+        // `<base href>` always points at mux's SPA root relative to the
+        // document URL the browser is currently rendering, regardless of the
+        // public prefix.
         res.setHeader("Content-Type", "text/html");
-        res.send(spaIndexHtml);
+        res.send(renderSpaShellForRequest(spaIndexHtmlTemplate, req.url));
         return;
       }
 

From e2df17c017faf51de887ab3aea8017b5f28b017c Mon Sep 17 00:00:00 2001
From: Atif Ali <me@matifali.dev>
Date: Mon, 20 Apr 2026 14:41:28 +0000
Subject: [PATCH 2/4] fix(browser): preserve path-app proxy prefix in URL bar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address review feedback on #3184:

- Scope base-href placeholder substitution to the `href="…"` attribute
  so stray `__MUX_BASE_HREF__` tokens elsewhere in the SPA shell survive
  untouched. (P1)
- Fix RouterContext's `useUrlSync` and App.tsx's popstate handler so
  `history.replaceState`/`pushState` preserve the public path-app
  proxy prefix. `MemoryRouter`'s internal paths are origin-relative,
  so writing them directly to the URL bar under a Coder path-app proxy
  would drop the `/@user/ws.main/apps/mux/` prefix on refresh. New
  `appBasePath` helper reads the server-injected `<base href>` to
  recover the public prefix. (P1)
- Bump service worker `CACHE_NAME` to `mux-v2` so existing installs
  purge pre-PR absolute-path cache entries on next activation. (P2)
- Export `computeBaseHrefForRequestUrl` and add unit tests for
  boundary inputs (empty, hash fragment, double slash); extend the
  per-request base-href table with a deeper trailing-slash case. (P3)
- Trim verbose comments on the placeholder and template helpers. (Nit)

All 47 existing server tests pass; adds 5 new tests (sentinel regression,
base-href unit table, three RouterContext proxy-prefix cases) plus
dedicated `appBasePath` unit coverage.
---
 public/service-worker.js                    |   2 +-
 src/browser/App.tsx                         |   8 +-
 src/browser/contexts/RouterContext.test.tsx | 110 +++++++++++++++-
 src/browser/contexts/RouterContext.tsx      |  19 ++-
 src/browser/utils/appBasePath.test.ts       | 100 +++++++++++++++
 src/browser/utils/appBasePath.ts            | 133 ++++++++++++++++++++
 src/node/orpc/server.test.ts                |  59 ++++++++-
 src/node/orpc/server.ts                     |  24 ++--
 8 files changed, 437 insertions(+), 18 deletions(-)
 create mode 100644 src/browser/utils/appBasePath.test.ts
 create mode 100644 src/browser/utils/appBasePath.ts

diff --git a/public/service-worker.js b/public/service-worker.js
index ff0334223b..49c99e6684 100644
--- a/public/service-worker.js
+++ b/public/service-worker.js
@@ -1,5 +1,5 @@
 // mux Service Worker for PWA support
-const CACHE_NAME = "mux-v1";
+const CACHE_NAME = "mux-v2";
 const urlsToCache = ["./", "./index.html"];
 
 // Install event - cache core assets
diff --git a/src/browser/App.tsx b/src/browser/App.tsx
index 1fda3782fc..7217fbca72 100644
--- a/src/browser/App.tsx
+++ b/src/browser/App.tsx
@@ -17,6 +17,7 @@ import {
 } from "./hooks/usePersistedState";
 import { useResizableSidebar } from "./hooks/useResizableSidebar";
 import { matchesKeybind, KEYBINDS } from "./utils/ui/keybinds";
+import { joinAppBasePath } from "./utils/appBasePath";
 import { handleLayoutSlotHotkeys } from "./utils/ui/layoutSlotHotkeys";
 import { buildSortedWorkspacesByProject } from "./utils/ui/workspaceFiltering";
 import { getVisibleWorkspaceIds } from "./utils/ui/workspaceDomNav";
@@ -869,9 +870,12 @@ function AppInner() {
     window.history.pushState({ mux: true }, "", window.location.href);
 
     const handlePopState = () => {
-      // Re-push the correct URL from MemoryRouter, not the popped browser URL
+      // Re-push the correct URL from MemoryRouter, not the popped browser URL.
+      // Re-apply the app base path so the URL bar keeps any path-app proxy
+      // prefix that mux is actually served under.
       const { pathname, search, hash } = locationRef.current;
-      const correctUrl = `${window.location.origin}${pathname}${search}${hash}`;
+      const publicPath = joinAppBasePath(pathname + search + hash);
+      const correctUrl = `${window.location.origin}${publicPath}`;
       window.history.pushState({ mux: true }, "", correctUrl);
     };
 
diff --git a/src/browser/contexts/RouterContext.test.tsx b/src/browser/contexts/RouterContext.test.tsx
index 3ec65ea232..1ebbd44cc5 100644
--- a/src/browser/contexts/RouterContext.test.tsx
+++ b/src/browser/contexts/RouterContext.test.tsx
@@ -9,6 +9,7 @@ import {
   LAUNCH_BEHAVIOR_KEY,
   SELECTED_WORKSPACE_KEY,
 } from "@/common/constants/storage";
+import { refreshAppBasePath } from "@/browser/utils/appBasePath";
 import { RouterProvider, useRouter, type RouterContext } from "./RouterContext";
 
 function createMatchMedia(isStandalone = false): typeof window.matchMedia {
@@ -29,7 +30,7 @@ type NavigationType = "navigate" | "reload" | "back_forward" | "prerender";
 
 function installWindow(
   url: string,
-  options?: { isStandalone?: boolean; navigationType?: NavigationType }
+  options?: { isStandalone?: boolean; navigationType?: NavigationType; baseHref?: string }
 ) {
   // Happy DOM can default to an opaque origin ("null") which breaks URL-based
   // logic in RouterContext. Give it a stable origin.
@@ -40,6 +41,17 @@ function installWindow(
   globalThis.window.localStorage.clear();
   globalThis.window.sessionStorage.clear();
 
+  if (options?.baseHref) {
+    const baseEl = globalThis.document.createElement("base");
+    baseEl.setAttribute("href", options.baseHref);
+    const head = globalThis.document.head;
+    head.insertBefore(baseEl, head.firstChild);
+  }
+
+  // RouterContext imports appBasePath which caches `document.baseURI` at
+  // module load. Force a refresh so each test starts with the correct prefix.
+  refreshAppBasePath();
+
   const navigationEntries = [
     { type: options?.navigationType ?? "navigate" } as unknown as PerformanceNavigationTiming,
   ];
@@ -64,6 +76,7 @@ describe("navigateFromSettings", () => {
     cleanup();
     globalThis.window = undefined as unknown as Window & typeof globalThis;
     globalThis.document = undefined as unknown as Document;
+    refreshAppBasePath();
   });
 
   test("restores the previous location.state when leaving settings", async () => {
@@ -135,6 +148,7 @@ describe("browser startup launch behavior", () => {
     cleanup();
     globalThis.window = undefined as unknown as Window & typeof globalThis;
     globalThis.document = undefined as unknown as Document;
+    refreshAppBasePath();
   });
 
   test("dashboard mode ignores a stale /workspace/:id URL", async () => {
@@ -217,6 +231,7 @@ describe("desktop startup route restoration", () => {
     cleanup();
     globalThis.window = undefined as unknown as Window & typeof globalThis;
     globalThis.document = undefined as unknown as Document;
+    refreshAppBasePath();
   });
 
   test("restores the last visited route when Electron boots from file:///index.html", async () => {
@@ -398,6 +413,7 @@ describe("standalone PWA startup", () => {
     cleanup();
     globalThis.window = undefined as unknown as Window & typeof globalThis;
     globalThis.document = undefined as unknown as Document;
+    refreshAppBasePath();
   });
 
   test("shows the dashboard on cold launch even if the launch URL points at a workspace", async () => {
@@ -470,3 +486,95 @@ describe("standalone PWA startup", () => {
     });
   });
 });
+
+describe("path-app proxy prefix", () => {
+  afterEach(() => {
+    cleanup();
+    globalThis.window = undefined as unknown as Window & typeof globalThis;
+    globalThis.document = undefined as unknown as Document;
+    refreshAppBasePath();
+  });
+
+  test("MemoryRouter initial route strips the proxy prefix", async () => {
+    // Cold load at a Coder app-proxy URL: the server injected a relative
+    // `<base href>` that resolves to the SPA root, so `document.baseURI` is
+    // the public prefix. MemoryRouter should see only the router-internal
+    // path (`/settings/general`), not the full public URL.
+    installWindow("https://coder.example.com/@u/ws.main/apps/mux/settings/general", {
+      baseHref: "./../",
+    });
+
+    const view = render(
+      <RouterProvider>
+        <PathnameObserver />
+      </RouterProvider>
+    );
+
+    await waitFor(() => {
+      expect(view.getByTestId("pathname").textContent).toBe("/settings/general");
+    });
+  });
+
+  test("useUrlSync preserves the proxy prefix in window.location", async () => {
+    // After a client-side navigation, the URL bar must keep the public
+    // prefix so a refresh (or a bookmarked copy) hits the proxy, not the
+    // bare backend path.
+    installWindow("https://coder.example.com/@u/ws.main/apps/mux/", {
+      baseHref: "./",
+    });
+    let latestRouter: RouterContext | null = null;
+
+    function Observer() {
+      latestRouter = useRouter();
+      return <PathnameObserver />;
+    }
+
+    render(
+      <RouterProvider>
+        <Observer />
+      </RouterProvider>
+    );
+
+    await waitFor(() => {
+      expect(latestRouter).not.toBeNull();
+    });
+
+    act(() => {
+      latestRouter!.navigateToSettings("general");
+    });
+
+    await waitFor(() => {
+      expect(window.location.pathname).toBe("/@u/ws.main/apps/mux/settings/general");
+    });
+  });
+
+  test("direct origin access (no prefix): pathname stays unprefixed", async () => {
+    // Sanity check: without an app-proxy prefix (or `<base>` that climbs to
+    // one), URL sync should behave exactly as before this fix.
+    installWindow("https://mux.example.com/", { baseHref: "./" });
+    let latestRouter: RouterContext | null = null;
+
+    function Observer() {
+      latestRouter = useRouter();
+      return <PathnameObserver />;
+    }
+
+    render(
+      <RouterProvider>
+        <Observer />
+      </RouterProvider>
+    );
+
+    await waitFor(() => {
+      expect(latestRouter).not.toBeNull();
+    });
+
+    act(() => {
+      latestRouter!.navigateToSettings("general");
+    });
+
+    await waitFor(() => {
+      expect(window.location.pathname).toBe("/settings/general");
+    });
+  });
+});
diff --git a/src/browser/contexts/RouterContext.tsx b/src/browser/contexts/RouterContext.tsx
index 2c002301b0..358fa3a9ae 100644
--- a/src/browser/contexts/RouterContext.tsx
+++ b/src/browser/contexts/RouterContext.tsx
@@ -17,6 +17,7 @@ import {
 } from "@/common/constants/storage";
 import type { WorkspaceSelection } from "@/browser/components/ProjectSidebar/ProjectSidebar";
 import { getProjectRouteId } from "@/common/utils/projectRouteId";
+import { joinAppBasePath, stripAppBasePath } from "@/browser/utils/appBasePath";
 
 export interface RouterContext {
   navigateToWorkspace: (workspaceId: string) => void;
@@ -195,7 +196,11 @@ function getInitialRoute(): string {
   // routes are special: fresh launches may ignore them, but explicit restore-style navigations
   // such as hard reload/back-forward should reopen the same chat.
   if (window.location.protocol !== "file:" && !isStorybook) {
-    const url = window.location.pathname + window.location.search;
+    // Strip any path-app proxy prefix so MemoryRouter sees the route the app
+    // knows about (e.g. `/settings`), not the full public URL
+    // (`/@user/ws.main/apps/mux/settings`). The prefix is re-applied later
+    // by `useUrlSync` when writing back to the URL bar.
+    const url = stripAppBasePath(window.location.pathname + window.location.search);
     // Only use URL if it's a valid route (starts with /, not just "/" or empty)
     if (url.startsWith("/") && url !== "/") {
       if (!url.startsWith("/workspace/")) {
@@ -259,8 +264,16 @@ function useUrlSync(): void {
     // Skip in Electron (file:// reloads always boot through index.html; we restore via localStorage above)
     if (window.location.protocol === "file:") return;
 
-    if (url !== window.location.pathname + window.location.search + window.location.hash) {
-      window.history.replaceState(null, "", url);
+    // Re-apply the app base path before writing back to the URL bar, so that
+    // `history.replaceState` preserves any path-app proxy prefix that the
+    // browser is actually served under. `pushState`/`replaceState` resolve
+    // their URL argument against the document URL (not `<base href>`), so an
+    // unprefixed router-internal path would strip the prefix on refresh.
+    const publicUrl = joinAppBasePath(url);
+    const currentUrl =
+      window.location.pathname + window.location.search + window.location.hash;
+    if (publicUrl !== currentUrl) {
+      window.history.replaceState(null, "", publicUrl);
     }
   }, [location.pathname, location.search, location.hash]);
 }
diff --git a/src/browser/utils/appBasePath.test.ts b/src/browser/utils/appBasePath.test.ts
new file mode 100644
index 0000000000..8ec677d460
--- /dev/null
+++ b/src/browser/utils/appBasePath.test.ts
@@ -0,0 +1,100 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { GlobalWindow } from "happy-dom";
+import {
+  getAppBasePath,
+  joinAppBasePath,
+  refreshAppBasePath,
+  stripAppBasePath,
+} from "./appBasePath";
+
+function installWindow(options: { href: string; baseHref?: string | null }): void {
+  const happyWindow = new GlobalWindow({ url: options.href });
+  globalThis.window = happyWindow as unknown as Window & typeof globalThis;
+  globalThis.document = happyWindow.document as unknown as Document;
+
+  if (options.baseHref !== undefined && options.baseHref !== null) {
+    const baseEl = globalThis.document.createElement("base");
+    baseEl.setAttribute("href", options.baseHref);
+    const head = globalThis.document.head;
+    head.insertBefore(baseEl, head.firstChild);
+  }
+
+  refreshAppBasePath();
+}
+
+function teardownWindow(): void {
+  globalThis.window = undefined as unknown as Window & typeof globalThis;
+  globalThis.document = undefined as unknown as Document;
+  refreshAppBasePath();
+}
+
+describe("appBasePath", () => {
+  afterEach(teardownWindow);
+
+  test("no proxy prefix: identity behavior", () => {
+    installWindow({ href: "https://mux.example.com/settings", baseHref: "./" });
+    expect(getAppBasePath()).toBe("/");
+    expect(stripAppBasePath("/settings")).toBe("/settings");
+    expect(joinAppBasePath("/settings")).toBe("/settings");
+  });
+
+  test("Coder app-proxy prefix: strips and re-applies correctly", () => {
+    // Coder serves mux at `/@user/ws.main/apps/mux/` and injects `<base href="./">`
+    // so `document.baseURI` resolves to the full public prefix.
+    installWindow({
+      href: "https://coder.example.com/@user/ws.main/apps/mux/settings",
+      baseHref: "./",
+    });
+    expect(getAppBasePath()).toBe("/@user/ws.main/apps/mux/");
+
+    // URL bar → router internal.
+    expect(stripAppBasePath("/@user/ws.main/apps/mux/settings")).toBe("/settings");
+    expect(stripAppBasePath("/@user/ws.main/apps/mux/")).toBe("/");
+    expect(stripAppBasePath("/@user/ws.main/apps/mux")).toBe("/");
+
+    // Router internal → URL bar.
+    expect(joinAppBasePath("/settings")).toBe("/@user/ws.main/apps/mux/settings");
+    expect(joinAppBasePath("/")).toBe("/@user/ws.main/apps/mux/");
+    expect(joinAppBasePath("/workspace/abc?x=1")).toBe(
+      "/@user/ws.main/apps/mux/workspace/abc?x=1"
+    );
+  });
+
+  test("nested request URL with relative-climb <base href>: recovers the public prefix", () => {
+    // When the browser hits `/@user/ws.main/apps/mux/settings/general`, the
+    // server-injected `<base href="./../">` makes `document.baseURI` resolve
+    // to the SPA root (`/@user/ws.main/apps/mux/`).
+    installWindow({
+      href: "https://coder.example.com/@user/ws.main/apps/mux/settings/general",
+      baseHref: "./../",
+    });
+    expect(getAppBasePath()).toBe("/@user/ws.main/apps/mux/");
+  });
+
+  test("stripAppBasePath: paths that don't start with the prefix pass through unchanged", () => {
+    installWindow({
+      href: "https://coder.example.com/@user/ws.main/apps/mux/",
+      baseHref: "./",
+    });
+    // An unrelated absolute path (shouldn't happen in practice, but guard
+    // against it anyway).
+    expect(stripAppBasePath("/some/other/path")).toBe("/some/other/path");
+  });
+
+  test("Electron file:// protocol: identity behavior", () => {
+    // Electron reloads always boot through index.html and restore via
+    // localStorage; there's no proxy prefix to manage.
+    installWindow({ href: "file:///index.html", baseHref: null });
+    expect(getAppBasePath()).toBe("/");
+    expect(stripAppBasePath("/workspace/abc")).toBe("/workspace/abc");
+    expect(joinAppBasePath("/workspace/abc")).toBe("/workspace/abc");
+  });
+
+  test("joinAppBasePath: root path maps to the bare prefix", () => {
+    installWindow({
+      href: "https://coder.example.com/@user/ws.main/apps/mux/",
+      baseHref: "./",
+    });
+    expect(joinAppBasePath("/")).toBe("/@user/ws.main/apps/mux/");
+  });
+});
diff --git a/src/browser/utils/appBasePath.ts b/src/browser/utils/appBasePath.ts
new file mode 100644
index 0000000000..d4155e4462
--- /dev/null
+++ b/src/browser/utils/appBasePath.ts
@@ -0,0 +1,133 @@
+/**
+ * App base path helpers for bridging MemoryRouter's origin-relative URLs and
+ * the browser's public URL bar when mux is served behind a path-rewriting
+ * reverse proxy.
+ *
+ * Background: `history.pushState(state, "", url)` and `history.replaceState`
+ * ignore `<base href>` per the HTML spec — they resolve `url` against the
+ * document URL. So when our MemoryRouter calls `replaceState(null, "", "/settings")`,
+ * a path-app proxy prefix like `/@user/ws.main/apps/mux/` is stripped from
+ * the URL bar. On refresh, the browser requests `/settings` (bypassing the
+ * proxy entirely) and 404s.
+ *
+ * Fix: the server-injected `<base href>` already climbs to the SPA root
+ * regardless of nesting depth, so `new URL(document.baseURI).pathname` gives
+ * us the public path prefix. We capture it once at module load — before any
+ * `replaceState` call can corrupt `window.location.pathname` — and use it to
+ * translate router-internal paths to public URLs and back.
+ */
+
+function isBrowserWithBase(): boolean {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return false;
+  }
+  // Electron file:// reloads always boot through index.html and restore via
+  // localStorage; no proxy prefix to manage there.
+  if (window.location.protocol === "file:") {
+    return false;
+  }
+  return true;
+}
+
+function computeAppBasePath(): string {
+  if (!isBrowserWithBase()) {
+    return "/";
+  }
+
+  // Only trust `document.baseURI` if there's an explicit `<base>` element.
+  // Without one, `baseURI` falls back to the document URL, which would make
+  // us incorrectly treat every current URL as a "proxy prefix".
+  const baseEl = document.querySelector("base[href]");
+  if (!baseEl) {
+    return "/";
+  }
+
+  try {
+    const baseUri = new URL(document.baseURI);
+    // The server-injected `<base href>` always ends in `/`, so the resolved
+    // pathname does too. Be defensive and trim a non-slash-terminated path
+    // to its parent directory.
+    const pathname = baseUri.pathname;
+    if (pathname.endsWith("/")) {
+      return pathname;
+    }
+    const lastSlash = pathname.lastIndexOf("/");
+    return lastSlash >= 0 ? pathname.slice(0, lastSlash + 1) : "/";
+  } catch {
+    return "/";
+  }
+}
+
+// Cache the base path at module load so it's captured before MemoryRouter's
+// first `useUrlSync` pass can overwrite `window.location` via `replaceState`.
+// Callers that need to refresh after DOM changes can use `refreshAppBasePath`.
+let cachedAppBasePath: string | null = null;
+
+/**
+ * Returns the app's base path (the public prefix under which mux is served),
+ * always ending in `/`. Returns `"/"` when there is no proxy prefix (direct
+ * origin access, Electron, or no `<base href>`).
+ *
+ * Cached at first call. Safe for hot paths.
+ */
+export function getAppBasePath(): string {
+  cachedAppBasePath ??= computeAppBasePath();
+  return cachedAppBasePath;
+}
+
+/**
+ * Force a recomputation of the cached base path. Intended for tests that
+ * swap `globalThis.window` between cases.
+ */
+export function refreshAppBasePath(): void {
+  cachedAppBasePath = null;
+}
+
+/**
+ * Convert a browser-URL-bar path (e.g. `/@user/ws.main/apps/mux/settings`)
+ * into a router-internal path (e.g. `/settings`). Accepts a full
+ * `pathname + search + hash` string; returns the same shape.
+ *
+ * Identity when there is no proxy prefix or when `pathWithSearchAndHash`
+ * doesn't start with the prefix.
+ */
+export function stripAppBasePath(pathWithSearchAndHash: string): string {
+  const base = getAppBasePath();
+  if (base === "/") {
+    return pathWithSearchAndHash;
+  }
+  // Base ends in "/". Match either exactly the base (e.g. "/prefix/") or
+  // the base followed by more path (e.g. "/prefix/settings").
+  const baseNoTrailing = base.slice(0, -1);
+  if (pathWithSearchAndHash === baseNoTrailing) {
+    return "/";
+  }
+  if (pathWithSearchAndHash.startsWith(base)) {
+    return "/" + pathWithSearchAndHash.slice(base.length);
+  }
+  return pathWithSearchAndHash;
+}
+
+/**
+ * Convert a router-internal path (e.g. `/settings`) into a browser-URL-bar
+ * path (e.g. `/@user/ws.main/apps/mux/settings`). Accepts a full
+ * `pathname + search + hash` string; returns the same shape.
+ *
+ * Identity when there is no proxy prefix.
+ */
+export function joinAppBasePath(routerPath: string): string {
+  const base = getAppBasePath();
+  if (base === "/") {
+    return routerPath;
+  }
+  if (routerPath === "/") {
+    return base;
+  }
+  if (!routerPath.startsWith("/")) {
+    // Defensive: router paths should always be absolute, but if a caller
+    // hands us a relative one, just append it to the base.
+    return base + routerPath;
+  }
+  // Base ends in "/", router path starts with "/", so drop one slash.
+  return base + routerPath.slice(1);
+}
diff --git a/src/node/orpc/server.test.ts b/src/node/orpc/server.test.ts
index 630d97ecd6..420b885fa5 100644
--- a/src/node/orpc/server.test.ts
+++ b/src/node/orpc/server.test.ts
@@ -6,7 +6,7 @@ import { WebSocket, WebSocketServer } from "ws";
 import { RPCLink as HTTPRPCLink } from "@orpc/client/fetch";
 import { createORPCClient } from "@orpc/client";
 import type { RouterClient } from "@orpc/server";
-import { createOrpcServer, DESKTOP_WS_PATH } from "./server";
+import { computeBaseHrefForRequestUrl, createOrpcServer, DESKTOP_WS_PATH } from "./server";
 import type { ORPCContext } from "./context";
 import type { AppRouter } from "./router";
 import { Config } from "@/node/config";
@@ -148,6 +148,23 @@ async function withProxyUriTemplateEnv<T>(
   }
 }
 
+describe("computeBaseHrefForRequestUrl", () => {
+  test("handles boundary request URLs", () => {
+    // Empty / nullish input falls through to `/` (defensive; callers always
+    // pass `req.url` which Express populates, but worth locking down).
+    expect(computeBaseHrefForRequestUrl("")).toBe("./");
+    // Hash fragments are not present in `req.url` per Node's HTTP parser,
+    // but if one ever shows up it should be tolerated (depth is counted
+    // from the path portion only).
+    expect(computeBaseHrefForRequestUrl("/a/b#anchor")).toBe("./../");
+    // Double slashes are a no-op in practice (Express normalizes them),
+    // but document the current behavior: an extra empty segment raises the
+    // depth by one. Not a correctness concern either way; pinning it here
+    // keeps the algorithm intentional rather than accidental.
+    expect(computeBaseHrefForRequestUrl("//a/b")).toBe("./../../");
+  });
+});
+
 describe("createOrpcServer", () => {
   test("serveStatic fallback does not swallow /api routes", async () => {
     // Minimal context stub - router won't be exercised by this test.
@@ -278,6 +295,44 @@ describe("createOrpcServer", () => {
     }
   });
 
+  test("SPA shell placeholder substitution is scoped to the injected <base href> attribute", async () => {
+    // Regression: an earlier revision used `replaceAll(PLACEHOLDER, …)`, which
+    // would rewrite any stray occurrence of the placeholder token elsewhere in
+    // the shell (e.g. in an inline comment, docs snippet, or code sample) and
+    // silently corrupt user content. The substitution must be scoped to the
+    // `href="…"` attribute we injected at startup.
+    const stubContext: Partial<ORPCContext> = {};
+
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "mux-placeholder-scope-"));
+    const sentinel = "sentinel:__MUX_BASE_HREF__";
+    const indexHtml = `<!doctype html><html><head><title>mux</title></head><body><!-- ${sentinel} --><div>ok</div></body></html>`;
+
+    let server: Awaited<ReturnType<typeof createOrpcServer>> | null = null;
+    try {
+      await fs.writeFile(path.join(tempDir, "index.html"), indexHtml, "utf-8");
+
+      server = await createOrpcServer({
+        host: "127.0.0.1",
+        port: 0,
+        context: stubContext as ORPCContext,
+        authToken: "test-token",
+        serveStatic: true,
+        staticDir: tempDir,
+      });
+
+      // Deep request path: the injected <base href> resolves to "./../../", but
+      // the sentinel embedded in the HTML body must survive untouched.
+      const res = await fetch(`${server.baseUrl}/a/b/c`);
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      expect(html).toContain('<base href="./../../"');
+      expect(html).toContain(sentinel);
+    } finally {
+      await server?.close();
+      await fs.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
   test("SPA shell uses a per-request relative <base href> that works under any path-stripping proxy", async () => {
     // <base href> is computed as a relative climb from the request URL back to
     // the SPA root. This is proxy-agnostic: it works for direct access, for
@@ -314,6 +369,8 @@ describe("createOrpcServer", () => {
         // Nested SPA routes climb one level per intermediate directory segment.
         { url: "/a/b", expectedBaseHref: "./../" },
         { url: "/a/b/c", expectedBaseHref: "./../../" },
+        // Deeper nested routes with trailing slash climb one more level.
+        { url: "/a/b/c/", expectedBaseHref: "./../../../" },
         // Query strings are ignored for depth computation.
         { url: "/a/b?x=1", expectedBaseHref: "./../" },
       ];
diff --git a/src/node/orpc/server.ts b/src/node/orpc/server.ts
index 8edfd5bb68..9bb73ba8dc 100644
--- a/src/node/orpc/server.ts
+++ b/src/node/orpc/server.ts
@@ -114,9 +114,7 @@ function extractBearerToken(header: string | undefined): string | null {
   return token.length ? token : null;
 }
 // Placeholder substituted per-request with the relative root for the current
-// request URL. Using a placeholder keeps the parse/serialize work out of the
-// hot path: we precompute the HTML with a placeholder once at startup and do a
-// single string replace per SPA shell response.
+// request URL. Precomputed once at startup; replaced per SPA shell response.
 const BASE_HREF_PLACEHOLDER = "__MUX_BASE_HREF__";
 
 function injectBaseHrefPlaceholder(indexHtml: string): string {
@@ -146,8 +144,9 @@ function injectBaseHrefPlaceholder(indexHtml: string): string {
  *   "/settings/"        -> "./../"
  *   "/a/b"              -> "./../"
  *   "/a/b/"             -> "./../../"
+ *   "" / nullish        -> "./" (via fallback)
  */
-function computeBaseHrefForRequestUrl(requestUrl: string): string {
+export function computeBaseHrefForRequestUrl(requestUrl: string): string {
   const pathOnly = requestUrl.split("?", 1)[0] ?? "/";
   // Count path segments excluding the leading "/". A trailing slash counts as
   // an empty final segment, which correctly raises the depth for directory-style
@@ -162,7 +161,14 @@ function computeBaseHrefForRequestUrl(requestUrl: string): string {
 
 function renderSpaShellForRequest(template: string, requestUrl: string): string {
   const baseHref = computeBaseHrefForRequestUrl(requestUrl);
-  return template.replaceAll(BASE_HREF_PLACEHOLDER, baseHref);
+  // Scope the substitution to the `href="…"` attribute we injected above.
+  // Using `replaceAll(PLACEHOLDER, …)` would also rewrite any stray occurrence
+  // of the token elsewhere in the shell (e.g. in an inline comment or code
+  // sample), which would silently corrupt user content.
+  return template.replace(
+    `href="${BASE_HREF_PLACEHOLDER}"`,
+    `href="${baseHref}"`
+  );
 }
 
 function escapeJsonForHtmlScript(value: unknown): string {
@@ -603,11 +609,9 @@ export async function createOrpcServer({
   app.use(express.urlencoded({ extended: false }));
 
   // Template for the SPA shell with a `__MUX_BASE_HREF__` placeholder in the
-  // injected `<base href>`. The placeholder is replaced per-request with a
-  // relative climb to the SPA root so mux works behind any path-rewriting
-  // reverse proxy (Coder path apps, nginx `proxy_pass http://backend/`, Traefik
-  // StripPrefix, k8s ingress rewrites, etc.) without requiring the backend to
-  // know the public prefix.
+  // injected `<base href>`, replaced per-request with a relative climb to the
+  // SPA root so mux works behind any path-rewriting reverse proxy without
+  // needing to know the public prefix.
   let spaIndexHtmlTemplate: string | null = null;
 
   // Static file serving (optional)

From 7d8e0d9efadfbcf34881d2d221b34c16657a84d3 Mon Sep 17 00:00:00 2001
From: Atif Ali <me@matifali.dev>
Date: Mon, 20 Apr 2026 14:51:34 +0000
Subject: [PATCH 3/4] chore(fmt): apply prettier formatting

---
 src/browser/contexts/RouterContext.tsx | 3 +--
 src/browser/utils/appBasePath.test.ts  | 4 +---
 src/node/orpc/server.ts                | 5 +----
 3 files changed, 3 insertions(+), 9 deletions(-)

diff --git a/src/browser/contexts/RouterContext.tsx b/src/browser/contexts/RouterContext.tsx
index 358fa3a9ae..539962a8ab 100644
--- a/src/browser/contexts/RouterContext.tsx
+++ b/src/browser/contexts/RouterContext.tsx
@@ -270,8 +270,7 @@ function useUrlSync(): void {
     // their URL argument against the document URL (not `<base href>`), so an
     // unprefixed router-internal path would strip the prefix on refresh.
     const publicUrl = joinAppBasePath(url);
-    const currentUrl =
-      window.location.pathname + window.location.search + window.location.hash;
+    const currentUrl = window.location.pathname + window.location.search + window.location.hash;
     if (publicUrl !== currentUrl) {
       window.history.replaceState(null, "", publicUrl);
     }
diff --git a/src/browser/utils/appBasePath.test.ts b/src/browser/utils/appBasePath.test.ts
index 8ec677d460..86c67f78a7 100644
--- a/src/browser/utils/appBasePath.test.ts
+++ b/src/browser/utils/appBasePath.test.ts
@@ -55,9 +55,7 @@ describe("appBasePath", () => {
     // Router internal → URL bar.
     expect(joinAppBasePath("/settings")).toBe("/@user/ws.main/apps/mux/settings");
     expect(joinAppBasePath("/")).toBe("/@user/ws.main/apps/mux/");
-    expect(joinAppBasePath("/workspace/abc?x=1")).toBe(
-      "/@user/ws.main/apps/mux/workspace/abc?x=1"
-    );
+    expect(joinAppBasePath("/workspace/abc?x=1")).toBe("/@user/ws.main/apps/mux/workspace/abc?x=1");
   });
 
   test("nested request URL with relative-climb <base href>: recovers the public prefix", () => {
diff --git a/src/node/orpc/server.ts b/src/node/orpc/server.ts
index 9bb73ba8dc..e10a501cc5 100644
--- a/src/node/orpc/server.ts
+++ b/src/node/orpc/server.ts
@@ -165,10 +165,7 @@ function renderSpaShellForRequest(template: string, requestUrl: string): string
   // Using `replaceAll(PLACEHOLDER, …)` would also rewrite any stray occurrence
   // of the token elsewhere in the shell (e.g. in an inline comment or code
   // sample), which would silently corrupt user content.
-  return template.replace(
-    `href="${BASE_HREF_PLACEHOLDER}"`,
-    `href="${baseHref}"`
-  );
+  return template.replace(`href="${BASE_HREF_PLACEHOLDER}"`, `href="${baseHref}"`);
 }
 
 function escapeJsonForHtmlScript(value: unknown): string {

From a625ef2a14bf85ae4f5ce1a913c9017c7e6738ad Mon Sep 17 00:00:00 2001
From: Atif Ali <me@matifali.dev>
Date: Mon, 20 Apr 2026 15:10:26 +0000
Subject: [PATCH 4/4] fix(server): emit slashless-root redirect to keep <base
 href> resolution correct

When a reverse proxy mounts mux at a slashless path (e.g.
`https://proxy.example.com/apps/mux`) and strips the prefix to `/`,
the browser resolves `<base href="./">` against the document URL and
drops the `mux` segment. Asset URLs then load from the wrong directory
and 404.

Emit a blocking inline script in `<head>` that upgrades slashless
app-root URLs to their trailing-slash form before the parser reaches
`<base>`. On the retried request, the corrected document URL produces
the right base href. The script only fires when the backend sees
`req.url === "/"`: deeper request paths already resolve correctly and
would be incorrectly bounced if we redirected universally.
---
 src/node/orpc/server.test.ts | 56 ++++++++++++++++++++++++++++++++++++
 src/node/orpc/server.ts      | 28 ++++++++++++++++--
 2 files changed, 82 insertions(+), 2 deletions(-)

diff --git a/src/node/orpc/server.test.ts b/src/node/orpc/server.test.ts
index 420b885fa5..a47ece1185 100644
--- a/src/node/orpc/server.test.ts
+++ b/src/node/orpc/server.test.ts
@@ -389,6 +389,62 @@ describe("createOrpcServer", () => {
     }
   });
 
+  test("SPA shell emits a slashless-root redirect script only when the request URL is '/'", async () => {
+    // When a reverse proxy mounts mux at a slashless path (e.g.
+    // `https://proxy.example.com/apps/mux`) and strips the prefix to `/`, the
+    // browser resolves `<base href="./">` against the document URL and drops
+    // the `mux` segment, breaking asset loading. A blocking inline script in
+    // `<head>` redirects to the trailing-slash form before the parser reaches
+    // `<base>`, so the corrected document URL produces the right base href on
+    // retry. The script must only fire at the app root: any deeper request
+    // path already resolves correctly, and redirecting would bounce legitimate
+    // SPA deep links.
+    const stubContext: Partial<ORPCContext> = {};
+
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "mux-slashless-redirect-"));
+    const indexHtml =
+      "<!doctype html><html><head><title>mux</title></head><body><div>ok</div></body></html>";
+
+    let server: Awaited<ReturnType<typeof createOrpcServer>> | null = null;
+    try {
+      await fs.writeFile(path.join(tempDir, "index.html"), indexHtml, "utf-8");
+
+      server = await createOrpcServer({
+        host: "127.0.0.1",
+        port: 0,
+        context: stubContext as ORPCContext,
+        authToken: "test-token",
+        serveStatic: true,
+        staticDir: tempDir,
+      });
+
+      // Marker string unique to the redirect script. Chosen so we don't match
+      // incidental occurrences of `location.replace` in user HTML.
+      const scriptMarker = 'if(!location.pathname.endsWith("/"))';
+
+      // Root request: script must be present, and it must precede `<base>` in
+      // the document so it executes before the browser resolves asset URLs.
+      const rootRes = await fetch(`${server.baseUrl}/`);
+      expect(rootRes.status).toBe(200);
+      const rootHtml = await rootRes.text();
+      expect(rootHtml).toContain(scriptMarker);
+      expect(rootHtml.indexOf(scriptMarker)).toBeLessThan(rootHtml.indexOf("<base"));
+
+      // Deeper request paths must NOT carry the redirect: `<base href="./…/">`
+      // already lands at the SPA root for these cases, and a redirect would
+      // rewrite the URL the user asked for.
+      for (const url of ["/settings", "/a/b", "/a/b/c"]) {
+        const res = await fetch(`${server.baseUrl}${url}`);
+        expect(res.status).toBe(200);
+        const html = await res.text();
+        expect(html).not.toContain(scriptMarker);
+      }
+    } finally {
+      await server?.close();
+      await fs.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
   test("does not apply origin validation to static and SPA fallback routes", async () => {
     // Static app shell must remain reachable even if proxy/header rewriting makes
     // request Origin values unexpected. API/WS/auth routes are validated separately.
diff --git a/src/node/orpc/server.ts b/src/node/orpc/server.ts
index e10a501cc5..f6f26733c3 100644
--- a/src/node/orpc/server.ts
+++ b/src/node/orpc/server.ts
@@ -117,6 +117,18 @@ function extractBearerToken(header: string | undefined): string | null {
 // request URL. Precomputed once at startup; replaced per SPA shell response.
 const BASE_HREF_PLACEHOLDER = "__MUX_BASE_HREF__";
 
+// Placeholder substituted per-request with an inline redirect script (or an
+// empty string). See `renderSpaShellForRequest` below for the full rationale.
+const SLASHLESS_ROOT_REDIRECT_PLACEHOLDER = "__MUX_SLASHLESS_ROOT_REDIRECT__";
+
+// Blocking inline script that upgrades a slashless app-root URL (e.g.
+// `https://proxy.example.com/apps/mux`) to its trailing-slash form before the
+// HTML parser reaches the `<base>` tag. Without this, the browser resolves
+// `<base href="./">` against the document URL and drops the final path
+// segment, so asset URLs like `main.js` load from the wrong directory and 404.
+const SLASHLESS_ROOT_REDIRECT_SCRIPT =
+  '<script>if(!location.pathname.endsWith("/"))location.replace(location.pathname+"/"+location.search+location.hash);</script>';
+
 function injectBaseHrefPlaceholder(indexHtml: string): string {
   // Avoid double-injecting if the HTML already has a base tag.
   if (/<base\b/i.test(indexHtml)) {
@@ -124,9 +136,12 @@ function injectBaseHrefPlaceholder(indexHtml: string): string {
   }
 
   // Insert immediately after the opening <head> tag (supports <head> and <head ...attrs>).
+  // The redirect placeholder must precede `<base>` so the script runs before
+  // the parser encounters the tag it's compensating for.
   return indexHtml.replace(
     /<head[^>]*>/i,
-    (match) => `${match}\n    <base href="${BASE_HREF_PLACEHOLDER}" />`
+    (match) =>
+      `${match}\n    ${SLASHLESS_ROOT_REDIRECT_PLACEHOLDER}\n    <base href="${BASE_HREF_PLACEHOLDER}" />`
   );
 }
 
@@ -161,11 +176,20 @@ export function computeBaseHrefForRequestUrl(requestUrl: string): string {
 
 function renderSpaShellForRequest(template: string, requestUrl: string): string {
   const baseHref = computeBaseHrefForRequestUrl(requestUrl);
+  const pathOnly = requestUrl.split("?", 1)[0] ?? "/";
+  // Only emit the slashless-root redirect at the SPA root. For any deeper
+  // request path (`/settings`, `/a/b`, …) the browser will correctly strip
+  // the final "file" segment when resolving `<base href="./…/">`, landing at
+  // the SPA root — which is what we want. Redirecting every slashless URL
+  // would bounce legitimate SPA deep links to a parent directory.
+  const redirectScript = pathOnly === "/" ? SLASHLESS_ROOT_REDIRECT_SCRIPT : "";
   // Scope the substitution to the `href="…"` attribute we injected above.
   // Using `replaceAll(PLACEHOLDER, …)` would also rewrite any stray occurrence
   // of the token elsewhere in the shell (e.g. in an inline comment or code
   // sample), which would silently corrupt user content.
-  return template.replace(`href="${BASE_HREF_PLACEHOLDER}"`, `href="${baseHref}"`);
+  return template
+    .replace(`href="${BASE_HREF_PLACEHOLDER}"`, `href="${baseHref}"`)
+    .replace(SLASHLESS_ROOT_REDIRECT_PLACEHOLDER, redirectScript);
 }
 
 function escapeJsonForHtmlScript(value: unknown): string {