catalyst-core 1.0.1 → 1.0.2-canary.2

package/dist/webmcp/registry.test.js

@@ -0,0 +1,228 @@
+/**
+ * Registry-level unit tests — no browser, no React.
+ *
+ * These pin the two behaviours the headless E2E can only observe indirectly:
+ *   - reapUnmatched() actually removes route-scoped tools whose route is gone
+ *     (in the browser, React unmount cleanup usually gets there first, so the
+ *     E2E can't tell which mechanism fired).
+ *   - a same-name collision across two owners is rejected, not silently
+ *     clobbered.
+ */
+import { describe, it, expect, beforeEach } from "vitest"
+import {
+    registerTool,
+    unregisterTool,
+    updateToolSpec,
+    reapUnmatched,
+    invokeTool,
+    inspect,
+    newOwnerKey,
+    __resetForTests,
+    __getBackendTools,
+} from "./registry.js"
+
+const spec = (name, execute = async () => `ran ${name}`) => ({
+    name,
+    description: `test ${name}`,
+    inputSchema: { type: "object", properties: {} },
+    execute,
+})
+
+describe("registry", () => {
+    beforeEach(() => {
+        __resetForTests()
+    })
+
+    it("reapUnmatched removes tools whose route is not in the keep-set", () => {
+        const k = newOwnerKey()
+        const res = registerTool(k, "/ghost/:id", spec("ghost_tool"))
+        expect(res.ok).toBe(true)
+        expect(inspect().tools.map((t) => t.name)).toContain("ghost_tool")
+
+        const reaped = reapUnmatched(new Set(["/cart", "/products"]))
+        expect(reaped).toEqual(["ghost_tool"])
+        expect(inspect().tools.map((t) => t.name)).not.toContain("ghost_tool")
+    })
+
+    it("reapUnmatched keeps tools whose route IS still matched", () => {
+        const k = newOwnerKey()
+        registerTool(k, "/cart", spec("checkout"))
+        const reaped = reapUnmatched(new Set(["/cart"]))
+        expect(reaped).toEqual([])
+        expect(inspect().tools.map((t) => t.name)).toContain("checkout")
+        unregisterTool(k)
+    })
+
+    it("reapUnmatched never touches app-scoped tools (routePath '')", () => {
+        const k = newOwnerKey()
+        registerTool(k, "", spec("global_help"))
+        reapUnmatched(new Set(["/literally-nothing"]))
+        expect(inspect().tools.map((t) => t.name)).toContain("global_help")
+        unregisterTool(k)
+    })
+
+    it("rejects a same-name tool from a different owner", () => {
+        const a = newOwnerKey()
+        const b = newOwnerKey()
+        const first = registerTool(a, "/product/:id", spec("add_to_cart"))
+        expect(first.ok).toBe(true)
+
+        const second = registerTool(b, "/other/:id", spec("add_to_cart"))
+        expect(second.ok).toBe(false)
+        expect(second.error.code).toBe("WEBMCP_DUPLICATE_TOOL")
+
+        // the original still works
+        expect(inspect().tools.filter((t) => t.name === "add_to_cart")).toHaveLength(1)
+        unregisterTool(a)
+    })
+
+    it("invokeTool runs the registered execute and surfaces arg-validation errors", async () => {
+        const k = newOwnerKey()
+        registerTool(k, "/product/:id", {
+            name: "buy",
+            description: "buy N",
+            inputSchema: { type: "object", properties: { qty: { type: "number", minimum: 1 } } },
+            execute: async ({ qty }) => `bought ${qty}`,
+        })
+
+        await expect(invokeTool("buy", { qty: 3 })).resolves.toBe("bought 3")
+        await expect(invokeTool("buy", { qty: "lots" })).rejects.toMatchObject({
+            code: "WEBMCP_INVALID_ARGS",
+        })
+        await expect(invokeTool("no_such_tool", {})).rejects.toMatchObject({
+            code: "WEBMCP_TOOL_NOT_FOUND",
+        })
+        unregisterTool(k)
+    })
+
+    it("a reaped tool cannot be invoked afterwards", async () => {
+        const k = newOwnerKey()
+        registerTool(k, "/gone", spec("stale_tool"))
+        reapUnmatched(new Set(["/elsewhere"]))
+        await expect(invokeTool("stale_tool", {})).rejects.toMatchObject({
+            code: "WEBMCP_TOOL_NOT_FOUND",
+        })
+    })
+
+    it("updateToolSpec refreshes the AGENT-VISIBLE schema, and an in-flight call still survives", async () => {
+        const k = newOwnerKey()
+        let releaseCall
+        const callStarted = new Promise((resolve) => {
+            registerTool(k, "/product/:id", {
+                name: "add_to_cart",
+                description: "v1",
+                inputSchema: { type: "object", properties: { qty: { type: "number", minimum: 1 } } },
+                execute: async ({ qty }) => {
+                    resolve()
+                    await new Promise((r) => {
+                        releaseCall = r
+                    })
+                    return `added ${qty}`
+                },
+            })
+        })
+
+        // Before the swap, the backend (what an agent actually sees) has the
+        // v1 schema — no `size` property.
+        const before = __getBackendTools().find((t) => t.name === "add_to_cart")
+        expect(before.description).toBe("v1")
+        expect(before.inputSchema.properties.size).toBeUndefined()
+
+        const inFlight = invokeTool("add_to_cart", { qty: 2 })
+        await callStarted
+
+        // Simulate a deps-array change mid-call (e.g. product changed size options).
+        updateToolSpec(k, {
+            description: "v2",
+            inputSchema: {
+                type: "object",
+                properties: { qty: { type: "number", minimum: 1 }, size: { type: "string" } },
+            },
+        })
+
+        // Same registration (same owner, same entry) — NOT torn down. The
+        // in-flight call, dispatched before the swap, still completes.
+        releaseCall()
+        await expect(inFlight).resolves.toBe("added 2")
+
+        // The backend now serves the NEW schema — this is the part that
+        // matters for an agent actually seeing the update.
+        const after = __getBackendTools().find((t) => t.name === "add_to_cart")
+        expect(after.description).toBe("v2")
+        expect(after.inputSchema.properties.size).toBeDefined()
+
+        // A call made AFTER the swap validates against the NEW schema.
+        await expect(invokeTool("add_to_cart", { qty: "nope" })).rejects.toMatchObject({
+            code: "WEBMCP_INVALID_ARGS",
+        })
+
+        // Still exactly one registration for this tool — the swap replaced,
+        // it didn't duplicate.
+        expect(inspect().tools.filter((t) => t.name === "add_to_cart")).toHaveLength(1)
+        unregisterTool(k)
+    })
+
+    it("updateToolSpec is a no-op when nothing actually changed", () => {
+        const k = newOwnerKey()
+        const schema = { type: "object", properties: {} }
+        registerTool(k, "/cart", { name: "checkout", description: "d", inputSchema: schema, execute: async () => "ok" })
+        const idBefore = inspect().tools.find((t) => t.name === "checkout").receiptId
+
+        updateToolSpec(k, { description: "d", inputSchema: schema })
+
+        // Re-register never ran (nothing changed), so the receipt is untouched.
+        const idAfter = inspect().tools.find((t) => t.name === "checkout").receiptId
+        expect(idAfter).toBe(idBefore)
+        unregisterTool(k)
+    })
+})
+
+describe("registry in-memory fallback backend (no document.modelContext)", () => {
+    beforeEach(() => {
+        __resetForTests()
+    })
+
+    it("registers, lists and executes through the fallback, and reports not-native", async () => {
+        const k = newOwnerKey()
+        expect(registerTool(k, "", spec("fb_tool")).ok).toBe(true)
+        expect(__getBackendTools()).toEqual([
+            { name: "fb_tool", description: "test fb_tool", inputSchema: { type: "object", properties: {} } },
+        ])
+        expect(inspect().isNative).toBe(false)
+        expect(await invokeTool("fb_tool")).toBe("ran fb_tool")
+    })
+
+    it("updateToolSpec treats a structurally equal schema as unchanged and a different one as a change", () => {
+        const k = newOwnerKey()
+        const schema = { type: "object", properties: { a: { type: "string" } } }
+        registerTool(k, "", { ...spec("u"), inputSchema: schema })
+        const before = inspect().tools[0].receiptId
+        updateToolSpec(k, { inputSchema: JSON.parse(JSON.stringify(schema)) })
+        expect(inspect().tools[0].receiptId).toBe(before)
+        updateToolSpec(k, { inputSchema: { type: "object", properties: { a: { type: "string" }, b: { type: "number" } } } })
+        expect(inspect().tools[0].receiptId).not.toBe(before)
+    })
+
+    it("rejects a second owner registering the same tool name", () => {
+        registerTool(newOwnerKey(), "/a", spec("dup"))
+        const res = registerTool(newOwnerKey(), "/b", spec("dup"))
+        expect(res.ok).toBe(false)
+        expect(res.error.code).toBe("WEBMCP_DUPLICATE_TOOL")
+    })
+})
+
+describe("required-argument validation", () => {
+    beforeEach(() => {
+        __resetForTests()
+    })
+
+    it("rejects a call missing a required arg with INVALID_ARGS", async () => {
+        registerTool(newOwnerKey(), "", {
+            ...spec("needs_id"),
+            inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+        })
+        await expect(invokeTool("needs_id", {})).rejects.toMatchObject({ code: "WEBMCP_INVALID_ARGS" })
+        await expect(invokeTool("needs_id", { id: null })).rejects.toThrow(/Missing required argument: id/)
+        expect(await invokeTool("needs_id", { id: "x" })).toBe("ran needs_id")
+    })
+})

package/dist/webmcp/routeContext.js

@@ -0,0 +1,11 @@
+import { createContext } from "react"
+
+/**
+ * Carries the *route path pattern* of the nearest matched route ("/product/:id",
+ * "/cart", …) down to every `useTool` call, so each tool knows which route it
+ * belongs to and WebMcpProvider can reap it on navigation.
+ *
+ * Empty string = "not under a known route" → the tool is treated as
+ * app-lifetime, not route-scoped, and is never reaped.
+ */
+export const RouteContext = createContext("")

package/dist/webmcp/shim-entry.js

@@ -0,0 +1,8 @@
+/**
+ * catalyst-core/webmcp/shim — opt-in DOM shim for `document.modelContext`.
+ *
+ * Not imported by `catalyst-core/webmcp`'s own entry point. Call
+ * `installShim()` once, before mounting WebMcpProvider, in any app that
+ * wants WebMCP to work in a browser without native support.
+ */
+export { installShim } from "./shim.js"

package/dist/webmcp/shim.js

@@ -0,0 +1,149 @@
+/**
+ * document.modelContext shim — published as the opt-in `catalyst-core/webmcp/shim`
+ * subpath, never imported by WebMcpProvider or the core `./webmcp` entry
+ * point itself.
+ *
+ * WebMCP's real entry point (Chrome origin trial, unstable) hangs a
+ * `modelContext` object off `navigator` and/or `document` with `registerTool`,
+ * `getTools`, and an agent-side `executeTool`. This shim provides the same
+ * surface so an app runs in any browser, not just one with native WebMCP.
+ *
+ * Import-time side-effect-free: nothing happens until an app calls
+ * `installShim()` itself (typically once, before WebMcpProvider mounts).
+ * Core ships provider/hooks/framework-tools only (no shim, no dev panel) —
+ * an app that wants WebMCP to work in a browser without native support opts
+ * into this subpath explicitly.
+ *
+ * Design choices:
+ *   - Installs only when there is no native implementation — unless forced
+ *     via `?webmcp=shim` or `localStorage.webmcp=shim` (useful for demoing/
+ *     testing the shim path even on a browser that does have native support).
+ *   - `registerTool(spec)` returns a *registration receipt* — `{ id, name,
+ *     registeredAt, unregister() }` — deliberately distinct from the value
+ *     `executeTool` resolves to: discovery/registration is distinguishable
+ *     from successful execution.
+ *   - Lifecycle *events* are emitted by registry.js, not here, so a dev
+ *     panel or other observer behaves the same whether the backend is this
+ *     shim or a native implementation.
+ */
+
+import { nativeModelContext } from "./native.js"
+
+let _seq = 0
+const nextId = () => `tool_${Date.now().toString(36)}_${(++_seq).toString(36)}`
+
+/** True when ?webmcp=shim (or localStorage webmcp=shim) forces the shim even if native exists. */
+function shimForced() {
+    if (typeof window === "undefined") return false
+    try {
+        const q = new URLSearchParams(window.location.search)
+        if (q.get("webmcp") === "shim") return true
+        if (window.localStorage && window.localStorage.getItem("webmcp") === "shim") return true
+    } catch {
+        /* ignore */
+    }
+    return false
+}
+
+function createShim() {
+    /** name -> { spec, id, registeredAt } */
+    const tools = new Map()
+
+    const api = {
+        __isWebMcpShim: true,
+
+        registerTool(spec) {
+            if (!spec || typeof spec.name !== "string" || !spec.name) {
+                throw new Error("registerTool: spec.name is required")
+            }
+            if (typeof spec.execute !== "function") {
+                throw new Error(`registerTool("${spec.name}"): spec.execute must be a function`)
+            }
+            // Last-registration-wins at this layer; the framework layer decides
+            // whether a same-name collision across owners is an error.
+            const replaced = tools.has(spec.name)
+            const id = nextId()
+            const registeredAt = Date.now()
+            tools.set(spec.name, { spec, id, registeredAt })
+
+            return {
+                id,
+                name: spec.name,
+                registeredAt,
+                replaced,
+                unregister: () => {
+                    const cur = tools.get(spec.name)
+                    if (cur && cur.id === id) {
+                        tools.delete(spec.name)
+                        return true
+                    }
+                    return false
+                },
+            }
+        },
+
+        /** Discovery: the shape an agent sees. No execute fn, JSON-serialisable. */
+        getTools() {
+            return Array.from(tools.values()).map(({ spec, id, registeredAt }) => ({
+                id,
+                name: spec.name,
+                description: spec.description || "",
+                inputSchema: spec.inputSchema || { type: "object", properties: {} },
+                annotations: spec.annotations || {},
+                registeredAt,
+            }))
+        },
+
+        /** Agent-side call. Returns whatever the tool's execute() resolves to. */
+        async executeTool(name, args = {}) {
+            const entry = tools.get(name)
+            if (!entry) {
+                const err = new Error(`executeTool: no tool named "${name}"`)
+                err.code = "TOOL_NOT_FOUND"
+                throw err
+            }
+            return entry.spec.execute(args)
+        },
+
+        _debug: { tools },
+    }
+
+    return api
+}
+
+let _installed = null // { api, isNative }
+
+/**
+ * Ensure a modelContext implementation is available, installing the shim
+ * onto `document.modelContext` if there is no native one (or the shim is
+ * forced). Idempotent — safe to call more than once. Call this once, before
+ * WebMcpProvider mounts, in any app that wants WebMCP to work on a browser
+ * without native support.
+ *
+ * @returns {{ api: object|null, isNative: boolean }}
+ */
+export function installShim() {
+    if (_installed) return _installed
+
+    if (typeof document === "undefined") {
+        // SSR — no-op stand-in so imports don't explode. Never registers.
+        return { api: null, isNative: false }
+    }
+
+    const native = nativeModelContext()
+    if (native && !shimForced()) {
+        _installed = { api: native, isNative: true }
+        return _installed
+    }
+
+    // Reuse an already-installed shim if present (e.g. from a prior call).
+    if (document.modelContext && document.modelContext.__isWebMcpShim) {
+        _installed = { api: document.modelContext, isNative: false }
+        return _installed
+    }
+
+    const api = createShim()
+    document.modelContext = api
+    _installed = { api, isNative: false }
+    return _installed
+}

package/dist/webmcp/useTool.js

@@ -0,0 +1,124 @@
+// 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"
+
+/**
+ * useTool — register an imperative WebMCP action tool for the lifetime of the
+ * calling component, or for the lifetime of a `deps` window within it.
+ *
+ * What the hook adds on top of a raw `document.modelContext.registerTool`:
+ *
+ *   - Lifetime: registers after mount, unregisters (and aborts any in-flight
+ *     execute) on unmount.
+ *   - Route scoping: the tool is tagged with the route path it was mounted
+ *     under, so WebMcpProvider can reap it the moment the agent navigates away
+ *     — even if this component's own unmount hasn't flushed yet.
+ *   - Deferred until the client: never registers during SSR (no document) or
+ *     before hydration. React effects already run post-hydration, so simply
+ *     living in `useEffect` is the deferral — no `hydrationReady` needed.
+ *   - Stable identity: the tool spec is read through a ref, so re-renders with
+ *     a new inline `execute` closure don't churn the registration.
+ *   - `deps` (optional, useEffect-style array): when a value in `deps`
+ *     changes, the tool's description/inputSchema/annotations/execute are
+ *     swapped IN PLACE on the still-live registration via updateToolSpec() —
+ *     never torn down and re-registered. A real unmount (or the route no
+ *     longer matching) is still the only thing that unregisters. This matters
+ *     because a naive effect-array re-registration would reopen the
+ *     WEBMCP_ABORTED bug fixed earlier: an agent call in flight against the
+ *     old AbortController would be orphaned the instant a dep (e.g. cart
+ *     quantity) changed mid-call. Swapping in place keeps the same
+ *     AbortController and receipt across a deps change, so an in-flight call
+ *     always completes against a live entry.
+ *
+ * @param {{
+ *   name: string,
+ *   description: string,
+ *   inputSchema: object,
+ *   annotations?: object,
+ *   execute: (args: any, ctx: { signal: AbortSignal }) => Promise<any>,
+ * }} spec
+ * @param {any[]} [deps] omit to behave exactly as before (register once on
+ *   mount, keyed only by tool name); pass an array to also refresh the spec
+ *   in place whenever an entry changes.
+ *
+ * @returns {{
+ *   status: "idle" | "registered" | "error",
+ *   receipt: object | null,   // registration receipt — NOT an execution result
+ *   error: import("./errors.js").WebMcpError | null,
+ * }}
+ */
+export function useTool(spec, deps) {
+    const specRef = useRef(spec)
+    specRef.current = spec
+
+    const ownerKeyRef = useRef(null)
+    if (ownerKeyRef.current === null) ownerKeyRef.current = newOwnerKey()
+
+    // The nearest matched route path, provided by WebMcpProvider.
+    const routePath = useContext(RouteContext)
+    const routePathRef = useRef(routePath)
+    routePathRef.current = routePath
+
+    const [state, setState] = useState({ status: "idle", receipt: null, error: null })
+
+    // Register ONCE per mounted component (keyed only by tool name). The tool's
+    // route scope can change while mounted — e.g. a transient re-match during a
+    // navigation — without tearing the registration down and back up, which
+    // would orphan the AbortController the agent is mid-call against. Route
+    // changes are pushed to the registry in place via updateToolRoute().
+    useEffect(() => {
+        if (typeof document === "undefined") return undefined
+
+        const ownerKey = ownerKeyRef.current
+        const s = specRef.current
+        const liveSpec = {
+            name: s.name,
+            description: s.description,
+            inputSchema: s.inputSchema,
+            annotations: s.annotations,
+            // Always dispatch to the latest execute + latest route.
+            execute: (args, ctx) => specRef.current.execute(args, ctx),
+        }
+
+        const res = registerTool(ownerKey, routePathRef.current || "", liveSpec)
+        if (res.ok) {
+            setState({ status: "registered", receipt: res.receipt, error: null })
+        } 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)
+        }
+
+        return () => {
+            unregisterTool(ownerKey)
+        }
+    }, [spec.name])
+
+    // Keep the registry's notion of this tool's route current, in place.
+    useEffect(() => {
+        if (typeof document === "undefined") return
+        updateToolRoute(ownerKeyRef.current, routePath || "")
+    }, [routePath])
+
+    // Optional deps array: refresh description/inputSchema/annotations/execute
+    // on the existing registration in place whenever a dep changes. Skipped
+    // entirely when the caller doesn't pass `deps` — that's the "register
+    // once, execute always reads specRef.current" behaviour from above, which
+    // already reflects the latest closure on every call.
+    useEffect(() => {
+        if (deps === undefined) return
+        if (typeof document === "undefined") return
+        const s = specRef.current
+        updateToolSpec(ownerKeyRef.current, {
+            description: s.description,
+            inputSchema: s.inputSchema,
+            annotations: s.annotations,
+        })
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, deps || [])
+
+    return state
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "catalyst-core",
-    "version": "1.0.1",
+    "version": "1.0.2-canary.2",
     "type": "module",
     "main": "./dist/index.jsx",
     "description": "Web framework that provides great performance out of the box",
@@ -35,6 +35,8 @@
             "default": "./dist/native/bridge/hooks.js"
         },
         "./errors": "./dist/errors/index.js",
+        "./webmcp": "./dist/webmcp/index.js",
+        "./webmcp/shim": "./dist/webmcp/shim-entry.js",
         "./sentry": "./dist/sentry.cjs",
         "./otel": "./dist/otel.js"
     },
@@ -54,7 +56,7 @@
     "scripts": {
         "lint": "eslint .",
         "lint-staged": "lint-staged",
-        "test:unit": "node --test \"test/**/*.test.js\"",
+        "test:unit": "node --test \"test/**/*.test.js\" \"test/**/*.test.cjs\"",
         "typecheck": "tsc --noEmit",
         "prettify": "prettier . --write",
         "prepare": "node scripts/safe-rimraf.cjs ./dist && node scripts/build-dist.mjs && cp -r ./src/native ./dist/native && babel src/native --out-dir dist/native --config-file ./babel.native.config.cjs --extensions '.js,.jsx,.ts,.tsx' --ignore '**/.build/**' && node scripts/strip-ts-sources.mjs ./dist/native && babel src/sentry.js --out-file dist/sentry.cjs --config-file ./babel.native.config.cjs && tsc -p tsconfig.declarations.json && node ./mcp_v2/scripts/copyErrorsIndex.cjs",
@@ -78,7 +80,6 @@
         "express-static-gzip": "^2.1.7",
         "react": "19.0.0",
         "react-dom": "19.0.0",
-        "react-helmet-async": "^1.3.0",
         "react-redux": "^9.2.0",
         "react-refresh": "^0.14.0",
         "redux": "^4.2.1",
@@ -137,10 +138,6 @@
         ]
     },
     "overrides": {
-        "react-helmet-async": {
-            "react": "19.0.0",
-            "react-dom": "19.0.0"
-        },
         "react-redux": {
             "react": "19.0.0",
             "react-dom": "19.0.0"