@ethisyscore/extension-runtime 1.135.0 → 1.137.0

package/dist/plugin/index.d.cts

@@ -1,13 +1,178 @@
-import { M as McpTransport } from '../bridge-envelopes-M5a42rAy.cjs';
-export { U as UploadDocumentMeta, f as UploadDocumentResult } from '../bridge-envelopes-M5a42rAy.cjs';
+import { M as McpTransport, h as UploadToStorageResult } from '../bridge-envelopes-BcKu-nQm.cjs';
+export { U as UploadDocumentMeta, f as UploadDocumentResult, g as UploadToStorageMeta } from '../bridge-envelopes-BcKu-nQm.cjs';
+import { b as McpToolError, a as McpErrorCode } from '../mcp-error-CCZQd8Xl.cjs';
+export { M as MCP_ERROR_CODES, c as classifyHostError, d as classifyHostResponse, i as isMcpErrorCode, e as isMcpToolError, f as isRetryableMcpErrorCode, m as mcpErrorCodeFromHttpStatus } from '../mcp-error-CCZQd8Xl.cjs';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { SduiNode, RenderMode } from '@ethisyscore/protocol';
 export { PagedResponse, PaginatedEnvelope } from '@ethisyscore/protocol';
 import { RemoteConnection } from '@remote-dom/core';
-import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload } from '../bridge-client-D9EYFq1l.cjs';
-export { A as A11yPayload, B as BridgePortShim, D as DensityPayload, N as NavPayload, S as SessionTokenPayload, c as createPortBridgeClient } from '../bridge-client-D9EYFq1l.cjs';
-export { M as MCP_ERROR_CODES, a as McpErrorCode, b as McpToolError, c as classifyHostError, d as classifyHostResponse, i as isMcpErrorCode, e as isMcpToolError, f as isRetryableMcpErrorCode, m as mcpErrorCodeFromHttpStatus } from '../mcp-error-CCZQd8Xl.cjs';
+import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload } from '../bridge-client-DkogtCvn.cjs';
+export { A as A11yPayload, B as BridgePortShim, D as DensityPayload, N as NavPayload, S as SessionTokenPayload, c as createPortBridgeClient } from '../bridge-client-DkogtCvn.cjs';
+
+/**
+ * Browser file → the calling app's OWN plugin storage.
+ *
+ * The plugin-facing half of the `uploadToStorage` request kind: client-side prefix validation that
+ * mirrors the kernel's `PluginStorageUploadPath.TryNormalizePrefix`, a typed error that keeps the
+ * server's status and message, and {@link uploadFileToPluginStorage}, the one function every
+ * plugin surface (and `@ethisyscore/plugin-ui`'s `useUploadToStorage`) calls.
+ *
+ * Browser uploads go through `uploadToStorage` into plugin storage; never base64 a file through a
+ * tool call.
+ *
+ * The client checks are there to fail fast, before a 30 MB file is read into memory. The server
+ * re-runs every one of them and is authoritative.
+ */
+
+/** The kernel's hard cap on one upload, in bytes (`UploadExtensionDocumentStream.MaxUploadBytes`). */
+declare const PLUGIN_STORAGE_UPLOAD_MAX_BYTES: number;
+/**
+ * Maximum length of a normalised prefix: 128 (the path column HR and Legal record into) less the
+ * `/`, the 32-character GUID leaf and an 11-character extension. `governance/{guid}/{guid}` is
+ * exactly 84.
+ */
+declare const PLUGIN_STORAGE_PREFIX_MAX_LENGTH = 84;
+/** Maximum length of a path the server returns. */
+declare const PLUGIN_STORAGE_PATH_MAX_LENGTH = 128;
+/**
+ * Why a plugin-storage upload failed. Each value is something a caller can act on differently;
+ * `status` on the error carries the exact HTTP status when the host supplied one.
+ *
+ * - `invalid_prefix`: the prefix broke the rules (client-side check, or a server 400).
+ * - `too_large`: over the 30 MB cap (client-side check, or a server 413).
+ * - `quota_exceeded`: the app's storage quota would be exceeded (507).
+ * - `unauthorized`: no capability-token caller or no session (401).
+ * - `forbidden`: token and session disagree, or the app owns no storage namespace (403).
+ * - `unsupported_type`: the file's extension is not on the allow-list, or the declared type does
+ *   not match it (client-side check, or a server 415).
+ * - `timeout`: the upload was too slow or missed the server's deadline (408). Retryable.
+ * - `busy`: the app's storage lock is held, or the server's upload slots are full (503). Retryable.
+ * - `storage_failed`: the store refused the write (500).
+ * - `unsupported`: the active transport has no `uploadToStorage`, i.e. the host predates it.
+ * - `aborted`: the caller's signal fired.
+ * - `unknown`: anything else.
+ */
+type PluginStorageUploadErrorReason = "invalid_prefix" | "too_large" | "quota_exceeded" | "unauthorized" | "forbidden" | "unsupported_type" | "timeout" | "busy" | "storage_failed" | "unsupported" | "aborted" | "unknown";
+/**
+ * A failed plugin-storage upload. `message` is the server's own `{ error }` text when the server
+ * answered, otherwise the client-side reason.
+ *
+ * Extends {@link McpToolError}, so `isMcpToolError` and `code` keep working for code that handles
+ * every MCP failure the same way. Prefer {@link isPluginStorageUploadError} over `instanceof`: the
+ * error can be built in one bundle and inspected in another.
+ */
+declare class PluginStorageUploadError extends McpToolError {
+    /** What went wrong, in terms a caller branches on. */
+    readonly reason: PluginStorageUploadErrorReason;
+    /** HTTP status from the server, when the host surfaced one. */
+    readonly status?: number;
+    /** Structural marker for {@link isPluginStorageUploadError}. */
+    readonly isPluginStorageUploadError: true;
+    constructor(message: string, reason: PluginStorageUploadErrorReason, options?: {
+        status?: number;
+        code?: McpErrorCode;
+    });
+}
+/** True when `value` is a {@link PluginStorageUploadError}, including one from another bundle. */
+declare function isPluginStorageUploadError(value: unknown): value is PluginStorageUploadError;
+/** Maps a status from `extensions/storage/upload-stream` onto a {@link PluginStorageUploadErrorReason}. */
+declare function pluginStorageUploadReasonFromStatus(status: number): PluginStorageUploadErrorReason;
+/**
+ * Normalises any failure from a transport's `uploadToStorage` into a {@link PluginStorageUploadError},
+ * keeping the server's message.
+ *
+ * Precedence: an existing `PluginStorageUploadError` passes through; then a numeric `status` /
+ * `statusCode` (what a host HTTP client carries); then an `AbortError`; then the MCP error `code`
+ * from the bridge; then `unknown`. Never inferred from the message text.
+ */
+declare function toPluginStorageUploadError(err: unknown): PluginStorageUploadError;
+/** Outcome of {@link validatePluginStoragePrefix}. */
+type PluginStoragePrefixValidation = {
+    readonly ok: true;
+    readonly prefix: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Validates a storage prefix with the kernel's rules (`PluginStorageUploadPath.TryNormalizePrefix`
+ * in CoreConnect-Api, Application.Extensions/Storage). A malformed prefix is REFUSED, never
+ * repaired, and an accepted one is returned exactly as given, so a caller that checks the
+ * returned path with `path.startsWith(prefix + "/")` always matches. In the server's order:
+ *
+ * - required (not empty or whitespace);
+ * - at most {@link PLUGIN_STORAGE_PREFIX_MAX_LENGTH} characters, measured on the raw value;
+ * - only `[A-Za-z0-9_-]` and `/`, so `%` (any encoding), `.`/`..`, `\`, whitespace and every
+ *   other character are refused;
+ * - every `/`-separated segment non-empty, which also refuses a leading or trailing `/` and `//`.
+ *
+ * The server's last check (its storage normaliser must be the identity on the prefix) cannot fail
+ * for a value that passed the rules above, so it has no client counterpart.
+ */
+declare function validatePluginStoragePrefix(raw: string | null | undefined): PluginStoragePrefixValidation;
+/**
+ * {@link validatePluginStoragePrefix}, throwing a `PluginStorageUploadError` with reason
+ * `invalid_prefix` instead of returning a result. Returns the prefix unchanged.
+ */
+declare function assertValidPluginStoragePrefix(raw: string): string;
+/**
+ * The file types a browser may upload into plugin storage, keyed by lower-case extension: the
+ * canonical type the server stores first, then the aliases browsers commonly declare for it.
+ *
+ * SOURCE OF TRUTH: `PluginStorageUploadContentTypes` in CoreConnect-Api
+ * (src/application/CoreConnect.Application.Extensions/Storage/PluginStorageUploadContentTypes.cs).
+ * This copy only lets the client fail fast with `unsupported_type`; the server decides. Keep it in
+ * step with the server. Passive formats only: never HTML, SVG, XML or JavaScript.
+ */
+declare const PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES: Readonly<Record<string, readonly [canonical: string, ...aliases: string[]]>>;
+/**
+ * The kernel's `PluginStorageUploadPath.SafeExtension`: the lower-cased extension with its dot,
+ * kept only when it is 1 to 10 ASCII letters or digits; otherwise empty.
+ */
+declare function pluginStorageSafeExtension(fileName: string | null | undefined): string;
+/** Outcome of {@link resolvePluginStorageContentType}. */
+type PluginStorageContentTypeResolution = {
+    readonly ok: true;
+    readonly contentType: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Mirrors `PluginStorageUploadContentTypes.TryResolve`: the extension decides. A file name with no
+ * allow-listed extension is refused. A declared type is accepted when it is that extension's
+ * canonical type or a listed alias (case-insensitive, parameters ignored); none, or
+ * `application/octet-stream`, means "use the extension's type". Resolves to the CANONICAL type the
+ * server will store.
+ */
+declare function resolvePluginStorageContentType(fileName: string | null | undefined, declaredContentType?: string | null): PluginStorageContentTypeResolution;
+/** Options for {@link uploadFileToPluginStorage}. */
+interface UploadToStorageOptions {
+    /** Folder inside the app's own storage namespace, e.g. `cvs` or `governance/{docId}/{versionId}`. */
+    pathPrefix: string;
+    /** File name. Defaults to the `File`'s name, else `upload.bin`. Required in practice for an `ArrayBuffer`. */
+    fileName?: string;
+    /** MIME type. Defaults to the `Blob`'s type, else `application/octet-stream` (the server then infers from the extension). */
+    contentType?: string;
+    /** Client-side size ceiling, never above the server's. Defaults to {@link PLUGIN_STORAGE_UPLOAD_MAX_BYTES}. */
+    maxSizeBytes?: number;
+    /** Cancels the upload. */
+    signal?: AbortSignal;
+}
+/**
+ * Upload a browser file into the calling app's own plugin storage and resolve the server-chosen
+ * `path` that the app's backend reads with `IPluginStorage`.
+ *
+ * Validates the prefix, the size and the file type (against the server's allow-list) before
+ * reading the file, then hands the bytes to the
+ * transport's `uploadToStorage`. Every failure (client-side or server) rejects with a
+ * {@link PluginStorageUploadError} whose `reason` is safe to branch on and whose `message` is the
+ * server's when the server answered.
+ *
+ * An `ArrayBuffer` argument is transferred to the host and detached; pass a copy to keep it.
+ */
+declare function uploadFileToPluginStorage(transport: McpTransport, file: File | Blob | ArrayBuffer, options: UploadToStorageOptions): Promise<UploadToStorageResult>;
 
 /**
  * A single client-push event delivered from the host to a plugin surface. The host
@@ -797,4 +962,4 @@ interface UseAuthResult {
  */
 declare function useAuth(transport: McpTransport): UseAuthResult;
 
-export { BridgeClientContext, type ClientPushChannel, ClientPushContext, type ClientPushEvent, type ClientPushSubscribeOptions, type CreatePortMcpTransportOptions, type CreateRemoteRootOptions, type DeclarativePluginConfig, type EthisysPluginConfig, ExtensionRuntimeProvider, type ExtensionRuntimeProviderProps, type HostIdentity, HostIdentityContext, type HostIdentityUser, type HostPermission, type ItemsResponse, LocalePayload, McpTransport, PluginRealtimeContext, type PluginRealtimeSource, PortBridgeClient, type PortShim, type RemoteRoot, ThemePayload, type UseAuthResult, type UseClientPushSubscriptionOptions, type UseFrontendSessionTokenResult, type UseMcpQueryOptions, type UseMcpQueryResult, type UseMcpResourceOptions, type UseMcpResourceResult, type UseMcpToolOptions, type UseMcpToolResult, type UseModuleQueryOptions, type UseModuleQueryResult, type UseModuleToolOptions, type UseModuleToolResult, createPortMcpTransport, createRemoteRoot, decodeJwtPayload, defineDeclarativePlugin, defineEthisysPlugin, unwrapItems, useAuth, useBridgeClient, useBridgeLocale, useBridgeTheme, useClientPushSubscription, useExtensionRuntimeTransport, useFrontendSessionToken, useHostIdentity, useMcpQuery, useMcpResource, useMcpTool, useModuleQuery, useModuleTool, useOptionalExtensionRuntimeTransport, usePluginRealtimeSource };
+export { BridgeClientContext, type ClientPushChannel, ClientPushContext, type ClientPushEvent, type ClientPushSubscribeOptions, type CreatePortMcpTransportOptions, type CreateRemoteRootOptions, type DeclarativePluginConfig, type EthisysPluginConfig, ExtensionRuntimeProvider, type ExtensionRuntimeProviderProps, type HostIdentity, HostIdentityContext, type HostIdentityUser, type HostPermission, type ItemsResponse, LocalePayload, McpErrorCode, McpToolError, McpTransport, PLUGIN_STORAGE_PATH_MAX_LENGTH, PLUGIN_STORAGE_PREFIX_MAX_LENGTH, PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES, PLUGIN_STORAGE_UPLOAD_MAX_BYTES, PluginRealtimeContext, type PluginRealtimeSource, type PluginStorageContentTypeResolution, type PluginStoragePrefixValidation, PluginStorageUploadError, type PluginStorageUploadErrorReason, PortBridgeClient, type PortShim, type RemoteRoot, ThemePayload, type UploadToStorageOptions, UploadToStorageResult, type UseAuthResult, type UseClientPushSubscriptionOptions, type UseFrontendSessionTokenResult, type UseMcpQueryOptions, type UseMcpQueryResult, type UseMcpResourceOptions, type UseMcpResourceResult, type UseMcpToolOptions, type UseMcpToolResult, type UseModuleQueryOptions, type UseModuleQueryResult, type UseModuleToolOptions, type UseModuleToolResult, assertValidPluginStoragePrefix, createPortMcpTransport, createRemoteRoot, decodeJwtPayload, defineDeclarativePlugin, defineEthisysPlugin, isPluginStorageUploadError, pluginStorageSafeExtension, pluginStorageUploadReasonFromStatus, resolvePluginStorageContentType, toPluginStorageUploadError, unwrapItems, uploadFileToPluginStorage, useAuth, useBridgeClient, useBridgeLocale, useBridgeTheme, useClientPushSubscription, useExtensionRuntimeTransport, useFrontendSessionToken, useHostIdentity, useMcpQuery, useMcpResource, useMcpTool, useModuleQuery, useModuleTool, useOptionalExtensionRuntimeTransport, usePluginRealtimeSource, validatePluginStoragePrefix };

package/dist/plugin/index.d.ts

@@ -1,13 +1,178 @@
-import { M as McpTransport } from '../bridge-envelopes-M5a42rAy.js';
-export { U as UploadDocumentMeta, f as UploadDocumentResult } from '../bridge-envelopes-M5a42rAy.js';
+import { M as McpTransport, h as UploadToStorageResult } from '../bridge-envelopes-BcKu-nQm.js';
+export { U as UploadDocumentMeta, f as UploadDocumentResult, g as UploadToStorageMeta } from '../bridge-envelopes-BcKu-nQm.js';
+import { b as McpToolError, a as McpErrorCode } from '../mcp-error-CCZQd8Xl.js';
+export { M as MCP_ERROR_CODES, c as classifyHostError, d as classifyHostResponse, i as isMcpErrorCode, e as isMcpToolError, f as isRetryableMcpErrorCode, m as mcpErrorCodeFromHttpStatus } from '../mcp-error-CCZQd8Xl.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { SduiNode, RenderMode } from '@ethisyscore/protocol';
 export { PagedResponse, PaginatedEnvelope } from '@ethisyscore/protocol';
 import { RemoteConnection } from '@remote-dom/core';
-import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload } from '../bridge-client-RJOl8WlU.js';
-export { A as A11yPayload, B as BridgePortShim, D as DensityPayload, N as NavPayload, S as SessionTokenPayload, c as createPortBridgeClient } from '../bridge-client-RJOl8WlU.js';
-export { M as MCP_ERROR_CODES, a as McpErrorCode, b as McpToolError, c as classifyHostError, d as classifyHostResponse, i as isMcpErrorCode, e as isMcpToolError, f as isRetryableMcpErrorCode, m as mcpErrorCodeFromHttpStatus } from '../mcp-error-CCZQd8Xl.js';
+import { P as PortBridgeClient, T as ThemePayload, L as LocalePayload } from '../bridge-client-CkxYcZcm.js';
+export { A as A11yPayload, B as BridgePortShim, D as DensityPayload, N as NavPayload, S as SessionTokenPayload, c as createPortBridgeClient } from '../bridge-client-CkxYcZcm.js';
+
+/**
+ * Browser file → the calling app's OWN plugin storage.
+ *
+ * The plugin-facing half of the `uploadToStorage` request kind: client-side prefix validation that
+ * mirrors the kernel's `PluginStorageUploadPath.TryNormalizePrefix`, a typed error that keeps the
+ * server's status and message, and {@link uploadFileToPluginStorage}, the one function every
+ * plugin surface (and `@ethisyscore/plugin-ui`'s `useUploadToStorage`) calls.
+ *
+ * Browser uploads go through `uploadToStorage` into plugin storage; never base64 a file through a
+ * tool call.
+ *
+ * The client checks are there to fail fast, before a 30 MB file is read into memory. The server
+ * re-runs every one of them and is authoritative.
+ */
+
+/** The kernel's hard cap on one upload, in bytes (`UploadExtensionDocumentStream.MaxUploadBytes`). */
+declare const PLUGIN_STORAGE_UPLOAD_MAX_BYTES: number;
+/**
+ * Maximum length of a normalised prefix: 128 (the path column HR and Legal record into) less the
+ * `/`, the 32-character GUID leaf and an 11-character extension. `governance/{guid}/{guid}` is
+ * exactly 84.
+ */
+declare const PLUGIN_STORAGE_PREFIX_MAX_LENGTH = 84;
+/** Maximum length of a path the server returns. */
+declare const PLUGIN_STORAGE_PATH_MAX_LENGTH = 128;
+/**
+ * Why a plugin-storage upload failed. Each value is something a caller can act on differently;
+ * `status` on the error carries the exact HTTP status when the host supplied one.
+ *
+ * - `invalid_prefix`: the prefix broke the rules (client-side check, or a server 400).
+ * - `too_large`: over the 30 MB cap (client-side check, or a server 413).
+ * - `quota_exceeded`: the app's storage quota would be exceeded (507).
+ * - `unauthorized`: no capability-token caller or no session (401).
+ * - `forbidden`: token and session disagree, or the app owns no storage namespace (403).
+ * - `unsupported_type`: the file's extension is not on the allow-list, or the declared type does
+ *   not match it (client-side check, or a server 415).
+ * - `timeout`: the upload was too slow or missed the server's deadline (408). Retryable.
+ * - `busy`: the app's storage lock is held, or the server's upload slots are full (503). Retryable.
+ * - `storage_failed`: the store refused the write (500).
+ * - `unsupported`: the active transport has no `uploadToStorage`, i.e. the host predates it.
+ * - `aborted`: the caller's signal fired.
+ * - `unknown`: anything else.
+ */
+type PluginStorageUploadErrorReason = "invalid_prefix" | "too_large" | "quota_exceeded" | "unauthorized" | "forbidden" | "unsupported_type" | "timeout" | "busy" | "storage_failed" | "unsupported" | "aborted" | "unknown";
+/**
+ * A failed plugin-storage upload. `message` is the server's own `{ error }` text when the server
+ * answered, otherwise the client-side reason.
+ *
+ * Extends {@link McpToolError}, so `isMcpToolError` and `code` keep working for code that handles
+ * every MCP failure the same way. Prefer {@link isPluginStorageUploadError} over `instanceof`: the
+ * error can be built in one bundle and inspected in another.
+ */
+declare class PluginStorageUploadError extends McpToolError {
+    /** What went wrong, in terms a caller branches on. */
+    readonly reason: PluginStorageUploadErrorReason;
+    /** HTTP status from the server, when the host surfaced one. */
+    readonly status?: number;
+    /** Structural marker for {@link isPluginStorageUploadError}. */
+    readonly isPluginStorageUploadError: true;
+    constructor(message: string, reason: PluginStorageUploadErrorReason, options?: {
+        status?: number;
+        code?: McpErrorCode;
+    });
+}
+/** True when `value` is a {@link PluginStorageUploadError}, including one from another bundle. */
+declare function isPluginStorageUploadError(value: unknown): value is PluginStorageUploadError;
+/** Maps a status from `extensions/storage/upload-stream` onto a {@link PluginStorageUploadErrorReason}. */
+declare function pluginStorageUploadReasonFromStatus(status: number): PluginStorageUploadErrorReason;
+/**
+ * Normalises any failure from a transport's `uploadToStorage` into a {@link PluginStorageUploadError},
+ * keeping the server's message.
+ *
+ * Precedence: an existing `PluginStorageUploadError` passes through; then a numeric `status` /
+ * `statusCode` (what a host HTTP client carries); then an `AbortError`; then the MCP error `code`
+ * from the bridge; then `unknown`. Never inferred from the message text.
+ */
+declare function toPluginStorageUploadError(err: unknown): PluginStorageUploadError;
+/** Outcome of {@link validatePluginStoragePrefix}. */
+type PluginStoragePrefixValidation = {
+    readonly ok: true;
+    readonly prefix: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Validates a storage prefix with the kernel's rules (`PluginStorageUploadPath.TryNormalizePrefix`
+ * in CoreConnect-Api, Application.Extensions/Storage). A malformed prefix is REFUSED, never
+ * repaired, and an accepted one is returned exactly as given, so a caller that checks the
+ * returned path with `path.startsWith(prefix + "/")` always matches. In the server's order:
+ *
+ * - required (not empty or whitespace);
+ * - at most {@link PLUGIN_STORAGE_PREFIX_MAX_LENGTH} characters, measured on the raw value;
+ * - only `[A-Za-z0-9_-]` and `/`, so `%` (any encoding), `.`/`..`, `\`, whitespace and every
+ *   other character are refused;
+ * - every `/`-separated segment non-empty, which also refuses a leading or trailing `/` and `//`.
+ *
+ * The server's last check (its storage normaliser must be the identity on the prefix) cannot fail
+ * for a value that passed the rules above, so it has no client counterpart.
+ */
+declare function validatePluginStoragePrefix(raw: string | null | undefined): PluginStoragePrefixValidation;
+/**
+ * {@link validatePluginStoragePrefix}, throwing a `PluginStorageUploadError` with reason
+ * `invalid_prefix` instead of returning a result. Returns the prefix unchanged.
+ */
+declare function assertValidPluginStoragePrefix(raw: string): string;
+/**
+ * The file types a browser may upload into plugin storage, keyed by lower-case extension: the
+ * canonical type the server stores first, then the aliases browsers commonly declare for it.
+ *
+ * SOURCE OF TRUTH: `PluginStorageUploadContentTypes` in CoreConnect-Api
+ * (src/application/CoreConnect.Application.Extensions/Storage/PluginStorageUploadContentTypes.cs).
+ * This copy only lets the client fail fast with `unsupported_type`; the server decides. Keep it in
+ * step with the server. Passive formats only: never HTML, SVG, XML or JavaScript.
+ */
+declare const PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES: Readonly<Record<string, readonly [canonical: string, ...aliases: string[]]>>;
+/**
+ * The kernel's `PluginStorageUploadPath.SafeExtension`: the lower-cased extension with its dot,
+ * kept only when it is 1 to 10 ASCII letters or digits; otherwise empty.
+ */
+declare function pluginStorageSafeExtension(fileName: string | null | undefined): string;
+/** Outcome of {@link resolvePluginStorageContentType}. */
+type PluginStorageContentTypeResolution = {
+    readonly ok: true;
+    readonly contentType: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Mirrors `PluginStorageUploadContentTypes.TryResolve`: the extension decides. A file name with no
+ * allow-listed extension is refused. A declared type is accepted when it is that extension's
+ * canonical type or a listed alias (case-insensitive, parameters ignored); none, or
+ * `application/octet-stream`, means "use the extension's type". Resolves to the CANONICAL type the
+ * server will store.
+ */
+declare function resolvePluginStorageContentType(fileName: string | null | undefined, declaredContentType?: string | null): PluginStorageContentTypeResolution;
+/** Options for {@link uploadFileToPluginStorage}. */
+interface UploadToStorageOptions {
+    /** Folder inside the app's own storage namespace, e.g. `cvs` or `governance/{docId}/{versionId}`. */
+    pathPrefix: string;
+    /** File name. Defaults to the `File`'s name, else `upload.bin`. Required in practice for an `ArrayBuffer`. */
+    fileName?: string;
+    /** MIME type. Defaults to the `Blob`'s type, else `application/octet-stream` (the server then infers from the extension). */
+    contentType?: string;
+    /** Client-side size ceiling, never above the server's. Defaults to {@link PLUGIN_STORAGE_UPLOAD_MAX_BYTES}. */
+    maxSizeBytes?: number;
+    /** Cancels the upload. */
+    signal?: AbortSignal;
+}
+/**
+ * Upload a browser file into the calling app's own plugin storage and resolve the server-chosen
+ * `path` that the app's backend reads with `IPluginStorage`.
+ *
+ * Validates the prefix, the size and the file type (against the server's allow-list) before
+ * reading the file, then hands the bytes to the
+ * transport's `uploadToStorage`. Every failure (client-side or server) rejects with a
+ * {@link PluginStorageUploadError} whose `reason` is safe to branch on and whose `message` is the
+ * server's when the server answered.
+ *
+ * An `ArrayBuffer` argument is transferred to the host and detached; pass a copy to keep it.
+ */
+declare function uploadFileToPluginStorage(transport: McpTransport, file: File | Blob | ArrayBuffer, options: UploadToStorageOptions): Promise<UploadToStorageResult>;
 
 /**
  * A single client-push event delivered from the host to a plugin surface. The host
@@ -797,4 +962,4 @@ interface UseAuthResult {
  */
 declare function useAuth(transport: McpTransport): UseAuthResult;
 
-export { BridgeClientContext, type ClientPushChannel, ClientPushContext, type ClientPushEvent, type ClientPushSubscribeOptions, type CreatePortMcpTransportOptions, type CreateRemoteRootOptions, type DeclarativePluginConfig, type EthisysPluginConfig, ExtensionRuntimeProvider, type ExtensionRuntimeProviderProps, type HostIdentity, HostIdentityContext, type HostIdentityUser, type HostPermission, type ItemsResponse, LocalePayload, McpTransport, PluginRealtimeContext, type PluginRealtimeSource, PortBridgeClient, type PortShim, type RemoteRoot, ThemePayload, type UseAuthResult, type UseClientPushSubscriptionOptions, type UseFrontendSessionTokenResult, type UseMcpQueryOptions, type UseMcpQueryResult, type UseMcpResourceOptions, type UseMcpResourceResult, type UseMcpToolOptions, type UseMcpToolResult, type UseModuleQueryOptions, type UseModuleQueryResult, type UseModuleToolOptions, type UseModuleToolResult, createPortMcpTransport, createRemoteRoot, decodeJwtPayload, defineDeclarativePlugin, defineEthisysPlugin, unwrapItems, useAuth, useBridgeClient, useBridgeLocale, useBridgeTheme, useClientPushSubscription, useExtensionRuntimeTransport, useFrontendSessionToken, useHostIdentity, useMcpQuery, useMcpResource, useMcpTool, useModuleQuery, useModuleTool, useOptionalExtensionRuntimeTransport, usePluginRealtimeSource };
+export { BridgeClientContext, type ClientPushChannel, ClientPushContext, type ClientPushEvent, type ClientPushSubscribeOptions, type CreatePortMcpTransportOptions, type CreateRemoteRootOptions, type DeclarativePluginConfig, type EthisysPluginConfig, ExtensionRuntimeProvider, type ExtensionRuntimeProviderProps, type HostIdentity, HostIdentityContext, type HostIdentityUser, type HostPermission, type ItemsResponse, LocalePayload, McpErrorCode, McpToolError, McpTransport, PLUGIN_STORAGE_PATH_MAX_LENGTH, PLUGIN_STORAGE_PREFIX_MAX_LENGTH, PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES, PLUGIN_STORAGE_UPLOAD_MAX_BYTES, PluginRealtimeContext, type PluginRealtimeSource, type PluginStorageContentTypeResolution, type PluginStoragePrefixValidation, PluginStorageUploadError, type PluginStorageUploadErrorReason, PortBridgeClient, type PortShim, type RemoteRoot, ThemePayload, type UploadToStorageOptions, UploadToStorageResult, type UseAuthResult, type UseClientPushSubscriptionOptions, type UseFrontendSessionTokenResult, type UseMcpQueryOptions, type UseMcpQueryResult, type UseMcpResourceOptions, type UseMcpResourceResult, type UseMcpToolOptions, type UseMcpToolResult, type UseModuleQueryOptions, type UseModuleQueryResult, type UseModuleToolOptions, type UseModuleToolResult, assertValidPluginStoragePrefix, createPortMcpTransport, createRemoteRoot, decodeJwtPayload, defineDeclarativePlugin, defineEthisysPlugin, isPluginStorageUploadError, pluginStorageSafeExtension, pluginStorageUploadReasonFromStatus, resolvePluginStorageContentType, toPluginStorageUploadError, unwrapItems, uploadFileToPluginStorage, useAuth, useBridgeClient, useBridgeLocale, useBridgeTheme, useClientPushSubscription, useExtensionRuntimeTransport, useFrontendSessionToken, useHostIdentity, useMcpQuery, useMcpResource, useMcpTool, useModuleQuery, useModuleTool, useOptionalExtensionRuntimeTransport, usePluginRealtimeSource, validatePluginStoragePrefix };