catalyst-core 1.0.2-canary.1 → 1.0.2

package/dist/server/renderer/handler.jsx

@@ -29,15 +29,84 @@ import { resolveOutputMode, getDebugEnvInfo } from "../../scripts/scriptUtils.js
 // this process never sees the parent's CLI flags, so process.argv here would
 // never contain --debug/--verbose — only CATALYST_OUTPUT_MODE is real input.
 const outputMode = resolveOutputMode([], process.env);
-// Debug mode's boxed output already embeds the full stack trace (see
-// errors/index.js#formatDebug), so only default/verbose need the original
-// error printed separately to avoid losing the stack.
-const logSSRError = (stage, error) => {
+const STAGE_LABEL = {
+  RENDER: "render",
+  FETCHER: "serverFetcher",
+  SERVER_SIDE_FUNCTION: "serverSideFunction",
+  REQUEST_HANDLING: "request"
+};
+
+// One failure is reported once. A render error used to surface at every catch
+// site it bubbled through -- render, fetcher, serverSideFunction, request --
+// each re-rendering the same broken tree, so one throw printed four coded
+// reports and four stacks per request.
+const reported = new WeakSet();
+
+// Marks an error that came out of rendering. The fetcher and
+// serverSideFunction fallbacks re-render the page; re-rendering after the
+// render itself failed only throws the same error again.
+const RENDER_FAILED = Symbol.for("catalyst.renderFailed");
+const asError = error => error && typeof error === "object" ? error : new Error(String(error));
+const markRenderFailure = error => {
+  const err = asError(error);
+  err[RENDER_FAILED] = true;
+  // Already reported by the render path; a thrown string arrives here as a
+  // fresh Error the outer catch would otherwise report a second time.
+  reported.add(err);
+  return err;
+};
+const isRenderFailure = error => Boolean(error && typeof error === "object" && error[RENDER_FAILED]);
+const logSSRError = (stage, error, req) => {
+  if (error && typeof error === "object") {
+    if (reported.has(error)) return;
+    reported.add(error);
+  }
   const wrapped = wrapSSRError(stage, error);
+
+  // This module is bundled into the app's build, so it cannot reach
+  // catalyst-core's terminal renderer by path. The server that loads it
+  // provides one (see expressServer.ts); a custom server without it gets the
+  // registry's plain formatting.
+  const report = globalThis.__catalystReportRuntimeError;
+  if (typeof report === "function") {
+    const where = req ? `${req.method} ${req.originalUrl}` : null;
+    report({
+      error,
+      code: wrapped.code,
+      docs: wrapped.docUrl,
+      scope: [where, STAGE_LABEL[stage]].filter(Boolean).join(" · ")
+    });
+    return;
+  }
+  // Debug mode's boxed output already embeds the full stack trace (see
+  // errors/index.js#formatDebug), so only default/verbose need the original
+  // error printed separately to avoid losing the stack.
   const debugEnv = outputMode === "debug" ? getDebugEnvInfo() : undefined;
   console.error(formatError(wrapped, outputMode, debugEnv));
   if (outputMode !== "debug") console.error(error);
 };
+
+/**
+ * Finish a request whose handling failed. Without this a render error left the
+ * response open: the browser spun until it timed out and the terminal was the
+ * only place the failure showed.
+ */
+const sendFailure = (res, error) => {
+  // Plain Node response calls, and never a throw: failing while reporting a
+  // failure would turn one error into an unhandled rejection.
+  try {
+    if (res.headersSent) {
+      if (!res.writableEnded) res.end();
+      return;
+    }
+    const detail = process.env.NODE_ENV !== "production" && error ? `\n\n${error?.message || String(error)}\n\nThe full error is in the terminal running catalyst start.` : "";
+    res.statusCode = 500;
+    res.setHeader?.("content-type", "text/plain; charset=utf-8");
+    res.end(`Internal Server Error${detail}`);
+  } catch {
+    // The connection is already gone; nothing left to tell it.
+  }
+};
 const DEFAULT_SAFE_AREA_INSETS = {
   top: 0,
   right: 0,
@@ -286,6 +355,10 @@ const _renderMarkUp = async (errorCode, req, res, metaTags, fetcherData, store,
           cb();
         }
       });
+      // destroy(error) below emits "error" on this stream. Unhandled, that
+      // became an uncaughtException per render on top of the report
+      // already printed; the failure is handled through reject().
+      tail.on("error", () => {});
       tail.pipe(res);
       const {
         pipe
@@ -299,7 +372,7 @@ const _renderMarkUp = async (errorCode, req, res, metaTags, fetcherData, store,
           resolve();
         },
         onError(error) {
-          logSSRError("RENDER", error);
+          logSSRError("RENDER", error, req);
           safeCall(onRenderError, {
             req,
             res,
@@ -308,20 +381,20 @@ const _renderMarkUp = async (errorCode, req, res, metaTags, fetcherData, store,
           });
           cleanupSafeArea();
           tail.destroy(error);
-          reject(error);
+          reject(markRenderFailure(error));
         }
       });
     });
   } catch (error) {
     cleanupSafeArea();
-    logSSRError("RENDER", error);
+    logSSRError("RENDER", error, req);
     safeCall(onRenderError, {
       req,
       res,
       store,
       error
     });
-    return Promise.reject(error);
+    return Promise.reject(markRenderFailure(error));
   }
 };
 const tracedRenderMarkUp = withObservability(SSR_SERVICE, _renderMarkUp, "renderMarkUp");
@@ -412,7 +485,8 @@ async function _handler(req, res) {
           await tracedRenderMarkUp(null, req, res, allTags, fetcherData, store, allMatches, context, chunkExtractor);
         }
       } catch (error) {
-        logSSRError("FETCHER", error);
+        if (isRenderFailure(error)) throw error;
+        logSSRError("FETCHER", error, req);
         safeCall(onFetcherError, {
           req,
           res,
@@ -424,7 +498,8 @@ async function _handler(req, res) {
         await tracedRenderMarkUp(404, req, res, allTags, fetcherData, store, allMatches, context, chunkExtractor);
       }
     } catch (error) {
-      logSSRError("SERVER_SIDE_FUNCTION", error);
+      if (isRenderFailure(error)) throw error;
+      logSSRError("SERVER_SIDE_FUNCTION", error, req);
       safeCall(onAppServerSideError, {
         req,
         res,
@@ -436,12 +511,13 @@ async function _handler(req, res) {
       await tracedRenderMarkUp(error.status_code, req, res, allTags, fetcherData, store, allMatches, context, chunkExtractor);
     }
   } catch (error) {
-    logSSRError("REQUEST_HANDLING", error);
+    logSSRError("REQUEST_HANDLING", error, req);
     safeCall(onRequestError, {
       req,
       res,
       error
     });
+    sendFailure(res, error);
   }
 }
 const handler = withObservability(SSR_SERVICE, _handler, "handler");

package/dist/server/utils/validator.js

@@ -1,4 +1,3 @@
-import pc from "ansis";
 import { createError, formatError, ERROR_CODES } from "../../errors/index.js";
 import { resolveOutputMode, getDebugEnvInfo } from "../../scripts/scriptUtils.js";
 
@@ -17,13 +16,19 @@ const outputMode = resolveOutputMode([], process.env);
 //     single error and fall back, keeping the request alive.
 // `handleError` below is the shared "log it, in whatever output mode" helper
 // those in-server sites use.
-const handleError = e => {
+// The default view is the CLI's diagnostic block. This module is also bundled
+// into the app's SSR build, where the CLI is not reachable by a relative path,
+// so the server process installs the renderer as a global (preServerInit.js,
+// the first module it loads). Without it, or under --verbose/--debug, the
+// registry's own format is used.
+const renderError = e => {
+  const render = globalThis.__catalystRenderRegistryError;
+  if (outputMode === "default" && typeof render === "function") return render(e, "server");
   const debugEnv = outputMode === "debug" ? getDebugEnvInfo() : undefined;
-  if (outputMode === "default") {
-    console.log(pc.red("Failed to start server: "), formatError(e, outputMode));
-  } else {
-    console.log(formatError(e, outputMode, debugEnv));
-  }
+  return formatError(e, outputMode, debugEnv);
+};
+const handleError = e => {
+  console.log(renderError(e));
 };
 const validatePreInitServer = fn => {
   if (!fn) return createError(ERROR_CODES.PREFLIGHT_PRE_SERVER_INIT_MISSING);
@@ -112,8 +117,7 @@ const safeCall = async (fn, ...args) => {
     const wrapped = createError(ERROR_CODES.PROCESS_USER_HOOK_FAILED, {
       cause: e
     });
-    const debugEnv = outputMode === "debug" ? getDebugEnvInfo() : undefined;
-    console.error(formatError(wrapped, outputMode, debugEnv));
+    console.error(renderError(wrapped));
   }
 };
 
@@ -132,8 +136,7 @@ const safeCallNamed = async (hookName, fn, ...args) => {
       details: `The "${hookName}" hook threw. See the cause below.`,
       cause: e
     });
-    const debugEnv = outputMode === "debug" ? getDebugEnvInfo() : undefined;
-    console.error(formatError(wrapped, outputMode, debugEnv));
+    console.error(renderError(wrapped));
   }
 };
 export { handleError, validateConfigFile, validateConfigureStore, validateCustomDocument, validateGetRoutes, validatePackageJson, validateReducerFunction, validateModuleAlias, validatePreInitServer, validateMiddleware, safeCall, safeCallNamed };

package/dist/vite/manifest-categorization-plugin.js

@@ -199,7 +199,7 @@ export function manifestCategorizationPlugin(options = {}) {
                 if (matchedViteEntry && matchedViteKey) {
                     newCategorizedChunks[category][matchedViteKey] = { ...matchedViteEntry }
                 } else {
-                    console.log(`❌ No manifest match found for ${chunkName}, keeping original structure`)
+                    console.debug(`No manifest match for ${chunkName}; keeping original structure`)
                     newCategorizedChunks[category][chunkName] = chunkData
                 }
             }
@@ -405,7 +405,7 @@ export function manifestCategorizationPlugin(options = {}) {
                         }
                     } catch (err) {
                         // nosemgrep: javascript.lang.security.audit.unsafe-formatstring.unsafe-formatstring - importPath comes from the app's own module import graph resolved by Vite at build time, not attacker-controlled; console.log here does no printf-style substitution.
-                        console.log(`❌ Error resolving ${importPath}:`, err.message)
+                        console.debug(`Could not resolve ${importPath}: ${err.message}`)
                     }
                 })
             )
@@ -430,16 +430,18 @@ export function manifestCategorizationPlugin(options = {}) {
                     const manifestContent = fs.readFileSync(manifestPath, "utf8")
                     viteManifest = JSON.parse(manifestContent)
                 } else {
-                    console.log("❌ Could not find manifest.json at expected path:", manifestPath)
+                    // Silent: this fires as a *consequence* of the bundle
+                    // failing, so shouting about a missing manifest adds a
+                    // second, misleading error on top of the real one.
                     return
                 }
             } catch (e) {
-                console.log("❌ Could not read manifest from file system:", e.message)
+                // Same reasoning as above: a consequence, not the cause.
                 return
             }
 
             if (!processedManifest) {
-                console.log("❌ No processed manifest available")
+                console.debug("No processed manifest available")
                 return
             }
 

package/dist/vite/resolveDevServerConfig.js

@@ -38,11 +38,18 @@ export function resolveDevFsAllow(devFs, frameworkPaths) {
  * first so the framework-owned `hmr` and `fs` always win.
  */
 export function buildDevServer(devServer = {}, { frameworkPaths, isProduction = false } = {}) {
-    // eslint-disable-next-line no-unused-vars -- base is destructured only to omit it from serverOverrides
+    // `base` is pulled out to keep it out of serverOverrides -- it is applied
+    // at the config root, not under `server` -- so it is unused by design.
+    // eslint-disable-next-line no-unused-vars
     const { base, hmr, fs, ...serverOverrides } = devServer
+    // CATALYST_NO_HMR lets a one-shot consumer of this config (the offline
+    // manifest step, which spins up a throwaway server purely to load a
+    // module) opt out. isProduction is captured at module load, so it cannot
+    // be flipped by setting NODE_ENV just before createServer().
+    const hmrDisabled = isProduction || process.env.CATALYST_NO_HMR === "true"
     return {
         ...serverOverrides,
-        hmr: isProduction ? false : (hmr ?? true),
+        hmr: hmrDisabled ? false : (hmr ?? true),
         fs: { allow: resolveDevFsAllow(fs, frameworkPaths) },
     }
 }

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

@@ -31,6 +31,10 @@ const createClientConfig = async () => {
             sourcemap: false,
             manifest: true,
             ssrManifest: true,
+            // Parallel client and server builds share this directory -- emptying it
+            // would delete the other bundle. Declared explicitly so Vite does not
+            // warn about an outDir outside the project root.
+            emptyOutDir: false,
             outDir: path.join(process.env.src_path, process.env.BUILD_OUTPUT_PATH || "build"),
 
             // cssCodeSplit: true (default) — each chunk gets its own CSS file.
@@ -38,6 +42,20 @@ const createClientConfig = async () => {
             // per-chunk CSS is fine — more files but each is small and cacheable.
 
             rollupOptions: {
+                // Advisory warnings about third-party code the app author
+                // cannot act on: a dependency's misplaced /*#__PURE__*/ comment
+                // and unused re-exports from our own entry. Genuine problems
+                // (unresolved imports, circular deps, missing exports) still
+                // surface.
+                onwarn(warning, defaultHandler) {
+                    const ignored = new Set([
+                        "INVALID_ANNOTATION",
+                        "UNUSED_EXTERNAL_IMPORT",
+                        "MODULE_LEVEL_DIRECTIVE",
+                    ])
+                    if (ignored.has(warning.code)) return
+                    defaultHandler(warning)
+                },
                 input: {
                     main: path.join(process.env.src_path, "client/index.js"),
                 },

package/dist/vite/vite.config.js

@@ -135,14 +135,20 @@ import { imageUrl, fontUrl } from "./scssParams.js"
 // options — so anything else is left alone and Vite falls back to its normal
 // auto-loaded postcss.config.js resolution.
 const resolvePostcssPlugins = () => {
-    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - process.env.src_path is the app root set by the framework's own build tooling, not request/user input.
-    const configPath = path.join(process.env.src_path, "postcss.config.js")
-    if (!fs.existsSync(configPath)) return null
+    // .cjs first: an app with "type": "module" (the scaffold default) must
+    // name a CommonJS config .cjs, and a .js one is ESM there.
+    const configPath = ["postcss.config.cjs", "postcss.config.js"]
+        // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - process.env.src_path is the app root set by the framework's own build tooling, not request/user input.
+        .map((name) => path.join(process.env.src_path, name))
+        .find((candidate) => fs.existsSync(candidate))
+    if (!configPath) return null
 
     const appRequire = createRequire(configPath)
 
     try {
-        const userConfig = appRequire(configPath)
+        const loaded = appRequire(configPath)
+        // require() of an ESM config returns its namespace.
+        const userConfig = loaded?.__esModule || loaded?.default ? loaded.default : loaded
         const pluginsConfig = userConfig?.plugins
 
         if (!pluginsConfig || Array.isArray(pluginsConfig) || typeof pluginsConfig !== "object") {
@@ -268,7 +274,28 @@ const getScssResourcesImport = () => {
 
 // Pre-bundling upfront avoids Vite discovering deps at runtime which causes
 // cascading full-page reloads and "stuck in loading" on dev server.
-const browserOptimizeDeps = [
+/**
+ * Keep only the packages this app can actually resolve.
+ *
+ * The list below is a superset covering every dependency a Catalyst app might
+ * use. Vite logs "Failed to resolve dependency: X, present in
+ * 'optimizeDeps.include'" for each entry it cannot find, so an app that uses
+ * half of them opened with 23 warning lines it could do nothing about.
+ */
+function resolvableFrom(candidates, appRoot) {
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - appRoot is the local project root resolved by the CLI.
+    const resolver = createRequire(path.join(appRoot, "package.json"))
+    return candidates.filter((name) => {
+        try {
+            resolver.resolve(name)
+            return true
+        } catch (error) {
+            return false
+        }
+    })
+}
+
+const candidateBrowserDeps = [
     "react",
     "react-dom",
     "react-dom/client",
@@ -364,13 +391,12 @@ export const sharedViteConfig = {
         // the bundler never tries to resolve the optional (opt-in) OTEL packages.
         external: nodeOnlyExternalDeps,
         optimizeDeps: {
-            include: [
-                "invariant",
-                "shallowequal",
-                "prop-types",
-                "redux-thunk",
-                "redux-logger",
-            ],
+            // Same treatment as the browser list: only include what this app
+            // can resolve, or Vite warns about every entry it cannot find.
+            include: resolvableFrom(
+                ["invariant", "shallowequal", "prop-types", "redux-thunk", "redux-logger"],
+                process.env.src_path
+            ),
             // Prevent pre-bundling React ecosystem packages for SSR to avoid duplicate
             // React instances. Pre-bundled copies in .vite/deps_ssr/ create a separate
             // React instance from node_modules/react used by react-dom/server, causing
@@ -437,7 +463,7 @@ export const sharedViteConfig = {
             path.join(process.env.src_path, "client/index.js"),
             path.join(process.env.src_path, "src/**/*.{js,jsx,ts,tsx}"),
         ],
-        include: browserOptimizeDeps,
+        include: resolvableFrom(candidateBrowserDeps, process.env.src_path),
         // 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
@@ -500,6 +526,16 @@ export const sharedViteConfig = {
     },
 }
 
+// Every catalyst-core subpath export except the main entry and webmcp, as bare
+// specifiers ("catalyst-core/hooks"). Read from package.json so a new subpath
+// stays externalized in dev SSR without touching this list.
+function catalystCoreExternalSubpaths() {
+    const { exports = {} } = JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"), "utf8"))
+    return Object.keys(exports)
+        .filter((key) => key.startsWith("./") && key !== "./package.json" && !key.startsWith("./webmcp"))
+        .map((key) => `catalyst-core/${key.slice(2)}`)
+}
+
 // ─── 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
@@ -512,6 +548,30 @@ export default defineConfig(async () => {
     return {
         ...sharedViteConfig,
         base: resolveDevBase(devServer),
+        // Dev SSR only: transform catalyst-core/webmcp through Vite instead of
+        // externalizing it. Node cannot load its .jsx files, and its provider
+        // must share one module record (one createContext()) with the main
+        // entry, which Vite always transforms (.jsx is never externalized).
+        // ssr.noExternal only matches package names, so the package goes in
+        // noExternal and every other subpath is pinned external: CJS subpaths
+        // (hooks, WebBridge, sentry) would fail to inline ("exports is not
+        // defined"), and apps that do not import webmcp resolve exactly as
+        // before. Keyed on NODE_ENV, not Vite's `command`: `catalyst build`
+        // also spins up this config for the offline manifest, and built
+        // output runs under plain Node ESM, one module record per file.
+        ssr: {
+            ...sharedViteConfig.ssr,
+            noExternal: [
+                ...new Set([
+                    ...(sharedViteConfig.ssr?.noExternal || []),
+                    ...(isProduction ? [] : ["catalyst-core"]),
+                ]),
+            ],
+            external: [
+                ...(sharedViteConfig.ssr?.external || []),
+                ...(isProduction ? [] : catalystCoreExternalSubpaths()),
+            ],
+        },
         server: buildDevServer(devServer, {
             frameworkPaths: [process.env.src_path, __dirname],
             isProduction,

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

@@ -28,8 +28,15 @@ export default defineConfig(async () => {
             ...(customViteConfig?.ssrPlugins || []),
         ],
 
+        // The CLI prints its own build summary and asset table, so Vite's
+        // duplicate table and rollup's advisory warnings are pure noise.
+
         build: {
             ...baseConfig.build,
+            // Parallel client and server builds share this directory -- emptying it
+            // would delete the other bundle. Declared explicitly so Vite does not
+            // warn about an outDir outside the project root.
+            emptyOutDir: false,
             outDir: path.join(process.env.src_path, process.env.BUILD_OUTPUT_PATH || "build"),
             target: "es2022",
             minify: "esbuild",
@@ -38,6 +45,20 @@ export default defineConfig(async () => {
             ssrManifest: false,
 
             rollupOptions: {
+                // Advisory warnings about third-party code the app author
+                // cannot act on: a dependency's misplaced /*#__PURE__*/ comment
+                // and unused re-exports from our own entry. Genuine problems
+                // (unresolved imports, circular deps, missing exports) still
+                // surface.
+                onwarn(warning, defaultHandler) {
+                    const ignored = new Set([
+                        "INVALID_ANNOTATION",
+                        "UNUSED_EXTERNAL_IMPORT",
+                        "MODULE_LEVEL_DIRECTIVE",
+                    ])
+                    if (ignored.has(warning.code)) return
+                    defaultHandler(warning)
+                },
                 // Belt-and-suspenders with ssr.external: ensures the opt-in OTEL /
                 // node-only packages (and their transitive @opentelemetry/* deps) are
                 // never resolved/bundled, even though they may not be installed.

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

@@ -1,4 +1,4 @@
-import React, { useContext, useState, useEffect } from "react";
+import React, { useContext, useState, useEffect, useRef } from "react";
 import { OneMgRouterContext } from "../context.jsx";
 import { useRouterData } from "./RouterDataProvider.jsx";
 import { getMetaData } from "../utils/metaDataUtils.jsx";
@@ -13,12 +13,25 @@ export const MetaTag = () => {
   } = useContext(OneMgRouterContext);
   const routeData = useRouterData();
   const location = useLocation();
-  const [metaTags, setMetaTags] = useState([]);
+  // 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);
     setMetaTags(Array.isArray(mergedMetaTags) ? mergedMetaTags : []);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [location]);
+  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

@@ -1,6 +1,7 @@
 import React from "react"
-import { describe, expect, it, vi } from "vitest"
-import { render, waitFor, act } from "@testing-library/react"
+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"
@@ -104,4 +105,72 @@ describe("MetaTag", () => {
             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={{}}>
+                        <button type="button" onClick={() => navigate("/b")}>
+                            go
+                        </button>
+                        <MetaTag />
+                    </RouterContext.Provider>
+                </OneMgRouterContext.Provider>
+            )
+        }
+        const tree = (
+            <MemoryRouter initialEntries={["/a"]}>
+                <App />
+            </MemoryRouter>
+        )
+
+        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"])
+        })
+    })
 })

package/dist/webmcp/WebMcpProvider.jsx

@@ -127,7 +127,7 @@ export function WebMcpProvider({ children, routes, filterNavigable }) {
             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)
+                console.warn('[webmcp] declarative tool "%s" failed to register:', spec.name, res.error)
         }
 
         // Framework: navigate + get_current_route + get_page_info.
@@ -146,7 +146,8 @@ export function WebMcpProvider({ children, routes, filterNavigable }) {
             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:`,
+                    '[webmcp] framework tool "%s" failed to register — a route tool may already use that name:',
+                    spec.name,
                     res.error
                 )
         }

package/dist/webmcp/useTool.js

@@ -1,3 +1,6 @@
+// The optional deps array is the caller's, passed through on purpose, which
+// the compiler cannot verify -- same exemption as the native bridge hooks.
+/* eslint-disable react-compiler/react-compiler */
 import { useContext, useEffect, useRef, useState } from "react"
 import { RouteContext } from "./routeContext.js"
 import { registerTool, unregisterTool, updateToolRoute, updateToolSpec, newOwnerKey } from "./registry.js"
@@ -86,7 +89,7 @@ export function useTool(spec, deps) {
         } else {
             setState({ status: "error", receipt: null, error: res.error })
             // eslint-disable-next-line no-console
-            console.warn(`[webmcp] useTool("${s.name}") failed to register:`, res.error)
+            console.warn('[webmcp] useTool("%s") failed to register:', s.name, res.error)
         }
 
         return () => {