catalyst-core 1.0.1 → 1.0.2-canary.2

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 })
+}

package/dist/webmcp/errors.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest"
+import { WebMcpError, WEBMCP_ERROR_CODES, toWebMcpError } from "./errors.js"
+
+describe("WebMcpError", () => {
+    it("falls back to the code as message and keeps an optional cause", () => {
+        const cause = new Error("root")
+        const e = new WebMcpError(WEBMCP_ERROR_CODES.EXECUTE_FAILED, { cause })
+        expect(e.message).toBe(WEBMCP_ERROR_CODES.EXECUTE_FAILED)
+        expect(e.cause).toBe(cause)
+    })
+
+    it("toResult() is a plain agent-facing object", () => {
+        const e = new WebMcpError(WEBMCP_ERROR_CODES.INVALID_ARGS, {
+            message: "bad",
+            details: "d",
+            suggestedAction: "retry",
+        })
+        expect(e.toResult()).toEqual({
+            ok: false,
+            code: WEBMCP_ERROR_CODES.INVALID_ARGS,
+            message: "bad",
+            details: "d",
+            suggestedAction: "retry",
+        })
+    })
+})
+
+describe("toWebMcpError", () => {
+    it("passes a WebMcpError through untouched", () => {
+        const e = new WebMcpError(WEBMCP_ERROR_CODES.ABORTED)
+        expect(toWebMcpError(e)).toBe(e)
+    })
+
+    it("wraps an Error as EXECUTE_FAILED with the original as cause", () => {
+        const orig = new Error("boom")
+        const w = toWebMcpError(orig)
+        expect(w.code).toBe(WEBMCP_ERROR_CODES.EXECUTE_FAILED)
+        expect(w.message).toBe("boom")
+        expect(w.cause).toBe(orig)
+    })
+
+    it("stringifies non-Error throwables and honours a fallback code", () => {
+        const w = toWebMcpError("plain string", WEBMCP_ERROR_CODES.INVALID_ARGS)
+        expect(w.message).toBe("plain string")
+        expect(w.code).toBe(WEBMCP_ERROR_CODES.INVALID_ARGS)
+    })
+})

package/dist/webmcp/index.js

@@ -0,0 +1,40 @@
+/**
+ * catalyst-core/webmcp — WebMCP integration for Catalyst apps.
+ *
+ * Public exports:
+ *
+ *   WebMcpProvider — framework glue. Mount once, inside RouterDataProvider,
+ *     wrapping the app. Takes the app's OWN route table as `routes` (core
+ *     cannot reach into an app's routing module the way the framework's own
+ *     route preparation can). Publishes route scope to useTool() and reaps
+ *     stale route-scoped tools on navigation.
+ *
+ *   useTool(spec, deps?) — register an imperative action tool for the
+ *     lifetime of the calling component, or (with a `deps` array) refresh
+ *     its description/inputSchema/annotations in place whenever a dep
+ *     changes, without tearing the registration down. Returns
+ *     { status, receipt, error } — the receipt is a registration handle,
+ *     deliberately not an execution result.
+ *
+ *   WebMcpError / WEBMCP_ERROR_CODES — the typed error a tool's execute()
+ *     should throw for a recoverable failure (bad args, not found, …) so an
+ *     agent gets a `.code` to act on instead of an opaque message.
+ *
+ * A DOM shim for browsers without native `document.modelContext` support is
+ * a SEPARATE opt-in subpath: `catalyst-core/webmcp/shim`. It is never
+ * imported here — an app calls its `installShim()` itself, once, before
+ * WebMcpProvider mounts, if it needs WebMCP to work without native support.
+ * Likewise a dev panel (a way to exercise tools by hand without a real
+ * agent) is an app-level concern, not shipped from core: subscribe to the
+ * `webmcp:register` / `webmcp:unregister` / `webmcp:execute:start` /
+ * `webmcp:execute:end` events this module's registry dispatches on
+ * `document`, and call `inspect()`/`invokeTool()` — both exported here for
+ * exactly that purpose.
+ */
+
+export { WebMcpProvider, flattenRoutes } from "./WebMcpProvider.jsx"
+export { useTool } from "./useTool.js"
+export { WebMcpError, WEBMCP_ERROR_CODES } from "./errors.js"
+export { inspect, invokeTool, isNative } from "./registry.js"
+export { declarativeToolFor, frameworkTools, toolNameFromPath, paramNames, fillPath, buildInputSchema } from "./declarative.js"
+export { pageInfoTool, flattenHeadElements } from "./pageInfo.js"

package/dist/webmcp/native.js

@@ -0,0 +1,37 @@
+/**
+ * Native `document.modelContext` detection — the part of WebMCP integration
+ * that is genuinely framework-owned: there is one `document.modelContext`
+ * per document, so there is one place that should decide whether a native
+ * implementation is present.
+ *
+ * NOTE: native WebMCP is intentionally UNSUPPORTED for now — no agent can
+ * drive a native `document.modelContext` yet, so Catalyst targets the opt-in
+ * shim (`catalyst-core/webmcp/shim`). The registry's teardown (receipt
+ * `unregister()` / `unregisterTool`) follows the shim's contract, not the
+ * spec's `registerTool(tool, { signal })` abort-to-unregister model, so
+ * revisit registry.js before relying on a native backend.
+ *
+ * This module does NOT install anything. It only looks. Installing a
+ * fallback (a DOM shim for browsers with no native WebMCP support yet, or an
+ * in-memory stand-in for SSR/tests) is a separate concern — see
+ * `catalyst-core/webmcp/shim` for the opt-in DOM shim, and registry.js's own
+ * `createFallbackBackend()` for the SSR/test safety net. Neither of those
+ * runs unless something explicitly calls it; importing this module alone
+ * never touches `document`.
+ */
+
+/** Locate a native modelContext, checking both documented mount points. */
+export function nativeModelContext() {
+    if (typeof document !== "undefined" && document.modelContext && !document.modelContext.__isWebMcpShim) {
+        return document.modelContext
+    }
+    if (typeof navigator !== "undefined" && navigator.modelContext && !navigator.modelContext.__isWebMcpShim) {
+        return navigator.modelContext
+    }
+    return null
+}
+
+/** Whether a real (non-shim) `document.modelContext` is present right now. */
+export function hasNative() {
+    return !!nativeModelContext()
+}

package/dist/webmcp/native.test.js

@@ -0,0 +1,41 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach } from "vitest"
+import { nativeModelContext, hasNative } from "./native.js"
+import { RouteContext } from "./routeContext.js"
+
+describe("native modelContext detection", () => {
+    afterEach(() => {
+        delete document.modelContext
+        delete navigator.modelContext
+    })
+
+    it("finds nothing when no modelContext is installed", () => {
+        expect(nativeModelContext()).toBeNull()
+        expect(hasNative()).toBe(false)
+    })
+
+    it("finds a native document.modelContext", () => {
+        const api = { registerTool() {} }
+        document.modelContext = api
+        expect(nativeModelContext()).toBe(api)
+        expect(hasNative()).toBe(true)
+    })
+
+    it("falls back to navigator.modelContext", () => {
+        const api = { registerTool() {} }
+        navigator.modelContext = api
+        expect(nativeModelContext()).toBe(api)
+    })
+
+    it("does not count a shim as native, on either mount point", () => {
+        document.modelContext = { __isWebMcpShim: true }
+        navigator.modelContext = { __isWebMcpShim: true }
+        expect(nativeModelContext()).toBeNull()
+    })
+})
+
+describe("RouteContext", () => {
+    it("defaults to the empty (app-lifetime) route path", () => {
+        expect(RouteContext._currentValue).toBe("")
+    })
+})

package/dist/webmcp/pageInfo.js

@@ -0,0 +1,119 @@
+/**
+ * get_page_info — a framework WebMCP tool that describes the current page to an
+ * agent, built ENTIRELY from metadata the app already writes for SEO.
+ *
+ * Catalyst pages define `Component.setMetaData(routeData)` returning an array of
+ * JSX <head> elements (<title>, <meta name/property ... content ...>). MetaTag
+ * renders exactly this into the document head. We read the SAME static, call it,
+ * and flatten the elements into a plain object an agent can consume:
+ *
+ *   { title, description, canonical, og: {...}, keywords, raw: [...] }
+ *
+ * No new authoring surface: if the page has good meta tags, the agent gets a
+ * good page description for free. This is the read-side complement to
+ * get_current_route ("where am I") — "what is this page and what's it for".
+ *
+ * Phase-3 note for discussion #466: the next layer up is the browser's
+ * accessibility tree (roles, landmarks, labelled controls) — a structured map
+ * of the page the platform already computes for screen readers. WebMCP could
+ * surface that too instead of leaving agents to DOM-scrape.
+ */
+
+/**
+ * Pull `{ type, props }` out of a React element without depending on React
+ * internals beyond the stable `.type` / `.props` shape.
+ */
+function readEl(el) {
+    if (!el || typeof el !== "object") return null
+    const type = typeof el.type === "string" ? el.type : null
+    const props = el.props || {}
+    return { type, props }
+}
+
+/**
+ * Flatten an array of head JSX elements (possibly nested arrays) into a
+ * plain, agent-friendly object.
+ */
+export function flattenHeadElements(elements) {
+    const out = { title: null, description: null, canonical: null, keywords: null, og: {}, twitter: {}, other: {} }
+    const walk = (node) => {
+        if (Array.isArray(node)) return node.forEach(walk)
+        const el = readEl(node)
+        if (!el || !el.type) return
+        const { type, props } = el
+
+        if (type === "title") {
+            out.title = childText(props.children)
+            return
+        }
+        if (type === "link" && (props.rel === "canonical")) {
+            out.canonical = props.href || null
+            return
+        }
+        if (type === "meta") {
+            const key = props.name || props.property || props["http-equiv"] || props.httpEquiv
+            const content = props.content
+            if (!key) return
+            if (key === "description") out.description = content
+            else if (key === "keywords") out.keywords = content
+            else if (String(key).startsWith("og:")) out.og[String(key).slice(3)] = content
+            else if (String(key).startsWith("twitter:")) out.twitter[String(key).slice(8)] = content
+            else out.other[key] = content
+        }
+    }
+    walk(elements)
+    // drop empties for a cleaner payload
+    if (!Object.keys(out.og).length) delete out.og
+    if (!Object.keys(out.twitter).length) delete out.twitter
+    if (!Object.keys(out.other).length) delete out.other
+    return out
+}
+
+function childText(children) {
+    if (children == null) return null
+    if (typeof children === "string" || typeof children === "number") return String(children)
+    if (Array.isArray(children)) return children.map(childText).filter(Boolean).join("")
+    return null
+}
+
+/**
+ * Build the get_page_info tool.
+ *
+ * @param getMatched  () => RouteMatch[]  (the current matched-route chain)
+ * @param getRouteData () => object       (RouterContext data, or {} — POC pages
+ *                                         use Redux so this is usually empty)
+ */
+export function pageInfoTool(getMatched, getRouteData) {
+    return {
+        name: "get_page_info",
+        description:
+            "Describe the current page: its title, description, and social/SEO metadata — " +
+            "the same information the page publishes in its <head>. Use this to understand " +
+            "what a page is about before acting on it.",
+        inputSchema: { type: "object", properties: {} },
+        annotations: { readOnlyHint: true },
+        execute: async () => {
+            const matched = getMatched() || []
+            const routeData = (getRouteData && getRouteData()) || {}
+            const collected = []
+            for (const m of matched) {
+                const fn = m && m.route && m.route.component && m.route.component.setMetaData
+                if (typeof fn === "function") {
+                    try {
+                        collected.push(fn(routeData))
+                    } catch (err) {
+                        // a page's setMetaData threw — report it, don't crash the tool
+                        collected.push([])
+                    }
+                }
+            }
+            const info = flattenHeadElements(collected)
+            const hasAny = info.title || info.description || info.canonical
+            return {
+                ...info,
+                _source: "Component.setMetaData (same as the page <head>)",
+                _note: hasAny ? undefined : "This page defines no setMetaData; nothing to report.",
+            }
+        },
+    }
+}