@floegence/redevplugin-ui 3.1.0 → 3.2.0

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.1.0",
+  "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.1.0",
+    "@floegence/redevplugin-contracts": "3.2.0",
     "@noble/hashes": "2.4.0"
   },
   "publishConfig": {