catalyst-core 1.0.1 → 1.0.2-canary.1

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.",
+            }
+        },
+    }
+}

package/dist/webmcp/pageInfo.test.js

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest"
+import { flattenHeadElements, pageInfoTool } from "./pageInfo.js"
+
+// Plain objects with the stable `.type` / `.props` shape of a React element.
+const el = (type, props = {}) => ({ type, props })
+
+describe("flattenHeadElements", () => {
+    it("flattens title, description, canonical, keywords, og, twitter and other meta", () => {
+        const out = flattenHeadElements([
+            el("title", { children: "Home" }),
+            [
+                el("meta", { name: "description", content: "d" }),
+                el("meta", { name: "keywords", content: "k" }),
+                el("link", { rel: "canonical", href: "https://x.test/" }),
+                el("meta", { property: "og:title", content: "OG" }),
+                el("meta", { name: "twitter:card", content: "summary" }),
+                el("meta", { httpEquiv: "refresh", content: "5" }),
+            ],
+        ])
+        expect(out).toMatchObject({
+            title: "Home",
+            description: "d",
+            keywords: "k",
+            canonical: "https://x.test/",
+            og: { title: "OG" },
+            twitter: { card: "summary" },
+            other: { refresh: "5" },
+        })
+    })
+
+    it("joins array/number title children and drops empty groups", () => {
+        const out = flattenHeadElements([el("title", { children: ["Docs", " - ", 2] })])
+        expect(out.title).toBe("Docs - 2")
+        expect(out).not.toHaveProperty("og")
+        expect(out).not.toHaveProperty("twitter")
+        expect(out).not.toHaveProperty("other")
+    })
+
+    it("ignores non-elements, keyless meta, and a canonical link without href", () => {
+        const out = flattenHeadElements([
+            null,
+            "text",
+            el(null),
+            el("meta", { content: "orphan" }),
+            el("link", { rel: "canonical" }),
+        ])
+        expect(out.canonical).toBeNull()
+        expect(out.title).toBeNull()
+    })
+
+    it("returns null title for missing or non-text children", () => {
+        expect(flattenHeadElements([el("title")]).title).toBeNull()
+        expect(flattenHeadElements([el("title", { children: { x: 1 } })]).title).toBeNull()
+    })
+})
+
+describe("pageInfoTool", () => {
+    const matchWith = (fn) => [{ route: { component: { setMetaData: fn } } }]
+
+    it("collects setMetaData from every matched route, passing route data", async () => {
+        let seen
+        const tool = pageInfoTool(
+            () => matchWith((data) => ((seen = data), [el("title", { children: "T" })])),
+            () => ({ a: 1 })
+        )
+        const res = await tool.execute()
+        expect(seen).toEqual({ a: 1 })
+        expect(res.title).toBe("T")
+        expect(res._note).toBeUndefined()
+    })
+
+    it("survives a throwing setMetaData and notes that nothing was reported", async () => {
+        const tool = pageInfoTool(() => matchWith(() => { throw new Error("nope") }))
+        const res = await tool.execute()
+        expect(res.title).toBeNull()
+        expect(res._note).toMatch(/no setMetaData/)
+    })
+
+    it("tolerates no matches and no route-data getter", async () => {
+        const tool = pageInfoTool(() => null)
+        const res = await tool.execute()
+        expect(res._note).toBeDefined()
+        expect(tool.annotations.readOnlyHint).toBe(true)
+    })
+})

package/dist/webmcp/registry.dom.test.js

@@ -0,0 +1,175 @@
+// @vitest-environment jsdom
+/**
+ * Registry behaviour that needs a DOM: lifecycle events and the native /
+ * shim `document.modelContext` backend contract (receipt shapes, spec
+ * re-registration, argument validation).
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"
+import {
+    registerTool,
+    unregisterTool,
+    updateToolRoute,
+    updateToolSpec,
+    invokeTool,
+    inspect,
+    isNative,
+    hasBackend,
+    newOwnerKey,
+    __resetForTests,
+} from "./registry.js"
+
+const makeSpec = (over = {}) => ({
+    name: "t",
+    description: "d",
+    inputSchema: { type: "object", properties: {} },
+    execute: async () => "ok",
+    ...over,
+})
+
+function listen(type) {
+    const events = []
+    const h = (e) => events.push(e.detail)
+    document.addEventListener(type, h)
+    return { events, off: () => document.removeEventListener(type, h) }
+}
+
+describe("registry with a DOM", () => {
+    beforeEach(() => __resetForTests())
+    afterEach(() => {
+        delete document.modelContext
+        __resetForTests()
+    })
+
+    it("emits register / execute / unregister events", async () => {
+        const reg = listen("webmcp:register")
+        const start = listen("webmcp:execute:start")
+        const end = listen("webmcp:execute:end")
+        const unreg = listen("webmcp:unregister")
+        const k = newOwnerKey()
+        registerTool(k, "/r", makeSpec())
+        await invokeTool("t", { x: 1 })
+        unregisterTool(k)
+        expect(reg.events[0]).toMatchObject({ name: "t", routePath: "/r", replaced: false })
+        expect(start.events[0]).toMatchObject({ name: "t", args: { x: 1 } })
+        expect(end.events[0]).toMatchObject({ name: "t", ok: true, result: "ok" })
+        expect(unreg.events[0]).toMatchObject({ name: "t" })
+        ;[reg, start, end, unreg].forEach((l) => l.off())
+    })
+
+    it("reports a failed execute and an unknown tool as ok:false end events", async () => {
+        const end = listen("webmcp:execute:end")
+        registerTool(newOwnerKey(), "", makeSpec({ execute: async () => { throw new Error("bad") } }))
+        await expect(invokeTool("t")).rejects.toMatchObject({ code: "WEBMCP_EXECUTE_FAILED" })
+        await expect(invokeTool("missing")).rejects.toMatchObject({ code: "WEBMCP_TOOL_NOT_FOUND" })
+        expect(end.events.map((e) => e.ok)).toEqual([false, false])
+        end.off()
+    })
+
+    it("rejects invalid arguments before executing", async () => {
+        const execute = vi.fn(async () => "ran")
+        registerTool(
+            newOwnerKey(),
+            "",
+            makeSpec({
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        n: { type: "number", minimum: 2 },
+                        i: { type: "integer" },
+                        s: { type: "string" },
+                        b: { type: "boolean" },
+                    },
+                },
+                execute,
+            })
+        )
+        for (const args of [{ n: "x" }, { n: 1 }, { i: 1.5 }, { s: 3 }, { b: "no" }]) {
+            await expect(invokeTool("t", args)).rejects.toMatchObject({ code: "WEBMCP_INVALID_ARGS" })
+        }
+        await invokeTool("t", { n: 2, i: 3, s: "a", b: true })
+        expect(execute).toHaveBeenCalledTimes(1)
+    })
+
+    it("uses an installed document.modelContext and normalises its receipts", () => {
+        const registered = []
+        document.modelContext = {
+            registerTool: (s) => (registered.push(s), "string-id"),
+            unregisterTool: () => {},
+            getTools: () => [],
+        }
+        expect(isNative()).toBe(true)
+        const k = newOwnerKey()
+        const res = registerTool(k, "/p", makeSpec())
+        expect(res.receipt.id).toBe("string-id")
+        updateToolRoute(k, "/q")
+        expect(inspect().tools[0].routePath).toBe("/q")
+        // the string receipt falls back to api.unregisterTool(name)
+        expect(res.receipt.unregister()).toBe(true)
+        expect(registered).toHaveLength(1)
+    })
+
+    it("treats a shim-marked backend as non-native and handles object receipts", () => {
+        document.modelContext = {
+            __isWebMcpShim: true,
+            registerTool: () => ({ id: "obj", unregister() { return true } }),
+            getTools: () => [],
+        }
+        expect(isNative()).toBe(false)
+        const res = registerTool(newOwnerKey(), "", makeSpec())
+        expect(res.receipt.id).toBe("obj")
+    })
+
+    it("surfaces a backend registerTool failure as ok:false", () => {
+        document.modelContext = {
+            registerTool: () => { throw new Error("backend down") },
+            getTools: () => [],
+        }
+        const res = registerTool(newOwnerKey(), "", makeSpec())
+        expect(res.ok).toBe(false)
+        expect(res.error.message).toBe("backend down")
+    })
+
+    it("updateToolSpec re-registers only on a real change", () => {
+        const calls = []
+        document.modelContext = {
+            registerTool: (s) => (calls.push(s), { id: `r${calls.length}`, unregister() {} }),
+            getTools: () => [],
+        }
+        const reg = listen("webmcp:register")
+        const k = newOwnerKey()
+        registerTool(k, "/p", makeSpec())
+        updateToolSpec(k, { description: "d", inputSchema: { type: "object", properties: {} }, annotations: {} })
+        expect(calls).toHaveLength(1)
+        updateToolSpec(k, { description: "new", annotations: { readOnlyHint: true } })
+        expect(calls).toHaveLength(2)
+        expect(calls[1].description).toBe("new")
+        expect(reg.events.at(-1).replaced).toBe(true)
+        updateToolSpec("unknown-owner", { description: "x" })
+        reg.off()
+    })
+
+    it("aborts in-flight tool signals on unregister", async () => {
+        let signal
+        const k = newOwnerKey()
+        registerTool(k, "", makeSpec({ execute: async (_a, ctx) => { signal = ctx.signal } }))
+        await invokeTool("t")
+        unregisterTool(k)
+        expect(signal.aborted).toBe(true)
+        expect(() => unregisterTool(k)).not.toThrow()
+    })
+})
+
+describe("hasBackend", () => {
+    beforeEach(() => {
+        __resetForTests()
+        delete document.modelContext
+    })
+
+    it("is false with nothing installed, true for a shim (which isNative treats as non-native)", () => {
+        expect(hasBackend()).toBe(false)
+        document.modelContext = { __isWebMcpShim: true, registerTool: () => ({}) }
+        expect(hasBackend()).toBe(true)
+        expect(inspect().isNative).toBe(false)
+        delete document.modelContext
+    })
+})