@floegence/redevplugin-ui 0.4.3 → 0.6.5

package/dist/surface.js

@@ -1,14 +1,17 @@
-import { PluginBridgeError, pluginBridgeErrorCodes } from "./errors.js";
+import { PluginBridgeError, PluginPlatformRequestError, PluginTransportError, pluginBridgeErrorCodes, } from "./errors.js";
+import { pluginBridgeCapabilityEffect, } from "./bridge-capability.js";
 import { pluginUIProtocolVersion } from "./contracts.gen.js";
 import { opaqueSurfaceAllowedTags, opaqueSurfaceGlobalAttributes, opaqueSurfaceRenderLimits, opaqueSurfaceSafeInputTypes, opaqueSurfaceTagAttributes, } from "./opaque-surface-policy.gen.js";
-import { defaultFetch, hasAllowedKeys, hasExactKeys, isRecord, readHostEnvelope, } from "./http.js";
+import { defaultFetch, hasAllowedKeys, hasExactKeys, isRecord, readMutationPlatformResponse, readPlatformResponse, } from "./http.js";
 import { defaultPluginSurfaceScope, registerPluginSurface, } from "./surface-scope.js";
-export const opaqueSurfaceDocumentSchemaVersion = "redevplugin.opaque_surface_document.v2";
+import { PluginUIReconcileError, reconcileValidatedPluginUITrees, validatePluginUITree, } from "./ui-reconciler.js";
+export const opaqueSurfaceDocumentSchemaVersion = "redevplugin.opaque_surface_document.v3";
 export const pluginRiskPlanSchemaVersion = "redevplugin.capability.risk_plan.v1";
-const opaquePluginBridgeGlobalKey = "__redevpluginWorkerBridgeV2";
+const opaquePluginBridgeGlobalKey = "__redevpluginWorkerBridge";
 const maxPendingPluginBridgeRequests = 256;
-const maxPluginBridgeMessageBytes = 256 * 1024;
+const maxPluginBridgeMessageBytes = opaqueSurfaceRenderLimits.max_message_bytes;
 const maxRetainedPluginStreamHandles = 128;
+const maxPluginJSONStructuralNodes = 32 * 1024;
 const streamCredentialInvalidatingErrorCodes = new Set([
     "PLUGIN_BRIDGE_DISPOSED",
     "PLUGIN_BRIDGE_HANDSHAKE_FAILED",
@@ -21,7 +24,7 @@ const streamCredentialInvalidatingErrorCodes = new Set([
     "PLUGIN_GRANT_INVALID",
     "PLUGIN_LEASE_INVALID",
     "PLUGIN_LEASE_REPLAYED",
-    "PLUGIN_STATE_VERSION_MISMATCH",
+    "PLUGIN_MANAGEMENT_REVISION_MISMATCH",
     "PLUGIN_STREAM_CANCELLED",
     "PLUGIN_STREAM_TICKET_INVALID",
     "PLUGIN_TOKEN_EXPIRED",
@@ -49,7 +52,15 @@ export class PluginBridgeClient {
     #readyPromise;
     #resolveReady;
     #rejectReady;
-    #disposed = false;
+    #lifecycleState = "active";
+    #handlingLifecycle = false;
+    #renderRevision = 0;
+    #committedTree;
+    #pendingRender;
+    #renderLoop;
+    #controlEditRevisions = new Map();
+    #pendingStreamDeliveries = new Map();
+    #streamReadTails = new Map();
     #onMessage = (event) => {
         void this.#handleMessage(event);
     };
@@ -72,7 +83,11 @@ export class PluginBridgeClient {
         this.#assertActive();
         return this.#ready ? Promise.resolve() : this.#readyPromise;
     }
-    call(method, params) {
+    call(method, params, options = {}) {
+        const effect = options[pluginBridgeCapabilityEffect];
+        return this.#call(method, params, options, effect === undefined || effect !== "read");
+    }
+    #call(method, params, options, mutation) {
         this.#assertActive();
         if (!validMethod(method)) {
             throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin bridge method and params are invalid");
@@ -91,21 +106,58 @@ export class PluginBridgeClient {
         return this.#request(id, {
             type: "redevplugin.bridge.call",
             request,
-        });
+        }, { mutation, signal: options.signal });
     }
-    readStream(streamHandle) {
+    readStream(streamHandle, options = {}) {
         this.#assertActive();
         if (!validOpaqueHandle(streamHandle, "stream")) {
             throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin stream handle is invalid");
         }
+        const previous = this.#streamReadTails.get(streamHandle);
+        const read = (previous ? previous.catch(() => undefined) : Promise.resolve()).then(() => {
+            this.#assertActive();
+            if (options.signal?.aborted)
+                throw streamReadAbortedError();
+            return this.#readStream(streamHandle, options.signal);
+        });
+        this.#streamReadTails.set(streamHandle, read);
+        void read.finally(() => {
+            if (this.#streamReadTails.get(streamHandle) === read)
+                this.#streamReadTails.delete(streamHandle);
+        }).catch(() => undefined);
+        return abortableStreamRead(read, options.signal);
+    }
+    async #readStream(streamHandle, signal) {
+        const pending = this.#pendingStreamDeliveries.get(streamHandle);
+        if (pending) {
+            await this.#acknowledgeStream(streamHandle, pending.deliveryID, signal);
+            this.#pendingStreamDeliveries.delete(streamHandle);
+            return pending.result;
+        }
         const id = this.#requestID("stream");
-        return this.#request(id, {
+        const privateResult = await this.#request(id, {
             type: "redevplugin.bridge.stream.read",
             id,
             stream_handle: streamHandle,
-        });
+        }, { cancellationKind: "stream", signal });
+        const { delivery_id: deliveryID, ...result } = privateResult;
+        if (!deliveryID)
+            return result;
+        this.#pendingStreamDeliveries.set(streamHandle, { deliveryID, result });
+        await this.#acknowledgeStream(streamHandle, deliveryID, signal);
+        this.#pendingStreamDeliveries.delete(streamHandle);
+        return result;
+    }
+    async #acknowledgeStream(streamHandle, deliveryID, signal) {
+        const id = this.#requestID("stream_ack");
+        await this.#request(id, {
+            type: "redevplugin.bridge.stream.ack",
+            id,
+            stream_handle: streamHandle,
+            delivery_id: deliveryID,
+        }, { cancellationKind: "stream", signal });
     }
-    cancelOperation(operationID, reason) {
+    cancelOperation(operationID, reason, options = {}) {
         this.#assertActive();
         if (!validOpaqueHandle(operationID, "operation") || (reason !== undefined && (typeof reason !== "string" || reason.length > 256))) {
             throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin operation cancellation is invalid");
@@ -116,15 +168,22 @@ export class PluginBridgeClient {
             id,
             operation_id: operationID,
             reason,
-        }));
+        }), { mutation: true, signal: options.signal });
     }
     render(tree) {
         this.#assertActive();
-        const id = this.#requestID("render");
-        return this.#request(id, {
-            type: "redevplugin.ui.render",
-            id,
-            tree,
+        let validated;
+        try {
+            validated = validatePluginUITree(tree);
+        }
+        catch (error) {
+            throw new PluginBridgeError("PLUGIN_UI_PROTOCOL_VIOLATION", error instanceof Error ? error.message : "Plugin UI tree is invalid");
+        }
+        return new Promise((resolve, reject) => {
+            const waiters = this.#pendingRender?.waiters ?? [];
+            waiters.push({ resolve, reject });
+            this.#pendingRender = { tree: validated, waiters };
+            this.#startRenderLoop();
         });
     }
     openCanvas(canvasId) {
@@ -137,7 +196,7 @@ export class PluginBridgeClient {
             type: "redevplugin.ui.canvas.open",
             id,
             canvas_id: canvasId,
-        }, "canvas", canvasId);
+        }, { kind: "canvas", identifier: canvasId });
     }
     updateCanvasAccessibility(canvasId, state) {
         this.#assertActive();
@@ -163,7 +222,7 @@ export class PluginBridgeClient {
             type: "redevplugin.ui.asset.image.open",
             id,
             asset_id: assetId,
-        }, "asset", assetId);
+        }, { kind: "asset", identifier: assetId });
     }
     onAction(action, handler) {
         this.#assertActive();
@@ -201,24 +260,97 @@ export class PluginBridgeClient {
         };
     }
     dispose() {
-        if (this.#disposed)
+        if (this.#lifecycleState === "disposed")
             return;
-        this.#disposed = true;
+        this.#lifecycleState = "disposed";
         const disposedError = new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin bridge client is disposed");
         if (!this.#ready)
             this.#rejectReady(disposedError);
         this.#port.removeEventListener("message", this.#onMessage);
         for (const [id, pending] of this.#pending) {
             clearTimeout(pending.timer);
+            pending.abortCleanup?.();
             pending.reject(new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", `Plugin bridge request ${id} was disposed`));
         }
         this.#pending.clear();
+        this.#pendingStreamDeliveries.clear();
         this.#actionHandlers.clear();
         this.#canvasInputHandlers.clear();
         this.#lifecycleHandlers.clear();
+        for (const waiter of this.#pendingRender?.waiters ?? [])
+            waiter.reject(disposedError);
+        this.#pendingRender = undefined;
+        this.#controlEditRevisions.clear();
         this.#port.close();
     }
-    #request(id, message, kind = "json", identifier) {
+    async #drainRenders() {
+        while (this.#pendingRender && this.#acceptsPluginWork()) {
+            const pending = this.#pendingRender;
+            this.#pendingRender = undefined;
+            const id = this.#requestID("render");
+            const nextRevision = this.#renderRevision + 1;
+            try {
+                if (!this.#committedTree) {
+                    await this.#request(id, {
+                        type: "redevplugin.ui.mount",
+                        id,
+                        revision: 1,
+                        tree: pending.tree,
+                    });
+                }
+                else {
+                    const operations = reconcileValidatedPluginUITrees(this.#committedTree, pending.tree, {
+                        controlEditRevisions: this.#controlEditRevisions,
+                    });
+                    if (operations.length > 0) {
+                        await this.#request(id, {
+                            type: "redevplugin.ui.patch",
+                            id,
+                            base_revision: this.#renderRevision,
+                            revision: nextRevision,
+                            operations,
+                        });
+                        this.#renderRevision = nextRevision;
+                    }
+                }
+                this.#committedTree = pending.tree;
+                if (this.#renderRevision === 0)
+                    this.#renderRevision = 1;
+                for (const waiter of pending.waiters)
+                    waiter.resolve();
+            }
+            catch (error) {
+                const bridgeError = error instanceof PluginUIReconcileError
+                    ? new PluginBridgeError("PLUGIN_UI_PROTOCOL_VIOLATION", error.message)
+                    : error;
+                for (const waiter of pending.waiters)
+                    waiter.reject(bridgeError);
+                const queued = this.#pendingRender;
+                for (const waiter of queued?.waiters ?? [])
+                    waiter.reject(bridgeError);
+                this.#pendingRender = undefined;
+                throw bridgeError;
+            }
+        }
+        if (this.#pendingRender) {
+            const error = new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin UI cannot render after quiescing starts");
+            for (const waiter of this.#pendingRender.waiters)
+                waiter.reject(error);
+            this.#pendingRender = undefined;
+        }
+    }
+    #startRenderLoop() {
+        if (this.#renderLoop)
+            return;
+        this.#renderLoop = this.#drainRenders()
+            .catch(() => undefined)
+            .finally(() => {
+            this.#renderLoop = undefined;
+            if (this.#pendingRender)
+                this.#startRenderLoop();
+        });
+    }
+    #request(id, message, options = {}) {
         let normalizedMessage;
         try {
             normalizedMessage = normalizePluginJSONObject(message);
@@ -232,9 +364,13 @@ export class PluginBridgeClient {
         if (this.#pending.size >= maxPendingPluginBridgeRequests) {
             throw new PluginBridgeError("PLUGIN_JSON_LIMIT_EXCEEDED", "Plugin bridge has too many pending requests");
         }
+        if (options.signal?.aborted)
+            return Promise.reject(requestCancelledError(options, false));
+        let posted = false;
         const result = new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
-                if (!this.#pending.delete(id))
+                const pending = this.#takePending(id);
+                if (!pending)
                     return;
                 try {
                     this.#port.postMessage({ type: "redevplugin.bridge.cancel", id });
@@ -242,39 +378,65 @@ export class PluginBridgeClient {
                 catch {
                     // The request is already locally cancelled when the port closes concurrently.
                 }
-                reject(new PluginBridgeError("PLUGIN_BRIDGE_TIMEOUT", `Plugin bridge request ${id} timed out`));
+                pending.reject(new PluginBridgeError("PLUGIN_BRIDGE_TIMEOUT", `Plugin bridge request ${id} timed out`, undefined, undefined, mutationOutcome(options, posted)));
             }, this.timeoutMs);
+            const onAbort = () => {
+                const pending = this.#takePending(id);
+                if (!pending)
+                    return;
+                if (posted) {
+                    try {
+                        this.#port.postMessage({ type: "redevplugin.bridge.cancel", id });
+                    }
+                    catch {
+                        // The request is already locally cancelled when the port closes concurrently.
+                    }
+                }
+                pending.reject(requestCancelledError(options, posted));
+            };
             this.#pending.set(id, {
                 resolve: (value) => resolve(value),
                 reject,
                 timer,
-                kind,
-                identifier,
+                abortCleanup: options.signal ? () => options.signal?.removeEventListener("abort", onAbort) : undefined,
+                kind: options.kind ?? "json",
+                identifier: options.identifier,
             });
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+            if (options.signal?.aborted)
+                onAbort();
         });
+        if (!this.#pending.has(id))
+            return result;
         try {
             this.#port.postMessage(normalizedMessage);
+            posted = true;
         }
         catch {
-            const pending = this.#pending.get(id);
+            const pending = this.#takePending(id);
             if (pending) {
-                this.#pending.delete(id);
-                clearTimeout(pending.timer);
-                pending.reject(new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", `Plugin bridge request ${id} could not be posted`));
+                pending.reject(new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", `Plugin bridge request ${id} could not be posted`, undefined, undefined, options.mutation ? "not_committed" : undefined));
             }
         }
         return result;
     }
+    #takePending(id) {
+        const pending = this.#pending.get(id);
+        if (!pending)
+            return undefined;
+        this.#pending.delete(id);
+        clearTimeout(pending.timer);
+        pending.abortCleanup?.();
+        return pending;
+    }
     async #handleMessage(event) {
-        if (this.#disposed)
+        if (this.#lifecycleState === "disposed")
             return;
         const data = event.data;
         if (isCanvasReadyCandidate(data)) {
-            const pending = this.#pending.get(data.id);
+            const pending = this.#takePending(data.id);
             if (!pending)
                 return;
-            this.#pending.delete(data.id);
-            clearTimeout(pending.timer);
             if (pending.kind !== "canvas" || pending.identifier !== data.canvas_id || !isCanvasReadyMessage(data)) {
                 pending.reject(new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", `Plugin canvas response ${data.id} is invalid`));
                 return;
@@ -289,11 +451,9 @@ export class PluginBridgeClient {
             return;
         }
         if (isImageReadyCandidate(data)) {
-            const pending = this.#pending.get(data.id);
+            const pending = this.#takePending(data.id);
             if (!pending)
                 return;
-            this.#pending.delete(data.id);
-            clearTimeout(pending.timer);
             if (pending.kind !== "asset" || pending.identifier !== data.asset_id || !isImageReadyMessage(data)) {
                 pending.reject(new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", `Plugin image response ${data.id} is invalid`));
                 return;
@@ -304,11 +464,9 @@ export class PluginBridgeClient {
         if (!messageWithinLimit(data))
             return;
         if (isBridgeResponseCandidate(data)) {
-            const pending = this.#pending.get(data.id);
+            const pending = this.#takePending(data.id);
             if (!pending)
                 return;
-            this.#pending.delete(data.id);
-            clearTimeout(pending.timer);
             if (!isBridgeResponse(data)) {
                 pending.reject(new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", `Plugin bridge response ${data.id} is invalid`));
                 return;
@@ -319,7 +477,7 @@ export class PluginBridgeClient {
             else if (data.ok)
                 pending.resolve(data.data);
             else
-                pending.reject(new PluginBridgeError(data.error_code, data.error, undefined, data.error_details));
+                pending.reject(new PluginBridgeError(data.error_code, data.error, undefined, data.error_details, data.mutation_outcome));
             return;
         }
         if (isLifecycleMessage(data)) {
@@ -327,6 +485,9 @@ export class PluginBridgeClient {
                 this.#ready = true;
                 this.#resolveReady();
             }
+            if (data.quiesce_id)
+                this.#lifecycleState = "quiescing";
+            this.#handlingLifecycle = true;
             await Promise.allSettled(Array.from(this.#lifecycleHandlers, async (handler) => {
                 try {
                     await handler(data.event);
@@ -335,19 +496,23 @@ export class PluginBridgeClient {
                     // A plugin lifecycle observer cannot block bounded surface teardown.
                 }
             }));
+            this.#handlingLifecycle = false;
             if (data.quiesce_id) {
                 this.#port.postMessage({
                     type: "redevplugin.bridge.lifecycle_ack",
                     quiesce_id: data.quiesce_id,
                 });
+                this.#lifecycleState = "quiesced";
             }
-            if (data.event.type === "dispose")
+            if (data.event.type === "dispose" && !data.quiesce_id)
                 this.dispose();
             return;
         }
         if (isActionMessage(data)) {
+            this.#controlEditRevisions.set(data.target_key, data.edit_revision);
+            const action = publicActionEvent(data);
             for (const handler of this.#actionHandlers.get(data.action) ?? [])
-                handler(data);
+                handler(action);
             return;
         }
         const canvasInput = publicCanvasInputMessage(data);
@@ -360,10 +525,14 @@ export class PluginBridgeClient {
         return `${prefix}_${this.#nextID++}`;
     }
     #assertActive() {
-        if (this.#disposed) {
+        if (!this.#acceptsPluginWork()) {
             throw new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin bridge client is disposed");
         }
     }
+    #acceptsPluginWork() {
+        return this.#lifecycleState === "active" ||
+            (this.#lifecycleState === "quiescing" && this.#handlingLifecycle);
+    }
 }
 export const defaultPluginSurfaceReloadMax = 2;
 export const defaultPluginSurfaceReloadWindowMs = 30_000;
@@ -449,14 +618,14 @@ export async function trustedParentBridgeHandshakeTranscriptSHA256(handshake, br
     }
     const encoder = new TextEncoder();
     const fields = [
-        "redevplugin.bridge.handshake.v2",
+        "redevplugin.bridge.handshake.v3",
         handshake.plugin_id,
         handshake.surface_id,
         handshake.surface_instance_id,
         handshake.active_fingerprint,
         handshake.bridge_nonce,
         handshake.asset_session_nonce,
-        String(handshake.plugin_state_version),
+        String(handshake.management_revision),
         String(handshake.revoke_epoch),
         handshake.ui_protocol_version,
         bridgeChannelID,
@@ -488,6 +657,53 @@ export function createReDevPluginSurfaceTransport(options = {}) {
     });
     return transport;
 }
+function requireSurfaceTransportInternals(transport) {
+    const internals = surfaceTransportInternals.get(transport);
+    if (!internals) {
+        throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface host transport is invalid");
+    }
+    return internals;
+}
+async function revokeSurfaceBootstrap(transport, bootstrap, timeoutMs, keepalive) {
+    const path = `/_redevplugin/api/plugins/surfaces/${encodeURIComponent(bootstrap.surfaceInstanceId)}/dispose`;
+    const controller = new AbortController();
+    let timedOut = false;
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+            reject(new PluginBridgeError("PLUGIN_BRIDGE_TIMEOUT", `Plugin surface request timed out: ${path}`, undefined, undefined, "unknown"));
+        }, timeoutMs);
+    });
+    try {
+        const response = await Promise.race([
+            transport.fetch(transport.apiBaseURL + path, {
+                method: "POST",
+                headers: { "Accept": "application/json", "Content-Type": "application/json" },
+                body: JSON.stringify({ bridge_nonce: bootstrap.bridgeNonce }),
+                credentials: "same-origin",
+                signal: controller.signal,
+                keepalive,
+            }),
+            timeout,
+        ]);
+        await readMutationPlatformResponse(response);
+    }
+    catch (error) {
+        if (timedOut) {
+            throw new PluginBridgeError("PLUGIN_BRIDGE_TIMEOUT", `Plugin surface request timed out: ${path}`, undefined, undefined, "unknown");
+        }
+        if (error instanceof PluginBridgeError || error instanceof PluginPlatformRequestError || error instanceof PluginTransportError) {
+            throw error;
+        }
+        throw new PluginTransportError(`Plugin surface request failed for POST ${path}`, error, "unknown");
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 export function createOpaquePluginBootstrapHTML(options = {}) {
     const scriptNonce = options.scriptNonce ?? randomOpaqueNonce();
     if (!/^[A-Za-z0-9_-]{8,128}$/.test(scriptNonce)) {
@@ -520,6 +736,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   const maxRendersPerSecond = ${opaqueSurfaceRenderLimits.max_renders_per_second};
   const maxRenderDepth = ${opaqueSurfaceRenderLimits.max_render_depth};
   const maxRenderNodes = ${opaqueSurfaceRenderLimits.max_render_nodes};
+  const maxPatchOperations = ${opaqueSurfaceRenderLimits.max_patch_operations};
   const maxAttributesPerElement = ${opaqueSurfaceRenderLimits.max_attributes_per_element};
   const maxTextLength = ${opaqueSurfaceRenderLimits.max_text_length};
   const maxAttributeValueLength = ${opaqueSurfaceRenderLimits.max_attribute_value_length};
@@ -553,7 +770,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
   const canonicalJSON = (value, depth = 0, state = { nodes: 0 }, seen = new Set()) => {
     state.nodes += 1;
-    if (state.nodes > 4096 || depth > 64) return false;
+    if (state.nodes > ${maxPluginJSONStructuralNodes} || depth > 64) return false;
     if (value === null || typeof value === "string" || typeof value === "boolean") return true;
     if (typeof value === "number") return Number.isFinite(value);
     if (typeof value !== "object" || seen.has(value)) return false;
@@ -581,6 +798,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   const validIdentifier = (value) => typeof value === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(value);
   const validResourceIdentifier = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value);
   const validOpaqueHandle = (value, prefix) => typeof value === "string" && value.startsWith(prefix + "_") && /^[A-Za-z0-9_-]{8,160}$/.test(value);
+  const validDeliveryID = (value) => typeof value === "string" && /^delivery_[A-Za-z0-9_-]{8,128}$/.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 validAttribute = (tag, name, value) => {
@@ -635,9 +853,13 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   let workerHeartbeatTimeout;
   let pendingQuiesceID;
   const pendingWorkerRequests = new Set();
-  const requestSequence = { rpc: 0, stream: 0, render: 0, operation: 0, canvas: 0, asset: 0 };
+  const requestSequence = { rpc: 0, stream: 0, stream_ack: 0, render: 0, operation: 0, canvas: 0, asset: 0 };
   let renderWindowStartedAt = 0;
   let renderCount = 0;
+  let uiRevision = 0;
+  let uiGraph = new Map();
+  let uiNodes = new Map();
+  const controlEdits = new Map();
   let lastAutofocusIdentity = "";
   const pendingAssets = new Map();
   const queuedAssets = [];
@@ -712,6 +934,27 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     verifiedAssetBytes.clear();
     assetByLogicalID.clear();
   };
+  const terminateQuiescedWorker = () => {
+    if (workerHeartbeatTimer) clearTimeout(workerHeartbeatTimer);
+    if (workerHeartbeatTimeout) clearTimeout(workerHeartbeatTimeout);
+    workerHeartbeatTimer = undefined;
+    workerHeartbeatTimeout = undefined;
+    workerHeartbeatPendingID = undefined;
+    workerReady = false;
+    if (workerControlPort) {
+      workerControlPort.close();
+      workerControlPort = undefined;
+    }
+    if (workerPort) {
+      workerPort.close();
+      workerPort = undefined;
+    }
+    if (worker) {
+      worker.terminate();
+      worker = undefined;
+    }
+    pendingWorkerRequests.clear();
+  };
   const validateCanvasIdentifiers = (root) => {
     const identifiers = new Set();
     let totalPixels = 0;
@@ -749,39 +992,96 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
       document.head.append(style);
     }
   };
-  const buildWorkerNode = (value, state, depth) => {
+  const applyWorkerAttribute = (element, tag, name, attributeValue) => {
+    const lower = name.toLowerCase();
+    if (!validAttribute(tag, name, attributeValue)) throw new Error("plugin render attribute is not allowed");
+    if (lower === "value" && "value" in element) element.value = String(attributeValue);
+    if (lower === "checked" && "checked" in element) element.checked = attributeValue === true;
+    if (lower === "autofocus") {
+      if (attributeValue !== false) element.setAttribute("data-redevplugin-renderer-autofocus", "");
+      else element.removeAttribute("data-redevplugin-renderer-autofocus");
+      return;
+    }
+    if (typeof attributeValue === "boolean") {
+      const serialized = lower.startsWith("aria-") ? String(attributeValue) : "";
+      if (attributeValue || serialized) element.setAttribute(name, serialized);
+      else element.removeAttribute(name);
+      return;
+    }
+    element.setAttribute(name, String(attributeValue));
+  };
+  const buildWorkerSubtree = (value, state, depth, parentKey, graph = new Map(), nodes = new Map()) => {
     state.nodes += 1;
-    if (state.nodes > maxRenderNodes || depth > maxRenderDepth) throw new Error("plugin render tree exceeds limits");
-    if (typeof value === "string") {
-      if (value.length > maxTextLength) throw new Error("plugin render text exceeds limits");
-      return document.createTextNode(value);
+    if (state.nodes > maxRenderNodes || depth > maxRenderDepth || !isRecord(value) || typeof value.key !== "string" ||
+        !validResourceIdentifier(value.key) || graph.has(value.key)) {
+      throw new Error("plugin render tree exceeds limits or contains an invalid key");
+    }
+    if (value.type === "text") {
+      if (!exactKeys(value, ["type", "key", "text"]) || typeof value.text !== "string" || value.text.length > maxTextLength) {
+        throw new Error("plugin render text node is invalid");
+      }
+      const node = document.createTextNode(value.text);
+      graph.set(value.key, {
+        key: value.key,
+        type: "text",
+        text: value.text,
+        parentKey,
+        prevKey: null,
+        nextKey: null,
+        firstChildKey: null,
+        lastChildKey: null,
+        height: 1,
+        heightDirty: false,
+      });
+      nodes.set(value.key, node);
+      return { node, graph, nodes };
+    }
+    if (!Object.keys(value).every((key) => ["type", "key", "tag", "attributes", "children"].includes(key)) ||
+        value.type !== "element" || typeof value.tag !== "string") {
+      throw new Error("plugin render node is invalid");
     }
-    if (!exactKeys(value, Object.prototype.hasOwnProperty.call(value, "attributes") && Object.prototype.hasOwnProperty.call(value, "children") ? ["type", "tag", "attributes", "children"] : Object.prototype.hasOwnProperty.call(value, "attributes") ? ["type", "tag", "attributes"] : Object.prototype.hasOwnProperty.call(value, "children") ? ["type", "tag", "children"] : ["type", "tag"]) || value.type !== "element" || typeof value.tag !== "string") throw new Error("plugin render node is invalid");
     const tag = value.tag.toLowerCase();
     if (!allowedTags.has(tag)) throw new Error("plugin render tag is not allowed");
-    const element = document.createElement(tag);
+    const attributes = {};
     if (value.attributes !== undefined) {
       if (!isRecord(value.attributes) || Object.keys(value.attributes).length > maxAttributesPerElement) throw new Error("plugin render attributes are invalid");
       for (const [name, attributeValue] of Object.entries(value.attributes)) {
-        const lower = name.toLowerCase();
         if (!validAttribute(tag, name, attributeValue)) throw new Error("plugin render attribute is not allowed");
-        if (lower === "autofocus") {
-          if (attributeValue !== false) element.setAttribute("data-redevplugin-renderer-autofocus", "");
-          continue;
-        }
-        if (typeof attributeValue === "boolean") {
-          const serialized = lower.startsWith("aria-") ? String(attributeValue) : "";
-          if (attributeValue || serialized) element.setAttribute(name, serialized);
-        } else {
-          element.setAttribute(name, String(attributeValue));
-        }
+        attributes[name] = attributeValue;
       }
     }
-    if (value.children !== undefined) {
-      if (!Array.isArray(value.children)) throw new Error("plugin render children are invalid");
-      for (const child of value.children) element.append(buildWorkerNode(child, state, depth + 1));
-    }
-    return element;
+    if (value.children !== undefined && !Array.isArray(value.children)) throw new Error("plugin render children are invalid");
+    const element = document.createElement(tag);
+    element.setAttribute("data-redevplugin-key", value.key);
+    for (const [name, attributeValue] of Object.entries(attributes)) applyWorkerAttribute(element, tag, name, attributeValue);
+    const record = {
+      key: value.key,
+      type: "element",
+      tag,
+      attributes,
+      parentKey,
+      prevKey: null,
+      nextKey: null,
+      firstChildKey: null,
+      lastChildKey: null,
+      height: 1,
+      heightDirty: false,
+    };
+    graph.set(value.key, record);
+    nodes.set(value.key, element);
+    let previousKey = null;
+    for (const child of value.children || []) {
+      const built = buildWorkerSubtree(child, state, depth + 1, value.key, graph, nodes);
+      const childRecord = graph.get(child.key);
+      childRecord.prevKey = previousKey;
+      if (previousKey) graph.get(previousKey).nextKey = child.key;
+      else record.firstChildKey = child.key;
+      record.lastChildKey = child.key;
+      record.height = Math.max(record.height, childRecord.height + 1);
+      previousKey = child.key;
+      element.append(built.node);
+    }
+    return { node: element, graph, nodes };
   };
   const renderElementIdentity = (element) => ({
     tag: element.tagName,
@@ -845,22 +1145,328 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     document.body.scrollTop = snapshot.bodyScrollTop;
     document.body.scrollLeft = snapshot.bodyScrollLeft;
   };
-  const applyWorkerRender = (tree) => {
-    if (canvasRuntimes.size > 0) throw new Error("plugin render cannot replace an active transferred canvas");
-    const values = Array.isArray(tree) ? tree : [tree];
-    const fragment = document.createDocumentFragment();
-    const state = { nodes: 0 };
-    for (const value of values) fragment.append(buildWorkerNode(value, state, 1));
-    validateCanvasIdentifiers(fragment);
+  const transferredCanvasKey = (key) => {
+    const element = uiNodes.get(key);
+    if (!(element instanceof HTMLCanvasElement)) return false;
+    for (const runtime of canvasRuntimes.values()) if (runtime.canvas === element) return true;
+    return false;
+  };
+  const editableControlAttribute = (tag, name) => {
+    const normalized = name.toLowerCase();
+    return (normalized === "value" && ["input", "textarea", "select", "option"].includes(tag)) ||
+      (normalized === "checked" && tag === "input");
+  };
+  const createGraphOverlay = (base) => {
+    const changed = new Map();
+    const deleted = new Set();
+    let count = base.size;
+    const get = (key) => changed.has(key) ? changed.get(key) : deleted.has(key) ? undefined : base.get(key);
+    const edit = (key) => {
+      const current = get(key);
+      if (!current) throw new Error("plugin UI patch target does not exist");
+      if (changed.has(key)) return current;
+      const copy = { ...current, ...(current.attributes ? { attributes: { ...current.attributes } } : {}) };
+      changed.set(key, copy);
+      return copy;
+    };
+    const add = (record) => {
+      if (get(record.key)) throw new Error("plugin UI insertion duplicates a key");
+      changed.set(record.key, { ...record, ...(record.attributes ? { attributes: { ...record.attributes } } : {}) });
+      count += 1;
+    };
+    const remove = (key) => {
+      if (!get(key)) throw new Error("plugin UI removal target does not exist");
+      changed.delete(key);
+      if (base.has(key)) deleted.add(key);
+      count -= 1;
+    };
+    const commit = () => {
+      for (const key of deleted) base.delete(key);
+      for (const [key, record] of changed) base.set(key, record);
+    };
+    return { get, edit, add, remove, commit, count: () => count };
+  };
+  const graphDepth = (graph, key) => {
+    let depth = 0;
+    let cursor = graph.get(key);
+    const seen = new Set();
+    while (cursor) {
+      if (seen.has(cursor.key)) throw new Error("plugin UI graph contains a cycle");
+      seen.add(cursor.key);
+      depth += 1;
+      cursor = cursor.parentKey ? graph.get(cursor.parentKey) : undefined;
+    }
+    return depth;
+  };
+  const graphSubtreeKeys = (graph, rootKey) => {
+    const keys = [];
+    const stack = [rootKey];
+    while (stack.length > 0) {
+      const key = stack.pop();
+      const record = key && graph.get(key);
+      if (!record) throw new Error("plugin UI graph is inconsistent");
+      keys.push(key);
+      const children = [];
+      let childKey = record.firstChildKey;
+      while (childKey) {
+        const child = graph.get(childKey);
+        if (!child || child.parentKey !== key) throw new Error("plugin UI child graph is inconsistent");
+        children.push(childKey);
+        childKey = child.nextKey;
+      }
+      stack.push(...children.reverse());
+    }
+    return keys;
+  };
+  const graphSubtreeHeight = (graph, rootKey) => {
+    const record = graph.get(rootKey);
+    if (!record) throw new Error("plugin UI graph is inconsistent");
+    if (!record.heightDirty) return record.height;
+    let height = 1;
+    let childKey = record.firstChildKey;
+    while (childKey) {
+      const child = graph.get(childKey);
+      if (!child || child.parentKey !== rootKey) throw new Error("plugin UI child graph is inconsistent");
+      height = Math.max(height, graphSubtreeHeight(graph, childKey) + 1);
+      childKey = child.nextKey;
+    }
+    const edited = graph.edit(rootKey);
+    edited.height = height;
+    edited.heightDirty = false;
+    return height;
+  };
+  const graphParentChainContains = (graph, rootKey, targetKey) => {
+    let cursor = graph.get(rootKey);
+    const seen = new Set();
+    while (cursor) {
+      if (cursor.key === targetKey) return true;
+      if (seen.has(cursor.key)) throw new Error("plugin UI graph contains a cycle");
+      seen.add(cursor.key);
+      cursor = cursor.parentKey ? graph.get(cursor.parentKey) : undefined;
+    }
+    return false;
+  };
+  const graphSubtreeHasTransferredCanvas = (graph, rootKey) => {
+    for (const runtime of canvasRuntimes.values()) {
+      const key = runtime.canvas.getAttribute("data-redevplugin-key");
+      if (!key) continue;
+      let cursor = graph.get(key);
+      const seen = new Set();
+      while (cursor) {
+        if (cursor.key === rootKey) return true;
+        if (seen.has(cursor.key)) throw new Error("plugin UI graph contains a cycle");
+        seen.add(cursor.key);
+        cursor = cursor.parentKey ? graph.get(cursor.parentKey) : undefined;
+      }
+    }
+    return false;
+  };
+  const markGraphHeightDirty = (graph, key) => {
+    let cursorKey = key;
+    const seen = new Set();
+    while (cursorKey) {
+      if (seen.has(cursorKey)) throw new Error("plugin UI graph contains a cycle");
+      seen.add(cursorKey);
+      const record = graph.edit(cursorKey);
+      record.heightDirty = true;
+      cursorKey = record.parentKey;
+    }
+  };
+  const detachGraphNode = (graph, key) => {
+    const record = graph.edit(key);
+    if (!record.parentKey) throw new Error("plugin UI root cannot be detached");
+    const parentKey = record.parentKey;
+    const parent = graph.edit(parentKey);
+    if (record.prevKey) graph.edit(record.prevKey).nextKey = record.nextKey;
+    else parent.firstChildKey = record.nextKey;
+    if (record.nextKey) graph.edit(record.nextKey).prevKey = record.prevKey;
+    else parent.lastChildKey = record.prevKey;
+    record.parentKey = undefined;
+    record.prevKey = null;
+    record.nextKey = null;
+    markGraphHeightDirty(graph, parentKey);
+  };
+  const attachGraphNode = (graph, key, parentKey, beforeKey) => {
+    const record = graph.edit(key);
+    const parent = graph.edit(parentKey);
+    if (parent.type !== "element" || record.parentKey) throw new Error("plugin UI insertion parent is invalid");
+    let previousKey = parent.lastChildKey;
+    if (beforeKey !== null) {
+      if (beforeKey === key) throw new Error("plugin UI anchor cannot target the moved node");
+      const before = graph.get(beforeKey);
+      if (!before || before.parentKey !== parentKey) throw new Error("plugin UI anchor is invalid");
+      previousKey = before.prevKey;
+      graph.edit(beforeKey).prevKey = key;
+    } else {
+      parent.lastChildKey = key;
+    }
+    if (previousKey) graph.edit(previousKey).nextKey = key;
+    else parent.firstChildKey = key;
+    record.parentKey = parentKey;
+    record.prevKey = previousKey;
+    record.nextKey = beforeKey;
+    if (beforeKey === null) parent.lastChildKey = key;
+    markGraphHeightDirty(graph, parentKey);
+  };
+  const validatePatch = (operations) => {
+    if (!Array.isArray(operations) || operations.length > maxPatchOperations) throw new Error("plugin UI patch exceeds limits");
+    const graph = createGraphOverlay(uiGraph);
+    const plan = [];
+    for (const operation of operations) {
+      if (!isRecord(operation) || typeof operation.type !== "string") throw new Error("plugin UI patch operation is invalid");
+      if (operation.type === "set_text") {
+        if (!exactKeys(operation, ["type", "target_key", "text"]) || !validResourceIdentifier(operation.target_key) ||
+            typeof operation.text !== "string" || operation.text.length > maxTextLength) throw new Error("plugin UI text patch is invalid");
+        const target = graph.edit(operation.target_key);
+        if (target.type !== "text") throw new Error("plugin UI text patch target is invalid");
+        target.text = operation.text;
+        plan.push(operation);
+      } else if (operation.type === "patch_attributes") {
+        if (!exactKeys(operation, ["type", "target_key", "set", "remove"]) || !validResourceIdentifier(operation.target_key) ||
+            !isRecord(operation.set) || Object.keys(operation.set).length > maxAttributesPerElement || !Array.isArray(operation.remove) ||
+            operation.remove.length > maxAttributesPerElement || new Set(operation.remove).size !== operation.remove.length ||
+            operation.remove.some((name) => typeof name !== "string")) throw new Error("plugin UI attribute patch is invalid");
+        const target = graph.edit(operation.target_key);
+        if (target.type !== "element" || transferredCanvasKey(target.key) || Object.keys(operation.set).some((name) => editableControlAttribute(target.tag, name)) ||
+            operation.remove.some((name) => editableControlAttribute(target.tag, name))) throw new Error("plugin UI attribute patch target is invalid");
+        target.attributes ||= {};
+        for (const [name, value] of Object.entries(operation.set)) {
+          if (!validAttribute(target.tag, name, value)) throw new Error("plugin UI attribute patch is not allowed");
+          target.attributes[name] = value;
+        }
+        for (const name of operation.remove) delete target.attributes[name];
+        plan.push(operation);
+      } else if (operation.type === "patch_control") {
+        if (!Object.keys(operation).every((key) => ["type", "target_key", "edit_revision", "value", "checked"].includes(key)) ||
+            !validResourceIdentifier(operation.target_key) || !Number.isSafeInteger(operation.edit_revision) || operation.edit_revision < 0 ||
+            (operation.value === undefined && operation.checked === undefined) ||
+            (operation.value !== undefined && operation.value !== null && typeof operation.value !== "string") ||
+            (operation.checked !== undefined && operation.checked !== null && typeof operation.checked !== "boolean")) throw new Error("plugin UI control patch is invalid");
+        const target = graph.edit(operation.target_key);
+        if (target.type !== "element" || !["input", "textarea", "select", "option"].includes(target.tag)) throw new Error("plugin UI control patch target is invalid");
+        target.attributes ||= {};
+        if (operation.value !== undefined) operation.value === null ? delete target.attributes.value : target.attributes.value = operation.value;
+        if (operation.checked !== undefined) operation.checked === null ? delete target.attributes.checked : target.attributes.checked = operation.checked;
+        plan.push(operation);
+      } else if (operation.type === "insert_child") {
+        if (!exactKeys(operation, ["type", "parent_key", "before_key", "node"]) || !validResourceIdentifier(operation.parent_key) ||
+            (operation.before_key !== null && !validResourceIdentifier(operation.before_key))) throw new Error("plugin UI insertion is invalid");
+        const parent = graph.get(operation.parent_key);
+        if (!parent || parent.type !== "element") throw new Error("plugin UI insertion target is invalid");
+        const state = { nodes: 0 };
+        const built = buildWorkerSubtree(operation.node, state, graphDepth(graph, operation.parent_key) + 1, undefined);
+        if (graph.count() + state.nodes > maxRenderNodes) throw new Error("plugin UI insertion exceeds node limits");
+        for (const record of built.graph.values()) graph.add(record);
+        attachGraphNode(graph, operation.node.key, operation.parent_key, operation.before_key);
+        plan.push({ ...operation, built });
+      } else if (operation.type === "remove_child") {
+        if (!exactKeys(operation, ["type", "target_key"]) || !validResourceIdentifier(operation.target_key)) throw new Error("plugin UI removal is invalid");
+        const target = graph.get(operation.target_key);
+        if (!target || !target.parentKey) throw new Error("plugin UI removal target is invalid");
+        if (graphSubtreeHasTransferredCanvas(graph, operation.target_key)) throw new Error("transferred canvas cannot be removed");
+        const removedKeys = graphSubtreeKeys(graph, operation.target_key);
+        detachGraphNode(graph, operation.target_key);
+        for (const key of removedKeys) graph.remove(key);
+        plan.push({ ...operation, removedKeys });
+      } else if (operation.type === "move_child") {
+        if (!exactKeys(operation, ["type", "target_key", "parent_key", "before_key"]) || !validResourceIdentifier(operation.target_key) ||
+            !validResourceIdentifier(operation.parent_key) || (operation.before_key !== null && !validResourceIdentifier(operation.before_key))) {
+          throw new Error("plugin UI move is invalid");
+        }
+        const target = graph.get(operation.target_key);
+        const parent = graph.get(operation.parent_key);
+        if (!target || !target.parentKey || !parent || parent.type !== "element" ||
+            graphParentChainContains(graph, operation.parent_key, operation.target_key) ||
+            graphSubtreeHasTransferredCanvas(graph, operation.target_key)) throw new Error("plugin UI move target is invalid");
+        if (graphDepth(graph, operation.parent_key) + graphSubtreeHeight(graph, operation.target_key) > maxRenderDepth) {
+          throw new Error("plugin UI move exceeds depth limits");
+        }
+        detachGraphNode(graph, operation.target_key);
+        attachGraphNode(graph, operation.target_key, operation.parent_key, operation.before_key);
+        plan.push(operation);
+      } else {
+        throw new Error("plugin UI patch operation type is unsupported");
+      }
+    }
+    return { graph, plan };
+  };
+  const applyPatchOperation = (operation) => {
+    const parent = operation.parent_key && uiNodes.get(operation.parent_key);
+    const target = operation.target_key && uiNodes.get(operation.target_key);
+    if (operation.type === "set_text") {
+      target.nodeValue = operation.text;
+    } else if (operation.type === "patch_attributes") {
+      for (const name of operation.remove) {
+        target.removeAttribute(name);
+        if (name.toLowerCase() === "autofocus") target.removeAttribute("data-redevplugin-renderer-autofocus");
+      }
+      for (const [name, value] of Object.entries(operation.set)) applyWorkerAttribute(target, target.tagName.toLowerCase(), name, value);
+    } else if (operation.type === "patch_control") {
+      const edit = controlEdits.get(operation.target_key) || { revision: 0, isComposing: false };
+      if (edit.revision !== operation.edit_revision || edit.isComposing) return;
+      if (operation.value !== undefined && "value" in target) target.value = operation.value === null ? "" : operation.value;
+      if (operation.checked !== undefined && "checked" in target) target.checked = operation.checked === true;
+    } else if (operation.type === "insert_child") {
+      const before = operation.before_key === null ? null : uiNodes.get(operation.before_key);
+      parent.insertBefore(operation.built.node, before || null);
+      for (const [key, node] of operation.built.nodes) uiNodes.set(key, node);
+    } else if (operation.type === "remove_child") {
+      for (const key of operation.removedKeys) uiNodes.delete(key);
+      target.remove();
+    } else if (operation.type === "move_child") {
+      const before = operation.before_key === null ? null : uiNodes.get(operation.before_key);
+      parent.insertBefore(target, before || null);
+    }
+  };
+  const onAnimationFrame = (commit) => new Promise((resolve, reject) => requestAnimationFrame(() => {
+    try { commit(); resolve(); } catch (error) { reject(error); }
+  }));
+  const mountWorkerTree = async (tree) => {
+    if (uiRevision !== 0) throw new Error("plugin UI mount may only occur once");
+    const built = buildWorkerSubtree(tree, { nodes: 0 }, 1, undefined);
+    const root = built.node;
+    if (!(root instanceof Element)) throw new Error("plugin UI root must be an element");
+    validateCanvasIdentifiers(root);
     const renderState = captureRenderState();
-    document.body.replaceChildren(fragment);
-    restoreRenderState(renderState);
+    await onAnimationFrame(() => {
+      document.body.replaceChildren(root);
+      restoreRenderState(renderState);
+    });
+    uiGraph = built.graph;
+    uiNodes = built.nodes;
+    uiRevision = 1;
+    sendParent({ type: "redevplugin.surface.first_commit" });
+  };
+  const patchWorkerTree = async (baseRevision, revision, operations) => {
+    if (uiRevision < 1 || baseRevision !== uiRevision || revision !== baseRevision + 1) throw new Error("plugin UI patch revision is invalid");
+    const validated = validatePatch(operations);
+    const renderState = captureRenderState();
+    await onAnimationFrame(() => {
+      for (const operation of validated.plan) applyPatchOperation(operation);
+      validated.graph.commit();
+      restoreRenderState(renderState);
+    });
+    uiRevision = revision;
   };
   const actionPayload = (event, element, eventType = event.type) => {
-    const payload = { type: "redevplugin.ui.action", action: element.getAttribute("data-redevplugin-action"), event: eventType };
-    const target = event.target;
-    if (target && typeof target.value === "string") payload.value = target.value.slice(0, maxTextLength);
-    if (target && typeof target.checked === "boolean") payload.checked = target.checked;
+    const target = event.target instanceof Element ? event.target.closest("[data-redevplugin-key]") : element;
+    const targetKey = target?.getAttribute("data-redevplugin-key") || element.getAttribute("data-redevplugin-key");
+    if (!validResourceIdentifier(targetKey)) throw new Error("plugin UI action target is invalid");
+    const edit = controlEdits.get(targetKey) || { revision: 0, isComposing: false };
+    if (eventType === "input" || eventType === "change") edit.revision += 1;
+    edit.isComposing = Boolean(event.isComposing || edit.isComposing);
+    controlEdits.set(targetKey, edit);
+    const payload = {
+      type: "redevplugin.ui.action",
+      action: element.getAttribute("data-redevplugin-action"),
+      event: eventType,
+      target_key: targetKey,
+      edit_revision: edit.revision,
+      is_composing: edit.isComposing,
+    };
+    const eventTarget = event.target;
+    if (eventTarget && typeof eventTarget.value === "string") payload.value = eventTarget.value.slice(0, maxTextLength);
+    if (eventTarget && typeof eventTarget.checked === "boolean") payload.checked = eventTarget.checked;
     if (eventType === "submit" && element.tagName === "FORM") {
       const values = {};
       let count = 0;
@@ -873,7 +1479,24 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     }
     return payload;
   };
+  document.addEventListener("compositionstart", (event) => {
+    const element = event.target instanceof Element ? event.target.closest("[data-redevplugin-key]") : null;
+    const key = element?.getAttribute("data-redevplugin-key");
+    if (!validResourceIdentifier(key)) return;
+    const edit = controlEdits.get(key) || { revision: 0, isComposing: false };
+    edit.isComposing = true;
+    controlEdits.set(key, edit);
+  }, true);
+  document.addEventListener("compositionend", (event) => {
+    const element = event.target instanceof Element ? event.target.closest("[data-redevplugin-key]") : null;
+    const key = element?.getAttribute("data-redevplugin-key");
+    if (!validResourceIdentifier(key)) return;
+    const edit = controlEdits.get(key) || { revision: 0, isComposing: true };
+    edit.isComposing = false;
+    controlEdits.set(key, edit);
+  }, true);
   const handleAction = (event) => {
+    if (pendingQuiesceID) return;
     if (!["click", "input", "change", "submit"].includes(event.type)) return;
     const origin = event.target instanceof Element ? event.target : null;
     const element = origin ? origin.closest("[data-redevplugin-action]") : null;
@@ -925,7 +1548,17 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     if (!owner || !document.body.contains(owner) || !validIdentifier(action)) return;
     event.preventDefault();
     event.stopPropagation();
-    sendWorker({ type: "redevplugin.ui.action", action, event: "escape" });
+    const targetKey = owner.getAttribute("data-redevplugin-key");
+    if (!validResourceIdentifier(targetKey)) return;
+    const edit = controlEdits.get(targetKey) || { revision: 0, isComposing: false };
+    sendWorker({
+      type: "redevplugin.ui.action",
+      action,
+      event: "escape",
+      target_key: targetKey,
+      edit_revision: edit.revision,
+      is_composing: edit.isComposing,
+    });
   }, true);
   const pumpAssets = () => {
     while (activeAssetReads < maxConcurrentAssetReads && queuedAssets.length > 0) {
@@ -1255,7 +1888,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|stream|render|operation|canvas|asset)_([1-9][0-9]{0,15})$/.exec(value);
+    const match = /^(rpc|stream|stream_ack|render|operation|canvas|asset)_([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;
@@ -1473,7 +2106,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     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 });
-      disposeRuntime();
+      terminateQuiescedWorker();
       return;
     }
     if (validCall(message)) {
@@ -1486,6 +2119,12 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
       sendParent(message);
       return;
     }
+    if (exactKeys(message, ["type", "id", "stream_handle", "delivery_id"]) && message.type === "redevplugin.bridge.stream.ack" &&
+        requestID(message.id, "stream_ack") && validOpaqueHandle(message.stream_handle, "stream") && validDeliveryID(message.delivery_id)) {
+      if (!acceptWorkerRequest(message.id, "stream_ack")) return rejectWorkerRequest(message.id, "duplicate, replayed, or excessive plugin request");
+      sendParent(message);
+      return;
+    }
     if (isRecord(message) && Object.keys(message).every((key) => ["type", "id", "operation_id", "reason"].includes(key)) &&
         message.type === "redevplugin.bridge.operation.cancel" && typeof message.id === "string" &&
         validOpaqueHandle(message.operation_id, "operation") && (message.reason === undefined || (typeof message.reason === "string" && message.reason.length <= 256))) {
@@ -1513,20 +2152,30 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
       void deliverImageAsset(message.id, message.asset_id, asset);
       return;
     }
-    if (exactKeys(message, ["type", "id", "tree"]) && message.type === "redevplugin.ui.render" && typeof message.id === "string") {
+    if (exactKeys(message, ["type", "id", "revision", "tree"]) && message.type === "redevplugin.ui.mount" &&
+        typeof message.id === "string" && message.revision === 1) {
       if (!acceptWorkerRequest(message.id, "render")) return rejectWorkerRequest(message.id, "duplicate, replayed, or excessive plugin request");
       if (!renderRateAllowed()) {
         completeWorkerRequest(message.id);
         return rejectWorkerRequest(message.id, "plugin render rate limit exceeded");
       }
-      try {
-        applyWorkerRender(message.tree);
+      void mountWorkerTree(message.tree).then(() => {
         completeWorkerRequest(message.id);
         sendWorker({ type: "redevplugin.bridge.response", id: message.id, ok: true });
-      } catch (error) {
+      }, (error) => fail(error && error.message || "plugin UI mount violated the protocol"));
+      return;
+    }
+    if (exactKeys(message, ["type", "id", "base_revision", "revision", "operations"]) && message.type === "redevplugin.ui.patch" &&
+        typeof message.id === "string" && Number.isSafeInteger(message.base_revision) && Number.isSafeInteger(message.revision)) {
+      if (!acceptWorkerRequest(message.id, "render")) return rejectWorkerRequest(message.id, "duplicate, replayed, or excessive plugin request");
+      if (!renderRateAllowed()) {
         completeWorkerRequest(message.id);
-        sendWorker({ type: "redevplugin.bridge.response", id: message.id, ok: false, error_code: "PLUGIN_CONTRACT_MISMATCH", error: String(error && error.message || error).slice(0, 512) });
+        return rejectWorkerRequest(message.id, "plugin render rate limit exceeded");
       }
+      void patchWorkerTree(message.base_revision, message.revision, message.operations).then(() => {
+        completeWorkerRequest(message.id);
+        sendWorker({ type: "redevplugin.bridge.response", id: message.id, ok: true });
+      }, (error) => fail(error && error.message || "plugin UI patch violated the protocol"));
       return;
     }
     if (exactKeys(message, ["type", "id"]) && message.type === "redevplugin.bridge.cancel" && typeof message.id === "string") {
@@ -1599,9 +2248,9 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
 })();`;
     return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="${escapeHTMLAttribute(csp)}"><title>Plugin</title></head><body><script nonce="${scriptNonce}">${bootstrapScript}</script></body></html>`;
 }
-const pluginSurfaceHostConstructorToken = Symbol("redevplugin.surface-host.constructor");
-export class PluginSurfaceHost {
+class PluginSurfaceHostImplementation {
     element;
+    surfaceInstanceId;
     bootstrap;
     bridgeChannelId;
     frameGenerationId;
@@ -1609,6 +2258,7 @@ export class PluginSurfaceHost {
     #iframe;
     #transport;
     #createMessageChannel;
+    #bridgeReady = false;
     #loadTimeoutMs;
     #requestTimeoutMs;
     #leaseRenewalLeadMs;
@@ -1639,6 +2289,7 @@ export class PluginSurfaceHost {
     #closePromise;
     #revokePromise;
     #unregisterSurfaceScope;
+    #onLocalInvalidation;
     #opened = false;
     #ready = false;
     #disposed = false;
@@ -1657,20 +2308,10 @@ export class PluginSurfaceHost {
         const error = new PluginBridgeError("PLUGIN_BRIDGE_HANDSHAKE_FAILED", `Plugin iframe reloaded unexpectedly (attempt ${decision.attempt})`);
         void this.#failSurface(error);
     };
-    static create(options) {
-        validateHostBootstrap(options.bootstrap);
-        const transport = surfaceTransportInternals.get(options.hostTransport);
-        if (!transport) {
-            throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface host transport is invalid");
-        }
-        return new PluginSurfaceHost(pluginSurfaceHostConstructorToken, options, transport, createPluginSurfaceFrame());
-    }
-    constructor(constructorToken, options, transport, iframe) {
-        if (constructorToken !== pluginSurfaceHostConstructorToken) {
-            throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface hosts must be created through PluginSurfaceHost.create()");
-        }
+    constructor(options, transport, iframe) {
         this.element = iframe;
         this.bootstrap = options.bootstrap;
+        this.surfaceInstanceId = options.bootstrap.surfaceInstanceId;
         this.bridgeChannelId = options.bridgeChannelId ?? randomOpaqueHandle("bridge");
         this.frameGenerationId = randomOpaqueHandle("frame");
         this.surfaceHandle = randomOpaqueHandle("surface");
@@ -1685,7 +2326,7 @@ export class PluginSurfaceHost {
         this.#onOpeningProgress = options.onOpeningProgress;
         this.#onError = options.onError;
         hardenPluginSurfaceFrame(this.#iframe);
-        this.#unregisterSurfaceScope = registerPluginSurface(options.surfaceScope ?? defaultPluginSurfaceScope, this.bootstrap.pluginInstanceId, () => this.#disposeLocal());
+        this.#unregisterSurfaceScope = registerPluginSurface(options.surfaceScope ?? defaultPluginSurfaceScope, this.bootstrap.pluginInstanceId, () => this.#disposeLocal(), () => this.#invalidateLocal());
     }
     async open() {
         this.#assertActive();
@@ -1696,16 +2337,22 @@ export class PluginSurfaceHost {
         const startedAt = Date.now();
         const progressTimer = setTimeout(() => {
             if (!this.#ready && !this.#disposed) {
-                this.#onOpeningProgress?.({
+                this.#reportOpeningProgress({
                     phase: "opening",
                     elapsedMs: Math.max(openingProgressDelayMs, Date.now() - startedAt),
                 });
             }
         }, openingProgressDelayMs);
-        const signals = { portAcknowledged: deferred(), firstPaint: deferred(), workerReady: deferred() };
+        const signals = {
+            portAcknowledged: deferred(),
+            firstPaint: deferred(),
+            workerReady: deferred(),
+            firstCommit: deferred(),
+        };
         void signals.portAcknowledged.promise.catch(() => undefined);
         void signals.firstPaint.promise.catch(() => undefined);
         void signals.workerReady.promise.catch(() => undefined);
+        void signals.firstCommit.promise.catch(() => undefined);
         this.#openSignals = signals;
         const scriptNonce = randomOpaqueNonce();
         this.#frameLoaded = false;
@@ -1722,7 +2369,7 @@ export class PluginSurfaceHost {
             if (bridgeError.errorCode === "PLUGIN_BRIDGE_TIMEOUT")
                 this.#reloadLimiter.recordCrash();
             this.#reportError(bridgeError);
-            const revoke = this.#bestEffortRevokeSurface(false);
+            const revoke = this.#revokeSurface(false);
             this.#disposeLocal();
             await revoke;
             throw bridgeError;
@@ -1767,18 +2414,27 @@ export class PluginSurfaceHost {
         });
         await Promise.all([signals.firstPaint.promise, signals.workerReady.promise]);
         this.#assertActive();
-        this.#ready = true;
+        this.#bridgeReady = true;
         this.#scheduleLeaseRenewal();
-        this.#reloadLimiter.recordHealthyLoad();
         this.#postToRenderer({ type: "redevplugin.bridge.lifecycle", event: { type: "ready" } });
+        await signals.firstCommit.promise;
+        this.#assertActive();
+        this.#ready = true;
+        this.#reloadLimiter.recordHealthyLoad();
     }
     sendLifecycle(event) {
         this.#assertReady();
         this.#postToRenderer({ type: "redevplugin.bridge.lifecycle", event });
     }
     close() {
-        if (this.#disposed)
-            return Promise.resolve();
+        if (this.#disposed) {
+            const result = {
+                quiesce: { outcome: "not_ready", durationMs: 0 },
+                revokeDurationMs: 0,
+                totalDurationMs: 0,
+            };
+            return this.#revokePromise ? this.#revokePromise.then(() => result) : Promise.resolve(result);
+        }
         if (this.#closePromise)
             return this.#closePromise;
         this.#closePromise = this.#closeSurface();
@@ -1786,14 +2442,24 @@ export class PluginSurfaceHost {
     }
     dispose() {
         if (this.#disposed)
-            return;
-        void this.#bestEffortRevokeSurface(true);
+            return this.#revokePromise ?? Promise.resolve();
+        const revoke = this.#revokeSurface(true);
+        void revoke.catch(() => undefined);
         this.#disposeLocal();
+        return revoke;
     }
-    async #closeSurface() {
-        await this.#quiesceSurface();
+    observeLocalInvalidation(observer) {
+        this.#onLocalInvalidation = observer;
         if (this.#disposed)
-            return;
+            observer();
+    }
+    async #closeSurface() {
+        const startedAt = performance.now();
+        const quiesce = await this.#quiesceSurface();
+        if (this.#disposed) {
+            return { quiesce, revokeDurationMs: 0, totalDurationMs: performance.now() - startedAt };
+        }
+        const revokeStartedAt = performance.now();
         const revoke = this.#revokeSurface(false);
         this.#disposeLocal();
         try {
@@ -1802,6 +2468,11 @@ export class PluginSurfaceHost {
         catch (error) {
             throw toBridgeError(error, "PLUGIN_BRIDGE_DISPOSED");
         }
+        return {
+            quiesce,
+            revokeDurationMs: performance.now() - revokeStartedAt,
+            totalDurationMs: performance.now() - startedAt,
+        };
     }
     #disposeLocal() {
         if (this.#disposed)
@@ -1810,6 +2481,7 @@ export class PluginSurfaceHost {
         this.#unregisterSurfaceScope?.();
         this.#unregisterSurfaceScope = undefined;
         this.#ready = false;
+        this.#bridgeReady = false;
         if (this.#leaseRenewalTimer)
             clearTimeout(this.#leaseRenewalTimer);
         this.#leaseRenewalTimer = undefined;
@@ -1821,6 +2493,7 @@ export class PluginSurfaceHost {
         const disposedError = new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin surface host was disposed");
         this.#openSignals?.firstPaint.reject(disposedError);
         this.#openSignals?.workerReady.reject(disposedError);
+        this.#openSignals?.firstCommit.reject(disposedError);
         this.#openSignals?.portAcknowledged.reject(disposedError);
         this.#initialFrameLoad?.reject(disposedError);
         this.#quiesce?.acknowledged.reject(disposedError);
@@ -1845,6 +2518,16 @@ export class PluginSurfaceHost {
         }
         this.#iframe.srcdoc = "";
     }
+    #invalidateLocal() {
+        this.#disposeLocal();
+        this.#iframe.remove?.();
+        try {
+            this.#onLocalInvalidation?.();
+        }
+        catch {
+            // Slot state observers cannot weaken local session containment.
+        }
+    }
     async #handlePortMessage(event) {
         if (this.#disposed || !messageWithinLimit(event.data))
             return;
@@ -1863,6 +2546,10 @@ export class PluginSurfaceHost {
                 this.#openSignals?.workerReady.resolve();
                 return;
             }
+            if (hasExactKeys(data, ["type"]) && data.type === "redevplugin.surface.first_commit") {
+                this.#openSignals?.firstCommit.resolve();
+                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;
@@ -1884,6 +2571,10 @@ export class PluginSurfaceHost {
                 await this.#handleStreamRead(data.id, data.stream_handle);
                 return;
             }
+            if (isStreamAcknowledgeMessage(data)) {
+                await this.#handleStreamAcknowledge(data.id, data.stream_handle, data.delivery_id);
+                return;
+            }
             if (isOperationCancelMessage(data)) {
                 await this.#handleOperationCancel(data);
                 return;
@@ -1897,7 +2588,7 @@ export class PluginSurfaceHost {
         }
     }
     async #handleCall(request) {
-        if (!this.#ready || !this.#gatewayToken) {
+        if ((!this.#bridgeReady && !this.#quiesce) || !this.#gatewayToken) {
             this.#postError(request.id, "PLUGIN_BRIDGE_HANDSHAKE_REQUIRED", "Plugin bridge call arrived before the surface became ready");
             return;
         }
@@ -1915,7 +2606,7 @@ export class PluginSurfaceHost {
                 await this.#handleConfirmationRequired(request, bridgeError, controller.signal);
                 return;
             }
-            this.#postError(request.id, bridgeError.errorCode, bridgeError.message, bridgeError.details);
+            this.#postError(request.id, bridgeError.errorCode, bridgeError.message, bridgeError.details, bridgeError.mutationOutcome);
         }
         finally {
             this.#pendingRequestControllers.delete(request.id);
@@ -1923,11 +2614,11 @@ export class PluginSurfaceHost {
     }
     async #handleConfirmationRequired(request, originalError, signal) {
         if (!this.#confirm) {
-            this.#postError(request.id, originalError.errorCode, originalError.message, originalError.details);
+            this.#postError(request.id, originalError.errorCode, originalError.message, originalError.details, originalError.mutationOutcome);
             return;
         }
         try {
-            const confirmation = await this.#prepareConfirmation(request, signal);
+            const confirmation = await this.#preparePluginMethodConfirmation(request, signal);
             const decision = await abortableConfirmationDecision(this.#confirm({
                 requestId: request.id,
                 method: request.method,
@@ -1955,47 +2646,60 @@ export class PluginSurfaceHost {
             if (signal.aborted || this.#disposed)
                 return;
             const bridgeError = toBridgeError(error, "PLUGIN_PERMISSION_DENIED");
-            this.#postError(request.id, bridgeError.errorCode, bridgeError.message, bridgeError.details);
+            this.#postError(request.id, bridgeError.errorCode, bridgeError.message, bridgeError.details, bridgeError.mutationOutcome);
         }
     }
     async #handleStreamRead(id, streamHandle) {
         const credential = this.#streamCredentials.get(streamHandle);
-        if (!credential || credential.reading) {
-            this.#postError(id, "PLUGIN_STREAM_TICKET_INVALID", "Plugin stream handle is invalid or already consumed");
+        if (!credential || credential.completed || credential.reading || credential.acknowledging) {
+            this.#postError(id, "PLUGIN_STREAM_TICKET_INVALID", "Plugin stream handle is invalid, completed, or busy");
             return;
         }
         if (credential.expiresAtMs <= Date.now()) {
             this.#postError(id, "PLUGIN_STREAM_TICKET_INVALID", "Plugin stream handle is expired");
             return;
         }
+        if (credential.pending) {
+            this.#postResponse(id, credential.pending.response);
+            return;
+        }
         credential.reading = true;
         const controller = this.#registerPendingRequest(id);
         try {
-            const result = await this.#postJSON(`/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/streams/read`, () => ({ stream_id: credential.streamID, stream_ticket: credential.streamTicket }), controller.signal);
-            if (!isStreamReadResult(result, credential.streamID, credential.lastSequence)) {
+            const readPath = `/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/streams/read`;
+            const readBody = () => ({ stream_id: credential.streamID, stream_ticket: credential.streamTicket, read_id: credential.readID });
+            let result;
+            try {
+                result = await this.#postJSON(readPath, readBody, controller.signal);
+            }
+            catch (error) {
+                if (!retryableStreamReadTransportFailure(error) || controller.signal.aborted || this.#disposed)
+                    throw error;
+                result = await this.#postJSON(readPath, readBody, controller.signal);
+            }
+            if (!isStreamReadResult(result, credential.streamID, credential.readID, credential.lastSequence)) {
                 throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin stream endpoint returned an invalid response");
             }
             const lastSequence = result.events.length > 0 ? result.events[result.events.length - 1].sequence : credential.lastSequence;
-            if (result.done) {
-                this.#streamCredentials.delete(streamHandle);
-            }
-            else {
-                const expiresAtMs = Date.parse(result.next_stream_expires_at);
-                credential.streamTicket = result.next_stream_ticket;
-                credential.expiresAtMs = expiresAtMs;
-                credential.lastSequence = lastSequence;
-                credential.reading = false;
+            const events = result.events.map(publicPluginStreamEvent);
+            const response = result.done
+                ? { delivery_id: result.delivery_id, events, done: true, terminal_status: result.terminal_status, retry_after_ms: 0 }
+                : { delivery_id: result.delivery_id, events, done: false, retry_after_ms: events.length === 0 ? 25 : 0 };
+            if (result.delivery_id) {
+                credential.pending = {
+                    deliveryID: result.delivery_id,
+                    lastSequence,
+                    done: result.done,
+                    response,
+                };
             }
+            credential.reading = false;
             if (!controller.signal.aborted && !this.#disposed)
-                this.#postResponse(id, {
-                    events: result.events.map(publicPluginStreamEvent),
-                    done: result.done,
-                    ...(result.done ? { terminal_status: result.terminal_status } : {}),
-                    retry_after_ms: result.events.length === 0 && !result.done ? 25 : 0,
-                });
+                this.#postResponse(id, response);
         }
         catch (error) {
-            if (streamReadFailureInvalidatesCredential(error)) {
+            const bridgeError = toBridgeError(error, "PLUGIN_RUNTIME_UNAVAILABLE");
+            if (streamReadFailureInvalidatesCredential(bridgeError)) {
                 this.#streamCredentials.delete(streamHandle);
             }
             else {
@@ -2003,17 +2707,62 @@ export class PluginSurfaceHost {
             }
             if (controller.signal.aborted || this.#disposed)
                 return;
-            const bridgeError = toBridgeError(error, "PLUGIN_RUNTIME_UNAVAILABLE");
             this.#postError(id, bridgeError.errorCode, bridgeError.message);
         }
         finally {
             this.#pendingRequestControllers.delete(id);
         }
     }
+    async #handleStreamAcknowledge(id, streamHandle, deliveryID) {
+        const credential = this.#streamCredentials.get(streamHandle);
+        if (!credential || credential.reading || credential.acknowledging) {
+            this.#postError(id, "PLUGIN_STREAM_DELIVERY_INVALID", "Plugin stream delivery is invalid or busy", undefined, "not_committed");
+            return;
+        }
+        if (credential.lastAcknowledgedDeliveryID === deliveryID) {
+            this.#postResponse(id, undefined);
+            return;
+        }
+        if (!credential.pending || credential.pending.deliveryID !== deliveryID) {
+            this.#postError(id, "PLUGIN_STREAM_DELIVERY_INVALID", "Plugin stream delivery does not match the pending batch", undefined, "not_committed");
+            return;
+        }
+        credential.acknowledging = true;
+        const controller = this.#registerPendingRequest(id);
+        try {
+            const result = await this.#postMutationJSON(`/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/streams/ack`, () => ({
+                stream_id: credential.streamID,
+                stream_ticket: credential.streamTicket,
+                delivery_id: deliveryID,
+            }), controller.signal);
+            if (!hasExactKeys(result, ["acknowledged"]) || result.acknowledged !== true) {
+                throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin stream acknowledgement endpoint returned an invalid response", undefined, undefined, "unknown");
+            }
+            const pending = credential.pending;
+            credential.lastAcknowledgedDeliveryID = deliveryID;
+            credential.lastSequence = pending.lastSequence;
+            credential.pending = undefined;
+            credential.readID = randomOpaqueHandle("read");
+            credential.completed = pending.done;
+            credential.acknowledging = false;
+            if (!controller.signal.aborted && !this.#disposed)
+                this.#postResponse(id, undefined);
+        }
+        catch (error) {
+            credential.acknowledging = false;
+            if (controller.signal.aborted || this.#disposed)
+                return;
+            const bridgeError = toBridgeError(error, "PLUGIN_STREAM_DELIVERY_INVALID");
+            this.#postError(id, bridgeError.errorCode, bridgeError.message, bridgeError.details, bridgeError.mutationOutcome);
+        }
+        finally {
+            this.#pendingRequestControllers.delete(id);
+        }
+    }
     async #handleOperationCancel(message) {
         const controller = this.#registerPendingRequest(message.id);
         try {
-            await this.#postJSON(`/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/operations/cancel`, { operation_id: message.operation_id, bridge_channel_id: this.bridgeChannelId, reason: message.reason }, controller.signal);
+            await this.#postMutationJSON(`/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/operations/cancel`, { operation_id: message.operation_id, bridge_channel_id: this.bridgeChannelId, reason: message.reason }, controller.signal);
             this.#releaseOperationStreams(message.operation_id);
             if (!controller.signal.aborted && !this.#disposed)
                 this.#postResponse(message.id, undefined);
@@ -2022,7 +2771,7 @@ export class PluginSurfaceHost {
             if (controller.signal.aborted || this.#disposed)
                 return;
             const bridgeError = toBridgeError(error, "PLUGIN_OPERATION_BLOCKED");
-            this.#postError(message.id, bridgeError.errorCode, bridgeError.message);
+            this.#postError(message.id, bridgeError.errorCode, bridgeError.message, bridgeError.details, bridgeError.mutationOutcome);
         }
         finally {
             this.#pendingRequestControllers.delete(message.id);
@@ -2096,7 +2845,10 @@ export class PluginSurfaceHost {
                 streamTicket: result.stream_ticket,
                 expiresAtMs,
                 lastSequence: 0,
+                readID: randomOpaqueHandle("read"),
                 reading: false,
+                acknowledging: false,
+                completed: false,
             });
             publicResult.stream_handle = handle;
         }
@@ -2115,13 +2867,13 @@ export class PluginSurfaceHost {
         }
     }
     #callRPC(request, confirmationID, signal) {
-        return this.#postJSON("/_redevplugin/api/plugins/rpc", () => this.#rpcBody(request, confirmationID), signal);
+        return this.#postMutationJSON("/_redevplugin/api/plugins/rpc", () => this.#rpcBody(request, confirmationID), signal);
     }
-    #prepareConfirmation(request, signal) {
-        return this.#postJSON("/_redevplugin/api/plugins/confirm", () => this.#rpcBody(request), signal);
+    #preparePluginMethodConfirmation(request, signal) {
+        return this.#postMutationJSON("/_redevplugin/api/plugins/confirmations/prepare", () => this.#rpcBody(request), signal);
     }
     async #rejectConfirmation(confirmationID, signal) {
-        const result = await this.#postJSON(`/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/confirmations/reject`, () => ({
+        const result = await this.#postMutationJSON(`/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/confirmations/reject`, () => ({
             plugin_instance_id: this.bootstrap.pluginInstanceId,
             bridge_channel_id: this.bridgeChannelId,
             plugin_gateway_token: this.#gatewayToken,
@@ -2145,7 +2897,7 @@ export class PluginSurfaceHost {
         return body;
     }
     #prepareSurface() {
-        return this.#postJSON(`/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/prepare`, { asset_ticket: this.bootstrap.assetTicket });
+        return this.#postMutationJSON(`/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/prepare`, { asset_ticket: this.bootstrap.assetTicket });
     }
     async #mintBridgeToken(previousGatewayToken, direct = false) {
         const handshake = this.#handshake();
@@ -2157,7 +2909,7 @@ export class PluginSurfaceHost {
             handshake_transcript_sha256: transcript,
             ...(previousGatewayToken ? { previous_plugin_gateway_token: previousGatewayToken } : {}),
         };
-        return direct ? this.#fetchJSON(path, body) : this.#postJSON(path, body);
+        return direct ? this.#fetchMutationJSON(path, body) : this.#postMutationJSON(path, body);
     }
     #handshake() {
         return {
@@ -2168,13 +2920,19 @@ export class PluginSurfaceHost {
             active_fingerprint: this.bootstrap.activeFingerprint,
             bridge_nonce: this.bootstrap.bridgeNonce,
             asset_session_nonce: this.bootstrap.assetSessionNonce,
-            plugin_state_version: this.bootstrap.pluginStateVersion,
+            management_revision: this.bootstrap.managementRevision,
             revoke_epoch: this.bootstrap.revokeEpoch,
             ui_protocol_version: pluginUIProtocolVersion,
         };
     }
     async #postJSON(path, body, signal) {
-        if (this.#ready) {
+        return this.#requestJSON(path, body, false, signal);
+    }
+    async #postMutationJSON(path, body, signal) {
+        return this.#requestJSON(path, body, true, signal);
+    }
+    async #requestJSON(path, body, mutation, signal) {
+        if (this.#bridgeReady) {
             if (Date.now() >= this.#leaseRenewAtMs)
                 await this.#startLeaseRenewal();
             else if (this.#leaseRenewalPromise)
@@ -2183,7 +2941,9 @@ export class PluginSurfaceHost {
         const requestBody = typeof body === "function" ? body() : body;
         this.#activeTransportRequests += 1;
         try {
-            return await this.#fetchJSON(path, requestBody, signal);
+            return mutation
+                ? await this.#fetchMutationJSON(path, requestBody, signal)
+                : await this.#fetchJSON(path, requestBody, signal);
         }
         finally {
             this.#activeTransportRequests -= 1;
@@ -2197,6 +2957,9 @@ export class PluginSurfaceHost {
     async #fetchJSON(path, body, signal) {
         return this.#fetchJSONRequest(path, body, { signal });
     }
+    async #fetchMutationJSON(path, body, signal) {
+        return this.#fetchJSONRequest(path, body, { signal, mutation: true });
+    }
     async #fetchJSONRequest(path, body, options = {}) {
         const controller = new AbortController();
         let timedOut = false;
@@ -2213,7 +2976,7 @@ export class PluginSurfaceHost {
             timer = setTimeout(() => {
                 timedOut = true;
                 controller.abort();
-                reject(new PluginBridgeError("PLUGIN_BRIDGE_TIMEOUT", `Plugin surface request timed out: ${path}`));
+                reject(new PluginBridgeError("PLUGIN_BRIDGE_TIMEOUT", `Plugin surface request timed out: ${path}`, undefined, undefined, options.mutation ? "unknown" : undefined));
             }, this.#requestTimeoutMs);
         });
         try {
@@ -2228,12 +2991,16 @@ export class PluginSurfaceHost {
                 }),
                 timeout,
             ]);
-            return await readHostEnvelope(response, "PLUGIN_PERMISSION_DENIED");
+            return options.mutation ? await readMutationPlatformResponse(response) : await readPlatformResponse(response);
         }
         catch (error) {
-            if (timedOut)
-                throw new PluginBridgeError("PLUGIN_BRIDGE_TIMEOUT", `Plugin surface request timed out: ${path}`);
-            throw error;
+            if (timedOut) {
+                throw new PluginBridgeError("PLUGIN_BRIDGE_TIMEOUT", `Plugin surface request timed out: ${path}`, undefined, undefined, options.mutation ? "unknown" : undefined);
+            }
+            if (error instanceof PluginBridgeError || error instanceof PluginPlatformRequestError || error instanceof PluginTransportError) {
+                throw error;
+            }
+            throw new PluginTransportError(`Plugin surface request failed for POST ${path}`, error, options.mutation ? "unknown" : undefined);
         }
         finally {
             if (timer)
@@ -2271,7 +3038,7 @@ export class PluginSurfaceHost {
     }
     #startLeaseRenewal() {
         this.#assertActive();
-        if (!this.#ready || !this.#gatewayToken) {
+        if (!this.#bridgeReady || !this.#gatewayToken) {
             return Promise.reject(new PluginBridgeError("PLUGIN_BRIDGE_HANDSHAKE_REQUIRED", "Plugin surface lease cannot renew before readiness"));
         }
         if (this.#leaseRenewalPromise)
@@ -2305,28 +3072,21 @@ export class PluginSurfaceHost {
     #revokeSurface(keepalive) {
         if (this.#revokePromise)
             return this.#revokePromise;
-        this.#revokePromise = (async () => {
-            await this.#fetchJSONRequest(`/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/dispose`, { bridge_nonce: this.bootstrap.bridgeNonce }, { keepalive, independentLifecycle: true });
-        })();
+        this.#revokePromise = revokeSurfaceBootstrap(this.#transport, this.bootstrap, this.#requestTimeoutMs, keepalive);
         return this.#revokePromise;
     }
-    async #bestEffortRevokeSurface(keepalive) {
-        try {
-            await this.#revokeSurface(keepalive);
-        }
-        catch {
-            // The server may already have revoked the surface after a failed prepare.
-        }
-    }
     async #quiesceSurface() {
-        if (!this.#ready || !this.#port || this.#quiesce)
-            return;
+        const startedAt = performance.now();
+        if (!this.#ready || !this.#port || this.#quiesce) {
+            return { outcome: "not_ready", durationMs: performance.now() - startedAt };
+        }
         const quiesce = {
             id: randomOpaqueHandle("quiesce"),
             acknowledged: deferred(),
         };
         void quiesce.acknowledged.promise.catch(() => undefined);
         this.#quiesce = quiesce;
+        this.#ready = false;
         try {
             this.#postToRenderer({
                 type: "redevplugin.bridge.lifecycle",
@@ -2334,9 +3094,12 @@ export class PluginSurfaceHost {
                 quiesce_id: quiesce.id,
             });
             await withTimeout(quiesce.acknowledged.promise, Math.min(this.#requestTimeoutMs, maxSurfaceQuiesceMs), "Plugin surface quiesce timed out");
+            return { outcome: "acknowledged", durationMs: performance.now() - startedAt };
         }
         catch {
-            // A non-responsive plugin cannot block session revocation and iframe teardown.
+            const error = new PluginBridgeError("PLUGIN_SURFACE_QUIESCE_TIMEOUT", "Plugin surface quiesce timed out");
+            this.#reportError(error);
+            return { outcome: "timed_out", durationMs: performance.now() - startedAt };
         }
         finally {
             if (this.#quiesce === quiesce)
@@ -2347,10 +3110,11 @@ export class PluginSurfaceHost {
         if (this.#disposed)
             return;
         this.#ready = false;
+        this.#bridgeReady = false;
         this.#openSignals?.firstPaint.reject(error);
         this.#openSignals?.workerReady.reject(error);
         this.#reportError(error);
-        const revoke = this.#bestEffortRevokeSurface(true);
+        const revoke = this.#revokeSurface(true);
         this.#disposeLocal();
         await revoke;
     }
@@ -2362,16 +3126,29 @@ export class PluginSurfaceHost {
         }
         this.#postToRenderer(response);
     }
-    #postError(id, errorCode, error, details) {
+    #postError(id, errorCode, error, details, mutationOutcome) {
         const errorDetails = details === undefined ? undefined : normalizePluginJSONObject(details);
-        this.#postToRenderer(removeUndefined({
+        const response = removeUndefined({
             type: "redevplugin.bridge.response",
             id,
             ok: false,
             error_code: errorCode,
             error,
             error_details: errorDetails,
-        }));
+            mutation_outcome: mutationOutcome,
+        });
+        if (!messageWithinLimit(response)) {
+            this.#postToRenderer(removeUndefined({
+                type: "redevplugin.bridge.response",
+                id,
+                ok: false,
+                error_code: "PLUGIN_JSON_LIMIT_EXCEEDED",
+                error: "Plugin error response exceeds the bridge message limit",
+                mutation_outcome: mutationOutcome,
+            }));
+            return;
+        }
+        this.#postToRenderer(response);
     }
     #postToRenderer(message) {
         if (!this.#port) {
@@ -2387,6 +3164,14 @@ export class PluginSurfaceHost {
             // Observers cannot weaken revocation or local teardown invariants.
         }
     }
+    #reportOpeningProgress(progress) {
+        try {
+            this.#onOpeningProgress?.(progress);
+        }
+        catch {
+            // Observers cannot weaken opening, revocation, or local teardown invariants.
+        }
+    }
     #assertReady() {
         this.#assertActive();
         if (!this.#ready || !this.#port) {
@@ -2399,6 +3184,418 @@ export class PluginSurfaceHost {
         }
     }
 }
+export function createPreparedPluginSurfaceHost(options) {
+    return createPluginSurfaceHostImplementation(options);
+}
+function createPluginSurfaceHostImplementation(options) {
+    validateHostBootstrap(options.bootstrap);
+    const transport = requireSurfaceTransportInternals(options.hostTransport);
+    return new PluginSurfaceHostImplementation(options, transport, createPluginSurfaceFrame());
+}
+const surfaceSlotInternals = new WeakMap();
+class PluginSurfaceCleanupError extends Error {
+    cause;
+    constructor(cause) {
+        super("Plugin surface cleanup failed", { cause });
+        this.name = "PluginSurfaceCleanupError";
+        this.cause = cause;
+    }
+}
+export function openPluginSurfaceInSlot(slot, request) {
+    const internals = surfaceSlotInternals.get(slot);
+    if (!internals)
+        throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin surface slot is invalid");
+    return internals.open(request);
+}
+export function openPreparedPluginSurfaceInSlot(slot, options) {
+    const internals = surfaceSlotInternals.get(slot);
+    if (!internals)
+        throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin surface slot is invalid");
+    return internals.openPrepared(options);
+}
+function createPluginSurfaceOpeningLease(request) {
+    let unregister = () => undefined;
+    let revokePromise;
+    let removeAbortListener = () => undefined;
+    let invalidationObserver = () => undefined;
+    const lease = {
+        options: Promise.resolve(undefined),
+        pluginInstanceId: request.pluginInstanceId,
+        signal: request.signal,
+        abortError: request.abortError,
+        owner: "opening",
+        cancelled: false,
+        adopt() {
+            if (lease.owner !== "opening" || lease.cancelled) {
+                throw new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin surface opening was cancelled before adoption");
+            }
+            lease.owner = "host";
+            unregister();
+            removeAbortListener();
+        },
+        cancel() {
+            lease.cancelled = true;
+            if (lease.owner === "host")
+                return Promise.resolve();
+            return lease.revoke();
+        },
+        invalidate() {
+            lease.cancelled = true;
+            if (lease.owner === "host" || lease.owner === "invalidated")
+                return;
+            lease.owner = "invalidated";
+            unregister();
+            removeAbortListener();
+            invalidationObserver();
+        },
+        observeInvalidation(observer) {
+            invalidationObserver = observer;
+            if (lease.owner === "invalidated")
+                observer();
+        },
+        revoke() {
+            if (lease.owner === "invalidated")
+                return Promise.resolve();
+            if (lease.owner === "host") {
+                throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface ownership was already adopted");
+            }
+            lease.cancelled = true;
+            lease.owner = "revoked";
+            unregister();
+            removeAbortListener();
+            revokePromise ??= lease.options.then(async (options) => {
+                await revokeSurfaceBootstrap(requireSurfaceTransportInternals(options.hostTransport), options.bootstrap, normalizeTimeout(options.requestTimeoutMs), false);
+            }, () => undefined);
+            return revokePromise;
+        },
+    };
+    unregister = registerPluginSurface(request.surfaceScope, request.pluginInstanceId, () => lease.cancel(), () => lease.invalidate());
+    if (lease.owner === "invalidated") {
+        lease.options = Promise.reject(new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin surface scope is invalidated"));
+    }
+    else {
+        try {
+            lease.options = Promise.resolve(request.open());
+        }
+        catch (error) {
+            lease.options = Promise.reject(error);
+        }
+    }
+    void lease.options.catch(() => {
+        if (lease.owner !== "opening")
+            return;
+        lease.owner = "revoked";
+        unregister();
+        removeAbortListener();
+    });
+    if (request.signal) {
+        const onAbort = () => {
+            void lease.cancel().catch(() => undefined);
+        };
+        request.signal.addEventListener("abort", onAbort, { once: true });
+        removeAbortListener = () => request.signal?.removeEventListener("abort", onAbort);
+        if (request.signal.aborted)
+            onAbort();
+    }
+    return lease;
+}
+export class PluginSurfaceSlot {
+    element;
+    #onStateChange;
+    #onSurfaceClosed;
+    #active;
+    #opening;
+    #transitionController;
+    #tail = Promise.resolve();
+    #disposed = false;
+    #retired = new WeakMap();
+    #disposePromise;
+    static create(options) {
+        if (!options.stage || typeof options.stage.append !== "function" || !options.stage.dataset) {
+            throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin surface slot requires an HTML stage");
+        }
+        return new PluginSurfaceSlot(options);
+    }
+    constructor(options) {
+        this.element = options.stage;
+        this.#onStateChange = options.onStateChange;
+        this.#onSurfaceClosed = options.onSurfaceClosed;
+        surfaceSlotInternals.set(this, {
+            open: (request) => {
+                this.#assertActive();
+                return this.#openLease(createPluginSurfaceOpeningLease(request));
+            },
+            openPrepared: (preparedOptions) => this.#queueOpening(Promise.resolve(preparedOptions)),
+        });
+        this.#setState("empty");
+    }
+    #openLease(lease) {
+        return this.#queueOpening(lease.options, lease);
+    }
+    #queueOpening(resolvedOptions, lease) {
+        this.#assertActive();
+        void resolvedOptions.catch(() => undefined);
+        this.#transitionController?.abort();
+        const controller = new AbortController();
+        this.#transitionController = controller;
+        this.#setState("opening");
+        lease?.observeInvalidation(() => {
+            if (this.#transitionController !== controller)
+                return;
+            controller.abort();
+            this.#setState("empty");
+        });
+        const transition = this.#tail.then(() => this.#openSurface(resolvedOptions, controller, lease), async (error) => {
+            await this.#revokeOpening(lease);
+            throw error;
+        });
+        this.#tail = transition.then(() => undefined, (error) => error instanceof PluginSurfaceCleanupError ? Promise.reject(error) : undefined);
+        void this.#tail.catch(() => undefined);
+        return transition.catch((error) => {
+            if (error instanceof PluginSurfaceCleanupError)
+                throw error.cause;
+            throw error;
+        });
+    }
+    async #openSurface(options, controller, lease) {
+        let resolvedOptions;
+        try {
+            resolvedOptions = await options;
+        }
+        catch (error) {
+            if (!this.#disposed && this.#transitionController === controller && !this.#openingCancelled(controller, lease)) {
+                this.#setState("error", toBridgeError(error, "PLUGIN_BRIDGE_HANDSHAKE_FAILED"));
+            }
+            else {
+                this.#setCancelledState(controller);
+            }
+            throw error;
+        }
+        if (lease && resolvedOptions.bootstrap.pluginInstanceId !== lease.pluginInstanceId) {
+            await this.#revokeOpening(lease);
+            throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface bootstrap identity does not match the opening lease");
+        }
+        if (this.#openingCancelled(controller, lease)) {
+            await this.#revokeOpening(lease);
+            this.#setCancelledState(controller);
+            throw this.#openingCancellationError(lease);
+        }
+        const previous = this.#active;
+        this.#active = undefined;
+        if (previous) {
+            try {
+                await this.#awaitRetirement(previous);
+            }
+            catch (error) {
+                await this.#revokeOpening(lease);
+                throw error;
+            }
+        }
+        if (this.#openingCancelled(controller, lease)) {
+            await this.#revokeOpening(lease);
+            this.#setCancelledState(controller);
+            throw this.#openingCancellationError(lease);
+        }
+        let host;
+        try {
+            host = createPluginSurfaceHostImplementation(resolvedOptions);
+        }
+        catch (error) {
+            await this.#revokeOpening(lease);
+            if (!this.#disposed && this.#transitionController === controller) {
+                this.#setState("error", toBridgeError(error, "PLUGIN_BRIDGE_HANDSHAKE_FAILED"));
+            }
+            throw error;
+        }
+        host.observeLocalInvalidation(() => {
+            if (this.#active === host)
+                this.#active = undefined;
+            if (this.#opening === host)
+                this.#opening = undefined;
+            if (this.#transitionController === controller)
+                controller.abort();
+            host.element.remove();
+            if (!this.#disposed)
+                this.#setState("empty");
+        });
+        this.#adoptOpening(lease);
+        this.#opening = host;
+        setSurfaceInteractive(host.element, false);
+        this.element.append(host.element);
+        try {
+            await this.#openHostUntilCancelled(host, controller, lease);
+            if (this.#openingCancelled(controller, lease) || this.#opening !== host) {
+                await this.#awaitRetirement(host);
+                this.#setCancelledState(controller);
+                throw this.#openingCancellationError(lease);
+            }
+            this.#opening = undefined;
+            this.#active = host;
+            setSurfaceInteractive(host.element, true);
+            this.#setState("ready");
+            return host;
+        }
+        catch (error) {
+            await this.#awaitRetirement(host);
+            if (!this.#disposed && this.#transitionController === controller && !this.#openingCancelled(controller, lease)) {
+                const bridgeError = toBridgeError(error, "PLUGIN_BRIDGE_HANDSHAKE_FAILED");
+                this.#setState("error", bridgeError);
+            }
+            throw error;
+        }
+    }
+    async close() {
+        this.#assertActive();
+        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);
+        void this.#tail.catch(() => undefined);
+        return this.#unwrapCleanupError(closing);
+    }
+    dispose() {
+        if (this.#disposePromise)
+            return this.#disposePromise;
+        this.#disposed = true;
+        this.#transitionController?.abort();
+        this.#transitionController = undefined;
+        this.#setState("disposed");
+        const disposal = this.#tail.then(async () => {
+            await this.#closeCurrentSurface();
+        });
+        this.#disposePromise = this.#unwrapCleanupError(disposal);
+        void this.#disposePromise.catch(() => undefined);
+        this.#tail = disposal.then(() => undefined, (error) => error instanceof PluginSurfaceCleanupError ? Promise.reject(error) : undefined);
+        void this.#tail.catch(() => undefined);
+        return this.#disposePromise;
+    }
+    async #closeCurrentSurface() {
+        const hosts = new Set([this.#active, this.#opening].filter((host) => host !== undefined));
+        this.#active = undefined;
+        this.#opening = undefined;
+        let result;
+        const failures = [];
+        for (const host of hosts) {
+            try {
+                const closed = await this.#retire(host);
+                result ??= closed;
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, "Plugin surface slot cleanup failed");
+        return result;
+    }
+    #retire(host) {
+        const existing = this.#retired.get(host);
+        if (existing)
+            return existing;
+        setSurfaceInteractive(host.element, false);
+        const closing = Promise.resolve().then(async () => {
+            try {
+                const result = await host.close();
+                try {
+                    this.#onSurfaceClosed?.(result);
+                }
+                catch {
+                    // Observers cannot turn a completed revocation into a cleanup failure.
+                }
+                return result;
+            }
+            finally {
+                host.element.remove();
+            }
+        });
+        this.#retired.set(host, closing);
+        return closing;
+    }
+    async #awaitRetirement(host) {
+        try {
+            return await this.#retire(host);
+        }
+        catch (error) {
+            throw new PluginSurfaceCleanupError(error);
+        }
+    }
+    async #openHostUntilCancelled(host, controller, lease) {
+        const signals = [controller.signal, lease?.signal].filter((signal) => signal !== undefined);
+        let cancel;
+        const cancelled = new Promise((_resolve, reject) => {
+            cancel = () => {
+                void this.#awaitRetirement(host).then(() => reject(this.#openingCancellationError(lease)), reject);
+            };
+            for (const signal of signals)
+                signal.addEventListener("abort", cancel, { once: true });
+            if (signals.some((signal) => signal.aborted))
+                cancel();
+        });
+        try {
+            await Promise.race([host.open(), cancelled]);
+        }
+        finally {
+            for (const signal of signals)
+                signal.removeEventListener("abort", cancel);
+        }
+    }
+    #openingCancelled(controller, lease) {
+        return this.#disposed || controller.signal.aborted || lease?.cancelled === true || lease?.signal?.aborted === true;
+    }
+    #openingCancellationError(lease) {
+        if (lease?.signal?.aborted)
+            return lease.abortError();
+        return new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin surface opening was superseded");
+    }
+    #setCancelledState(controller) {
+        if (!this.#disposed && this.#transitionController === controller)
+            this.#setState("empty");
+    }
+    #adoptOpening(lease) {
+        lease?.adopt();
+    }
+    async #revokeOpening(lease) {
+        if (!lease || lease.owner === "host")
+            return;
+        try {
+            await lease.revoke();
+        }
+        catch (error) {
+            throw new PluginSurfaceCleanupError(error);
+        }
+    }
+    async #unwrapCleanupError(result) {
+        try {
+            return await result;
+        }
+        catch (error) {
+            if (error instanceof PluginSurfaceCleanupError)
+                throw error.cause;
+            throw error;
+        }
+    }
+    #setState(state, error) {
+        this.element.dataset.redevpluginSurfaceState = state;
+        try {
+            this.#onStateChange?.(state, error);
+        }
+        catch {
+            // Observers cannot alter the slot lifecycle state machine.
+        }
+    }
+    #assertActive() {
+        if (this.#disposed)
+            throw new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin surface slot is disposed");
+    }
+}
+function setSurfaceInteractive(element, interactive) {
+    element.hidden = !interactive;
+    element.inert = !interactive;
+    element.setAttribute("aria-hidden", interactive ? "false" : "true");
+}
 function claimOpaquePluginBridge() {
     const value = globalThis[opaquePluginBridgeGlobalKey];
     if (!isRecord(value) || typeof value.claim !== "function") {
@@ -2504,7 +3701,7 @@ function validateHostBootstrap(bootstrap) {
             throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface bootstrap is incomplete");
         }
     }
-    if (!Number.isSafeInteger(bootstrap.pluginStateVersion) || bootstrap.pluginStateVersion < 1 ||
+    if (!Number.isSafeInteger(bootstrap.managementRevision) || bootstrap.managementRevision < 1 ||
         !Number.isSafeInteger(bootstrap.revokeEpoch) || bootstrap.revokeEpoch < 1) {
         throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface revision is invalid");
     }
@@ -2513,7 +3710,7 @@ function validateSurfacePreparation(bootstrap, preparation) {
     if (!isSurfacePreparationResult(preparation)) {
         throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface prepare returned an invalid opaque document");
     }
-    if (preparation.plugin_state_version !== bootstrap.pluginStateVersion || preparation.revoke_epoch !== bootstrap.revokeEpoch) {
+    if (preparation.management_revision !== bootstrap.managementRevision || preparation.revoke_epoch !== bootstrap.revokeEpoch) {
         throw new PluginBridgeError("PLUGIN_GATEWAY_TOKEN_INVALID", "Plugin surface state changed during prepare");
     }
     if (preparation.asset_session_nonce !== bootstrap.assetSessionNonce) {
@@ -2531,7 +3728,7 @@ function isSurfacePreparationResult(value) {
         "asset_session_nonce",
         "entry_path",
         "entry_sha256",
-        "plugin_state_version",
+        "management_revision",
         "revoke_epoch",
         "issued_at",
         "expires_at",
@@ -2545,7 +3742,7 @@ function isSurfacePreparationResult(value) {
         typeof value.asset_session_nonce === "string" && value.asset_session_nonce.length > 0 &&
         validPackagePath(value.entry_path) &&
         validSHA256(value.entry_sha256) &&
-        Number.isSafeInteger(value.plugin_state_version) && Number(value.plugin_state_version) >= 1 &&
+        Number.isSafeInteger(value.management_revision) && Number(value.management_revision) >= 1 &&
         Number.isSafeInteger(value.revoke_epoch) && Number(value.revoke_epoch) >= 1 &&
         Number.isFinite(issuedAt) && Number.isFinite(expiresAt) && expiresAt > issuedAt &&
         isOpaqueSurfaceDocument(value.document);
@@ -2611,6 +3808,13 @@ function isStreamReadMessage(value) {
         validBridgeRequestID(value.id, "stream") &&
         validOpaqueHandle(value.stream_handle, "stream");
 }
+function isStreamAcknowledgeMessage(value) {
+    return hasExactKeys(value, ["type", "id", "stream_handle", "delivery_id"]) &&
+        value.type === "redevplugin.bridge.stream.ack" &&
+        validBridgeRequestID(value.id, "stream_ack") &&
+        validOpaqueHandle(value.stream_handle, "stream") &&
+        validDeliveryID(value.delivery_id);
+}
 function isOperationCancelMessage(value) {
     return hasAllowedKeys(value, ["type", "id", "operation_id", "reason"]) &&
         value.type === "redevplugin.bridge.operation.cancel" &&
@@ -2641,7 +3845,9 @@ function isBridgeResponse(value) {
         return Object.keys(value).every((key) => ["type", "id", "ok", "data"].includes(key));
     if (value.ok !== false || typeof value.error_code !== "string" || !pluginBridgeErrorCodeSet.has(value.error_code) ||
         typeof value.error !== "string" || value.error.length > 4096 ||
-        !Object.keys(value).every((key) => ["type", "id", "ok", "error_code", "error", "error_details"].includes(key))) {
+        !Object.keys(value).every((key) => ["type", "id", "ok", "error_code", "error", "error_details", "mutation_outcome"].includes(key)) ||
+        (value.mutation_outcome !== undefined && value.mutation_outcome !== "committed" &&
+            value.mutation_outcome !== "not_committed" && value.mutation_outcome !== "unknown")) {
         return false;
     }
     if (value.error_code === "PLUGIN_CAPABILITY_ERROR")
@@ -2701,14 +3907,28 @@ function isLifecycleMessage(value) {
         (value.quiesce_id === undefined || (value.event.type === "dispose" && validOpaqueHandle(value.quiesce_id, "quiesce")));
 }
 function isActionMessage(value) {
-    return hasAllowedKeys(value, ["type", "action", "event", "value", "checked", "form_data"]) &&
+    return hasAllowedKeys(value, ["type", "action", "event", "target_key", "edit_revision", "is_composing", "value", "checked", "form_data"]) &&
         value.type === "redevplugin.ui.action" &&
         validActionID(value.action) &&
         (value.event === "click" || value.event === "input" || value.event === "change" || value.event === "submit" || value.event === "escape") &&
+        validUIIdentifier(value.target_key) && Number.isSafeInteger(value.edit_revision) && Number(value.edit_revision) >= 0 &&
+        typeof value.is_composing === "boolean" &&
         (value.value == null || (typeof value.value === "string" && value.value.length <= 65536)) &&
         (value.checked == null || typeof value.checked === "boolean") &&
         (value.form_data == null || (isRecord(value.form_data) && Object.entries(value.form_data).every(([key, item]) => validActionID(key) && typeof item === "string" && item.length <= 65536)));
 }
+function publicActionEvent(value) {
+    return removeUndefined({
+        action: value.action,
+        event: value.event,
+        targetKey: value.target_key,
+        editRevision: value.edit_revision,
+        isComposing: value.is_composing,
+        value: value.value,
+        checked: value.checked,
+        form_data: value.form_data,
+    });
+}
 function isCanvasReadyCandidate(value) {
     return isRecord(value) && value.type === "redevplugin.ui.canvas.ready" && typeof value.id === "string" && typeof value.canvas_id === "string";
 }
@@ -2827,25 +4047,23 @@ function isGatewayTokenResult(value) {
         typeof value.asset_session_id === "string" && value.asset_session_id.length > 0 &&
         typeof value.issued_at === "string" && typeof value.expires_at === "string";
 }
-function isStreamReadResult(value, expectedStreamID, previousSequence) {
+function isStreamReadResult(value, expectedStreamID, expectedReadID, previousSequence) {
     if (!isRecord(value) || typeof value.done !== "boolean" || !Array.isArray(value.events))
         return false;
+    const hasDelivery = value.events.length > 0 || value.done;
     const expectedKeys = value.done
-        ? ["done", "events", "terminal_status"]
-        : ["done", "events", "next_stream_expires_at", "next_stream_ticket", "next_stream_ticket_id"];
+        ? ["delivery_id", "done", "events", "read_id", "terminal_status"]
+        : hasDelivery
+            ? ["delivery_id", "done", "events", "read_id"]
+            : ["done", "events", "read_id"];
     if (!hasExactKeys(value, expectedKeys))
         return false;
+    if (value.read_id !== expectedReadID || (hasDelivery && !validDeliveryID(value.delivery_id)))
+        return false;
     if (value.done) {
         if (!validPluginStreamTerminalStatus(value.terminal_status))
             return false;
     }
-    else {
-        const expiresAt = Date.parse(String(value.next_stream_expires_at));
-        if (typeof value.next_stream_ticket !== "string" || value.next_stream_ticket.length === 0 ||
-            typeof value.next_stream_ticket_id !== "string" || value.next_stream_ticket_id.length === 0 ||
-            !Number.isFinite(expiresAt) || expiresAt <= Date.now())
-            return false;
-    }
     let terminal = false;
     for (const event of value.events) {
         if (!isStreamEvent(event) || event.stream_id !== expectedStreamID || event.sequence <= previousSequence || terminal)
@@ -2886,7 +4104,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|stream|render|operation|canvas|asset)_([1-9][0-9]{0,15})$/;
+const bridgeRequestIDPattern = /^(rpc|stream|stream_ack|render|operation|canvas|asset)_([1-9][0-9]{0,15})$/;
 function validBridgeRequestID(value, expectedKind) {
     if (typeof value !== "string")
         return false;
@@ -2907,6 +4125,9 @@ function validUIIdentifier(value) {
 function validOpaqueHandle(value, prefix) {
     return typeof value === "string" && value.startsWith(`${prefix}_`) && opaqueHandlePattern.test(value);
 }
+function validDeliveryID(value) {
+    return typeof value === "string" && /^delivery_[A-Za-z0-9_-]{8,128}$/.test(value);
+}
 function validSHA256(value) {
     return typeof value === "string" && /^sha256:[a-f0-9]{64}$/.test(value);
 }
@@ -2994,6 +4215,38 @@ function isPluginRiskEffect(value) {
 function confirmationDecisionAccepted(decision) {
     return typeof decision === "boolean" ? decision : decision.confirmed;
 }
+function streamReadAbortedError() {
+    return new PluginBridgeError("PLUGIN_STREAM_CANCELLED", "Plugin stream read was aborted");
+}
+function mutationOutcome(options, posted) {
+    if (!options.mutation)
+        return undefined;
+    return posted ? "unknown" : "not_committed";
+}
+function requestCancelledError(options, posted) {
+    if (options.cancellationKind === "stream")
+        return streamReadAbortedError();
+    return new PluginBridgeError("PLUGIN_BRIDGE_CANCELLED", "Plugin bridge request was cancelled", undefined, undefined, mutationOutcome(options, posted));
+}
+function abortableStreamRead(read, signal) {
+    if (!signal)
+        return read;
+    if (signal.aborted)
+        return Promise.reject(streamReadAbortedError());
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (callback, value) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            callback(value);
+        };
+        const onAbort = () => finish(reject, streamReadAbortedError());
+        signal.addEventListener("abort", onAbort, { once: true });
+        read.then((value) => finish(resolve, value), (error) => finish(reject, error));
+    });
+}
 function abortableConfirmationDecision(decision, signal) {
     if (signal.aborted) {
         return Promise.reject(new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin confirmation was aborted"));
@@ -3032,7 +4285,7 @@ function normalizePluginJSONObject(value) {
 }
 function normalizePluginJSONValue(value, depth = 0, state = { nodes: 0, seen: new Set() }) {
     state.nodes += 1;
-    if (state.nodes > 4096 || depth > 64)
+    if (state.nodes > maxPluginJSONStructuralNodes || depth > 64)
         throw new TypeError("JSON value exceeds structural limits");
     if (value === null || typeof value === "string" || typeof value === "boolean")
         return value;
@@ -3119,15 +4372,25 @@ function removeUndefined(value) {
             delete value[key];
     return value;
 }
-function toBridgeError(error, fallbackCode) {
+function toBridgeError(error, defaultCode) {
     if (error instanceof PluginBridgeError)
         return error;
+    if (error instanceof PluginPlatformRequestError) {
+        return new PluginBridgeError(error.errorCode, error.message, undefined, error.details, error.mutationOutcome);
+    }
+    if (error instanceof PluginTransportError) {
+        return new PluginBridgeError(defaultCode, error.message, undefined, undefined, error.mutationOutcome);
+    }
     if (error instanceof Error)
-        return new PluginBridgeError(fallbackCode, error.message);
-    return new PluginBridgeError(fallbackCode, String(error));
+        return new PluginBridgeError(defaultCode, error.message);
+    return new PluginBridgeError(defaultCode, String(error));
 }
 function streamReadFailureInvalidatesCredential(error) {
     if (!(error instanceof PluginBridgeError))
         return true;
     return streamCredentialInvalidatingErrorCodes.has(error.errorCode);
 }
+function retryableStreamReadTransportFailure(error) {
+    return error instanceof PluginTransportError ||
+        (error instanceof PluginBridgeError && error.errorCode === "PLUGIN_BRIDGE_TIMEOUT");
+}