@netless/app-slide 0.2.106-beta.1 → 0.2.106-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netless/app-slide",
-  "version": "0.2.106-beta.1",
+  "version": "0.2.106-beta.3",
   "main": "dist/main.cjs.js",
   "module": "dist/main.es.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
     "build": "vite build && npm run types",
     "build:dev": "vite build --mode development && npm run types",
     "cleanup": "rimraf ./dist",
-    "test": "rimraf test/.cache && esbuild test/ResizableContainer.test.ts --bundle --platform=node --format=cjs --outfile=test/.cache/ResizableContainer.test.cjs && node test/.cache/ResizableContainer.test.cjs"
+    "test": "rimraf test/.cache && esbuild test/ResizableContainer.test.ts test/NavigationButtonMode.test.ts test/DocsViewerNavigation.integration.test.ts test/FocusTransition.test.ts --bundle --platform=node --format=cjs --outdir=test/.cache && node test/.cache/ResizableContainer.test.js && node test/.cache/NavigationButtonMode.test.js && node test/.cache/DocsViewerNavigation.integration.test.js && node test/.cache/FocusTransition.test.js && node test/run-runtime-activity.mjs"
   },
   "files": [
     "src",
@@ -18,7 +18,7 @@
   ],
   "devDependencies": {
     "@juggle/resize-observer": "^3.3.1",
-    "@netless/slide": "1.4.61-beta.0",
+    "@netless/slide": "1.4.61",
     "@types/color-string": "^1.5.2",
     "color-string": "^1.9.1",
     "jspdf": "2.5.1",

package/src/SlideController/index.ts

@@ -17,8 +17,9 @@ import { SideEffectManager } from "side-effect-manager";
 import { Slide, SLIDE_EVENTS } from "@netless/slide";
 import { clamp } from "../utils/helpers";
 import { cachedGetBgColor } from "../utils/bgcolor";
-import { log, verbose, setRoomLogger } from "../utils/logger";
+import { log, verbose, setRoomLogger, logger } from "../utils/logger";
 import { getRoomTracker } from "../utils/tracker";
+import { createFocusTransitionQueue, shouldSlideRuntimeBeActive } from "../utils/focus-transition";
 export { syncSceneWithSlide, createDocsViewerPages } from "./helpers";
 
 export const DefaultUrl = "https://convertcdn.netless.link/dynamicConvert";
@@ -80,6 +81,7 @@ export class SlideControllerBase {
 
   protected visible: boolean;
   protected savedIsFrozen: boolean;
+  protected focused = true;
 
   protected invisibleBehavior: "frozen" | "pause";
 
@@ -132,7 +134,9 @@ export class SlideControllerBase {
         log("[Slide] render end", slideIndex);
       } else {
         setTimeout(() => {
+          if (this.destroyed) return;
           this.ready = true;
+          if (this.isLazySetupMode()) void this.reconcileActivity(true).catch(() => undefined);
           resolve();
         }, 1000);
       }
@@ -282,6 +286,10 @@ export class SlideControllerBase {
   protected pollCount = 0;
   protected pollReadyState = () => {
     if (this.ready) {
+      if (this.isLazySetupMode()) {
+        void this.reconcileActivity().catch(() => undefined);
+        return;
+      }
       if (this._toFreeze === 1) {
         this.freeze();
       } else if (this._toFreeze === -1) {
@@ -378,49 +386,117 @@ export class SlideControllerBase {
   };
 
   public isFrozen = false;
+  private resourceStateUnknown = false;
+  private managedActivity = false;
   protected _toFreeze: -1 | 0 | 1 = 0; // -1: unfreeze, 0: no change, 1: freeze
 
-  public freeze = (): Promise<void> => {
+  public setFocusedState = (focused: boolean): Promise<void> => {
+    this.focused = focused;
+    return this.reconcileActivity();
+  };
+
+  private resourceTransition = createFocusTransitionQueue(
+    undefined,
+    async active => {
+      if (this.destroyed) return;
+      // A queued release can become stale before the engine starts it.
+      if (active && this.shouldBeActive()) await this.unfreeze();
+      else await this.freeze();
+    },
+    error => logger.warn("[Slide] resource transition failed", this.context.appId, error)
+  );
+
+  private shouldBeActive = (): boolean => {
+    const wm = this.context.getWindowManager() as any;
+    const host = (this.context as any).getRuntimeActivity?.();
+    const lazy = this.isLazySetupMode();
+    // New hosts own one activity snapshot. Mixing it with the delayed UI
+    // boxState can acknowledge "frozen" while the host expects activation.
+    // Old hosts retain the original local/Attribute checks.
+    const minimized =
+      lazy && host
+        ? !host.active
+        : wm?.boxState === "minimized" ||
+          wm?.attributes?.minimized === true ||
+          this.context.getBoxStatus() === "minimized";
+    return (
+      shouldSlideRuntimeBeActive(
+        !lazy || this.focused,
+        document.visibilityState !== "hidden",
+        minimized
+      ) &&
+      (!lazy || host?.active !== false)
+    );
+  };
+
+  public reconcileActivity = (force = false): Promise<void> => {
+    if (this.destroyed) return Promise.resolve();
+    if (this.isLazySetupMode()) this.managedActivity = true;
+    if (!this.managedActivity) return Promise.resolve();
+    this.visible = document.visibilityState !== "hidden";
+    return this.resourceTransition(this.shouldBeActive(), force);
+  };
+
+  public freeze = async (): Promise<void> => {
+    const previousIsFrozen = this.isFrozen;
+    const previousToFreeze = this._toFreeze;
     this.isFrozen = true;
-    if (this.ready) {
-      log("[Slide] freeze", this.context.appId);
-      if (this.invisibleBehavior === "frozen") {
-        return Promise.resolve(this.slide.frozen());
+    try {
+      if (this.ready) {
+        log("[Slide] freeze", this.context.appId);
+        if (this.invisibleBehavior === "frozen") {
+          await this.slide.frozen();
+        } else {
+          this.slide.pause();
+        }
       } else {
-        this.slide.pause();
+        this._toFreeze = 1;
       }
-    } else {
-      this._toFreeze = 1;
+      this.resourceStateUnknown = false;
+    } catch (error) {
+      this.resourceStateUnknown = true;
+      this.isFrozen = previousIsFrozen;
+      this._toFreeze = previousToFreeze;
+      throw error;
     }
-    return Promise.resolve();
   };
 
   public unfreeze = async (): Promise<void> => {
     if (!this.visible) return;
-    if (!this.isFrozen && this.ready) return;
+    if (!this.isFrozen && this.ready && !this.resourceStateUnknown) return;
+    const previousIsFrozen = this.isFrozen;
+    const previousToFreeze = this._toFreeze;
     this.isFrozen = false;
-    if (this.ready) {
-      let isNeedSyncState = false;
-      log("[Slide] unfreeze", this.context.appId);
-      if (this.invisibleBehavior === "frozen") {
-        await this.slide.release(() => {
-          // release 会重建 player，内部 observer 已关闭，需要按当前 frame 尺寸重绘
+    try {
+      if (this.ready) {
+        let isNeedSyncState = false;
+        log("[Slide] unfreeze", this.context.appId);
+        if (this.invisibleBehavior === "frozen") {
+          await this.slide.release(() => {
+            // release 会重建 player，内部 observer 已关闭，需要按当前 frame 尺寸重绘
+            if (!this.isLazySetupMode() || this.shouldBeActive()) this.slide.notifyFrameResize();
+          });
+          isNeedSyncState = true;
+        } else {
+          this.slide.resume();
           this.slide.notifyFrameResize();
-        });
-        isNeedSyncState = true;
-      } else {
-        this.slide.resume();
-        this.slide.notifyFrameResize();
-      }
-      if (isNeedSyncState) {
-        const state = this.context.storage.state.state;
-        if (state) {
-          log("[Slide] sync storage", JSON.stringify(state));
-          this.slide.setSlideState(state);
         }
+        if (isNeedSyncState && (!this.isLazySetupMode() || this.shouldBeActive())) {
+          const state = this.context.storage.state.state;
+          if (state) {
+            log("[Slide] sync storage", JSON.stringify(state));
+            await this.slide.setSlideState(state);
+          }
+        }
+      } else {
+        this._toFreeze = -1;
       }
-    } else {
-      this._toFreeze = -1;
+      this.resourceStateUnknown = false;
+    } catch (error) {
+      this.resourceStateUnknown = true;
+      this.isFrozen = previousIsFrozen;
+      this._toFreeze = previousToFreeze;
+      throw error;
     }
   };
 
@@ -446,6 +522,10 @@ export class SlideControllerBase {
   };
 
   protected onAppStateChangeHandler = (state: "normal" | "minimized" | "maximized") => {
+    if (this.isLazySetupMode() || this.managedActivity) {
+      void this.reconcileActivity().catch(() => undefined);
+      return;
+    }
     if (state === "minimized") {
       log("[Slide] freeze because app state is minimized");
       this.freeze();
@@ -457,6 +537,10 @@ export class SlideControllerBase {
     status: "normal" | "minimized" | "maximized";
   }) => {
     const { appId, status } = payload;
+    if (appId === this.context.appId && (this.isLazySetupMode() || this.managedActivity)) {
+      void this.reconcileActivity().catch(() => undefined);
+      return;
+    }
     if (appId === this.context.appId && status === "minimized") {
       log("[Slide] freeze because app status is minimized");
       this.freeze();
@@ -479,21 +563,35 @@ export class SlideControllerBase {
     }
   };
 
+  protected isLazySetupMode = (): boolean => {
+    try {
+      return (this.context.getWindowManager() as any)?.lazySetupInMaximizedMode === true;
+    } catch {
+      return false;
+    }
+  };
+
   protected onVisibilityChange = async () => {
+    this.visible = document.visibilityState === "visible";
+    if (this.isLazySetupMode() || this.managedActivity) {
+      await this.reconcileActivity().catch(() => undefined);
+      return;
+    }
     const appStatus = this.getAppStatus();
+    if (!this.visible) {
+      this.savedIsFrozen = this.isFrozen;
+      log("[Slide] freeze because tab becomes invisible");
+      if (!this.isFrozen) await this.freeze();
+      return;
+    }
+
     if (appStatus === "minimized") {
       log("[Slide] do nothing because app state is minimized");
       return;
     }
-    if (!(this.visible = document.visibilityState === "visible")) {
-      this.savedIsFrozen = this.isFrozen;
-      log("[Slide] freeze because tab becomes invisible");
-      this.freeze();
-    } else {
-      if (!this.savedIsFrozen) {
-        log("[Slide] unfreeze because tab becomes visible", { savedIsFrozen: this.savedIsFrozen });
-        this.unfreeze();
-      }
+    if (!this.savedIsFrozen) {
+      log("[Slide] unfreeze because tab becomes visible", { savedIsFrozen: this.savedIsFrozen });
+      await this.unfreeze();
     }
   };
 }

package/src/SlideDocsViewer/index.ts

@@ -12,10 +12,11 @@ import { SideEffectManager } from "side-effect-manager";
 import { createDocsViewerPages } from "../SlideController";
 import { DocsViewer, type DocsViewerPage } from "../DocsViewer";
 import { ResizableContainer } from "../DocsViewer/ResizableContainer";
+import { navigateWithNavigationButton, resolveNavigationButtonMode } from "./navigation";
 import { logger } from "../utils/logger";
 import { isEditable } from "../utils/helpers";
 import type { Attributes, MagixEvents } from "../typings";
-import type { AppOptions } from "..";
+import type { AppOptions, NavigationButtonMode } from "..";
 import type { SyncEventQueuePolicy } from "@netless/slide";
 import { ResizeObserver as ResizeObserverPolyfill } from "@juggle/resize-observer";
 
@@ -55,6 +56,7 @@ export interface SlideDocsViewerConfig {
   appId: string;
   urlInterrupter?: (url: string) => Promise<string>;
   enableScale?: boolean;
+  navigationButtonMode?: NavigationButtonMode;
   onPagesReady?: (pages: DocsViewerPage[]) => void;
   onNavigate?: (index: number, origin?: string) => void;
 }
@@ -79,6 +81,7 @@ export class SlideDocsViewer {
   protected isViewMounted = false;
   protected justSildeReadonly = false;
   protected syncEventQueuePolicy: SyncEventQueuePolicy = "fifo";
+  private readonly navigationButtonMode: NavigationButtonMode;
   private enableScale: boolean;
   private boxSizeEventCount = 0;
   private latestBoxSize: BoxSize | undefined;
@@ -98,6 +101,7 @@ export class SlideDocsViewer {
     appId,
     urlInterrupter,
     enableScale,
+    navigationButtonMode,
     onPagesReady,
     onNavigate,
   }: SlideDocsViewerConfig) {
@@ -109,6 +113,7 @@ export class SlideDocsViewer {
     this.onNavigate = onNavigate || noop;
     this.baseScenePath = baseScenePath;
     this.enableScale = enableScale ?? false;
+    this.navigationButtonMode = resolveNavigationButtonMode(navigationButtonMode);
     this.appId = appId;
     this.viewer = new DocsViewer({
       readonly: box.readonly,
@@ -298,6 +303,7 @@ export class SlideDocsViewer {
   }
 
   public mount() {
+    this.unmountPromise = undefined;
     this.box.mountContent(this.viewer.$content);
     this.box.mountFooter(this.viewer.$footer);
 
@@ -465,29 +471,42 @@ export class SlideDocsViewer {
     return (page > 0 ? page : 1) - 1;
   }
 
-  public async unmount(): Promise<this> {
-    this.offBoxSizeChange?.();
-    this.offBoxSizeChange = undefined;
-    this.contentResizeObserver?.disconnect();
-    this.contentResizeObserver = undefined;
-    if (this.slideController) {
-      const controller = this.slideController;
-      this.slideController = null;
-      await controller.destroy();
+  protected unmountPromise?: Promise<this>;
+  protected destroyPromise?: Promise<void>;
+
+  public unmount(): Promise<this> {
+    if (!this.unmountPromise) {
+      this.unmountPromise = Promise.resolve().then(async () => {
+        this.offBoxSizeChange?.();
+        this.offBoxSizeChange = undefined;
+        this.contentResizeObserver?.disconnect();
+        this.contentResizeObserver = undefined;
+        if (this.slideController) {
+          const controller = this.slideController;
+          this.slideController = null;
+          await controller.destroy();
+        }
+        this.viewer.unmount();
+        this.resizableContainer.destroy(this.box);
+        return this;
+      });
     }
-    this.viewer.unmount();
-    this.resizableContainer.destroy(this.box);
-    return this;
+    return this.unmountPromise;
   }
 
   public setReadonly(readonly: boolean) {
     this.viewer.setReadonly(readonly);
   }
 
-  public async destroy(): Promise<void> {
-    this.sideEffect.flushAll();
-    await this.unmount();
-    this.viewer.destroy();
+  public destroy(): Promise<void> {
+    if (!this.destroyPromise) {
+      this.destroyPromise = Promise.resolve().then(async () => {
+        this.sideEffect.flushAll();
+        await this.unmount();
+        this.viewer.destroy();
+      });
+    }
+    return this.destroyPromise;
   }
 
   public toggleClickThrough(tool?: string) {
@@ -541,7 +560,14 @@ export class SlideDocsViewer {
 
   protected onNewPageIndex = (index: number, origin?: string) => {
     if (this.slideController) {
-      this.slideController.jumpToPage(index + 1, origin);
+      navigateWithNavigationButton(
+        this.navigationButtonMode,
+        origin,
+        this.viewer.pageIndex,
+        index,
+        this.slideController,
+        this.onNavigate
+      );
     }
   };
 

package/src/SlideDocsViewer/navigation.ts

@@ -0,0 +1,33 @@
+import type { NavigationButtonMode } from "..";
+
+export type NavigationButtonAction = "prevStep" | "nextStep";
+
+export function resolveNavigationButtonMode(
+  mode: NavigationButtonMode | undefined
+): NavigationButtonMode {
+  return mode ?? "page";
+}
+
+interface NavigationController {
+  readonly page: number;
+  readonly slide: Record<NavigationButtonAction, () => void>;
+  jumpToPage(page: number, origin?: string): void;
+}
+
+export function navigateWithNavigationButton(
+  mode: NavigationButtonMode,
+  origin: string | undefined,
+  currentPageIndex: number,
+  targetPageIndex: number,
+  controller: NavigationController,
+  onNavigate: (page: number, origin?: string) => void
+): void {
+  if (mode === "step" && origin === "navigation") {
+    const action: NavigationButtonAction =
+      targetPageIndex < currentPageIndex ? "prevStep" : "nextStep";
+    controller.slide[action]();
+    onNavigate(controller.page, origin);
+    return;
+  }
+  controller.jumpToPage(targetPageIndex + 1, origin);
+}

package/src/index.ts

@@ -43,6 +43,8 @@ export { DefaultUrl, apps, FreezerLength, addHooks, useFreezer, log, logger };
 
 export { setFreezerLength, getFreezerLength, onCreated, onDestroyed } from "./utils/freezer";
 
+export type NavigationButtonMode = "page" | "step";
+
 export interface AppOptions
   extends Pick<
     ISlideConfig,
@@ -86,12 +88,14 @@ export interface AppOptions
   invisibleBehavior?: "frozen" | "pause";
   /** just readonly, no operate silder */
   justSildeReadonly?: true;
+  /** footer navigation button behavior @default 'page' */
+  navigationButtonMode?: NavigationButtonMode;
   enableScale?: boolean;
   resourceMaxRetries?: number;
   onResourceMaxRetries: (url: string, error: Error) => void;
   /**
-   * Max time (ms) `setup()` waits for the first `renderEnd` before resolving
-   * anyway (the slide keeps loading in background). Default: 5_000.
+   * First-render warning threshold in ms. Default: 5_000. New lazy hosts
+   * continue awaiting real readiness; legacy/eager hosts resolve on timeout.
    */
   setupReadyTimeout?: number;
 }
@@ -235,6 +239,7 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
       appId: context.appId,
       urlInterrupter: context.getAppOptions()?.urlInterrupter,
       enableScale: context.getAppOptions()?.enableScale ?? false,
+      navigationButtonMode: context.getAppOptions()?.navigationButtonMode,
       onPagesReady: ({ length }) => {
         const index = docsViewer?.viewer.pageIndex || 0;
         context.dispatchAppEvent("pageStateChange", { index, length });
@@ -284,49 +289,43 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
     // a lazy-mode-only cache optimization: inactive unless the WindowManager
     // runs with lazySetupInMaximizedMode enabled (read dynamically — lazy can
     // be disabled at runtime, e.g. when forceMaximized is cleared).
-    const isBlurFreezeAllowed = (): boolean => {
-      const boxStatus = context.getBoxStatus();
-      if (boxStatus) return boxStatus !== "normal";
-      const boxState = context.getWindowManager()?.boxState;
-      return boxState != null && boxState !== "normal";
-    };
     sideEffect.add(() =>
-      context.emitter.on("focus", async (isFocused: boolean) => {
+      context.emitter.on("focus", (isFocused: boolean) => {
         if (disposed) return;
-        if (!isLazySetupMode()) return;
         const controller = docsViewer?.slideController;
-        if (!controller) return;
-        if (!isFocused) {
-          if (!isBlurFreezeAllowed()) return;
-          if (!controller.isFrozen) {
-            log("[Slide] blur freeze", context.appId);
-            await controller.freeze();
-          }
-          return;
-        }
-        if (controller.isFrozen) {
-          log("[Slide] focus unfreeze", context.appId);
-          await controller.unfreeze();
-        }
+        // Emittery waits for listener return values. Propagate the transition
+        // promise so WindowManager commits focus only after resources are
+        // frozen/unfrozen and Slide state restoration has completed.
+        return controller?.setFocusedState(isFocused);
+      })
+    );
+    sideEffect.add(() =>
+      (context.emitter as any).on("runtimeActivity", () => {
+        if (!disposed) return docsViewer?.slideController?.reconcileActivity();
       })
     );
 
     let disposed = false;
     let offDestroy: (() => void) | undefined;
-    const teardown = async (): Promise<void> => {
-      if (disposed) return;
+    let teardownPromise: Promise<void> | undefined;
+    const teardown = (): Promise<void> => {
+      if (teardownPromise) return teardownPromise;
       disposed = true;
-      const removeDestroy = offDestroy;
-      offDestroy = undefined;
-      removeDestroy?.();
-      log("[Slide] destroy", context.appId);
-      if (useFreezer) apps.delete(context.appId);
-      sideEffect.flushAll();
-      if (docsViewer) {
-        const viewer = docsViewer;
-        docsViewer = null;
-        await viewer.destroy();
-      }
+      // Store the promise before cleanup can synchronously trigger another teardown.
+      teardownPromise = Promise.resolve().then(async () => {
+        const removeDestroy = offDestroy;
+        offDestroy = undefined;
+        removeDestroy?.();
+        log("[Slide] destroy", context.appId);
+        if (useFreezer) apps.delete(context.appId);
+        sideEffect.flushAll();
+        if (docsViewer) {
+          const viewer = docsViewer;
+          docsViewer = null;
+          await viewer.destroy();
+        }
+      });
+      return teardownPromise;
     };
     offDestroy = context.emitter.on("destroy", teardown);
 
@@ -336,11 +335,12 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
     (SlideApp as any).__teardownByContext.set(context, teardown);
 
     // Resolve once the SlideController finished its first render (renderEnd).
-    // `false` means timeout or teardown; the slide then keeps loading in the
-    // background without blocking WindowManager's serial setup queue.
+    // New lazy hosts retain the real completion after the warning threshold.
+    // Legacy/eager hosts retain timed readiness; disposal/failure rejects below.
     const waitForFirstRender = (timeoutMs: number): Promise<boolean> =>
       new Promise<boolean>(resolve => {
         let settled = false;
+        let timedOut = false;
         const settle = (loaded: boolean) => {
           if (settled) return;
           settled = true;
@@ -348,7 +348,11 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
           window.clearInterval(pollTimer);
           resolve(loaded);
         };
-        const timeoutTimer = window.setTimeout(() => settle(false), timeoutMs);
+        const timeoutTimer = window.setTimeout(() => {
+          timedOut = true;
+          logger.warn("[Slide] first render still pending", context.appId, timeoutMs);
+          if (!(context as any).waitForActualSetupReady) settle(false);
+        }, timeoutMs);
         // Success path resolves straight from readyPromise (no polling lag);
         // the poll only catches teardown and pre-ready render failures.
         slideControllerRef?.readyPromise.then(
@@ -357,6 +361,7 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
         );
         const pollTimer = window.setInterval(() => {
           if (disposed || firstRenderFailed) settle(false);
+          else if (timedOut && !(context as any).waitForActualSetupReady) settle(false);
         }, 100);
       });
 
@@ -498,6 +503,7 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
 
     const setupReadyTimeout = appOptions?.setupReadyTimeout ?? DEFAULT_SLIDE_SETUP_READY_TIMEOUT;
     return waitForFirstRender(setupReadyTimeout).then(() => {
+      if (disposed) throw new Error("[Slide] disposed before first render");
       if (firstRenderFailed) {
         throw new Error("[Slide] first render failed before ready");
       }

package/src/utils/focus-transition.ts

@@ -0,0 +1,51 @@
+export type FocusTransitionHandler = (isFocused: boolean) => void | Promise<void>;
+
+export function shouldSlideRuntimeBeActive(
+  isFocused: boolean,
+  isVisible: boolean,
+  isMinimized: boolean
+): boolean {
+  return isFocused && isVisible && !isMinimized;
+}
+
+/**
+ * Drops duplicate focus states and serializes opposite resource transitions.
+ * The state tracks accepted events so an in-flight async transition cannot be
+ * started twice by duplicate host signals.
+ */
+export function createFocusTransitionQueue(
+  initialState: boolean | undefined,
+  apply: FocusTransitionHandler,
+  onError?: (error: unknown) => void
+): (isFocused: boolean, force?: boolean) => Promise<void> {
+  let acceptedState = initialState;
+  let revision = 0;
+  let queue = Promise.resolve();
+  let acceptedPromise = Promise.resolve();
+
+  return (isFocused, force = false) => {
+    // A duplicate signal must observe the same completion barrier. Returning
+    // early here would let the host commit focus while freeze/unfreeze is
+    // still running.
+    if (!force && isFocused === acceptedState) return acceptedPromise;
+    acceptedState = isFocused;
+    const transitionRevision = ++revision;
+    const transition = queue
+      .then(() => apply(isFocused))
+      .catch(error => {
+        // Permit a later same-state signal to retry only when no newer focus
+        // transition has superseded the failed request.
+        if (revision === transitionRevision) {
+          acceptedState = undefined;
+          acceptedPromise = Promise.resolve();
+        }
+        onError?.(error);
+        throw error;
+      });
+    // Keep later opposite transitions runnable after a failure, while the
+    // caller still receives the rejection for this exact transition.
+    queue = transition.catch(() => undefined);
+    acceptedPromise = transition;
+    return transition;
+  };
+}