@floegence/redevplugin-ui 3.0.24 → 3.0.25

package/dist/platform.d.ts

@@ -1,6 +1,6 @@
 import { type FetchLike } from "./http.js";
 import type { components } from "./openapi.gen.js";
-import { type PluginConfirmationHandler, type PluginSurfaceHost, type PluginSurfaceContext, type PluginSurfaceOpeningProgress, type PluginSurfaceInteractionEvent, type PluginSurfaceReloadLimiter, type PluginSurfaceSlot, type PluginMethodResult, type ReDevPluginSurfaceTransport } from "./surface.js";
+import { type PluginConfirmationHandler, type PluginSurfaceHost, type PluginSurfaceContext, type PluginSurfaceOpeningProgress, type PluginSurfaceInteractionEvent, type PluginSurfaceFileExportHandler, type PluginSurfaceReloadLimiter, type PluginSurfaceSlot, type PluginMethodResult, type ReDevPluginSurfaceTransport } from "./surface.js";
 import { type PluginSurfaceScope } from "./surface-scope.js";
 export type PluginPlatformClientOptions = {
     fetch?: FetchLike;
@@ -46,6 +46,7 @@ export type PluginOpenSurfaceInSlotOptions = PluginRequestOptions & {
     confirm?: PluginConfirmationHandler;
     onOpeningProgress?: (progress: PluginSurfaceOpeningProgress) => void;
     onInteraction?: (event: PluginSurfaceInteractionEvent) => void;
+    onFileExport?: PluginSurfaceFileExportHandler;
     onError?: (error: import("./errors.js").PluginBridgeError) => void;
     surfaceContext?: PluginSurfaceContext;
 };

package/dist/plugin.d.ts

@@ -2,5 +2,5 @@ export { PluginBridgeClient } from "./surface.js";
 export { PluginBridgeError } from "./errors.js";
 export { pluginAPIMajor } from "./contracts.gen.js";
 export { callCapabilityOperation, callCapabilityStream, callCapabilitySync, isCapabilityBusinessError, } from "./capability-client.js";
-export type { BridgeLifecycleEvent, MessagePortLike, PluginBridgeClientOptions, PluginBridgeRequestOptions, PluginCanvasAccessibilityState, PluginCanvasInputEvent, PluginCanvasKeyEvent, PluginCanvasPointerEvent, PluginCanvasWheelEvent, PluginCanvasResizeEvent, PluginCanvasSurface, PluginSurfaceKeyboardBinding, PluginSurfaceKeyboardEvent, PluginSurfaceKeyboardTargetKind, PluginJSONObject, PluginJSONValue, PluginMethodResult, PluginExecutionFailureCode, PluginExecutionSnapshot, PluginExecutionProgress, PluginExecutionEvent, PluginExecutionEventList, PluginSurfaceContext, PluginUIActionEvent, PluginUIAttributeValue, PluginUIElementVNode, PluginUIPatchOperation, PluginUIVNode, } from "./surface.js";
+export type { BridgeLifecycleEvent, MessagePortLike, PluginBridgeClientOptions, PluginBridgeRequestOptions, PluginCanvasAccessibilityState, PluginCanvasInputEvent, PluginCanvasKeyEvent, PluginCanvasPointerEvent, PluginCanvasWheelEvent, PluginCanvasResizeEvent, PluginCanvasSurface, PluginFileExportRequest, PluginSurfaceKeyboardBinding, PluginSurfaceKeyboardEvent, PluginSurfaceKeyboardTargetKind, PluginJSONObject, PluginJSONValue, PluginMethodResult, PluginExecutionFailureCode, PluginExecutionSnapshot, PluginExecutionProgress, PluginExecutionEvent, PluginExecutionEventList, PluginSurfaceContext, PluginSurfaceFileExportMediaType, PluginUIActionEvent, PluginUIAttributeValue, PluginUIElementVNode, PluginUIPatchOperation, PluginUIVNode, } from "./surface.js";
 export type { PluginCapabilitySchema, PluginCapabilityEffect, PluginCapabilityOperationContract, PluginCapabilityStreamContract, PluginCapabilitySyncContract, PluginCapabilityStreamEvent, PluginCapabilityStreamReadResult, PluginExecution, PluginExecutionTerminalStatus, PluginExecutionWaitOptions, PluginStream, } from "./capability-client.js";

package/dist/surface.d.ts

@@ -101,6 +101,19 @@ export type PluginCanvasSurface = {
     cssHeight: number;
     devicePixelRatio: number;
 };
+export declare const pluginSurfaceFileExportMaxBytes: number;
+export declare const pluginSurfaceFileExportActionWindowMs = 30000;
+export declare const pluginSurfaceFileExportMediaTypes: readonly ["image/png", "image/jpeg", "image/webp", "image/svg+xml", "text/plain"];
+export type PluginSurfaceFileExportMediaType = (typeof pluginSurfaceFileExportMediaTypes)[number];
+export type PluginFileExportRequest = {
+    fileName: string;
+    mediaType: PluginSurfaceFileExportMediaType;
+    bytes: Uint8Array;
+};
+export type PluginSurfaceFileExport = Readonly<PluginFileExportRequest & {
+    signal: AbortSignal;
+}>;
+export type PluginSurfaceFileExportHandler = (request: PluginSurfaceFileExport) => Promise<void> | void;
 export type PluginCanvasAccessibilityState = {
     label: string;
     description: string;
@@ -336,6 +349,7 @@ export declare class PluginBridgeClient {
     setKeyboardBindings(bindings: readonly PluginSurfaceKeyboardBinding[]): Promise<void>;
     onKeyboardInput(handler: (event: PluginSurfaceKeyboardEvent) => void): () => void;
     loadImageAsset(assetId: string): Promise<ImageBitmap>;
+    exportFile(request: PluginFileExportRequest, options?: PluginBridgeRequestOptions): Promise<void>;
     onAction(action: string, handler: (event: PluginUIActionEvent) => void): () => void;
     onCanvasInput(canvasId: string, handler: (event: PluginCanvasInputEvent) => void): () => void;
     onLifecycle(handler: (event: BridgeLifecycleEvent) => Promise<void> | void): () => void;
@@ -483,6 +497,7 @@ export type PluginSurfaceHostOptions = {
     confirm?: PluginConfirmationHandler;
     onOpeningProgress?: (progress: PluginSurfaceOpeningProgress) => void;
     onInteraction?: (event: PluginSurfaceInteractionEvent) => void;
+    onFileExport?: PluginSurfaceFileExportHandler;
     onError?: (error: PluginBridgeError) => void;
     surfaceContext?: PluginSurfaceContext;
 };

package/dist/surface.js

@@ -7,6 +7,15 @@ import { PluginUIReconcileError, reconcileValidatedPluginUITrees, validatePlugin
 export const opaqueSurfaceDocumentSchemaVersion = "redevplugin.opaque_surface_document.v3";
 export const pluginRiskPlanSchemaVersion = "redevplugin.capability.risk_plan.v1";
 export const pluginSurfaceContextSchemaVersion = "redevplugin.surface_context.v1";
+export const pluginSurfaceFileExportMaxBytes = 16 * 1024 * 1024;
+export const pluginSurfaceFileExportActionWindowMs = 30_000;
+export const pluginSurfaceFileExportMediaTypes = [
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/svg+xml",
+    "text/plain",
+];
 const opaquePluginBridgeGlobalKey = "__redevpluginWorkerBridge";
 const maxPendingPluginBridgeRequests = 256;
 const maxPluginBridgeMessageBytes = opaqueSurfaceRenderLimits.max_message_bytes;
@@ -238,6 +247,23 @@ export class PluginBridgeClient {
             asset_id: assetId,
         }, { kind: "asset", identifier: assetId });
     }
+    exportFile(request, options = {}) {
+        this.#assertActive();
+        if (!validFileExportName(request?.fileName) || !validFileExportMediaType(request?.mediaType) ||
+            !(request?.bytes instanceof Uint8Array) || request.bytes.byteLength === 0 ||
+            request.bytes.byteLength > pluginSurfaceFileExportMaxBytes) {
+            throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin file export request is invalid");
+        }
+        const id = this.#requestID("file");
+        const content = Uint8Array.from(request.bytes).buffer;
+        return this.#dispatchRequest(id, {
+            type: "redevplugin.ui.file.export",
+            id,
+            file_name: request.fileName,
+            media_type: request.mediaType,
+            content,
+        }, { mutation: true, signal: options.signal }, [content]);
+    }
     onAction(action, handler) {
         this.#assertActive();
         if (!validActionID(action) || typeof handler !== "function") {
@@ -377,6 +403,9 @@ export class PluginBridgeClient {
         if (new TextEncoder().encode(JSON.stringify(normalizedMessage)).byteLength > maxPluginBridgeMessageBytes) {
             throw new PluginBridgeError("PLUGIN_JSON_LIMIT_EXCEEDED", "Plugin bridge request exceeds the message size limit");
         }
+        return this.#dispatchRequest(id, normalizedMessage, options);
+    }
+    #dispatchRequest(id, message, options, transfer) {
         if (this.#pending.size >= maxPendingPluginBridgeRequests) {
             throw new PluginBridgeError("PLUGIN_JSON_LIMIT_EXCEEDED", "Plugin bridge has too many pending requests");
         }
@@ -425,7 +454,7 @@ export class PluginBridgeClient {
         if (!this.#pending.has(id))
             return result;
         try {
-            this.#port.postMessage(normalizedMessage);
+            this.#port.postMessage(message, transfer);
             posted = true;
         }
         catch {
@@ -789,6 +818,9 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   const maxImageCount = ${opaqueSurfaceRenderLimits.max_image_count};
   const maxImageDimension = ${opaqueSurfaceRenderLimits.max_image_dimension};
   const maxImageTotalPixels = ${opaqueSurfaceRenderLimits.max_image_total_pixels};
+  const maxFileExportBytes = ${pluginSurfaceFileExportMaxBytes};
+  const fileExportActionWindowMs = ${pluginSurfaceFileExportActionWindowMs};
+  const fileExportMediaTypes = new Set(${JSON.stringify(pluginSurfaceFileExportMediaTypes)});
   const workerHeartbeatIntervalMs = ${opaqueSurfaceRenderLimits.worker_heartbeat_interval_ms};
   const workerHeartbeatTimeoutMs = ${opaqueSurfaceRenderLimits.worker_heartbeat_timeout_ms};
   const rendererCommitFallbackMs = 100;
@@ -842,6 +874,18 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   const validOpaqueHandle = (value, prefix) => typeof value === "string" && value.startsWith(prefix + "_") && /^[A-Za-z0-9_-]{8,160}$/.test(value);
   const validDigest = (value) => typeof value === "string" && /^sha256:[a-f0-9]{64}$/.test(value);
   const validPath = (value) => typeof value === "string" && value.length > 0 && value.length <= 512 && !value.startsWith("/") && !value.includes("\\\\") && !value.split("/").some((part) => !part || part === "." || part === "..");
+  const validFileExportName = (value) => {
+    if (typeof value !== "string" || value.length === 0 || value.length > 128 || value.trim() !== value || value === "." || value === ".." || new TextEncoder().encode(value).byteLength > 255) return false;
+    for (let index = 0; index < value.length; index += 1) {
+      const code = value.charCodeAt(index);
+      if (code < 32 || code === 47 || code === 92 || code === 127) return false;
+    }
+    return true;
+  };
+  const validWorkerFileExport = (value) => exactKeys(value, ["type", "id", "file_name", "media_type", "content"]) &&
+    value.type === "redevplugin.ui.file.export" && typeof value.id === "string" && validFileExportName(value.file_name) &&
+    fileExportMediaTypes.has(value.media_type) && value.content instanceof ArrayBuffer &&
+    value.content.byteLength > 0 && value.content.byteLength <= maxFileExportBytes;
   const validAttribute = (tag, name, value) => {
     const lower = name.toLowerCase();
     if (lower.startsWith("on") || lower === "style" || lower === "src" || lower === "srcset" || lower === "href" || lower === "srcdoc" || lower === "action" || lower === "formaction") return false;
@@ -904,10 +948,11 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   let workerHeartbeatTimer;
   let workerHeartbeatTimeout;
   let pendingQuiesceID;
+  let pendingFileExportAction;
   let runtimeDisposed = false;
   const pendingWorkerRequests = new Set();
   const pendingRendererCommits = new Set();
-  const requestSequence = { rpc: 0, execution: 0, render: 0, canvas: 0, asset: 0, keyboard: 0 };
+  const requestSequence = { rpc: 0, execution: 0, render: 0, canvas: 0, asset: 0, keyboard: 0, file: 0 };
   let executionQuerySurfaceTokens = 8;
   let executionQuerySurfaceRefillAt = performance.now();
   const executionQueryStateIdleMS = 120000;
@@ -991,6 +1036,9 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   const sendParent = (message) => {
     if (parentPort && withinLimit(message)) parentPort.postMessage(message);
   };
+  const sendParentTransfer = (message, transfer) => {
+    if (parentPort) parentPort.postMessage(message, transfer);
+  };
   let interactionSequence = 0;
   const interactionTargetKey = (target) => {
     const element = target instanceof Element ? target.closest("[data-redevplugin-key]") : null;
@@ -1011,7 +1059,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     return false;
   };
   const sendInteraction = (kind, target, options = {}) => {
-    if (!initialized || pendingQuiesceID) return;
+    if (!initialized || pendingQuiesceID) return 0;
     interactionSequence += 1;
     sendParent({
       type: "redevplugin.surface.interaction",
@@ -1024,6 +1072,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
       local_scroll: options.localScroll === true,
       selection_active: options.selectionActive === true,
     });
+    return interactionSequence;
   };
   document.addEventListener("pointerdown", (event) => sendInteraction("activation", event.target), true);
   document.addEventListener("focusin", (event) => sendInteraction("focus", event.target), true);
@@ -1701,6 +1750,8 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
       const buttonType = submitButton && element.contains(submitButton) ? (submitButton.getAttribute("type") || "submit").toLowerCase() : "";
       if (event.type === "click" && buttonType === "submit") {
         event.preventDefault();
+        const sequence = sendInteraction("action", event.target, { action: element.getAttribute("data-redevplugin-action") });
+        if (sequence > 0) pendingFileExportAction = { sequence, expires_at: performance.now() + fileExportActionWindowMs };
         sendWorker(actionPayload(event, element, "submit"));
       }
       return;
@@ -1708,7 +1759,10 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     if (event.type === "submit" || (event.type === "click" && element.tagName === "BUTTON")) event.preventDefault();
     const action = element.getAttribute("data-redevplugin-action");
     if (!validIdentifier(action)) return;
-    sendInteraction("action", event.target, { action });
+    const sequence = sendInteraction("action", event.target, { action });
+    if (sequence > 0 && (event.type === "click" || event.type === "submit")) {
+      pendingFileExportAction = { sequence, expires_at: performance.now() + fileExportActionWindowMs };
+    }
     sendWorker(actionPayload(event, element));
   };
   for (const eventType of ["click", "input", "change", "submit"]) document.addEventListener(eventType, handleAction, true);
@@ -1994,7 +2048,8 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     '    const widthDescriptor = __rpGetOwnPropertyDescriptor(__rpCanvasPrototype, "width");',
     '    const heightDescriptor = __rpGetOwnPropertyDescriptor(__rpCanvasPrototype, "height");',
     '    const contextDescriptor = __rpGetOwnPropertyDescriptor(__rpCanvasPrototype, "getContext");',
-    '    if (!widthDescriptor || !heightDescriptor || typeof widthDescriptor.get !== "function" || typeof widthDescriptor.set !== "function" || typeof heightDescriptor.get !== "function" || typeof heightDescriptor.set !== "function" || !contextDescriptor || typeof contextDescriptor.value !== "function") throw new TypeError("OffscreenCanvas descriptors are unavailable");',
+    '    const convertDescriptor = __rpGetOwnPropertyDescriptor(__rpCanvasPrototype, "convertToBlob");',
+    '    if (!widthDescriptor || !heightDescriptor || typeof widthDescriptor.get !== "function" || typeof widthDescriptor.set !== "function" || typeof heightDescriptor.get !== "function" || typeof heightDescriptor.set !== "function" || !contextDescriptor || typeof contextDescriptor.value !== "function" || !convertDescriptor || typeof convertDescriptor.value !== "function") throw new TypeError("OffscreenCanvas descriptors are unavailable");',
     '    const readWidth = (canvas) => __rpApply(widthDescriptor.get, canvas, []);',
     '    const readHeight = (canvas) => __rpApply(heightDescriptor.get, canvas, []);',
     '    const validateResize = (canvas, axis, value) => {',
@@ -2013,7 +2068,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     '    __rpDefineProperty(__rpCanvasPrototype, "height", { configurable: false, enumerable: Boolean(heightDescriptor.enumerable), get() { return readHeight(this); }, set(value) { validateResize(this, "height", value); __rpApply(heightDescriptor.set, this, [value]); } });',
     '    __rpDefineProperty(__rpCanvasPrototype, "getContext", { configurable: false, enumerable: Boolean(contextDescriptor.enumerable), writable: false, value(type, ...options) { if (type !== "2d") throw new TypeError("only 2d canvas contexts are available"); __rpTrackCanvas(this); return __rpApply(contextDescriptor.value, this, [type, ...options]); } });',
     '    __rpSealDescriptor(__rpCanvasPrototype, "constructor", undefined);',
-    '    __rpSealDescriptor(__rpCanvasPrototype, "convertToBlob", __rpBlocked);',
+    '    __rpSealDescriptor(__rpCanvasPrototype, "convertToBlob", convertDescriptor.value);',
     '    __rpSealDescriptor(__rpCanvasPrototype, "transferToImageBitmap", __rpBlocked);',
     '};',
     'try {',
@@ -2080,7 +2135,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   const validCall = (value) => exactKeys(value, ["type", "request"]) && value.type === "redevplugin.bridge.call" && isRecord(value.request) && Object.keys(value.request).every((key) => ["id", "method", "params"].includes(key)) && typeof value.request.id === "string" && value.request.id.length <= 128 && typeof value.request.method === "string" && /^[A-Za-z0-9._:-]{1,256}$/.test(value.request.method) && (value.request.params === undefined || isRecord(value.request.params));
   const requestID = (value, expectedKind) => {
     if (typeof value !== "string") return undefined;
-    const match = /^(rpc|execution|render|canvas|asset|keyboard)_([1-9][0-9]{0,15})$/.exec(value);
+    const match = /^(rpc|execution|render|canvas|asset|keyboard|file)_([1-9][0-9]{0,15})$/.exec(value);
     if (!match || match[1] !== expectedKind) return undefined;
     const sequence = Number(match[2]);
     return Number.isSafeInteger(sequence) ? { kind: match[1], sequence } : undefined;
@@ -2162,7 +2217,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     renderCount += 1;
     return true;
   };
-  const rejectWorkerRequest = (id, error) => sendWorker({ type: "redevplugin.bridge.response", id, ok: false, error_code: "PLUGIN_INVALID_REQUEST", error });
+  const rejectWorkerRequest = (id, error, errorCode = "PLUGIN_INVALID_REQUEST") => sendWorker({ type: "redevplugin.bridge.response", id, ok: false, error_code: errorCode, error });
   const findCanvas = (canvasID) => {
     for (const element of document.querySelectorAll("canvas[data-redevplugin-canvas]")) {
       if (element.getAttribute("data-redevplugin-canvas") === canvasID) return element;
@@ -2372,8 +2427,30 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     }
   };
   const onWorkerMessage = (event) => {
-    if (!withinLimit(event.data)) return;
     const message = event.data;
+    if (isRecord(message) && message.type === "redevplugin.ui.file.export" && typeof message.id === "string") {
+      if (!validWorkerFileExport(message)) return rejectWorkerRequest(message.id, "plugin file export request is invalid");
+      if (!acceptWorkerRequest(message.id, "file")) return rejectWorkerRequest(message.id, "duplicate, replayed, or excessive plugin request");
+      const action = pendingFileExportAction;
+      if (!action || performance.now() > action.expires_at) {
+        completeWorkerRequest(message.id);
+        pendingFileExportAction = undefined;
+        return rejectWorkerRequest(message.id, "plugin file export requires a recent user action", "PLUGIN_ACTION_DENIED");
+      }
+      pendingFileExportAction = undefined;
+      sendParentTransfer({
+        type: "redevplugin.surface.file.export",
+        frame_generation_id: frameGenerationID,
+        surface_handle: surfaceHandle,
+        action_sequence: action.sequence,
+        id: message.id,
+        file_name: message.file_name,
+        media_type: message.media_type,
+        content: message.content,
+      }, [message.content]);
+      return;
+    }
+    if (!withinLimit(message)) return;
     if (exactKeys(message, ["type", "quiesce_id"]) && message.type === "redevplugin.bridge.lifecycle_ack" && validOpaqueHandle(message.quiesce_id, "quiesce") && message.quiesce_id === pendingQuiesceID) {
       pendingQuiesceID = undefined;
       sendParent({ type: "redevplugin.surface.quiesce_ack", quiesce_id: message.quiesce_id });
@@ -2567,8 +2644,10 @@ class PluginSurfaceHostImplementation {
     #confirm;
     #onOpeningProgress;
     #onInteraction;
+    #onFileExport;
     #onError;
     #lastInteractionSequence = 0;
+    #pendingFileExportAction;
     #interactionWindowStartedAt = 0;
     #interactionWindowCount = 0;
     #abortController = new AbortController();
@@ -2631,6 +2710,7 @@ class PluginSurfaceHostImplementation {
         this.#confirm = options.confirm;
         this.#onOpeningProgress = options.onOpeningProgress;
         this.#onInteraction = options.onInteraction;
+        this.#onFileExport = options.onFileExport;
         this.#onError = options.onError;
         this.#surfaceContext = options.surfaceContext === undefined ? undefined : normalizePluginSurfaceContext(options.surfaceContext);
         hardenPluginSurfaceFrame(this.#iframe);
@@ -2835,6 +2915,7 @@ class PluginSurfaceHostImplementation {
         this.#assetSessionID = undefined;
         this.#document = undefined;
         this.#assets.clear();
+        this.#pendingFileExportAction = undefined;
         if (this.#port) {
             try {
                 this.#port.postMessage({ type: "redevplugin.bridge.lifecycle", event: { type: "dispose" } });
@@ -2859,10 +2940,16 @@ class PluginSurfaceHostImplementation {
         }
     }
     async #handlePortMessage(event) {
-        if (this.#disposed || !messageWithinLimit(event.data))
+        if (this.#disposed)
             return;
         const data = event.data;
         try {
+            if (isSurfaceFileExportCandidate(data)) {
+                await this.#handleFileExport(data);
+                return;
+            }
+            if (!messageWithinLimit(data))
+                return;
             if (hasExactKeys(data, ["type"]) && data.type === "redevplugin.surface.first_paint") {
                 this.#openSignals?.firstPaint.resolve();
                 return;
@@ -2928,6 +3015,12 @@ class PluginSurfaceHostImplementation {
             return;
         this.#lastInteractionSequence = message.sequence;
         const now = performance.now();
+        if (message.kind === "action") {
+            this.#pendingFileExportAction = {
+                sequence: message.sequence,
+                expiresAt: now + pluginSurfaceFileExportActionWindowMs,
+            };
+        }
         if (now - this.#interactionWindowStartedAt >= 1000) {
             this.#interactionWindowStartedAt = now;
             this.#interactionWindowCount = 0;
@@ -2950,6 +3043,50 @@ class PluginSurfaceHostImplementation {
             // Interaction observers cannot alter the surface lifecycle.
         }
     }
+    async #handleFileExport(message) {
+        if (!validBridgeRequestID(message.id, "file"))
+            return;
+        if (!isSurfaceFileExportMessage(message)) {
+            this.#postError(message.id, "PLUGIN_INVALID_REQUEST", "Plugin file export request is invalid");
+            return;
+        }
+        if (!this.#bridgeReady || !this.#ready) {
+            this.#postError(message.id, "PLUGIN_BRIDGE_HANDSHAKE_REQUIRED", "Plugin file export arrived before the surface became ready");
+            return;
+        }
+        if (message.frame_generation_id !== this.frameGenerationId || message.surface_handle !== this.surfaceHandle)
+            return;
+        const action = this.#pendingFileExportAction;
+        if (!action || action.sequence !== message.action_sequence || performance.now() > action.expiresAt) {
+            this.#postError(message.id, "PLUGIN_ACTION_DENIED", "Plugin file export requires a recent user action");
+            return;
+        }
+        this.#pendingFileExportAction = undefined;
+        if (!this.#onFileExport) {
+            this.#postError(message.id, "PLUGIN_FEATURE_NOT_CONFIGURED", "Plugin file export is not configured by the host");
+            return;
+        }
+        const controller = this.#registerPendingRequest(message.id);
+        try {
+            await this.#onFileExport({
+                fileName: message.file_name,
+                mediaType: message.media_type,
+                bytes: new Uint8Array(message.content),
+                signal: controller.signal,
+            });
+            if (!controller.signal.aborted && !this.#disposed)
+                this.#postResponse(message.id);
+        }
+        catch (error) {
+            if (controller.signal.aborted || this.#disposed)
+                return;
+            const bridgeError = toBridgeError(error, "PLUGIN_ADAPTER_FAILURE");
+            this.#postError(message.id, bridgeError.errorCode, bridgeError.message, bridgeError.details, bridgeError.mutationOutcome);
+        }
+        finally {
+            this.#pendingRequestControllers.delete(message.id);
+        }
+    }
     async #handleCall(request) {
         if ((!this.#bridgeReady && !this.#quiesce) || !this.#gatewayToken) {
             this.#postError(request.id, "PLUGIN_BRIDGE_HANDSHAKE_REQUIRED", "Plugin bridge call arrived before the surface became ready");
@@ -3878,6 +4015,18 @@ function setSurfacePresentation(element, state) {
     element.style.opacity = state === "opening" ? "0" : "";
     element.style.pointerEvents = ready ? "" : "none";
 }
+function isSurfaceFileExportCandidate(value) {
+    return isRecord(value) && value.type === "redevplugin.surface.file.export" && typeof value.id === "string";
+}
+function isSurfaceFileExportMessage(value) {
+    return hasExactKeys(value, [
+        "type", "frame_generation_id", "surface_handle", "action_sequence", "id", "file_name", "media_type", "content",
+    ]) && validOpaqueHandle(value.frame_generation_id, "frame") && validOpaqueHandle(value.surface_handle, "surface") &&
+        Number.isSafeInteger(value.action_sequence) && Number(value.action_sequence) > 0 &&
+        validBridgeRequestID(value.id, "file") && validFileExportName(value.file_name) &&
+        validFileExportMediaType(value.media_type) && value.content instanceof ArrayBuffer &&
+        value.content.byteLength > 0 && value.content.byteLength <= pluginSurfaceFileExportMaxBytes;
+}
 function isSurfaceInteractionMessage(value) {
     if (!hasExactKeys(value, [
         "type", "frame_generation_id", "surface_handle", "sequence", "kind", "target_key", "action", "local_scroll", "selection_active",
@@ -4553,7 +4702,7 @@ const pluginMethodPattern = new RegExp("^[-A-Za-z0-9._:]{1,256}$");
 const pluginActionPattern = new RegExp("^[-A-Za-z0-9._:]{1,128}$");
 const pluginUIIdentifierPattern = new RegExp("^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$");
 const opaqueHandlePattern = new RegExp("^[-A-Za-z0-9_]{8,160}$");
-const bridgeRequestIDPattern = /^(rpc|execution|render|canvas|asset|keyboard)_([1-9][0-9]{0,15})$/;
+const bridgeRequestIDPattern = /^(rpc|execution|render|canvas|asset|keyboard|file)_([1-9][0-9]{0,15})$/;
 function validBridgeRequestID(value, expectedKind) {
     if (typeof value !== "string")
         return false;
@@ -4599,6 +4748,20 @@ function validActionID(value) {
 function validUIIdentifier(value) {
     return typeof value === "string" && pluginUIIdentifierPattern.test(value);
 }
+function validFileExportName(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 128 || value.trim() !== value ||
+        value === "." || value === ".." || new TextEncoder().encode(value).byteLength > 255)
+        return false;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < 32 || code === 47 || code === 92 || code === 127)
+            return false;
+    }
+    return true;
+}
+function validFileExportMediaType(value) {
+    return pluginSurfaceFileExportMediaTypes.includes(value);
+}
 function validOpaqueHandle(value, prefix) {
     return typeof value === "string" && value.startsWith(`${prefix}_`) && opaqueHandlePattern.test(value);
 }

package/dist/trusted-parent.d.ts

@@ -2,6 +2,6 @@ export * from "./contracts.gen.js";
 export * from "./errors.js";
 export * from "./platform.js";
 export { PluginSurfaceScope, createPluginSurfaceScope } from "./surface-scope.js";
-export { PluginSurfaceReloadLimiter, PluginSurfaceSlot, createReDevPluginSurfaceTransport, defaultPluginSurfaceReloadMax, defaultPluginSurfaceReloadWindowMs, isPluginRiskPlan, opaqueSurfaceDocumentSchemaVersion, pluginSurfaceContextSchemaVersion, pluginRiskPlanSchemaVersion, trustedParentBridgeHandshakeTranscriptSHA256, } from "./surface.js";
-export type { BridgeLifecycleEvent, MessageChannelLike, MessageEventLike, MessagePortLike, OpaqueSurfaceAsset, OpaqueSurfaceDocument, OpaqueSurfaceStyle, OpaqueSurfaceWorker, PluginConfirmationDecision, PluginConfirmationHandler, PluginConfirmationIntent, PluginConfirmationPlan, PluginMethodResult, PluginRiskEffect, PluginRiskFlag, PluginRiskPlan, PluginRiskSeverity, PluginExecutionEvent, PluginSurfaceHost, PluginSurfaceCloseResult, PluginSurfaceOpeningProgress, PluginSurfaceInteractionEvent, PluginSurfaceInteractionKind, PluginSurfaceQuiesceResult, PluginSurfaceRevocationReconciliation, PluginSurfacePreparationResult, PluginSurfaceContext, PluginSurfaceReloadDecision, PluginSurfaceReloadLimiterOptions, PluginSurfaceReloadState, PluginSurfaceSlotOptions, PluginSurfaceSlotState, ReDevPluginSurfaceTransport, ReDevPluginSurfaceTransportOptions, TrustedParentBridgeHandshake, TrustedParentBridgeTokenRequest, WindowLike, } from "./surface.js";
+export { PluginSurfaceReloadLimiter, PluginSurfaceSlot, createReDevPluginSurfaceTransport, defaultPluginSurfaceReloadMax, defaultPluginSurfaceReloadWindowMs, isPluginRiskPlan, opaqueSurfaceDocumentSchemaVersion, pluginSurfaceContextSchemaVersion, pluginRiskPlanSchemaVersion, pluginSurfaceFileExportActionWindowMs, pluginSurfaceFileExportMaxBytes, pluginSurfaceFileExportMediaTypes, trustedParentBridgeHandshakeTranscriptSHA256, } from "./surface.js";
+export type { BridgeLifecycleEvent, MessageChannelLike, MessageEventLike, MessagePortLike, OpaqueSurfaceAsset, OpaqueSurfaceDocument, OpaqueSurfaceStyle, OpaqueSurfaceWorker, PluginConfirmationDecision, PluginConfirmationHandler, PluginConfirmationIntent, PluginConfirmationPlan, PluginMethodResult, PluginRiskEffect, PluginRiskFlag, PluginRiskPlan, PluginRiskSeverity, PluginExecutionEvent, PluginSurfaceHost, PluginSurfaceCloseResult, PluginSurfaceOpeningProgress, PluginSurfaceInteractionEvent, PluginSurfaceInteractionKind, PluginSurfaceFileExport, PluginSurfaceFileExportHandler, PluginSurfaceFileExportMediaType, PluginSurfaceQuiesceResult, PluginSurfaceRevocationReconciliation, PluginSurfacePreparationResult, PluginSurfaceContext, PluginSurfaceReloadDecision, PluginSurfaceReloadLimiterOptions, PluginSurfaceReloadState, PluginSurfaceSlotOptions, PluginSurfaceSlotState, ReDevPluginSurfaceTransport, ReDevPluginSurfaceTransportOptions, TrustedParentBridgeHandshake, TrustedParentBridgeTokenRequest, WindowLike, } from "./surface.js";
 export type { FetchInitLike, FetchLike, FetchResponseLike, PlatformResponse } from "./http.js";

package/dist/trusted-parent.js

@@ -2,4 +2,4 @@ export * from "./contracts.gen.js";
 export * from "./errors.js";
 export * from "./platform.js";
 export { PluginSurfaceScope, createPluginSurfaceScope } from "./surface-scope.js";
-export { PluginSurfaceReloadLimiter, PluginSurfaceSlot, createReDevPluginSurfaceTransport, defaultPluginSurfaceReloadMax, defaultPluginSurfaceReloadWindowMs, isPluginRiskPlan, opaqueSurfaceDocumentSchemaVersion, pluginSurfaceContextSchemaVersion, pluginRiskPlanSchemaVersion, trustedParentBridgeHandshakeTranscriptSHA256, } from "./surface.js";
+export { PluginSurfaceReloadLimiter, PluginSurfaceSlot, createReDevPluginSurfaceTransport, defaultPluginSurfaceReloadMax, defaultPluginSurfaceReloadWindowMs, isPluginRiskPlan, opaqueSurfaceDocumentSchemaVersion, pluginSurfaceContextSchemaVersion, pluginRiskPlanSchemaVersion, pluginSurfaceFileExportActionWindowMs, pluginSurfaceFileExportMaxBytes, pluginSurfaceFileExportMediaTypes, trustedParentBridgeHandshakeTranscriptSHA256, } from "./surface.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/redevplugin-ui",
-  "version": "3.0.24",
+  "version": "3.0.25",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -40,7 +40,7 @@
     "dist"
   ],
   "dependencies": {
-    "@floegence/redevplugin-contracts": "3.0.24"
+    "@floegence/redevplugin-contracts": "3.0.25"
   },
   "publishConfig": {
     "access": "public"