@netless/app-presentation 0.1.13-beta.1 → 0.1.13-beta.3

package/README-zh.md

@@ -93,6 +93,24 @@ scenePpt.height = ppt.height * ratio
 
 ### 应用选项
 
+#### Lazy 缓存生命周期与图片就绪
+
+Lazy setup/cache 需要带有 `teardown` 和 focus 事件生命周期的 WindowManager
+`1.0.23-beta.1` 或更高版本；当前集成验证版本为 `1.0.23-beta.3`。
+未启用 lazy 的旧宿主仍可使用普通查看功能。
+
+`setupReadyTimeout` 限制当前背景图的等待时间，默认 5000ms。图片加载成功或请求失败
+均结束等待；尚未设置图片地址的元素仍等待 SDK 赋值。失败/超时会记录警告并允许 setup
+完成，不会取消 SDK 自己的图片加载或重试。
+
+在 lazy 最大化/最小化模式下，失焦 App 优先使用可用的 `ppt.previewURL` 缩略图；
+没有可用缩略图时隐藏背景并替换为静态像素，重新聚焦恢复原图。`thumbnail(src)` 自定义
+侧边预览图，不参与此背景降级策略。设置 `disableBlurThumbnailDegradation: true` 可关闭降级。
+该优化减少常驻图片资源，不保证节省下载流量：宿主可能在首次 setup 等待完成后才补发焦点状态。
+
+预加载为尽力而为：失败时移除对应 link，不自动循环重试；显式重新访问失败页时可再次尝试
+预加载。SDK 的可见图片加载不受此策略影响。
+
 #### `disableDeviceCameraTransform`
 
 禁止鼠标滚轮、触摸手势等本地设备输入改变相机，但不改变程序化相机操作使用的

package/README.md

@@ -99,6 +99,28 @@ handles app whose kind is `DocsViewer` or `Slide`.
 
 ### App Options
 
+#### Lazy cache lifecycle and image readiness
+
+Lazy setup/cache requires WindowManager `1.0.23-beta.1` or later with the
+`teardown` and focus-event lifecycle; integration is currently verified with
+`1.0.23-beta.3`. Older hosts without lazy mode can still use the normal viewer.
+
+`setupReadyTimeout` bounds the current background-image wait (default 5000 ms).
+A loaded image or a failed image request releases the wait; an image element
+without a source still waits for the SDK to assign it. Failure/timeout logs a
+warning and lets setup finish; it does not cancel SDK image loading or retrying.
+
+In lazy maximized/minimized mode, blurred apps use `ppt.previewURL` when it is a
+usable thumbnail. Otherwise their background is hidden behind a static pixel;
+focus restores the original image. `thumbnail(src)` customizes sidebar previews,
+not this background policy. Set `disableBlurThumbnailDegradation: true` to opt out.
+This reduces retained image resources; it does not guarantee reduced downloads,
+since the host can synchronize focus only after the initial setup wait.
+
+Image preloading is best effort: failed preload links are removed without an
+automatic retry loop. Explicitly revisiting the failed page can retry preloading;
+the SDK's visible image loading remains independent.
+
 #### `disableDeviceCameraTransform`
 
 Disable camera transforms initiated by local device input, such as mouse-wheel and touch gestures,

package/dist/index.d.ts

@@ -143,6 +143,40 @@ interface DisposableStore extends DisposableDisposer {
      */
     size(): number;
 }
+/**
+ * Create a {@link DisposableStore} that manages {@link Disposer}s and {@link IDisposable}s.
+ *
+ * A {@link DisposableStore} is also a {@link Disposer}, which means it can be the `dispose` method of an {@link IDisposable}.
+ *
+ * A {@link DisposableStore} is also an {@link IDisposable}, which means it can be managed by another {@link DisposableStore}.
+ *
+ * @example
+ * ```ts
+ * import { type IDisposable, disposableStore } from "@wopjs/disposable";
+ *
+ * class A implements IDisposable {
+ *   dispose = disposableStore()
+ *   constructor() {
+ *     this.dispose.add(...);
+ *   }
+ * }
+ *
+ * class B implements IDisposable {
+ *   dispose = disposableStore()
+ *   a = this.dispose.add(new A())
+ *   constructor() {
+ *     this.dispose.add(...);
+ *  }
+ * }
+ *
+ * const b = new B();
+ * b.dispose(); // dispose both `b` and `b.a`.
+ * ```
+ *
+ * @param disposables Optional array of {@link DisposableType}s added to the store.
+ * @returns A disposable store.
+ */
+declare function disposableStore(disposables?: DisposableType[]): DisposableStore;
 
 interface ILazyLoadInstance {
   /**
@@ -219,11 +253,13 @@ declare class Preload implements IDisposable {
     touchIndex: number;
     preloadSize: number;
     paused: boolean;
+    private disposed;
     constructor(pages: PresentationPage[]);
     pause(): void;
     resume(index?: number): void;
     touch(index: number, force?: boolean): void;
     private createLink;
+    private removeLink;
     private destroySomeLink;
     private requestAsyncCallBack;
     dispose(): void;
@@ -302,15 +338,27 @@ declare class Presentation implements IDisposable<void> {
     setReadonly(readonly: boolean): void;
     setPageIndex(pageIndex: number): void;
     togglePreview(showPreview?: boolean): void;
+    /** Release preview images while this presentation stays in the runtime cache. */
+    suspendPreviewResources(): void;
     onNewPageIndex(index: number, _origin: "navigation" | "keydown" | "input" | "preview"): void;
     page(): PresentationPage | undefined;
     updateImage(): void;
     /** Returns a modified URL that points to the thumbnail image. */
     thumbnail(src: string): string;
+    private destroyPreviewLazyload;
     private c;
     private isEditable;
 }
 
+type Subscriber<T> = (value: T) => void;
+type Unsubscriber = () => void;
+interface Readable<T> {
+    readonly value: T;
+    subscribe(this: void, run: Subscriber<T>): Unsubscriber;
+    reaction(this: void, run: Subscriber<T>): Unsubscriber;
+    dispose(value?: T): void;
+}
+
 interface ScrollbarOption {
     appId: string;
     readonly?: boolean;
@@ -483,6 +531,30 @@ interface PresentationController {
     /** screenshot the current page */
     screenshotCurrentPageAsync: (context: CanvasRenderingContext2D, width?: number, height?: number) => Promise<void>;
 }
+/**
+ * Blur thumbnail degradation (see lazy-setup design doc §15): when the app
+ * loses focus but stays cached (multi-runtime cache mode), swap the scene
+ * background `<img>` src to the low-res `PptDescription.previewURL`
+ * (`page.thumbnail`) via a pure DOM change and pause full-image preloading;
+ * restore the full image when focus comes back. A page without a real
+ * thumbnail keeps its measurable view container, but its background layer is
+ * hidden and replaced with a static pixel after TeleBox commits the blur.
+ *
+ * While degraded, every load of a background `<img>` is re-degraded
+ * immediately via a capture-phase `load` listener on the document, filtered
+ * to the current view container
+ * (`load` does not bubble but capture works). This covers remote page turns,
+ * SDK React re-renders and the SDK's own background-image onError retries —
+ * any path that (re)renders the full-size image while the app stays blurred.
+ */
+declare const setupBlurThumbnailDegradation: (config: {
+    context: AppContext;
+    view: View;
+    pages: PresentationPage[];
+    pageIndex$: Readable<number>;
+    app: Presentation;
+    dispose: ReturnType<typeof disposableStore>;
+}) => void;
 declare const NetlessAppPresentation: NetlessApp<PresentationAttributes, {}, PresentationAppOptions, PresentationController> & {
     teardown(context: AppContext): void;
 };
@@ -510,5 +582,5 @@ declare const install: (register: RegisterFn, options?: InstallOptions) => Promi
 
 declare const version: string;
 
-export { NetlessAppPresentation, Presentation, Scrollbar, NetlessAppPresentation as default, install, version };
+export { NetlessAppPresentation, Presentation, Scrollbar, NetlessAppPresentation as default, install, setupBlurThumbnailDegradation, version };
 export type { InstallOptions, Logger, PresentationAppOptions, PresentationAttributes, PresentationConfig, PresentationController, PresentationPage, RegisterFn, ScrollbarEventCallback, ScrollbarOption };