@netless/app-presentation

中文

A Netless App that display multiple images as presentation slides.

Install

Usage

import { register } from "@netless/fastboard"
import { install } from "@netless/app-presentation"

install(register, { 
  as: 'DocsViewer',
  appOptions: {
    // Enable scrollbar feature
    useScrollbar: true,
    // Enable clip view feature, only show page content area
    useClipView: true,
    // Scrollbar event callbacks
    scrollbarEventCallback: {
      onScrollCameraUpdated: (appid, originScale, scale) => {
        console.log('Camera scale updated', appid, scale)
      },
      onScrollbarDragEnd: () => {
        console.log('Scrollbar drag ended')
      }
    }
  }
})

Insert This App Into Room

Call fastboard.insertDocs() if you installed this app { as: 'DocsViewer' }.

// Assume you have got the presentation pages as such data structure
const data = [
  // The [preview] field is optional
  { width: 1024, height: 768, url: 'url/to/1.png', preview: 'url/to/1.small.png' },
]

// Now call addApp()
fastboard.manager.addApp({
  kind: 'Presentation',
  options: {
    // folder name to mount whiteboard scenes
    // the same folder name will prevent you from insterting it again
    scenePath: `/presentation/foo`,
    // app window title
    title: 'a.pdf',
    // whiteboard scenes specification
    scenes: data.map((e, i) => ({
      name: String(i + 1),
      ppt: {
        src: e.url,
        width: e.width,
        height: e.height,
        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:

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() function won't work on the Presentation app. This is because that function only 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, without changing the camera bound used by programmatic camera operations:

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.

install(register, {
  as: 'DocsViewer',
  appOptions: {
    useScrollbar: true,
    scrollbarEventCallback: {
      onScrollCameraUpdated: (appid, originScale, scale) => {
        // Triggered when camera scale is updated
      },
      onScrollbarDragEnd: () => {
        // Triggered when scrollbar drag ends
      }
    }
  }
})

useClipView

Enable clip view feature, only show page content area, hide content outside the whiteboard area.

install(register, {
  as: 'DocsViewer',
  appOptions: {
    useClipView: true
  }
})

App Result API

screenshotCurrentPageAsync(context, width?, height?)

Asynchronously screenshot the current page to Canvas context. Supports custom width and height.

const app = fastboard.manager.queryOne(appId)
if (app && app.kind === 'DocsViewer') {
  const controller = app.appResult
  const canvas = document.createElement('canvas')
  const { width, height } = controller.getPageSize()
  canvas.width = width
  canvas.height = height
  const ctx = canvas.getContext('2d')
  if (ctx) {
    await controller.screenshotCurrentPageAsync(ctx, width, height)
    // Use canvas for subsequent operations, such as exporting images
    canvas.toBlob((blob) => {
      const url = URL.createObjectURL(blob)
      const a = document.createElement('a')
      a.href = url
      a.download = 'screenshot.png'
      a.click()
    })
  }
}

getPageSize()

Get the current page size in whiteboard scene coordinates. With originSize, this returns the proportionally normalized size.

const app = fastboard.manager.queryOne(appId)
if (app && app.kind === 'DocsViewer') {
  const controller = app.appResult
  const { width, height } = controller.getPageSize()
  console.log(`Current page size: ${width}x${height}`)
}

Develop

See Write you a Netless App.

To only develop the UI part, run:

$ pnpm build
$ pnpm dev

Then goto http://localhost:5173/ to see the app locally.

To develop it in a real whiteboard room, add a file .env.local containing the room's uuid and token, then goto http://localhost:5173/e2e/.

License

MIT @ netless