catalyst-core 1.0.1 → 1.0.2-canary.1

package/dist/web-router/context.jsx

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

@@ -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}`
+}

package/dist/webmcp/declarative.js

@@ -0,0 +1,207 @@
+/**
+ * Declarative WebMCP tools — the §4a layer of discussion #466.
+ *
+ * A route declares its own tool config directly in routes/index.js, next to
+ * `path`/`component` — NOT as a static on the page component:
+ *
+ *   { path: "/products", component: ProductList, tool: {
+ *       description: "Browse the product catalogue, optionally filtered.",
+ *       searchParams: {
+ *         category: { type: "string", enum: ["footwear","electronics","apparel"], description: "..." },
+ *         maxPrice: { type: "number", description: "upper price bound in INR" },
+ *       },
+ *       annotations: { readOnlyHint: true },
+ *   } }
+ *
+ * `route.tool` over a `Component.tool` static: routing config belongs with
+ * the route, and — unlike a component static — it survives lazy-loading. A
+ * component rendered through Split (packages/catalyst-core/src/web-router/
+ * components/Split.tsx) only has its statics copied onto the lazy wrapper
+ * for the keys Split's own copyRouteStatics() lists (clientFetcher/
+ * serverFetcher/setMetaData); a `tool` static would silently vanish behind
+ * Split. `route.tool` needs no such patch: getRoutes() returns the route
+ * table directly, before any Split wrapping happens. No app has ever shipped
+ * the component-static form, so there is no fallback to carry here.
+ *
+ * From that + the route's path pattern, the framework derives a full WebMCP
+ * tool with zero extra wiring:
+ *
+ *   - name         from the path      ("/products" -> "products",
+ *                                       "/product/:id" -> "product")
+ *   - inputSchema   route :params (required) + declared searchParams (optional)
+ *   - execute       navigate to the filled path + query string, then report the
+ *                   new location. (This POC's pages fetch via Redux, not
+ *                   serverFetcher/clientFetcher, and plain {path,component}
+ *                   routes never have their fetchers invoked by Catalyst — so
+ *                   "navigate + refetch" degrades cleanly to "navigate".)
+ *
+ * Lifetime: declarative READ tools are registered ONCE, for the life of the
+ * app — NOT scoped to a matched route. That is the whole point: an agent
+ * sitting on /cart must still be able to call `products({category:"footwear"})`
+ * to get there. (Only imperative ACTION tools — useTool — are route-scoped,
+ * because acting on a page you've left is what you want to prevent.)
+ * This resolves open question #4 in the discussion for the POC.
+ */
+
+import { WebMcpError, WEBMCP_ERROR_CODES } from "./errors.js"
+
+/** "/product/:id" -> "product" ; "/products" -> "products" ; "/" -> "home" */
+export function toolNameFromPath(pathPattern) {
+    const segs = String(pathPattern)
+        .split("/")
+        .filter(Boolean)
+        .filter((s) => !s.startsWith(":"))
+    if (segs.length === 0) return "home"
+    return segs.join("_")
+}
+
+/** Pull ":id", ":slug" etc. out of a path pattern. */
+export function paramNames(pathPattern) {
+    return String(pathPattern)
+        .split("/")
+        .filter((s) => s.startsWith(":"))
+        .map((s) => s.slice(1))
+}
+
+/** Fill "/product/:id" + { id: "trail-runner-x" } -> "/product/trail-runner-x". */
+export function fillPath(pathPattern, params = {}) {
+    return String(pathPattern).replace(/:([A-Za-z0-9_]+)/g, (_, k) => {
+        if (params[k] == null || params[k] === "") {
+            throw new WebMcpError(WEBMCP_ERROR_CODES.INVALID_ARGS, {
+                message: `missing required path param "${k}" for ${pathPattern}`,
+            })
+        }
+        return encodeURIComponent(params[k])
+    })
+}
+
+/**
+ * Build the WebMCP inputSchema for a declarative tool: path params are required
+ * strings, declared searchParams are optional and typed as given.
+ */
+export function buildInputSchema(pathPattern, toolStatic) {
+    const properties = {}
+    const required = []
+    for (const p of paramNames(pathPattern)) {
+        properties[p] = { type: "string", description: `path parameter "${p}"` }
+        required.push(p)
+    }
+    const sp = (toolStatic && toolStatic.searchParams) || {}
+    for (const [key, def] of Object.entries(sp)) {
+        properties[key] = { ...def }
+    }
+    const schema = { type: "object", properties }
+    if (required.length) schema.required = required
+    return schema
+}
+
+/**
+ * Turn one route (with a `.tool` config) into a registrable WebMCP tool
+ * spec. `navigate` is react-router's navigate fn.
+ */
+export function declarativeToolFor(route, navigate) {
+    const toolStatic = route && route.tool
+    if (!toolStatic) return null
+
+    const pattern = route.path.startsWith("/") ? route.path : `/${route.path}`
+    const name = toolNameFromPath(pattern)
+    const params = paramNames(pattern)
+    const searchKeys = Object.keys((toolStatic && toolStatic.searchParams) || {})
+
+    return {
+        name,
+        description: toolStatic.description || `Open ${pattern}`,
+        inputSchema: buildInputSchema(pattern, toolStatic),
+        annotations: { readOnlyHint: true, ...(toolStatic.annotations || {}) },
+        execute: async (args = {}) => {
+            const pathParams = {}
+            for (const p of params) pathParams[p] = args[p]
+            const path = fillPath(pattern, pathParams)
+
+            const qs = new URLSearchParams()
+            for (const k of searchKeys) {
+                if (args[k] != null && args[k] !== "") qs.set(k, String(args[k]))
+            }
+            const query = qs.toString()
+            const to = query ? `${path}?${query}` : path
+
+            navigate(to)
+            return {
+                navigated: true,
+                path: to,
+                note:
+                    "Navigation done. The set of available tools changes with the route — " +
+                    "call get_current_route to see what's now callable before the next step.",
+            }
+        },
+    }
+}
+
+/**
+ * The two fixed framework tools from §4c.
+ *
+ * @param routes      flat route table `navigate`'s enum is built from — already
+ *                    run through the app's `filterNavigable`, if any (see
+ *                    WebMcpProvider). Parameterised routes ("/product/:id")
+ *                    are reachable through their own declarative tool, so
+ *                    only static paths are ever offered here.
+ * @param navigate    react-router navigate fn
+ * @param getCurrent  () => ({ pathname, params, patterns, tools })
+ * @param allRoutes   the FULL flat route table, before filterNavigable —
+ *                    optional, used only to give a more useful error when an
+ *                    agent asks for a path that's a real route but was
+ *                    deliberately excluded from `navigate` (e.g. one of many
+ *                    generated content pages, reachable through the app's
+ *                    own search/read tools instead).
+ */
+export function frameworkTools(routes, navigate, getCurrent, allRoutes) {
+    // Closed set of navigable destinations. Parameterised routes ("/product/:id")
+    // are reachable through their own declarative tool, so we list only the
+    // static paths here.
+    const staticPaths = routes
+        .map((r) => (r.path.startsWith("/") ? r.path : `/${r.path}`))
+        .filter((p) => !p.includes(":"))
+
+    const allPaths = allRoutes
+        ? allRoutes.map((r) => (r.path.startsWith("/") ? r.path : `/${r.path}`))
+        : staticPaths
+
+    return [
+        {
+            name: "navigate",
+            description: "Go to one of this app's pages.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", enum: staticPaths, description: "destination route" },
+                },
+                required: ["path"],
+            },
+            annotations: { readOnlyHint: true },
+            execute: async ({ path } = {}) => {
+                if (!staticPaths.includes(path)) {
+                    // A real route, just not one `navigate` offers (e.g. deliberately
+                    // excluded via filterNavigable) — say so, rather than implying
+                    // the path doesn't exist at all. get_current_route's own tool
+                    // list is the generic way to discover what IS callable right now.
+                    const isKnownButExcluded = allPaths.includes(path)
+                    throw new WebMcpError(WEBMCP_ERROR_CODES.INVALID_ARGS, {
+                        message: isKnownButExcluded
+                            ? `"${path}" exists but isn't a navigate() destination. Call get_current_route to see ` +
+                              "what other tools are callable right now — this app likely exposes it through one of those instead."
+                            : `"${path}" is not a navigable page. One of: ${staticPaths.join(", ")}`,
+                    })
+                }
+                navigate(path)
+                return { navigated: true, path }
+            },
+        },
+        {
+            name: "get_current_route",
+            description: "Report the current page, its URL params, and which tools are callable right now.",
+            inputSchema: { type: "object", properties: {} },
+            annotations: { readOnlyHint: true },
+            execute: async () => getCurrent(),
+        },
+    ]
+}

package/dist/webmcp/declarative.test.js

@@ -0,0 +1,122 @@
+import { describe, it, expect, vi } from "vitest"
+import {
+    toolNameFromPath,
+    paramNames,
+    fillPath,
+    buildInputSchema,
+    declarativeToolFor,
+    frameworkTools,
+} from "./declarative.js"
+import { flattenHeadElements } from "./pageInfo.js"
+import React from "react"
+
+describe("declarative helpers", () => {
+    it("derives tool names from path patterns", () => {
+        expect(toolNameFromPath("/")).toBe("home")
+        expect(toolNameFromPath("/products")).toBe("products")
+        expect(toolNameFromPath("/product/:id")).toBe("product")
+        expect(toolNameFromPath("/orders/:oid/items")).toBe("orders_items")
+    })
+
+    it("extracts and fills path params", () => {
+        expect(paramNames("/product/:id")).toEqual(["id"])
+        expect(fillPath("/product/:id", { id: "trail-runner-x" })).toBe("/product/trail-runner-x")
+        expect(() => fillPath("/product/:id", {})).toThrow(/missing required path param/)
+        expect(() => fillPath("/product/:id", {})).toThrow(expect.objectContaining({ code: "WEBMCP_INVALID_ARGS" }))
+    })
+
+    it("builds an inputSchema: params required, searchParams optional", () => {
+        const s = buildInputSchema("/product/:id", {
+            searchParams: { variant: { type: "string" } },
+        })
+        expect(s.required).toEqual(["id"])
+        expect(s.properties.id.type).toBe("string")
+        expect(s.properties.variant.type).toBe("string")
+        expect(s.required).not.toContain("variant")
+    })
+
+    it("declarativeToolFor returns null when the route has no .tool config", () => {
+        expect(declarativeToolFor({ path: "/x", component: () => null }, vi.fn())).toBeNull()
+    })
+
+    it("declarativeToolFor reads route.tool", async () => {
+        const navigate = vi.fn()
+        const route = {
+            path: "/products",
+            component: () => null,
+            tool: {
+                description: "list",
+                searchParams: { category: { type: "string" }, maxPrice: { type: "number" } },
+            },
+        }
+        const spec = declarativeToolFor(route, navigate)
+        expect(spec.name).toBe("products")
+        expect(spec.annotations.readOnlyHint).toBe(true)
+
+        const res = await spec.execute({ category: "footwear", maxPrice: 3000 })
+        expect(navigate).toHaveBeenCalledWith("/products?category=footwear&maxPrice=3000")
+        expect(res.navigated).toBe(true)
+    })
+
+    it("frameworkTools: navigate enum excludes parameterised routes; rejects unknown", async () => {
+        const navigate = vi.fn()
+        const routes = [
+            { path: "/" },
+            { path: "/products" },
+            { path: "/product/:id" },
+            { path: "/cart" },
+        ]
+        const [nav] = frameworkTools(routes, navigate, () => ({}))
+        expect(nav.inputSchema.properties.path.enum).toEqual(["/", "/products", "/cart"])
+
+        await expect(nav.execute({ path: "/product/:id" })).rejects.toThrow(/not a navigable page/)
+        await nav.execute({ path: "/cart" })
+        expect(navigate).toHaveBeenCalledWith("/cart")
+    })
+
+    it("frameworkTools: navigate gives a distinct, actionable error for a route excluded via filterNavigable", async () => {
+        const navigate = vi.fn()
+        const navigableRoutes = [{ path: "/" }, { path: "/errors" }]
+        const allRoutes = [{ path: "/" }, { path: "/errors" }, { path: "/content/foo" }, { path: "/content/bar" }]
+        const [nav] = frameworkTools(navigableRoutes, navigate, () => ({}), allRoutes)
+
+        // A genuinely unknown path still gets the generic "not a navigable page" message.
+        await expect(nav.execute({ path: "/nope" })).rejects.toMatchObject({ code: "WEBMCP_INVALID_ARGS" })
+        await expect(nav.execute({ path: "/nope" })).rejects.toThrow(/not a navigable page/)
+
+        // A real route that was deliberately excluded gets a DIFFERENT, more
+        // useful message — pointing the agent at get_current_route instead of
+        // implying the page doesn't exist.
+        await expect(nav.execute({ path: "/content/foo" })).rejects.toMatchObject({ code: "WEBMCP_INVALID_ARGS" })
+        await expect(nav.execute({ path: "/content/foo" })).rejects.toThrow(/exists but isn't a navigate\(\) destination/)
+        expect(navigate).not.toHaveBeenCalled()
+    })
+})
+
+describe("pageInfo.flattenHeadElements", () => {
+    it("flattens title / description / og / twitter", () => {
+        const els = [
+            [
+                React.createElement("title", { key: "t" }, "My Page"),
+                React.createElement("meta", { key: "d", name: "description", content: "about my page" }),
+                React.createElement("meta", { key: "o", property: "og:title", content: "OG My Page" }),
+                React.createElement("meta", { key: "w", name: "twitter:card", content: "summary" }),
+                React.createElement("meta", { key: "k", name: "keywords", content: "a,b,c" }),
+                React.createElement("link", { key: "c", rel: "canonical", href: "https://x.test/" }),
+            ],
+        ]
+        const info = flattenHeadElements(els)
+        expect(info.title).toBe("My Page")
+        expect(info.description).toBe("about my page")
+        expect(info.og.title).toBe("OG My Page")
+        expect(info.twitter.card).toBe("summary")
+        expect(info.keywords).toBe("a,b,c")
+        expect(info.canonical).toBe("https://x.test/")
+    })
+
+    it("returns nulls for a page with no head elements", () => {
+        const info = flattenHeadElements([])
+        expect(info.title).toBeNull()
+        expect(info.description).toBeNull()
+    })
+})

package/dist/webmcp/errors.js

@@ -0,0 +1,59 @@
+/**
+ * WebMcpError — the error type for catalyst-core's WebMCP integration.
+ *
+ * Shaped deliberately like catalyst-core's `CatalystError` (same `.code`,
+ * `.details`, `.suggestedAction`, `.cause` fields) so a later integration can
+ * swap these ad-hoc codes for registry codes from `catalyst-core/errors`
+ * without changing any call sites. The framework's own error registry
+ * (PREFLIGHT_* / RUNTIME_WEB_* / AI_* …) has no code that means "a page
+ * tool's execute() threw" or "the agent called a tool that isn't registered
+ * on this route", so this module defines its own small set. That mapping
+ * (folding these into the shared registry) is a follow-up, not part of this
+ * migration — src/errors/registry.js has its own contract tests (#411) that
+ * this module deliberately does not touch.
+ */
+
+export const WEBMCP_ERROR_CODES = Object.freeze({
+    /** Agent invoked a tool name that is not currently registered. */
+    TOOL_NOT_FOUND: "WEBMCP_TOOL_NOT_FOUND",
+    /** Agent-supplied arguments failed a (shallow) inputSchema check. */
+    INVALID_ARGS: "WEBMCP_INVALID_ARGS",
+    /** The tool's own execute() threw or rejected. Original error is `.cause`. */
+    EXECUTE_FAILED: "WEBMCP_EXECUTE_FAILED",
+    /** The tool's route was left (or component unmounted) before execute() finished. */
+    ABORTED: "WEBMCP_ABORTED",
+    /** registerTool was called with a name that is already live. */
+    DUPLICATE_TOOL: "WEBMCP_DUPLICATE_TOOL",
+})
+
+export class WebMcpError extends Error {
+    constructor(code, { message, details, suggestedAction, cause } = {}) {
+        super(message || code)
+        this.name = "WebMcpError"
+        this.code = code
+        this.details = details
+        this.suggestedAction = suggestedAction
+        if (cause !== undefined) this.cause = cause
+    }
+
+    /** Plain object suitable for returning to an agent / rendering in a dev panel. */
+    toResult() {
+        return {
+            ok: false,
+            code: this.code,
+            message: this.message,
+            details: this.details,
+            suggestedAction: this.suggestedAction,
+        }
+    }
+}
+
+/**
+ * Wrap whatever a tool's execute() threw. If it already is a WebMcpError we
+ * keep it; otherwise it becomes EXECUTE_FAILED with the original as `cause`.
+ */
+export function toWebMcpError(err, fallbackCode = WEBMCP_ERROR_CODES.EXECUTE_FAILED) {
+    if (err instanceof WebMcpError) return err
+    const message = err && err.message ? err.message : String(err)
+    return new WebMcpError(fallbackCode, { message, cause: err })
+}