simple-webmcp 0.1.0 → 0.3.0

package/.agents/skills/webmcp-simple/SKILL.md

@@ -42,18 +42,27 @@ searchTool.unregister();
 await searchTool({ query: 'alice' });
 ```
 
-### 2. React — component lifecycle
+### 2. React — component lifecycle (1-line optional)
 
 ```tsx
 'use client';
-import { webmcp } from 'simple-webmcp';
 import { useWebMCP, Scope } from 'simple-webmcp/react';
+import { useTool } from 'simple-webmcp/react'; // alias
 
-const addToCartTool = webmcp(addToCart, { description: 'Add product to cart' });
-
+// 1-line: wrap + register while mounted — recommended
 export function ProductPage() {
-  // exposed only while component mounted — maps to AbortSignal
-  useWebMCP(addToCartTool);
+  const addToCartTool = useWebMCP(addToCart, { description: 'Add product to cart' });
+  // or: const tool = useTool(addToCart, { description: '...' });
+  // addToCartTool({productId:'p1', quantity:1}) still callable
+  // addToCartTool.registered, addToCartTool.status also available
+  return <div>...</div>;
+}
+
+// verbose 2-line still works:
+import { webmcp } from 'simple-webmcp';
+const addToCartTool2 = webmcp(addToCart, { description: 'Add product to cart' });
+export function ProductPage2() {
+  useWebMCP(addToCartTool2);
   return <div>...</div>;
 }
 
@@ -86,10 +95,16 @@ In all cases `schema` (whole) establishes contract; `fields` patches it (adds de
 
 ### 4. Polyfill (non-Chrome)
 
+For **production cross-browser** (Firefox/Safari), use the dedicated polyfill:
+
+```ts
+import '@mcp-b/webmcp-polyfill'; // ~6k weekly, real transport
+```
+
+For **dev/testing** (Storybook, vitest, local without Chrome), `simple-webmcp` provides a thin in-memory shim (not full MCP):
+
 ```ts
-// before importing tools — no-op in Chrome with native WebMCP
-import 'simple-webmcp/polyfill';
-// or programmatic: import { installPolyfill } from 'simple-webmcp/polyfill'; installPolyfill();
+import 'simple-webmcp/dev-polyfill'; // or 'simple-webmcp/testing' or legacy 'simple-webmcp/polyfill'
 ```
 
 ### 5. Global vs Scoped
@@ -105,11 +120,11 @@ webmcp.global(fn, { description: '…' }); // alias
 
 ## Progression Ladder (teach stepwise)
 
-1. **Beginner:** `webmcp(fn)` done.
-2. **Better desc:** `webmcp(fn, { description: '…' })`
+1. **Beginner:** `webmcp(fn)` done (vanilla) or `useWebMCP(fn,{description})` / `useTool(fn)` in React — 1 line.
+2. **Better desc:** `webmcp(fn, { description: '…' })` or `useTool(fn,{description})`
 3. **Field docs:** `webmcp(fn, { fields: { query: { description: '…' } } })`
 4. **Full control:** `webmcp(fn, { schema: z.object({…}) })`
-5. **Lifecycle:** `useWebMCP(tool)` / `<Scope tools>`
+5. **Lifecycle:** `useWebMCP(tool)` / `useTool(fn, opts)` / `<Scope tools>`
 
 ## Rules
 

package/README.md

@@ -1,6 +1,6 @@
-# simple-webmcp
+# Make your existing functions agent-ready
 
-> Turn any JS/TS function into a WebMCP tool — `webmcp(fn)` stays callable, auto-registers with React lifecycle or globally. Minimal, typed, framework-agnostic.
+`simple-webmcp` turns ordinary JavaScript and TypeScript functions into WebMCP tools without creating a second tool layer.
 
 ```ts
 import { webmcp } from 'simple-webmcp';
@@ -9,128 +9,268 @@ async function searchCustomers({ query, limit = 20 }: { query: string; limit?: n
   return customers.filter(c => c.name.includes(query)).slice(0, limit);
 }
 
-// One line — same function, now also a tool
-export const searchTool = webmcp(searchCustomers, {
-  description: 'Search customers in current account',
-  fields: { query: { description: 'Name, email, or ID' } },
+const search = webmcp(searchCustomers);
+```
+
+That's it. Your function stays callable:
+
+```ts
+await search({ query: 'alice' });
+```
+
+And can be exposed to WebMCP:
+
+```ts
+import { useWebMCP } from 'simple-webmcp/react';
+
+function CustomersPage() {
+  const tool = useWebMCP(search, { description: 'Search customers' });
+  // visible while mounted — unregisters on unmount (AbortSignal)
+  return <CustomersUI />;
+}
+```
+
+**Framework-agnostic core. React adapter included.** Works with vanilla JS, TypeScript, Vite — Next.js support remains experimental until proven.
+
+> **One function. Two interfaces.** Human code `search(input)` and agent `search(input)` — same capability.
+>
+> **Write the function once. Expose it to humans and agents.**
+
+**Docs:** https://emingure.github.io/simple-webmcp/ · **Live Demo:** [Try the shopping cart demo →](https://emingure.github.io/simple-webmcp/demo/) *(see `examples/demo`)* · **npm:** `simple-webmcp`
+
+---
+
+## Why simple-webmcp?
+
+Most WebMCP integrations force a second layer:
+
+```text
+Existing app logic
+  ↓
+Define tool metadata (name, description, inputSchema)
+  ↓
+Define execute wrapper
+  ↓
+Call registerTool()
+  ↓
+Manage lifecycle (AbortSignal, StrictMode, SSR)
+```
+
+`simple-webmcp` collapses it:
+
+```text
+Existing function
+  ↓
+webmcp(existingFunction)
+  ↓
+Done — keep your API, types, and business logic
+```
+
+Use **raw `document.modelContext.registerTool()`** when you want total control over `getTools()` / `executeTool()` / `toolchange` / `exposedTo` — the browser imperative API ([Chrome Docs](https://developer.chrome.com/docs/ai/webmcp/imperative-api)). Use **`simple-webmcp`** when you already have `addToCart`, `searchCustomers`, `updateCustomer` and want them agent-callable without duplicating schema and lifecycle.
+
+**Focused on tool authoring and lifecycle** — not a full WebMCP SDK. The browser provides `getTools`, `executeTool`, `exposedTo` etc.; we provide the tiny application layer on top and stay stable while WebMCP evolves underneath.
+
+## Before / After
+
+**Without — raw WebMCP:**
+
+```ts
+document.modelContext.registerTool({
+  name: 'add_to_cart',
+  description: 'Add a product to the shopping cart',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      productId: { type: 'string', description: 'Product ID' },
+      quantity: { type: 'number', minimum: 1 }
+    },
+    required: ['productId', 'quantity']
+  },
+  execute: ({ productId, quantity }) => addToCart(productId, quantity)
+}, { signal });
+```
+
+**With — function-first:**
+
+```ts
+import { webmcp } from 'simple-webmcp';
+
+const addToCartTool = webmcp(addToCart, {
+  description: 'Add a product to the shopping cart'
 });
 
-await searchTool({ query: 'alice' }); // still just a function
-await searchTool.register(); // => document.modelContext.registerTool(...)
-// or React: useWebMCP(searchTool) → mounted = exposed
+// same function, same app — one line
+await addToCartTool({ productId: 'p_123', quantity: 2 }); // human
+// agent calls same tool via WebMCP when <CartPage> is mounted
 ```
 
-Works with plain JS, TS, React, Vite… (Next.js Server Actions experimental 0.3). Open source, lean (`sideEffects:false`, core no React dep).
+**Same function. Same application. One line.** No duplicated business logic.
 
-**Docs:** https://emingure.github.io/simple-webmcp/ (via GitHub Pages)
+For e-commerce, SaaS dashboards, booking, CRM, forms, internal tools — where `addToCart`, `searchCustomers`, `createInvoice` already exist and suddenly need to be agent-callable.
 
 ## Install
 
 ```bash
 npm i simple-webmcp
-# React is optional peer (≥18) only if you import simple-webmcp/react
-# Repo: https://github.com/emingure/simple-webmcp
+# React is optional peer only if you use simple-webmcp/react
 ```
 
 ## Quick Start
 
-| Need | Code |
-|------|------|
-| Vanilla — global | `webmcp(fn,{description, global:true})` or `await tool.register()` |
-| Vanilla — manual | `tool.register()` / `tool.unregister()` |
-| React — page | `useWebMCP(tool)` while component mounted |
-| React — layout / route | `<Scope tools={[a,b]}>{children}</Scope>` |
-| Rate-limited / disabled | `webmcp(fn,{enabled:false})` |
-| Polyfill (Firefox/Safari) | `import 'simple-webmcp/polyfill'` |
-
-## Schema
-
-Hierarchy **corrected per review**: `schema` (whole) → inferred (runtime 0.1 / build 0.2 TS/JSDoc) → `fields` patch → metadata override.
+### Vanilla — manual or global
 
 ```ts
-// prefer single object param fn({query, limit}) for best inference
-webmcp(fn, { description:'…', fields:{ query:{description:'…'}, limit:{type:'integer', maximum:50} } });
+import { webmcp } from 'simple-webmcp';
 
-// whole Zod / StandardSchema — requires `simple-webmcp/zod` side-effect (keeps core lean)
-import { z } from 'zod';
-import 'simple-webmcp/zod'; // enables Zod → JSON Schema in core
-webmcp(fn, { description:'…', schema: z.object({ query: z.string().min(1) }) });
+export const tool = webmcp(addToCart, {
+  description: 'Add product to shopping cart',
+  fields: { productId: { description: 'Product ID' }, quantity: { type: 'integer', minimum: 1 } }
+});
 
-// per-field mix — same import enables it
-webmcp(fn, { fields:{ query: z.string().describe('…'), limit:{type:'integer'} } });
+await tool({ productId: 'p_1', quantity: 2 }); // human
+await tool.register(); // expose — uses document.modelContext (Chrome canary)
+tool.unregister();
 
-// JSON Schema directly
-webmcp(fn, { schema:{type:'object', properties:{query:{type:'string'}}, required:['query']} });
+// global (registers on import, client only) — prefer scoped for least privilege
+webmcp.global(addToCart, { description: '...' });
 ```
 
-`fields` is a **patch** (`Partial<JsonSchema>` or per-field `StandardSchema`) — annotates, does not silently replace core type. Provide `strict:true` to make ambiguous runtime inference throw instead of warn.
-
-## React
+### React — 1-line (recommended)
 
 ```tsx
 'use client';
-import { webmcp } from 'simple-webmcp';
-import { useWebMCP, Scope } from 'simple-webmcp/react';
-
-const tool = webmcp(fn, { description:'…' });
+import { useWebMCP } from 'simple-webmcp/react'; // alias: useTool
 
-export function Page() {
-  const { supported, registered, error } = useWebMCP(tool);
-  return null; // exposed while mounted — maps to AbortSignal
+export function ProductPage() {
+  const tool = useWebMCP(addToCart, { description: 'Add product to cart' });
+  // tool is callable + has tool.registered / tool.status
+  return <Product />;
 }
+```
+
+Verbose 2-line still works: `const t = webmcp(fn); useWebMCP(t)`. Layout-level: `<Scope tools={[search, update]}>{children}</Scope>` — naturally gives route-level scope in Next.js `app/layout.tsx`.
 
-// layout-level route scope (Next.js app/layout.tsx naturally gives route scope)
-<Scope tools={[toolA, toolB]}>{children}</Scope>
+`register()` is `async` (`Promise<() => void>`) per current `webmcp-types`; hook maps to `AbortSignal` and dedupes StrictMode. `status` is `'unregistered'|'registering'|'registered'|'unsupported'|'error'` — `supported` and `registered` are mutually exclusive (unsupported never claims registered).
+
+### Hooks — before / after / error / denied (HITL)
+
+```ts
+const tool = webmcp(checkout, {
+  description: 'Checkout cart',
+  hooks: {
+    before: [async ({input}) => {
+      const ok = await confirm(`Checkout £${total}?`);
+      if (!ok) return { action: 'deny', message: 'User declined' };
+    }],
+    after:  [({output}) => ({ output: redact(output) })],
+    error:  [({error}) => console.warn(error)],
+    denied: [({reason}) => analytics.track('denied', {reason})],
+  }
+});
+webmcp.configure({ hooks:{ before:[trackInvocation], after:[trackResult] }});
+<WebMCPProvider hooks={{ before:[addTenant] }}><Scope tools={[tool]}>{children}</Scope></WebMCPProvider>
 ```
 
-## Polyfill
+Hooks wrap only the agent `execute` path — `tool({input})` stays pure. Ordering: `before` `global→scoped→tool`, `after` `tool→scoped→global`. Direct + `console` + UI logs in the [demo](/demo) **Hooks & HITL** card. See [Guide — Hooks](https://emingure.github.io/simple-webmcp/guide/hooks) and [Analytics](https://emingure.github.io/simple-webmcp/guide/analytics) (PostHog, Mixpanel, GA4, Sentry, etc.).
 
-`simple-webmcp/polyfill` is an adapter entry (not hard-coded to one impl). It installs a thin in-memory shim if `document.modelContext` missing, shielding spec churn. For full MCP transport, install `@mcp-b/global` before.
+## Customize only what you need
 
 ```ts
-import 'simple-webmcp/polyfill';
-import { installPolyfill } from 'simple-webmcp/polyfill'; // programmatic
+const search = webmcp(searchCustomers, {
+  description: 'Search customers by name or email',
+  fields: {
+    query: { description: 'Customer name, email, or ID' },
+    limit: { type: 'integer', minimum: 1, maximum: 50 }
+  }
+});
 ```
 
-## API
+**Enhance inferred schemas without rewriting them.** `fields` is a patch over the base schema (`Partial<JsonSchema>` or per-field `StandardSchema`). Whole `schema` establishes the contract; `fields` decorates it.
 
-See `.agents/skills/webmcp-simple/references/api.md` and examples `examples/`.
+```ts
+// Zod — requires side-effect (keeps core 6.26KB gz lean)
+import { z } from 'zod';
+import 'simple-webmcp/zod';
+webmcp(fn, { schema: z.object({ query: z.string().min(1) }) });
+webmcp(fn, { fields: { query: z.string().describe('Name') } });
+```
+
+## How inference works
+
+**Infer what JavaScript can know at runtime. Get richer TypeScript/JSDoc inference with the optional build plugin.**
+
+*Runtime* — best-effort, `confidence:'low'`: parameter names, defaults, destructured keys (`{query, limit=20}` → `query` required, `limit` optional `default:20`), some primitives from literal defaults. `function search(query: string)` alone becomes `{properties:{query:{}}}` — we warn and need `fields`/`schema` or `strict:true` throws.
+
+*Build* — optional `simple-webmcp/unplugin` (Vite/Webpack) reads TypeScript types + JSDoc before erasure. Same `webmcp(fn)` call, richer `inputSchema`, no code change.
+
+Progressive:
+
+```
+webmcp(fn)
+  ↓ add description
+  ↓ add field metadata (fields)
+  ↓ provide a schema (Zod)
+  ↓ opt into build-time TS/JSDoc inference
+```
+
+Start with one function.
+
+## Comparison
+
+|  | simple-webmcp | raw WebMCP (`document.modelContext`) | `usewebmcp` | `@mcp-b/react-webmcp` |
+|---|---|---|---|---|
+| Existing function stays callable | ✅ | ❌ | ❌ | ❌ |
+| `webmcp(fn)` — function-first | ✅ | — | — | — |
+| Metadata patching | ✅ | Manual `registerTool` | Manual | Manual |
+| `fields` patch | ✅ | ❌ | ❌ | ❌ |
+| React lifecycle (`AbortSignal`, StrictMode) | ✅ | Manual | ✅ | ✅ |
+| Full MCP ecosystem / `getTools` etc | — (authoring) | ✅ Browser API | — | ✅ |
+| Weekly downloads | new | n/a (browser) | — | ~6k |
+| Focus | Function-first DX | Native API | React hooks | MCP ecosystem |
+
+> **simple-webmcp + MCP-B are complementary.** `simple-webmcp` authors capabilities; MCP-B / native WebMCP is the runtime. For real cross-browser WebMCP (Firefox/Safari), use the dedicated `@mcp-b/webmcp-polyfill` (~6k weekly):
+> ```bash
+> npm i @mcp-b/webmcp-polyfill && import '@mcp-b/webmcp-polyfill'
+> ```
+> `simple-webmcp/polyfill` is a **dev/testing shim** (in-memory `registerTool`/`listTools`/`invokeTool`, not full transport) — prefer `simple-webmcp/dev-polyfill` or `simple-webmcp/testing` in tests/Storybook. Native `document.modelContext` (not `navigator.modelContext`) is detected first.
+
+## Live Demo
+
+**Shopping Cart:** MacBook £1,299 / Keyboard £99 / [Checkout] — agent says *“Add a keyboard to my cart”* → `add_to_cart` via WebMCP, UI updates. Chrome's docs point to demos + inspector extension for this flow.
+
+**Admin Dashboard (e-commerce/CRM):** `search_customers`, `get_customer`, `update_customer`, `create_invoice` — ordinary functions `const tools = [webmcp(search), webmcp(get), webmcp(update)]` exposed from the active component only. See `examples/demo/` and https://emingure.github.io/simple-webmcp/demo/.
+
+## API
 
-### Core
+See `.agents/skills/webmcp-simple/references/api.md`.
 
-- `webmcp(fn, opts)` → `WebMCPTool<F>` (callable + `tool/definition/register/unregister/status`)
-- `webmcp.global(fn, opts)` alias
-- `isWebMCPSupported()`, `toSnakeCase`, `registry.list()/clear()`
-- Errors: `NotSupportedError`, `NotAllowedError` (Permissions Policy), `RegistrationError`, `ValidationError`, `ConfigurationError`
+**Core:** `webmcp(fn, opts)` → `WebMCPTool` (callable + `tool`/`definition`/`register`/`status`), `webmcp.global`, `webmcp.configure({hooks})`, `isWebMCPSupported()`, `registry.list()`. Errors: `NotSupportedError` (`unsupported` status, mutually exclusive with `registered`), `NotAllowedError`, `RegistrationError`, `ConfigurationError`.
 
-### React
+**Hooks:** `hooks:{ before:[], after:[], error:[], denied:[] }` on `webmcp(fn,{hooks})`, `webmcp.configure`, and `<WebMCPProvider hooks>`. See [Guide — Hooks](https://emingure.github.io/simple-webmcp/guide/hooks) and [Analytics](https://emingure.github.io/simple-webmcp/guide/analytics) for PostHog/Mixpanel/GA4/Sentry examples. Demo shows live hook log + HITL approval modal.
 
-- `useWebMCP(tool, {enabled})`
-- `<Scope tools>`
+**React:** `useWebMCP(fn, opts)` / `useWebMCP(tool)` → `WebMCPTool & status` / `status`, `useTool` alias, `<Scope tools>`, `<WebMCPProvider hooks>`.
 
-### Errors & Lifecycle
+**Zod:** `import 'simple-webmcp/zod'` then `schema`/`fields` accept Zod/StandardSchema.
 
-`register()` is async `Promise<()=>void>` per current WebMCP types. `status: 'unregistered'|'registering'|'registered'|'unregistering'|'error'`. Use `tool.status` / `tool.isRegistered()`; hook exposes `supported/registered/error`.
+WebMCP today is `document.modelContext` (Chrome canary, origin trial). This package tracks the spec — your app stays on the tiny `webmcp(fn)` API while we absorb browser changes.
 
 ## Development
 
 ```bash
-npm run build      # tsup ESM+CJS+DTS
-npm test           # vitest jsdom
+npm run build      # tsup ESM+CJS+DTS (core 6.26KB gz, zod 1.40KB separate)
+npm test           # vitest jsdom — 47 tests
 npm run typecheck
+npm run docs:dev   # VitePress
 ```
 
 ## Versioning
 
-- **0.1** — `webmcp()` + `useWebMCP` + `Scope` + runtime fallback + polyfill adapter + tests (this release)
-- **0.2** — `simple-webmcp/unplugin` TS/JSDoc build inference (Vite/Webpack)
-- **0.3** — `simple-webmcp/next` `webmcp.server()` — experimental, gated behind working `fixtures/next-app` spike (verifies Server Action reference survival)
-- **0.4** — `webmcp.bind()`, DevTools, CLI
+Follows [Semantic Versioning](https://semver.org/). See [`CHANGELOG.md`](./CHANGELOG.md) for the current `0.2.0` notes and [`RELEASING.md`](./RELEASING.md) for the release process. No future roadmap is promised here — track GitHub issues/discussions for what's next.
 
 ## Skills (Agent)
 
-This package ships `.agents/skills/webmcp-simple/SKILL.md` for auto-discovery by OpenCode/Claude. No install needed — agents discover via `.agents/skills/`.
+This package ships `.agents/skills/webmcp-simple/SKILL.md` for auto-discovery by OpenCode/Claude — the agent becomes distribution: *“Make this function WebMCP callable”* → `webmcp(fn)` instead of raw `registerTool`.
 
 ## License
 
-MIT
+MIT — Copyright © 2026 Muhammed Emin Gure (https://github.com/emingure)

package/dist/dev-polyfill.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// src/polyfill.ts
+var installed = false;
+function installPolyfill(opts) {
+  if (installed && !opts?.force) return true;
+  if (typeof document === "undefined") return false;
+  const docAny = document;
+  if (docAny.modelContext && !opts?.force) {
+    installed = true;
+    return true;
+  }
+  const tools = /* @__PURE__ */ new Map();
+  const polyfill = {
+    _isPolyfill: true,
+    _tools: tools,
+    async registerTool(def, opts2) {
+      const name = def?.name;
+      if (!name) throw new Error("registerTool: name required");
+      if (tools.has(name)) {
+        return;
+      }
+      tools.set(name, { def, signal: opts2?.signal });
+      if (opts2?.signal) {
+        const onAbort = () => {
+          if (tools.get(name)?.signal === opts2.signal) tools.delete(name);
+        };
+        if (opts2.signal.aborted) {
+          tools.delete(name);
+        } else {
+          opts2.signal.addEventListener("abort", onAbort, { once: true });
+        }
+      }
+    },
+    listTools() {
+      return Array.from(tools.values()).map((v) => v.def);
+    },
+    async invokeTool(name, args) {
+      const entry = tools.get(name);
+      if (!entry) throw new Error(`Tool ${name} not found`);
+      return entry.def.execute(args);
+    }
+  };
+  docAny.modelContext = polyfill;
+  installed = true;
+  return true;
+}
+function isPolyfilled() {
+  if (typeof document === "undefined") return false;
+  return !!document.modelContext?._isPolyfill;
+}
+if (typeof document !== "undefined") {
+  queueMicrotask(() => {
+    const docAny = document;
+    if (!docAny.modelContext) {
+      installPolyfill();
+    }
+  });
+}
+var polyfill_default = installPolyfill;
+
+exports.default = polyfill_default;
+exports.installPolyfill = installPolyfill;
+exports.isPolyfilled = isPolyfilled;
+//# sourceMappingURL=dev-polyfill.cjs.map
+//# sourceMappingURL=dev-polyfill.cjs.map

package/dist/dev-polyfill.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/polyfill.ts"],"names":["opts"],"mappings":";;;;;AAwBA,IAAI,SAAA,GAAY,KAAA;AAET,SAAS,gBAAgB,IAAA,EAAiC;AAC/D,EAAA,IAAI,SAAA,IAAa,CAAC,IAAA,EAAM,KAAA,EAAO,OAAO,IAAA;AACtC,EAAA,IAAI,OAAO,QAAA,KAAa,WAAA,EAAa,OAAO,KAAA;AAC5C,EAAA,MAAM,MAAA,GAAS,QAAA;AACf,EAAA,IAAI,MAAA,CAAO,YAAA,IAAgB,CAAC,IAAA,EAAM,KAAA,EAAO;AACvC,IAAA,SAAA,GAAY,IAAA;AACZ,IAAA,OAAO,IAAA;AAAA,EACT;AAIA,EAAA,MAAM,KAAA,uBAAY,GAAA,EAMhB;AAEF,EAAA,MAAM,QAAA,GAAW;AAAA,IACf,WAAA,EAAa,IAAA;AAAA,IACb,MAAA,EAAQ,KAAA;AAAA,IACR,MAAM,YAAA,CAAa,GAAA,EAAUA,KAAAA,EAAiC;AAC5D,MAAA,MAAM,OAAO,GAAA,EAAK,IAAA;AAClB,MAAA,IAAI,CAAC,IAAA,EAAM,MAAM,IAAI,MAAM,6BAA6B,CAAA;AACxD,MAAA,IAAI,KAAA,CAAM,GAAA,CAAI,IAAI,CAAA,EAAG;AAEnB,QAAA;AAAA,MACF;AACA,MAAA,KAAA,CAAM,IAAI,IAAA,EAAM,EAAE,KAAK,MAAA,EAAQA,KAAAA,EAAM,QAAQ,CAAA;AAC7C,MAAA,IAAIA,OAAM,MAAA,EAAQ;AAChB,QAAA,MAAM,UAAU,MAAM;AACpB,UAAA,IAAI,KAAA,CAAM,IAAI,IAAI,CAAA,EAAG,WAAWA,KAAAA,CAAK,MAAA,EAAQ,KAAA,CAAM,MAAA,CAAO,IAAI,CAAA;AAAA,QAChE,CAAA;AACA,QAAA,IAAIA,KAAAA,CAAK,OAAO,OAAA,EAAS;AACvB,UAAA,KAAA,CAAM,OAAO,IAAI,CAAA;AAAA,QACnB,CAAA,MAAO;AACL,UAAAA,KAAAA,CAAK,OAAO,gBAAA,CAAiB,OAAA,EAAS,SAAS,EAAE,IAAA,EAAM,MAAM,CAAA;AAAA,QAC/D;AAAA,MACF;AAAA,IACF,CAAA;AAAA,IACA,SAAA,GAAY;AACV,MAAA,OAAO,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,MAAA,EAAQ,EAAE,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,GAAG,CAAA;AAAA,IACpD,CAAA;AAAA,IACA,MAAM,UAAA,CAAW,IAAA,EAAc,IAAA,EAAe;AAC5C,MAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,GAAA,CAAI,IAAI,CAAA;AAC5B,MAAA,IAAI,CAAC,KAAA,EAAO,MAAM,IAAI,KAAA,CAAM,CAAA,KAAA,EAAQ,IAAI,CAAA,UAAA,CAAY,CAAA;AACpD,MAAA,OAAO,KAAA,CAAM,GAAA,CAAI,OAAA,CAAQ,IAAI,CAAA;AAAA,IAC/B;AAAA,GACF;AAEA,EAAA,MAAA,CAAO,YAAA,GAAe,QAAA;AACtB,EAAA,SAAA,GAAY,IAAA;AACZ,EAAA,OAAO,IAAA;AACT;AAEO,SAAS,YAAA,GAAwB;AACtC,EAAA,IAAI,OAAO,QAAA,KAAa,WAAA,EAAa,OAAO,KAAA;AAC5C,EAAA,OAAO,CAAC,CAAE,QAAA,CAAiB,YAAA,EAAc,WAAA;AAC3C;AAGA,IAAI,OAAO,aAAa,WAAA,EAAa;AAEnC,EAAA,cAAA,CAAe,MAAM;AACnB,IAAA,MAAM,MAAA,GAAS,QAAA;AACf,IAAA,IAAI,CAAC,OAAO,YAAA,EAAc;AACxB,MAAA,eAAA,EAAgB;AAAA,IAClB;AAAA,EACF,CAAC,CAAA;AACH;AAEA,IAAO,gBAAA,GAAQ","file":"dev-polyfill.cjs","sourcesContent":["/**\n * simple-webmcp/polyfill — dev/testing shim (NOT a WebMCP interoperability polyfill).\n *\n * This is an in-memory registry for tests, Storybook, and local dev without Chrome.\n * It implements `registerTool`/`listTools`/`invokeTool` but not full MCP transport.\n *\n * For real cross-browser WebMCP (Firefox/Safari), use the dedicated\n * `@mcp-b/webmcp-polyfill` (https://www.npmjs.com/package/@mcp-b/webmcp-polyfill)\n * — ~6k weekly downloads, broader MCP ecosystem. Example:\n *   `npm i @mcp-b/webmcp-polyfill && import '@mcp-b/webmcp-polyfill'`\n *\n * In production Chrome with native `document.modelContext`, this is a no-op\n * (detected via native presence). Prefer the real polyfill for production\n * cross-browser, and this shim for testing.\n *\n * New aliases (preferred for clarity): `simple-webmcp/dev-polyfill` and\n * `simple-webmcp/testing` — same module, clearer intent. `simple-webmcp/polyfill`\n * is kept for backward compat but will be documented as dev shim.\n */\n\nexport type PolyfillOptions = {\n  force?: boolean;\n};\n\nlet installed = false;\n\nexport function installPolyfill(opts?: PolyfillOptions): boolean {\n  if (installed && !opts?.force) return true;\n  if (typeof document === 'undefined') return false;\n  const docAny = document as any;\n  if (docAny.modelContext && !opts?.force) {\n    installed = true;\n    return true;\n  }\n\n  // Minimal polyfill — tracks tools in memory, invokes via same ABI.\n  // Not a full MCP transport; sufficient for registry + tests + devtools.\n  const tools = new Map<\n    string,\n    {\n      def: any;\n      signal?: AbortSignal;\n    }\n  >();\n\n  const polyfill = {\n    _isPolyfill: true,\n    _tools: tools,\n    async registerTool(def: any, opts?: { signal?: AbortSignal }) {\n      const name = def?.name;\n      if (!name) throw new Error('registerTool: name required');\n      if (tools.has(name)) {\n        // Dedup like native — ignore second registration\n        return;\n      }\n      tools.set(name, { def, signal: opts?.signal });\n      if (opts?.signal) {\n        const onAbort = () => {\n          if (tools.get(name)?.signal === opts.signal) tools.delete(name);\n        };\n        if (opts.signal.aborted) {\n          tools.delete(name);\n        } else {\n          opts.signal.addEventListener('abort', onAbort, { once: true });\n        }\n      }\n    },\n    listTools() {\n      return Array.from(tools.values()).map((v) => v.def);\n    },\n    async invokeTool(name: string, args: unknown) {\n      const entry = tools.get(name);\n      if (!entry) throw new Error(`Tool ${name} not found`);\n      return entry.def.execute(args);\n    },\n  };\n\n  docAny.modelContext = polyfill;\n  installed = true;\n  return true;\n}\n\nexport function isPolyfilled(): boolean {\n  if (typeof document === 'undefined') return false;\n  return !!(document as any).modelContext?._isPolyfill;\n}\n\n// Auto-install side-effect import: `import 'simple-webmcp/polyfill'`\nif (typeof document !== 'undefined') {\n  // Defer to next tick to allow native detection first\n  queueMicrotask(() => {\n    const docAny = document as any;\n    if (!docAny.modelContext) {\n      installPolyfill();\n    }\n  });\n}\n\nexport default installPolyfill;\n"]}

package/dist/dev-polyfill.d.cts

@@ -0,0 +1 @@
+export { PolyfillOptions, default, default as installPolyfill, isPolyfilled } from './polyfill.cjs';

package/dist/dev-polyfill.d.ts

@@ -0,0 +1 @@
+export { PolyfillOptions, default, default as installPolyfill, isPolyfilled } from './polyfill.js';

package/dist/dev-polyfill.js

@@ -0,0 +1,62 @@
+// src/polyfill.ts
+var installed = false;
+function installPolyfill(opts) {
+  if (installed && !opts?.force) return true;
+  if (typeof document === "undefined") return false;
+  const docAny = document;
+  if (docAny.modelContext && !opts?.force) {
+    installed = true;
+    return true;
+  }
+  const tools = /* @__PURE__ */ new Map();
+  const polyfill = {
+    _isPolyfill: true,
+    _tools: tools,
+    async registerTool(def, opts2) {
+      const name = def?.name;
+      if (!name) throw new Error("registerTool: name required");
+      if (tools.has(name)) {
+        return;
+      }
+      tools.set(name, { def, signal: opts2?.signal });
+      if (opts2?.signal) {
+        const onAbort = () => {
+          if (tools.get(name)?.signal === opts2.signal) tools.delete(name);
+        };
+        if (opts2.signal.aborted) {
+          tools.delete(name);
+        } else {
+          opts2.signal.addEventListener("abort", onAbort, { once: true });
+        }
+      }
+    },
+    listTools() {
+      return Array.from(tools.values()).map((v) => v.def);
+    },
+    async invokeTool(name, args) {
+      const entry = tools.get(name);
+      if (!entry) throw new Error(`Tool ${name} not found`);
+      return entry.def.execute(args);
+    }
+  };
+  docAny.modelContext = polyfill;
+  installed = true;
+  return true;
+}
+function isPolyfilled() {
+  if (typeof document === "undefined") return false;
+  return !!document.modelContext?._isPolyfill;
+}
+if (typeof document !== "undefined") {
+  queueMicrotask(() => {
+    const docAny = document;
+    if (!docAny.modelContext) {
+      installPolyfill();
+    }
+  });
+}
+var polyfill_default = installPolyfill;
+
+export { polyfill_default as default, installPolyfill, isPolyfilled };
+//# sourceMappingURL=dev-polyfill.js.map
+//# sourceMappingURL=dev-polyfill.js.map

package/dist/dev-polyfill.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/polyfill.ts"],"names":["opts"],"mappings":";AAwBA,IAAI,SAAA,GAAY,KAAA;AAET,SAAS,gBAAgB,IAAA,EAAiC;AAC/D,EAAA,IAAI,SAAA,IAAa,CAAC,IAAA,EAAM,KAAA,EAAO,OAAO,IAAA;AACtC,EAAA,IAAI,OAAO,QAAA,KAAa,WAAA,EAAa,OAAO,KAAA;AAC5C,EAAA,MAAM,MAAA,GAAS,QAAA;AACf,EAAA,IAAI,MAAA,CAAO,YAAA,IAAgB,CAAC,IAAA,EAAM,KAAA,EAAO;AACvC,IAAA,SAAA,GAAY,IAAA;AACZ,IAAA,OAAO,IAAA;AAAA,EACT;AAIA,EAAA,MAAM,KAAA,uBAAY,GAAA,EAMhB;AAEF,EAAA,MAAM,QAAA,GAAW;AAAA,IACf,WAAA,EAAa,IAAA;AAAA,IACb,MAAA,EAAQ,KAAA;AAAA,IACR,MAAM,YAAA,CAAa,GAAA,EAAUA,KAAAA,EAAiC;AAC5D,MAAA,MAAM,OAAO,GAAA,EAAK,IAAA;AAClB,MAAA,IAAI,CAAC,IAAA,EAAM,MAAM,IAAI,MAAM,6BAA6B,CAAA;AACxD,MAAA,IAAI,KAAA,CAAM,GAAA,CAAI,IAAI,CAAA,EAAG;AAEnB,QAAA;AAAA,MACF;AACA,MAAA,KAAA,CAAM,IAAI,IAAA,EAAM,EAAE,KAAK,MAAA,EAAQA,KAAAA,EAAM,QAAQ,CAAA;AAC7C,MAAA,IAAIA,OAAM,MAAA,EAAQ;AAChB,QAAA,MAAM,UAAU,MAAM;AACpB,UAAA,IAAI,KAAA,CAAM,IAAI,IAAI,CAAA,EAAG,WAAWA,KAAAA,CAAK,MAAA,EAAQ,KAAA,CAAM,MAAA,CAAO,IAAI,CAAA;AAAA,QAChE,CAAA;AACA,QAAA,IAAIA,KAAAA,CAAK,OAAO,OAAA,EAAS;AACvB,UAAA,KAAA,CAAM,OAAO,IAAI,CAAA;AAAA,QACnB,CAAA,MAAO;AACL,UAAAA,KAAAA,CAAK,OAAO,gBAAA,CAAiB,OAAA,EAAS,SAAS,EAAE,IAAA,EAAM,MAAM,CAAA;AAAA,QAC/D;AAAA,MACF;AAAA,IACF,CAAA;AAAA,IACA,SAAA,GAAY;AACV,MAAA,OAAO,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,MAAA,EAAQ,EAAE,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,GAAG,CAAA;AAAA,IACpD,CAAA;AAAA,IACA,MAAM,UAAA,CAAW,IAAA,EAAc,IAAA,EAAe;AAC5C,MAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,GAAA,CAAI,IAAI,CAAA;AAC5B,MAAA,IAAI,CAAC,KAAA,EAAO,MAAM,IAAI,KAAA,CAAM,CAAA,KAAA,EAAQ,IAAI,CAAA,UAAA,CAAY,CAAA;AACpD,MAAA,OAAO,KAAA,CAAM,GAAA,CAAI,OAAA,CAAQ,IAAI,CAAA;AAAA,IAC/B;AAAA,GACF;AAEA,EAAA,MAAA,CAAO,YAAA,GAAe,QAAA;AACtB,EAAA,SAAA,GAAY,IAAA;AACZ,EAAA,OAAO,IAAA;AACT;AAEO,SAAS,YAAA,GAAwB;AACtC,EAAA,IAAI,OAAO,QAAA,KAAa,WAAA,EAAa,OAAO,KAAA;AAC5C,EAAA,OAAO,CAAC,CAAE,QAAA,CAAiB,YAAA,EAAc,WAAA;AAC3C;AAGA,IAAI,OAAO,aAAa,WAAA,EAAa;AAEnC,EAAA,cAAA,CAAe,MAAM;AACnB,IAAA,MAAM,MAAA,GAAS,QAAA;AACf,IAAA,IAAI,CAAC,OAAO,YAAA,EAAc;AACxB,MAAA,eAAA,EAAgB;AAAA,IAClB;AAAA,EACF,CAAC,CAAA;AACH;AAEA,IAAO,gBAAA,GAAQ","file":"dev-polyfill.js","sourcesContent":["/**\n * simple-webmcp/polyfill — dev/testing shim (NOT a WebMCP interoperability polyfill).\n *\n * This is an in-memory registry for tests, Storybook, and local dev without Chrome.\n * It implements `registerTool`/`listTools`/`invokeTool` but not full MCP transport.\n *\n * For real cross-browser WebMCP (Firefox/Safari), use the dedicated\n * `@mcp-b/webmcp-polyfill` (https://www.npmjs.com/package/@mcp-b/webmcp-polyfill)\n * — ~6k weekly downloads, broader MCP ecosystem. Example:\n *   `npm i @mcp-b/webmcp-polyfill && import '@mcp-b/webmcp-polyfill'`\n *\n * In production Chrome with native `document.modelContext`, this is a no-op\n * (detected via native presence). Prefer the real polyfill for production\n * cross-browser, and this shim for testing.\n *\n * New aliases (preferred for clarity): `simple-webmcp/dev-polyfill` and\n * `simple-webmcp/testing` — same module, clearer intent. `simple-webmcp/polyfill`\n * is kept for backward compat but will be documented as dev shim.\n */\n\nexport type PolyfillOptions = {\n  force?: boolean;\n};\n\nlet installed = false;\n\nexport function installPolyfill(opts?: PolyfillOptions): boolean {\n  if (installed && !opts?.force) return true;\n  if (typeof document === 'undefined') return false;\n  const docAny = document as any;\n  if (docAny.modelContext && !opts?.force) {\n    installed = true;\n    return true;\n  }\n\n  // Minimal polyfill — tracks tools in memory, invokes via same ABI.\n  // Not a full MCP transport; sufficient for registry + tests + devtools.\n  const tools = new Map<\n    string,\n    {\n      def: any;\n      signal?: AbortSignal;\n    }\n  >();\n\n  const polyfill = {\n    _isPolyfill: true,\n    _tools: tools,\n    async registerTool(def: any, opts?: { signal?: AbortSignal }) {\n      const name = def?.name;\n      if (!name) throw new Error('registerTool: name required');\n      if (tools.has(name)) {\n        // Dedup like native — ignore second registration\n        return;\n      }\n      tools.set(name, { def, signal: opts?.signal });\n      if (opts?.signal) {\n        const onAbort = () => {\n          if (tools.get(name)?.signal === opts.signal) tools.delete(name);\n        };\n        if (opts.signal.aborted) {\n          tools.delete(name);\n        } else {\n          opts.signal.addEventListener('abort', onAbort, { once: true });\n        }\n      }\n    },\n    listTools() {\n      return Array.from(tools.values()).map((v) => v.def);\n    },\n    async invokeTool(name: string, args: unknown) {\n      const entry = tools.get(name);\n      if (!entry) throw new Error(`Tool ${name} not found`);\n      return entry.def.execute(args);\n    },\n  };\n\n  docAny.modelContext = polyfill;\n  installed = true;\n  return true;\n}\n\nexport function isPolyfilled(): boolean {\n  if (typeof document === 'undefined') return false;\n  return !!(document as any).modelContext?._isPolyfill;\n}\n\n// Auto-install side-effect import: `import 'simple-webmcp/polyfill'`\nif (typeof document !== 'undefined') {\n  // Defer to next tick to allow native detection first\n  queueMicrotask(() => {\n    const docAny = document as any;\n    if (!docAny.modelContext) {\n      installPolyfill();\n    }\n  });\n}\n\nexport default installPolyfill;\n"]}