@floegence/redevplugin-ui 3.0.27 → 3.0.29

package/dist/openapi.gen.d.ts

@@ -340,6 +340,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
+        /** @description Authorized worker calls wait for runtime startup and plugin preparation before execution admission. Cancellation or preparation failure prevents dispatch. Executed calls are never automatically retried. */
         post: operations["callPluginMethod"];
         delete?: never;
         options?: never;
@@ -356,6 +357,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
+        /** @description Worker confirmation targets wait for runtime startup and plugin preparation before binding the current runtime generation. Preparation does not execute the method. */
         post: operations["preparePluginMethodConfirmation"];
         delete?: never;
         options?: never;

package/dist/surface.d.ts

@@ -455,9 +455,14 @@ export type PluginSurfaceHostBootstrap = {
     runtimeGenerationId: string;
 };
 export type PluginSurfaceHostContext = PluginSurfaceContext;
+export type PluginSurfaceOpeningStage = "preparing" | "connecting" | "authorizing" | "initializing" | "committing";
+export type PluginSurfaceOpeningMilestone = "frame_load" | "prepare" | "port_ack" | "token" | "renderer_ready" | "worker_ready" | "first_commit";
 export type PluginSurfaceOpeningProgress = {
     phase: "opening";
     elapsedMs: number;
+    stage: PluginSurfaceOpeningStage;
+    stageElapsedMs: number;
+    pendingMilestones: PluginSurfaceOpeningMilestone[];
 };
 export type PluginSurfaceInteractionKind = "activation" | "focus" | "wheel" | "text-selection" | "action";
 export type PluginSurfaceInteractionEvent = {

package/dist/surface.js

@@ -2586,10 +2586,10 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
       currentContext = message.context;
       try { applyStaticDocument(currentDocument); if (currentContext) applySurfaceContext(currentContext); startWorker(currentDocument); }
       catch (error) { return fail(error); }
-      requestAnimationFrame(() => requestAnimationFrame(() => {
-        sendParent({ type: "redevplugin.surface.first_paint" });
-        loadAssets();
-      }));
+      // Readiness describes applied initialization, not a browser paint. Hidden
+      // and offscreen opaque frames may never receive an animation frame.
+      sendParent({ type: "redevplugin.surface.renderer_ready" });
+      loadAssets();
       return;
     }
     if (isRecord(message) && exactKeys(message, ["type", "frame_generation_id", "surface_handle", "context"]) && message.type === "redevplugin.surface.context" && message.frame_generation_id === frameGenerationID && message.surface_handle === surfaceHandle && validSurfaceContext(message.context)) {
@@ -2687,6 +2687,10 @@ class PluginSurfaceHostImplementation {
     #port;
     #openSignals;
     #openingFailure;
+    #openingStartedAt = 0;
+    #openingStageStartedAt = 0;
+    #openingStage = "preparing";
+    #openingPending = new Set();
     #quiesce;
     #initialFrameLoad;
     #frameLoaded = false;
@@ -2742,23 +2746,22 @@ class PluginSurfaceHostImplementation {
         }
         this.#opened = true;
         this.#openingFailure = undefined;
-        const startedAt = Date.now();
-        const progressTimer = setTimeout(() => {
+        this.#openingStartedAt = performance.now();
+        this.#setOpeningStage("preparing", ["frame_load", "prepare"]);
+        const progressTimer = setInterval(() => {
             if (!this.#ready && !this.#disposed) {
-                this.#reportOpeningProgress({
-                    phase: "opening",
-                    elapsedMs: Math.max(openingProgressDelayMs, Date.now() - startedAt),
-                });
+                const progress = this.#openingProgress();
+                this.#reportOpeningProgress({ ...progress, elapsedMs: Math.max(openingProgressDelayMs, progress.elapsedMs) });
             }
         }, openingProgressDelayMs);
         const signals = {
             portAcknowledged: deferred(),
-            firstPaint: deferred(),
+            rendererReady: deferred(),
             workerReady: deferred(),
             firstCommit: deferred(),
         };
         void signals.portAcknowledged.promise.catch(() => undefined);
-        void signals.firstPaint.promise.catch(() => undefined);
+        void signals.rendererReady.promise.catch(() => undefined);
         void signals.workerReady.promise.catch(() => undefined);
         void signals.firstCommit.promise.catch(() => undefined);
         this.#openSignals = signals;
@@ -2773,9 +2776,11 @@ class PluginSurfaceHostImplementation {
             await withTimeout(this.#completeOpening(signals, initialFrameLoad.promise), this.#loadTimeoutMs, "Plugin surface opening timed out");
         }
         catch (error) {
-            const bridgeError = this.#openingFailure ?? toBridgeError(error, "PLUGIN_BRIDGE_HANDSHAKE_FAILED");
-            if (bridgeError.errorCode === "PLUGIN_BRIDGE_TIMEOUT")
+            let bridgeError = this.#openingFailure ?? toBridgeError(error, "PLUGIN_BRIDGE_HANDSHAKE_FAILED");
+            if (bridgeError.errorCode === "PLUGIN_BRIDGE_TIMEOUT") {
+                bridgeError = new PluginBridgeError(bridgeError.errorCode, bridgeError.message, undefined, this.#openingProgress(), bridgeError.mutationOutcome);
                 this.#reloadLimiter.recordCrash();
+            }
             this.#reportError(bridgeError);
             const revoke = this.#revokeSurface(false);
             this.#disposeLocal();
@@ -2783,20 +2788,28 @@ class PluginSurfaceHostImplementation {
             throw bridgeError;
         }
         finally {
-            clearTimeout(progressTimer);
+            clearInterval(progressTimer);
+            this.#openingPending.clear();
             this.#openSignals = undefined;
             this.#openingFailure = undefined;
             this.#initialFrameLoad = undefined;
         }
     }
     async #completeOpening(signals, initialFrameLoad) {
-        const [preparation] = await Promise.all([this.#prepareSurface(), initialFrameLoad]);
+        const [preparation] = await Promise.all([
+            this.#prepareSurface().then((value) => {
+                this.#openingPending.delete("prepare");
+                return value;
+            }),
+            initialFrameLoad.then(() => { this.#openingPending.delete("frame_load"); }),
+        ]);
         this.#assertActive();
         validateSurfacePreparation(this.bootstrap, preparation);
         this.#assetSession = preparation.asset_session;
         this.#assetSessionID = preparation.asset_session_id;
         this.#document = preparation.document;
         this.#assets = new Map(preparation.document.assets.map((asset) => [asset.binding_id, asset]));
+        this.#setOpeningStage("connecting", ["port_ack"]);
         const channel = this.#createMessageChannel();
         this.#port = channel.port1;
         this.#port.addEventListener("message", this.#onPortMessage);
@@ -2811,9 +2824,11 @@ class PluginSurfaceHostImplementation {
         }, "*", [channel.port2]);
         await signals.portAcknowledged.promise;
         this.#assertActive();
+        this.#setOpeningStage("authorizing", ["token"]);
         const token = await this.#mintBridgeToken();
         this.#assertActive();
         this.#applyLease(token);
+        this.#setOpeningStage("initializing", ["renderer_ready", "worker_ready"]);
         this.#postToRenderer(removeUndefined({
             type: "redevplugin.surface.initialize",
             frame_generation_id: this.frameGenerationId,
@@ -2822,10 +2837,11 @@ class PluginSurfaceHostImplementation {
             context: this.#surfaceContext,
         }));
         this.#rendererInitialized = true;
-        await Promise.all([signals.firstPaint.promise, signals.workerReady.promise]);
+        await Promise.all([signals.rendererReady.promise, signals.workerReady.promise]);
         this.#assertActive();
         this.#bridgeReady = true;
         this.#scheduleLeaseRenewal();
+        this.#setOpeningStage("committing", ["first_commit"]);
         this.#postToRenderer({ type: "redevplugin.bridge.lifecycle", event: { type: "ready" } });
         await signals.firstCommit.promise;
         this.#assertActive();
@@ -2921,7 +2937,7 @@ class PluginSurfaceHostImplementation {
             controller.abort();
         this.#pendingRequestControllers.clear();
         const disposedError = new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin surface host was disposed");
-        this.#openSignals?.firstPaint.reject(disposedError);
+        this.#openSignals?.rendererReady.reject(disposedError);
         this.#openSignals?.workerReady.reject(disposedError);
         this.#openSignals?.firstCommit.reject(disposedError);
         this.#openSignals?.portAcknowledged.reject(disposedError);
@@ -2969,20 +2985,24 @@ class PluginSurfaceHostImplementation {
             }
             if (!messageWithinLimit(data))
                 return;
-            if (hasExactKeys(data, ["type"]) && data.type === "redevplugin.surface.first_paint") {
-                this.#openSignals?.firstPaint.resolve();
+            if (hasExactKeys(data, ["type"]) && data.type === "redevplugin.surface.renderer_ready") {
+                this.#openingPending.delete("renderer_ready");
+                this.#openSignals?.rendererReady.resolve();
                 return;
             }
             if (hasExactKeys(data, ["type", "frame_generation_id"]) &&
                 data.type === "redevplugin.surface.port_ack" && data.frame_generation_id === this.frameGenerationId) {
+                this.#openingPending.delete("port_ack");
                 this.#openSignals?.portAcknowledged.resolve();
                 return;
             }
             if (hasExactKeys(data, ["type"]) && data.type === "redevplugin.surface.worker_ready") {
+                this.#openingPending.delete("worker_ready");
                 this.#openSignals?.workerReady.resolve();
                 return;
             }
             if (hasExactKeys(data, ["type"]) && data.type === "redevplugin.surface.first_commit") {
+                this.#openingPending.delete("first_commit");
                 this.#openSignals?.firstCommit.resolve();
                 return;
             }
@@ -3528,7 +3548,7 @@ class PluginSurfaceHostImplementation {
         this.#rendererInitialized = false;
         const terminalError = opening ? (this.#openingFailure ??= error) : error;
         this.#openSignals?.portAcknowledged.reject(terminalError);
-        this.#openSignals?.firstPaint.reject(terminalError);
+        this.#openSignals?.rendererReady.reject(terminalError);
         this.#openSignals?.workerReady.reject(terminalError);
         this.#openSignals?.firstCommit.reject(terminalError);
         if (!opening)
@@ -3583,6 +3603,21 @@ class PluginSurfaceHostImplementation {
             // Observers cannot weaken revocation or local teardown invariants.
         }
     }
+    #setOpeningStage(stage, pending) {
+        this.#openingStage = stage;
+        this.#openingStageStartedAt = performance.now();
+        this.#openingPending = new Set(pending);
+    }
+    #openingProgress() {
+        const now = performance.now();
+        return {
+            phase: "opening",
+            elapsedMs: Math.max(0, Math.floor(now - this.#openingStartedAt)),
+            stage: this.#openingStage,
+            stageElapsedMs: Math.max(0, Math.floor(now - this.#openingStageStartedAt)),
+            pendingMilestones: [...this.#openingPending],
+        };
+    }
     #reportOpeningProgress(progress) {
         try {
             this.#onOpeningProgress?.(progress);

package/dist/trusted-parent.d.ts

@@ -3,5 +3,5 @@ export * from "./errors.js";
 export * from "./platform.js";
 export { PluginSurfaceScope, createPluginSurfaceScope } from "./surface-scope.js";
 export { PluginSurfaceReloadLimiter, PluginSurfaceSlot, createReDevPluginSurfaceTransport, defaultPluginSurfaceReloadMax, defaultPluginSurfaceReloadWindowMs, isPluginRiskPlan, opaqueSurfaceDocumentSchemaVersion, pluginSurfaceContextSchemaVersion, pluginRiskPlanSchemaVersion, pluginSurfaceFileExportActionWindowMs, pluginSurfaceFileExportMaxBytes, pluginSurfaceFileExportMediaTypes, trustedParentBridgeHandshakeTranscriptSHA256, } from "./surface.js";
-export type { BridgeLifecycleEvent, MessageChannelLike, MessageEventLike, MessagePortLike, OpaqueSurfaceAsset, OpaqueSurfaceDocument, OpaqueSurfaceStyle, OpaqueSurfaceWorker, PluginConfirmationDecision, PluginConfirmationHandler, PluginConfirmationIntent, PluginConfirmationPlan, PluginMethodResult, PluginRiskEffect, PluginRiskFlag, PluginRiskPlan, PluginRiskSeverity, PluginExecutionEvent, PluginSurfaceHost, PluginSurfaceCloseResult, PluginSurfaceOpeningProgress, PluginSurfaceInteractionEvent, PluginSurfaceInteractionKind, PluginSurfaceFileExport, PluginSurfaceFileExportHandler, PluginSurfaceFileExportMediaType, PluginSurfaceQuiesceResult, PluginSurfaceRevocationReconciliation, PluginSurfacePreparationResult, PluginSurfaceContext, PluginSurfaceReloadDecision, PluginSurfaceReloadLimiterOptions, PluginSurfaceReloadState, PluginSurfaceSlotOptions, PluginSurfaceSlotState, ReDevPluginSurfaceTransport, ReDevPluginSurfaceTransportOptions, TrustedParentBridgeHandshake, TrustedParentBridgeTokenRequest, WindowLike, } from "./surface.js";
+export type { BridgeLifecycleEvent, MessageChannelLike, MessageEventLike, MessagePortLike, OpaqueSurfaceAsset, OpaqueSurfaceDocument, OpaqueSurfaceStyle, OpaqueSurfaceWorker, PluginConfirmationDecision, PluginConfirmationHandler, PluginConfirmationIntent, PluginConfirmationPlan, PluginMethodResult, PluginRiskEffect, PluginRiskFlag, PluginRiskPlan, PluginRiskSeverity, PluginExecutionEvent, PluginSurfaceHost, PluginSurfaceCloseResult, PluginSurfaceOpeningProgress, PluginSurfaceOpeningStage, PluginSurfaceOpeningMilestone, PluginSurfaceInteractionEvent, PluginSurfaceInteractionKind, PluginSurfaceFileExport, PluginSurfaceFileExportHandler, PluginSurfaceFileExportMediaType, PluginSurfaceQuiesceResult, PluginSurfaceRevocationReconciliation, PluginSurfacePreparationResult, PluginSurfaceContext, PluginSurfaceReloadDecision, PluginSurfaceReloadLimiterOptions, PluginSurfaceReloadState, PluginSurfaceSlotOptions, PluginSurfaceSlotState, ReDevPluginSurfaceTransport, ReDevPluginSurfaceTransportOptions, TrustedParentBridgeHandshake, TrustedParentBridgeTokenRequest, WindowLike, } from "./surface.js";
 export type { FetchInitLike, FetchLike, FetchResponseLike, PlatformResponse } from "./http.js";

package/package.json

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