@ethisyscore/extension-runtime 1.6.0

package/dist/plugin/index.cjs

@@ -0,0 +1,113 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/plugin/ExtensionRuntimeProvider.tsx
+var ExtensionRuntimeContext = react.createContext(null);
+function ExtensionRuntimeProvider({ transport, children }) {
+  const value = react.useMemo(() => transport, [transport]);
+  return /* @__PURE__ */ jsxRuntime.jsx(ExtensionRuntimeContext.Provider, { value, children });
+}
+function useExtensionRuntimeTransport(override) {
+  const fromContext = react.useContext(ExtensionRuntimeContext);
+  const resolved = override ?? fromContext;
+  if (!resolved) {
+    throw new Error(
+      "No McpTransport available. Wrap your plugin in <ExtensionRuntimeProvider transport={...}> or pass `transport` directly to the hook."
+    );
+  }
+  return resolved;
+}
+function useMcpResource(uri, opts) {
+  const transport = useExtensionRuntimeTransport(opts?.transport);
+  const [data, setData] = react.useState(void 0);
+  const [error, setError] = react.useState(void 0);
+  const [loading, setLoading] = react.useState(true);
+  const [refetchTick, setRefetchTick] = react.useState(0);
+  const controllerRef = react.useRef(null);
+  react.useEffect(() => {
+    const controller = new AbortController();
+    controllerRef.current?.abort();
+    controllerRef.current = controller;
+    let cancelled = false;
+    setLoading(true);
+    setError(void 0);
+    transport.getResource(uri, controller.signal).then((result) => {
+      if (cancelled || controller.signal.aborted) {
+        return;
+      }
+      setData(result.data);
+      setLoading(false);
+    }).catch((err) => {
+      if (cancelled || controller.signal.aborted) {
+        return;
+      }
+      setError(err instanceof Error ? err : new Error(String(err)));
+      setLoading(false);
+    });
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+  }, [uri, transport, refetchTick]);
+  const refetch = react.useCallback(() => {
+    setRefetchTick((tick) => tick + 1);
+  }, []);
+  return { data, error, loading, refetch };
+}
+function useMcpTool(toolName, opts) {
+  const transport = useExtensionRuntimeTransport(opts?.transport);
+  const [loading, setLoading] = react.useState(false);
+  const [error, setError] = react.useState(void 0);
+  const controllerRef = react.useRef(null);
+  const mountedRef = react.useRef(true);
+  react.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      controllerRef.current?.abort();
+    };
+  }, []);
+  const invoke = react.useCallback(
+    async (req) => {
+      const controller = new AbortController();
+      controllerRef.current?.abort();
+      controllerRef.current = controller;
+      setLoading(true);
+      setError(void 0);
+      try {
+        const result = await transport.invokeTool(
+          toolName,
+          req,
+          controller.signal
+        );
+        if (mountedRef.current && !controller.signal.aborted) {
+          setLoading(false);
+        }
+        return result;
+      } catch (err) {
+        const wrapped = err instanceof Error ? err : new Error(String(err));
+        if (mountedRef.current && !controller.signal.aborted) {
+          setError(wrapped);
+          setLoading(false);
+        }
+        throw wrapped;
+      }
+    },
+    [transport, toolName]
+  );
+  return { invoke, loading, error };
+}
+
+// src/plugin/define.ts
+var defineDeclarativePlugin = (cfg) => cfg;
+var defineEthisysPlugin = (cfg) => cfg;
+
+exports.ExtensionRuntimeProvider = ExtensionRuntimeProvider;
+exports.defineDeclarativePlugin = defineDeclarativePlugin;
+exports.defineEthisysPlugin = defineEthisysPlugin;
+exports.useMcpResource = useMcpResource;
+exports.useMcpTool = useMcpTool;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/plugin/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/plugin/ExtensionRuntimeProvider.tsx","../../src/plugin/useMcpResource.ts","../../src/plugin/useMcpTool.ts","../../src/plugin/define.ts"],"names":["createContext","useMemo","jsx","useContext","useState","useRef","useEffect","useCallback"],"mappings":"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","file":"index.cjs","sourcesContent":["import { createContext, useContext, useMemo, type ReactNode } from \"react\";\nimport type { McpTransport } from \"./transport\";\n\n/**\n * React context carrying the {@link McpTransport} the plugin should use to\n * reach the host. `null` is the explicit \"not provided\" sentinel so the hooks\n * can disambiguate from a transport that was provided but is incidentally\n * falsy in some other dimension.\n */\nconst ExtensionRuntimeContext = createContext<McpTransport | null>(null);\n\nexport interface ExtensionRuntimeProviderProps\n{\n    transport: McpTransport;\n    children?: ReactNode;\n}\n\n/**\n * Wrap a plugin's React tree so descendant {@link useMcpResource} and\n * {@link useMcpTool} calls resolve a default transport without having to\n * thread it through every component.\n *\n * Hooks still accept a per-call `transport` override, which takes precedence\n * over the context value — useful for tests and for plugins that want to\n * shard work across multiple hosts.\n */\nexport function ExtensionRuntimeProvider({ transport, children }: ExtensionRuntimeProviderProps): ReactNode\n{\n    // Memoise so swapping `children` doesn't churn the context identity.\n    const value = useMemo(() => transport, [transport]);\n    return (\n        <ExtensionRuntimeContext.Provider value={value}>\n            {children}\n        </ExtensionRuntimeContext.Provider>\n    );\n}\n\n/**\n * Internal helper used by the hooks. Returns the explicit override when\n * supplied, otherwise falls back to the context. Throws a deterministic\n * error if neither is available so misconfiguration fails loudly at the\n * first render rather than producing silent no-ops.\n */\nexport function useExtensionRuntimeTransport(override?: McpTransport): McpTransport\n{\n    const fromContext = useContext(ExtensionRuntimeContext);\n    const resolved = override ?? fromContext;\n    if (!resolved)\n    {\n        throw new Error(\n            \"No McpTransport available. Wrap your plugin in <ExtensionRuntimeProvider transport={...}> \"\n            + \"or pass `transport` directly to the hook.\",\n        );\n    }\n    return resolved;\n}\n","import { useCallback, useEffect, useRef, useState } from \"react\";\nimport { useExtensionRuntimeTransport } from \"./ExtensionRuntimeProvider\";\nimport type { McpTransport } from \"./transport\";\n\nexport interface UseMcpResourceOptions\n{\n    /**\n     * Override the transport resolved from {@link ExtensionRuntimeProvider}.\n     * Primarily intended for tests and advanced multi-host scenarios.\n     */\n    transport?: McpTransport;\n}\n\nexport interface UseMcpResourceResult<T>\n{\n    data: T | undefined;\n    error: Error | undefined;\n    loading: boolean;\n    /** Re-run the fetch against the current URI. Stable across renders. */\n    refetch: () => void;\n}\n\n/**\n * Subscribe to an MCP resource by URI.\n *\n * The hook fetches via the resolved {@link McpTransport} on mount and whenever\n * the URI changes. Each fetch is cancellable: when the component unmounts or\n * the URI changes, the in-flight call is aborted via an {@link AbortController}\n * so stale responses cannot overwrite later state.\n *\n * `refetch` re-runs the fetch against the latest URI. The returned callback is\n * stable across renders so it is safe to include in `useEffect` dependency\n * arrays.\n */\nexport function useMcpResource<T>(\n    uri: string,\n    opts?: UseMcpResourceOptions,\n): UseMcpResourceResult<T>\n{\n    const transport = useExtensionRuntimeTransport(opts?.transport);\n\n    const [data, setData] = useState<T | undefined>(undefined);\n    const [error, setError] = useState<Error | undefined>(undefined);\n    const [loading, setLoading] = useState<boolean>(true);\n\n    // Bump this counter to force a re-fetch from `refetch()`.\n    const [refetchTick, setRefetchTick] = useState(0);\n\n    // Track the active controller so `refetch` and unmount can abort it.\n    const controllerRef = useRef<AbortController | null>(null);\n\n    useEffect(() =>\n    {\n        const controller = new AbortController();\n        controllerRef.current?.abort();\n        controllerRef.current = controller;\n\n        let cancelled = false;\n        setLoading(true);\n        setError(undefined);\n\n        transport\n            .getResource<T>(uri, controller.signal)\n            .then((result) =>\n            {\n                if (cancelled || controller.signal.aborted)\n                {\n                    return;\n                }\n                setData(result.data);\n                setLoading(false);\n            })\n            .catch((err: unknown) =>\n            {\n                if (cancelled || controller.signal.aborted)\n                {\n                    return;\n                }\n                setError(err instanceof Error ? err : new Error(String(err)));\n                setLoading(false);\n            });\n\n        return () =>\n        {\n            cancelled = true;\n            controller.abort();\n        };\n    }, [uri, transport, refetchTick]);\n\n    const refetch = useCallback(() =>\n    {\n        setRefetchTick((tick) => tick + 1);\n    }, []);\n\n    return { data, error, loading, refetch };\n}\n","import { useCallback, useEffect, useRef, useState } from \"react\";\nimport { useExtensionRuntimeTransport } from \"./ExtensionRuntimeProvider\";\nimport type { McpTransport } from \"./transport\";\n\nexport interface UseMcpToolOptions\n{\n    /**\n     * Override the transport resolved from {@link ExtensionRuntimeProvider}.\n     * Primarily intended for tests and advanced multi-host scenarios.\n     */\n    transport?: McpTransport;\n}\n\nexport interface UseMcpToolResult<TReq, TRes>\n{\n    /**\n     * Invoke the tool. Each call gets a fresh {@link AbortController} that is\n     * aborted on unmount so unresolved promises cannot keep state alive after\n     * the component is gone.\n     */\n    invoke: (req: TReq) => Promise<TRes>;\n    loading: boolean;\n    error: Error | undefined;\n}\n\n/**\n * Hook returning a callback that invokes an MCP tool by name through the\n * resolved {@link McpTransport}.\n *\n * `loading` and `error` track the most recent in-flight invocation. Callers\n * may also `await` the returned promise directly — failures are both rejected\n * to the caller AND surfaced via `error` so component-level UI can react.\n *\n * `invoke` is a stable reference across renders for the same `toolName` and\n * transport, making it safe to use inside `useEffect`/`useCallback` deps.\n */\nexport function useMcpTool<TReq, TRes>(\n    toolName: string,\n    opts?: UseMcpToolOptions,\n): UseMcpToolResult<TReq, TRes>\n{\n    const transport = useExtensionRuntimeTransport(opts?.transport);\n\n    const [loading, setLoading] = useState(false);\n    const [error, setError] = useState<Error | undefined>(undefined);\n\n    // Track the latest controller so unmount can abort an in-flight call.\n    const controllerRef = useRef<AbortController | null>(null);\n    const mountedRef = useRef(true);\n\n    useEffect(() =>\n    {\n        mountedRef.current = true;\n        return () =>\n        {\n            mountedRef.current = false;\n            controllerRef.current?.abort();\n        };\n    }, []);\n\n    const invoke = useCallback(\n        async (req: TReq): Promise<TRes> =>\n        {\n            const controller = new AbortController();\n            controllerRef.current?.abort();\n            controllerRef.current = controller;\n\n            setLoading(true);\n            setError(undefined);\n\n            try\n            {\n                const result = await transport.invokeTool<TReq, TRes>(\n                    toolName,\n                    req,\n                    controller.signal,\n                );\n                if (mountedRef.current && !controller.signal.aborted)\n                {\n                    setLoading(false);\n                }\n                return result;\n            }\n            catch (err)\n            {\n                const wrapped = err instanceof Error ? err : new Error(String(err));\n                if (mountedRef.current && !controller.signal.aborted)\n                {\n                    setError(wrapped);\n                    setLoading(false);\n                }\n                throw wrapped;\n            }\n        },\n        [transport, toolName],\n    );\n\n    return { invoke, loading, error };\n}\n","import type { RenderMode, SduiNode } from \"@ethisyscore/protocol\";\n\n/**\n * Configuration accepted by {@link defineDeclarativePlugin}.\n *\n * A Contract A (host-rendered) plugin contributes a map of resource URIs to\n * declarative SDUI trees. The host fetches a resource by URI and renders it\n * against the v1 vocabulary.\n */\nexport interface DeclarativePluginConfig\n{\n    resources: Record<string, SduiNode>;\n}\n\n/**\n * Configuration accepted by {@link defineEthisysPlugin}.\n *\n * `renderMode` is constrained to the protocol's {@link RenderMode} enum so\n * authoring mistakes (`\"iframe\"`, `\"webview\"`, …) are caught at compile time.\n * `mount` is generic so Contract B remote-runtime authors can attach their\n * own mount surface without losing type information at the call site.\n */\nexport interface EthisysPluginConfig<TMount>\n{\n    renderMode: RenderMode;\n    mount?: TMount;\n}\n\n/**\n * Author-facing identity helper for a Contract A (host-rendered) declarative\n * plugin definition.\n *\n * The helper performs no runtime work — it exists purely so authoring sites\n * receive precise type inference and editor tooling against the protocol's\n * {@link SduiNode} contract. The returned value is the exact same reference\n * the caller passed in.\n */\nexport const defineDeclarativePlugin = (\n    cfg: DeclarativePluginConfig,\n): DeclarativePluginConfig => cfg;\n\n/**\n * Author-facing identity helper for a generic EthisysCore plugin definition.\n *\n * The helper performs no runtime work. It constrains `renderMode` to the\n * protocol's {@link RenderMode} enum and preserves the inferred type of an\n * optional `mount` surface, so Contract B authors can pass through their own\n * mount object without widening it to `unknown`.\n */\nexport const defineEthisysPlugin = <TMount>(\n    cfg: EthisysPluginConfig<TMount>,\n): EthisysPluginConfig<TMount> => cfg;\n"]}

package/dist/plugin/index.d.cts

@@ -0,0 +1,120 @@
+import { M as McpTransport } from '../transport-DVn2GVZh.cjs';
+import { ReactNode } from 'react';
+import { SduiNode, RenderMode } from '@ethisyscore/protocol';
+
+interface ExtensionRuntimeProviderProps {
+    transport: McpTransport;
+    children?: ReactNode;
+}
+/**
+ * Wrap a plugin's React tree so descendant {@link useMcpResource} and
+ * {@link useMcpTool} calls resolve a default transport without having to
+ * thread it through every component.
+ *
+ * Hooks still accept a per-call `transport` override, which takes precedence
+ * over the context value — useful for tests and for plugins that want to
+ * shard work across multiple hosts.
+ */
+declare function ExtensionRuntimeProvider({ transport, children }: ExtensionRuntimeProviderProps): ReactNode;
+
+interface UseMcpResourceOptions {
+    /**
+     * Override the transport resolved from {@link ExtensionRuntimeProvider}.
+     * Primarily intended for tests and advanced multi-host scenarios.
+     */
+    transport?: McpTransport;
+}
+interface UseMcpResourceResult<T> {
+    data: T | undefined;
+    error: Error | undefined;
+    loading: boolean;
+    /** Re-run the fetch against the current URI. Stable across renders. */
+    refetch: () => void;
+}
+/**
+ * Subscribe to an MCP resource by URI.
+ *
+ * The hook fetches via the resolved {@link McpTransport} on mount and whenever
+ * the URI changes. Each fetch is cancellable: when the component unmounts or
+ * the URI changes, the in-flight call is aborted via an {@link AbortController}
+ * so stale responses cannot overwrite later state.
+ *
+ * `refetch` re-runs the fetch against the latest URI. The returned callback is
+ * stable across renders so it is safe to include in `useEffect` dependency
+ * arrays.
+ */
+declare function useMcpResource<T>(uri: string, opts?: UseMcpResourceOptions): UseMcpResourceResult<T>;
+
+interface UseMcpToolOptions {
+    /**
+     * Override the transport resolved from {@link ExtensionRuntimeProvider}.
+     * Primarily intended for tests and advanced multi-host scenarios.
+     */
+    transport?: McpTransport;
+}
+interface UseMcpToolResult<TReq, TRes> {
+    /**
+     * Invoke the tool. Each call gets a fresh {@link AbortController} that is
+     * aborted on unmount so unresolved promises cannot keep state alive after
+     * the component is gone.
+     */
+    invoke: (req: TReq) => Promise<TRes>;
+    loading: boolean;
+    error: Error | undefined;
+}
+/**
+ * Hook returning a callback that invokes an MCP tool by name through the
+ * resolved {@link McpTransport}.
+ *
+ * `loading` and `error` track the most recent in-flight invocation. Callers
+ * may also `await` the returned promise directly — failures are both rejected
+ * to the caller AND surfaced via `error` so component-level UI can react.
+ *
+ * `invoke` is a stable reference across renders for the same `toolName` and
+ * transport, making it safe to use inside `useEffect`/`useCallback` deps.
+ */
+declare function useMcpTool<TReq, TRes>(toolName: string, opts?: UseMcpToolOptions): UseMcpToolResult<TReq, TRes>;
+
+/**
+ * Configuration accepted by {@link defineDeclarativePlugin}.
+ *
+ * A Contract A (host-rendered) plugin contributes a map of resource URIs to
+ * declarative SDUI trees. The host fetches a resource by URI and renders it
+ * against the v1 vocabulary.
+ */
+interface DeclarativePluginConfig {
+    resources: Record<string, SduiNode>;
+}
+/**
+ * Configuration accepted by {@link defineEthisysPlugin}.
+ *
+ * `renderMode` is constrained to the protocol's {@link RenderMode} enum so
+ * authoring mistakes (`"iframe"`, `"webview"`, …) are caught at compile time.
+ * `mount` is generic so Contract B remote-runtime authors can attach their
+ * own mount surface without losing type information at the call site.
+ */
+interface EthisysPluginConfig<TMount> {
+    renderMode: RenderMode;
+    mount?: TMount;
+}
+/**
+ * Author-facing identity helper for a Contract A (host-rendered) declarative
+ * plugin definition.
+ *
+ * The helper performs no runtime work — it exists purely so authoring sites
+ * receive precise type inference and editor tooling against the protocol's
+ * {@link SduiNode} contract. The returned value is the exact same reference
+ * the caller passed in.
+ */
+declare const defineDeclarativePlugin: (cfg: DeclarativePluginConfig) => DeclarativePluginConfig;
+/**
+ * Author-facing identity helper for a generic EthisysCore plugin definition.
+ *
+ * The helper performs no runtime work. It constrains `renderMode` to the
+ * protocol's {@link RenderMode} enum and preserves the inferred type of an
+ * optional `mount` surface, so Contract B authors can pass through their own
+ * mount object without widening it to `unknown`.
+ */
+declare const defineEthisysPlugin: <TMount>(cfg: EthisysPluginConfig<TMount>) => EthisysPluginConfig<TMount>;
+
+export { type DeclarativePluginConfig, type EthisysPluginConfig, ExtensionRuntimeProvider, type ExtensionRuntimeProviderProps, McpTransport, type UseMcpResourceOptions, type UseMcpResourceResult, type UseMcpToolOptions, type UseMcpToolResult, defineDeclarativePlugin, defineEthisysPlugin, useMcpResource, useMcpTool };

package/dist/plugin/index.d.ts

@@ -0,0 +1,120 @@
+import { M as McpTransport } from '../transport-DVn2GVZh.js';
+import { ReactNode } from 'react';
+import { SduiNode, RenderMode } from '@ethisyscore/protocol';
+
+interface ExtensionRuntimeProviderProps {
+    transport: McpTransport;
+    children?: ReactNode;
+}
+/**
+ * Wrap a plugin's React tree so descendant {@link useMcpResource} and
+ * {@link useMcpTool} calls resolve a default transport without having to
+ * thread it through every component.
+ *
+ * Hooks still accept a per-call `transport` override, which takes precedence
+ * over the context value — useful for tests and for plugins that want to
+ * shard work across multiple hosts.
+ */
+declare function ExtensionRuntimeProvider({ transport, children }: ExtensionRuntimeProviderProps): ReactNode;
+
+interface UseMcpResourceOptions {
+    /**
+     * Override the transport resolved from {@link ExtensionRuntimeProvider}.
+     * Primarily intended for tests and advanced multi-host scenarios.
+     */
+    transport?: McpTransport;
+}
+interface UseMcpResourceResult<T> {
+    data: T | undefined;
+    error: Error | undefined;
+    loading: boolean;
+    /** Re-run the fetch against the current URI. Stable across renders. */
+    refetch: () => void;
+}
+/**
+ * Subscribe to an MCP resource by URI.
+ *
+ * The hook fetches via the resolved {@link McpTransport} on mount and whenever
+ * the URI changes. Each fetch is cancellable: when the component unmounts or
+ * the URI changes, the in-flight call is aborted via an {@link AbortController}
+ * so stale responses cannot overwrite later state.
+ *
+ * `refetch` re-runs the fetch against the latest URI. The returned callback is
+ * stable across renders so it is safe to include in `useEffect` dependency
+ * arrays.
+ */
+declare function useMcpResource<T>(uri: string, opts?: UseMcpResourceOptions): UseMcpResourceResult<T>;
+
+interface UseMcpToolOptions {
+    /**
+     * Override the transport resolved from {@link ExtensionRuntimeProvider}.
+     * Primarily intended for tests and advanced multi-host scenarios.
+     */
+    transport?: McpTransport;
+}
+interface UseMcpToolResult<TReq, TRes> {
+    /**
+     * Invoke the tool. Each call gets a fresh {@link AbortController} that is
+     * aborted on unmount so unresolved promises cannot keep state alive after
+     * the component is gone.
+     */
+    invoke: (req: TReq) => Promise<TRes>;
+    loading: boolean;
+    error: Error | undefined;
+}
+/**
+ * Hook returning a callback that invokes an MCP tool by name through the
+ * resolved {@link McpTransport}.
+ *
+ * `loading` and `error` track the most recent in-flight invocation. Callers
+ * may also `await` the returned promise directly — failures are both rejected
+ * to the caller AND surfaced via `error` so component-level UI can react.
+ *
+ * `invoke` is a stable reference across renders for the same `toolName` and
+ * transport, making it safe to use inside `useEffect`/`useCallback` deps.
+ */
+declare function useMcpTool<TReq, TRes>(toolName: string, opts?: UseMcpToolOptions): UseMcpToolResult<TReq, TRes>;
+
+/**
+ * Configuration accepted by {@link defineDeclarativePlugin}.
+ *
+ * A Contract A (host-rendered) plugin contributes a map of resource URIs to
+ * declarative SDUI trees. The host fetches a resource by URI and renders it
+ * against the v1 vocabulary.
+ */
+interface DeclarativePluginConfig {
+    resources: Record<string, SduiNode>;
+}
+/**
+ * Configuration accepted by {@link defineEthisysPlugin}.
+ *
+ * `renderMode` is constrained to the protocol's {@link RenderMode} enum so
+ * authoring mistakes (`"iframe"`, `"webview"`, …) are caught at compile time.
+ * `mount` is generic so Contract B remote-runtime authors can attach their
+ * own mount surface without losing type information at the call site.
+ */
+interface EthisysPluginConfig<TMount> {
+    renderMode: RenderMode;
+    mount?: TMount;
+}
+/**
+ * Author-facing identity helper for a Contract A (host-rendered) declarative
+ * plugin definition.
+ *
+ * The helper performs no runtime work — it exists purely so authoring sites
+ * receive precise type inference and editor tooling against the protocol's
+ * {@link SduiNode} contract. The returned value is the exact same reference
+ * the caller passed in.
+ */
+declare const defineDeclarativePlugin: (cfg: DeclarativePluginConfig) => DeclarativePluginConfig;
+/**
+ * Author-facing identity helper for a generic EthisysCore plugin definition.
+ *
+ * The helper performs no runtime work. It constrains `renderMode` to the
+ * protocol's {@link RenderMode} enum and preserves the inferred type of an
+ * optional `mount` surface, so Contract B authors can pass through their own
+ * mount object without widening it to `unknown`.
+ */
+declare const defineEthisysPlugin: <TMount>(cfg: EthisysPluginConfig<TMount>) => EthisysPluginConfig<TMount>;
+
+export { type DeclarativePluginConfig, type EthisysPluginConfig, ExtensionRuntimeProvider, type ExtensionRuntimeProviderProps, McpTransport, type UseMcpResourceOptions, type UseMcpResourceResult, type UseMcpToolOptions, type UseMcpToolResult, defineDeclarativePlugin, defineEthisysPlugin, useMcpResource, useMcpTool };

package/dist/plugin/index.js

@@ -0,0 +1,107 @@
+import { createContext, useMemo, useState, useRef, useEffect, useCallback, useContext } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/plugin/ExtensionRuntimeProvider.tsx
+var ExtensionRuntimeContext = createContext(null);
+function ExtensionRuntimeProvider({ transport, children }) {
+  const value = useMemo(() => transport, [transport]);
+  return /* @__PURE__ */ jsx(ExtensionRuntimeContext.Provider, { value, children });
+}
+function useExtensionRuntimeTransport(override) {
+  const fromContext = useContext(ExtensionRuntimeContext);
+  const resolved = override ?? fromContext;
+  if (!resolved) {
+    throw new Error(
+      "No McpTransport available. Wrap your plugin in <ExtensionRuntimeProvider transport={...}> or pass `transport` directly to the hook."
+    );
+  }
+  return resolved;
+}
+function useMcpResource(uri, opts) {
+  const transport = useExtensionRuntimeTransport(opts?.transport);
+  const [data, setData] = useState(void 0);
+  const [error, setError] = useState(void 0);
+  const [loading, setLoading] = useState(true);
+  const [refetchTick, setRefetchTick] = useState(0);
+  const controllerRef = useRef(null);
+  useEffect(() => {
+    const controller = new AbortController();
+    controllerRef.current?.abort();
+    controllerRef.current = controller;
+    let cancelled = false;
+    setLoading(true);
+    setError(void 0);
+    transport.getResource(uri, controller.signal).then((result) => {
+      if (cancelled || controller.signal.aborted) {
+        return;
+      }
+      setData(result.data);
+      setLoading(false);
+    }).catch((err) => {
+      if (cancelled || controller.signal.aborted) {
+        return;
+      }
+      setError(err instanceof Error ? err : new Error(String(err)));
+      setLoading(false);
+    });
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+  }, [uri, transport, refetchTick]);
+  const refetch = useCallback(() => {
+    setRefetchTick((tick) => tick + 1);
+  }, []);
+  return { data, error, loading, refetch };
+}
+function useMcpTool(toolName, opts) {
+  const transport = useExtensionRuntimeTransport(opts?.transport);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(void 0);
+  const controllerRef = useRef(null);
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      controllerRef.current?.abort();
+    };
+  }, []);
+  const invoke = useCallback(
+    async (req) => {
+      const controller = new AbortController();
+      controllerRef.current?.abort();
+      controllerRef.current = controller;
+      setLoading(true);
+      setError(void 0);
+      try {
+        const result = await transport.invokeTool(
+          toolName,
+          req,
+          controller.signal
+        );
+        if (mountedRef.current && !controller.signal.aborted) {
+          setLoading(false);
+        }
+        return result;
+      } catch (err) {
+        const wrapped = err instanceof Error ? err : new Error(String(err));
+        if (mountedRef.current && !controller.signal.aborted) {
+          setError(wrapped);
+          setLoading(false);
+        }
+        throw wrapped;
+      }
+    },
+    [transport, toolName]
+  );
+  return { invoke, loading, error };
+}
+
+// src/plugin/define.ts
+var defineDeclarativePlugin = (cfg) => cfg;
+var defineEthisysPlugin = (cfg) => cfg;
+
+export { ExtensionRuntimeProvider, defineDeclarativePlugin, defineEthisysPlugin, useMcpResource, useMcpTool };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/plugin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/plugin/ExtensionRuntimeProvider.tsx","../../src/plugin/useMcpResource.ts","../../src/plugin/useMcpTool.ts","../../src/plugin/define.ts"],"names":["useState","useRef","useEffect","useCallback"],"mappings":";;;;AASA,IAAM,uBAAA,GAA0B,cAAmC,IAAI,CAAA;AAiBhE,SAAS,wBAAA,CAAyB,EAAE,SAAA,EAAW,QAAA,EAAS,EAC/D;AAEI,EAAA,MAAM,QAAQ,OAAA,CAAQ,MAAM,SAAA,EAAW,CAAC,SAAS,CAAC,CAAA;AAClD,EAAA,uBACI,GAAA,CAAC,uBAAA,CAAwB,QAAA,EAAxB,EAAiC,OAC7B,QAAA,EACL,CAAA;AAER;AAQO,SAAS,6BAA6B,QAAA,EAC7C;AACI,EAAA,MAAM,WAAA,GAAc,WAAW,uBAAuB,CAAA;AACtD,EAAA,MAAM,WAAW,QAAA,IAAY,WAAA;AAC7B,EAAA,IAAI,CAAC,QAAA,EACL;AACI,IAAA,MAAM,IAAI,KAAA;AAAA,MACN;AAAA,KAEJ;AAAA,EACJ;AACA,EAAA,OAAO,QAAA;AACX;ACrBO,SAAS,cAAA,CACZ,KACA,IAAA,EAEJ;AACI,EAAA,MAAM,SAAA,GAAY,4BAAA,CAA6B,IAAA,EAAM,SAAS,CAAA;AAE9D,EAAA,MAAM,CAAC,IAAA,EAAM,OAAO,CAAA,GAAI,SAAwB,MAAS,CAAA;AACzD,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,CAAA,GAAI,SAA4B,MAAS,CAAA;AAC/D,EAAA,MAAM,CAAC,OAAA,EAAS,UAAU,CAAA,GAAI,SAAkB,IAAI,CAAA;AAGpD,EAAA,MAAM,CAAC,WAAA,EAAa,cAAc,CAAA,GAAI,SAAS,CAAC,CAAA;AAGhD,EAAA,MAAM,aAAA,GAAgB,OAA+B,IAAI,CAAA;AAEzD,EAAA,SAAA,CAAU,MACV;AACI,IAAA,MAAM,UAAA,GAAa,IAAI,eAAA,EAAgB;AACvC,IAAA,aAAA,CAAc,SAAS,KAAA,EAAM;AAC7B,IAAA,aAAA,CAAc,OAAA,GAAU,UAAA;AAExB,IAAA,IAAI,SAAA,GAAY,KAAA;AAChB,IAAA,UAAA,CAAW,IAAI,CAAA;AACf,IAAA,QAAA,CAAS,MAAS,CAAA;AAElB,IAAA,SAAA,CACK,YAAe,GAAA,EAAK,UAAA,CAAW,MAAM,CAAA,CACrC,IAAA,CAAK,CAAC,MAAA,KACP;AACI,MAAA,IAAI,SAAA,IAAa,UAAA,CAAW,MAAA,CAAO,OAAA,EACnC;AACI,QAAA;AAAA,MACJ;AACA,MAAA,OAAA,CAAQ,OAAO,IAAI,CAAA;AACnB,MAAA,UAAA,CAAW,KAAK,CAAA;AAAA,IACpB,CAAC,CAAA,CACA,KAAA,CAAM,CAAC,GAAA,KACR;AACI,MAAA,IAAI,SAAA,IAAa,UAAA,CAAW,MAAA,CAAO,OAAA,EACnC;AACI,QAAA;AAAA,MACJ;AACA,MAAA,QAAA,CAAS,GAAA,YAAe,QAAQ,GAAA,GAAM,IAAI,MAAM,MAAA,CAAO,GAAG,CAAC,CAAC,CAAA;AAC5D,MAAA,UAAA,CAAW,KAAK,CAAA;AAAA,IACpB,CAAC,CAAA;AAEL,IAAA,OAAO,MACP;AACI,MAAA,SAAA,GAAY,IAAA;AACZ,MAAA,UAAA,CAAW,KAAA,EAAM;AAAA,IACrB,CAAA;AAAA,EACJ,CAAA,EAAG,CAAC,GAAA,EAAK,SAAA,EAAW,WAAW,CAAC,CAAA;AAEhC,EAAA,MAAM,OAAA,GAAU,YAAY,MAC5B;AACI,IAAA,cAAA,CAAe,CAAC,IAAA,KAAS,IAAA,GAAO,CAAC,CAAA;AAAA,EACrC,CAAA,EAAG,EAAE,CAAA;AAEL,EAAA,OAAO,EAAE,IAAA,EAAM,KAAA,EAAO,OAAA,EAAS,OAAA,EAAQ;AAC3C;AC3DO,SAAS,UAAA,CACZ,UACA,IAAA,EAEJ;AACI,EAAA,MAAM,SAAA,GAAY,4BAAA,CAA6B,IAAA,EAAM,SAAS,CAAA;AAE9D,EAAA,MAAM,CAAC,OAAA,EAAS,UAAU,CAAA,GAAIA,SAAS,KAAK,CAAA;AAC5C,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,CAAA,GAAIA,SAA4B,MAAS,CAAA;AAG/D,EAAA,MAAM,aAAA,GAAgBC,OAA+B,IAAI,CAAA;AACzD,EAAA,MAAM,UAAA,GAAaA,OAAO,IAAI,CAAA;AAE9B,EAAAC,UAAU,MACV;AACI,IAAA,UAAA,CAAW,OAAA,GAAU,IAAA;AACrB,IAAA,OAAO,MACP;AACI,MAAA,UAAA,CAAW,OAAA,GAAU,KAAA;AACrB,MAAA,aAAA,CAAc,SAAS,KAAA,EAAM;AAAA,IACjC,CAAA;AAAA,EACJ,CAAA,EAAG,EAAE,CAAA;AAEL,EAAA,MAAM,MAAA,GAASC,WAAAA;AAAA,IACX,OAAO,GAAA,KACP;AACI,MAAA,MAAM,UAAA,GAAa,IAAI,eAAA,EAAgB;AACvC,MAAA,aAAA,CAAc,SAAS,KAAA,EAAM;AAC7B,MAAA,aAAA,CAAc,OAAA,GAAU,UAAA;AAExB,MAAA,UAAA,CAAW,IAAI,CAAA;AACf,MAAA,QAAA,CAAS,MAAS,CAAA;AAElB,MAAA,IACA;AACI,QAAA,MAAM,MAAA,GAAS,MAAM,SAAA,CAAU,UAAA;AAAA,UAC3B,QAAA;AAAA,UACA,GAAA;AAAA,UACA,UAAA,CAAW;AAAA,SACf;AACA,QAAA,IAAI,UAAA,CAAW,OAAA,IAAW,CAAC,UAAA,CAAW,OAAO,OAAA,EAC7C;AACI,UAAA,UAAA,CAAW,KAAK,CAAA;AAAA,QACpB;AACA,QAAA,OAAO,MAAA;AAAA,MACX,SACO,GAAA,EACP;AACI,QAAA,MAAM,OAAA,GAAU,eAAe,KAAA,GAAQ,GAAA,GAAM,IAAI,KAAA,CAAM,MAAA,CAAO,GAAG,CAAC,CAAA;AAClE,QAAA,IAAI,UAAA,CAAW,OAAA,IAAW,CAAC,UAAA,CAAW,OAAO,OAAA,EAC7C;AACI,UAAA,QAAA,CAAS,OAAO,CAAA;AAChB,UAAA,UAAA,CAAW,KAAK,CAAA;AAAA,QACpB;AACA,QAAA,MAAM,OAAA;AAAA,MACV;AAAA,IACJ,CAAA;AAAA,IACA,CAAC,WAAW,QAAQ;AAAA,GACxB;AAEA,EAAA,OAAO,EAAE,MAAA,EAAQ,OAAA,EAAS,KAAA,EAAM;AACpC;;;AC7DO,IAAM,uBAAA,GAA0B,CACnC,GAAA,KAC0B;AAUvB,IAAM,mBAAA,GAAsB,CAC/B,GAAA,KAC8B","file":"index.js","sourcesContent":["import { createContext, useContext, useMemo, type ReactNode } from \"react\";\nimport type { McpTransport } from \"./transport\";\n\n/**\n * React context carrying the {@link McpTransport} the plugin should use to\n * reach the host. `null` is the explicit \"not provided\" sentinel so the hooks\n * can disambiguate from a transport that was provided but is incidentally\n * falsy in some other dimension.\n */\nconst ExtensionRuntimeContext = createContext<McpTransport | null>(null);\n\nexport interface ExtensionRuntimeProviderProps\n{\n    transport: McpTransport;\n    children?: ReactNode;\n}\n\n/**\n * Wrap a plugin's React tree so descendant {@link useMcpResource} and\n * {@link useMcpTool} calls resolve a default transport without having to\n * thread it through every component.\n *\n * Hooks still accept a per-call `transport` override, which takes precedence\n * over the context value — useful for tests and for plugins that want to\n * shard work across multiple hosts.\n */\nexport function ExtensionRuntimeProvider({ transport, children }: ExtensionRuntimeProviderProps): ReactNode\n{\n    // Memoise so swapping `children` doesn't churn the context identity.\n    const value = useMemo(() => transport, [transport]);\n    return (\n        <ExtensionRuntimeContext.Provider value={value}>\n            {children}\n        </ExtensionRuntimeContext.Provider>\n    );\n}\n\n/**\n * Internal helper used by the hooks. Returns the explicit override when\n * supplied, otherwise falls back to the context. Throws a deterministic\n * error if neither is available so misconfiguration fails loudly at the\n * first render rather than producing silent no-ops.\n */\nexport function useExtensionRuntimeTransport(override?: McpTransport): McpTransport\n{\n    const fromContext = useContext(ExtensionRuntimeContext);\n    const resolved = override ?? fromContext;\n    if (!resolved)\n    {\n        throw new Error(\n            \"No McpTransport available. Wrap your plugin in <ExtensionRuntimeProvider transport={...}> \"\n            + \"or pass `transport` directly to the hook.\",\n        );\n    }\n    return resolved;\n}\n","import { useCallback, useEffect, useRef, useState } from \"react\";\nimport { useExtensionRuntimeTransport } from \"./ExtensionRuntimeProvider\";\nimport type { McpTransport } from \"./transport\";\n\nexport interface UseMcpResourceOptions\n{\n    /**\n     * Override the transport resolved from {@link ExtensionRuntimeProvider}.\n     * Primarily intended for tests and advanced multi-host scenarios.\n     */\n    transport?: McpTransport;\n}\n\nexport interface UseMcpResourceResult<T>\n{\n    data: T | undefined;\n    error: Error | undefined;\n    loading: boolean;\n    /** Re-run the fetch against the current URI. Stable across renders. */\n    refetch: () => void;\n}\n\n/**\n * Subscribe to an MCP resource by URI.\n *\n * The hook fetches via the resolved {@link McpTransport} on mount and whenever\n * the URI changes. Each fetch is cancellable: when the component unmounts or\n * the URI changes, the in-flight call is aborted via an {@link AbortController}\n * so stale responses cannot overwrite later state.\n *\n * `refetch` re-runs the fetch against the latest URI. The returned callback is\n * stable across renders so it is safe to include in `useEffect` dependency\n * arrays.\n */\nexport function useMcpResource<T>(\n    uri: string,\n    opts?: UseMcpResourceOptions,\n): UseMcpResourceResult<T>\n{\n    const transport = useExtensionRuntimeTransport(opts?.transport);\n\n    const [data, setData] = useState<T | undefined>(undefined);\n    const [error, setError] = useState<Error | undefined>(undefined);\n    const [loading, setLoading] = useState<boolean>(true);\n\n    // Bump this counter to force a re-fetch from `refetch()`.\n    const [refetchTick, setRefetchTick] = useState(0);\n\n    // Track the active controller so `refetch` and unmount can abort it.\n    const controllerRef = useRef<AbortController | null>(null);\n\n    useEffect(() =>\n    {\n        const controller = new AbortController();\n        controllerRef.current?.abort();\n        controllerRef.current = controller;\n\n        let cancelled = false;\n        setLoading(true);\n        setError(undefined);\n\n        transport\n            .getResource<T>(uri, controller.signal)\n            .then((result) =>\n            {\n                if (cancelled || controller.signal.aborted)\n                {\n                    return;\n                }\n                setData(result.data);\n                setLoading(false);\n            })\n            .catch((err: unknown) =>\n            {\n                if (cancelled || controller.signal.aborted)\n                {\n                    return;\n                }\n                setError(err instanceof Error ? err : new Error(String(err)));\n                setLoading(false);\n            });\n\n        return () =>\n        {\n            cancelled = true;\n            controller.abort();\n        };\n    }, [uri, transport, refetchTick]);\n\n    const refetch = useCallback(() =>\n    {\n        setRefetchTick((tick) => tick + 1);\n    }, []);\n\n    return { data, error, loading, refetch };\n}\n","import { useCallback, useEffect, useRef, useState } from \"react\";\nimport { useExtensionRuntimeTransport } from \"./ExtensionRuntimeProvider\";\nimport type { McpTransport } from \"./transport\";\n\nexport interface UseMcpToolOptions\n{\n    /**\n     * Override the transport resolved from {@link ExtensionRuntimeProvider}.\n     * Primarily intended for tests and advanced multi-host scenarios.\n     */\n    transport?: McpTransport;\n}\n\nexport interface UseMcpToolResult<TReq, TRes>\n{\n    /**\n     * Invoke the tool. Each call gets a fresh {@link AbortController} that is\n     * aborted on unmount so unresolved promises cannot keep state alive after\n     * the component is gone.\n     */\n    invoke: (req: TReq) => Promise<TRes>;\n    loading: boolean;\n    error: Error | undefined;\n}\n\n/**\n * Hook returning a callback that invokes an MCP tool by name through the\n * resolved {@link McpTransport}.\n *\n * `loading` and `error` track the most recent in-flight invocation. Callers\n * may also `await` the returned promise directly — failures are both rejected\n * to the caller AND surfaced via `error` so component-level UI can react.\n *\n * `invoke` is a stable reference across renders for the same `toolName` and\n * transport, making it safe to use inside `useEffect`/`useCallback` deps.\n */\nexport function useMcpTool<TReq, TRes>(\n    toolName: string,\n    opts?: UseMcpToolOptions,\n): UseMcpToolResult<TReq, TRes>\n{\n    const transport = useExtensionRuntimeTransport(opts?.transport);\n\n    const [loading, setLoading] = useState(false);\n    const [error, setError] = useState<Error | undefined>(undefined);\n\n    // Track the latest controller so unmount can abort an in-flight call.\n    const controllerRef = useRef<AbortController | null>(null);\n    const mountedRef = useRef(true);\n\n    useEffect(() =>\n    {\n        mountedRef.current = true;\n        return () =>\n        {\n            mountedRef.current = false;\n            controllerRef.current?.abort();\n        };\n    }, []);\n\n    const invoke = useCallback(\n        async (req: TReq): Promise<TRes> =>\n        {\n            const controller = new AbortController();\n            controllerRef.current?.abort();\n            controllerRef.current = controller;\n\n            setLoading(true);\n            setError(undefined);\n\n            try\n            {\n                const result = await transport.invokeTool<TReq, TRes>(\n                    toolName,\n                    req,\n                    controller.signal,\n                );\n                if (mountedRef.current && !controller.signal.aborted)\n                {\n                    setLoading(false);\n                }\n                return result;\n            }\n            catch (err)\n            {\n                const wrapped = err instanceof Error ? err : new Error(String(err));\n                if (mountedRef.current && !controller.signal.aborted)\n                {\n                    setError(wrapped);\n                    setLoading(false);\n                }\n                throw wrapped;\n            }\n        },\n        [transport, toolName],\n    );\n\n    return { invoke, loading, error };\n}\n","import type { RenderMode, SduiNode } from \"@ethisyscore/protocol\";\n\n/**\n * Configuration accepted by {@link defineDeclarativePlugin}.\n *\n * A Contract A (host-rendered) plugin contributes a map of resource URIs to\n * declarative SDUI trees. The host fetches a resource by URI and renders it\n * against the v1 vocabulary.\n */\nexport interface DeclarativePluginConfig\n{\n    resources: Record<string, SduiNode>;\n}\n\n/**\n * Configuration accepted by {@link defineEthisysPlugin}.\n *\n * `renderMode` is constrained to the protocol's {@link RenderMode} enum so\n * authoring mistakes (`\"iframe\"`, `\"webview\"`, …) are caught at compile time.\n * `mount` is generic so Contract B remote-runtime authors can attach their\n * own mount surface without losing type information at the call site.\n */\nexport interface EthisysPluginConfig<TMount>\n{\n    renderMode: RenderMode;\n    mount?: TMount;\n}\n\n/**\n * Author-facing identity helper for a Contract A (host-rendered) declarative\n * plugin definition.\n *\n * The helper performs no runtime work — it exists purely so authoring sites\n * receive precise type inference and editor tooling against the protocol's\n * {@link SduiNode} contract. The returned value is the exact same reference\n * the caller passed in.\n */\nexport const defineDeclarativePlugin = (\n    cfg: DeclarativePluginConfig,\n): DeclarativePluginConfig => cfg;\n\n/**\n * Author-facing identity helper for a generic EthisysCore plugin definition.\n *\n * The helper performs no runtime work. It constrains `renderMode` to the\n * protocol's {@link RenderMode} enum and preserves the inferred type of an\n * optional `mount` surface, so Contract B authors can pass through their own\n * mount object without widening it to `unknown`.\n */\nexport const defineEthisysPlugin = <TMount>(\n    cfg: EthisysPluginConfig<TMount>,\n): EthisysPluginConfig<TMount> => cfg;\n"]}

package/dist/registry-DpCx_LxF.d.cts

@@ -0,0 +1,25 @@
+import { ComponentType, ReactNode } from 'react';
+import { PrimitiveName } from '@ethisyscore/protocol';
+
+/**
+ * Props supplied by the interpreter to every registered primitive component.
+ *
+ * - `children` — already-interpreted child nodes (zero or more React elements).
+ * - `props`   — opaque per-primitive properties from the SDUI tree. The host
+ *   component owns interpretation. The interpreter never reads or mutates them.
+ */
+interface PrimitiveProps {
+    children?: ReactNode;
+    props?: Record<string, unknown>;
+}
+/**
+ * Exhaustive primitive-name → component map.
+ *
+ * `Record<PrimitiveName, ...>` forces TypeScript to fail compilation if any of
+ * the closed v1 vocabulary entries are missing when a consumer constructs the
+ * registry. This is the mechanism that keeps host registries in lockstep with
+ * the protocol-owned primitive set.
+ */
+type ComponentRegistry = Record<PrimitiveName, ComponentType<PrimitiveProps>>;
+
+export type { ComponentRegistry as C, PrimitiveProps as P };

package/dist/registry-DpCx_LxF.d.ts

@@ -0,0 +1,25 @@
+import { ComponentType, ReactNode } from 'react';
+import { PrimitiveName } from '@ethisyscore/protocol';
+
+/**
+ * Props supplied by the interpreter to every registered primitive component.
+ *
+ * - `children` — already-interpreted child nodes (zero or more React elements).
+ * - `props`   — opaque per-primitive properties from the SDUI tree. The host
+ *   component owns interpretation. The interpreter never reads or mutates them.
+ */
+interface PrimitiveProps {
+    children?: ReactNode;
+    props?: Record<string, unknown>;
+}
+/**
+ * Exhaustive primitive-name → component map.
+ *
+ * `Record<PrimitiveName, ...>` forces TypeScript to fail compilation if any of
+ * the closed v1 vocabulary entries are missing when a consumer constructs the
+ * registry. This is the mechanism that keeps host registries in lockstep with
+ * the protocol-owned primitive set.
+ */
+type ComponentRegistry = Record<PrimitiveName, ComponentType<PrimitiveProps>>;
+
+export type { ComponentRegistry as C, PrimitiveProps as P };