Camera

The Present-mode canvas camera — the Present twin of core.camera. Present mode lays sheets out on an infinite 2D canvas; its camera is a pan (x, y) and a zoom. Screenshot what that canvas currently shows, read the camera, pan/zoom it, or frame all sheets or one shape. Accessed via snaptrude.presentation.camera.

All methods are host API calls that return Promises. They are transient view-state changes — not model edits — so they are not write-gated and not undoable.

Present mode required

Every method needs Present mode (the documentation editor) open — it throws PRECONDITION_FAILED ("Present mode is not open") when it is closed.

Which screenshot?

presentation.camera.capture shoots the Present canvas as it is on screen. For the Design (3D) canvas use presentation.views.capture; for whole sheets at their own size use presentation.export.

At a glance

Method	What it does	Mutates?
capture(options?)	Screenshot the visible Present canvas as a base64 image	—
get()	Read pan, zoom, the visible page rectangle and the sheet on screen	—
set(camera)	Pan and/or zoom (omitted fields keep their value)	view
zoomToFit()	Frame everything on the canvas	view
zoomTo(shapeId)	Frame one sheet, placed view, table, annotation or keyed shape	view

Coordinates

Present canvas page units — pixels at 100% zoom, the same space sheets, placedViews and shapes report positions in. zoom is a factor: 1 = 100%, 0.5 = zoomed out to half size. x/y are the camera offset: the page point that lands at the tldraw viewport's top-left corner (under the sidebar) is (-x, -y); viewport is the visible part of it. Read a state with get() and pass it back to set() to reproduce a framing exactly.

"Visible" means what the user actually sees: the canvas as clipped by the window, minus the strip under the floating left sidebar. Floating right-hand panels (view settings, AI presets) are not subtracted.

Types

PluginPresentationCameraState

Returned by every method.

Property	Type	Description
x	number	Camera pan offset (page units): the page point at the tldraw viewport's top-left is (-x, -y)
y	number	Camera pan offset (page units)
zoom	number	Zoom factor, 1 = 100%
viewport	PluginPresentationCameraViewport	The visible page-space rectangle
sheetId	string | null	The sheet under the centre of the view, or null when none

PluginPresentationCameraViewport

Property	Type	Description
x	number	Left edge (page units)
y	number	Top edge (page units)
width	number	Width (page units)
height	number	Height (page units)

PluginPresentationCameraCaptureResult

Property	Type	Description
image	string	The screenshot as a base64 data URL (data:image/png;base64,…)
width	number	Image width in pixels
height	number	Image height in pixels

Functions

capture(options?)

Screenshot what the Present canvas currently shows: exactly the visible area (the canvas as clipped by the window, minus the strip under the floating left sidebar) at the current pan and zoom, rendered through the same pipeline as the Present-mode Export dialog, so sheet content, placed views, text, annotations and imported images look as they do on screen. Selection handles, cursors and the UI itself are not in the image. An empty view still yields an image (the export backdrop).

Export-pipeline details to expect, exactly as in the Export dialog: sheet frames themselves are not drawn (no paper, dashed margin guides or name label, which are editor chrome), the backdrop is tldraw's near-white export backdrop (#f9fafb) rather than the on-screen canvas grey (#f0f0f0), and when exactly one sheet is in view the backdrop is white (tldraw treats a lone sheet as a page). The image is the encoded bitmap's real size; very large pixelRatio captures are clamped by the browser's maximum canvas size.

• Parameters (all optional):
  • options.format: "png" | "jpeg" — output format (default "png")
  • options.pixelRatio: number — output pixels per screen pixel, 1–4 (default 1; 2 for a retina-sharp image)
• Returns: { image, width, height } — the base64 data URL and its pixel size.
• Throws: If Present mode is not open.

const { image, width, height } = await snaptrude.presentation.camera.capture({
  format: "png",
  pixelRatio: 2
});

get()

Read the Present camera.

• Returns: PluginPresentationCameraState — pan, zoom, the visible rectangle and the sheet under the centre of the view.
• Throws: If Present mode is not open.

const { zoom, sheetId } = await snaptrude.presentation.camera.get();

set(camera)

Pan and/or zoom the Present canvas. Fields left out keep their current value, so { zoom: 2 } changes only the zoom (the page point at the viewport's top-left corner stays put) and { x, y } pans at the current zoom. Immediate (no animation). zoom is clamped to the editor's range (0.01 to 10, 1% to 1000%); the requested x/y are always honoured.

• Parameters:
  • camera.x: number | undefined — camera pan offset (page units)
  • camera.y: number | undefined — camera pan offset (page units)
  • camera.zoom: number | undefined — zoom factor, > 0, clamped to 0.01–10
  • At least one field is required.
• Returns: The resulting PluginPresentationCameraState.
• Throws: If Present mode is not open, or another Present-mode control has locked the camera (an open style dropdown, AI Inspiration's layout mode).

const saved = await snaptrude.presentation.camera.get();
await snaptrude.presentation.camera.set({ zoom: 0.5 });
// …later, restore the exact framing
await snaptrude.presentation.camera.set({ x: saved.x, y: saved.y, zoom: saved.zoom });

zoomToFit()

Frame everything on the Present canvas — every sheet and loose shape — the Present-mode "zoom to fit". A no-op on an empty canvas.

• Returns: The resulting PluginPresentationCameraState.
• Throws: If Present mode is not open, or the camera is locked.

await snaptrude.presentation.camera.zoomToFit();

zoomTo(shapeId)

Frame one shape: a sheet, a placed view, a table, an annotation or a keyed shape — any id the other presentation namespaces hand out. Pair with capture to screenshot a single sheet or placed view as it appears on screen. Immediate, unlike sheets.setActive, which animates its move over half a second.

• Parameters:
  • shapeId: string — the sheet or shape to frame
• Returns: The resulting PluginPresentationCameraState.
• Throws: If Present mode is not open, the id is unknown (HANDLE_INVALID), or the camera is locked.

const { sheets } = await snaptrude.presentation.sheets.list();
await snaptrude.presentation.camera.zoomTo(sheets[1].id);
const { image } = await snaptrude.presentation.camera.capture();

Errors

Code	When
VALIDATION	Bad options — unknown format, pixelRatio outside 1–4, an empty set({}), a non-positive zoom, an empty shapeId
PRECONDITION_FAILED	Present mode is not open; (set/zoomToFit/zoomTo) the camera is locked by another Present-mode control; (capture) no canvas is visible at all
HANDLE_INVALID	zoomTo with an id that is not a shape on the Present canvas