@ethisyscore/plugin-ui 1.111.0 → 1.112.0

package/dist/platform-react/index.d.cts

@@ -40,7 +40,13 @@ interface DefinePlatformReactPluginPageOptions {
     styleId: string;
     /** The plugin's compiled CSS string (typically a `*.css?inline` import). */
     css: string;
-    /** Override the per-page `QueryClient`. */
+    /**
+     * Override the `QueryClient` this page runs on.
+     *
+     * Left unset, the page runs on the host's client when the host realm provides
+     * one, and on a per-bundle client of its own when it does not — see
+     * {@link useSurfaceQueryClient}. Setting it opts out of both.
+     */
     queryClient?: QueryClient;
     /**
      * Optional wrapper applied around the page element, inside the style root. Use
@@ -96,12 +102,14 @@ interface PluginPageDefinerConfig {
 declare function createPluginPageDefiner(config: PluginPageDefinerConfig): (Page: ComponentType<PlatformReactPageProps>, views?: Record<string, ViewComponent>) => ComponentType<PlatformReactPageProps>;
 
 /**
- * The `QueryClient` every PlatformReact plugin surface runs on.
+ * The `QueryClient` a PlatformReact plugin surface falls back to when the host realm provides
+ * none — see {@link useSurfaceQueryClient} for when that is, and what it costs.
  *
  * # Why this file exists
  *
- * A plugin bundle cannot see the host's app-wide `QueryClientProvider` — react-query is
- * bundle-local, which is why each page and overlay creates its own client. The host's client
+ * It predates the react-query external. A plugin bundle could not see the host's app-wide
+ * `QueryClientProvider` — react-query was bundle-local, which is why each page and overlay
+ * created its own client. The host's client
  * carries cache-level `onError` handlers that turn a failed query or mutation into a toast, and
  * for a long time the plugin-side client carried none. The consequence was not a degraded
  * message: it was NO message. A command could be refused by the server, travel back through
@@ -139,6 +147,20 @@ interface PluginQueryMeta {
  */
 declare function createPluginQueryClient(config?: QueryClientConfig): QueryClient;
 
+/**
+ * The client this surface should provide to its subtree.
+ *
+ * Precedence, and the order matters:
+ *
+ * 1. `override` — the definers' existing `queryClient` option. A plugin that asks
+ *    for a specific client gets it, and is never second-guessed or warned about.
+ * 2. The host's client, read from the host realm's react-query context.
+ * 3. This bundle's own client — today's behaviour, unchanged.
+ *
+ * @param override The `queryClient` a definer's caller supplied, if any.
+ */
+declare function useSurfaceQueryClient(override?: QueryClient): QueryClient;
+
 /**
  * Matches component types renderable via `useView`: plain function/class
  * components plus the object wrappers `React.lazy`, `React.forwardRef`, and
@@ -1180,7 +1202,13 @@ interface DefinePlatformReactPluginOverlayOptions {
     styleId: string;
     css: string;
     manifest?: Record<string, Partial<Record<string, ViewComponent>>>;
-    /** Override the per-overlay `QueryClient`. */
+    /**
+     * Override the `QueryClient` this overlay runs on.
+     *
+     * Left unset, the overlay runs on the host's client when the host realm
+     * provides one, and on a per-bundle client of its own when it does not — see
+     * {@link useSurfaceQueryClient}. Setting it opts out of both.
+     */
     queryClient?: QueryClient;
     wrapOverlay?: (overlay: ReactElement) => ReactElement;
 }
@@ -1430,4 +1458,4 @@ interface MenuConfigHostSidebarOptions {
  */
 declare function menuConfigToHostSidebarInput(config: HeaderMenuItem[], opts: MenuConfigHostSidebarOptions): HostSidebarHookInput;
 
-export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, type PluginQueryMeta, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceUrl, useTypedToolInvokerMap, useView };
+export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, type PluginQueryMeta, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceQueryClient, useSurfaceUrl, useTypedToolInvokerMap, useView };

package/dist/platform-react/index.d.ts

@@ -40,7 +40,13 @@ interface DefinePlatformReactPluginPageOptions {
     styleId: string;
     /** The plugin's compiled CSS string (typically a `*.css?inline` import). */
     css: string;
-    /** Override the per-page `QueryClient`. */
+    /**
+     * Override the `QueryClient` this page runs on.
+     *
+     * Left unset, the page runs on the host's client when the host realm provides
+     * one, and on a per-bundle client of its own when it does not — see
+     * {@link useSurfaceQueryClient}. Setting it opts out of both.
+     */
     queryClient?: QueryClient;
     /**
      * Optional wrapper applied around the page element, inside the style root. Use
@@ -96,12 +102,14 @@ interface PluginPageDefinerConfig {
 declare function createPluginPageDefiner(config: PluginPageDefinerConfig): (Page: ComponentType<PlatformReactPageProps>, views?: Record<string, ViewComponent>) => ComponentType<PlatformReactPageProps>;
 
 /**
- * The `QueryClient` every PlatformReact plugin surface runs on.
+ * The `QueryClient` a PlatformReact plugin surface falls back to when the host realm provides
+ * none — see {@link useSurfaceQueryClient} for when that is, and what it costs.
  *
  * # Why this file exists
  *
- * A plugin bundle cannot see the host's app-wide `QueryClientProvider` — react-query is
- * bundle-local, which is why each page and overlay creates its own client. The host's client
+ * It predates the react-query external. A plugin bundle could not see the host's app-wide
+ * `QueryClientProvider` — react-query was bundle-local, which is why each page and overlay
+ * created its own client. The host's client
  * carries cache-level `onError` handlers that turn a failed query or mutation into a toast, and
  * for a long time the plugin-side client carried none. The consequence was not a degraded
  * message: it was NO message. A command could be refused by the server, travel back through
@@ -139,6 +147,20 @@ interface PluginQueryMeta {
  */
 declare function createPluginQueryClient(config?: QueryClientConfig): QueryClient;
 
+/**
+ * The client this surface should provide to its subtree.
+ *
+ * Precedence, and the order matters:
+ *
+ * 1. `override` — the definers' existing `queryClient` option. A plugin that asks
+ *    for a specific client gets it, and is never second-guessed or warned about.
+ * 2. The host's client, read from the host realm's react-query context.
+ * 3. This bundle's own client — today's behaviour, unchanged.
+ *
+ * @param override The `queryClient` a definer's caller supplied, if any.
+ */
+declare function useSurfaceQueryClient(override?: QueryClient): QueryClient;
+
 /**
  * Matches component types renderable via `useView`: plain function/class
  * components plus the object wrappers `React.lazy`, `React.forwardRef`, and
@@ -1180,7 +1202,13 @@ interface DefinePlatformReactPluginOverlayOptions {
     styleId: string;
     css: string;
     manifest?: Record<string, Partial<Record<string, ViewComponent>>>;
-    /** Override the per-overlay `QueryClient`. */
+    /**
+     * Override the `QueryClient` this overlay runs on.
+     *
+     * Left unset, the overlay runs on the host's client when the host realm
+     * provides one, and on a per-bundle client of its own when it does not — see
+     * {@link useSurfaceQueryClient}. Setting it opts out of both.
+     */
     queryClient?: QueryClient;
     wrapOverlay?: (overlay: ReactElement) => ReactElement;
 }
@@ -1430,4 +1458,4 @@ interface MenuConfigHostSidebarOptions {
  */
 declare function menuConfigToHostSidebarInput(config: HeaderMenuItem[], opts: MenuConfigHostSidebarOptions): HostSidebarHookInput;
 
-export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, type PluginQueryMeta, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceUrl, useTypedToolInvokerMap, useView };
+export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, type PluginQueryMeta, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceQueryClient, useSurfaceUrl, useTypedToolInvokerMap, useView };

package/dist/platform-react/index.js

@@ -1,4 +1,5 @@
-import { createContext, useEffect, useContext, useState, useMemo, useRef, createElement, useCallback, useSyncExternalStore } from 'react';
+import { createContext, useContext, useEffect, useState, useMemo, useRef, createElement, useCallback, useSyncExternalStore } from 'react';
+import * as reactQuery from '@tanstack/react-query';
 import { QueryClient, MutationCache, QueryCache, useQuery, useQueries, QueryClientProvider } from '@tanstack/react-query';
 import { definePlatformReactPage, emitNavigation } from '@ethisyscore/components-react';
 import * as extensionRuntime from '@ethisyscore/extension-runtime/plugin';
@@ -88,6 +89,39 @@ function createPluginQueryClient(config) {
     }
   });
 }
+
+// src/platform-react/hostQueryClient.ts
+var hostRealmExposesContext = isReactContext(reactQuery.QueryClientContext);
+var resolvedHostContext = hostRealmExposesContext ? reactQuery.QueryClientContext : createContext(void 0);
+function isReactContext(value) {
+  return typeof value === "object" && value !== null && "Provider" in value;
+}
+var bundleQueryClient;
+function pluginBundleQueryClient() {
+  bundleQueryClient ??= createPluginQueryClient();
+  return bundleQueryClient;
+}
+var warnedAboutMissingHostClient = false;
+function warnOnceAboutMissingHostClient() {
+  if (warnedAboutMissingHostClient) {
+    return;
+  }
+  warnedAboutMissingHostClient = true;
+  console.warn(
+    "[plugin-ui] The host realm provides no QueryClient" + (hostRealmExposesContext ? " (@tanstack/react-query is served, but this surface renders outside the host's QueryClientProvider)" : " (the host's @tanstack/react-query namespace has no QueryClientContext export)") + ". This surface falls back to a client of its own, so a mutation here will not invalidate another surface's cache. Deploy a host that mounts plugin surfaces inside its QueryClientProvider to share one cache."
+  );
+}
+function useSurfaceQueryClient(override) {
+  const hostQueryClient = useContext(resolvedHostContext);
+  if (override !== void 0) {
+    return override;
+  }
+  if (hostQueryClient !== void 0) {
+    return hostQueryClient;
+  }
+  warnOnceAboutMissingHostClient();
+  return pluginBundleQueryClient();
+}
 var TemplateContext = createContext(null);
 function injectPluginStyles(id, css) {
   if (typeof document === "undefined") return;
@@ -307,7 +341,6 @@ function useReportingCurrencySync() {
 }
 
 // src/platform-react/definePlatformReactPluginPage.tsx
-var defaultQueryClient = createPluginQueryClient();
 var EHX_PLUGIN_ROOT_CLASS = "ehx-plugin-root";
 function definePlatformReactPluginPage(Page, options) {
   const {
@@ -315,10 +348,11 @@ function definePlatformReactPluginPage(Page, options) {
     rootClassName,
     styleId,
     css,
-    queryClient = defaultQueryClient,
+    queryClient: queryClientOverride,
     wrapPage
   } = options;
   function PluginPage(props) {
+    const queryClient = useSurfaceQueryClient(queryClientOverride);
     useOrgFormatSync();
     useReportingCurrencySync();
     const page = createElement(Page, props);
@@ -798,18 +832,19 @@ function useOverlayHost() {
   }
   return api;
 }
-var defaultQueryClient2 = createPluginQueryClient();
 function definePlatformReactPluginOverlay(Overlay, options) {
-  const { rootClassName, styleId, css, manifest = {}, queryClient = defaultQueryClient2, wrapOverlay } = options;
+  const { rootClassName, styleId, css, manifest = {}, queryClient: queryClientOverride, wrapOverlay } = options;
   return function MountedOverlay(props) {
+    const queryClient = useSurfaceQueryClient(queryClientOverride);
     useOrgFormatSync();
     useReportingCurrencySync();
     const tree = createElement(
       OverlayHostContext.Provider,
       { value: props.overlayHost },
-      // react-query provider — an overlay bundle has its own react-query module
-      // instance, so the host's app-wide client is invisible across the bundle
-      // boundary; it needs its own provider exactly as each page gets one.
+      // react-query provider. Normally re-providing the host's own client, which
+      // is a no-op for the subtree and deliberate: the tree shape stays identical
+      // whichever client `useSurfaceQueryClient` returned, so the fallback path is
+      // not a second code path through the renderer.
       createElement(
         QueryClientProvider,
         { client: queryClient },
@@ -1217,6 +1252,6 @@ function withActiveNavHref(input, activeNavHref) {
   return { ...input, activeNavHref };
 }
 
-export { BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HOST_CHROME_CONTRACT_VERSION, HostSidebarActionsContext, LIST_CURRENCIES_TOOL, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, OverlayHostContext, PluginPortalScope, PluginStyleScope, REPORTING_CURRENCY_TOOL2 as REPORTING_CURRENCY_TOOL, SIDEBAR_MODE, SurfaceBaseContext, TemplateContext, TypedMcpService, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, isHostChromeCompatible, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, reportHostChromeDiagnostic, resolveActiveNavHref, resolveSurfaceBase, setHostChromeDiagnosticSink, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useHostSidebarActions, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView, withActiveNavHref };
+export { BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HOST_CHROME_CONTRACT_VERSION, HostSidebarActionsContext, LIST_CURRENCIES_TOOL, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, OverlayHostContext, PluginPortalScope, PluginStyleScope, REPORTING_CURRENCY_TOOL2 as REPORTING_CURRENCY_TOOL, SIDEBAR_MODE, SurfaceBaseContext, TemplateContext, TypedMcpService, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, isHostChromeCompatible, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, reportHostChromeDiagnostic, resolveActiveNavHref, resolveSurfaceBase, setHostChromeDiagnosticSink, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useHostSidebarActions, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceQueryClient, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView, withActiveNavHref };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map