@floegence/redevplugin-ui 3.0.22 → 3.0.24

package/dist/opaque-surface-policy.gen.d.ts

@@ -33,6 +33,7 @@ export declare const opaqueSurfaceRenderLimits: {
     readonly max_text_length: 65536;
     readonly max_attribute_value_length: 4096;
     readonly max_form_fields: 128;
+    readonly max_keyboard_bindings: 128;
     readonly max_canvas_count: 4;
     readonly max_canvas_dimension: 4096;
     readonly max_canvas_total_pixels: 16777216;

package/dist/opaque-surface-policy.gen.js

@@ -215,6 +215,7 @@ export const opaqueSurfaceRenderLimits = {
     "max_text_length": 65536,
     "max_attribute_value_length": 4096,
     "max_form_fields": 128,
+    "max_keyboard_bindings": 128,
     "max_canvas_count": 4,
     "max_canvas_dimension": 4096,
     "max_canvas_total_pixels": 16777216,

package/dist/plugin.d.ts

@@ -2,5 +2,5 @@ export { PluginBridgeClient } from "./surface.js";
 export { PluginBridgeError } from "./errors.js";
 export { pluginAPIMajor } from "./contracts.gen.js";
 export { callCapabilityOperation, callCapabilityStream, callCapabilitySync, isCapabilityBusinessError, } from "./capability-client.js";
-export type { BridgeLifecycleEvent, MessagePortLike, PluginBridgeClientOptions, PluginBridgeRequestOptions, PluginCanvasAccessibilityState, PluginCanvasInputEvent, PluginCanvasKeyEvent, PluginCanvasPointerEvent, PluginCanvasWheelEvent, PluginCanvasResizeEvent, PluginCanvasSurface, PluginJSONObject, PluginJSONValue, PluginMethodResult, PluginExecutionFailureCode, PluginExecutionSnapshot, PluginExecutionProgress, PluginExecutionEvent, PluginExecutionEventList, PluginSurfaceContext, PluginUIActionEvent, PluginUIAttributeValue, PluginUIElementVNode, PluginUIPatchOperation, PluginUIVNode, } from "./surface.js";
+export type { BridgeLifecycleEvent, MessagePortLike, PluginBridgeClientOptions, PluginBridgeRequestOptions, PluginCanvasAccessibilityState, PluginCanvasInputEvent, PluginCanvasKeyEvent, PluginCanvasPointerEvent, PluginCanvasWheelEvent, PluginCanvasResizeEvent, PluginCanvasSurface, PluginSurfaceKeyboardBinding, PluginSurfaceKeyboardEvent, PluginSurfaceKeyboardTargetKind, PluginJSONObject, PluginJSONValue, PluginMethodResult, PluginExecutionFailureCode, PluginExecutionSnapshot, PluginExecutionProgress, PluginExecutionEvent, PluginExecutionEventList, PluginSurfaceContext, PluginUIActionEvent, PluginUIAttributeValue, PluginUIElementVNode, PluginUIPatchOperation, PluginUIVNode, } from "./surface.js";
 export type { PluginCapabilitySchema, PluginCapabilityEffect, PluginCapabilityOperationContract, PluginCapabilityStreamContract, PluginCapabilitySyncContract, PluginCapabilityStreamEvent, PluginCapabilityStreamReadResult, PluginExecution, PluginExecutionTerminalStatus, PluginExecutionWaitOptions, PluginStream, } from "./capability-client.js";

package/dist/surface.d.ts

@@ -149,6 +149,34 @@ export type PluginCanvasWheelEvent = {
     shiftKey: boolean;
 };
 export type PluginCanvasInputEvent = PluginCanvasFocusEvent | PluginCanvasResizeEvent | PluginCanvasKeyEvent | PluginCanvasPointerEvent | PluginCanvasWheelEvent;
+export type PluginSurfaceKeyboardTargetKind = "canvas" | "editable" | "control" | "surface";
+export type PluginSurfaceKeyboardBinding = {
+    id: string;
+    event: "keydown" | "keyup";
+    code: string;
+    repeat: boolean;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+    targetKey: string | null;
+    targetKind: PluginSurfaceKeyboardTargetKind;
+};
+export type PluginSurfaceKeyboardEvent = {
+    event: "keydown" | "keyup";
+    code: string;
+    key: string;
+    repeat: boolean;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+    isComposing: boolean;
+    targetKey: string | null;
+    targetKind: PluginSurfaceKeyboardTargetKind;
+    defaultPrevented: boolean;
+    bindingId: string | null;
+};
 export type PluginMethodResult<T = unknown> = {
     data: T;
     execution_id?: string;
@@ -305,6 +333,8 @@ export declare class PluginBridgeClient {
     render(tree: PluginUIVNode): Promise<void>;
     openCanvas(canvasId: string): Promise<PluginCanvasSurface>;
     updateCanvasAccessibility(canvasId: string, state: PluginCanvasAccessibilityState): Promise<void>;
+    setKeyboardBindings(bindings: readonly PluginSurfaceKeyboardBinding[]): Promise<void>;
+    onKeyboardInput(handler: (event: PluginSurfaceKeyboardEvent) => void): () => void;
     loadImageAsset(assetId: string): Promise<ImageBitmap>;
     onAction(action: string, handler: (event: PluginUIActionEvent) => void): () => void;
     onCanvasInput(canvasId: string, handler: (event: PluginCanvasInputEvent) => void): () => void;

package/dist/surface.js

@@ -28,6 +28,7 @@ export class PluginBridgeClient {
     #pending = new Map();
     #actionHandlers = new Map();
     #canvasInputHandlers = new Map();
+    #keyboardInputHandlers = new Set();
     #lifecycleHandlers = new Set();
     #contextHandlers = new Set();
     #context;
@@ -194,6 +195,37 @@ export class PluginBridgeClient {
             description: state.description,
         });
     }
+    setKeyboardBindings(bindings) {
+        this.#assertActive();
+        if (!validKeyboardBindings(bindings)) {
+            throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin surface keyboard bindings are invalid");
+        }
+        const id = this.#requestID("keyboard");
+        return this.#request(id, {
+            type: "redevplugin.ui.keyboard.bindings",
+            id,
+            bindings: bindings.map((binding) => ({
+                binding_id: binding.id,
+                event: binding.event,
+                code: binding.code,
+                repeat: binding.repeat,
+                alt_key: binding.altKey,
+                ctrl_key: binding.ctrlKey,
+                meta_key: binding.metaKey,
+                shift_key: binding.shiftKey,
+                target_key: binding.targetKey,
+                target_kind: binding.targetKind,
+            })),
+        });
+    }
+    onKeyboardInput(handler) {
+        this.#assertActive();
+        if (typeof handler !== "function") {
+            throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin surface keyboard input subscription is invalid");
+        }
+        this.#keyboardInputHandlers.add(handler);
+        return () => this.#keyboardInputHandlers.delete(handler);
+    }
     loadImageAsset(assetId) {
         this.#assertActive();
         if (!validUIIdentifier(assetId)) {
@@ -257,6 +289,7 @@ export class PluginBridgeClient {
         this.#pending.clear();
         this.#actionHandlers.clear();
         this.#canvasInputHandlers.clear();
+        this.#keyboardInputHandlers.clear();
         this.#lifecycleHandlers.clear();
         this.#contextHandlers.clear();
         this.#context = undefined;
@@ -517,6 +550,12 @@ export class PluginBridgeClient {
         if (canvasInput) {
             for (const handler of this.#canvasInputHandlers.get(canvasInput.canvasId) ?? [])
                 handler(canvasInput.event);
+            return;
+        }
+        const keyboardInput = publicKeyboardInputMessage(data);
+        if (keyboardInput) {
+            for (const handler of this.#keyboardInputHandlers)
+                handler(keyboardInput);
         }
     }
     #requestID(prefix) {
@@ -742,6 +781,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   const maxTextLength = ${opaqueSurfaceRenderLimits.max_text_length};
   const maxAttributeValueLength = ${opaqueSurfaceRenderLimits.max_attribute_value_length};
   const maxFormFields = ${opaqueSurfaceRenderLimits.max_form_fields};
+  const maxKeyboardBindings = ${opaqueSurfaceRenderLimits.max_keyboard_bindings};
   const maxCanvasCount = ${opaqueSurfaceRenderLimits.max_canvas_count};
   const maxCanvasDimension = ${opaqueSurfaceRenderLimits.max_canvas_dimension};
   const maxCanvasTotalPixels = ${opaqueSurfaceRenderLimits.max_canvas_total_pixels};
@@ -867,7 +907,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   let runtimeDisposed = false;
   const pendingWorkerRequests = new Set();
   const pendingRendererCommits = new Set();
-  const requestSequence = { rpc: 0, execution: 0, render: 0, canvas: 0, asset: 0 };
+  const requestSequence = { rpc: 0, execution: 0, render: 0, canvas: 0, asset: 0, keyboard: 0 };
   let executionQuerySurfaceTokens = 8;
   let executionQuerySurfaceRefillAt = performance.now();
   const executionQueryStateIdleMS = 120000;
@@ -881,6 +921,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   let uiGraph = new Map();
   let uiNodes = new Map();
   const controlEdits = new Map();
+  let keyboardBindings = [];
   let lastAutofocusIdentity = "";
   const pendingAssets = new Map();
   const queuedAssets = [];
@@ -898,6 +939,55 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   let retainedImagePixels = 0;
   const canvasRuntimes = new Map();
 
+  const keyboardTarget = (target) => {
+    const origin = target instanceof Element ? target : document.activeElement instanceof Element ? document.activeElement : null;
+    const keyed = origin?.closest("[data-redevplugin-key]");
+    const key = keyed?.getAttribute("data-redevplugin-key");
+    const targetKey = validResourceIdentifier(key) ? key : null;
+    const control = origin?.closest("canvas, input, textarea, select, button");
+    if (!control) return { targetKey, targetKind: "surface" };
+    const tag = control.tagName.toLowerCase();
+    if (tag === "canvas") return { targetKey, targetKind: "canvas" };
+    if (tag === "textarea") return { targetKey, targetKind: "editable" };
+    if (tag === "input" && ["text", "search", "number"].includes((control.getAttribute("type") || "text").toLowerCase())) {
+      return { targetKey, targetKind: "editable" };
+    }
+    return { targetKey, targetKind: "control" };
+  };
+  const handleSurfaceKeyboard = (event) => {
+    if (!initialized || runtimeDisposed || pendingQuiesceID || !workerPort || !["keydown", "keyup"].includes(event.type)) return;
+    const target = keyboardTarget(event.target);
+    const edit = target.targetKey === null ? undefined : controlEdits.get(target.targetKey);
+    const isComposing = Boolean(event.isComposing || edit?.isComposing);
+    const binding = isComposing ? undefined : keyboardBindings.find((candidate) =>
+      candidate.event === event.type && candidate.code === String(event.code || "") &&
+      candidate.repeat === Boolean(event.repeat) && candidate.alt_key === Boolean(event.altKey) &&
+      candidate.ctrl_key === Boolean(event.ctrlKey) && candidate.meta_key === Boolean(event.metaKey) &&
+      candidate.shift_key === Boolean(event.shiftKey) && candidate.target_key === target.targetKey &&
+      candidate.target_kind === target.targetKind
+    );
+    if (binding) event.preventDefault();
+    sendWorker({
+      type: "redevplugin.ui.keyboard.input",
+      event: {
+        event: event.type,
+        code: String(event.code || "").slice(0, 64),
+        key: String(event.key || "").slice(0, 64),
+        repeat: Boolean(event.repeat),
+        alt_key: Boolean(event.altKey),
+        ctrl_key: Boolean(event.ctrlKey),
+        meta_key: Boolean(event.metaKey),
+        shift_key: Boolean(event.shiftKey),
+        is_composing: isComposing,
+        target_key: target.targetKey,
+        target_kind: target.targetKind,
+        default_prevented: Boolean(event.defaultPrevented),
+        binding_id: binding?.binding_id || null,
+      },
+    });
+  };
+  for (const eventType of ["keydown", "keyup"]) document.addEventListener(eventType, handleSurfaceKeyboard, true);
+
   const sendParent = (message) => {
     if (parentPort && withinLimit(message)) parentPort.postMessage(message);
   };
@@ -977,6 +1067,8 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     workerHeartbeatTimeout = undefined;
     workerHeartbeatPendingID = undefined;
     workerReady = false;
+    keyboardBindings = [];
+    for (const eventType of ["keydown", "keyup"]) document.removeEventListener(eventType, handleSurfaceKeyboard, true);
     for (const runtime of canvasRuntimes.values()) runtime.dispose();
     canvasRuntimes.clear();
     if (workerControlPort) {
@@ -1526,8 +1618,8 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     const root = built.node;
     if (!(root instanceof Element)) throw new Error("plugin UI root must be an element");
     validateCanvasIdentifiers(root);
-    const renderState = captureRenderState();
     const committed = await commitOnRenderOpportunity(() => {
+      const renderState = captureRenderState();
       document.body.replaceChildren(root);
       restoreRenderState(renderState);
     });
@@ -1541,8 +1633,8 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   const patchWorkerTree = async (baseRevision, revision, operations) => {
     if (uiRevision < 1 || baseRevision !== uiRevision || revision !== baseRevision + 1) throw new Error("plugin UI patch revision is invalid");
     const validated = validatePatch(operations);
-    const renderState = captureRenderState();
     const committed = await commitOnRenderOpportunity(() => {
+      const renderState = captureRenderState();
       for (const operation of validated.plan) applyPatchOperation(operation);
       validated.graph.commit();
       restoreRenderState(renderState);
@@ -1988,7 +2080,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   const validCall = (value) => exactKeys(value, ["type", "request"]) && value.type === "redevplugin.bridge.call" && isRecord(value.request) && Object.keys(value.request).every((key) => ["id", "method", "params"].includes(key)) && typeof value.request.id === "string" && value.request.id.length <= 128 && typeof value.request.method === "string" && /^[A-Za-z0-9._:-]{1,256}$/.test(value.request.method) && (value.request.params === undefined || isRecord(value.request.params));
   const requestID = (value, expectedKind) => {
     if (typeof value !== "string") return undefined;
-    const match = /^(rpc|execution|render|canvas|asset)_([1-9][0-9]{0,15})$/.exec(value);
+    const match = /^(rpc|execution|render|canvas|asset|keyboard)_([1-9][0-9]{0,15})$/.exec(value);
     if (!match || match[1] !== expectedKind) return undefined;
     const sequence = Number(match[2]);
     return Number.isSafeInteger(sequence) ? { kind: match[1], sequence } : undefined;
@@ -2001,6 +2093,26 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     return true;
   };
   const completeWorkerRequest = (id) => pendingWorkerRequests.delete(id);
+  const validKeyboardBinding = (value) => exactKeys(value, ["binding_id", "event", "code", "repeat", "alt_key", "ctrl_key", "meta_key", "shift_key", "target_key", "target_kind"]) &&
+    validIdentifier(value.binding_id) && ["keydown", "keyup"].includes(value.event) &&
+    typeof value.code === "string" && value.code.length > 0 && value.code.length <= 64 &&
+    typeof value.repeat === "boolean" && typeof value.alt_key === "boolean" && typeof value.ctrl_key === "boolean" &&
+    typeof value.meta_key === "boolean" && typeof value.shift_key === "boolean" &&
+    (value.target_key === null || validResourceIdentifier(value.target_key)) &&
+    ["canvas", "editable", "control", "surface"].includes(value.target_kind);
+  const validKeyboardBindings = (value) => {
+    if (!Array.isArray(value) || value.length > maxKeyboardBindings || !value.every(validKeyboardBinding)) return false;
+    const ids = new Set();
+    const matchers = new Set();
+    for (const binding of value) {
+      if (ids.has(binding.binding_id)) return false;
+      ids.add(binding.binding_id);
+      const matcher = JSON.stringify([binding.event, binding.code, binding.repeat, binding.alt_key, binding.ctrl_key, binding.meta_key, binding.shift_key, binding.target_key, binding.target_kind]);
+      if (matchers.has(matcher)) return false;
+      matchers.add(matcher);
+    }
+    return true;
+  };
   const completeExecutionQueryRequest = (id) => {
     const executionID = executionQueryRequests.get(id);
     executionQueryRequests.delete(id);
@@ -2307,6 +2419,17 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
       updateCanvasAccessibility(message.id, message.canvas_id, message.label, message.description);
       return;
     }
+    if (exactKeys(message, ["type", "id", "bindings"]) && message.type === "redevplugin.ui.keyboard.bindings" && typeof message.id === "string") {
+      if (!acceptWorkerRequest(message.id, "keyboard")) return rejectWorkerRequest(message.id, "duplicate, replayed, or excessive plugin request");
+      if (!validKeyboardBindings(message.bindings)) {
+        completeWorkerRequest(message.id);
+        return rejectWorkerRequest(message.id, "plugin surface keyboard bindings are invalid");
+      }
+      keyboardBindings = message.bindings.map((binding) => ({ ...binding }));
+      completeWorkerRequest(message.id);
+      sendWorker({ type: "redevplugin.bridge.response", id: message.id, ok: true });
+      return;
+    }
     if (exactKeys(message, ["type", "id", "asset_id"]) && message.type === "redevplugin.ui.asset.image.open" && typeof message.id === "string" && validResourceIdentifier(message.asset_id)) {
       if (!acceptWorkerRequest(message.id, "asset")) return rejectWorkerRequest(message.id, "duplicate, replayed, or excessive plugin request");
       const asset = assetByLogicalID.get(message.asset_id);
@@ -4243,6 +4366,35 @@ function publicActionEvent(value) {
         form_data: value.form_data,
     });
 }
+function publicKeyboardInputMessage(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ["type", "event"]) || value.type !== "redevplugin.ui.keyboard.input" || !isRecord(value.event))
+        return undefined;
+    const event = value.event;
+    if (!hasExactKeys(event, ["event", "code", "key", "repeat", "alt_key", "ctrl_key", "meta_key", "shift_key", "is_composing", "target_key", "target_kind", "default_prevented", "binding_id"]) ||
+        (event.event !== "keydown" && event.event !== "keyup") || typeof event.code !== "string" || event.code.length > 64 ||
+        typeof event.key !== "string" || event.key.length > 64 || typeof event.repeat !== "boolean" ||
+        typeof event.alt_key !== "boolean" || typeof event.ctrl_key !== "boolean" || typeof event.meta_key !== "boolean" ||
+        typeof event.shift_key !== "boolean" || typeof event.is_composing !== "boolean" ||
+        (event.target_key !== null && !validUIIdentifier(event.target_key)) ||
+        (event.target_kind !== "canvas" && event.target_kind !== "editable" && event.target_kind !== "control" && event.target_kind !== "surface") ||
+        typeof event.default_prevented !== "boolean" || (event.binding_id !== null && !validActionID(event.binding_id)))
+        return undefined;
+    return {
+        event: event.event,
+        code: event.code,
+        key: event.key,
+        repeat: event.repeat,
+        altKey: event.alt_key,
+        ctrlKey: event.ctrl_key,
+        metaKey: event.meta_key,
+        shiftKey: event.shift_key,
+        isComposing: event.is_composing,
+        targetKey: event.target_key,
+        targetKind: event.target_kind,
+        defaultPrevented: event.default_prevented,
+        bindingId: event.binding_id,
+    };
+}
 function isCanvasReadyCandidate(value) {
     return isRecord(value) && value.type === "redevplugin.ui.canvas.ready" && typeof value.id === "string" && typeof value.canvas_id === "string";
 }
@@ -4401,7 +4553,7 @@ const pluginMethodPattern = new RegExp("^[-A-Za-z0-9._:]{1,256}$");
 const pluginActionPattern = new RegExp("^[-A-Za-z0-9._:]{1,128}$");
 const pluginUIIdentifierPattern = new RegExp("^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$");
 const opaqueHandlePattern = new RegExp("^[-A-Za-z0-9_]{8,160}$");
-const bridgeRequestIDPattern = /^(rpc|execution|render|canvas|asset)_([1-9][0-9]{0,15})$/;
+const bridgeRequestIDPattern = /^(rpc|execution|render|canvas|asset|keyboard)_([1-9][0-9]{0,15})$/;
 function validBridgeRequestID(value, expectedKind) {
     if (typeof value !== "string")
         return false;
@@ -4410,6 +4562,34 @@ function validBridgeRequestID(value, expectedKind) {
         return false;
     return Number.isSafeInteger(Number(match[2]));
 }
+function validKeyboardBinding(value) {
+    return isRecord(value) && hasExactKeys(value, ["id", "event", "code", "repeat", "altKey", "ctrlKey", "metaKey", "shiftKey", "targetKey", "targetKind"]) &&
+        validActionID(value.id) && (value.event === "keydown" || value.event === "keyup") &&
+        typeof value.code === "string" && value.code.length > 0 && value.code.length <= 64 &&
+        typeof value.repeat === "boolean" && typeof value.altKey === "boolean" && typeof value.ctrlKey === "boolean" &&
+        typeof value.metaKey === "boolean" && typeof value.shiftKey === "boolean" &&
+        (value.targetKey === null || validUIIdentifier(value.targetKey)) &&
+        (value.targetKind === "canvas" || value.targetKind === "editable" || value.targetKind === "control" || value.targetKind === "surface");
+}
+function validKeyboardBindings(value) {
+    if (!Array.isArray(value) || value.length > 128 || !value.every(validKeyboardBinding))
+        return false;
+    const ids = new Set();
+    const matchers = new Set();
+    for (const binding of value) {
+        if (ids.has(binding.id))
+            return false;
+        ids.add(binding.id);
+        const matcher = JSON.stringify([
+            binding.event, binding.code, binding.repeat, binding.altKey, binding.ctrlKey,
+            binding.metaKey, binding.shiftKey, binding.targetKey, binding.targetKind,
+        ]);
+        if (matchers.has(matcher))
+            return false;
+        matchers.add(matcher);
+    }
+    return true;
+}
 function validMethod(value) {
     return typeof value === "string" && pluginMethodPattern.test(value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/redevplugin-ui",
-  "version": "3.0.22",
+  "version": "3.0.24",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -40,7 +40,7 @@
     "dist"
   ],
   "dependencies": {
-    "@floegence/redevplugin-contracts": "3.0.22"
+    "@floegence/redevplugin-contracts": "3.0.24"
   },
   "publishConfig": {
     "access": "public"