@netless/slide 1.4.55-alpha.1 → 1.4.55-alpha.3

package/README.md

@@ -2,9 +2,40 @@
 
 ## [示例及具体文档参考](https://github.com/netless-io/netless-slide-demo)
 
+## interactive 客户端的同步队列追最新策略
+
+`@netless/slide` 默认按 FIFO 顺序执行所有接收到的同步事件。对于需要在弱网积压时优先追赶最新页面的 interactive 客户端，可以显式启用 `latest-pending-render`；可写端和只读端都可以使用：
+
+```ts
+const slide = new Slide({
+  // 其他配置
+  syncEventQueuePolicy: "latest-pending-render",
+});
+
+slide.setSyncEventQueuePolicy("fifo");
+slide.setSyncEventQueuePolicy("latest-pending-render");
+```
+
+该策略只处理尚未开始执行的 pending 事件：
+
+- 新的 `renderSlide` 到达时，删除同一资源段内排在它之前的 pending 翻页、`nextStep`、`prevStep`、交互动画和媒体操作。
+- 保留最新 `renderSlide`，以及它之后到达的所有操作，并继续按 FIFO 执行。
+- `setResource` 和未知事件是硬边界，不会被删除，也不会跨越边界压缩。
+- 已经开始执行的事件不会被取消；该策略不保证完全不显示 running 中间页。
+- 动态切换策略本身不会清空或重排已有队列；切换后新到达的 `renderSlide` 才会触发压缩。
+- latest 策略下开始执行远端 `renderSlide`，或远端事件形成 pending 积压后，Slide 会暂时阻止本地 `nextStep()`、`prevStep()`、`renderSlide()`、`doRenderSlide()` 和画布交互；同步接收、状态恢复和队列执行不受影响。本机事件优先通过现有 Lock 的 UUID 回包识别，并以 `clientId` 作为补充，不会锁住正在操作的当前控制者。
+- 临时输入锁在同步队列重新空闲后解除，并恢复调用方最近一次通过 `setInteractive()` 设置的权限；不会把原本的只读端恢复成可写。
+
+该能力不会根据 `interactive` 自动开启。调用方应通过自己的灰度开关显式选择；关闭策略时可以恢复为 `fifo`，不会修改调用方原有的本地交互权限。
+
+该策略只在 Slide 的 `mode: "interactive"` 下生效；`sync`、`local` 和 `addLink` mode 会强制使用 `fifo`。这项 mode 保护不能替代调用方的只读权限与 feature flag 判断。
+
+实际发生压缩时，SDK 会通过现有 logger/tracker 记录丢弃分类、保留页码、目标事件接收时间、对应渲染完成时间和追赶输入锁状态；记录中不包含事件 UUID、资源 URL 或 token。
+
 ## changelog
 
 ### 未发布
+* 增加 `latest-pending-render` 同步队列策略，弱网积压时丢弃最后翻页前尚未执行的中间页面操作，并在追赶期间阻止本地输入
 * 修复 PPT 图形内阴影（`innerShadow`）被错误渲染为不透明黑边的问题
   * 按转换数据中的颜色、模糊半径、距离和方向渲染柔化内阴影
   * 使用 SDF 判定形状内边缘，并扩展滤镜与 SDF 边界，避免阴影被裁剪

package/lib/FrozenMediaState.d.ts

@@ -0,0 +1,13 @@
+export interface FrozenMediaPlaybackState {
+    type: "pause" | "play";
+    time: number;
+}
+export declare type FrozenMediaTimes = {
+    [key: string]: number;
+};
+export declare function captureFrozenMediaTimes(mediaState: {
+    [key: string]: FrozenMediaPlaybackState;
+}, frozenTime: number): FrozenMediaTimes;
+export declare function applyFrozenMediaTimes(mediaState: {
+    [key: string]: FrozenMediaPlaybackState;
+}, frozenMediaTimes: FrozenMediaTimes, releaseTime: number): void;

package/lib/Lock.d.ts

@@ -1,9 +1,11 @@
 export declare class Lock {
     private autoUnlock;
+    private localKeyAutoRemove;
+    private localKeys;
     private locks;
     private available;
     constructor(available: boolean);
     addLock(type: string, key: string): void;
-    unlock(type: string, key: string | null | undefined): void;
+    unlock(type: string, key: string | null | undefined): boolean;
     isLocked(type: string): boolean;
 }

package/lib/Lock.js

@@ -4,6 +4,8 @@
 var Lock = /** @class */ (function () {
     function Lock(available) {
         this.autoUnlock = Object.create(null);
+        this.localKeyAutoRemove = Object.create(null);
+        this.localKeys = Object.create(null);
         this.locks = Object.create(null);
         this.available = false;
         this.available = available;
@@ -14,18 +16,32 @@ var Lock = /** @class */ (function () {
             return;
         }
         this.locks[type] = key;
+        this.localKeys[key] = true;
+        this.localKeyAutoRemove[key] = window.setTimeout(function () {
+            delete _this.localKeys[key];
+            delete _this.localKeyAutoRemove[key];
+        }, 60 * 1000);
         this.autoUnlock[type] = window.setTimeout(function () {
             delete _this.locks[type];
+            delete _this.autoUnlock[type];
         }, 3000);
     };
     Lock.prototype.unlock = function (type, key) {
         if (!this.available) {
-            return;
+            return false;
+        }
+        var isLocalEvent = !!key && !!this.localKeys[key];
+        if (key && isLocalEvent) {
+            window.clearTimeout(this.localKeyAutoRemove[key]);
+            delete this.localKeys[key];
+            delete this.localKeyAutoRemove[key];
         }
         if (key && this.locks[type] && this.locks[type] === key) {
             window.clearTimeout(this.autoUnlock[type]);
             delete this.locks[type];
+            delete this.autoUnlock[type];
         }
+        return isLocalEvent;
     };
     Lock.prototype.isLocked = function (type) {
         if (!this.available) {

package/lib/Slide.d.ts

@@ -1,9 +1,10 @@
 import { SlideError, VolumeAdjuster } from "@netless/ppt-player";
 import { IPlugin } from "@netless/plugin-system";
+import type { SyncEventQueuePolicy } from "./SyncTaskManager";
 import { AliTrackLogger } from "./AliTrackLogger";
 import { preloadResource } from "./global";
 export { ErrorType, PreloadCancelledError } from "@netless/ppt-player";
-export declare const LOCAL_GIF_RUNTIME_CAPABILITY = "netless-slide-local-gif-production-client-geometry";
+export type { SyncEventQueuePolicy } from "./SyncTaskManager";
 export declare type UrlInterrupter = (url: string) => Promise<string>;
 export interface ILoaderDelegate {
     /**
@@ -178,10 +179,6 @@ export interface ISlideRenderOptions {
      */
     transitionResolutionLevel?: number;
     antialias?: boolean;
-    /** Maximum compressed bytes accepted for one client-decoded GIF. */
-    localGifMaxCompressedBytes?: number;
-    /** Maximum estimated GIF working set for one cached slide. */
-    localGifMaxWorkingSetBytes?: number;
 }
 export interface INavigatorDelegate {
     gotoPage?: (index: number) => void;
@@ -213,6 +210,12 @@ export interface ISlideConfig {
      * "local" Local mode, no synchronization events will be triggered
      */
     mode: "interactive" | "sync" | "local" | "addLink";
+    /**
+     * Queue policy for received synchronization events.
+     * Default is "fifo". "latest-pending-render" lets interactive clients skip pending intermediate pages.
+     * Non-interactive modes always use "fifo".
+     */
+    syncEventQueuePolicy?: SyncEventQueuePolicy;
     /**
      * Whether to enable global clicking, after turning on, as long as you click within the ppt viewport range,
      * and do not trigger interactive elements inside ppt, it will trigger the next action.
@@ -281,13 +284,18 @@ export interface ISlideConfig {
     skipActionWhenFrozen?: boolean;
     enableAutoForward?: boolean;
     customLinks?: CustomLink[];
+    /**
+     * Disable the built-in ResizeObserver and rely on external notifyFrameResize() calls.
+     * Set this to true when using window-manager's boxSizeChange event as the resize signal.
+     * @default false
+     */
+    disableFrameResizeObserver?: boolean;
     resourceMaxRetries?: number;
     onResourceMaxRetries?: (url: string, error: Error) => void;
 }
 interface MediaState {
     type: "pause" | "play";
     time: number;
-    frozenTime?: number;
     fullscreen?: boolean;
 }
 interface TimeNodeSeqState {
@@ -438,12 +446,14 @@ export declare class Slide extends Slide_base {
     private userInputTime;
     private isSyncingSlideState;
     private frozenTaskManager;
+    private frozenMediaTimes;
     private randomId;
     private resize;
     private isAnimating;
     private renderingTaskManager;
     private isLoading;
     private interactive;
+    private syncCatchUpInputBlocked;
     private anchor;
     private tracker;
     private player?;
@@ -459,6 +469,7 @@ export declare class Slide extends Slide_base {
     private enableGlobalClick;
     private lastEmitedState;
     private syncQueue;
+    private selfSyncEvents;
     private playerController;
     private lock;
     private isInitResized;
@@ -482,6 +493,10 @@ export declare class Slide extends Slide_base {
     private get dispatchIncrId();
     constructor(initConfig: ISlideConfig);
     private _updateVolumeByStaticAdjuster;
+    private handleSyncQueueCompact;
+    private handleSyncQueueCompactRenderComplete;
+    private handleSyncQueueCatchUpStateChange;
+    private updatePlayerInteractive;
     private recoverHandler;
     private reportError;
     initSlideConfig(config: ISlideConfig): ISlideConfig;
@@ -500,6 +515,12 @@ export declare class Slide extends Slide_base {
     private updateStageCountLimit;
     private setMedianControllerAttribute;
     private frameResizeHandler;
+    /**
+     * Notify the slide that its frame container may have changed size.
+     * Call this when using an external resize signal (e.g. window-manager's boxSizeChange event)
+     * instead of the built-in ResizeObserver.
+     */
+    notifyFrameResize(): void;
     /**
      *  Update ppt fixed height and width, this method only takes effect when the fixedFrameSize configuration item is set.
      * @param width Width value that needs to be updated, unit px.
@@ -622,6 +643,7 @@ export declare class Slide extends Slide_base {
      * @param isForward Whether to flip forward or backward, affecting the page transition animation.
      */
     doRenderSlide(index: number, isForward?: boolean): Promise<void>;
+    private enqueueRenderSlide;
     getSnapshot(): string | null;
     /**
      * 执行下一个主序列动画
@@ -647,6 +669,11 @@ export declare class Slide extends Slide_base {
      * @param val boolean
      */
     setInteractive(val: boolean): void;
+    /**
+     * Set how received synchronization events are scheduled.
+     * Changing the policy does not reorder or clear the current pending queue by itself.
+     */
+    setSyncEventQueuePolicy(policy: SyncEventQueuePolicy): void;
     /**
      * Pause playback, asynchronous operation.
      */