fix(studio): resolve router basepath at runtime so pre-built dist works under /_studio/

Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/8502c67c-765c-4170-acc4-8c27a49b32b9

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

Author: Copilot

apps/studio/CHANGELOG.md

@@ -8,9 +8,17 @@
   (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. The router now derives `basepath` from Vite's
-  `import.meta.env.BASE_URL`, which works transparently for both root and
-  sub-path deployments.
+  "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.
 
 ## 4.0.4
 

apps/studio/src/router.ts

@@ -11,24 +11,49 @@ import { createRouter } from '@tanstack/react-router';
 import { routeTree } from './routeTree.gen';
 
 /**
- * Compute the router basepath from Vite's `BASE_URL`.
+ * Compute the router basepath for TanStack Router.
  *
- * When Studio is mounted under a sub-path (e.g. `/_studio/` via the CLI `--ui`
- * flag, which sets `VITE_BASE=/_studio/`), TanStack Router must strip that
- * prefix before matching route patterns. Otherwise URLs such as
- * `/_studio/packages` are mis-interpreted as `/$package="_studio"/packages`.
+ * 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`.
  *
- * Vite exposes the configured base as `import.meta.env.BASE_URL`:
- *   - Root deployment: `'/'` → basepath `'/'` (no-op)
- *   - Sub-path deployment: `'/_studio/'` → basepath `'/_studio'`
+ * 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.
  */
+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 {
-  const base = (import.meta.env.BASE_URL ?? '/').trim();
-  if (!base || base === '/' || base === './') return '/';
-  return base.endsWith('/') ? base.slice(0, -1) : base;
+  // 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 ?? '/');
 }
 
 export const router = createRouter({

packages/cli/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @objectstack/cli
 
+## Unreleased
+
+### 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.
+
 ## 4.0.4
 
 ### Patch Changes

packages/cli/src/utils/studio.ts

@@ -284,11 +284,23 @@ export function createStudioStaticPlugin(distPath: string, options?: { isDev?: b
       // 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 rewrittenHtml = rawHtml.replace(
+      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}`;
 
       // In dev mode, redirect root to Studio for convenience
       if (options?.isDev) {