catalyst-core 0.3.0-beta.3 → 0.3.0-beta.5

package/dist/index.jsx

@@ -1,4 +1,4 @@
-export * from "react-router-dom"
+export * from "react-router"
 export * from "./web-router/components/RouterDataProvider.jsx"
 export * from "./web-router/components/MetaTag.jsx"
 export { split, hydrationReady } from "./web-router/components/Split.jsx"

package/dist/native/bridge/hooks/useNativeTransition.js

@@ -5,7 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useNativeTransition = void 0;
 var _react = require("react");
-var _reactRouterDom = require("react-router-dom");
+var _reactRouter = require("react-router");
 var _NativeBridge = _interopRequireDefault(require("../utils/NativeBridge.js"));
 var _NativeInterfaces = require("../constants/NativeInterfaces.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
@@ -34,7 +34,7 @@ const MIN_TIMEOUT = 800;
  *   timeout: ms safety timer (default: max(duration*3, 800))
  */
 const useNativeTransition = (defaults = {}) => {
-  const router = (0, _reactRouterDom.useNavigate)();
+  const router = (0, _reactRouter.useNavigate)();
   const isNative = typeof window !== "undefined" && _NativeBridge.default.isAvailable();
   const [transitioning, setTransitioning] = (0, _react.useState)(false);
   const overlayRef = (0, _react.useRef)(null);

package/dist/server/expressServer.js

@@ -10,6 +10,7 @@ import pc from "picocolors"
 import fs from "fs"
 const { cyan, yellow, green } = pc
 
+import { toMountPathPrefix } from "../vite/resolveDevServerConfig.js"
 import { validateMiddleware, safeCall } from "./utils/validator.js"
 import { botDetectionMiddleware } from "./utils/botDetectionMiddleware.js"
 import { cjsRequire } from "./utils/cjsRequire.js"
@@ -208,6 +209,12 @@ async function createServer() {
             appType: "custom",
             root: process.env.src_path,
         })
+
+        // Expose Vite's resolved base to the SSR renderer so the URLs it injects
+        // (client entry, react-refresh preamble) match the path Vite serves under.
+        // Vite normalizes base with a trailing slash; trim it for clean URL joins.
+        process.env.APP_MOUNT_PATH = toMountPathPrefix(vite.config.base)
+
         app.use(vite.middlewares)
     }
 

package/dist/server/renderer/document/Body.jsx

@@ -30,7 +30,10 @@ export function Body(props) {
                     __html: `window.__SAFE_AREA_INITIAL__ = ${JSON.stringify(safeArea)}; window.__CATALYST_NATIVE_WEBVIEW__ = ${nativeWebView ? "true" : "false"}`,
                 }}
             />
-            {process.env.NODE_ENV === "development" && <script type="module" src="/client/index.js"></script>}
+            {process.env.NODE_ENV === "development" && (
+                // Base pinned to Vite's resolved base by server/expressServer.js.
+                <script type="module" src={`${process.env.APP_MOUNT_PATH || ""}/client/index.js`}></script>
+            )}
             {jsx}
             <script
                 /* eslint-disable */

package/dist/server/renderer/handler.jsx

@@ -4,7 +4,7 @@ import { Provider } from "react-redux"
 import { Body } from "./document/Body.jsx"
 import { Head } from "./document/Head.jsx"
 
-import { StaticRouter } from "react-router-dom/server"
+import { StaticRouter } from "react-router"
 import ServerRouter from "../../router/ServerRouter.js"
 import { renderToPipeableStream } from "react-dom/server"
 import { getUserAgentDetails } from "../utils/userAgentUtil.js"

package/dist/vite/FastRefresh.jsx

@@ -6,8 +6,10 @@ const FastRefresh = () => {
             type="module"
             // eslint-disable-next-line risxss/catch-potential-xss-react
             dangerouslySetInnerHTML={{
+                // Base-prefixed so the preamble resolves under a sub-path; otherwise
+                // plugin-react modules throw "$RefreshSig$ is not defined".
                 __html: `
-        import { injectIntoGlobalHook } from "/@react-refresh";
+        import { injectIntoGlobalHook } from "${process.env.APP_MOUNT_PATH || ""}/@react-refresh";
         injectIntoGlobalHook(window);
         window.$RefreshReg$ = () => {};
         window.$RefreshSig$ = () => (type) => type;

package/dist/vite/loadCustomViteConfig.js

@@ -5,6 +5,34 @@ import { pathToFileURL } from "url"
 const emptyConfig = {
     ssrPlugins: [],
     clientPlugins: [],
+    /**
+     * devServer lets apps tune the Vite dev server without editing framework
+     * internals.  All fields are optional and map 1-to-1 onto Vite's `server`
+     * config (https://vite.dev/config/server-options).
+     *
+     * The most common use-case is an app served under a sub-path behind an SSL
+     * reverse proxy (nginx/caddy):
+     *
+     *   // buildConfig.js
+     *   export default {
+     *     devServer: {
+     *       // Vite's base path — the single source of truth for the dev mount
+     *       // path; must match the reverse-proxy location prefix. Defaults to "/".
+     *       base: "/o-mweb",
+     *
+     *       // HMR WebSocket tuning when the browser connects via the proxy
+     *       hmr: {
+     *         clientPort: 443,   // port the browser uses (proxy's SSL port)
+     *         path: "__vite_hmr" // WebSocket pathname (relative to base)
+     *       },
+     *
+     *       // Vite 6 rejects requests whose Host header isn't localhost/127.0.0.1.
+     *       // Add your proxy hostname here so the dev server accepts them.
+     *       allowedHosts: ["local.odinweb.1mg.com"],
+     *     },
+     *   }
+     */
+    devServer: {},
 }
 
 export async function loadCustomViteConfig() {

package/dist/vite/node-loader.mjs

@@ -308,9 +308,37 @@ function isValidExportName(name) {
 // Loader-scoped require for discovering CJS exports
 const loaderRequire = createRequire(import.meta.url)
 
-const CJS_PATTERN = /\b(module\.exports\b|exports\.\w+\s*=)/
 const REQUIRE_CALL_PATTERN = /\brequire\s*\(/
 
+/**
+ * Decide whether a source file is really CommonJS by parsing it, not by
+ * regex-matching the raw text.
+ *
+ * A regex like /module\.exports\b/ cannot tell code from text, so any file that
+ * merely *mentions* module.exports inside a string, comment or template literal
+ * was misclassified as CJS. When such a file was real ESM with its own
+ * `export default`, the CJS shim appended a second one and Node failed the
+ * module with "Duplicate export of 'default'". Docs sites hit this constantly:
+ * a Markdown page documenting a CJS config compiles into a string literal in
+ * the bundled ESM output. Do not reintroduce source-regex detection.
+ *
+ * esbuild parses properly and lowers CJS itself, so a file it wraps in its
+ * __commonJS helper had no ESM syntax of its own — that is the CJS signal.
+ */
+function isCjsSource(source, filePath) {
+    try {
+        const { code } = transformSync(source, {
+            loader: "jsx",
+            format: "esm",
+            sourcefile: filePath,
+            target: "node20",
+        })
+        return /\bvar __commonJS =/.test(code)
+    } catch {
+        return false
+    }
+}
+
 // Shim __dirname and __filename for ESM app files (these globals only exist in CJS)
 const createDirnameShim = (source) => {
     const hasFilename = /\b(?:const|let|var)\s+__filename\b/.test(source)
@@ -396,7 +424,7 @@ export async function load(url, context, defaultLoad) {
         // We can't use createRequire here because the file lives in a "type":"module"
         // package — Node's CJS require refuses to load it. Instead, we wrap the
         // source inline so that `module.exports` becomes the default export.
-        if (CJS_PATTERN.test(source)) {
+        if (isCjsSource(source, filePath)) {
             const shimmed = [
                 createRequireShim(source),
                 createDirnameShim(source),

package/dist/vite/resolveDevServerConfig.js

@@ -0,0 +1,45 @@
+// Pure resolvers for the Vite dev-server config derived from an app's
+// `buildConfig.devServer`. Side-effect free so the base precedence and the fs
+// allowlist merge can be unit-tested without spinning up Vite.
+
+/**
+ * Vite `base` for the dev server. `buildConfig.devServer.base` is the single
+ * source of truth (default "/"). Normalized to a leading slash and no trailing
+ * slash so it doubles as a URL prefix for the SSR renderer.
+ */
+export function resolveDevBase(devServer = {}) {
+    const base = devServer?.base
+    if (!base || base === "/") return "/"
+    return `/${String(base).trim().replace(/^\/+|\/+$/g, "")}`
+}
+
+/**
+ * A resolved base as a URL prefix. Root ("/") becomes "" so
+ * `${prefix}/client/index.js` stays single-slashed.
+ */
+export function toMountPathPrefix(base) {
+    return !base || base === "/" ? "" : String(base).replace(/\/+$/, "")
+}
+
+/**
+ * fs.allow for the dev server. Framework paths are always present; apps may
+ * extend the list via `devServer.fs.allow` but cannot replace it or relax other
+ * fs guards (e.g. `strict`), so buildConfig can't widen filesystem exposure.
+ */
+export function resolveDevFsAllow(devFs, frameworkPaths) {
+    const extra = Array.isArray(devFs?.allow) ? devFs.allow : []
+    return [...frameworkPaths, ...extra]
+}
+
+/**
+ * Vite `server` block from `buildConfig.devServer`. Passthrough keys are spread
+ * first so the framework-owned `hmr` and `fs` always win.
+ */
+export function buildDevServer(devServer = {}, { frameworkPaths, isProduction = false } = {}) {
+    const { base, hmr, fs, ...serverOverrides } = devServer
+    return {
+        ...serverOverrides,
+        hmr: isProduction ? false : (hmr ?? true),
+        fs: { allow: resolveDevFsAllow(fs, frameworkPaths) },
+    }
+}

package/dist/vite/vite.config.client.js

@@ -1,7 +1,7 @@
 import loadEnvironmentVariables from "../scripts/loadEnvironmentVariables.js"
 loadEnvironmentVariables()
 import { defineConfig } from "vite"
-import baseConfig, { getClientEnvVariables } from "./vite.config.js"
+import { sharedViteConfig as baseConfig, getClientEnvVariables } from "./vite.config.js"
 import path from "path"
 import { manifestCategorizationPlugin } from "./manifest-categorization-plugin.js"
 import { injectCacheKeyPlugin } from "./inject-cache-key-plugin.js"

package/dist/vite/vite.config.js

@@ -2,6 +2,8 @@ import { defineConfig, transformWithEsbuild } from "vite"
 import react from "@vitejs/plugin-react"
 import svgr from "vite-plugin-svgr"
 import { builtinModules, createRequire } from "node:module"
+import { loadCustomViteConfig } from "./loadCustomViteConfig.js"
+import { resolveDevBase, buildDevServer } from "./resolveDevServerConfig.js"
 
 /**
  * Treat all .scss imports as CSS modules (webpack compat).
@@ -286,6 +288,7 @@ const browserOptimizeDeps = [
     "react-dom",
     "react-dom/client",
     "react-redux",
+    "react-router",
     "react-router-dom",
     "redux",
     "redux-thunk",
@@ -362,7 +365,10 @@ export const isNodeOnlyExternal = (id) =>
     id === "@grpc/grpc-js" ||
     id.startsWith("@opentelemetry/")
 
-export default defineConfig({
+// ─── Shared config ────────────────────────────────────────────────────────────
+// Exported for the production build (vite.config.client.js spreads this in).
+// Does NOT include `base` or `server` — those differ between dev and prod.
+export const sharedViteConfig = {
     // Parallel `vite build` (SSR + client) must use separate dirs or Vite will block on shared `node_modules/.vite`.
     cacheDir: path.join(
         process.env.src_path,
@@ -391,6 +397,7 @@ export default defineConfig({
             exclude: [
                 "react",
                 "react-dom",
+                "react-router",
                 "react-router-dom",
                 "@tata1mg/router",
                 // "@tata1mg/slowoi-react",
@@ -422,8 +429,15 @@ export default defineConfig({
     resolve: {
         alias: alias(),
         // Ensure only one copy of React-related packages is used (prevents
-        // duplicate instances from hoisted/linked packages in monorepos)
-        dedupe: ["react", "react-dom", "react-router-dom", "@tata1mg/slowboi-react"],
+        // duplicate instances from hoisted/linked packages in monorepos).
+        // NOTE: react-router deliberately excluded from dedupe. Consumer apps
+        // that still have an older react-router (e.g. v6, hoisted transitively
+        // through another dependency) at their own node_modules root would
+        // have that copy forced onto catalyst-core's v7 import too, silently
+        // resolving to the wrong package version (wrong export list, e.g.
+        // missing StaticRouter/Link) instead of an error. See tata1mg/1mg_web
+        // fix/react-router-v7-upgrade-staging for the confirmed repro.
+        dedupe: ["react", "react-dom", "react-router-dom"],
     },
     define: {
         ...getClientEnvVariables(),
@@ -488,17 +502,34 @@ export default defineConfig({
         "**/*.woff2",
     ],
 
-    // Server configuration
-    server: {
-        hmr: !isProduction,
-        fs: {
-            allow: [process.env.src_path, __dirname],
-        },
-    },
-
     // Preview configuration for production preview
     preview: {
         port: process.env.NODE_SERVER_PORT ? parseInt(process.env.NODE_SERVER_PORT) : 3005,
         host: process.env.NODE_SERVER_HOSTNAME || "localhost",
     },
+}
+
+// ─── Dev server config ────────────────────────────────────────────────────────
+// Async factory so it can read the app's buildConfig.devServer for `base`, HMR
+// and other Vite server options. `base` comes solely from devServer.base; the
+// resolved value is propagated to the SSR renderer by server/expressServer.js.
+// The production build (vite.config.client.js) ignores this and spreads
+// sharedViteConfig directly.
+export default defineConfig(async () => {
+    const { devServer = {}, ssrPlugins = [] } = await loadCustomViteConfig()
+
+    return {
+        ...sharedViteConfig,
+        base: resolveDevBase(devServer),
+        server: buildDevServer(devServer, {
+            frameworkPaths: [process.env.src_path, __dirname],
+            isProduction,
+        }),
+        // Apply the app's SSR plugins in dev too — the production build already
+        // does this in vite.config.server.js. This lets buildConfig.ssrPlugins
+        // inject SSR-only config (e.g. a plugin whose `config()` hook adds
+        // ssr.noExternal to bundle React-consuming deps so dev SSR shares the
+        // app's single React instance) without hardcoding anything in the framework.
+        plugins: [...(sharedViteConfig.plugins || []), ...ssrPlugins],
+    }
 })

package/dist/vite/vite.config.server.js

@@ -1,7 +1,11 @@
 import loadEnvironmentVariables from "../scripts/loadEnvironmentVariables.js"
 loadEnvironmentVariables()
 import { defineConfig } from "vite"
-import baseConfig, { getClientEnvVariables, isNodeOnlyExternal } from "./vite.config.js"
+// Spread the static shared config (a plain object), NOT the default export —
+// the default export is now an async dev-server factory function, and spreading
+// a function would silently drop cacheDir, resolve aliases, css, plugins and
+// build from the production SSR bundle. Mirrors vite.config.client.js.
+import { sharedViteConfig as baseConfig, getClientEnvVariables, isNodeOnlyExternal } from "./vite.config.js"
 import path from "path"
 import { fileURLToPath } from "url"
 import { dirname } from "path"

package/dist/web-router/components/MetaTag.jsx

@@ -3,7 +3,7 @@ import { HelmetProvider, Helmet } from "react-helmet-async"
 import { OneMgRouterContext } from "../context.jsx"
 import { useRouterData } from "./RouterDataProvider.jsx"
 import { deleteHeadTagsByDataAttribute, getMetaData } from "../utils/metaDataUtils.jsx"
-import { useLocation } from "react-router-dom"
+import { useLocation } from "react-router"
 
 /**
  * @description renders meta tags component assigned to setMetaData

package/dist/web-router/components/RouterDataProvider.jsx

@@ -7,7 +7,7 @@ import {
     useSearchParams,
     UNSAFE_RouteContext,
     matchRoutes,
-} from "react-router-dom"
+} from "react-router"
 import { OneMgRouterContext } from "../context.jsx"
 // import sanitizeHtml from "sanitize-html"
 
@@ -41,15 +41,15 @@ const INITIAL_DATA_STATE = {
 /**
  * @typedef RouterFetcherProps
  * @property {any} route route object
- * @property {import("react-router-dom").Location} location the current location object, which represents the current URL in web browsers.
- * @property {import("react-router-dom").Params} params object of key/value pairs of the dynamic params from the current URL that were matched by the route path.
+ * @property {import("react-router").Location} location the current location object, which represents the current URL in web browsers.
+ * @property {import("react-router").Params} params object of key/value pairs of the dynamic params from the current URL that were matched by the route path.
  * @property {URLSearchParams} searchParams search parameters via URLSearchParams interface.
- * @property {import("react-router-dom").NavigateFunction} navigate function to navigate to other pages based on response.
+ * @property {import("react-router").NavigateFunction} navigate function to navigate to other pages based on response.
  */
 
 /**
  * @typedef ServerFetchDataProps
- * @property {import("react-router-dom").RouteObject[]} routes routes Array
+ * @property {import("react-router").RouteObject[]} routes routes Array
  * @property {string} url current url
  * @property {import("express").Request} req Express request object
  */
@@ -139,7 +139,7 @@ const fetchRouteData = async (routerProps, fetcherArgs, refetchArgs) => {
 /**
  *
  * @param {RouteContextObject} routeContext route context object
- * @returns {import('react-router-dom').RouteMatch[]} Array of matched routes
+ * @returns {import('react-router').RouteMatch[]} Array of matched routes
  */
 const getMatchedRoutes = ({ matches, outlet }) => {
     if (outlet) {
@@ -150,7 +150,7 @@ const getMatchedRoutes = ({ matches, outlet }) => {
 
 /**
  * Generates route key for given route using pathname and query params
- * @param {import('react-router-dom').RouteMatch} match Router Match Object
+ * @param {import('react-router').RouteMatch} match Router Match Object
  * @param {string} searchParamsString Query params string
  * @returns {string} routerKey
  */
@@ -190,7 +190,7 @@ export const RouterDataProvider = ({ children, initialState, fetcherArgs = {}, c
 
     /**
      * @description HOF which returns a function to refetch the route data
-     * @param {import("react-router-dom").RouteObject} route
+     * @param {import("react-router").RouteObject} route
      * @param {string} routeKey
      * @returns
      */
@@ -214,7 +214,7 @@ export const RouterDataProvider = ({ children, initialState, fetcherArgs = {}, c
 
     /**
      * @description HOF which returns a function to clear the route data immediately or after given time in ms
-     * @param {import("react-router-dom").RouteObject} route
+     * @param {import("react-router").RouteObject} route
      * @param {string} routeKey
      * @returns
      */
@@ -235,7 +235,7 @@ export const RouterDataProvider = ({ children, initialState, fetcherArgs = {}, c
 
     /**
      * @description Check the config for refetching the data
-     * @param {import('react-router-dom').RouteObject} route
+     * @param {import('react-router').RouteObject} route
      * @returns {boolean}
      */
     const shouldFetch = (route) => {

package/dist/web-router/context.jsx

@@ -2,7 +2,7 @@ import { createContext } from "react"
 
 /**
  * @typedef oneMgRouterContext
- * @property {import("react-router-dom").RouteMatch<string, import("react-router-dom").RouteObject>[]=} matchedRoutes
+ * @property {import("react-router").RouteMatch<string, import("react-router").RouteObject>[]=} matchedRoutes
  */
 
 /**

package/dist/web-router/hooks.jsx

@@ -1,4 +1,4 @@
-import { useNavigate, useLocation } from "react-router-dom"
+import { useNavigate, useLocation } from "react-router"
 
 /**
  * @param {number} delay

package/dist/web-router/types/components/RouterDataProvider.d.ts

@@ -47,11 +47,11 @@ export type RouterFetcherProps = {
     /**
      * the current location object, which represents the current URL in web browsers.
      */
-    location: import("react-router-dom").Location
+    location: import("react-router").Location
     /**
      * object of key/value pairs of the dynamic params from the current URL that were matched by the route path.
      */
-    params: import("react-router-dom").Params
+    params: import("react-router").Params
     /**
      * search parameters via URLSearchParams interface.
      */
@@ -59,13 +59,13 @@ export type RouterFetcherProps = {
     /**
      * function to navigate to other pages based on response.
      */
-    navigate: import("react-router-dom").NavigateFunction
+    navigate: import("react-router").NavigateFunction
 }
 export type ServerFetchDataProps = {
     /**
      * routes Array
      */
-    routes: import("react-router-dom").RouteObject[]
+    routes: import("react-router").RouteObject[]
     /**
      * current url
      */

package/dist/web-router/types/context.d.ts

@@ -1,6 +1,6 @@
 /**
  * @typedef oneMgRouterContext
- * @property {import("react-router-dom").RouteMatch<string, import("react-router-dom").RouteObject>[]=} matchedRoutes
+ * @property {import("react-router").RouteMatch<string, import("react-router").RouteObject>[]=} matchedRoutes
  */
 /**
  * @description This is internal context made for sharing data among router components
@@ -9,6 +9,6 @@
 export const OneMgRouterContext: import("react").Context<oneMgRouterContext>
 export type oneMgRouterContext = {
     matchedRoutes?:
-        | import("react-router-dom").RouteMatch<string, import("react-router-dom").RouteObject>[]
+        | import("react-router").RouteMatch<string, import("react-router").RouteObject>[]
         | undefined
 }

package/dist/web-router/types/hooks.d.ts

@@ -1 +1 @@
-export function useNavigateWithTransition(): import("react-router-dom").NavigateFunction
+export function useNavigateWithTransition(): import("react-router").NavigateFunction

package/dist/web-router/types/index.d.ts

@@ -1,3 +1,3 @@
-export * from "react-router-dom"
+export * from "react-router"
 declare const _default: any
 export default _default

package/dist/web-router/types/utils/metaDataUtils.d.ts

@@ -22,3 +22,19 @@ export function deleteHeadTagsByDataAttribute(attributeName: string, attributeVa
  * @returns {Array<JSX.Element>} - List of all meta tags for the matched location.
  */
 export function getMetaData(matchedRoutes: Array<Match>, routeData: Object): Array<JSX.Element>
+/**
+ * Static function defined on a route component that returns metadata elements
+ * to be rendered in the document head for that route.
+ * Must return an array of JSX elements (e.g. <title>, <meta>), NOT a plain
+ * object. Returning an object fails silently: no error is thrown, but the
+ * tags will not appear in the rendered <head>.
+ *
+ * @param {any} fetcherData - Data returned from the route's fetcher (serverFetcher/clientFetcher).
+ * @returns {Array<JSX.Element>} - Array of JSX head elements (title, meta, link, etc).
+ *
+ * @example
+ * HomePage.setMetaData = (apiResponse) => [
+ *   <title key="title">{apiResponse?.title || "Home"}</title>,
+ * ];
+ */
+export type SetMetaData = (fetcherData: any) => Array<JSX.Element>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "catalyst-core",
-    "version": "0.3.0-beta.3",
+    "version": "0.3.0-beta.5",
     "type": "module",
     "main": "./dist/index.jsx",
     "description": "Web framework that provides great performance out of the box",
@@ -30,6 +30,7 @@
     "scripts": {
         "lint": "eslint .",
         "lint-staged": "lint-staged",
+        "test:unit": "node --test \"test/**/*.test.js\"",
         "prettify": "prettier . --write",
         "prepare": "node ../../scripts/safe-rimraf.js ./dist && cp -r ./src ./dist && babel src/native --out-dir dist/native --config-file ./babel.native.config.cjs --ignore '**/.build/**' && babel src/sentry.js --out-file dist/sentry.cjs --config-file ./babel.native.config.cjs",
         "prepublishOnly": "npm run prepare",
@@ -49,7 +50,7 @@
         "react-helmet-async": "^1.3.0",
         "react-redux": "^9.2.0",
         "react-refresh": "^0.14.0",
-        "react-router-dom": "^6.16.0",
+        "react-router": "^7.18.2",
         "redux": "^4.2.1",
         "sanitize-html": "^2.17.6",
         "sass": "^1.89.2",

package/test/vite/resolveDevServerConfig.test.js

@@ -0,0 +1,113 @@
+import { test } from "node:test"
+import assert from "node:assert/strict"
+
+import {
+    resolveDevBase,
+    toMountPathPrefix,
+    resolveDevFsAllow,
+    buildDevServer,
+} from "../../src/vite/resolveDevServerConfig.js"
+
+// ─── resolveDevBase ───────────────────────────────────────────────────────────
+
+test("resolveDevBase: resolves from devServer.base", () => {
+    assert.equal(resolveDevBase({ base: "/o-mweb" }), "/o-mweb")
+})
+
+test("resolveDevBase: defaults to '/' when base is unset", () => {
+    assert.equal(resolveDevBase({}), "/")
+    assert.equal(resolveDevBase(undefined), "/")
+    assert.equal(resolveDevBase({ base: "/" }), "/")
+})
+
+test("resolveDevBase: normalizes to a leading slash, no trailing slash", () => {
+    assert.equal(resolveDevBase({ base: "o-mweb" }), "/o-mweb")
+    assert.equal(resolveDevBase({ base: "/o-mweb/" }), "/o-mweb")
+    assert.equal(resolveDevBase({ base: "  /o-mweb//  " }), "/o-mweb")
+})
+
+// ─── toMountPathPrefix ────────────────────────────────────────────────────────
+
+test("toMountPathPrefix: root maps to empty string for clean URL joins", () => {
+    assert.equal(toMountPathPrefix("/"), "")
+    assert.equal(toMountPathPrefix(""), "")
+    assert.equal(toMountPathPrefix(undefined), "")
+})
+
+test("toMountPathPrefix: trims Vite's trailing slash", () => {
+    assert.equal(toMountPathPrefix("/o-mweb/"), "/o-mweb")
+    assert.equal(toMountPathPrefix("/o-mweb"), "/o-mweb")
+    // The joined result stays single-slashed.
+    assert.equal(`${toMountPathPrefix("/o-mweb/")}/client/index.js`, "/o-mweb/client/index.js")
+    assert.equal(`${toMountPathPrefix("/")}/client/index.js`, "/client/index.js")
+})
+
+// ─── resolveDevFsAllow: security-sensitive allowlist merge ─────────────────────
+
+const FRAMEWORK = ["/app/src", "/framework/dist/vite"]
+
+test("resolveDevFsAllow: framework paths always present, none provided", () => {
+    assert.deepEqual(resolveDevFsAllow(undefined, FRAMEWORK), FRAMEWORK)
+    assert.deepEqual(resolveDevFsAllow({}, FRAMEWORK), FRAMEWORK)
+})
+
+test("resolveDevFsAllow: apps may EXTEND but never drop framework paths", () => {
+    const result = resolveDevFsAllow({ allow: ["/extra/pkg"] }, FRAMEWORK)
+    assert.deepEqual(result, ["/app/src", "/framework/dist/vite", "/extra/pkg"])
+})
+
+test("resolveDevFsAllow: non-array allow is ignored (no widening via bad input)", () => {
+    assert.deepEqual(resolveDevFsAllow({ allow: "/" }, FRAMEWORK), FRAMEWORK)
+    assert.deepEqual(resolveDevFsAllow({ allow: null }, FRAMEWORK), FRAMEWORK)
+})
+
+// ─── buildDevServer: precedence + security ────────────────────────────────────
+
+test("buildDevServer: hmr defaults to true in dev", () => {
+    const server = buildDevServer({}, { frameworkPaths: FRAMEWORK, isProduction: false })
+    assert.equal(server.hmr, true)
+})
+
+test("buildDevServer: hmr is false in production", () => {
+    const server = buildDevServer({ hmr: { clientPort: 443 } }, { frameworkPaths: FRAMEWORK, isProduction: true })
+    assert.equal(server.hmr, false)
+})
+
+test("buildDevServer: app hmr overrides are honored in dev", () => {
+    const hmr = { clientPort: 443, path: "__vite_hmr" }
+    const server = buildDevServer({ hmr }, { frameworkPaths: FRAMEWORK, isProduction: false })
+    assert.deepEqual(server.hmr, hmr)
+})
+
+test("buildDevServer: passthrough keys (proxy/allowedHosts) are forwarded", () => {
+    const server = buildDevServer(
+        { allowedHosts: ["local.example.com"], proxy: { "/api": "http://localhost:9000" } },
+        { frameworkPaths: FRAMEWORK, isProduction: false }
+    )
+    assert.deepEqual(server.allowedHosts, ["local.example.com"])
+    assert.deepEqual(server.proxy, { "/api": "http://localhost:9000" })
+})
+
+test("buildDevServer: app fs cannot replace the allowlist, only extend it", () => {
+    const server = buildDevServer(
+        { fs: { allow: ["/extra"] } },
+        { frameworkPaths: FRAMEWORK, isProduction: false }
+    )
+    assert.deepEqual(server.fs.allow, ["/app/src", "/framework/dist/vite", "/extra"])
+})
+
+test("buildDevServer: app cannot relax fs.strict or clobber fs via overrides", () => {
+    const server = buildDevServer(
+        { fs: { allow: ["/"], strict: false } },
+        { frameworkPaths: FRAMEWORK, isProduction: false }
+    )
+    // strict is dropped entirely (framework keeps Vite's secure default), and
+    // the framework paths remain — "/" is merely appended, not a replacement.
+    assert.equal(server.fs.strict, undefined)
+    assert.ok(server.fs.allow.includes("/app/src"))
+})
+
+test("buildDevServer: 'base' is not leaked into the server block", () => {
+    const server = buildDevServer({ base: "/o-mweb" }, { frameworkPaths: FRAMEWORK, isProduction: false })
+    assert.equal(server.base, undefined)
+})