@floegence/redevplugin-ui 0.6.8 → 0.6.13

package/dist/contracts.gen.d.ts

@@ -42,8 +42,8 @@ export declare const redevPluginContractVersions: {
     readonly host_capability_signature_schema_version: "host-capability-signature-v1";
     readonly host_capability_notices_schema_version: "host-capability-notices-v1";
     readonly error_codes_schema_version: "error-codes-v6";
-    readonly performance_contract_version: "performance-contract-v3";
-    readonly performance_evidence_schema_version: "performance-evidence-v3";
+    readonly performance_contract_version: "performance-contract-v4";
+    readonly performance_evidence_schema_version: "performance-evidence-v4";
     readonly contract_registry_version: "contract-registry-v2";
     readonly platform_package_set_schema_version: "platform-package-set-v1";
     readonly platform_package_publication_schema_version: "platform-package-publication-v1";
@@ -66,7 +66,7 @@ export declare const redevPluginContractArtifacts: readonly [{
     readonly id: "compatibility-manifest-schema";
     readonly path: "spec/plugin/compatibility-manifest-v8.schema.json";
     readonly version: "compatibility-manifest-v8";
-    readonly sha256: "a1831e0ae9a1b47d92e7ad9879b1ca4e3510ebc212b87360595b672e8b87bc79";
+    readonly sha256: "fe966f66e23a6d7558156608f269d08fbe57d8bca16514f1d095445cea697189";
 }, {
     readonly id: "contract-registry-schema";
     readonly path: "spec/plugin/contract-registry-v2.schema.json";
@@ -131,7 +131,7 @@ export declare const redevPluginContractArtifacts: readonly [{
     readonly id: "opaque-surface-transport-schema";
     readonly path: "spec/plugin/opaque-surface-transport-v4.schema.json";
     readonly version: "opaque-surface-transport-v4";
-    readonly sha256: "70a32dc8bf281cea2c92492c466fd477070c62156a3f593d45eb460cde62dca2";
+    readonly sha256: "004da73aba882cf8c2130af0c69d3eed4c710539f21287841bc2e7e870e60f8f";
 }, {
     readonly id: "owner-scope-inventory-registry";
     readonly path: "spec/plugin/owner-scope-inventories-v1.json";
@@ -154,14 +154,14 @@ export declare const redevPluginContractArtifacts: readonly [{
     readonly sha256: "13951c0f6831ba28647774368c76a817868aeb7984628e2cf3dc4ad1b54f8284";
 }, {
     readonly id: "performance-contract";
-    readonly path: "spec/plugin/performance-contract-v3.json";
-    readonly version: "performance-contract-v3";
-    readonly sha256: "a4e1a099dc16f2b0a4d6bdc5fdf8f6ce622948ffec40f70bfc2743286a2b816b";
+    readonly path: "spec/plugin/performance-contract-v4.json";
+    readonly version: "performance-contract-v4";
+    readonly sha256: "aedc50ed8899346140965dc46e8adf2048c47bcf6c146c3b7a51646eda7725e1";
 }, {
     readonly id: "performance-evidence-schema";
-    readonly path: "spec/plugin/performance-evidence-v3.schema.json";
-    readonly version: "performance-evidence-v3";
-    readonly sha256: "a2f5e94071bb09a9327fc55ad3f6c39052b01c3e54cceb8b974dc244667a0326";
+    readonly path: "spec/plugin/performance-evidence-v4.schema.json";
+    readonly version: "performance-evidence-v4";
+    readonly sha256: "f51ba9d425f0e40bc4f2db7ed26454e7575b14ffb6937a06dc01b8e7a66b3f61";
 }, {
     readonly id: "platform-package-publication-schema";
     readonly path: "spec/plugin/platform-package-publication-v1.schema.json";
@@ -176,7 +176,7 @@ export declare const redevPluginContractArtifacts: readonly [{
     readonly id: "plugin-platform-openapi";
     readonly path: "spec/openapi/plugin-platform-v8.yaml";
     readonly version: "plugin-platform-v8";
-    readonly sha256: "39bcfcfb846c868945ab0d21404747b2f5f083574c7ead5aca64f65b98212b7d";
+    readonly sha256: "94e0cc88cb5ad8e7773677617530028578859e0bf229a6b75997f24885eb36d2";
 }, {
     readonly id: "process-containment-schema";
     readonly path: "spec/plugin/process-containment-v1.schema.json";

package/dist/contracts.gen.js

@@ -43,8 +43,8 @@ export const redevPluginContractVersions = {
     "host_capability_signature_schema_version": "host-capability-signature-v1",
     "host_capability_notices_schema_version": "host-capability-notices-v1",
     "error_codes_schema_version": "error-codes-v6",
-    "performance_contract_version": "performance-contract-v3",
-    "performance_evidence_schema_version": "performance-evidence-v3",
+    "performance_contract_version": "performance-contract-v4",
+    "performance_evidence_schema_version": "performance-evidence-v4",
     "contract_registry_version": "contract-registry-v2",
     "platform_package_set_schema_version": "platform-package-set-v1",
     "platform_package_publication_schema_version": "platform-package-publication-v1",
@@ -62,7 +62,7 @@ export const redevPluginContractArtifacts = [
         id: "compatibility-manifest-schema",
         path: "spec/plugin/compatibility-manifest-v8.schema.json",
         version: "compatibility-manifest-v8",
-        sha256: "a1831e0ae9a1b47d92e7ad9879b1ca4e3510ebc212b87360595b672e8b87bc79",
+        sha256: "fe966f66e23a6d7558156608f269d08fbe57d8bca16514f1d095445cea697189",
     },
     {
         id: "contract-registry-schema",
@@ -140,7 +140,7 @@ export const redevPluginContractArtifacts = [
         id: "opaque-surface-transport-schema",
         path: "spec/plugin/opaque-surface-transport-v4.schema.json",
         version: "opaque-surface-transport-v4",
-        sha256: "70a32dc8bf281cea2c92492c466fd477070c62156a3f593d45eb460cde62dca2",
+        sha256: "004da73aba882cf8c2130af0c69d3eed4c710539f21287841bc2e7e870e60f8f",
     },
     {
         id: "owner-scope-inventory-registry",
@@ -168,15 +168,15 @@ export const redevPluginContractArtifacts = [
     },
     {
         id: "performance-contract",
-        path: "spec/plugin/performance-contract-v3.json",
-        version: "performance-contract-v3",
-        sha256: "a4e1a099dc16f2b0a4d6bdc5fdf8f6ce622948ffec40f70bfc2743286a2b816b",
+        path: "spec/plugin/performance-contract-v4.json",
+        version: "performance-contract-v4",
+        sha256: "aedc50ed8899346140965dc46e8adf2048c47bcf6c146c3b7a51646eda7725e1",
     },
     {
         id: "performance-evidence-schema",
-        path: "spec/plugin/performance-evidence-v3.schema.json",
-        version: "performance-evidence-v3",
-        sha256: "a2f5e94071bb09a9327fc55ad3f6c39052b01c3e54cceb8b974dc244667a0326",
+        path: "spec/plugin/performance-evidence-v4.schema.json",
+        version: "performance-evidence-v4",
+        sha256: "f51ba9d425f0e40bc4f2db7ed26454e7575b14ffb6937a06dc01b8e7a66b3f61",
     },
     {
         id: "platform-package-publication-schema",
@@ -194,7 +194,7 @@ export const redevPluginContractArtifacts = [
         id: "plugin-platform-openapi",
         path: "spec/openapi/plugin-platform-v8.yaml",
         version: "plugin-platform-v8",
-        sha256: "39bcfcfb846c868945ab0d21404747b2f5f083574c7ead5aca64f65b98212b7d",
+        sha256: "94e0cc88cb5ad8e7773677617530028578859e0bf229a6b75997f24885eb36d2",
     },
     {
         id: "process-containment-schema",

package/dist/openapi.gen.d.ts

@@ -405,6 +405,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
+        /** @description Atomically observes and revokes one exact authenticated surface. An active surface becomes closed, a retained closure confirms closed, and an absent result is authoritative inactivity; transport failures remain an unknown mutation outcome. */
         post: operations["disposePluginSurface"];
         delete?: never;
         options?: never;
@@ -719,6 +720,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/_redevplugin/api/plugins/permissions/requirements/query": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description Projects required permissions only from the active plugin version's Host-verified capability contracts. */
+        post: operations["getPluginPermissionRequirements"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/_redevplugin/api/plugins/permissions/grant": {
         parameters: {
             query?: never;
@@ -1070,6 +1088,11 @@ export interface components {
             ok: true;
             data: components["schemas"]["PluginPermissionList"];
         };
+        PermissionRequirementsSuccessResponse: {
+            /** @constant */
+            ok: true;
+            data: components["schemas"]["PluginPermissionRequirements"];
+        };
         PermissionMutationSuccessResponse: {
             /** @constant */
             ok: true;
@@ -1309,6 +1332,11 @@ export interface components {
         SurfaceDisposeResult: {
             /** @constant */
             disposed: true;
+            /** @enum {string} */
+            state: "closed" | "absent";
+            /** @enum {string} */
+            previous_state: "active" | "closed" | "absent";
+            revoked: boolean;
         };
         SessionScopeRevokeCounts: components["schemas"]["SessionScopeV1RevokeCounts"];
         SessionScopeRevokeResult: components["schemas"]["SessionScopeV1PublicRevokeResult"];
@@ -1359,6 +1387,26 @@ export interface components {
         PluginPermissionList: {
             permissions: components["schemas"]["PluginPermissionGrant"][];
         };
+        PluginPermissionRequirementMethod: {
+            method: string;
+            required_permissions: string[];
+        };
+        PluginPermissionRequirementContract: {
+            contract_id: string;
+            contract_version: string;
+            contract_sha256: string;
+            capability_id: string;
+            capability_version: string;
+            methods: components["schemas"]["PluginPermissionRequirementMethod"][];
+        };
+        PluginPermissionRequirements: {
+            plugin_instance_id: string;
+            plugin_version: string;
+            active_fingerprint: string;
+            management_revision: number;
+            contracts: components["schemas"]["PluginPermissionRequirementContract"][];
+            required_permissions: string[];
+        };
         AuthorizationRevisions: {
             policy_revision: number;
             management_revision: number;
@@ -2105,6 +2153,9 @@ export interface components {
             plugin_instance_id?: string;
             active_only?: boolean;
         };
+        PermissionRequirementsQueryRequest: {
+            plugin_instance_id: string;
+        };
         ListDiagnosticsQueryRequest: {
             plugin_id?: string;
             plugin_instance_id?: string;
@@ -2721,9 +2772,9 @@ export interface components {
                 /** @constant */
                 error_codes_schema_version: "error-codes-v6";
                 /** @constant */
-                performance_contract_version: "performance-contract-v3";
+                performance_contract_version: "performance-contract-v4";
                 /** @constant */
-                performance_evidence_schema_version: "performance-evidence-v3";
+                performance_evidence_schema_version: "performance-evidence-v4";
                 /** @constant */
                 contract_registry_version: "contract-registry-v2";
                 /** @constant */
@@ -3376,6 +3427,15 @@ export interface components {
                 "application/json": components["schemas"]["PermissionListSuccessResponse"];
             };
         };
+        /** @description Active-version permission requirements derived from Host-verified capability contracts. */
+        PermissionRequirementsResponse: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["PermissionRequirementsSuccessResponse"];
+            };
+        };
         /** @description Permission grant mutation result. */
         PermissionMutationResponse: {
             headers: {
@@ -3558,6 +3618,11 @@ export interface components {
                 "application/json": components["schemas"]["ListPermissionsQueryRequest"];
             };
         };
+        PermissionRequirementsQueryRequest: {
+            content: {
+                "application/json": components["schemas"]["PermissionRequirementsQueryRequest"];
+            };
+        };
         ListDiagnosticsQueryRequest: {
             content: {
                 "application/json": components["schemas"]["ListDiagnosticsQueryRequest"];
@@ -4332,6 +4397,19 @@ export interface operations {
             default: components["responses"]["PlatformErrorResponse"];
         };
     };
+    getPluginPermissionRequirements: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["PermissionRequirementsQueryRequest"];
+        responses: {
+            200: components["responses"]["PermissionRequirementsResponse"];
+            default: components["responses"]["PlatformErrorResponse"];
+        };
+    };
     grantPluginPermission: {
         parameters: {
             query?: never;

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;
@@ -50,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"]>;
@@ -89,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"];
@@ -156,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

@@ -214,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);
     }

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.8",
+  "version": "0.6.13",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -32,7 +32,7 @@
     "dist"
   ],
   "dependencies": {
-    "@floegence/redevplugin-contracts": "0.6.8"
+    "@floegence/redevplugin-contracts": "0.6.13"
   },
   "publishConfig": {
     "access": "public"