@netless/app-presentation 0.1.10 → 0.1.11

package/README-zh.md

@@ -64,10 +64,27 @@ fastboard.manager.addApp({
         previewURL: e.preview
       }
     }))
+  },
+  attributes: {
+    originSize: { width: 1280, height: 720 }
   }
 })
 ```
 
+配置 `originSize` 后，它表示 `scale = 1` 时的共享白板原始尺寸。Presentation 在写入白板
+scene 前，将每页 `ppt.width/ppt.height` 按原始宽高比等比 contain 到 `originSize`：
+
+```text
+ratio = min(originSize.width / ppt.width, originSize.height / ppt.height)
+scenePpt.width  = ppt.width * ratio
+scenePpt.height = ppt.height * ratio
+```
+
+图片 URL 不变。归一化后的尺寸同时用于 scene、CameraBound、滚动条和裁剪范围，因此相对倍率为
+`1` 时页面以最大等比例完整显示，不出现滚动条。切页时如果 shared viewport 已建立，会直接恢复
+该 viewport 并保持当前相对 scale，不会先应用一次中间 fit camera。未配置 `originSize` 时继续
+直接使用输入的 `ppt.width/ppt.height`。
+
 请注意，如果你没有使用 `{ as: 'DocsViewer' }` 替换 DocsViewer 应用，
 [`dispatchDocsEvent()`](https://github.com/netless-io/fastboard#control-the-pdfpptx-apps)
 函数将无法在 Presentation 应用上工作。这是因为该函数只处理类型为 `DocsViewer` 或 `Slide` 的应用。
@@ -76,6 +93,30 @@ fastboard.manager.addApp({
 
 ### 应用选项
 
+#### `disableDeviceCameraTransform`
+
+禁止鼠标滚轮、触摸手势等本地设备输入改变相机，但不改变程序化相机操作使用的
+CameraBound：
+
+```js
+const manager = await WindowManager.mount({
+  room,
+  container,
+  builtinAppOptions: {
+    Presentation: {
+      disableDeviceCameraTransform: true,
+    },
+  },
+})
+```
+
+该配置仅在本地客户端生效，不会同步给其他客户端。不要同时启用旧的
+`disableCameraTransform`，因为旧配置会按原有语义将 CameraBound 锁定到页面适配缩放。
+
+`useScrollbar` 和 `maxCameraScale` 是相互独立的配置。Presentation Controller 的程序化
+`moveCamera` 要求启用 `useScrollbar`；`maxCameraScale` 只控制程序化缩放上限，默认值为
+`3`，只有业务需要调用 `scalePage({ scale: 4 })` 时才需要设为 `4`。
+
 #### `useScrollbar`
 启用滚动条功能，提供水平和垂直滚动条用于导航和查看演示文稿。
 
@@ -141,7 +182,7 @@ if (app && app.kind === 'DocsViewer') {
 ```
 
 #### `getPageSize()`
-获取当前页面的尺寸（宽度和高度）。
+获取当前页面在白板 scene 中的尺寸（宽度和高度）。配置 `originSize` 时返回等比归一化后的尺寸。
 
 ```js
 const app = fastboard.manager.queryOne(appId)

package/README.md

@@ -67,10 +67,29 @@ fastboard.manager.addApp({
         previewURL: e.preview
       }
     }))
+  },
+  attributes: {
+    originSize: { width: 1280, height: 720 }
   }
 })
 ```
 
+When `originSize` is configured, it is the shared whiteboard reference size for `scale = 1`.
+Before writing each page into the whiteboard scene, Presentation contains its
+`ppt.width/ppt.height` proportionally within `originSize`:
+
+```text
+ratio = min(originSize.width / ppt.width, originSize.height / ppt.height)
+scenePpt.width  = ppt.width * ratio
+scenePpt.height = ppt.height * ratio
+```
+
+The image URL is unchanged. The normalized size is used consistently by the scene, CameraBound,
+scrollbars, and clipping, so relative scale `1` shows the largest complete page without scrollbars.
+When switching pages, an established shared viewport is restored directly so the current relative
+scale is preserved without first applying an intermediate fit camera.
+Without `originSize`, the input `ppt.width/ppt.height` remains unchanged.
+
 Note that if you do not replace the DocsViewer app with `{ as: 'DocsViewer' }`,
 the [`dispatchDocsEvent()`](https://github.com/netless-io/fastboard#control-the-pdfpptx-apps)
 function won't work on the Presentation app. This is because that function only
@@ -80,6 +99,32 @@ handles app whose kind is `DocsViewer` or `Slide`.
 
 ### App Options
 
+#### `disableDeviceCameraTransform`
+
+Disable camera transforms initiated by local device input, such as mouse-wheel and touch gestures,
+without changing the camera bound used by programmatic camera operations:
+
+```js
+const manager = await WindowManager.mount({
+  room,
+  container,
+  builtinAppOptions: {
+    Presentation: {
+      disableDeviceCameraTransform: true,
+    },
+  },
+})
+```
+
+This option is local and is not synchronized to other clients. Do not enable the legacy
+`disableCameraTransform` option at the same time because it intentionally locks the camera bound
+to the fitted page scale.
+
+`useScrollbar` and `maxCameraScale` are independent options. `useScrollbar` is required by the
+Presentation controller's programmatic `moveCamera` operation. `maxCameraScale` only controls its
+upper scaling bound and defaults to `3`; set it to `4` only when the application needs
+`scalePage({ scale: 4 })`.
+
 #### `useScrollbar`
 Enable scrollbar feature, providing horizontal and vertical scrollbars for navigation and viewing presentations.
 
@@ -141,7 +186,8 @@ if (app && app.kind === 'DocsViewer') {
 ```
 
 #### `getPageSize()`
-Get the size (width and height) of the current page.
+Get the current page size in whiteboard scene coordinates. With `originSize`, this returns the
+proportionally normalized size.
 
 ```js
 const app = fastboard.manager.queryOne(appId)

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { View, NetlessApp, AppContext, WindowManager } from '@netless/window-manager';
+import { View, NetlessApp, Size, AppContext, WindowManager } from '@netless/window-manager';
 
 /**
  * A combination of {@link Disposer} and {@link IDisposable}.
@@ -378,6 +378,13 @@ declare class Scrollbar {
 }
 
 type Logger = (...data: any[]) => void;
+declare const ORIGIN_SIZE_COORDINATE_VERSION = 2;
+interface PresentationAttributes {
+    /** Shared logical camera reference size. New pages are proportionally contained within it. */
+    originSize?: Size | null;
+    /** Internal marker for scenes whose ppt size has been normalized to originSize. */
+    _originSizeCoordinateVersion?: typeof ORIGIN_SIZE_COORDINATE_VERSION;
+}
 interface Viewport {
     readonly x: number;
     readonly y: number;
@@ -387,6 +394,8 @@ interface Viewport {
 interface PresentationAppOptions {
     /** Disables user move / scale the image and whiteboard. */
     disableCameraTransform?: boolean;
+    /** Disables camera transforms from local device input without restricting programmatic scaling. */
+    disableDeviceCameraTransform?: boolean;
     /** Max scale = `maxCameraScale` * default scale. Not working when `disableCameraTransform` is true. Default: 3 */
     maxCameraScale?: number;
     /** Custom logger. Default: a logger that reports to the whiteboard server. */
@@ -405,7 +414,7 @@ interface PresentationAppOptions {
     viewport?: Viewport | ((page: PresentationPage) => Viewport);
     /** justDocsViewReadonly is used to set the presentation readonly, it will be used in the presentation, and the presentation will be readonly when the app is initialized */
     justDocsViewReadonly?: true;
-    /** useScrollbar is used to set the presentation use scrollbar, it will be used in the presentation, and the presentation will be use scrollbar when the app is initialized */
+    /** Shows draggable scrollbars. This does not affect PresentationController.moveCamera(). */
     useScrollbar?: boolean;
     /** debounceSync is used to set the presentation debounce sync, it will be used in the presentation, and the presentation will be debounce sync when the app is initialized */
     debounceSync?: boolean;
@@ -425,6 +434,12 @@ interface PresentationController {
     prevPage(): boolean;
     /** Returns false if failed to jump */
     nextPage(): boolean;
+    /** Resolves after the whiteboard View has accepted the target scene path. */
+    jumpPageAsync(index: number): Promise<boolean>;
+    /** Resolves after the whiteboard View has accepted the previous scene path. */
+    prevPageAsync(): Promise<boolean>;
+    /** Resolves after the whiteboard View has accepted the next scene path. */
+    nextPageAsync(): Promise<boolean>;
     /** `index` ranges from 0 to `length - 1` */
     pageState(): {
         index: number;
@@ -439,7 +454,7 @@ interface PresentationController {
     setDocsViewReadonly: (bol: boolean) => void;
     /** set the presentation readonly */
     setReadonly: (bol: boolean) => void;
-    /** move the camera */
+    /** Moves the camera through the API, regardless of whether scrollbars are shown. */
     moveCamera: (camera: {
         centerX: number;
         centerY: number;
@@ -457,7 +472,7 @@ interface PresentationController {
     /** screenshot the current page */
     screenshotCurrentPageAsync: (context: CanvasRenderingContext2D, width?: number, height?: number) => Promise<void>;
 }
-declare const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions, PresentationController>;
+declare const NetlessAppPresentation: NetlessApp<PresentationAttributes, {}, PresentationAppOptions, PresentationController>;
 type RegisterFn = typeof WindowManager["register"];
 interface InstallOptions {
     /**
@@ -483,4 +498,4 @@ declare const install: (register: RegisterFn, options?: InstallOptions) => Promi
 declare const version: string;
 
 export { NetlessAppPresentation, Presentation, Scrollbar, NetlessAppPresentation as default, install, version };
-export type { InstallOptions, Logger, PresentationAppOptions, PresentationConfig, PresentationController, PresentationPage, RegisterFn, ScrollbarEventCallback, ScrollbarOption };
+export type { InstallOptions, Logger, PresentationAppOptions, PresentationAttributes, PresentationConfig, PresentationController, PresentationPage, RegisterFn, ScrollbarEventCallback, ScrollbarOption };