@floegence/redevplugin-ui 3.0.37 → 3.2.0

package/dist/openapi.gen.d.ts

@@ -684,7 +684,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** @description Projects required permissions only from the active plugin version's Host-verified capability contracts. */
+        /** @description Projects active Worker permission ceilings and Host-verified capability requirements, bound to the active plugin version. */
         post: operations["getPluginPermissionRequirements"];
         delete?: never;
         options?: never;
@@ -1292,7 +1292,13 @@ export interface components {
         SessionScopeRevokeResult: components["schemas"]["SessionScopeV1PublicRevokeResult"];
         SessionScopeRevokeCompleteResult: components["schemas"]["SessionScopeV1CompleteRevokeResult"];
         SessionScopeRevokeIncompleteResult: components["schemas"]["SessionScopeV1IncompleteRevokeResult"];
+        PluginSurfaceActionState: {
+            surface_id: string;
+            can_open: boolean;
+            blocked_reason?: components["schemas"]["PluginActionState"]["blocked_reason"];
+        };
         PluginActionState: {
+            surfaces?: components["schemas"]["PluginSurfaceActionState"][];
             can_open: boolean;
             can_enable: boolean;
             can_disable: boolean;
@@ -1372,6 +1378,7 @@ export interface components {
             active_fingerprint: string;
             management_revision: number;
             contracts: components["schemas"]["PluginPermissionRequirementContract"][];
+            methods?: components["schemas"]["PluginPermissionRequirementMethod"][];
             required_permissions: string[];
         };
         AuthorizationRevisions: {
@@ -1803,6 +1810,7 @@ export interface components {
             method_access: components["schemas"]["ExternalPackageProcessMethodAccessSummary"][];
         };
         ExternalPackageBackgroundSummary: {
+            method?: string;
             /** @enum {string} */
             strategy: "runtime_start" | "on_demand";
             worker_id: string;
@@ -2602,6 +2610,8 @@ export interface components {
                     width: number;
                     height: number;
                 };
+                /** @description Methods required to open this surface. Omitted retains aggregate authorization. An empty array allows opening without method grants; calls remain individually authorized. Requires authorization.scoped.v1. */
+                required_methods?: string[];
             }[];
             capability_bindings?: {
                 binding_id: string;
@@ -2666,7 +2676,9 @@ export interface components {
                     /** @constant */
                     additionalProperties: false;
                 };
-            } & (unknown & unknown & unknown & unknown))[];
+                /** @description Explicit Worker permission ceiling. Omitted retains the package ceiling; an empty array grants no resource permissions. Requires authorization.scoped.v1. */
+                permissions?: ("fs.workspace.read" | "fs.workspace.write" | "fs.home.read" | "fs.home.write" | "fs.environment.read" | "fs.environment.write" | "network.client" | "network.listen" | "process.local")[];
+            } & (unknown & unknown & unknown & unknown & unknown))[];
             workers: {
                 worker_id: string;
                 artifact: string;
@@ -2710,6 +2722,8 @@ export interface components {
                 /** @enum {unknown} */
                 strategy: "runtime_start" | "on_demand";
                 worker_id: string;
+                method?: string;
+                params?: Record<string, never>;
             };
             settings?: {
                 schema_version: number;
@@ -2737,7 +2751,7 @@ export interface components {
                 optional_features?: components["schemas"]["ManifestV9OptionalFeatures"];
             };
             permissions: ("fs.workspace.read" | "fs.workspace.write" | "fs.home.read" | "fs.home.write" | "fs.environment.read" | "fs.environment.write" | "network.client" | "network.listen" | "process.local")[];
-        };
+        } & (unknown & unknown & unknown);
         ManifestV9Locale: string;
         ManifestV9Summary: string;
         ManifestV9Description: string[];
@@ -2806,7 +2820,7 @@ export interface components {
             minProperties?: number;
             maxProperties?: number;
         } & (unknown & unknown)) | unknown | unknown | unknown | unknown | unknown | unknown | unknown | unknown | unknown | unknown | unknown | unknown | unknown);
-        ManifestV9RequiredFeatures: ("io.stream.v1" | "fs.workspace.v1" | "fs.home.v1" | "fs.environment.v1" | "fs.watch.v1" | "net.http.v1" | "net.websocket.v1" | "net.tcp.v1" | "net.udp.v1" | "process.local.v1")[];
+        ManifestV9RequiredFeatures: ("io.stream.v1" | "fs.workspace.v1" | "fs.home.v1" | "fs.environment.v1" | "fs.watch.v1" | "net.http.v1" | "net.websocket.v1" | "net.tcp.v1" | "net.udp.v1" | "process.local.v1" | "authorization.scoped.v1" | "background.method.v1")[];
         ManifestV9OptionalFeatures: string[];
         HostCapabilityPinV1: {
             publisher_id: components["schemas"]["HostCapabilityPinV1Id"];

package/dist/platform.d.ts

@@ -15,6 +15,9 @@ export type PluginRequestOptions = {
 type PlatformSchemas = components["schemas"];
 export type PluginCatalogResult = PlatformSchemas["PluginCatalogResult"];
 export type PluginCatalogRecord = PluginCatalogResult["plugins"][number];
+export type PluginSurfaceActionState = PlatformSchemas["PluginSurfaceActionState"];
+/** Read the Host projection; never infer authorization from manifest permissions. */
+export declare function getPluginSurfaceActionState(record: Pick<PluginCatalogRecord, "action_state">, surfaceId: string): PluginSurfaceActionState;
 export type PluginFeatures = PlatformSchemas["PluginFeaturesSuccessResponse"]["data"];
 export type PluginTrustState = PlatformSchemas["TrustState"];
 export type PluginTrustHashSet = PlatformSchemas["TrustHashSet"];

package/dist/platform.js

@@ -2,6 +2,15 @@ import { assertMutationDispatchable, defaultFetch, dispatchMutationRequest, disp
 import { PluginBridgeError, PluginMutationLifecycleError, PluginTransportError, pluginMutationOutcome, } from "./errors.js";
 import { createReDevPluginSurfaceTransport, openPluginSurfaceInSlot, } from "./surface.js";
 import { defaultPluginSurfaceScope, disposePluginSurfaceScope, invalidatePluginSurfaceScope, } from "./surface-scope.js";
+/** Read the Host projection; never infer authorization from manifest permissions. */
+export function getPluginSurfaceActionState(record, surfaceId) {
+    const state = record.action_state;
+    if (state.surfaces !== undefined) {
+        return state.surfaces.find((surface) => surface.surface_id === surfaceId)
+            ?? { surface_id: surfaceId, can_open: false, blocked_reason: "incompatible" };
+    }
+    return { surface_id: surfaceId, can_open: state.can_open, ...(state.blocked_reason ? { blocked_reason: state.blocked_reason } : {}) };
+}
 function toPluginSurfaceHostBootstrap(value) {
     return {
         pluginId: value.plugin_id,

package/dist/testing.d.ts

@@ -0,0 +1,111 @@
+import { type MessagePortLike, type MessageEventLike, type PluginJSONObject, type PluginUIElementVNode, type PluginSurfaceContext, type PluginUIActionEvent, type PluginBridgeClientOptions } from "./surface.js";
+/** Business/bridge fixture only. It does not certify Host permissions or WASM execution. */
+export type PluginTestCall = {
+    method: string;
+    input?: PluginJSONObject;
+    tree?: PluginUIElementVNode;
+    cancelled: boolean;
+    resolve(value: unknown): void;
+    reject(error: Error): void;
+};
+export type PluginTestHarnessOptions = {
+    context?: PluginSurfaceContext;
+    call?: (method: string, input?: PluginJSONObject) => unknown | Promise<unknown>;
+};
+export declare function createPluginTestContext(languageTag?: string, revision?: number): PluginSurfaceContext;
+/** A deterministic transport adapter around the actual production bridge client. */
+export declare function createPluginTestHarness(options?: PluginTestHarnessOptions): {
+    mode: "fixture";
+    BridgeClient: {
+        new (clientOptions?: PluginBridgeClientOptions): {
+            render(next: PluginUIElementVNode): Promise<void>;
+            readonly surfaceHandle: string;
+            readonly timeoutMs: number;
+            "__#private@#nextID": number;
+            "__#private@#port": MessagePortLike;
+            "__#private@#pending": Map<string, {
+                resolve: (value: unknown) => void;
+                reject: (reason: unknown) => void;
+                timer: ReturnType<typeof setTimeout> | undefined;
+                abortCleanup?: () => void;
+                kind: "json" | "canvas" | "asset";
+                identifier?: string;
+            }>;
+            "__#private@#actionHandlers": Map<string, Set<(event: PluginUIActionEvent) => void>>;
+            "__#private@#canvasInputHandlers": Map<string, Set<(event: import("./surface.js").PluginCanvasInputEvent) => void>>;
+            "__#private@#keyboardInputHandlers": Set<(event: import("./surface.js").PluginSurfaceKeyboardEvent) => void>;
+            "__#private@#lifecycleHandlers": Set<(event: import("./surface.js").BridgeLifecycleEvent) => Promise<void> | void>;
+            "__#private@#contextHandlers": Set<(context: PluginSurfaceContext) => void>;
+            "__#private@#context"?: PluginSurfaceContext;
+            "__#private@#ready": boolean;
+            "__#private@#readyPromise": Promise<void>;
+            "__#private@#resolveReady": () => void;
+            "__#private@#rejectReady": (reason: unknown) => void;
+            "__#private@#lifecycleState": "active" | "quiescing" | "quiesced" | "disposed";
+            "__#private@#handlingLifecycle": boolean;
+            "__#private@#renderRevision": number;
+            "__#private@#committedTree"?: PluginUIElementVNode;
+            "__#private@#pendingRender"?: {
+                tree: PluginUIElementVNode;
+                waiters: Array<{
+                    resolve: () => void;
+                    reject: (reason: unknown) => void;
+                }>;
+            };
+            "__#private@#renderLoop"?: Promise<void>;
+            "__#private@#controlEditRevisions": Map<string, number>;
+            "__#private@#onMessage": (event: MessageEventLike) => void;
+            ready(): Promise<void>;
+            call<T = unknown>(method: string, params?: PluginJSONObject, options?: import("./surface.js").PluginBridgeRequestOptions): Promise<T>;
+            "__#private@#call"<T>(method: string, params: PluginJSONObject | undefined, options: import("./surface.js").PluginBridgeRequestOptions, mutation: boolean): Promise<T>;
+            executionEvents(executionID: string, afterCursor: number, options?: import("./surface.js").PluginBridgeRequestOptions): Promise<import("./surface.js").PluginExecutionEventList>;
+            cancelExecution(executionID: string, reason?: string, options?: import("./surface.js").PluginBridgeRequestOptions): Promise<void>;
+            executionSnapshot(executionID: string, options?: import("./surface.js").PluginBridgeRequestOptions): Promise<import("./surface.js").PluginExecutionSnapshot>;
+            context(): PluginSurfaceContext | undefined;
+            onContext(handler: (context: PluginSurfaceContext) => void): () => void;
+            openCanvas(canvasId: string): Promise<import("./surface.js").PluginCanvasSurface>;
+            updateCanvasAccessibility(canvasId: string, state: import("./surface.js").PluginCanvasAccessibilityState): Promise<void>;
+            setKeyboardBindings(bindings: readonly import("./surface.js").PluginSurfaceKeyboardBinding[]): Promise<void>;
+            onKeyboardInput(handler: (event: import("./surface.js").PluginSurfaceKeyboardEvent) => void): () => void;
+            loadImageAsset(assetId: string): Promise<ImageBitmap>;
+            exportFile(request: import("./surface.js").PluginFileExportRequest, options?: import("./surface.js").PluginBridgeRequestOptions): Promise<void>;
+            onAction(action: string, handler: (event: PluginUIActionEvent) => void): () => void;
+            onCanvasInput(canvasId: string, handler: (event: import("./surface.js").PluginCanvasInputEvent) => void): () => void;
+            onLifecycle(handler: (event: import("./surface.js").BridgeLifecycleEvent) => Promise<void> | void): () => void;
+            dispose(): void;
+            "__#private@#drainRenders"(): Promise<void>;
+            "__#private@#startRenderLoop"(): void;
+            "__#private@#request"<T>(id: string, message: unknown, options?: {
+                kind?: "canvas" | "json" | "asset";
+                identifier?: string;
+                cancellationKind?: "bridge" | "stream";
+                mutation?: boolean;
+                signal?: AbortSignal;
+            }): Promise<T>;
+            "__#private@#dispatchRequest"<T>(id: string, message: unknown, options: {
+                kind?: "canvas" | "json" | "asset";
+                identifier?: string;
+                cancellationKind?: "bridge" | "stream";
+                mutation?: boolean;
+                signal?: AbortSignal;
+            }, transfer?: readonly unknown[]): Promise<T>;
+            "__#private@#takePending"(id: string): {
+                resolve: (value: unknown) => void;
+                reject: (reason: unknown) => void;
+                timer: ReturnType<typeof setTimeout> | undefined;
+                abortCleanup?: () => void;
+                kind: "json" | "canvas" | "asset";
+                identifier?: string;
+            } | undefined;
+            "__#private@#handleMessage"(event: MessageEventLike): Promise<void>;
+            "__#private@#requestID"(prefix: string): string;
+            "__#private@#assertActive"(): void;
+            "__#private@#acceptsPluginWork"(): boolean;
+        };
+    };
+    calls: PluginTestCall[];
+    readonly tree: PluginUIElementVNode | undefined;
+    context(next: PluginSurfaceContext): void;
+    action(action: string, event?: Partial<PluginUIActionEvent>): void;
+    dispose(): void;
+};

package/dist/testing.js

@@ -0,0 +1,83 @@
+import { PluginBridgeClient } from "./surface.js";
+import { PluginBridgeError } from "./errors.js";
+class FixturePort {
+    dispatch;
+    listeners = new Set();
+    closed = false;
+    constructor(dispatch) {
+        this.dispatch = dispatch;
+    }
+    postMessage(message) { if (this.closed)
+        throw new Error("Fixture port is closed"); queueMicrotask(() => { if (!this.closed)
+        this.dispatch(message); }); }
+    addEventListener(_type, listener) { this.listeners.add(listener); }
+    removeEventListener(_type, listener) { this.listeners.delete(listener); }
+    start() { }
+    close() { this.closed = true; this.listeners.clear(); }
+    emit(data) { if (!this.closed)
+        for (const listener of this.listeners)
+            listener({ origin: "null", data }); }
+}
+export function createPluginTestContext(languageTag = "en-US", revision = 1) {
+    return { schema_version: "redevplugin.surface_context.v1", revision, appearance: { color_scheme: "dark", colors: {
+                canvas: "#101010", surface: "#181818", surface_elevated: "#202020", text: "#ffffff", text_muted: "#aaaaaa", border: "#444444", accent: "#66aaff", accent_text: "#000000", success: "#44cc88", warning: "#ffcc44", danger: "#ff6677", focus: "#88bbff",
+            } }, locale: { language_tag: languageTag, direction: "ltr" } };
+}
+/** A deterministic transport adapter around the actual production bridge client. */
+export function createPluginTestHarness(options = {}) {
+    const calls = [], pending = new Map();
+    const clients = new Set();
+    let tree, disposed = false;
+    let context = options.context ?? createPluginTestContext();
+    const port = new FixturePort(message => {
+        const value = message;
+        if (value.type === "redevplugin.bridge.cancel") {
+            const call = pending.get(value.id);
+            if (call)
+                call.cancelled = true;
+            pending.delete(value.id);
+            return;
+        }
+        if (value.type === "redevplugin.ui.mount" || value.type === "redevplugin.ui.patch") {
+            port.emit({ type: "redevplugin.bridge.response", id: value.id, ok: true });
+            return;
+        }
+        if (value.type !== "redevplugin.bridge.call" || !value.request)
+            return;
+        const request = value.request;
+        if (calls.length >= 1024) {
+            port.emit({ type: "redevplugin.bridge.response", id: request.id, ok: false, error_code: "PLUGIN_INVALID_REQUEST", error: "Fixture call history exceeds 1024 entries" });
+            return;
+        }
+        const finish = (response) => { if (!pending.delete(request.id))
+            return; port.emit({ type: "redevplugin.bridge.response", id: request.id, ...response }); };
+        const call = { method: request.method, input: request.params, tree, cancelled: false,
+            resolve: value => finish({ ok: true, data: value }),
+            reject: failure => finish({ ok: false, error_code: failure instanceof PluginBridgeError ? failure.errorCode : "PLUGIN_CAPABILITY_ERROR", error: failure.message }),
+        };
+        calls.push(call);
+        pending.set(request.id, call);
+        if (options.call)
+            void Promise.resolve().then(() => options.call(call.method, call.input)).then(call.resolve, failure => call.reject(failure instanceof Error ? failure : new Error(String(failure))));
+    });
+    class BridgeClient extends PluginBridgeClient {
+        constructor(clientOptions = {}) {
+            if (clients.size || disposed)
+                throw new Error("A fixture owns exactly one bridge client");
+            super({ ...clientOptions, port, surfaceHandle: "surface_author_fixture" });
+            clients.add(this);
+            queueMicrotask(() => { port.emit({ type: "redevplugin.bridge.context", context }); port.emit({ type: "redevplugin.bridge.lifecycle", event: { type: "ready" } }); });
+        }
+        async render(next) { await super.render(next); tree = structuredClone(next); }
+    }
+    return {
+        mode: "fixture", BridgeClient, calls,
+        get tree() { return tree; },
+        context(next) { context = next; port.emit({ type: "redevplugin.bridge.context", context }); },
+        action(action, event = {}) {
+            port.emit({ type: "redevplugin.ui.action", action, event: event.event ?? "click", target_key: event.targetKey ?? "fixture-target", edit_revision: event.editRevision ?? 0, is_composing: event.isComposing ?? false, ...(event.value !== undefined ? { value: event.value } : {}), ...(event.checked !== undefined ? { checked: event.checked } : {}), ...(event.form_data ? { form_data: event.form_data } : {}) });
+        },
+        dispose() { disposed = true; for (const client of clients)
+            client.dispose(); clients.clear(); port.close(); pending.clear(); },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/redevplugin-ui",
-  "version": "3.0.37",
+  "version": "3.2.0",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -34,13 +34,17 @@
     "./local-import": {
       "types": "./dist/local-import.d.ts",
       "default": "./dist/local-import.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@floegence/redevplugin-contracts": "3.0.37",
+    "@floegence/redevplugin-contracts": "3.2.0",
     "@noble/hashes": "2.4.0"
   },
   "publishConfig": {