catalyst-core 1.0.1 → 1.0.2-canary.1

package/dist/errors/registry.js

@@ -22,6 +22,7 @@ export const ERROR_CODES = {
     PREFLIGHT_GET_ROUTES_NOT_FUNCTION: "PREFLIGHT-019",
     PREFLIGHT_CUSTOM_DOCUMENT_MISSING: "PREFLIGHT-020",
     PREFLIGHT_CUSTOM_DOCUMENT_NOT_FUNCTION: "PREFLIGHT-021",
+    PREFLIGHT_BUILD_STALE: "PREFLIGHT-022",
 
     PROCESS_SERVER_INIT_FAILED: "PROCESS-001",
     PROCESS_USER_HOOK_FAILED: "PROCESS-002",
@@ -204,6 +205,13 @@ export const ERROR_DEFINITIONS = {
         defaultDetails: "document was found but is not a function/component.",
         suggestedAction: "Ensure document is exported as a React component (function).",
     },
+    [ERROR_CODES.PREFLIGHT_BUILD_STALE]: {
+        category: "PREFLIGHT",
+        defaultMessage: "The build is stale: config/config.json changed since it was built",
+        defaultDetails:
+            "PUBLIC_STATIC_ASSET_URL, PUBLIC_STATIC_ASSET_PATH and the CLIENT_ENV_VARIABLES values are inlined into the bundles at build time, so serving this build would use the old values.",
+        suggestedAction: "Run `npm run build` again, then `npm run serve`.",
+    },
 
     [ERROR_CODES.PROCESS_SERVER_INIT_FAILED]: {
         category: "PROCESS",

package/dist/errors-index.json

@@ -216,6 +216,13 @@
         "suggestedAction": "Ensure document is exported as a React component (function).",
         "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/PREFLIGHT/PREFLIGHT-021.md"
     },
+    "PREFLIGHT-022": {
+        "category": "PREFLIGHT",
+        "message": "The build is stale: config/config.json changed since it was built",
+        "details": "PUBLIC_STATIC_ASSET_URL, PUBLIC_STATIC_ASSET_PATH and the CLIENT_ENV_VARIABLES values are inlined into the bundles at build time, so serving this build would use the old values.",
+        "suggestedAction": "Run `npm run build` again, then `npm run serve`.",
+        "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/PREFLIGHT/PREFLIGHT-022.md"
+    },
     "PROCESS-001": {
         "category": "PROCESS",
         "message": "preServerInit threw an error during server startup",

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { RouterDataProvider, useCurrentRouteData, useRouterData, } from "./web-router/components/RouterDataProvider.jsx";
+export { RouterDataProvider, useCurrentRouteData, useRouterData, useRouterState, } from "./web-router/components/RouterDataProvider.jsx";
 export { MetaTag } from "./web-router/components/MetaTag.jsx";
 export { split, hydrationReady } from "./web-router/components/Split.jsx";
 export { Head } from "./server/renderer/document/Head.jsx";

package/dist/index.jsx

@@ -1,4 +1,4 @@
-export { RouterDataProvider, useCurrentRouteData, useRouterData } from "./web-router/components/RouterDataProvider.jsx";
+export { RouterDataProvider, useCurrentRouteData, useRouterData, useRouterState } from "./web-router/components/RouterDataProvider.jsx";
 export { MetaTag } from "./web-router/components/MetaTag.jsx";
 export { split, hydrationReady } from "./web-router/components/Split.jsx";
 export { Head } from "./server/renderer/document/Head.jsx";

package/dist/scripts/build.js

@@ -6,7 +6,7 @@ import { dirname } from "path"
 import { readFileSync, existsSync, rmSync } from "fs"
 import { createRequire } from "module"
 import { wrapForeignError, formatError } from "../errors/index.js"
-import { runStaticPreflightOrExit } from "./preflight.js"
+import { runStaticPreflightOrExit, writeBuildInfo } from "./preflight.js"
 
 // Fail fast on a misconfigured app (missing/invalid config.json, package.json,
 // or moduleAliases) with a coded, doc-linked error — must run before the raw
@@ -112,6 +112,8 @@ async function build() {
 
     console.log("✅ Server and client builds completed!")
 
+    writeBuildInfo(process.env.PWD, configJSON, argumentsObject)
+
     await runBuildStep(["./dist/scripts/generateOfflineManifest.js"], {
         ...spawnBase,
         env: baseEnv,

package/dist/scripts/preflight.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "fs"
+import { readFileSync, writeFileSync } from "fs"
 import path from "path"
 import {
     validateConfigFile,
@@ -109,3 +109,83 @@ export function runStaticPreflightOrExit(appDir = process.env.PWD || process.cwd
     )
     process.exit(1)
 }
+
+// Records the config values a build was made with, so `serve` can refuse a
+// build that no longer matches config/config.json (issue #251).
+const BUILD_INFO_FILE = ".catalyst-build.json"
+
+/**
+ * Config values Vite inlines into the bundles at build time (see
+ * getClientEnvVariables in vite.config.js). KEY=value CLI arguments win over
+ * config.json, and objects are stored as JSON, as in loadEnvironmentVariables.
+ * @param {Record<string, unknown>} config - parsed config/config.json
+ * @param {Record<string, string>} [args] - KEY=value CLI arguments
+ */
+export function getInlinedConfig(config, args = {}) {
+    const values = { ...config, ...args }
+    let clientVars = values.CLIENT_ENV_VARIABLES ?? []
+    if (typeof clientVars === "string") clientVars = JSON.parse(clientVars)
+    const keys = ["PUBLIC_STATIC_ASSET_URL", "PUBLIC_STATIC_ASSET_PATH", ...clientVars]
+    return Object.fromEntries(
+        keys.map((key) => [key, typeof values[key] === "object" ? JSON.stringify(values[key]) : values[key]])
+    )
+}
+
+function buildInfoPath(appDir, config, args) {
+    return path.join(appDir, args.BUILD_OUTPUT_PATH || config.BUILD_OUTPUT_PATH || "build", BUILD_INFO_FILE)
+}
+
+/**
+ * @param {string} appDir
+ * @param {Record<string, unknown>} config
+ * @param {Record<string, string>} [args]
+ */
+export function writeBuildInfo(appDir, config, args = {}) {
+    writeFileSync(
+        buildInfoPath(appDir, config, args),
+        JSON.stringify(getInlinedConfig(config, args), null, 4)
+    )
+}
+
+/**
+ * Compare the values a build was made with against the current config.
+ * Anything that stops the comparison (a missing or unreadable build info
+ * file, e.g. from an older catalyst-core, an unparseable CLIENT_ENV_VARIABLES)
+ * only warns, so the build still serves.
+ * @param {string} [appDir]
+ * @param {Record<string, string>} [args]
+ * @returns {import("../errors/index.js").CatalystError | null}
+ */
+export function checkBuildMatchesConfig(appDir = process.env.PWD || process.cwd(), args = {}) {
+    const skip = (reason) => {
+        console.warn(`Skipping the build/config check: ${reason}`)
+        return null
+    }
+
+    // runStaticPreflightOrExit has already checked config.json.
+    const config = JSON.parse(readFileSync(path.join(appDir, "config", "config.json"), "utf8"))
+    const infoPath = buildInfoPath(appDir, config, args)
+    const info = readJson(infoPath)
+    if (info.error || !info.value || typeof info.value !== "object" || Array.isArray(info.value)) {
+        return skip(`${infoPath} is missing or invalid. Rebuild to enable it.`)
+    }
+
+    let current
+    try {
+        current = getInlinedConfig(config, args)
+    } catch (e) {
+        return skip(`could not read CLIENT_ENV_VARIABLES: ${e.message}`)
+    }
+
+    const keys = new Set([...Object.keys(info.value), ...Object.keys(current)])
+    const changed = [...keys].filter((key) => info.value[key] !== current[key])
+    if (changed.length === 0) return null
+
+    const show = (value) => (value === undefined ? "unset" : JSON.stringify(value))
+    const lines = changed.map(
+        (key) => `${key}: built with ${show(info.value[key])}, now ${show(current[key])}`
+    )
+    return createError(ERROR_CODES.PREFLIGHT_BUILD_STALE, {
+        details: `These values were inlined into the build and differ from config/config.json:\n  ${lines.join("\n  ")}`,
+    })
+}

package/dist/scripts/serve.js

@@ -1,7 +1,8 @@
 import path from "path"
 import { spawnSync } from "child_process"
 import { arrayToObject, resolveOutputMode } from "./scriptUtils.js"
-import { runStaticPreflightOrExit } from "./preflight.js"
+import { runStaticPreflightOrExit, checkBuildMatchesConfig } from "./preflight.js"
+import { formatError } from "../errors/index.js"
 import { fileURLToPath } from "url"
 import { dirname } from "path"
 import { readFileSync } from "fs"
@@ -23,6 +24,12 @@ function startProd() {
     const outputMode = resolveOutputMode(process.argv)
     const dirname = path.resolve(__dirname, "../../")
 
+    const staleBuild = checkBuildMatchesConfig(undefined, argumentsObject)
+    if (staleBuild) {
+        console.error(formatError(staleBuild, outputMode))
+        process.exit(1)
+    }
+
     // Read package.json
     const packageJson = JSON.parse(readFileSync(path.join(process.env.PWD, "package.json"), "utf-8"))
     const { name } = packageJson

package/dist/server/renderer/document/Body.d.ts

@@ -8,14 +8,3 @@ import React from "react";
  * @param {object} children - contains any child elements defined within the component
  */
 export declare function Body(props: any): React.JSX.Element;
-export declare namespace Body {
-    var propTypes: {
-        initialState: any;
-        jsx: any;
-        statusCode: any;
-        fetcherData: any;
-        children: any;
-        safeArea: any;
-        nativeWebView: any;
-    };
-}

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

@@ -1,5 +1,4 @@
 import React from "react";
-import PropTypes from "prop-types";
 const DEFAULT_SAFE_AREA = {
   top: 0,
   right: 0,
@@ -51,12 +50,3 @@ export function Body(props) {
             {children}
         </body>;
 }
-Body.propTypes = {
-  initialState: PropTypes.object,
-  jsx: PropTypes.any,
-  statusCode: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
-  fetcherData: PropTypes.object,
-  children: PropTypes.node,
-  safeArea: PropTypes.object,
-  nativeWebView: PropTypes.bool
-};

package/dist/server/renderer/document/Head.d.ts

@@ -5,16 +5,3 @@ import React from "react";
  * Route-cached deferred CSS is inlined here on repeat visits; new deferred CSS still appends after body.
  */
 export declare function Head(props: any): React.JSX.Element;
-export declare namespace Head {
-    var propTypes: {
-        isBot: any;
-        inlineCss: any;
-        deferredRouteInlineCss: any;
-        jsScripts: any;
-        criticalPreloadLinks: any;
-        deferredPreloadLinks: any;
-        metaTags: any;
-        publicAssetPath: any;
-        children: any;
-    };
-}

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

@@ -1,5 +1,4 @@
 import React from "react";
-import PropTypes from "prop-types";
 import FastRefresh from "../../../vite/FastRefresh.jsx";
 
 /**
@@ -49,14 +48,3 @@ export function Head(props) {
             {children}
         </head>;
 }
-Head.propTypes = {
-  isBot: PropTypes.bool,
-  inlineCss: PropTypes.string,
-  deferredRouteInlineCss: PropTypes.string,
-  jsScripts: PropTypes.array,
-  criticalPreloadLinks: PropTypes.array,
-  deferredPreloadLinks: PropTypes.array,
-  metaTags: PropTypes.array,
-  publicAssetPath: PropTypes.string,
-  children: PropTypes.node
-};

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

@@ -74,7 +74,7 @@ const createClientConfig = async () => {
                             return undefined
                         }
                         if (
-                            /[\\/]node_modules[\\/](react|react-dom|scheduler|react-fast-compare|react-side-effect|react-helmet-async)[\\/]/.test(
+                            /[\\/]node_modules[\\/](react|react-dom|scheduler)[\\/]/.test(
                                 id
                             )
                         ) {

package/dist/vite/vite.config.js

@@ -51,15 +51,27 @@ function scssModulesPlugin() {
     }
 }
 
+// Automatic runtime so the output imports react/jsx-(dev-)runtime: plugin-react
+// only adds Fast Refresh to .js files that import it. Classic createElement
+// output leaves the module without an HMR boundary, forcing full page reloads.
 function jsxInJsPlugin() {
+    let isProduction = process.env.NODE_ENV === "production"
+
     return {
         name: "vite-plugin-jsx-in-js",
         enforce: "pre",
+        configResolved(config) {
+            isProduction = config.isProduction
+        },
         async transform(code, id) {
             if (!id.endsWith(".js")) return null
             if (id.includes("node_modules")) return null
             if (!/</.test(code)) return null
-            return transformWithEsbuild(code, id, { loader: "jsx" })
+            return transformWithEsbuild(code, id, {
+                loader: "jsx",
+                jsx: "automatic",
+                jsxDev: !isProduction,
+            })
         },
     }
 }
@@ -266,9 +278,7 @@ const browserOptimizeDeps = [
     "redux",
     "redux-thunk",
     "axios",
-    "react-helmet-async",
     "react-google-recaptcha",
-    "react-fast-compare",
     "history",
     "lottie-web",
     // Pre-bundle alongside React so esbuild marks react/react-router as external
@@ -295,7 +305,6 @@ const browserOptimizeDeps = [
     // first navigation that pulls them in doesn't trigger a full-page reload.
     "react-loadable-visibility",
     "react-detect-offline",
-    "react-side-effect",
     "react-async-script",
     "normalize.css",
 ]
@@ -357,7 +366,6 @@ export const sharedViteConfig = {
         optimizeDeps: {
             include: [
                 "invariant",
-                "react-fast-compare",
                 "shallowequal",
                 "prop-types",
                 "redux-thunk",
@@ -430,7 +438,17 @@ export const sharedViteConfig = {
             path.join(process.env.src_path, "src/**/*.{js,jsx,ts,tsx}"),
         ],
         include: browserOptimizeDeps,
-        exclude: ["catalyst-core/router/ClientRouter"],
+        // catalyst-core/webmcp (and its shim subpath) must share the SAME
+        // pre-bundled module instance as catalyst-core's main entry:
+        // WebMcpProvider reads router state through a React context
+        // (OneMgRouterContext, via useRouterState()) that RouterDataProvider
+        // populates. If esbuild's dep scanner pre-bundles the subpath as its
+        // own separate optimized chunk, that chunk gets its own
+        // `createContext()` call — a second, unlinked context instance that
+        // WebMcpProvider reads from empty, throwing "must be used within a
+        // RouterDataProvider" even though one genuinely is an ancestor.
+        // Same rationale as the existing ClientRouter exclusion below.
+        exclude: ["catalyst-core/router/ClientRouter", "catalyst-core/webmcp", "catalyst-core/webmcp/shim"],
         esbuildOptions: {
             format: "esm",
             target: "node2022",

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

@@ -1,8 +1,7 @@
 import React, { useContext, useState, useEffect } from "react";
-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 { getMetaData } from "../utils/metaDataUtils.jsx";
 import { useLocation } from "react-router";
 
 /**
@@ -14,19 +13,13 @@ export const MetaTag = () => {
   } = useContext(OneMgRouterContext);
   const routeData = useRouterData();
   const location = useLocation();
-  const [metaTags, setMetaTags] = useState([<meta key={0}></meta>]);
+  const [metaTags, setMetaTags] = useState([]);
   useEffect(() => {
     const mergedMetaTags = getMetaData(matchedRoutes, routeData);
-    if (Array.isArray(mergedMetaTags) && mergedMetaTags.length > 0) {
-      setMetaTags(mergedMetaTags);
-    }
-    return () => deleteHeadTagsByDataAttribute("catalyst");
+    setMetaTags(Array.isArray(mergedMetaTags) ? mergedMetaTags : []);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [location]);
-  if (Array.isArray(metaTags) && metaTags.length >= 0) {
-    return <HelmetProvider>
-                <Helmet>{metaTags}</Helmet>
-            </HelmetProvider>;
-  }
-  return <></>;
+
+  // React 19 hoists document metadata rendered by components into <head>.
+  return <>{metaTags}</>;
 };

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

@@ -1,7 +1,7 @@
 import React from "react"
-import { describe, expect, it, vi, afterEach } from "vitest"
+import { describe, expect, it, vi } from "vitest"
 import { render, waitFor, act } from "@testing-library/react"
-import { MemoryRouter, Routes, Route, useNavigate } from "react-router"
+import { MemoryRouter, Routes, Route, useLocation, useNavigate } from "react-router"
 import { MetaTag } from "./MetaTag.jsx"
 import { OneMgRouterContext } from "../context.jsx"
 import { RouterContext } from "./RouterDataProvider.jsx"
@@ -26,10 +26,6 @@ function renderMetaTag({ matchedRoutes = [], routerData = {} } = {}) {
 }
 
 describe("MetaTag", () => {
-    afterEach(() => {
-        document.head.innerHTML = ""
-    })
-
     it("renders without crashing when there are no matched routes", () => {
         expect(() => renderMetaTag()).not.toThrow()
     })
@@ -48,53 +44,64 @@ describe("MetaTag", () => {
         await waitFor(() => {
             expect(document.head.querySelector('meta[name="description"]')).not.toBeNull()
         })
-        expect(document.head.querySelector('meta[name="description"]').getAttribute("content")).toBe(
-            "hello"
-        )
+        expect(document.head.querySelector('meta[name="description"]').getAttribute("content")).toBe("hello")
     })
 
-    it("keeps the placeholder meta tag when no route provides setMetaData", () => {
+    it("renders no metadata when no route provides setMetaData", () => {
         renderMetaTag({ matchedRoutes: [{ route: { component: {} } }] })
-        // Component should still render (Helmet/HelmetProvider tree),
-        // even with the single empty placeholder <meta> from useState.
-        expect(document.querySelector("head")).not.toBeNull()
+        expect(document.head.querySelector("[data-catalyst]")).toBeNull()
     })
 
-    it("re-runs setMetaData and clears previous tags when the location changes", async () => {
-        // A rerender() with a NEW <MemoryRouter initialEntries> does not
-        // navigate an already-mounted router -- initialEntries is only
-        // read on first mount. Confirmed directly: that approach left
-        // setMetaData called once even after "changing" the path.
-        // Navigating within one mounted router (via a real useNavigate
-        // call, triggered here through a button) is what actually
-        // changes useLocation() and re-fires MetaTag's effect.
-        const setMetaData = vi.fn(() => [<meta key="d" name="description" content="v1" />])
-        const matchedRoutes = [{ route: { component: { setMetaData } } }]
+    it("clears previous metadata when navigating to a route without setMetaData", async () => {
+        const routeWithMetadata = [
+            {
+                route: {
+                    component: {
+                        setMetaData: () => [<meta key="d" name="description" content="with metadata" />],
+                    },
+                },
+            },
+        ]
+
+        function RouteMetadata() {
+            const location = useLocation()
+            const matchedRoutes = location.pathname === "/with-metadata" ? routeWithMetadata : []
+
+            return (
+                <OneMgRouterContext.Provider value={{ matchedRoutes }}>
+                    <RouterContext.Provider value={{}}>
+                        <MetaTag />
+                    </RouterContext.Provider>
+                </OneMgRouterContext.Provider>
+            )
+        }
 
         function NavButton() {
             const navigate = useNavigate()
             return (
-                <button type="button" onClick={() => navigate("/b")}>
+                <button type="button" onClick={() => navigate("/without-metadata")}>
                     go
                 </button>
             )
         }
 
         render(
-            <MemoryRouter initialEntries={["/a"]}>
-                <OneMgRouterContext.Provider value={{ matchedRoutes }}>
-                    <RouterContext.Provider value={{}}>
-                        <NavButton />
-                        <MetaTag />
-                    </RouterContext.Provider>
-                </OneMgRouterContext.Provider>
+            <MemoryRouter initialEntries={["/with-metadata"]}>
+                <NavButton />
+                <RouteMetadata />
             </MemoryRouter>
         )
-        await waitFor(() => expect(setMetaData).toHaveBeenCalledTimes(1))
+
+        await waitFor(() => {
+            expect(document.head.querySelector('meta[name="description"]')).not.toBeNull()
+        })
 
         await act(async () => {
             document.querySelector("button").click()
         })
-        await waitFor(() => expect(setMetaData).toHaveBeenCalledTimes(2))
+
+        await waitFor(() => {
+            expect(document.head.querySelector('meta[name="description"]')).toBeNull()
+        })
     })
 })

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

@@ -1,5 +1,5 @@
 import React from "react";
-import type { Location, NavigateFunction, Params, RouteObject } from "react-router";
+import type { Location, NavigateFunction, Params, RouteMatch, RouteObject } from "react-router";
 /**
  * Data a route fetcher produced, as exposed by useCurrentRouteData / useRouterData.
  */
@@ -94,3 +94,27 @@ export declare const useCurrentRouteData: () => RouteData;
  * @throws If used outside RouterDataProvider Context
  */
 export declare const useRouterData: () => RoutesData;
+/**
+ * Router state (location, params, navigate, the matched-route chain) read
+ * through OneMgRouterContext rather than react-router's own hooks directly.
+ *
+ * Exists so a `catalyst-core/*` SUBPATH package (e.g. `catalyst-core/webmcp`)
+ * can read router state without importing react-router itself. A subpath is
+ * a separate module resolution root from the app's own react-router import
+ * under Vite's dev SSR (react-router is deliberately excluded from
+ * vite.config.js's `dedupe`), so two `useLocation()` calls made from two
+ * different entry points can land on two different react-router module
+ * instances with two different, mutually invisible RouterContexts — the
+ * hook throws "may be used only in the context of a <Router> component"
+ * even though a <Router> genuinely is an ancestor. Going through this
+ * context instead relies only on `react`'s context identity, and `react`
+ * (unlike react-router) IS deduped.
+ *
+ * @throws If used outside RouterDataProvider Context
+ */
+export declare const useRouterState: () => {
+    location: Location;
+    params: Params;
+    navigate: NavigateFunction;
+    matchedRoutes: RouteMatch<string, RouteObject>[];
+};

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

@@ -270,7 +270,10 @@ export const RouterDataProvider = ({
   return <OneMgRouterContext.Provider value={{
     matchedRoutes,
     refetchData,
-    clear
+    clear,
+    location,
+    params,
+    navigate
   }}>
             <RouterContext.Provider value={{
       ...routeData,
@@ -331,3 +334,34 @@ export const useRouterData = () => {
   }
   return context;
 };
+
+/**
+ * Router state (location, params, navigate, the matched-route chain) read
+ * through OneMgRouterContext rather than react-router's own hooks directly.
+ *
+ * Exists so a `catalyst-core/*` SUBPATH package (e.g. `catalyst-core/webmcp`)
+ * can read router state without importing react-router itself. A subpath is
+ * a separate module resolution root from the app's own react-router import
+ * under Vite's dev SSR (react-router is deliberately excluded from
+ * vite.config.js's `dedupe`), so two `useLocation()` calls made from two
+ * different entry points can land on two different react-router module
+ * instances with two different, mutually invisible RouterContexts — the
+ * hook throws "may be used only in the context of a <Router> component"
+ * even though a <Router> genuinely is an ancestor. Going through this
+ * context instead relies only on `react`'s context identity, and `react`
+ * (unlike react-router) IS deduped.
+ *
+ * @throws If used outside RouterDataProvider Context
+ */
+export const useRouterState = () => {
+  const context = useContext(OneMgRouterContext);
+  if (context.location === undefined) {
+    throw new Error("useRouterState must be used within a RouterDataProvider");
+  }
+  return {
+    location: context.location,
+    params: context.params || {},
+    navigate: context.navigate,
+    matchedRoutes: context.matchedRoutes || []
+  };
+};

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

@@ -6,6 +6,7 @@ import {
     RouterDataProvider,
     useRouterData,
     useCurrentRouteData,
+    useRouterState,
     serverDataFetcher,
 } from "./RouterDataProvider.jsx"
 
@@ -308,3 +309,46 @@ describe("useCurrentRouteData", () => {
         await waitFor(() => expect(screen.getByTestId("ready")).toBeInTheDocument())
     })
 })
+
+describe("useRouterState", () => {
+    function StateProbe() {
+        const { location, params, navigate, matchedRoutes } = useRouterState()
+        return (
+            <div
+                data-testid="state"
+                data-path={location.pathname}
+                data-params={JSON.stringify(params)}
+                data-nav={typeof navigate}
+                data-matched={Array.isArray(matchedRoutes) ? "array" : "other"}
+            />
+        )
+    }
+
+    it("exposes the router location, params, navigate and matched routes under a RouterDataProvider", async () => {
+        render(
+            <MemoryRouter initialEntries={["/items/42"]}>
+                <Routes>
+                    <Route
+                        path="/items/:id"
+                        element={
+                            <RouterDataProvider initialState={{}} config={{}}>
+                                <StateProbe />
+                            </RouterDataProvider>
+                        }
+                    />
+                </Routes>
+            </MemoryRouter>
+        )
+        const el = await screen.findByTestId("state")
+        expect(el.dataset.path).toBe("/items/42")
+        expect(JSON.parse(el.dataset.params)).toEqual({ id: "42" })
+        expect(el.dataset.nav).toBe("function")
+        expect(el.dataset.matched).toBe("array")
+    })
+
+    it("throws a clear error when used outside a RouterDataProvider", () => {
+        const spy = vi.spyOn(console, "error").mockImplementation(() => {})
+        expect(() => render(<StateProbe />)).toThrow(/useRouterState must be used within a RouterDataProvider/)
+        spy.mockRestore()
+    })
+})

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

@@ -1,13 +1,27 @@
-import type { RouteMatch, RouteObject } from "react-router";
+import type { Location, NavigateFunction, Params, RouteMatch, RouteObject } from "react-router";
 /**
  * Internal context shared among the router components. `matchedRoutes` is the
  * match chain for the current location; the two callbacks are supplied by
  * RouterDataProvider and consumed by useCurrentRouteData.
+ *
+ * `location`/`params`/`navigate` are the same values RouterDataProvider
+ * already reads via react-router's own hooks (useLocation/useParams/
+ * useNavigate) — republished here so a `catalyst-core/*` SUBPATH package
+ * (loaded through a separate module resolution than the app's own
+ * react-router import under Vite's dev SSR — `react-router` is deliberately
+ * excluded from vite.config.js's `dedupe`, see that file's comment) can read
+ * router state through ONE shared React context (identity guaranteed by
+ * `react`, which IS deduped) instead of calling react-router's hooks itself
+ * and risking a second, unlinked `react-router` module instance whose
+ * internal context a subpath's own hook calls can't see.
  */
 export interface OneMgRouterContextValue {
     matchedRoutes?: RouteMatch<string, RouteObject>[];
     refetchData?: (route: RouteObject, routeKey: string) => (args?: Record<string, any>) => void | Promise<void>;
     clear?: (routeKey: string) => (wait?: number) => void;
+    location?: Location;
+    params?: Params;
+    navigate?: NavigateFunction;
 }
 /**
  * @description This is internal context made for sharing data among router components