@floegence/redevplugin-ui 0.4.2 → 0.5.1

package/dist/platform.js

@@ -1,6 +1,8 @@
-import { defaultFetch, readHostEnvelope, trimTrailingSlash } from "./http.js";
+import { assertMutationDispatchable, defaultFetch, dispatchMutationRequest, readMutationPlatformResponse, readPlatformResponse, trimTrailingSlash, } from "./http.js";
+import { PluginBridgeError, PluginMutationLifecycleError, PluginTransportError, pluginMutationOutcome, } from "./errors.js";
+import { createReDevPluginSurfaceTransport, openPluginSurfaceInSlot, } from "./surface.js";
 import { defaultPluginSurfaceScope, disposePluginSurfaceScope, } from "./surface-scope.js";
-export function toPluginSurfaceHostBootstrap(value) {
+function toPluginSurfaceHostBootstrap(value) {
     return {
         pluginId: value.plugin_id,
         pluginInstanceId: value.plugin_instance_id,
@@ -13,7 +15,7 @@ export function toPluginSurfaceHostBootstrap(value) {
         entrySHA256: value.entry_sha256,
         assetTicket: value.asset_ticket,
         assetSessionNonce: value.asset_session_nonce,
-        pluginStateVersion: value.plugin_state_version,
+        managementRevision: value.management_revision,
         revokeEpoch: value.revoke_epoch,
         runtimeGenerationId: value.runtime_generation_id,
     };
@@ -22,121 +24,288 @@ export class PluginPlatformClient {
     #fetch;
     #apiBaseURL;
     #surfaceScope;
+    #surfaceTransport;
+    #onMutationOutcomeUnknown;
     constructor(options = {}) {
         this.#fetch = options.fetch ?? defaultFetch();
         this.#apiBaseURL = trimTrailingSlash(options.apiBaseURL ?? "");
         this.#surfaceScope = options.surfaceScope ?? defaultPluginSurfaceScope;
+        this.#surfaceTransport = options.surfaceTransport;
+        this.#onMutationOutcomeUnknown = options.onMutationOutcomeUnknown;
     }
-    catalog() { return this.#getJSON("/_redevplugin/api/plugins/catalog"); }
-    getCompatibility() { return this.#getJSON("/_redevplugin/api/plugins/platform/compatibility"); }
-    installReleaseRef(request) { return this.#postJSON("/_redevplugin/api/plugins/install-release-ref", request); }
-    updateReleaseRef(request) { return this.#mutatePlugin("/_redevplugin/api/plugins/update-release-ref", request); }
-    downgradePlugin(request) { return this.#mutatePlugin("/_redevplugin/api/plugins/downgrade", request); }
-    enablePlugin(request) { return this.#postJSON("/_redevplugin/api/plugins/enable", request); }
-    disablePlugin(request) { return this.#mutatePlugin("/_redevplugin/api/plugins/disable", request); }
-    uninstallPlugin(request) { return this.#mutatePlugin("/_redevplugin/api/plugins/uninstall", request); }
-    openSurface(request) { return this.#postJSON("/_redevplugin/api/plugins/surfaces/open", request); }
-    async revokeSurfaceScope() {
-        try {
-            return await this.#postJSON("/_redevplugin/api/plugins/surfaces/revoke-scope", {});
+    catalog(options = {}) { return this.#getJSON("/_redevplugin/api/plugins/catalog", options); }
+    features(options = {}) { return this.#getJSON("/_redevplugin/api/plugins/features", options); }
+    getCompatibility(options = {}) { return this.#getJSON("/_redevplugin/api/plugins/platform/compatibility", options); }
+    installReleaseRef(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/install-release-ref", request, options);
+    }
+    updateReleaseRef(request, options = {}) {
+        return this.#mutatePlugin("/_redevplugin/api/plugins/update-release-ref", request, options);
+    }
+    downgradePlugin(request, options = {}) {
+        return this.#mutatePlugin("/_redevplugin/api/plugins/downgrade", request, options);
+    }
+    enablePlugin(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/enable", request, options);
+    }
+    disablePlugin(request, options = {}) {
+        return this.#mutatePlugin("/_redevplugin/api/plugins/disable", request, options);
+    }
+    uninstallPlugin(request, options = {}) {
+        return this.#mutatePlugin("/_redevplugin/api/plugins/uninstall", request, options);
+    }
+    #openSurface(request) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/surfaces/open", request, {});
+    }
+    openSurfaceInSlot(slot, request, options = {}) {
+        const { signal, ...hostOptions } = options;
+        const pluginInstanceId = typeof request.plugin_instance_id === "string"
+            ? request.plugin_instance_id.trim()
+            : "";
+        if (!pluginInstanceId) {
+            return Promise.reject(new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin surface opening requires a canonical plugin instance identifier"));
         }
-        finally {
-            disposePluginSurfaceScope(this.#surfaceScope);
+        if (signal?.aborted) {
+            return Promise.reject(new PluginTransportError("Plugin surface opening was aborted before dispatch", signal.reason, "not_committed"));
         }
+        const surfaceTransport = this.#surfaceTransport ??= createReDevPluginSurfaceTransport({
+            fetch: this.#fetch,
+            apiBaseURL: surfaceTransportAPIBaseURL(this.#apiBaseURL),
+        });
+        const canonicalRequest = {
+            ...request,
+            plugin_instance_id: pluginInstanceId,
+        };
+        return openPluginSurfaceInSlot(slot, {
+            pluginInstanceId,
+            surfaceScope: this.#surfaceScope,
+            signal,
+            abortError: () => new PluginTransportError("Plugin surface opening was aborted after dispatch", signal?.reason, "unknown"),
+            open: () => this.#openSurface(canonicalRequest).then((result) => ({
+                ...hostOptions,
+                bootstrap: toPluginSurfaceHostBootstrap(result),
+                hostTransport: surfaceTransport,
+                surfaceScope: this.#surfaceScope,
+            })),
+        });
     }
-    startRuntime(request = {}) { return this.#postJSON("/_redevplugin/api/plugins/runtime/start", request); }
-    async stopRuntime() {
+    async revokeSurfaceScope(options = {}) {
+        let result;
         try {
-            return await this.#postJSON("/_redevplugin/api/plugins/runtime/stop", {});
+            result = await this.#requestMutation("POST", "/_redevplugin/api/plugins/surfaces/revoke-scope", {}, options);
         }
-        finally {
-            disposePluginSurfaceScope(this.#surfaceScope);
+        catch (error) {
+            await this.#handleMutationFailure(error, undefined, "Plugin surface scope revocation and local teardown failed");
+            throw error;
         }
+        await disposePluginSurfaceScope(this.#surfaceScope);
+        return result;
+    }
+    startRuntime(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/runtime/start", request, options);
+    }
+    stopRuntime(options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/runtime/stop", {}, options);
+    }
+    refreshEnabledRuntimeState(options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/runtime/refresh-enabled", {}, options);
+    }
+    runtimeHealth(options = {}) { return this.#getJSON("/_redevplugin/api/plugins/runtime/health", options); }
+    getSettingsSchema(pluginInstanceId, scope, options = {}) {
+        return this.#getJSON(`/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings/schema?scope=${encodeURIComponent(scope)}`, options);
+    }
+    getSettings(pluginInstanceId, scope, options = {}) {
+        return this.#getJSON(`/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings?scope=${encodeURIComponent(scope)}`, options);
+    }
+    patchSettings(pluginInstanceId, request, options = {}) {
+        return this.#mutatePluginAt("PATCH", `/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings`, pluginInstanceId, request, options);
     }
-    refreshEnabledRuntimeState() { return this.#postJSON("/_redevplugin/api/plugins/runtime/refresh-enabled", {}); }
-    runtimeHealth() { return this.#getJSON("/_redevplugin/api/plugins/runtime/health"); }
-    getSettingsSchema(pluginInstanceId) { return this.#getJSON(`/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings/schema`); }
-    getSettings(pluginInstanceId) { return this.#getJSON(`/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings`); }
-    patchSettings(pluginInstanceId, values) { return this.#patchJSON(`/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings`, { values }); }
-    listOperations(pluginInstanceId) { return this.#getJSON(`/_redevplugin/api/plugins/operations${pluginInstanceId ? `?plugin_instance_id=${encodeURIComponent(pluginInstanceId)}` : ""}`); }
-    getOperation(operationId) { return this.#getJSON(`/_redevplugin/api/plugins/operations/${encodeURIComponent(operationId)}`); }
-    cancelOperation(operationId, reason) { return this.#postJSON(`/_redevplugin/api/plugins/operations/${encodeURIComponent(operationId)}/cancel`, reason ? { reason } : {}); }
-    listIntents(options = {}) {
+    listOperations(options = {}, requestOptions = {}) {
         const params = new URLSearchParams();
-        if (options.intent_id)
-            params.set("intent_id", options.intent_id);
         if (options.plugin_instance_id)
             params.set("plugin_instance_id", options.plugin_instance_id);
+        if (options.cursor)
+            params.set("cursor", options.cursor);
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
         const query = params.toString();
-        return this.#getJSON(`/_redevplugin/api/plugins/intents${query ? `?${query}` : ""}`);
+        return this.#getJSON(`/_redevplugin/api/plugins/operations${query ? `?${query}` : ""}`, requestOptions);
+    }
+    getOperation(operationId, options = {}) {
+        return this.#getJSON(`/_redevplugin/api/plugins/operations/${encodeURIComponent(operationId)}`, options);
     }
-    invokeIntent(request) {
-        return this.#postJSON("/_redevplugin/api/plugins/intents/invoke", request);
+    cancelOperation(operationId, reason, options = {}) {
+        return this.#requestMutation("POST", `/_redevplugin/api/plugins/operations/${encodeURIComponent(operationId)}/cancel`, reason ? { reason } : {}, options);
     }
-    exportData(request) { return this.#postJSON("/_redevplugin/api/plugins/data/export", request); }
-    importData(request) { return this.#postJSON("/_redevplugin/api/plugins/data/import", request); }
-    listRetainedData(options = {}) {
+    listIntents(options = {}, requestOptions = {}) {
         const params = new URLSearchParams();
-        if (options.publisher_id)
-            params.set("publisher_id", options.publisher_id);
-        if (options.plugin_id)
-            params.set("plugin_id", options.plugin_id);
-        if (options.source_plugin_instance_id)
-            params.set("source_plugin_instance_id", options.source_plugin_instance_id);
-        if (options.state)
-            params.set("state", options.state);
+        if (options.intent_id !== undefined)
+            params.set("intent_id", options.intent_id);
+        if (options.plugin_instance_id !== undefined)
+            params.set("plugin_instance_id", options.plugin_instance_id);
         const query = params.toString();
-        return this.#getJSON(`/_redevplugin/api/plugins/retained-data${query ? `?${query}` : ""}`);
+        return this.#getJSON(`/_redevplugin/api/plugins/intents${query ? `?${query}` : ""}`, requestOptions);
+    }
+    invokeIntent(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/intents/invoke", request, options);
+    }
+    exportData(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/data/export", request, options);
+    }
+    deleteDataExport(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/data/export/delete", request, options);
+    }
+    importData(request, options = {}) {
+        return this.#mutatePluginAt("POST", "/_redevplugin/api/plugins/data/import", request.plugin_instance_id, request, options);
     }
-    deleteRetainedData(retainedId) { return this.#postJSON("/_redevplugin/api/plugins/retained-data/delete", { retained_id: retainedId }); }
-    bindRetainedData(request) { return this.#postJSON("/_redevplugin/api/plugins/retained-data/bind", request); }
-    cleanupExpiredRetainedData(request = {}) { return this.#postJSON("/_redevplugin/api/plugins/retained-data/cleanup-expired", request); }
-    listPermissions(pluginInstanceId, activeOnly) {
+    listRetainedData(options = {}, requestOptions = {}) {
         const params = new URLSearchParams();
-        if (pluginInstanceId)
-            params.set("plugin_instance_id", pluginInstanceId);
-        if (activeOnly != null)
-            params.set("active_only", activeOnly ? "true" : "false");
+        if (options.plugin_instance_id)
+            params.set("plugin_instance_id", options.plugin_instance_id);
         const query = params.toString();
-        return this.#getJSON(`/_redevplugin/api/plugins/permissions${query ? `?${query}` : ""}`);
-    }
-    grantPermission(request) { return this.#postJSON("/_redevplugin/api/plugins/permissions/grant", request); }
-    revokePermission(request) { return this.#postJSON("/_redevplugin/api/plugins/permissions/revoke", request); }
-    bindSecret(request) { return this.#postJSON("/_redevplugin/api/plugins/secrets/bind", request); }
-    testSecret(request) { return this.#postJSON("/_redevplugin/api/plugins/secrets/test", request); }
-    deleteSecret(request) { return this.#postJSON("/_redevplugin/api/plugins/secrets/delete", request); }
-    listAuditEvents(options = {}) { return this.#getJSON(`/_redevplugin/api/plugins/audit${queryString(options)}`); }
-    listDiagnosticEvents(options = {}) { return this.#getJSON(`/_redevplugin/api/plugins/diagnostics${queryString(options)}`); }
-    #getJSON(path) { return this.#requestJSON("GET", path); }
-    #postJSON(path, body) { return this.#requestJSON("POST", path, body); }
-    #patchJSON(path, body) { return this.#requestJSON("PATCH", path, body); }
-    async #mutatePlugin(path, request) {
+        return this.#getJSON(`/_redevplugin/api/plugins/retained-data${query ? `?${query}` : ""}`, requestOptions);
+    }
+    deleteRetainedData(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/retained-data/delete", request, options);
+    }
+    bindRetainedData(request, options = {}) {
+        return this.#mutatePluginAt("POST", "/_redevplugin/api/plugins/retained-data/bind", request.target_plugin_instance_id, request, options);
+    }
+    cleanupExpiredRetainedData(request = {}, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/retained-data/cleanup-expired", request, options);
+    }
+    listPermissions(options = {}, requestOptions = {}) {
+        const params = new URLSearchParams();
+        if (options.plugin_instance_id !== undefined)
+            params.set("plugin_instance_id", options.plugin_instance_id);
+        if (options.active_only !== undefined)
+            params.set("active_only", options.active_only ? "true" : "false");
+        const query = params.toString();
+        return this.#getJSON(`/_redevplugin/api/plugins/permissions${query ? `?${query}` : ""}`, requestOptions);
+    }
+    grantPermission(request, options = {}) {
+        return this.#mutatePlugin("/_redevplugin/api/plugins/permissions/grant", request, options);
+    }
+    revokePermission(request, options = {}) {
+        return this.#mutatePlugin("/_redevplugin/api/plugins/permissions/revoke", request, options);
+    }
+    listSecurityPolicies(options = {}) {
+        return this.#getJSON("/_redevplugin/api/plugins/security-policies", options);
+    }
+    getSecurityPolicy(pluginInstanceId, options = {}) {
+        return this.#getJSON(`/_redevplugin/api/plugins/security-policies/${encodeURIComponent(pluginInstanceId)}`, options);
+    }
+    putSecurityPolicy(pluginInstanceId, request, options = {}) {
+        return this.#mutatePluginAt("PUT", `/_redevplugin/api/plugins/security-policies/${encodeURIComponent(pluginInstanceId)}`, pluginInstanceId, request, options);
+    }
+    deleteSecurityPolicy(pluginInstanceId, request, options = {}) {
+        return this.#mutatePluginAt("DELETE", `/_redevplugin/api/plugins/security-policies/${encodeURIComponent(pluginInstanceId)}`, pluginInstanceId, request, options);
+    }
+    bindSecret(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/secrets/bind", request, options);
+    }
+    testSecret(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/secrets/test", request, options);
+    }
+    deleteSecret(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/secrets/delete", request, options);
+    }
+    listDiagnosticEvents(options = {}, requestOptions = {}) {
+        return this.#getJSON(`/_redevplugin/api/plugins/diagnostics${queryString(options)}`, requestOptions);
+    }
+    #getJSON(path, options) {
+        return this.#requestJSON("GET", path, options);
+    }
+    #mutatePlugin(path, request, options) {
+        return this.#mutatePluginAt("POST", path, request.plugin_instance_id, request, options);
+    }
+    async #mutatePluginAt(method, path, pluginInstanceId, request, options) {
+        let result;
         try {
-            return await this.#postJSON(path, request);
+            result = await this.#requestMutation(method, path, request, options);
         }
-        finally {
-            disposePluginSurfaceScope(this.#surfaceScope, request.plugin_instance_id);
+        catch (error) {
+            await this.#handleMutationFailure(error, pluginInstanceId, "Plugin mutation and local surface teardown failed");
+            throw error;
         }
+        await disposePluginSurfaceScope(this.#surfaceScope, pluginInstanceId);
+        return result;
     }
-    async #requestJSON(method, path, body) {
-        const headers = { "Accept": "application/json" };
-        if (body !== undefined)
-            headers["Content-Type"] = "application/json";
-        const response = await this.#fetch(this.#apiBaseURL + path, {
+    async #handleMutationFailure(error, pluginInstanceId, message) {
+        if (pluginMutationOutcome(error) === "not_committed")
+            return;
+        const lifecycleErrors = [];
+        try {
+            await disposePluginSurfaceScope(this.#surfaceScope, pluginInstanceId);
+        }
+        catch (caught) {
+            lifecycleErrors.push(caught);
+        }
+        try {
+            this.#onMutationOutcomeUnknown?.(pluginInstanceId);
+        }
+        catch (caught) {
+            lifecycleErrors.push(caught);
+        }
+        if (lifecycleErrors.length > 0)
+            throw new PluginMutationLifecycleError(message, error, lifecycleErrors);
+    }
+    async #requestJSON(method, path, options) {
+        let response;
+        try {
+            response = await this.#fetch(this.#apiBaseURL + path, {
+                method,
+                headers: { "Accept": "application/json" },
+                credentials: "same-origin",
+                signal: options.signal,
+            });
+        }
+        catch (cause) {
+            throw new PluginTransportError(`Plugin platform request failed for ${method} ${path}`, cause);
+        }
+        return readPlatformResponse(response);
+    }
+    async #requestMutation(method, path, body, options) {
+        const operation = `${method} ${path}`;
+        assertMutationDispatchable(options.signal, operation);
+        const headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        };
+        let encodedBody;
+        try {
+            encodedBody = JSON.stringify(body);
+        }
+        catch (cause) {
+            throw new PluginTransportError(`Plugin platform request body serialization failed for ${operation}`, cause, "not_committed");
+        }
+        const response = await dispatchMutationRequest(this.#fetch, this.#apiBaseURL + path, {
             method,
             headers,
-            body: body === undefined ? undefined : JSON.stringify(body),
+            body: encodedBody,
             credentials: "same-origin",
-        });
-        return readHostEnvelope(response, "PLUGIN_PLATFORM_REQUEST_FAILED");
+            signal: options.signal,
+        }, operation);
+        return readMutationPlatformResponse(response);
     }
 }
 function queryString(values) {
     const params = new URLSearchParams();
     for (const [key, value] of Object.entries(values)) {
-        if (value != null && value !== "")
+        if (value !== undefined)
             params.set(key, String(value));
     }
     const query = params.toString();
     return query ? `?${query}` : "";
 }
+function surfaceTransportAPIBaseURL(value) {
+    if (!value || value.startsWith("/"))
+        return value;
+    const parsed = new URL(value);
+    const currentOrigin = globalThis.location?.origin;
+    if (!currentOrigin || currentOrigin === "null" || parsed.origin !== currentOrigin ||
+        parsed.username !== "" || parsed.password !== "" || parsed.search !== "" || parsed.hash !== "") {
+        throw new TypeError("Plugin surface transport apiBaseURL must be same-origin");
+    }
+    return trimTrailingSlash(parsed.pathname);
+}

package/dist/plugin.d.ts

@@ -1,5 +1,5 @@
 export { PluginBridgeClient } from "./surface.js";
 export { PluginBridgeError } from "./errors.js";
 export { callCapabilityOperation, callCapabilityStream, callCapabilitySync, isCapabilityBusinessError, } from "./capability-client.js";
-export type { BridgeLifecycleEvent, MessagePortLike, PluginBridgeClientOptions, PluginCanvasAccessibilityState, PluginCanvasInputEvent, PluginCanvasKeyEvent, PluginCanvasPointerEvent, PluginCanvasResizeEvent, PluginCanvasSurface, PluginJSONObject, PluginJSONValue, PluginMethodResult, PluginStreamTerminalStatus, PluginUIActionEvent, PluginUIAttributeValue, PluginUIVNode, } from "./surface.js";
-export type { PluginCapabilitySchema, PluginCapabilityStreamEvent, PluginCapabilityStreamReadResult, PluginOperation, PluginStream, } from "./capability-client.js";
+export type { BridgeLifecycleEvent, MessagePortLike, PluginBridgeClientOptions, PluginBridgeRequestOptions, PluginCanvasAccessibilityState, PluginCanvasInputEvent, PluginCanvasKeyEvent, PluginCanvasPointerEvent, PluginCanvasResizeEvent, PluginCanvasSurface, PluginJSONObject, PluginJSONValue, PluginMethodResult, PluginStreamTerminalStatus, PluginUIActionEvent, PluginUIAttributeValue, PluginUIElementVNode, PluginUIPatchOperation, PluginUIVNode, } from "./surface.js";
+export type { PluginCapabilitySchema, PluginCapabilityEffect, PluginCapabilityOperationContract, PluginCapabilityStreamContract, PluginCapabilitySyncContract, PluginCapabilityStreamEvent, PluginCapabilityStreamReadResult, PluginOperation, PluginStream, } from "./capability-client.js";

package/dist/surface-scope.d.ts

@@ -4,5 +4,5 @@ export declare class PluginSurfaceScope {
 }
 export declare function createPluginSurfaceScope(): PluginSurfaceScope;
 export declare const defaultPluginSurfaceScope: PluginSurfaceScope;
-export declare function registerPluginSurface(scope: PluginSurfaceScope, pluginInstanceId: string, dispose: () => void): () => void;
-export declare function disposePluginSurfaceScope(scope: PluginSurfaceScope, pluginInstanceId?: string): void;
+export declare function registerPluginSurface(scope: PluginSurfaceScope, pluginInstanceId: string, dispose: () => Promise<void> | void): () => void;
+export declare function disposePluginSurfaceScope(scope: PluginSurfaceScope, pluginInstanceId?: string): Promise<void>;

package/dist/surface-scope.js

@@ -1,4 +1,10 @@
 const registrations = new WeakMap();
+function canonicalPluginInstanceId(pluginInstanceId) {
+    const canonical = typeof pluginInstanceId === "string" ? pluginInstanceId.trim() : "";
+    if (!canonical)
+        throw new TypeError("Plugin instance identifier must be a non-empty string");
+    return canonical;
+}
 export class PluginSurfaceScope {
     constructor() {
         registrations.set(this, new Map());
@@ -15,17 +21,27 @@ export function registerPluginSurface(scope, pluginInstanceId, dispose) {
     const state = registrations.get(scope);
     if (!state)
         throw new TypeError("Plugin surface scope is invalid");
-    const registration = Symbol(pluginInstanceId);
-    state.set(registration, { pluginInstanceId, dispose });
+    const canonicalPluginId = canonicalPluginInstanceId(pluginInstanceId);
+    const registration = Symbol(canonicalPluginId);
+    state.set(registration, { pluginInstanceId: canonicalPluginId, dispose });
     return () => state.delete(registration);
 }
-export function disposePluginSurfaceScope(scope, pluginInstanceId) {
+export async function disposePluginSurfaceScope(scope, pluginInstanceId) {
     const state = registrations.get(scope);
     if (!state)
         throw new TypeError("Plugin surface scope is invalid");
-    const selected = [...state.entries()].filter(([, registration]) => pluginInstanceId === undefined || registration.pluginInstanceId === pluginInstanceId);
+    const canonicalPluginId = pluginInstanceId === undefined
+        ? undefined
+        : canonicalPluginInstanceId(pluginInstanceId);
+    const selected = [...state.entries()].filter(([, registration]) => canonicalPluginId === undefined || registration.pluginInstanceId === canonicalPluginId);
     for (const [key] of selected)
         state.delete(key);
-    for (const [, registration] of selected)
-        registration.dispose();
+    const results = await Promise.allSettled(selected.map(([, registration]) => Promise.resolve().then(() => registration.dispose())));
+    const failures = results
+        .filter((result) => result.status === "rejected")
+        .map((result) => result.reason);
+    if (failures.length === 1)
+        throw failures[0];
+    if (failures.length > 1)
+        throw new AggregateError(failures, "Plugin surface scope teardown failed");
 }

package/dist/surface.d.ts

@@ -1,9 +1,10 @@
-import { PluginBridgeError } from "./errors.js";
+import { PluginBridgeError, type PluginMutationOutcome } from "./errors.js";
 import { pluginUIProtocolVersion } from "./contracts.gen.js";
-import { type OpaqueSurfaceAllowedTag } from "./opaque-surface-policy.gen.js";
 import { type FetchLike } from "./http.js";
 import { type PluginSurfaceScope } from "./surface-scope.js";
-export declare const opaqueSurfaceDocumentSchemaVersion: "redevplugin.opaque_surface_document.v2";
+import { type PluginUIVNode } from "./ui-reconciler.js";
+export type { PluginUIAttributeValue, PluginUIElementVNode, PluginUIPatchOperation, PluginUIVNode, } from "./ui-reconciler.js";
+export declare const opaqueSurfaceDocumentSchemaVersion: "redevplugin.opaque_surface_document.v3";
 export declare const pluginRiskPlanSchemaVersion: "redevplugin.capability.risk_plan.v1";
 export type PluginJSONValue = null | boolean | number | string | PluginJSONValue[] | PluginJSONObject;
 export type PluginJSONObject = {
@@ -26,7 +27,7 @@ export type TrustedParentBridgeHandshake = {
     active_fingerprint: string;
     bridge_nonce: string;
     asset_session_nonce: string;
-    plugin_state_version: number;
+    management_revision: number;
     revoke_epoch: number;
     ui_protocol_version: typeof pluginUIProtocolVersion;
 };
@@ -53,6 +54,7 @@ export type PluginBridgeResponse = {
     error_code: string;
     error: string;
     error_details?: PluginJSONObject;
+    mutation_outcome?: PluginMutationOutcome;
 };
 export type PluginBridgeCancelMessage = {
     type: "redevplugin.bridge.cancel";
@@ -70,6 +72,9 @@ export type PluginBridgeLifecycleAckMessage = {
 export type PluginUIActionEvent = {
     action: string;
     event: "click" | "input" | "change" | "submit" | "escape";
+    targetKey: string;
+    editRevision: number;
+    isComposing: boolean;
     value?: string;
     checked?: boolean;
     form_data?: Record<string, string>;
@@ -117,13 +122,6 @@ export type PluginCanvasPointerEvent = {
     pressure: number;
 };
 export type PluginCanvasInputEvent = PluginCanvasFocusEvent | PluginCanvasResizeEvent | PluginCanvasKeyEvent | PluginCanvasPointerEvent;
-export type PluginUIAttributeValue = string | number | boolean;
-export type PluginUIVNode = string | {
-    type: "element";
-    tag: OpaqueSurfaceAllowedTag;
-    attributes?: Record<string, PluginUIAttributeValue>;
-    children?: PluginUIVNode[];
-};
 export type PluginMethodResult<T = unknown> = {
     data: T;
     operation_id?: string;
@@ -227,16 +225,19 @@ export type PluginBridgeClientOptions = {
     port?: MessagePortLike;
     surfaceHandle?: string;
 };
+export type PluginBridgeRequestOptions = {
+    signal?: AbortSignal;
+};
 export declare class PluginBridgeClient {
     #private;
     readonly surfaceHandle: string;
     readonly timeoutMs: number;
     constructor(options?: PluginBridgeClientOptions);
     ready(): Promise<void>;
-    call<T = unknown>(method: string, params?: PluginJSONObject): Promise<T>;
-    readStream(streamHandle: string): Promise<PluginStreamReadResult>;
-    cancelOperation(operationID: string, reason?: string): Promise<void>;
-    render(tree: PluginUIVNode | PluginUIVNode[]): Promise<void>;
+    call<T = unknown>(method: string, params?: PluginJSONObject, options?: PluginBridgeRequestOptions): Promise<T>;
+    readStream(streamHandle: string, options?: PluginBridgeRequestOptions): Promise<PluginStreamReadResult>;
+    cancelOperation(operationID: string, reason?: string, options?: PluginBridgeRequestOptions): Promise<void>;
+    render(tree: PluginUIVNode): Promise<void>;
     openCanvas(canvasId: string): Promise<PluginCanvasSurface>;
     updateCanvasAccessibility(canvasId: string, state: PluginCanvasAccessibilityState): Promise<void>;
     loadImageAsset(assetId: string): Promise<ImageBitmap>;
@@ -322,7 +323,7 @@ export type PluginSurfacePreparationResult = {
     asset_session_nonce: string;
     entry_path: string;
     entry_sha256: string;
-    plugin_state_version: number;
+    management_revision: number;
     revoke_epoch: number;
     issued_at: string;
     expires_at: string;
@@ -340,7 +341,7 @@ export type PluginSurfaceHostBootstrap = {
     entrySHA256: string;
     assetTicket: string;
     assetSessionNonce: string;
-    pluginStateVersion: number;
+    managementRevision: number;
     revokeEpoch: number;
     runtimeGenerationId: string;
 };
@@ -348,6 +349,22 @@ export type PluginSurfaceOpeningProgress = {
     phase: "opening";
     elapsedMs: number;
 };
+export type PluginSurfaceHost = {
+    readonly element: HTMLIFrameElement;
+    readonly surfaceInstanceId: string;
+    sendLifecycle(event: Exclude<BridgeLifecycleEvent, {
+        type: "ready" | "dispose";
+    }>): void;
+    close(): Promise<PluginSurfaceCloseResult>;
+    dispose(): Promise<void>;
+};
+export type PreparedPluginSurfaceHost = PluginSurfaceHost & {
+    readonly bootstrap: PluginSurfaceHostBootstrap;
+    readonly bridgeChannelId: string;
+    readonly frameGenerationId: string;
+    readonly surfaceHandle: string;
+    open(): Promise<void>;
+};
 export type PluginSurfaceHostOptions = {
     bootstrap: PluginSurfaceHostBootstrap;
     hostTransport: ReDevPluginSurfaceTransport;
@@ -361,6 +378,13 @@ export type PluginSurfaceHostOptions = {
     onOpeningProgress?: (progress: PluginSurfaceOpeningProgress) => void;
     onError?: (error: PluginBridgeError) => void;
 };
+type PluginSurfaceOpeningRequest = {
+    pluginInstanceId: string;
+    surfaceScope: PluginSurfaceScope;
+    signal?: AbortSignal;
+    abortError: () => Error;
+    open: () => Promise<PluginSurfaceHostOptions>;
+};
 declare const redevPluginSurfaceTransportBrand: unique symbol;
 export type ReDevPluginSurfaceTransport = {
     readonly [redevPluginSurfaceTransportBrand]: true;
@@ -373,21 +397,30 @@ export declare function createReDevPluginSurfaceTransport(options?: ReDevPluginS
 export type OpaquePluginBootstrapHTMLOptions = {
     scriptNonce?: string;
 };
+export type PluginSurfaceQuiesceResult = {
+    outcome: "acknowledged" | "not_ready" | "timed_out";
+    durationMs: number;
+};
+export type PluginSurfaceCloseResult = {
+    quiesce: PluginSurfaceQuiesceResult;
+    revokeDurationMs: number;
+    totalDurationMs: number;
+};
 export declare function createOpaquePluginBootstrapHTML(options?: OpaquePluginBootstrapHTMLOptions): string;
-export declare class PluginSurfaceHost {
+export declare function createPreparedPluginSurfaceHost(options: PluginSurfaceHostOptions): PreparedPluginSurfaceHost;
+export type PluginSurfaceSlotState = "empty" | "opening" | "ready" | "error" | "disposed";
+export type PluginSurfaceSlotOptions = {
+    stage: HTMLElement;
+    onStateChange?: (state: PluginSurfaceSlotState, error?: PluginBridgeError) => void;
+    onSurfaceClosed?: (result: PluginSurfaceCloseResult) => void;
+};
+export declare function openPluginSurfaceInSlot(slot: PluginSurfaceSlot, request: PluginSurfaceOpeningRequest): Promise<PluginSurfaceHost>;
+export declare function openPreparedPluginSurfaceInSlot(slot: PluginSurfaceSlot, options: PluginSurfaceHostOptions | PromiseLike<PluginSurfaceHostOptions>): Promise<PluginSurfaceHost>;
+export declare class PluginSurfaceSlot {
     #private;
-    readonly element: HTMLIFrameElement;
-    readonly bootstrap: PluginSurfaceHostBootstrap;
-    readonly bridgeChannelId: string;
-    readonly frameGenerationId: string;
-    readonly surfaceHandle: string;
-    static create(options: PluginSurfaceHostOptions): PluginSurfaceHost;
+    readonly element: HTMLElement;
+    static create(options: PluginSurfaceSlotOptions): PluginSurfaceSlot;
     private constructor();
-    open(): Promise<void>;
-    sendLifecycle(event: Exclude<BridgeLifecycleEvent, {
-        type: "ready" | "dispose";
-    }>): void;
-    close(): Promise<void>;
-    dispose(): void;
+    close(): Promise<PluginSurfaceCloseResult | undefined>;
+    dispose(): Promise<void>;
 }
-export {};