@floegence/redevplugin-ui 0.6.7 → 0.6.10

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 PluginSurfaceOpeningProgress, type PluginSurfaceReloadLimiter, type PluginSurfaceSlot, type PluginTrustedMethodResult, type ReDevPluginSurfaceTransport } from "./surface.js";
+import { type PluginConfirmationHandler, type PluginSurfaceHost, type PluginSurfaceOpeningProgress, type PluginSurfaceInteractionEvent, type PluginSurfaceReloadLimiter, type PluginSurfaceSlot, type PluginTrustedMethodResult, type ReDevPluginSurfaceTransport } from "./surface.js";
 import { type PluginSurfaceScope } from "./surface-scope.js";
 export type PluginPlatformClientOptions = {
     fetch?: FetchLike;
@@ -31,6 +31,12 @@ export type PluginPackageHashSet = PlatformSchemas["PackageHashSet"];
 export type PluginReleaseRef = PlatformSchemas["PluginReleaseRef"];
 export type PluginInstallReleaseRefRequest = PlatformSchemas["InstallReleaseRefRequest"];
 export type PluginUpdateReleaseRefRequest = PlatformSchemas["UpdateReleaseRefRequest"];
+export type PluginInspectExternalPackageRequest = PlatformSchemas["InspectExternalPackageRequest"];
+export type PluginUploadedExternalPackageIntent = PlatformSchemas["ExternalPackageIntentRequest"];
+export type PluginExternalPackageInspection = PlatformSchemas["ExternalPackageInspection"];
+export type PluginCommitExternalPackageRequest = PlatformSchemas["CommitExternalPackageRequest"];
+export type PluginQueryExternalPackageCommitRequest = PlatformSchemas["QueryExternalPackageCommitRequest"];
+export type PluginExternalPackageCommitResult = PlatformSchemas["ExternalPackageCommitResult"];
 export type PluginDowngradeRequest = PlatformSchemas["DowngradeRequest"];
 export type PluginEnableRequest = PlatformSchemas["EnableRequest"];
 export type PluginDisableRequest = PlatformSchemas["DisableRequest"];
@@ -44,6 +50,7 @@ export type PluginOpenSurfaceInSlotOptions = PluginRequestOptions & {
     reloadLimiter?: PluginSurfaceReloadLimiter;
     confirm?: PluginConfirmationHandler;
     onOpeningProgress?: (progress: PluginSurfaceOpeningProgress) => void;
+    onInteraction?: (event: PluginSurfaceInteractionEvent) => void;
     onError?: (error: import("./errors.js").PluginBridgeError) => void;
 };
 export type PluginSessionScopeRevokeCounts = Readonly<PlatformSchemas["SessionScopeRevokeCounts"]>;
@@ -83,6 +90,8 @@ export type PluginPermissionGrant = PlatformSchemas["PluginPermissionGrant"];
 export type PluginPermissionMutationResult = PlatformSchemas["PluginPermissionMutationResult"];
 export type PluginPermissionList = PlatformSchemas["PluginPermissionList"];
 export type PluginPermissionListOptions = PlatformSchemas["ListPermissionsQueryRequest"];
+export type PluginPermissionRequirements = PlatformSchemas["PluginPermissionRequirements"];
+export type PluginPermissionRequirementsRequest = PlatformSchemas["PermissionRequirementsQueryRequest"];
 export type PluginPermissionGrantRequest = PlatformSchemas["GrantPermissionRequest"];
 export type PluginPermissionRevokeRequest = PlatformSchemas["RevokePermissionRequest"];
 export type PluginSecurityPolicy = PlatformSchemas["PluginSecurityPolicy"];
@@ -119,6 +128,10 @@ export declare class PluginPlatformClient {
     features(options?: PluginRequestOptions): Promise<PluginFeatures>;
     getCompatibility(options?: PluginRequestOptions): Promise<PluginCompatibilityManifest>;
     installReleaseRef(request: PluginInstallReleaseRefRequest, options?: PluginRequestOptions): Promise<PluginRecord>;
+    inspectExternalPackage(request: PluginInspectExternalPackageRequest, options?: PluginRequestOptions): Promise<PluginExternalPackageInspection>;
+    inspectUploadedExternalPackage(intent: PluginUploadedExternalPackageIntent, packageBlob: Blob, options?: PluginRequestOptions): Promise<PluginExternalPackageInspection>;
+    commitExternalPackage(request: PluginCommitExternalPackageRequest, options?: PluginRequestOptions): Promise<PluginExternalPackageCommitResult>;
+    queryExternalPackageCommit(request: PluginQueryExternalPackageCommitRequest, options?: PluginRequestOptions): Promise<PluginExternalPackageCommitResult>;
     updateReleaseRef(request: PluginUpdateReleaseRefRequest, options?: PluginRequestOptions): Promise<PluginRecord>;
     downgradePlugin(request: PluginDowngradeRequest, options?: PluginRequestOptions): Promise<PluginRecord>;
     enablePlugin(request: PluginEnableRequest, options?: PluginRequestOptions): Promise<PluginRecord>;
@@ -146,6 +159,7 @@ export declare class PluginPlatformClient {
     bindRetainedData(request: PluginRetainedDataBindRequest, options?: PluginRequestOptions): Promise<PluginDataBinding>;
     cleanupExpiredRetainedData(request?: PluginRetainedDataCleanupRequest, options?: PluginRequestOptions): Promise<PluginRetainedDataCleanupResult>;
     listPermissions(options?: PluginPermissionListOptions, requestOptions?: PluginRequestOptions): Promise<PluginPermissionList>;
+    getPermissionRequirements(request: PluginPermissionRequirementsRequest, options?: PluginRequestOptions): Promise<PluginPermissionRequirements>;
     grantPermission(request: PluginPermissionGrantRequest, options?: PluginRequestOptions): Promise<PluginPermissionMutationResult>;
     revokePermission(request: PluginPermissionRevokeRequest, options?: PluginRequestOptions): Promise<PluginPermissionMutationResult>;
     listSecurityPolicies(options?: PluginRequestOptions): Promise<PluginSecurityPolicyList>;

package/dist/platform.js

@@ -26,6 +26,7 @@ export class PluginPlatformClient {
     #surfaceScope;
     #surfaceTransport;
     #onMutationOutcomeUnknown;
+    #externalInspectionTargets = new Map();
     constructor(options = {}) {
         this.#fetch = options.fetch ?? defaultFetch();
         this.#apiBaseURL = trimTrailingSlash(options.apiBaseURL ?? "");
@@ -39,6 +40,56 @@ export class PluginPlatformClient {
     installReleaseRef(request, options = {}) {
         return this.#requestMutation("POST", "/_redevplugin/api/plugins/install-release-ref", request, options);
     }
+    async inspectExternalPackage(request, options = {}) {
+        const inspection = await this.#requestMutation("POST", "/_redevplugin/api/plugins/external-packages/inspect", request, options);
+        this.#externalInspectionTargets.set(inspection.inspection_id, inspection.intent.plugin_instance_id ?? "");
+        return inspection;
+    }
+    async inspectUploadedExternalPackage(intent, packageBlob, options = {}) {
+        const canonicalIntent = canonicalUploadedExternalPackageIntent(intent);
+        if (!(packageBlob instanceof Blob)) {
+            throw new TypeError("external package upload must be a Blob");
+        }
+        const update = canonicalIntent.action === "update";
+        const path = update
+            ? `/_redevplugin/api/plugins/${encodeURIComponent(canonicalIntent.plugin_instance_id)}/external-packages/upload/inspect`
+            : "/_redevplugin/api/plugins/external-packages/upload/inspect";
+        const inspection = await this.#requestPackageUploadInspection(update ? "PUT" : "POST", path, packageBlob, options, update
+            ? { "X-ReDevPlugin-Expected-Management-Revision": String(canonicalIntent.expected_management_revision) }
+            : {});
+        this.#externalInspectionTargets.set(inspection.inspection_id, update ? canonicalIntent.plugin_instance_id : "");
+        return inspection;
+    }
+    async commitExternalPackage(request, options = {}) {
+        const target = this.#externalInspectionTargets.get(request.inspection_id);
+        let result;
+        try {
+            result = await this.#requestMutation("POST", "/_redevplugin/api/plugins/external-packages/commit", request, options);
+        }
+        catch (error) {
+            await this.#handleMutationFailure(error, target || undefined, "External package commit and local surface teardown failed");
+            throw error;
+        }
+        if (result.status === "committed") {
+            await disposePluginSurfaceScope(this.#surfaceScope, result.plugin.plugin_instance_id);
+            this.#externalInspectionTargets.delete(request.inspection_id);
+        }
+        else if (result.status === "failed") {
+            this.#externalInspectionTargets.delete(request.inspection_id);
+        }
+        return result;
+    }
+    async queryExternalPackageCommit(request, options = {}) {
+        const result = await this.#requestQuery("/_redevplugin/api/plugins/external-packages/commit/query", request, options);
+        if (result.status === "committed") {
+            await disposePluginSurfaceScope(this.#surfaceScope, result.plugin.plugin_instance_id);
+            this.#externalInspectionTargets.delete(request.inspection_id);
+        }
+        else if (result.status === "failed") {
+            this.#externalInspectionTargets.delete(request.inspection_id);
+        }
+        return result;
+    }
     updateReleaseRef(request, options = {}) {
         return this.#mutatePlugin("/_redevplugin/api/plugins/update-release-ref", request, options);
     }
@@ -163,6 +214,9 @@ export class PluginPlatformClient {
     listPermissions(options = {}, requestOptions = {}) {
         return this.#requestQuery("/_redevplugin/api/plugins/permissions/query", options, requestOptions);
     }
+    getPermissionRequirements(request, options = {}) {
+        return this.#requestQuery("/_redevplugin/api/plugins/permissions/requirements/query", request, options);
+    }
     grantPermission(request, options = {}) {
         return this.#mutatePlugin("/_redevplugin/api/plugins/permissions/grant", request, options);
     }
@@ -296,6 +350,58 @@ export class PluginPlatformClient {
         }, operation);
         return readMutationPlatformResponse(response);
     }
+    async #requestPackageUploadInspection(method, path, body, options, metadataHeaders) {
+        const operation = `${method} ${path}`;
+        assertMutationDispatchable(options.signal, operation);
+        const response = await dispatchMutationRequest(this.#fetch, this.#apiBaseURL + path, {
+            method,
+            headers: {
+                "Accept": "application/json",
+                "Content-Type": "application/vnd.redevplugin.package+zip",
+                ...metadataHeaders,
+            },
+            body,
+            credentials: "same-origin",
+            signal: options.signal,
+        }, operation);
+        return readMutationPlatformResponse(response);
+    }
+}
+function canonicalUploadedExternalPackageIntent(intent) {
+    if (typeof intent !== "object" || intent === null || Array.isArray(intent)) {
+        throw new TypeError("uploaded external package intent must be a closed install or update object");
+    }
+    const value = intent;
+    const keys = Object.keys(value).sort();
+    if (value.action === "install") {
+        if (keys.length !== 1 || keys[0] !== "action") {
+            throw new TypeError("uploaded external package install intent accepts only action");
+        }
+        return { action: "install" };
+    }
+    if (value.action !== "update") {
+        throw new TypeError("uploaded external package intent action must be install or update");
+    }
+    const updateKeys = ["action", "expected_management_revision", "plugin_instance_id"];
+    if (keys.length !== updateKeys.length || keys.some((key, index) => key !== updateKeys[index])) {
+        throw new TypeError("uploaded external package update intent requires only action, plugin_instance_id, and expected_management_revision");
+    }
+    if (typeof value.plugin_instance_id !== "string" ||
+        value.plugin_instance_id.length === 0 ||
+        value.plugin_instance_id.trim() !== value.plugin_instance_id ||
+        value.plugin_instance_id.startsWith(".") ||
+        value.plugin_instance_id.includes("/")) {
+        throw new TypeError("uploaded external package update plugin_instance_id must be a canonical non-empty string");
+    }
+    if (!Number.isSafeInteger(value.expected_management_revision) ||
+        value.expected_management_revision <= 0) {
+        throw new TypeError("uploaded external package update expected_management_revision must be a positive safe integer");
+    }
+    return {
+        action: "update",
+        plugin_instance_id: value.plugin_instance_id,
+        expected_management_revision: value.expected_management_revision,
+    };
 }
 const sessionScopeCountKeys = [
     "surfaces",

package/dist/surface.d.ts

@@ -349,6 +349,15 @@ export type PluginSurfaceOpeningProgress = {
     phase: "opening";
     elapsedMs: number;
 };
+export type PluginSurfaceInteractionKind = "activation" | "focus" | "wheel" | "text-selection" | "action";
+export type PluginSurfaceInteractionEvent = {
+    kind: PluginSurfaceInteractionKind;
+    sequence: number;
+    targetKey?: string;
+    action?: string;
+    localScroll: boolean;
+    selectionActive: boolean;
+};
 export type PluginSurfaceHost = {
     readonly element: HTMLIFrameElement;
     readonly surfaceInstanceId: string;
@@ -376,6 +385,7 @@ export type PluginSurfaceHostOptions = {
     reloadLimiter?: PluginSurfaceReloadLimiter;
     confirm?: PluginConfirmationHandler;
     onOpeningProgress?: (progress: PluginSurfaceOpeningProgress) => void;
+    onInteraction?: (event: PluginSurfaceInteractionEvent) => void;
     onError?: (error: PluginBridgeError) => void;
 };
 type PluginSurfaceOpeningRequest = {
@@ -403,9 +413,16 @@ export type PluginSurfaceQuiesceResult = {
 };
 export type PluginSurfaceCloseResult = {
     quiesce: PluginSurfaceQuiesceResult;
+    readonly revocation?: PluginSurfaceRevocationReconciliation;
     revokeDurationMs: number;
     totalDurationMs: number;
 };
+export type PluginSurfaceRevocationReconciliation = {
+    disposed: true;
+    state: "closed" | "absent";
+    previous_state: "active" | "closed" | "absent";
+    revoked: boolean;
+};
 export declare function createOpaquePluginBootstrapHTML(options?: OpaquePluginBootstrapHTMLOptions): string;
 export declare function createPreparedPluginSurfaceHost(options: PluginSurfaceHostOptions): PreparedPluginSurfaceHost;
 export type PluginSurfaceSlotState = "empty" | "opening" | "ready" | "error" | "disposed";

package/dist/surface.js

@@ -34,6 +34,7 @@ const maxOpaqueSurfaceLazyAssets = 128;
 const maxOpaqueSurfaceLazyBytes = 32 * 1024 * 1024;
 const maxConcurrentAssetReads = 4;
 const maxSurfaceQuiesceMs = 1500;
+const maxSurfaceInteractionEventsPerSecond = 120;
 const pluginBridgeErrorCodeSet = new Set(pluginBridgeErrorCodes);
 const hostCapabilityIDPattern = new RegExp("^[A-Za-z0-9][A-Za-z0-9._-]*$");
 const canonicalSemverPattern = new RegExp("^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-(?:(?:0|[1-9][0-9]*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$");
@@ -688,7 +689,11 @@ async function revokeSurfaceBootstrap(transport, bootstrap, timeoutMs, keepalive
             }),
             timeout,
         ]);
-        await readMutationPlatformResponse(response);
+        const result = await readMutationPlatformResponse(response);
+        if (!isSurfaceRevocationReconciliation(result)) {
+            throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface revocation reconciliation returned an invalid result", undefined, undefined, "unknown");
+        }
+        return result;
     }
     catch (error) {
         if (timedOut) {
@@ -880,6 +885,48 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   const sendParent = (message) => {
     if (parentPort && withinLimit(message)) parentPort.postMessage(message);
   };
+  let interactionSequence = 0;
+  const interactionTargetKey = (target) => {
+    const element = target instanceof Element ? target.closest("[data-redevplugin-key]") : null;
+    const key = element?.getAttribute("data-redevplugin-key");
+    return validResourceIdentifier(key) ? key : null;
+  };
+  const ownsLocalScroll = (event) => {
+    const path = typeof event.composedPath === "function" ? event.composedPath() : [event.target];
+    for (const candidate of path) {
+      if (!(candidate instanceof Element)) continue;
+      if (candidate === document.scrollingElement &&
+          (candidate.scrollHeight > candidate.clientHeight || candidate.scrollWidth > candidate.clientWidth)) return true;
+      const style = getComputedStyle(candidate);
+      const vertical = /(auto|scroll|overlay)/.test(style.overflowY) && candidate.scrollHeight > candidate.clientHeight;
+      const horizontal = /(auto|scroll|overlay)/.test(style.overflowX) && candidate.scrollWidth > candidate.clientWidth;
+      if (vertical || horizontal) return true;
+    }
+    return false;
+  };
+  const sendInteraction = (kind, target, options = {}) => {
+    if (!initialized || pendingQuiesceID) return;
+    interactionSequence += 1;
+    sendParent({
+      type: "redevplugin.surface.interaction",
+      frame_generation_id: frameGenerationID,
+      surface_handle: surfaceHandle,
+      sequence: interactionSequence,
+      kind,
+      target_key: interactionTargetKey(target),
+      action: options.action || null,
+      local_scroll: options.localScroll === true,
+      selection_active: options.selectionActive === true,
+    });
+  };
+  document.addEventListener("pointerdown", (event) => sendInteraction("activation", event.target), true);
+  document.addEventListener("focusin", (event) => sendInteraction("focus", event.target), true);
+  document.addEventListener("wheel", (event) => sendInteraction("wheel", event.target, { localScroll: ownsLocalScroll(event) }), { capture: true, passive: true });
+  document.addEventListener("selectionchange", () => {
+    const selection = document.getSelection();
+    const target = selection?.anchorNode instanceof Element ? selection.anchorNode : selection?.anchorNode?.parentElement;
+    sendInteraction("text-selection", target, { selectionActive: Boolean(selection && !selection.isCollapsed) });
+  });
   const sendWorker = (message) => {
     if (workerPort && withinLimit(message)) workerPort.postMessage(message);
   };
@@ -1513,6 +1560,7 @@ 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 });
     sendWorker(actionPayload(event, element));
   };
   for (const eventType of ["click", "input", "change", "submit"]) document.addEventListener(eventType, handleAction, true);
@@ -1551,6 +1599,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     const targetKey = owner.getAttribute("data-redevplugin-key");
     if (!validResourceIdentifier(targetKey)) return;
     const edit = controlEdits.get(targetKey) || { revision: 0, isComposing: false };
+    sendInteraction("action", origin, { action });
     sendWorker({
       type: "redevplugin.ui.action",
       action,
@@ -2265,7 +2314,11 @@ class PluginSurfaceHostImplementation {
     #reloadLimiter;
     #confirm;
     #onOpeningProgress;
+    #onInteraction;
     #onError;
+    #lastInteractionSequence = 0;
+    #interactionWindowStartedAt = 0;
+    #interactionWindowCount = 0;
     #abortController = new AbortController();
     #gatewayToken;
     #leaseExpiresAtMs = 0;
@@ -2324,6 +2377,7 @@ class PluginSurfaceHostImplementation {
         this.#reloadLimiter = options.reloadLimiter ?? new PluginSurfaceReloadLimiter();
         this.#confirm = options.confirm;
         this.#onOpeningProgress = options.onOpeningProgress;
+        this.#onInteraction = options.onInteraction;
         this.#onError = options.onError;
         hardenPluginSurfaceFrame(this.#iframe);
         this.#unregisterSurfaceScope = registerPluginSurface(options.surfaceScope ?? defaultPluginSurfaceScope, this.bootstrap.pluginInstanceId, () => this.#disposeLocal(), () => this.#invalidateLocal());
@@ -2430,23 +2484,29 @@ class PluginSurfaceHostImplementation {
         if (this.#disposed) {
             const result = {
                 quiesce: { outcome: "not_ready", durationMs: 0 },
+                revocation: { disposed: true, state: "closed", previous_state: "closed", revoked: false },
                 revokeDurationMs: 0,
                 totalDurationMs: 0,
             };
-            return this.#revokePromise ? this.#revokePromise.then(() => result) : Promise.resolve(result);
+            return this.#revokeSurface(false).then((revocation) => ({ ...result, revocation }));
         }
         if (this.#closePromise)
             return this.#closePromise;
-        this.#closePromise = this.#closeSurface();
-        return this.#closePromise;
+        const closing = this.#closeSurface();
+        this.#closePromise = closing;
+        void closing.catch(() => {
+            if (this.#closePromise === closing)
+                this.#closePromise = undefined;
+        });
+        return closing;
     }
     dispose() {
         if (this.#disposed)
-            return this.#revokePromise ?? Promise.resolve();
+            return this.#revokeSurface(true).then(() => undefined);
         const revoke = this.#revokeSurface(true);
         void revoke.catch(() => undefined);
         this.#disposeLocal();
-        return revoke;
+        return revoke.then(() => undefined);
     }
     observeLocalInvalidation(observer) {
         this.#onLocalInvalidation = observer;
@@ -2457,22 +2517,24 @@ class PluginSurfaceHostImplementation {
         const startedAt = performance.now();
         const quiesce = await this.#quiesceSurface();
         if (this.#disposed) {
-            return { quiesce, revokeDurationMs: 0, totalDurationMs: performance.now() - startedAt };
+            const revocation = this.#revokePromise ? await this.#revokePromise : { disposed: true, state: "closed", previous_state: "closed", revoked: false };
+            return { quiesce, revocation, revokeDurationMs: 0, totalDurationMs: performance.now() - startedAt };
         }
         const revokeStartedAt = performance.now();
         const revoke = this.#revokeSurface(false);
         this.#disposeLocal();
         try {
-            await revoke;
+            const revocation = await revoke;
+            return {
+                quiesce,
+                revocation,
+                revokeDurationMs: performance.now() - revokeStartedAt,
+                totalDurationMs: performance.now() - startedAt,
+            };
         }
         catch (error) {
             throw toBridgeError(error, "PLUGIN_BRIDGE_DISPOSED");
         }
-        return {
-            quiesce,
-            revokeDurationMs: performance.now() - revokeStartedAt,
-            totalDurationMs: performance.now() - startedAt,
-        };
     }
     #disposeLocal() {
         if (this.#disposed)
@@ -2550,6 +2612,10 @@ class PluginSurfaceHostImplementation {
                 this.#openSignals?.firstCommit.resolve();
                 return;
             }
+            if (isSurfaceInteractionMessage(data)) {
+                this.#handleInteraction(data);
+                return;
+            }
             if (hasExactKeys(data, ["type", "quiesce_id"]) && data.type === "redevplugin.surface.quiesce_ack" && validOpaqueHandle(data.quiesce_id, "quiesce") && data.quiesce_id === this.#quiesce?.id) {
                 this.#quiesce.acknowledged.resolve();
                 return;
@@ -2587,6 +2653,35 @@ class PluginSurfaceHostImplementation {
             await this.#failSurface(toBridgeError(error, "PLUGIN_CONTRACT_MISMATCH"));
         }
     }
+    #handleInteraction(message) {
+        if (!this.#ready || message.frame_generation_id !== this.frameGenerationId || message.surface_handle !== this.surfaceHandle)
+            return;
+        if (message.sequence <= this.#lastInteractionSequence)
+            return;
+        this.#lastInteractionSequence = message.sequence;
+        const now = performance.now();
+        if (now - this.#interactionWindowStartedAt >= 1000) {
+            this.#interactionWindowStartedAt = now;
+            this.#interactionWindowCount = 0;
+        }
+        this.#interactionWindowCount += 1;
+        if (this.#interactionWindowCount > maxSurfaceInteractionEventsPerSecond)
+            return;
+        const interaction = {
+            kind: message.kind,
+            sequence: message.sequence,
+            localScroll: message.local_scroll,
+            selectionActive: message.selection_active,
+            ...(message.target_key === null ? {} : { targetKey: message.target_key }),
+            ...(message.action === null ? {} : { action: message.action }),
+        };
+        try {
+            this.#onInteraction?.(interaction);
+        }
+        catch {
+            // Interaction observers cannot alter the surface lifecycle.
+        }
+    }
     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");
@@ -3072,8 +3167,13 @@ class PluginSurfaceHostImplementation {
     #revokeSurface(keepalive) {
         if (this.#revokePromise)
             return this.#revokePromise;
-        this.#revokePromise = revokeSurfaceBootstrap(this.#transport, this.bootstrap, this.#requestTimeoutMs, keepalive);
-        return this.#revokePromise;
+        const revocation = revokeSurfaceBootstrap(this.#transport, this.bootstrap, this.#requestTimeoutMs, keepalive);
+        this.#revokePromise = revocation;
+        void revocation.catch(() => {
+            if (this.#revokePromise === revocation)
+                this.#revokePromise = undefined;
+        });
+        return revocation;
     }
     async #quiesceSurface() {
         const startedAt = performance.now();
@@ -3309,6 +3409,7 @@ export class PluginSurfaceSlot {
     #tail = Promise.resolve();
     #disposed = false;
     #retired = new WeakMap();
+    #pendingRetirements = new Set();
     #disposePromise;
     static create(options) {
         if (!options.stage || typeof options.stage.append !== "function" || !options.stage.dataset) {
@@ -3449,8 +3550,8 @@ export class PluginSurfaceSlot {
         this.#transitionController?.abort();
         this.#transitionController = undefined;
         this.#setState("empty");
-        const closing = this.#tail.then(() => this.#closeCurrentSurface());
-        this.#tail = closing.then(() => undefined, (error) => error instanceof PluginSurfaceCleanupError ? Promise.reject(error) : undefined);
+        const closing = this.#tail.then(() => this.#closeCurrentSurface(), () => this.#closeCurrentSurface());
+        this.#tail = closing.then(() => undefined, () => undefined);
         void this.#tail.catch(() => undefined);
         return this.#unwrapCleanupError(closing);
     }
@@ -3461,17 +3562,22 @@ export class PluginSurfaceSlot {
         this.#transitionController?.abort();
         this.#transitionController = undefined;
         this.#setState("disposed");
-        const disposal = this.#tail.then(async () => {
-            await this.#closeCurrentSurface();
+        const disposal = this.#tail.then(() => this.#closeCurrentSurface().then(() => undefined), () => this.#closeCurrentSurface().then(() => undefined));
+        const disposePromise = this.#unwrapCleanupError(disposal);
+        this.#disposePromise = disposePromise;
+        void disposePromise.catch(() => {
+            if (this.#disposePromise === disposePromise)
+                this.#disposePromise = undefined;
         });
-        this.#disposePromise = this.#unwrapCleanupError(disposal);
-        void this.#disposePromise.catch(() => undefined);
-        this.#tail = disposal.then(() => undefined, (error) => error instanceof PluginSurfaceCleanupError ? Promise.reject(error) : undefined);
+        this.#tail = disposal.then(() => undefined, () => undefined);
         void this.#tail.catch(() => undefined);
-        return this.#disposePromise;
+        return disposePromise;
     }
     async #closeCurrentSurface() {
-        const hosts = new Set([this.#active, this.#opening].filter((host) => host !== undefined));
+        const hosts = new Set([
+            ...this.#pendingRetirements,
+            ...[this.#active, this.#opening].filter((host) => host !== undefined),
+        ]);
         this.#active = undefined;
         this.#opening = undefined;
         let result;
@@ -3495,6 +3601,7 @@ export class PluginSurfaceSlot {
         const existing = this.#retired.get(host);
         if (existing)
             return existing;
+        this.#pendingRetirements.add(host);
         setSurfaceInteractive(host.element, false);
         const closing = Promise.resolve().then(async () => {
             try {
@@ -3512,6 +3619,14 @@ export class PluginSurfaceSlot {
             }
         });
         this.#retired.set(host, closing);
+        void closing.then(() => {
+            this.#pendingRetirements.delete(host);
+            if (this.#retired.get(host) === closing)
+                this.#retired.delete(host);
+        }, () => {
+            if (this.#retired.get(host) === closing)
+                this.#retired.delete(host);
+        });
         return closing;
     }
     async #awaitRetirement(host) {
@@ -3596,6 +3711,31 @@ function setSurfaceInteractive(element, interactive) {
     element.inert = !interactive;
     element.setAttribute("aria-hidden", interactive ? "false" : "true");
 }
+function isSurfaceInteractionMessage(value) {
+    if (!hasExactKeys(value, [
+        "type", "frame_generation_id", "surface_handle", "sequence", "kind", "target_key", "action", "local_scroll", "selection_active",
+    ]))
+        return false;
+    return value.type === "redevplugin.surface.interaction" &&
+        validOpaqueHandle(value.frame_generation_id, "frame") &&
+        validOpaqueHandle(value.surface_handle, "surface") &&
+        typeof value.sequence === "number" && Number.isSafeInteger(value.sequence) && value.sequence > 0 &&
+        ["activation", "focus", "wheel", "text-selection", "action"].includes(String(value.kind)) &&
+        (value.target_key === null || validUIIdentifier(value.target_key)) &&
+        (value.action === null || validActionID(value.action)) &&
+        typeof value.local_scroll === "boolean" && typeof value.selection_active === "boolean" &&
+        (value.kind === "action" ? value.action !== null : value.action === null) &&
+        (value.kind === "wheel" || value.local_scroll === false) &&
+        (value.kind === "text-selection" || value.selection_active === false);
+}
+function isSurfaceRevocationReconciliation(value) {
+    if (!hasExactKeys(value, ["disposed", "state", "previous_state", "revoked"]))
+        return false;
+    return value.disposed === true && ["closed", "absent"].includes(String(value.state)) &&
+        ["active", "closed", "absent"].includes(String(value.previous_state)) &&
+        typeof value.revoked === "boolean" &&
+        (value.revoked ? value.state === "closed" && value.previous_state === "active" : true);
+}
 function claimOpaquePluginBridge() {
     const value = globalThis[opaquePluginBridgeGlobalKey];
     if (!isRecord(value) || typeof value.claim !== "function") {

package/dist/trusted-parent.d.ts

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

package/package.json

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