@netless/app-presentation 0.1.9 → 0.1.11

package/src/app-presentation.ts

@@ -1,4 +1,4 @@
-import type { AnimationMode, AppContext, AppPayload, NetlessApp, PublicEvent, ReadonlyTeleBox, Room, SceneDefinition, View, WindowManager } from "@netless/window-manager"
+import type { AnimationMode, AppContext, AppPayload, NetlessApp, PublicEvent, ReadonlyTeleBox, Room, SceneDefinition, Size, View, WindowManager } from "@netless/window-manager"
 
 import { disposableStore } from '@wopjs/disposable'
 import { listen } from '@wopjs/dom'
@@ -7,11 +7,31 @@ import styles from './style.scss?inline';
 import { Presentation, type PresentationConfig, type PresentationPage } from "./presentation";
 import { readable, type Readable } from "./store";
 import { Scrollbar, type ScrollbarEventCallback } from "./scrollbar";
-import { debounce } from "lodash";
+import { getCameraScaleRange, shouldDisableDeviceCameraTransform } from "./camera-options";
+import { cameraToSharedViewport, fitPageSizeToOrigin, getCameraReferenceSize, getFitScale, isValidSharedViewport, isValidSize } from "./camera-reference";
+import debounce from "lodash/debounce";
 
 export type Logger = (...data: any[]) => void
 
+interface PresentationDiagnosticLogger {
+  info(event: string, payload?: unknown): void;
+  warn(event: string, payload?: unknown): void;
+  error(event: string, error: unknown, payload?: unknown): void;
+  debouncedInfo(event: string, payload?: unknown): void;
+  flush(): void;
+}
+
+type MoveCameraRequest = { centerX: number, centerY: number, scale: number }
+
 const emptySceneName = '$$empty$$'
+const ORIGIN_SIZE_COORDINATE_VERSION = 2
+
+export 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;
@@ -23,6 +43,8 @@ interface Viewport {
 export 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. */
@@ -42,7 +64,7 @@ export interface PresentationAppOptions {
 
   /** 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;
@@ -63,6 +85,12 @@ export 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, length: number };
 
@@ -73,7 +101,7 @@ export 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, scale: number }) => void;
   /** get the origin scale */
   getOriginScale: () => number;
@@ -85,8 +113,15 @@ export interface PresentationController {
   screenshotCurrentPageAsync: (context: CanvasRenderingContext2D, width?: number, height?: number) => Promise<void>;
 }
 
-const ppt2page = (ppt: SceneDefinition["ppt"], name?: string): PresentationPage | null =>
-  ppt ? { width: ppt.width, height: ppt.height, src: ppt.src, thumbnail: ppt.previewURL, name } : null
+const ppt2page = (
+  ppt: SceneDefinition["ppt"],
+  name?: string,
+  originSize?: Size
+): PresentationPage | null => {
+  if (!ppt) return null
+  const size = fitPageSizeToOrigin(ppt, originSize)
+  return { ...size, src: ppt.src, thumbnail: ppt.previewURL, name }
+}
 
 const createLogger = (room: Room | undefined): Logger => {
   if (room && (room as any).logger) {
@@ -95,6 +130,56 @@ const createLogger = (room: Room | undefined): Logger => {
     return (...args) => console.log(...args)
   }
 }
+
+const createDiagnosticLogger = (context: AppContext): PresentationDiagnosticLogger => {
+  const createAppLogger = (context as any).createLogger
+  if (typeof createAppLogger === 'function') {
+    return createAppLogger.call(context, 'camera', { debounceTime: 300, maxWaitTime: 2000 })
+  }
+
+  // Compatibility fallback for WindowManager versions without AppContext.createLogger().
+  const roomLogger = (context.getRoom() as any)?.logger
+  const prefix = `[Presentation][${context.appId}][camera]`
+  const emit = (level: 'info' | 'warn' | 'error', event: string, ...data: unknown[]) => {
+    try {
+      const printer = roomLogger?.[level]
+      if (typeof printer === 'function') printer.call(roomLogger, `${prefix}[${event}]`, ...data)
+    } catch {
+      // Diagnostics must never change the App API result or replace its original error.
+    }
+  }
+  const debouncedByEvent = new Map<string, ReturnType<typeof debounce>>()
+  const debouncedInfo = (event: string, payload?: unknown) => {
+    let emitDebounced = debouncedByEvent.get(event)
+    if (!emitDebounced) {
+      emitDebounced = debounce(
+        (nextPayload?: unknown) => emit('info', event, nextPayload),
+        300,
+        { maxWait: 2000 }
+      )
+      debouncedByEvent.set(event, emitDebounced)
+    }
+    emitDebounced(payload)
+  }
+  return {
+    info: (event, payload) => emit('info', event, payload),
+    warn: (event, payload) => emit('warn', event, payload),
+    error: (event, error, payload) => emit('error', event, error, payload),
+    debouncedInfo,
+    flush: () => debouncedByEvent.forEach(logger => logger.flush()),
+  }
+}
+
+const safeResourceLocation = (value: string): string => {
+  if (value.startsWith('data:')) return 'data:[omitted]'
+  if (value.startsWith('blob:')) return 'blob:[omitted]'
+  try {
+    const url = new URL(value)
+    return `${url.origin}${url.pathname}`
+  } catch {
+    return value.split('?')[0]
+  }
+}
 const scenesEqual = (scenes1?: SceneDefinition[], scenes2?: SceneDefinition[]): boolean => {
   if (!scenes1 || !scenes2) {return false}
   if (scenes1.length !== scenes2.length) return false;
@@ -107,14 +192,40 @@ const scenesEqual = (scenes1?: SceneDefinition[], scenes2?: SceneDefinition[]):
   });
 };
 
-export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions, PresentationController> = {
+export const NetlessAppPresentation: NetlessApp<PresentationAttributes, {}, PresentationAppOptions, PresentationController> = {
   kind: "Presentation",
   setup(context) {
+    const diagnosticLogger = createDiagnosticLogger(context)
     const view = context.getView()
     if (!view)
       throw new Error("[Presentation]: no whiteboard view, make sure you have added options.scenePath in addApp()")
 
-    const pages = context.getScenes()?.map(({ ppt, name }) => ppt2page(ppt, name)).filter(Boolean) as PresentationPage[]
+    const options = context.getAppOptions() || {}
+    const room = context.getRoom()
+    const log = options.log || createLogger(room)
+    const roomLogger = (room as any)?.logger
+    const warn: Logger = (...data) => roomLogger?.warn ? roomLogger.warn(...data) : log(...data)
+    const configuredOriginSize = context.storage.state.originSize
+    const originSize = isValidSize(configuredOriginSize)
+      ? { width: configuredOriginSize.width, height: configuredOriginSize.height }
+      : undefined
+    if (configuredOriginSize != null && !originSize) {
+      warn(`[Presentation] originSize should contain finite positive width and height, got ${JSON.stringify(configuredOriginSize)}`)
+    }
+    const useOriginSizeCoordinates = Boolean(
+      originSize && (
+        context.isAddApp ||
+        context.storage.state._originSizeCoordinateVersion === ORIGIN_SIZE_COORDINATE_VERSION
+      )
+    )
+    if (originSize && context.isAddApp && context.getIsWritable()) {
+      context.storage.setState({
+        _originSizeCoordinateVersion: ORIGIN_SIZE_COORDINATE_VERSION,
+      })
+    }
+    const pages = context.getScenes()
+      ?.map(({ ppt, name }) => ppt2page(ppt, name, useOriginSizeCoordinates ? originSize : undefined))
+      .filter(Boolean) as PresentationPage[]
     if (!pages || pages.length === 0)
       throw new Error("[Presentation]: empty scenes, make sure you have added options.scenes in addApp()")
     if (pages[0].src.startsWith('ppt'))
@@ -123,19 +234,17 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
     // Now it must have a blank scene points to "{scenePath}/{scenes[0].name}", e.g. "/pdf/123456/1"
     // https://github.com/netless-io/window-manager/blob/c87df17/src/index.ts#L465-L476
     const scenePath = context.getInitScenePath()!
-
-    const options = context.getAppOptions() || {}
     let maxCameraScale = options.maxCameraScale ?? 3
     if (!(Number.isFinite(maxCameraScale) && maxCameraScale! > 0)) {
-      console.warn(`[Presentation] maxCameraScale should be a positive number, got ${options.maxCameraScale}`)
+      warn(`[Presentation] maxCameraScale should be a positive number, got ${options.maxCameraScale}`)
       maxCameraScale = 3
     }
 
-    const log = options.log || createLogger(context.getRoom())
     log(`[Presentation] new ${context.appId}`)
 
     const dispose = disposableStore()
     dispose.add(() => log(`[Presentation] dispose ${context.appId}`))
+    dispose.add(() => diagnosticLogger.flush())
 
     const view$$ = context.createStorage('view', { uid: "", originX: 0, originY: 0, width: 0, height: 0 })
 
@@ -178,63 +287,18 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
       pageIndex$.dispose();
     })
 
-    // Prepare scenes.
-    // Caution: some user may insert a 500-page PDF.
-    if (context.isAddApp) {
-      if (pages.length > 100)
-        console.warn(`[Presentation]: too many pages (${pages.length}), may cause performance issues`)
-
-      let redirectResolve: ((bol:boolean) => void) | undefined = undefined;
-      const room = context.getRoom();
-      if (room && room.isWritable) {
-        const scenes = room.entireScenes()[scenePath];
-        if (pageIndex$.value < 0 || pageIndex$.value >= pages.length) {
-          throw new Error(`[Presentation] Invalid page index: ${pageIndex$.value}, scenes length: ${pages.length}`);
-        }
-        new Promise((resolve) => {
-          const {name, ppt} = scenes[pageIndex$.value];
-          redirectResolve = resolve;
-          const _scenes = pages.map((p, index) => ({
-            name: p.name ?? String(index + 1),
-            ppt: { width: p.width, height: p.height, src: p.src }
-          }))
-          
-          if (!scenesEqual(scenes, _scenes)) {
-            room.removeScenes(scenePath)
-            room.putScenes(scenePath, _scenes)
-          }
-          if(name === _scenes[pageIndex$.value].name && !ppt){
-            context.addPage({ scene: { name: emptySceneName } }).then(() => {
-              log(`[Presentation] setup setScenePath ${scenePath}/${emptySceneName}`);
-              context.setScenePath(`${scenePath}/${emptySceneName}`).then(()=>{
-                redirectResolve && redirectResolve(true);
-              })
-            });
-          } else {
-            redirectResolve && redirectResolve(false)
-          }
-        }).then(async(bol)=>{
-          await syncPage(pageIndex$.value, (room as any).logger);
-          if (bol) {
-            log(`[Presentation] setup removeScenes ${scenePath}/${emptySceneName}`);
-            room.removeScenes(`${scenePath}/${emptySceneName}`);
-          }
-        });
-      }
-    }
-
     // let lastIndex = -1
 
     const me = context.getRoom()?.uid || context.getDisplayer().observerId + ''
 
     let throttleSyncView = 0
 
-    const syncPage = async (index: number, logger?: any) => {
+    const syncPage = async (index: number, logger?: any): Promise<boolean> => {
 
-      if (!context.getIsWritable()) return
+      if (!context.getIsWritable()) return false
 
       const scenes = context.getDisplayer().entireScenes()[scenePath]
-      if (!scenes) return
+      if (!scenes) return false
 
       const p = pages[index];
       const name = p.name ?? String(index + 1);
@@ -251,58 +315,150 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
 
       // Switch to that page.
       await context.setScenePath(`${scenePath}/${name}`)
+      return true
     }
 
-    const jumpPage = (index: number): boolean => {
+    const prepareScenes = async (): Promise<void> => {
+      if (!context.isAddApp) return
+      // Caution: some user may insert a 500-page PDF.
+      if (pages.length > 100)
+        warn(`[Presentation]: too many pages (${pages.length}), may cause performance issues`)
+      if (!room || !room.isWritable) return
+      if (pageIndex$.value < 0 || pageIndex$.value >= pages.length) {
+        throw new Error(`[Presentation] Invalid page index: ${pageIndex$.value}, scenes length: ${pages.length}`)
+      }
+
+      const scenes = room.entireScenes()[scenePath]
+      if (!scenes || !scenes[pageIndex$.value]) {
+        throw new Error(`[Presentation]: no initial scene found at ${scenePath}, page index: ${pageIndex$.value}`)
+      }
+      const { name, ppt } = scenes[pageIndex$.value]
+      const nextScenes = pages.map((page, index) => ({
+        name: page.name ?? String(index + 1),
+        ppt: { width: page.width, height: page.height, src: page.src }
+      }))
+
+      if (!scenesEqual(scenes, nextScenes)) {
+        room.removeScenes(scenePath)
+        room.putScenes(scenePath, nextScenes)
+      }
+
+      const shouldRedirect = name === nextScenes[pageIndex$.value].name && !ppt
+      if (shouldRedirect) {
+        await context.addPage({ scene: { name: emptySceneName } })
+        log(`[Presentation] setup setScenePath ${scenePath}/${emptySceneName}`)
+        await context.setScenePath(`${scenePath}/${emptySceneName}`)
+      }
+
+      await syncPage(pageIndex$.value, (room as any).logger)
+      if (shouldRedirect) {
+        log(`[Presentation] setup removeScenes ${scenePath}/${emptySceneName}`)
+        room.removeScenes(`${scenePath}/${emptySceneName}`)
+      }
+    }
+
+    const prepareScenesPromise = prepareScenes()
+
+    const canJumpPage = (index: number): boolean => {
       if (!context.getIsWritable()) {
-        console.warn('[Presentation]: no permission, make sure you have test room.isWritable')
+        warn('[Presentation]: no permission, make sure you have test room.isWritable')
         return false
       }
 
       if (!(0 <= index && index < pages.length)) {
-        console.warn(`[Presentation]: page ${index + 1} out of bounds [1, ${pages.length}]`)
+        warn(`[Presentation]: page ${index + 1} out of bounds [1, ${pages.length}]`)
         return false
       }
 
       const scenes = context.getDisplayer().entireScenes()[scenePath]
       if (!scenes) {
-        console.warn(`[Presentation]: no scenes found at ${scenePath}, make sure you have added options.scenePath in addApp()`)
+        warn(`[Presentation]: no scenes found at ${scenePath}, make sure you have added options.scenePath in addApp()`)
         return false
       }
 
-      const p = pages[index];
-      const name = p.name ?? String(index + 1);
-
-      if (!scenes.some(scene => scene.name === name)) {
-        context.addPage({ scene: { name, ppt: { width: p.width, height: p.height, src: p.src } } })
-      }
+      return true
+    }
 
-      syncPage(index);
+    const jumpPage = (index: number): boolean => {
+      if (!canJumpPage(index)) return false
+
+      void syncPage(index).catch(error => {
+        warn('[Presentation]: failed to sync page', error)
+        diagnosticLogger.error('jumpPage.failed', error, {
+          index,
+          pageIndex: pageIndex$.value,
+          focusScenePath: view.focusScenePath,
+        })
+      })
       return true
     }
 
     const prevPage = () => jumpPage(pageIndex$.value - 1)
     const nextPage = () => jumpPage(pageIndex$.value + 1)
+    const jumpPageAsync = async (index: number): Promise<boolean> => {
+      if (!canJumpPage(index)) return false
+      try {
+        return await syncPage(index)
+      } catch (error) {
+        diagnosticLogger.error('jumpPageAsync.failed', error, {
+          index,
+          pageIndex: pageIndex$.value,
+          focusScenePath: view.focusScenePath,
+        })
+        throw error
+      }
+    }
+    const prevPageAsync = () => jumpPageAsync(pageIndex$.value - 1)
+    const nextPageAsync = () => jumpPageAsync(pageIndex$.value + 1)
     const pageState = () => ({ index: pageIndex$.value, length: pages.length })
 
     const scaleDocsToFit = () => {
-      const { width, height } = app.page() || {}
-      if (width && height) {
+      const page = app.page()
+      if (page && isValidSize(page)) {
+        const referenceSize = getCameraReferenceSize(originSize, page)
+        if (originSize) {
+          const fitScale = getFitScale(view.size, referenceSize)
+          if (!fitScale) return
+          const { minScale, maxScale } = getCameraScaleRange(
+            fitScale,
+            maxCameraScale,
+            options.disableCameraTransform
+          )
+          view.setCameraBound({
+            damping: 1,
+            maxContentMode: () => maxScale,
+            minContentMode: () => minScale,
+            centerX: 0, centerY: 0, width: page.width, height: page.height
+          })
+          if (isValidSharedViewport(view$$.state)) {
+            syncViewFromRemote(true)
+            return
+          }
+        }
         view.moveCameraToContain({
-          originX: -width / 2, originY: -height / 2, width, height,
+          originX: -referenceSize.width / 2,
+          originY: -referenceSize.height / 2,
+          width: referenceSize.width,
+          height: referenceSize.height,
           animationMode: 'immediately' as AnimationMode.Immediately
         })
-        const maxScale = view.camera.scale * (options.disableCameraTransform ? 1 : maxCameraScale)
-        const minScale = view.camera.scale
-        view.setCameraBound({
-          damping: 1,
-          maxContentMode: () => maxScale,
-          minContentMode: () => minScale,
-          centerX: 0, centerY: 0, width, height
-        })
+        if (!originSize) {
+          const { minScale, maxScale } = getCameraScaleRange(
+            view.camera.scale,
+            maxCameraScale,
+            options.disableCameraTransform
+          )
+          view.setCameraBound({
+            damping: 1,
+            maxContentMode: () => maxScale,
+            minContentMode: () => minScale,
+            centerX: 0, centerY: 0, width: page.width, height: page.height
+          })
+        }
         syncViewFromRemote(true)
       }
     }
+    let pendingMoveCameraRequest: MoveCameraRequest | undefined
     const syncView = () => {
       if (context.getIsWritable()) {
         if (options.debounceSync) {
@@ -310,18 +466,30 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
           throttleSyncView = 0;
         }
         if (throttleSyncView > 0) return
-        const { width, height } = app.page() || {}
-        if(width && height){
+        const page = app.page()
+        if (page && isValidSize(page)) {
           throttleSyncView = setTimeout(() => {
             throttleSyncView = 0
-            const { camera, size } = view;
-            const fixedW = Math.min(size.width, size.height * width / height)
-            const fixedH = Math.min(size.height, size.width * height / width)
-            const w = fixedW / camera.scale
-            const h = fixedH / camera.scale
-            const x = camera.centerX - w / 2
-            const y = camera.centerY - h / 2
-            view$$.setState({ uid: me, originX: x, originY: y, width: w, height: h })
+            try {
+              const { camera, size } = view;
+              const referenceSize = getCameraReferenceSize(originSize, page)
+              const viewport = cameraToSharedViewport(camera, size, referenceSize)
+              if (viewport) view$$.setState({ uid: me, ...viewport })
+              if (pendingMoveCameraRequest) {
+                diagnosticLogger.debouncedInfo(
+                  'moveCamera',
+                  getCameraDiagnosticState('moveCamera', pendingMoveCameraRequest)
+                )
+                pendingMoveCameraRequest = undefined
+              }
+            } catch (error) {
+              diagnosticLogger.error(
+                'syncView.failed',
+                error,
+                getCameraDiagnosticState('moveCamera', pendingMoveCameraRequest)
+              )
+              pendingMoveCameraRequest = undefined
+            }
           }, 50)
         }
       }
@@ -330,6 +498,7 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
     dispose.add(() => {
       clearTimeout(throttleSyncView)
       throttleSyncView = 0
+      pendingMoveCameraRequest = undefined
     })
 
     const syncViewFromRemote = (force = false, animate = false) => {
@@ -354,12 +523,78 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
     app.contentDOM.dataset.appPresentationVersion = __VERSION__
     app.scaleDocsToFit = scaleDocsToFit
     app.log = log
+    app.warn = warn
+
+    const getCameraDiagnosticState = (
+      reason: 'initialize' | 'moveCamera',
+      requestedCamera?: MoveCameraRequest
+    ) => {
+      const page = app.page()
+      const pageSize = page && isValidSize(page)
+        ? { width: page.width, height: page.height }
+        : undefined
+      const referenceSize = pageSize
+        ? getCameraReferenceSize(originSize, pageSize)
+        : undefined
+      const viewSize = { width: view.size.width, height: view.size.height }
+      const viewCamera = {
+        centerX: view.camera.centerX,
+        centerY: view.camera.centerY,
+        scale: view.camera.scale,
+      }
+      const sharedViewport = { ...view$$.state }
+      const originScale = referenceSize ? getFitScale(viewSize, referenceSize) : undefined
+      const normalizedScale = originScale && originScale > 0
+        ? viewCamera.scale / originScale
+        : undefined
+      const sharedScaleX = referenceSize && sharedViewport.width > 0
+        ? referenceSize.width / sharedViewport.width
+        : undefined
+      const sharedScaleY = referenceSize && sharedViewport.height > 0
+        ? referenceSize.height / sharedViewport.height
+        : undefined
+
+      return {
+        reason,
+        requestedCamera,
+        storageOriginSize: context.storage.state.originSize,
+        sharedViewport,
+        pageSize,
+        referenceSize,
+        viewSize,
+        viewCamera,
+        originScale,
+        normalizedScale,
+        sharedScaleX,
+        sharedScaleY,
+        focusScenePath: view.focusScenePath,
+        isWritable: context.getIsWritable(),
+      }
+    }
+
+    let didReportInitializedCamera = false
+    const reportInitializedCamera = (source: 'setup' | 'onSizeUpdated') => {
+      if (didReportInitializedCamera || !isValidSize(view.size) || !isValidSize(app.page())) return
+      didReportInitializedCamera = true
+      diagnosticLogger.info('initialize', {
+        source,
+        ...getCameraDiagnosticState('initialize'),
+      })
+    }
+
+    if (originSize) {
+      let previousPageIndex = pageIndex$.value
+      dispose.add(pageIndex$.subscribe(nextPageIndex => {
+        if (nextPageIndex === previousPageIndex) return
+        previousPageIndex = nextPageIndex
+        scaleDocsToFit()
+      }))
+    }
 
     if (options.justDocsViewReadonly) {
       app.setDocsViewReadonly(true)
     }
 
-    const room = context.getRoom();
     const goToPageByClick = () => {
       const currentApplianceName = context.getRoom()?.state?.memberState?.currentApplianceName ?? '';
       if (!app.readonly && currentApplianceName === 'clicker') {
@@ -375,13 +610,17 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
     }
 
     context.mountView(app.whiteboardDOM)
-    if (options.disableCameraTransform) {
+    if (shouldDisableDeviceCameraTransform(options)) {
       view.disableCameraTransform = true
     }
     scaleDocsToFit()
     dispose.make(() => {
-      view.callbacks.on('onSizeUpdated', scaleDocsToFit)
-      return () => view.callbacks.off('onSizeUpdated', scaleDocsToFit)
+      const onSizeUpdated = () => {
+        scaleDocsToFit()
+        reportInitializedCamera('onSizeUpdated')
+      }
+      view.callbacks.on('onSizeUpdated', onSizeUpdated)
+      return () => view.callbacks.off('onSizeUpdated', onSizeUpdated)
     })
 
     // Init viewport if provided `viewport`.
@@ -404,24 +643,23 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
     })
 
     syncViewFromRemote(true)
+    reportInitializedCamera('setup')
 
     dispose.add(context.emitter.on("writableChange", (isWritable: boolean): void => {
       app.setReadonly(!isWritable)
     }))
 
     const getOriginScale = () => {
-      const { size } = view;
-      const { width, height } = getPageSize();
-      return Math.min(size.height / height, size.width / width);
+      const page = app.page()
+      if (!page || !isValidSize(page)) return 0
+      return getFitScale(view.size, getCameraReferenceSize(originSize, page)) || 0
     }
 
     const getScale =() => {
       return view.camera.scale
     }
 
-    const screenshotCurrentPageAsync = async (_context: CanvasRenderingContext2D, _width?: number, _height?: number) => {
-      const uuid = room?.calibrationTimestamp?.toString() ?? Date.now().toString();
-
+    const screenshotCurrentPage = async (_context: CanvasRenderingContext2D, _width?: number, _height?: number) => {
       const currentPage = pages[pageIndex$.value];
       if (!currentPage) {
         throw new Error('[Presentation]: current page not found')
@@ -432,7 +670,13 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
       img.width = width;
       img.height = height;
       img.crossOrigin = 'Anonymous';
-      await new Promise(resolve => { img.onload = resolve; img.src = src })
+      await new Promise<void>((resolve, reject) => {
+        img.onload = () => resolve()
+        img.onerror = () => reject(new Error(
+          `[Presentation]: failed to load screenshot page image: ${safeResourceLocation(src)}`
+        ))
+        img.src = src
+      })
       _context.drawImage(img, 0, 0, width, height, 0, 0, _width || width, _height || height);
       const currentScenePath = view.focusScenePath;
       if (!currentScenePath) {
@@ -454,6 +698,23 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
       }
     }
 
+    const screenshotCurrentPageAsync = async (
+      _context: CanvasRenderingContext2D,
+      _width?: number,
+      _height?: number
+    ) => {
+      try {
+        await screenshotCurrentPage(_context, _width, _height)
+      } catch (error) {
+        diagnosticLogger.error('screenshotCurrentPage.failed', error, {
+          pageIndex: pageIndex$.value,
+          outputSize: { width: _width, height: _height },
+          camera: getCameraDiagnosticState('initialize'),
+        })
+        throw error
+      }
+    }
+
     let scrollbar:Scrollbar | undefined;
     if (options.useScrollbar) {
       dispose.make(() => {
@@ -470,14 +731,29 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
     }
 
     const moveCamera = (camera: { centerX: number, centerY: number, scale: number }) => {
-      if (context.getIsWritable() && scrollbar) {
-        if (!scrollbar) {
-          throw new Error('[Presentation]: moveCamera must be called when appOptions: useScrollbar is true')
+      try {
+        if (!context.getIsWritable()) {
+          throw new Error('[Presentation]: moveCamera must be called in writable room')
         }
-        scrollbar.moveCamera(camera);
-        return;
+        pendingMoveCameraRequest = { ...camera }
+        if (scrollbar) {
+          scrollbar.moveCamera(camera);
+          return;
+        }
+        view.moveCamera({
+          ...camera,
+          animationMode: 'immediately' as AnimationMode.Immediately
+        })
+        syncView()
+      } catch (error) {
+        pendingMoveCameraRequest = undefined
+        diagnosticLogger.error(
+          'moveCamera.failed',
+          error,
+          getCameraDiagnosticState('moveCamera', camera)
+        )
+        throw error
       }
-      throw new Error('[Presentation]: moveCamera must be called in writable room')
     }
 
     context.emitter.on('destroy', () => dispose())
@@ -495,7 +771,11 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
       } catch {}
 
       const data = await fetch(url)
-      if (!data.ok) throw new Error(`[Presentation]: failed to fetch ${url} - ${await data.text()}`)
+      if (!data.ok) {
+        throw new Error(
+          `[Presentation]: failed to fetch ${safeResourceLocation(url)}, status: ${data.status} ${data.statusText}`
+        )
+      }
 
       const blob = await data.blob()
       const reader = new FileReader()
@@ -506,7 +786,7 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
       })
     }
 
-    const toPdf = async (): Promise<{ pdf: ArrayBuffer, title: string } | null> => {
+    const toPdfInternal = async (): Promise<{ pdf: ArrayBuffer, title: string } | null> => {
       const MAX = 1920
       const firstPage = pages[0]
       const { width, height } = firstPage
@@ -520,6 +800,9 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
         pdfWidth = Math.floor(width * pdfHeight / height)
       }
       const scenes = context.getDisplayer().entireScenes()[scenePath]
+      if (!scenes) {
+        throw new Error(`[Presentation]: no scenes found while exporting PDF: ${scenePath}`)
+      }
 
       const stage_canvas = document.createElement('canvas')
       stage_canvas.width = pdfWidth
@@ -545,8 +828,14 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
 
         const url = await base64url(src)
         const img = document.createElement('img')
-        await new Promise(resolve => { img.onload = resolve; img.src = url })
-        stage.drawImage(img, 0, 0)
+        await new Promise<void>((resolve, reject) => {
+          img.onload = () => resolve()
+          img.onerror = () => reject(new Error(
+            `[Presentation]: failed to load PDF page image, page index: ${index}`
+          ))
+          img.src = url
+        })
+        stage.drawImage(img, 0, 0, width, height)
 
         wb.clearRect(0, 0, pdfWidth, pdfHeight)
         const name = p.name ?? String(index + 1)
@@ -571,7 +860,7 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
             await new Promise(resolve => { wb_img.onload = resolve; wb_img.src = wb_url })
             stage.drawImage(wb_img, 0, 0, pdfWidth, pdfHeight)
           } catch (err) {
-            console.warn(err)
+            warn(err)
           }
         }
 
@@ -589,9 +878,22 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
       return reportProgress(100, { pdf: data, title })
     }
 
+    const toPdf = async (): Promise<{ pdf: ArrayBuffer, title: string } | null> => {
+      try {
+        return await toPdfInternal()
+      } catch (error) {
+        diagnosticLogger.error('toPdf.failed', error, {
+          pageIndex: pageIndex$.value,
+          pageCount: pages.length,
+          focusScenePath: view.focusScenePath,
+        })
+        throw error
+      }
+    }
+
     dispose.add(listen(window, 'message', (ev: MessageEvent<{ appId: string, type: "@netless/_request_save_pdf_" }>) => {
       if (ev.data && ev.data.type == '@netless/_request_save_pdf_' && ev.data.appId == context.appId) {
-        toPdf().catch(err => { console.warn(err); reportProgress(100, null) })
+        toPdf().catch(err => { warn(err); reportProgress(100, null) })
       }
     }))
 
@@ -609,7 +911,7 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
       }
     }
 
-    const controller: PresentationController = { app, view, context, jumpPage, prevPage, nextPage, pageState, toPdf, log, setDocsViewReadonly, setReadonly, moveCamera, getOriginScale, getScale, getPageSize, screenshotCurrentPageAsync }
+    const controller: PresentationController = { app, view, context, jumpPage, prevPage, nextPage, jumpPageAsync, prevPageAsync, nextPageAsync, pageState, toPdf, log, setDocsViewReadonly, setReadonly, moveCamera, getOriginScale, getScale, getPageSize, screenshotCurrentPageAsync }
 
     dispose.add(listen(window, 'message', (ev: MessageEvent<"@netless/_presentation_">) => {
       if (ev.data === "@netless/_presentation_") {
@@ -622,7 +924,10 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
       }
     }))
 
-    return controller
+    // Older WindowManager declarations model setup as synchronous even though
+    // AppProxy awaits its result. Keep that source compatibility until the new
+    // `SetupResult | Promise<SetupResult>` declaration is the minimum version.
+    return prepareScenesPromise.then(() => controller) as unknown as PresentationController
   }
 }
 
@@ -631,6 +936,7 @@ export const NetlessAppPresentation: NetlessApp<{}, {}, PresentationAppOptions,
  */
 class AppPresentation extends Presentation {
   log?: Logger;
+  warn?: Logger;
   box?: ReadonlyTeleBox;
   scaleDocsToFit?: () => void;
   readonly jumpPage: (index: number) => void
@@ -656,7 +962,7 @@ class AppPresentation extends Presentation {
     if (0 <= index && index < this.pages.length) {
       this.jumpPage(index)
     } else {
-      console.warn(`[Presentation]: page index ${index} out of bounds [0, ${this.pages.length - 1}]`)
+      this.warn?.(`[Presentation]: page index ${index} out of bounds [0, ${this.pages.length - 1}]`)
     }
   }
 }