fix(studio,server): unify mount path to /_studio/ for CLI, Vercel, and self-host

Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/6df1882e-39c5-45ae-ab1d-e15e4912d3aa

Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>

Author: Copilot

apps/server/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @objectstack/example-host
 
+## Unreleased
+
+### Patch Changes
+
+- **Unified Studio mount path to `/_studio/` for all deployments** (CLI embedded, Vercel, self-host).
+  - `vercel.json`: studio SPA now serves under `/_studio/:path*` with a dedicated rewrite to `/_studio/index.html`. Root `/` and bare `/_studio` redirect to `/_studio/`. Asset caching headers scoped to `/_studio/assets/*`. `VITE_BASE=/_studio/` is set in `build.env`.
+  - `scripts/build-vercel.sh`: studio dist is copied to `public/_studio/` (previously `public/`), so Vercel serves it under the same sub-path the CLI uses. This resolves the deep-link / sidebar-click routing failures that occurred when the Studio was mounted at the public root.
+
 ## 4.0.4
 
 ### Patch Changes

apps/server/scripts/build-vercel.sh

@@ -27,13 +27,16 @@ cd apps/server
 # 2. Bundle API serverless function
 node scripts/bundle-api.mjs
 
-# 3. Copy studio dist files to public/ for UI serving
-echo "[build-vercel] Copying studio dist to public/..."
+# 3. Copy studio dist files to public/_studio/ for UI serving.
+# Studio is always mounted under /_studio/ (same convention as the CLI
+# static plugin). Vite builds with base: '/_studio/' so its asset URLs
+# and router basepath are already correct for this mount point.
+echo "[build-vercel] Copying studio dist to public/_studio/..."
 rm -rf public
-mkdir -p public
+mkdir -p public/_studio
 if [ -d "../studio/dist" ]; then
-  cp -r ../studio/dist/* public/
-  echo "[build-vercel]   ✓ Copied studio dist to public/"
+  cp -r ../studio/dist/. public/_studio/
+  echo "[build-vercel]   ✓ Copied studio dist to public/_studio/"
 else
   echo "[build-vercel]   ⚠ Studio dist not found (skipped)"
 fi

apps/server/vercel.json

@@ -6,7 +6,8 @@
   "build": {
     "env": {
       "VITE_RUNTIME_MODE": "server",
-      "VITE_SERVER_URL": ""
+      "VITE_SERVER_URL": "",
+      "VITE_BASE": "/_studio/"
     }
   },
   "functions": {
@@ -17,14 +18,18 @@
   },
   "headers": [
     {
-      "source": "/assets/(.*)",
+      "source": "/_studio/assets/(.*)",
       "headers": [
         { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
       ]
     }
   ],
+  "redirects": [
+    { "source": "/", "destination": "/_studio/", "permanent": false },
+    { "source": "/_studio", "destination": "/_studio/", "permanent": false }
+  ],
   "rewrites": [
     { "source": "/api/:path*", "destination": "/api/[[...route]]" },
-    { "source": "/((?!api/).*)", "destination": "/index.html" }
+    { "source": "/_studio/:path*", "destination": "/_studio/index.html" }
   ]
 }

apps/studio/CHANGELOG.md

@@ -4,21 +4,16 @@
 
 ### Patch Changes
 
-- Fix TanStack Router basepath resolution when Studio is mounted under a sub-path
-  (e.g. `/_studio/` via the CLI `--ui` flag). Previously, routes such as
-  `/_studio/packages` or `/_studio/:package/objects/:name` failed to match —
-  the router treated the mount prefix as a `$package` route parameter, producing
-  "Not Found" errors on hard refresh and dropping the prefix on sidebar clicks
-  (`navigate({ to: '/packages' })` → `/packages`).
-
-  The router now resolves its `basepath` from (1) a runtime global
-  `window.__OBJECTSTACK_STUDIO_BASEPATH__` injected by the host server, falling
-  back to (2) Vite's `import.meta.env.BASE_URL`, then (3) `'/'`. The runtime
-  override is required because `import.meta.env.BASE_URL` is a build-time
-  constant — a pre-built dist (shipped via npm and re-hosted by the CLI static
-  plugin under `/_studio/`) would otherwise hard-code basepath as `'/'`
-  regardless of its actual mount path. The CLI's `createStudioStaticPlugin` now
-  injects the appropriate global so the same dist works at any mount point.
+- **Unified Studio mount path to `/_studio/` for all deployments.** The Vite
+  build default is now `base: '/_studio/'` (was `'./'`), baking the correct
+  absolute asset URLs and router basepath into every bundle. This removes the
+  previous build-time/runtime ambiguity that required the host server to
+  rewrite `href="/..."` URLs or inject a `window.__OBJECTSTACK_STUDIO_BASEPATH__`
+  marker.
+- `resolveBasepath()` in `src/router.ts` simplified to rely solely on Vite's
+  `import.meta.env.BASE_URL`, which now always yields `/_studio/` for
+  production bundles and CLI dev (the CLI dev server sets
+  `VITE_BASE=/_studio/`). Runtime `window` injection workaround removed.
 
 ## 4.0.4
 

apps/studio/src/router.ts

@@ -11,49 +11,20 @@ import { createRouter } from '@tanstack/react-router';
 import { routeTree } from './routeTree.gen';
 
 /**
- * Compute the router basepath for TanStack Router.
+ * Compute the router basepath from Vite's `BASE_URL`.
  *
- * When Studio is mounted under a sub-path (e.g. `/_studio/`), TanStack Router
- * must strip that prefix before matching route patterns. Otherwise URLs such
- * as `/_studio/packages` are mis-interpreted as `/$package="_studio"/packages`.
+ * Studio is always mounted under `/_studio/` — the Vite build sets
+ * `base: '/_studio/'` by default (see `vite.config.ts`), which makes
+ * `import.meta.env.BASE_URL === '/_studio/'` for every production bundle
+ * and `/_studio/` for the CLI dev server (which also sets `VITE_BASE`).
  *
- * Resolution order (first match wins):
- *
- *   1. **Runtime global `window.__OBJECTSTACK_STUDIO_BASEPATH__`** — injected
- *      into `index.html` by the host server (see `createStudioStaticPlugin`
- *      in `@objectstack/cli`) when the pre-built dist is served under a
- *      sub-path. This is the authoritative signal for *any* deployment where
- *      the same pre-built bundle is re-hosted at a different mount point —
- *      `import.meta.env.BASE_URL` is a build-time constant and cannot
- *      capture this.
- *
- *   2. **Vite `import.meta.env.BASE_URL`** — works at dev-server time when
- *      `VITE_BASE` is set (e.g. the CLI dev proxy), and for bundles that
- *      were explicitly built with a non-default `base` config.
- *
- *   3. Fallback: `'/'` (root deployment).
- *
- * TanStack Router expects the basepath WITHOUT a trailing slash (except for
- * the root `'/'`), so we normalise accordingly.
+ * TanStack Router expects the basepath WITHOUT a trailing slash (except
+ * for the root `'/'`), so we normalise accordingly.
  */
-function normalise(base: string): string {
-  const trimmed = base.trim();
-  if (!trimmed || trimmed === '/' || trimmed === './') return '/';
-  return trimmed.endsWith('/') ? trimmed.slice(0, -1) : trimmed;
-}
-
 function resolveBasepath(): string {
-  // 1. Runtime injection from host server (works for any pre-built dist)
-  if (typeof window !== 'undefined') {
-    const injected = (window as unknown as { __OBJECTSTACK_STUDIO_BASEPATH__?: string })
-      .__OBJECTSTACK_STUDIO_BASEPATH__;
-    if (typeof injected === 'string' && injected.length > 0) {
-      return normalise(injected);
-    }
-  }
-
-  // 2. Vite build-time / dev-server base
-  return normalise(import.meta.env.BASE_URL ?? '/');
+  const base = (import.meta.env.BASE_URL ?? '/').trim();
+  if (!base || base === '/' || base === './') return '/';
+  return base.endsWith('/') ? base.slice(0, -1) : base;
 }
 
 export const router = createRouter({

apps/studio/vite.config.ts

@@ -10,7 +10,7 @@ const hmrConfig = process.env.VITE_HMR_PORT
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  base: process.env.VITE_BASE || './',  // Relative base for sub-path mounting (e.g. /_studio/)
+  base: process.env.VITE_BASE || '/_studio/',  // Studio is always mounted under /_studio/ (CLI, Vercel, self-host)
   resolve: {
     dedupe: ['react', 'react-dom'],
     alias: {

packages/cli/CHANGELOG.md

@@ -4,13 +4,11 @@
 
 ### Patch Changes
 
-- `createStudioStaticPlugin` now injects
-  `<script>window.__OBJECTSTACK_STUDIO_BASEPATH__="/_studio";</script>` into the
-  rewritten `index.html`. This allows the Studio's TanStack Router to discover
-  its mount path at runtime — a pre-built Studio `dist/` (whose
-  `import.meta.env.BASE_URL` is baked in as `'./'` at build time) previously
-  hard-coded its router basepath to `'/'`, breaking deep-link refresh and
-  causing sidebar navigation to drop the `/_studio` prefix.
+- `createStudioStaticPlugin` simplified now that the Studio is always built with
+  `base: '/_studio/'`: asset URLs in `index.html` are already absolute and
+  correct, so the HTML is served verbatim (no `href="/..."` rewriting, no
+  runtime basepath script injection). Single source of truth for the mount
+  path: Vite `base`.
 
 ## 4.0.4
 

packages/cli/src/utils/studio.ts

@@ -281,26 +281,10 @@ export function createStudioStaticPlugin(distPath: string, options?: { isDev?: b
         return;
       }
 
-      // Read and rewrite index.html so asset paths respect the mount path.
-      // The dist may have been built with base '/' (absolute paths like
-      // /assets/...) which won't resolve when mounted under /_studio/.
-      //
-      // We also inject a tiny inline script that publishes the runtime
-      // basepath as `window.__OBJECTSTACK_STUDIO_BASEPATH__`. The Studio's
-      // TanStack Router reads this at boot to configure its `basepath` —
-      // without it, a pre-built bundle (whose `import.meta.env.BASE_URL`
-      // is baked in at build time) would treat the mount prefix as a
-      // route parameter and fail to resolve sub-routes.
-      const rawHtml = fs.readFileSync(indexPath, 'utf-8');
-      const withRewrittenUrls = rawHtml.replace(
-        /(\s(?:href|src))="\/(?!\/)/g,
-        `$1="${STUDIO_PATH}/`,
-      );
-      const basepathScript =
-        `<script>window.__OBJECTSTACK_STUDIO_BASEPATH__=${JSON.stringify(STUDIO_PATH)};</script>`;
-      const rewrittenHtml = withRewrittenUrls.includes('</head>')
-        ? withRewrittenUrls.replace('</head>', `${basepathScript}</head>`)
-        : `${basepathScript}${withRewrittenUrls}`;
+      // Studio is always built with `base: '/_studio/'`, so its asset URLs
+      // (and runtime router basepath) are already absolute and correct. We
+      // can serve the pre-built dist verbatim.
+      const indexHtml = fs.readFileSync(indexPath, 'utf-8');
 
       // In dev mode, redirect root to Studio for convenience
       if (options?.isDev) {
@@ -327,8 +311,8 @@ export function createStudioStaticPlugin(distPath: string, options?: { isDev?: b
           });
         }
 
-        // SPA fallback: serve rewritten index.html for non-file routes
-        return new Response(rewrittenHtml, {
+        // SPA fallback: serve index.html for non-file routes
+        return new Response(indexHtml, {
           headers: { 'content-type': 'text/html; charset=utf-8' },
         });
       });