Sheets

Read and edit the layout sheets a presentation is assembled on. A sheet is a page in Present mode that saved views and diagrams are placed onto. Accessed via snaptrude.presentation.sheets.

All methods are host API calls that return Promises. Reads never throw for a missing sheet (get returns null, list returns []). Every write (create, place, rename, setSize, delete, reorder, setActive, updatePlacedView) throws when Present mode is not open.

At a glance

Method	What it does	Mutates?
list()	List the layout sheets in the presentation	—
get(sheetId)	Get a single sheet by id	—
create(name?, options?)	Create a new layout sheet (optional paper size/orientation)	✓
place(sheetId, viewId, options?)	Place a saved view onto a sheet as a live linked view shape	✓
rename(sheetId, name)	Set a sheet's display name	✓
setSize(sheetId, size, orientation?)	Set a sheet's paper size / orientation	✓
delete(sheetId)	Delete a sheet and renumber the rest	✓
reorder(sheetId, index)	Move a sheet to a new position in the order	✓
setActive(sheetId)	Select a sheet and navigate the Present canvas to it	✓
updatePlacedView(options?)	Re-render placed views to the current model state	✓

Present mode required

Every method in this namespace needs Present mode (the documentation editor) open. Writes throw "Present mode is not open" when it is closed; reads do not throw — list returns [] and get returns null, so a plugin cannot distinguish "Present mode is closed" from "there are no sheets".

Types

PluginPresentationSheet

A layout sheet in the presentation.

Property	Type	Description
id	string	Unique sheet id
name	string	Display name
size	PluginSheetSize | null	Paper preset (null for a legacy sheet without one)
orientation	"landscape" | "portrait" | null	Orientation (null for a legacy sheet)

PluginSheetSize

The standard paper-size presets — identical to the sheet header's size dropdown in Present mode:

"ANSI_A" | "ANSI_B" | "ANSI_C" | "ANSI_D" | "ANSI_E" | "ARCH_A" | "ARCH_B" | "ARCH_C" | "ARCH_D" | "ARCH_E" | "ARCH_E1" | "ISO_A4" | "ISO_A3" | "ISO_A2" | "ISO_A1" | "ISO_A0"

PluginSheetPosition

A position on a sheet/canvas (sheet coordinates).

Property	Type	Description
x	number	X coordinate
y	number	Y coordinate

Functions

list()

List the layout sheets in the presentation.

• Returns: { sheets: PluginPresentationSheet[] } — empty when Present mode is closed or there are no sheets.

const { sheets } = await snaptrude.presentation.sheets.list();
for (const s of sheets) console.log(s.id, s.name);

---

get(sheetId)

Get a single sheet by id.

• Parameters:
  • sheetId: string — the id of the sheet to read
• Returns: PluginPresentationSheet | null — null if no sheet has that id.

const sheet = await snaptrude.presentation.sheets.get("sheet_1");
if (sheet) console.log(sheet.name);

---

create(name?, options?)

Create a new layout sheet. The new sheet is blank — add content by placing saved views onto it with place, or diagrams via snaptrude.presentation.diagrams.

Pass size when the output format matters

When options.size is omitted, the sheet inherits the editor session's last-used size (initially ANSI B) in landscape — the same behavior as the native "+ sheet" button. Pass size explicitly to control the paper format.

• Parameters:
  • name: string | undefined — display name for the new sheet (optional)
  • options.size: PluginSheetSize | undefined — paper preset for the new sheet
  • options.orientation: "landscape" | "portrait" | undefined — orientation ("landscape" when omitted)
• Returns: PluginPresentationSheet — the newly created sheet (including its size and orientation). When you pass name, it is stored on the sheet and reflected back (and surfaced by list/get); when omitted, the returned name is the sheets-panel label ("New Sheet" by default, or the ordinal "Sheet N" once the sheet has no custom name).
• Throws: If Present mode is not open.

const sheet = await snaptrude.presentation.sheets.create("Cover", {
  size: "ISO_A3",
  orientation: "landscape"
});
console.log(sheet.id, sheet.name, sheet.size); // "…", "Cover", "ISO_A3"

---

place(sheetId, viewId, options?)

Place a saved view onto a sheet. Drops the given view — saved through snaptrude.presentation.views — through the native view drop path: the placed shape is a live linked view shape (the same shape the Present views panel's drag-drop creates), re-rendered from the current model, nested under the sheet frame, and centered on the given position (sheet centre when omitted). Because it is a live view — not a static image — updatePlacedView refreshes it later, and it carries the same Scale dropdown the panel-dropped views show.

2D and site-plan views are placed at an architectural scale: the closest standard scale by default (the native auto-fit), or the explicit options.scale when given. scale must be one of the standard values the placed view's Scale dropdown offers for the project's unit system:

Unit system	Standard scale values
Metric	10, 20, 50, 100, 150, 200, 250, 500, 1000 (e.g. 100 = 1:100)
Imperial	Detail: 12, 16, 24, 32, 48, 64, 96, 128, 192, 384, 768, 1536 (e.g. 48 = 1/4″ = 1′); Site: 120, 240, 360, 480, 600, 1200, 2400, 3600, 4800 (e.g. 120 = 1″ = 10′)

3D views have no architectural scale — passing scale when placing a 3D view throws.

• Parameters:
  • sheetId: string — the sheet to place onto
  • viewId: string — the saved view to place
  • options.position: PluginSheetPosition | undefined — where to place it, in sheet coordinates (sheet centre when omitted)
  • options.scale: number | undefined — a standard scale value for the project's unit system (2D/site-plan views only; auto-fit to the closest standard scale when omitted)
• Returns: { shapeId: string } — id of the created view shape (the same id updatePlacedView reports back).
• Throws: If Present mode is not open, the sheet/view id is invalid, scale is not a standard value for the project's unit system, or scale is passed for a 3D view.

const { sheets } = await snaptrude.presentation.sheets.list();
const { views } = await snaptrude.presentation.views.list();
const { shapeId } = await snaptrude.presentation.sheets.place(sheets[0].id, views[0].id, {
  position: { x: 100, y: 200 },
  scale: 100 // 1:100 (metric project); omit for auto-fit
});

---

rename(sheetId, name)

Set a sheet's display name — the same props.name the sheets panel shows and that list/get read back (create writes the same field). The name is trimmed and must be non-empty.

• Parameters:
  • sheetId: string — the sheet to rename
  • name: string — the new display name (non-empty after trimming)
• Returns: PluginPresentationSheet — the updated sheet ({ id, name }).
• Throws: If Present mode is not open, or the sheet id is invalid.

const sheet = await snaptrude.presentation.sheets.rename("sheet_1", "Cover");
console.log(sheet.name); // "Cover"

---

setSize(sheetId, size, orientation?)

Set a sheet's paper size and/or orientation — exactly what the sheet header's size dropdown and orientation toggle do. Content that no longer fits inside the resized sheet is moved out onto the canvas (matching the native behavior). Undoable. Unlike the header, the API does not navigate the camera, change the selection, or update the user's remembered default size for new sheets.

• Parameters:
  • sheetId: string — the sheet to resize
  • size: PluginSheetSize — the paper preset
  • orientation: "landscape" | "portrait" | undefined — keeps the sheet's current orientation when omitted
• Returns: PluginPresentationSheet — the updated sheet.
• Throws: If Present mode is not open, or the sheet id is invalid.

const sheet = await snaptrude.presentation.sheets.setSize("sheet_1", "ISO_A1", "portrait");
console.log(sheet.size, sheet.orientation); // "ISO_A1", "portrait"

---

delete(sheetId)

Delete a layout sheet and its placed content, then renumber the remaining sheets. This is the same delete the Present canvas runs. Auto-diagram sheets cannot be deleted through the API — those go through a confirmation flow that only the Present UI can drive.

• Parameters:
  • sheetId: string — the sheet to delete
• Returns: { id: string } — the id of the deleted sheet.
• Throws: If Present mode is not open, the sheet id is invalid, or the sheet is an auto-diagram sheet.

const { id } = await snaptrude.presentation.sheets.delete("sheet_2");

---

reorder(sheetId, index)

Move a sheet to a new zero-based position in the sheet order — the same reordering the sheets panel performs when a sheet is dragged. All sheets are renumbered so their order is dense. index is clamped to the valid range (0 … count − 1).

• Parameters:
  • sheetId: string — the sheet to move
  • index: number — zero-based target position (a non-negative integer; clamped to range)
• Returns: { sheets: PluginPresentationSheet[] } — the sheets in their new order.
• Throws: If Present mode is not open, or the sheet id is invalid.

const { sheets } = await snaptrude.presentation.sheets.reorder("sheet_3", 0);
// sheet_3 is now first

---

setActive(sheetId)

Make a sheet the active sheet: select it in the sheets panel and navigate the Present canvas to it (the same as clicking it in the panel).

• Parameters:
  • sheetId: string — the sheet to activate
• Returns: PluginPresentationSheet — the now-active sheet ({ id, name }).
• Throws: If Present mode is not open, or the sheet id is invalid.

await snaptrude.presentation.sheets.setActive("sheet_1");

---

updatePlacedView(options?)

Re-render the presentation's placed views to the current model state — the Present sidebar's "Update views" action. Pass options.sheetId to refresh only the views placed on that sheet, or omit it to refresh every placed view. Views whose source proposal has been removed (and diagram shapes) are skipped by the engine.

All linked view shapes are refreshed — both those dropped from the Present views panel and those placed with place (which creates the same live view shape).

• Parameters:
  • options.sheetId: string | undefined — restrict the refresh to one sheet's placed views (all placed views when omitted)
• Returns: { shapeIds: string[] } — the ids of the placed view shapes submitted for refresh (empty when there are no placed views to refresh).
• Throws: If Present mode is not open, or sheetId is given but is not a sheet.

const { shapeIds } = await snaptrude.presentation.sheets.updatePlacedView();
// or just one sheet:
await snaptrude.presentation.sheets.updatePlacedView({ sheetId: "sheet_1" });

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
PRECONDITION_FAILED	every write	Present mode is not open	—
HANDLE_INVALID	place, rename, delete, reorder, setActive, updatePlacedView	sheetId is unknown or is not a sheet (frame), or (place) viewId does not match a saved view	—
PRECONDITION_FAILED	delete	The sheet is an auto-diagram sheet (delete it from the Present UI)	—
PRECONDITION_FAILED	place	scale was passed for a 3D view (3D views have no architectural scale)	handles — the view id
VALIDATION	place	scale is not one of the standard scale values for the project's unit system	scale, unitSystem, standardScales
OPERATION_FAILED	create	The sheet could not be created	—
OPERATION_FAILED	place	The view could not be re-rendered from the model, so no view shape was created	handles — the view id

list and get never throw — see the warning above for how they behave when Present mode is closed.