@ethisyscore/plugin-ui 1.136.0 → 1.137.0

package/README.md

@@ -16,7 +16,7 @@ and the shared MUI component surface externalised to the host's instances.
 | Subpath | Key exports | Purpose |
 |---|---|---|
 | `.` | `createPortBridgeClient`, `BridgeClientContext` / `useBridgeClient`, `useBridgeTheme` / `useBridgeLocale`, `ExtensionRuntimeProvider`, `useMcpResource` / `useMcpTool` / `useMcpQuery` / `unwrapItems`, `useHostIdentity` / `useCurrentUser`, `definePlatformReactPage` / `emitNavigation` / `PlatformReactPageProps` | Bridge client + theme/locale context, brokered-MCP data hooks, host identity, and the base PlatformReact page contract |
-| `./platform-react` | `definePlatformReactPluginPage` / `createPluginPageDefiner`, `definePlatformReactPluginOverlay` / `useOverlayHost`, `useView` / `createUseView` / `ViewComponent` / `isComponent`, `BaseMcpService` / `useToolInvoker` / `useToolInvokerMap`, `useAuthenticatedQuery` / `useAuthenticatedQueries`, `injectPluginStyles` / `PluginStyleScope`, `createReactRouterShim`, `usePluginRealtime`, `useBackgroundOperation` / `useOperationsByParent` / `useLatestTerminalOperationByParent` / `hasKind`, `useMcpUpload`, `useManagedLifecycle` | The plugin authoring layer: page/overlay wrappers (react-query + manifest + style root), the static `useView` adapter pattern, the MCP service base + tool invokers, pre-authenticated react-query wrappers, scoped-style injection, router shim, realtime, following the plugin's own background operations, and file upload |
+| `./platform-react` | `definePlatformReactPluginPage` / `createPluginPageDefiner`, `definePlatformReactPluginOverlay` / `useOverlayHost`, `useView` / `createUseView` / `ViewComponent` / `isComponent`, `BaseMcpService` / `useToolInvoker` / `useToolInvokerMap`, `useAuthenticatedQuery` / `useAuthenticatedQueries`, `injectPluginStyles` / `PluginStyleScope`, `createReactRouterShim`, `usePluginRealtime`, `useBackgroundOperation` / `useOperationsByParent` / `useLatestTerminalOperationByParent` / `hasKind`, `useUploadToStorage` / `PluginStorageUploadError` / `isPluginStorageUploadError` / `validatePluginStoragePrefix`, `useMcpUpload` (legacy CORE storage), `useManagedLifecycle` | The plugin authoring layer: page/overlay wrappers (react-query + manifest + style root), the static `useView` adapter pattern, the MCP service base + tool invokers, pre-authenticated react-query wrappers, scoped-style injection, router shim, realtime, following the plugin's own background operations, and file upload |
 | `./icons` | `NextureIcons`, `IconMap`, 470+ `Ni*` icon components, `sizeHelper` / `strokeSizeHelper`, `IconName` / `IconSize` / `IconVariant` | The gogo-ui "nexture" SVG icon set with props types and size/stroke helpers |
 | `./components/ui` | `Button`, `Card`, `Dialog`, `Table`, `TextField`, `Select`, `Tabs`, `Typography`, `Grid`, `Stack`, `Menu`, `DebouncedSearchInput`, … | MUI component re-exports plus the Dialog scroll-lock wrapper and the debounced search field. These are **host externals** — never bundled; production builds bind them to the host's MUI instance |
 | `./components/layout` | `PageHeader` / `usePageHeader` / `withPageHeader` / `buildBreadcrumbs`, `FillGrid` / `FillGridItem` / `FillGap` / `FillSpan`, sidebar-action context (`SidebarActionProvider`, `useSidebarAction` / `useSidebarActions` / `useTriggerSidebarAction`), `RouteMeta` / `RouteMetaEntry` | Layout primitives (flex-wrap grid), the page-header layer + breadcrumb builder, and the sidebar-action context/provider |
@@ -52,6 +52,27 @@ service extending `BaseMcpService` and consume it through `useToolInvoker`. See
 the top-level README §"services over MCP" and the
 [FE migration playbook](../../docs/app-migration/fe-migration-playbook.md).
 
+### Uploading a browser file
+
+Browser uploads go through `useUploadToStorage` into the app's own plugin storage. Never base64 a file through a tool call.
+
+```tsx
+import { useUploadToStorage, isPluginStorageUploadError } from "@ethisyscore/plugin-ui/platform-react";
+
+const { upload, loading, error } = useUploadToStorage();
+
+async function onFile(file: File) {
+  try {
+    const { path } = await upload(file, { pathPrefix: "cvs" });
+    await recordCv({ path }); // the app's own command; the backend reads `path` via IPluginStorage
+  } catch (err) {
+    if (isPluginStorageUploadError(err) && err.reason === "quota_exceeded") { /* ... */ }
+  }
+}
+```
+
+The prefix is one or more `/`-separated `[A-Za-z0-9_-]` segments, at most 84 characters, with no leading or trailing `/`. It is refused, never repaired. Files are capped at 30 MB, and only allow-listed passive types (`PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES`) are accepted. See [CAPABILITIES.md](../../CAPABILITIES.md#browser-file-uploads) for the full rules and the error reasons.
+
 ## Build and test
 
 ```bash

package/dist/platform-react/index.cjs

@@ -985,6 +985,63 @@ function useMcpUpload(opts) {
   );
   return { upload, progress, loading, error };
 }
+function useUploadToStorage(opts) {
+  const transport = extensionRuntime.useExtensionRuntimeTransport(opts?.transport);
+  const maxSizeBytes = opts?.maxSizeBytes;
+  const [progress, setProgress] = react.useState(0);
+  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 upload = react.useCallback(
+    async (file, target) => {
+      const controller = new AbortController();
+      controllerRef.current?.abort();
+      controllerRef.current = controller;
+      const applyState = (fn) => {
+        if (mountedRef.current && !controller.signal.aborted) {
+          fn();
+        }
+      };
+      applyState(() => {
+        setLoading(true);
+        setError(void 0);
+        setProgress(0);
+      });
+      try {
+        const result = await extensionRuntime.uploadFileToPluginStorage(transport, file, {
+          pathPrefix: target.pathPrefix,
+          fileName: target.fileName,
+          contentType: target.contentType,
+          maxSizeBytes,
+          signal: controller.signal
+        });
+        applyState(() => {
+          setProgress(1);
+          setLoading(false);
+        });
+        return result;
+      } catch (err) {
+        const typed = extensionRuntime.toPluginStorageUploadError(err);
+        applyState(() => {
+          setError(typed);
+          setLoading(false);
+          setProgress(0);
+        });
+        throw typed;
+      }
+    },
+    [transport, maxSizeBytes]
+  );
+  return { upload, progress, loading, error };
+}
 var OVERLAY_HOST_CONTRACT_VERSION = "1.0.0";
 var OverlayHostContext = react.createContext(null);
 function useOverlayHost() {
@@ -1414,6 +1471,26 @@ function withActiveNavHref(input, activeNavHref) {
   return { ...input, activeNavHref };
 }
 
+Object.defineProperty(exports, "PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES", {
+  enumerable: true,
+  get: function () { return extensionRuntime.PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES; }
+});
+Object.defineProperty(exports, "PluginStorageUploadError", {
+  enumerable: true,
+  get: function () { return extensionRuntime.PluginStorageUploadError; }
+});
+Object.defineProperty(exports, "isPluginStorageUploadError", {
+  enumerable: true,
+  get: function () { return extensionRuntime.isPluginStorageUploadError; }
+});
+Object.defineProperty(exports, "resolvePluginStorageContentType", {
+  enumerable: true,
+  get: function () { return extensionRuntime.resolvePluginStorageContentType; }
+});
+Object.defineProperty(exports, "validatePluginStoragePrefix", {
+  enumerable: true,
+  get: function () { return extensionRuntime.validatePluginStoragePrefix; }
+});
 exports.BaseMcpService = BaseMcpService;
 exports.DEFAULT_MAX_UPLOAD_BYTES = DEFAULT_MAX_UPLOAD_BYTES;
 exports.EHX_PLUGIN_PORTAL_ATTR = EHX_PLUGIN_PORTAL_ATTR;
@@ -1480,6 +1557,7 @@ exports.useSurfaceUrl = useSurfaceUrl;
 exports.useToolInvoker = useToolInvoker;
 exports.useToolInvokerMap = useToolInvokerMap;
 exports.useTypedToolInvokerMap = useTypedToolInvokerMap;
+exports.useUploadToStorage = useUploadToStorage;
 exports.useView = useView;
 exports.withActiveNavHref = withActiveNavHref;
 //# sourceMappingURL=index.cjs.map