npm - catalyst-core - Versions diffs - 1.0.1 → 1.0.2-canary.2 - Mend

catalyst-core 1.0.1 → 1.0.2-canary.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (114) hide show

package/bin/catalyst.js +105 -1
package/dist/cli/README.md +119 -0
package/dist/cli/appConfig.js +50 -0
package/dist/cli/buildErrors.js +170 -0
package/dist/cli/buildWarnings.js +28 -0
package/dist/cli/devOutput.js +524 -0
package/dist/cli/diagnostic.js +388 -0
package/dist/cli/hints.js +69 -0
package/dist/cli/package.json +3 -0
package/dist/cli/spinner.js +141 -0
package/dist/cli/theme.js +155 -0
package/dist/errors/index.js +7 -3
package/dist/errors/registry.js +8 -0
package/dist/errors-index.json +7 -0
package/dist/index.d.ts +1 -1
package/dist/index.jsx +1 -1
package/dist/logger.js +61 -6
package/dist/native/androidProject/app/build.gradle.kts +2 -1
package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/CustomWebview.kt +2 -0
package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/MainActivity.kt +9 -0
package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/SplashActivity.kt +65 -34
package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/SplashOverlay.kt +109 -0
package/dist/native/androidSetup.js +46 -57
package/dist/native/buildAndroid/assets.js +22 -13
package/dist/native/buildAndroid/build.js +98 -26
package/dist/native/buildAndroid/config.js +43 -12
package/dist/native/buildAndroid/index.js +49 -191
package/dist/native/buildAppAndroid.js +19 -8
package/dist/native/buildAppIos.js +35 -16
package/dist/native/buildIos/assets.js +1 -6
package/dist/native/buildIos/build.js +61 -94
package/dist/native/buildIos/config.js +26 -8
package/dist/native/buildIos/index.js +143 -64
package/dist/native/buildIos/plugins.js +12 -15
package/dist/native/internalPluginUtils.js +0 -1
package/dist/native/iosnativeWebView/CoreLogic/Sources/CatalystCoreLogic/Constants/ConfigConstants.swift +2 -0
package/dist/native/iosnativeWebView/Sources/Core/WebView/SplashHTMLView.swift +31 -0
package/dist/native/iosnativeWebView/Sources/Core/WebView/SplashView.swift +17 -1
package/dist/native/iosnativeWebView/Sources/Core/WebView/SplashViewModel.swift +41 -1
package/dist/native/iosnativeWebView/Sources/Core/WebView/WebViewModel.swift +2 -0
package/dist/native/iosnativeWebView/Sources/Core/WebView/WebViewNavigationDelegate.swift +3 -0
package/dist/native/pluginComposerAndroid.js +2 -3
package/dist/native/renameAndroidProject.js +42 -20
package/dist/native/setupEmulatorIos.js +28 -49
package/dist/native/setupServer.js +12 -15
package/dist/native/terminalProgress.js +186 -147
package/dist/native/utils.js +335 -54
package/dist/otel.js +15 -9
package/dist/scripts/build.js +314 -42
package/dist/scripts/generateOfflineManifest.js +11 -1
package/dist/scripts/loadEnvironmentVariables.js +24 -2
package/dist/scripts/preServerInit.js +32 -10
package/dist/scripts/preflight.js +115 -11
package/dist/scripts/scriptUtils.js +34 -0
package/dist/scripts/serve.js +65 -9
package/dist/scripts/start.js +58 -21
package/dist/server/expressServer.js +167 -32
package/dist/server/renderer/document/Body.d.ts +0 -11
package/dist/server/renderer/document/Body.jsx +0 -10
package/dist/server/renderer/document/Head.d.ts +0 -13
package/dist/server/renderer/document/Head.jsx +0 -12
package/dist/server/renderer/handler.jsx +87 -11
package/dist/server/utils/validator.js +14 -11
package/dist/vite/manifest-categorization-plugin.js +7 -5
package/dist/vite/resolveDevServerConfig.js +9 -2
package/dist/vite/vite.config.client.js +19 -1
package/dist/vite/vite.config.js +96 -19
package/dist/vite/vite.config.server.js +21 -0
package/dist/web-router/components/MetaTag.jsx +20 -14
package/dist/web-router/components/MetaTag.test.jsx +108 -32
package/dist/web-router/components/RouterDataProvider.d.ts +25 -1
package/dist/web-router/components/RouterDataProvider.jsx +35 -1
package/dist/web-router/components/RouterDataProvider.test.jsx +44 -0
package/dist/web-router/context.d.ts +15 -1
package/dist/web-router/context.jsx +11 -0
package/dist/webmcp/WebMcpProvider.jsx +234 -0
package/dist/webmcp/declarative.js +207 -0
package/dist/webmcp/declarative.test.js +122 -0
package/dist/webmcp/errors.js +59 -0
package/dist/webmcp/errors.test.js +47 -0
package/dist/webmcp/index.js +40 -0
package/dist/webmcp/native.js +37 -0
package/dist/webmcp/native.test.js +41 -0
package/dist/webmcp/pageInfo.js +119 -0
package/dist/webmcp/pageInfo.test.js +85 -0
package/dist/webmcp/registry.dom.test.js +175 -0
package/dist/webmcp/registry.js +540 -0
package/dist/webmcp/registry.test.js +228 -0
package/dist/webmcp/routeContext.js +11 -0
package/dist/webmcp/shim-entry.js +8 -0
package/dist/webmcp/shim.js +149 -0
package/dist/webmcp/useTool.js +124 -0
package/package.json +4 -7
package/test/cli/buildErrors.test.ts +173 -0
package/test/cli/buildWarnings.test.cjs +62 -0
package/test/cli/devOutput.test.ts +549 -0
package/test/cli/diagnostic.test.ts +434 -0
package/test/cli/output.test.cjs +90 -0
package/test/cli/spinner.test.ts +177 -0
package/test/cli/theme.test.ts +163 -0
package/test/native/redactSecrets.test.ts +72 -0
package/test/native/utils.test.ts +532 -0
package/test/scripts/build.test.ts +275 -0
package/test/scripts/preflight.test.ts +100 -2
package/test/scripts/serve.test.ts +102 -0
package/test/server/fixtures/template/src/js/routes/index.jsx +8 -0
package/test/server/handler.test.ts +17 -0
package/test/server/logger.test.ts +185 -0
package/test/server/manifestCache.test.ts +13 -0
package/test/server/otel.test.ts +556 -0
package/test/server/validator.test.ts +19 -8
package/vitest.config.ts +4 -0
package/dist/scripts/checkVersion.js +0 -3
package/dist/scripts/cleanCache.js +0 -30

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

@@ -1,8 +1,7 @@
-import React, { useContext, useState, useEffect } from "react";
-import { HelmetProvider, Helmet } from "react-helmet-async";
+import React, { useContext, useState, useEffect, useRef } from "react";
 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,26 @@ export const MetaTag = () => {
   } = useContext(OneMgRouterContext);
   const routeData = useRouterData();
   const location = useLocation();
-  const [metaTags, setMetaTags] = useState([<meta key={0}></meta>]);
+  // null until the first client update, so server and hydration renders match (both empty).
+  const [metaTags, setMetaTags] = useState(null);
+  // The server renders these tags into <head> (Head.tsx). React 19 does not
+  // adopt them when MetaTag renders its own copies, and renders non-metadata
+  // tags such as <script type="application/ld+json"> in place, so the server
+  // copies would outlive the page they describe. Captured on mount, before
+  // any client copy exists, and removed once the client copies are in.
+  const serverTags = useRef(null);
   useEffect(() => {
+    serverTags.current ??= Array.from(document.head.querySelectorAll("[data-catalyst]"));
     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 <></>;
+  useEffect(() => {
+    if (!metaTags || !serverTags.current?.length) return;
+    serverTags.current.forEach(el => el.remove());
+    serverTags.current = [];
+  }, [metaTags]);
+  // React 19 hoists document metadata rendered by components into <head>.
+  return <>{metaTags}</>;
 };

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

@@ -1,7 +1,8 @@
 import React from "react"
-import { describe, expect, it, vi, afterEach } from "vitest"
-import { render, waitFor, act } from "@testing-library/react"
-import { MemoryRouter, Routes, Route, useNavigate } from "react-router"
+import { renderToString } from "react-dom/server"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { render, waitFor, act, cleanup } from "@testing-library/react"
+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 +27,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 +45,132 @@ 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 }}>
+            <MemoryRouter initialEntries={["/with-metadata"]}>
+                <NavButton />
+                <RouteMetadata />
+            </MemoryRouter>
+        )
+        await waitFor(() => {
+            expect(document.head.querySelector('meta[name="description"]')).not.toBeNull()
+        })
+        await act(async () => {
+            document.querySelector("button").click()
+        })
+        await waitFor(() => {
+            expect(document.head.querySelector('meta[name="description"]')).toBeNull()
+        })
+    })
+    describe("server-rendered head tags", () => {
+        afterEach(() => {
+            cleanup()
+            document.head.innerHTML = ""
+        })
+        const pageMeta = (page) => [
+            <title key="t">{`Page ${page}`}</title>,
+            <meta key="d" name="description" content={`about ${page}`} />,
+            <script key="ld" type="application/ld+json">{`{"page":"${page}"}`}</script>,
+        ]
+        const routesFor = (pathname) => [
+            { route: { component: { setMetaData: () => pageMeta(pathname === "/a" ? "a" : "b") } } },
+        ]
+        function App() {
+            const location = useLocation()
+            const navigate = useNavigate()
+            return (
+                <OneMgRouterContext.Provider value={{ matchedRoutes: routesFor(location.pathname) }}>
                     <RouterContext.Provider value={{}}>
-                        <NavButton />
+                        <button type="button" onClick={() => navigate("/b")}>
+                            go
+                        </button>
                         <MetaTag />
                     </RouterContext.Provider>
                 </OneMgRouterContext.Provider>
+            )
+        }
+        const tree = (
+            <MemoryRouter initialEntries={["/a"]}>
+                <App />
             </MemoryRouter>
         )
-        await waitFor(() => expect(setMetaData).toHaveBeenCalledTimes(1))
-        await act(async () => {
-            document.querySelector("button").click()
+        it("hydrates without a mismatch and replaces the server's JSON-LD, title and meta on navigation", async () => {
+            // What Head.tsx streams for /a: getMetaData output stamped data-catalyst.
+            document.head.innerHTML = renderToString(<>{pageMeta("a")}</>).replace(
+                /<(title|meta|script)/g,
+                '<$1 data-catalyst="true"'
+            )
+            const container = document.createElement("div")
+            container.innerHTML = renderToString(tree)
+            document.body.appendChild(container)
+            const onRecoverableError = vi.fn()
+            await act(async () => {
+                render(tree, { container, hydrate: true, onRecoverableError })
+            })
+            expect(onRecoverableError).not.toHaveBeenCalled()
+            await act(async () => {
+                container.querySelector("button").click()
+            })
+            await waitFor(() => {
+                expect(document.title).toBe("Page b")
+            })
+            const jsonLd = document.querySelectorAll('script[type="application/ld+json"]')
+            expect(Array.from(jsonLd, (el) => el.textContent)).toEqual(['{"page":"b"}'])
+            expect(document.head.querySelector('script[type="application/ld+json"]')).toBeNull()
+            expect(document.querySelectorAll("title")).toHaveLength(1)
+            expect(
+                Array.from(document.querySelectorAll('meta[name="description"]'), (el) => el.content)
+            ).toEqual(["about b"])
         })
-        await waitFor(() => expect(setMetaData).toHaveBeenCalledTimes(2))
     })
 })

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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

package/dist/web-router/context.jsx CHANGED Viewed

@@ -4,6 +4,17 @@ import { createContext } from "react";
  * 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.
  */
 /**

package/dist/webmcp/WebMcpProvider.jsx ADDED Viewed

@@ -0,0 +1,234 @@
+import React, { useEffect, useMemo, useRef } from "react"
+// Relative import, not the "catalyst-core" package specifier: under Vite's
+// dev SSR, re-entering through the package specifier from INSIDE
+// node_modules/catalyst-core/dist/webmcp/ can resolve to a separate module
+// record than the app's own `import ... from "catalyst-core"` — even though
+// both point at the identical file on disk — which defeats the whole point
+// of routing state through a shared React context (see the file-level
+// comment below). A relative path from this file straight to the main
+// entry's compiled output guarantees the SAME module record both places.
+import { useRouterState } from "../index.jsx"
+import { RouteContext } from "./routeContext.js"
+import { hasBackend, reapUnmatched, registerTool, unregisterTool, inspect, newOwnerKey } from "./registry.js"
+import { declarativeToolFor, frameworkTools } from "./declarative.js"
+import { pageInfoTool } from "./pageInfo.js"
+/**
+ * WebMcpProvider — framework glue for WebMCP.
+ *
+ * Mounted once, inside RouterDataProvider (so it sees the same route match
+ * chain) and wrapping the app. Two jobs:
+ *
+ *   1. Publishes the current innermost route path pattern via <RouteContext>
+ *      so every useTool() beneath it tags its registration with a route.
+ *
+ *   2. On every navigation, hands the registry the set of still-matched route
+ *      patterns. Any route-scoped tool whose route is no longer matched is
+ *      aborted + unregistered *now* — leaving a route aborts its tools.
+ *
+ * Route state (location/params/navigate/the matched-route chain) comes from
+ * catalyst-core's `useRouterState()`, NOT from react-router's own hooks
+ * called directly in this file. That is deliberate: this module ships as
+ * the `catalyst-core/webmcp` SUBPATH, 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`). Calling
+ * `useLocation()` etc. here risks landing on a second, unlinked
+ * react-router module instance whose RouterContext this component can't
+ * see — `useRouterState()` sidesteps that by reading through a plain React
+ * context RouterDataProvider already populates, and `react` context
+ * identity (unlike react-router's) IS guaranteed single-instance.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.children
+ * @param {any[]} props.routes  the app's OWN route table (whatever shape it
+ *   builds `preparedRoutes()`/`getRoutes()` from), in its natural nested
+ *   form — WebMcpProvider flattens it itself. Required: unlike the earlier
+ *   POC, core cannot reach into an app's own routing module, so the caller
+ *   passes its routes explicitly.
+ * @param {(flatRoute: any) => boolean} [props.filterNavigable]  optional
+ *   predicate deciding which flattened, non-parameterised routes are offered
+ *   through the `navigate` framework tool's enum. Default: every such route.
+ *   An app with many generated pages (e.g. one route per doc page) should
+ *   exclude those here — they're reachable through their own search/open
+ *   tools instead of bloating `navigate`'s enum to the whole site map.
+ */
+export function WebMcpProvider({ children, routes, filterNavigable }) {
+    const { location, params, navigate, matchedRoutes: matches } = useRouterState()
+    const currentRoutePath = useMemo(() => {
+        for (let i = matches.length - 1; i >= 0; i--) {
+            const patt = patternOf(matches[i])
+            if (patt) return patt
+        }
+        return ""
+    }, [matches])
+    const matchedPatterns = useMemo(() => {
+        const set = new Set()
+        for (const m of matches) {
+            const patt = patternOf(m)
+            if (patt) set.add(patt)
+        }
+        return set
+    }, [matches])
+    // A stable string key so effects only fire when the matched SET changes.
+    const patternsKey = useMemo(() => Array.from(matchedPatterns).sort().join("|"), [matchedPatterns])
+    const firstRun = useRef(true)
+    useEffect(() => {
+        if (typeof document === "undefined") return
+        if (hasBackend()) return
+        // Neither a native document.modelContext nor an app-installed shim
+        // is present — every registerTool() call below still "succeeds"
+        // against the in-memory fallback (registry.js's safety net), but no
+        // agent can see any of it. This is silent otherwise, and the
+        // resulting "nothing is broken, nothing works" state is exactly the
+        // kind of thing worth a loud one-time warning for.
+        // eslint-disable-next-line no-console
+        console.warn(
+            "[webmcp] No document.modelContext found (native or shim) — WebMCP tools are registering into an " +
+                "in-memory fallback that no agent can see. Install a shim (e.g. catalyst-core/webmcp/shim's " +
+                "installShim()) before this provider mounts if you need WebMCP to work in a browser without " +
+                "native support."
+        )
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [])
+    // Keep live route facts + the matched-route chain in a ref so the framework
+    // tools (registered once, below) always report the *current* page without
+    // re-registering.
+    const routeFactsRef = useRef({ pathname: location.pathname, pattern: currentRoutePath, params, matches })
+    routeFactsRef.current = { pathname: location.pathname, pattern: currentRoutePath, params, matches }
+    const flatRoutes = useMemo(() => flattenRoutes(routes), [routes])
+    // Register the DECLARATIVE read tools + the framework tools ONCE, as
+    // app-lifetime tools (routePath ""), so an agent can navigate from anywhere
+    // to anywhere. Imperative useTool() action tools stay route-scoped.
+    useEffect(() => {
+        if (typeof document === "undefined") return undefined
+        const owners = []
+        const getCurrent = () => ({
+            pathname: routeFactsRef.current.pathname,
+            pattern: routeFactsRef.current.pattern,
+            params: routeFactsRef.current.params,
+            tools: inspect().tools.map((t) => ({ name: t.name, routePath: t.routePath })),
+        })
+        // Declarative, one per route that declares route.tool.
+        for (const route of flatRoutes) {
+            const spec = declarativeToolFor(route, navigate)
+            if (!spec) continue
+            const key = newOwnerKey()
+            const res = registerTool(key, "", spec)
+            if (res.ok) owners.push(key)
+            else
+                // eslint-disable-next-line no-console
+                console.warn(`[webmcp] declarative tool "${spec.name}" failed to register:`, res.error)
+        }
+        // Framework: navigate + get_current_route + get_page_info.
+        const navigableRoutes = filterNavigable ? flatRoutes.filter(filterNavigable) : flatRoutes
+        const fw = [
+            ...frameworkTools(navigableRoutes, navigate, getCurrent, flatRoutes),
+            pageInfoTool(
+                () => routeFactsRef.current.matches,
+                () => ({})
+            ),
+        ]
+        for (const spec of fw) {
+            const key = newOwnerKey()
+            const res = registerTool(key, "", spec)
+            if (res.ok) owners.push(key)
+            else
+                // eslint-disable-next-line no-console
+                console.warn(
+                    `[webmcp] framework tool "${spec.name}" failed to register — a route tool may already use that name:`,
+                    res.error
+                )
+        }
+        return () => owners.forEach(unregisterTool)
+        // navigate identity is stable for the life of the router; flatRoutes
+        // is memoised on the routes prop, which an app should pass a stable
+        // reference for (the same module-level array every render).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [flatRoutes])
+    useEffect(() => {
+        if (firstRun.current) {
+            firstRun.current = false
+            return
+        }
+        const reaped = reapUnmatched(matchedPatterns)
+        if (reaped.length) {
+            // eslint-disable-next-line no-console
+            console.info(
+                `[webmcp] navigated to ${location.pathname} — reaped ${reaped.length} stale tool(s): ${reaped.join(", ")}`
+            )
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [patternsKey, location.pathname])
+    return <RouteContext.Provider value={currentRoutePath}>{children}</RouteContext.Provider>
+}
+/**
+ * Flatten a nested route table into the flat array declarative.js's
+ * declarativeToolFor()/frameworkTools() expect: one entry per NAVIGABLE
+ * route, each carrying an absolute `.path` and (if present) its own
+ * `.tool` config.
+ *
+ * Rules:
+ *   - A route with `children` is a layout wrapper — recurse into its
+ *     children, joining relative child paths against the parent's absolute
+ *     path. Its own entry is dropped UNLESS it itself has a `path` (a layout
+ *     can also be directly navigable, e.g. nested `/parent` + `/parent/:id`).
+ *   - A route with `index: true` and no `path` is the default child of its
+ *     parent — it has no path of its own to register a tool under, so it is
+ *     skipped. (Its parent's own path, if any, already covers "/".)
+ *   - A route with neither `path` nor `children` nor `index` contributes
+ *     nothing (matches ServerRouter's own tolerance for pathless wrapper
+ *     routes, e.g. an outer <RouterDataProvider> element with no path).
+ */
+export function flattenRoutes(routes, parentPath = "") {
+    if (!Array.isArray(routes)) return []
+    const out = []
+    for (const route of routes) {
+        if (route.index || typeof route.path !== "string") {
+            if (Array.isArray(route.children)) {
+                out.push(...flattenRoutes(route.children, parentPath))
+            }
+            continue
+        }
+        const absolutePath = route.path.startsWith("/")
+            ? route.path
+            : `${parentPath.replace(/\/$/, "")}/${route.path}`
+        out.push({ ...route, path: absolutePath })
+        if (Array.isArray(route.children)) {
+            out.push(...flattenRoutes(route.children, absolutePath))
+        }
+    }
+    return out
+}
+/**
+ * A RouteMatch has `.route.path` (the pattern segment as react-router sees
+ * it — usually just the leaf segment, not the full absolute path) and
+ * `.pathname` (the full matched URL). We want the full pattern, so this
+ * joins every matched segment's `.route.path` up the chain rather than
+ * trusting either alone.
+ *
+ * A *pathless* layout route (no `.route.path`) contributes NO scope — it is
+ * not a navigable destination. Falling back to `.pathname` instead would pin
+ * whatever page happened to be current into the matched-set, and stop that
+ * route's tools from ever being reaped.
+ */
+function patternOf(match) {
+    if (!match || !match.route || typeof match.route.path !== "string" || !match.route.path) return ""
+    const p = match.route.path
+    return p.startsWith("/") ? p : `/${p}`
+}