@floegence/redevplugin-ui 0.4.3 → 0.6.5

package/dist/platform.js

@@ -1,6 +1,8 @@
-import { defaultFetch, readHostEnvelope, trimTrailingSlash } from "./http.js";
-import { defaultPluginSurfaceScope, disposePluginSurfaceScope, } from "./surface-scope.js";
-export function toPluginSurfaceHostBootstrap(value) {
+import { assertMutationDispatchable, defaultFetch, dispatchMutationRequest, dispatchQueryRequest, readMutationPlatformResponse, readPlatformResponse, trimTrailingSlash, } from "./http.js";
+import { PluginBridgeError, PluginMutationLifecycleError, PluginTransportError, pluginMutationOutcome, } from "./errors.js";
+import { createReDevPluginSurfaceTransport, openPluginSurfaceInSlot, } from "./surface.js";
+import { defaultPluginSurfaceScope, disposePluginSurfaceScope, invalidatePluginSurfaceScope, } from "./surface-scope.js";
+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,320 @@ 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() {
+    catalog(options = {}) { return this.#requestQuery("/_redevplugin/api/plugins/catalog/query", {}, options); }
+    features(options = {}) { return this.#requestQuery("/_redevplugin/api/plugins/features/query", {}, options); }
+    getCompatibility(options = {}) { return this.#requestQuery("/_redevplugin/api/plugins/platform/compatibility/query", {}, 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"));
+        }
+        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,
+            })),
+        });
+    }
+    async revokeSessionScope(options = {}) {
+        let result;
+        try {
+            const raw = await this.#requestMutation("POST", "/_redevplugin/api/plugins/session/revoke-scope", {}, options);
+            if (!isPluginSessionScopeRevokeResult(raw)) {
+                throw new PluginTransportError("Plugin session scope revocation returned an invalid result", new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Invalid session scope revocation result"), "unknown");
+            }
+            result = raw;
+        }
+        catch (error) {
+            await this.#handleSessionRevokeFailure(error);
+            throw error;
+        }
+        await invalidatePluginSurfaceScope(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.#requestQuery("/_redevplugin/api/plugins/runtime/health/query", {}, options); }
+    getSettingsSchema(pluginInstanceId, scope, options = {}) {
+        return this.#requestQuery(`/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings/schema/query`, { scope }, options);
+    }
+    getSettings(pluginInstanceId, scope, options = {}) {
+        return this.#requestQuery(`/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings/query`, { scope }, options);
+    }
+    patchSettings(pluginInstanceId, request, options = {}) {
+        return this.#mutatePluginAt("PATCH", `/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings`, pluginInstanceId, request, options);
+    }
+    listOperations(options = {}, requestOptions = {}) {
+        return this.#requestQuery("/_redevplugin/api/plugins/operations/query", options, requestOptions);
+    }
+    getOperation(operationId, options = {}) {
+        return this.#requestQuery(`/_redevplugin/api/plugins/operations/${encodeURIComponent(operationId)}/query`, {}, options);
+    }
+    cancelOperation(operationId, reason, options = {}) {
+        return this.#requestMutation("POST", `/_redevplugin/api/plugins/operations/${encodeURIComponent(operationId)}/cancel`, reason ? { reason } : {}, options);
+    }
+    listIntents(options = {}, requestOptions = {}) {
+        return this.#requestQuery("/_redevplugin/api/plugins/intents/query", options, 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);
+    }
+    listRetainedData(options = {}, requestOptions = {}) {
+        return this.#requestQuery("/_redevplugin/api/plugins/retained-data/query", options, 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 = {}) {
+        return this.#requestQuery("/_redevplugin/api/plugins/permissions/query", options, 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.#requestQuery("/_redevplugin/api/plugins/security-policies/query", {}, options);
+    }
+    getSecurityPolicy(pluginInstanceId, options = {}) {
+        return this.#requestQuery(`/_redevplugin/api/plugins/security-policies/${encodeURIComponent(pluginInstanceId)}/query`, {}, 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.#requestQuery("/_redevplugin/api/plugins/diagnostics/query", options, requestOptions);
+    }
+    #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("/_redevplugin/api/plugins/surfaces/revoke-scope", {});
+            result = await this.#requestMutation(method, path, request, options);
         }
-        finally {
-            disposePluginSurfaceScope(this.#surfaceScope);
+        catch (error) {
+            await this.#handleMutationFailure(error, pluginInstanceId, "Plugin mutation and local surface teardown failed");
+            throw error;
         }
+        await disposePluginSurfaceScope(this.#surfaceScope, pluginInstanceId);
+        return result;
     }
-    startRuntime(request = {}) { return this.#postJSON("/_redevplugin/api/plugins/runtime/start", request); }
-    async stopRuntime() {
+    async #handleMutationFailure(error, pluginInstanceId, message) {
+        const outcome = pluginMutationOutcome(error);
+        if (outcome === "not_committed" || outcome === undefined)
+            return;
+        const lifecycleErrors = [];
         try {
-            return await this.#postJSON("/_redevplugin/api/plugins/runtime/stop", {});
-        }
-        finally {
-            disposePluginSurfaceScope(this.#surfaceScope);
-        }
-    }
-    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 = {}) {
-        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);
-        const query = params.toString();
-        return this.#getJSON(`/_redevplugin/api/plugins/intents${query ? `?${query}` : ""}`);
-    }
-    invokeIntent(request) {
-        return this.#postJSON("/_redevplugin/api/plugins/intents/invoke", request);
-    }
-    exportData(request) { return this.#postJSON("/_redevplugin/api/plugins/data/export", request); }
-    importData(request) { return this.#postJSON("/_redevplugin/api/plugins/data/import", request); }
-    listRetainedData(options = {}) {
-        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);
-        const query = params.toString();
-        return this.#getJSON(`/_redevplugin/api/plugins/retained-data${query ? `?${query}` : ""}`);
-    }
-    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) {
-        const params = new URLSearchParams();
-        if (pluginInstanceId)
-            params.set("plugin_instance_id", pluginInstanceId);
-        if (activeOnly != null)
-            params.set("active_only", activeOnly ? "true" : "false");
-        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) {
+            await disposePluginSurfaceScope(this.#surfaceScope, pluginInstanceId);
+        }
+        catch (caught) {
+            lifecycleErrors.push(caught);
+        }
+        if (outcome === "unknown") {
+            try {
+                this.#onMutationOutcomeUnknown?.(pluginInstanceId);
+            }
+            catch (caught) {
+                lifecycleErrors.push(caught);
+            }
+        }
+        if (lifecycleErrors.length > 0)
+            throw new PluginMutationLifecycleError(message, error, lifecycleErrors);
+    }
+    async #handleSessionRevokeFailure(error) {
+        const outcome = pluginMutationOutcome(error);
+        if (outcome === "not_committed")
+            return;
+        const lifecycleErrors = [];
+        if (outcome === "committed" || outcome === "unknown") {
+            try {
+                await invalidatePluginSurfaceScope(this.#surfaceScope);
+            }
+            catch (caught) {
+                lifecycleErrors.push(caught);
+            }
+        }
+        if (outcome === "unknown") {
+            try {
+                this.#onMutationOutcomeUnknown?.();
+            }
+            catch (caught) {
+                lifecycleErrors.push(caught);
+            }
+        }
+        if (lifecycleErrors.length > 0) {
+            throw new PluginMutationLifecycleError("Plugin session scope revocation and local invalidation failed", error, lifecycleErrors);
+        }
+    }
+    async #requestQuery(path, body, options) {
+        const operation = `POST ${path}`;
+        let encodedBody;
         try {
-            return await this.#postJSON(path, request);
+            encodedBody = JSON.stringify(body);
         }
-        finally {
-            disposePluginSurfaceScope(this.#surfaceScope, request.plugin_instance_id);
+        catch (cause) {
+            throw new PluginTransportError(`Plugin platform query body serialization failed for ${operation}`, cause);
         }
+        const response = await dispatchQueryRequest(this.#fetch, this.#apiBaseURL + path, {
+            method: "POST",
+            headers: { "Accept": "application/json", "Content-Type": "application/json" },
+            body: encodedBody,
+            credentials: "same-origin",
+            signal: options.signal,
+        }, operation);
+        return readPlatformResponse(response);
     }
-    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 #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 !== "")
-            params.set(key, String(value));
-    }
-    const query = params.toString();
-    return query ? `?${query}` : "";
+const sessionScopeCountKeys = [
+    "surfaces",
+    "asset_tickets",
+    "asset_sessions",
+    "plugin_gateway_tokens",
+    "confirmation_tokens",
+    "stream_tickets",
+    "handle_grants",
+    "confirmations",
+    "operations",
+    "streams",
+    "runtime_executions",
+    "active_network_requests",
+    "sockets",
+    "network_streams",
+    "storage_hostcalls",
+];
+function isPluginSessionScopeRevokeResult(value) {
+    if (!isExactRecord(value, ["state", "fenced", "complete", "counts"]) ||
+        value.state !== "complete" || value.fenced !== true || value.complete !== true)
+        return false;
+    const counts = value.counts;
+    if (!isExactRecord(counts, sessionScopeCountKeys))
+        return false;
+    return sessionScopeCountKeys.every((key) => Number.isSafeInteger(counts[key]) && Number(counts[key]) >= 0);
+}
+function isExactRecord(value, keys) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+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,6 @@ 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, invalidate: () => Promise<void> | void): () => void;
+export declare function disposePluginSurfaceScope(scope: PluginSurfaceScope, pluginInstanceId?: string): Promise<void>;
+export declare function invalidatePluginSurfaceScope(scope: PluginSurfaceScope): Promise<void>;

package/dist/surface-scope.js

@@ -1,7 +1,13 @@
-const registrations = new WeakMap();
+const scopes = 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());
+        scopes.set(this, { invalidated: false, registrations: new Map() });
     }
     static create() {
         return new PluginSurfaceScope();
@@ -11,21 +17,56 @@ export function createPluginSurfaceScope() {
     return PluginSurfaceScope.create();
 }
 export const defaultPluginSurfaceScope = createPluginSurfaceScope();
-export function registerPluginSurface(scope, pluginInstanceId, dispose) {
-    const state = registrations.get(scope);
+export function registerPluginSurface(scope, pluginInstanceId, dispose, invalidate) {
+    const state = scopes.get(scope);
     if (!state)
         throw new TypeError("Plugin surface scope is invalid");
-    const registration = Symbol(pluginInstanceId);
-    state.set(registration, { pluginInstanceId, dispose });
-    return () => state.delete(registration);
+    const canonicalPluginId = canonicalPluginInstanceId(pluginInstanceId);
+    const registration = Symbol(canonicalPluginId);
+    if (state.invalidated) {
+        try {
+            void Promise.resolve(invalidate()).catch(() => undefined);
+        }
+        catch {
+            // A fenced session remains invalid even when a local observer fails.
+        }
+        return () => undefined;
+    }
+    state.registrations.set(registration, { pluginInstanceId: canonicalPluginId, dispose, invalidate });
+    return () => state.registrations.delete(registration);
 }
-export function disposePluginSurfaceScope(scope, pluginInstanceId) {
-    const state = registrations.get(scope);
+export async function disposePluginSurfaceScope(scope, pluginInstanceId) {
+    const state = scopes.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.registrations.entries()].filter(([, registration]) => canonicalPluginId === undefined || registration.pluginInstanceId === canonicalPluginId);
     for (const [key] of selected)
-        state.delete(key);
-    for (const [, registration] of selected)
-        registration.dispose();
+        state.registrations.delete(key);
+    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");
+}
+export async function invalidatePluginSurfaceScope(scope) {
+    const state = scopes.get(scope);
+    if (!state)
+        throw new TypeError("Plugin surface scope is invalid");
+    state.invalidated = true;
+    const selected = [...state.registrations.values()];
+    state.registrations.clear();
+    const results = await Promise.allSettled(selected.map((registration) => Promise.resolve().then(() => registration.invalidate())));
+    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 invalidation failed");
 }