Sketchpad Document Boundary

SketchAPI exposes instance-scoped document handles for runtime work and open/save namespaces for portable files. A hosted SketchDocumentHandle is a data reference deliberately narrower than the private renderer document.

Table of Contents

• Document Handles
• Structural Layers
• Viewport
• History Transactions
• Clipboard
• Open
• Save
• Saved Data
• Service Data

Document Handles

const documentHandle = await api.document.create({
	height: 768,
	width: 1024
})

const current = await api.document.current()
const openDocuments = await api.document.list()
await api.document.close(documentHandle)

Handles expose stable identity and dimensions. Document lookup accepts a handle, id, or open-document index. Internal renderer objects and caches never cross the hosted boundary.

Document-aware operations target the active document by default. Pass { doc: documentHandle } when one integration has multiple open documents and an operation must not change the active default.

Structural Layers

Layer methods accept either an instance handle or its stable id. Read with list, get, or snapshot; make structural changes through the API so selection, rendering, and history stay coordinated:

const card = await api.layer.create({
	fill: '#2f6fed',
	height: 240,
	type: 'rectangle',
	width: 320,
	x: 512,
	y: 384
})

await api.layer.update(card, { name: 'Feature card', opacity: 0.9 })
await api.layer.move(card, { index: 0 })

const savedState = await api.layer.snapshot(card)

The same namespace groups, ungroups, removes, and reparents layers. Snapshots are detached serializable state; handles remain instance-owned.

Viewport

Viewport state belongs to its document rather than the host application:

const viewport = await api.document.getViewport()

await api.document.setViewport({
	scroll: { x: viewport.scroll.x + 40, y: viewport.scroll.y },
	zoom: 1.25
})

await api.document.fit({ margin: 24 })

Use resize for document dimensions and resizeViewport when the embedding element changes size. getViewport returns immutable camera and document-size state.

History Transactions

Undo and redo are scoped to a document. A transaction combines related history-recording mutations into one entry and rolls back recorded changes if the action fails:

await api.history.transaction(
	async () => {
		await api.layer.update(card, { opacity: 0.75 })
		await api.layer.move(card, { index: 1 })
	},
	{ name: 'Arrange feature card' }
)

if (await api.history.canUndo()) await api.history.undo()
if (await api.history.canRedo()) await api.history.redo()

Clipboard

The instance clipboard copies selected layers by default or explicit layer references when supplied. Paste returns new instance handles:

await api.clipboard.copy(card)

const [copy] = await api.clipboard.paste({
	offsetBy: { x: 24, y: 24 }
})

Use cut for a history-aware move through the clipboard and clear to release copied content and retained assets. Clipboard ownership stays with the mounted Sketchpad instance; browser copy/paste events and native-format export remain separate host-integrated behavior.

Open

api.open exposes explicit import methods for browser-provided data. The hosted client accepts structured data, Blob, File, ArrayBuffer, and typed array values through the matching format method.

Use a normal browser file input and pass the selected File or Blob to the matching open method. Native file-picker policy stays with the embedding app.

Open operations coordinate parsing, migrations, diagnostics, resources, and the active runtime. Avoid bypassing them with private document constructors.

Save

api.save owns portable export. Result shape depends on the method and its as option:

const image = await api.save.png() // Blob
const documentData = await api.save.json({ as: 'object' }) // SketchJsonDocument

Your application decides whether to download, upload, or otherwise persist the result.

When the connected product offers it, sketchpad.files exposes native save, open, list, rename, duplicate, delete, and flush operations backed by the hosted frame’s browser storage. It does not turn portable document data into account, cloud, sharing, or synchronization state.

Exact format support depends on the mounted hosted product. Query the API rather than copying a format list into application code or documentation.

Saved Data

Maintained Sketchpad codecs serialize a versioned envelope containing document configuration, layers, resources, and optional history or asset payloads. The exact layer and resource contracts remain owned by their document, layer, and IO packages; this guide does not maintain a second schema table.

Saved document data must not contain renderer backend ids, GPU resources, caches, live DOM objects, credentials, or host service implementations.

Service Data

Sharing policy, permissions, workspace membership, remote sync state, search indexes, billing, and service timestamps belong to a server-side record that wraps or references portable document data. None of those fields is required to create, open, or save a document through the hosted API.

See the API Reference for current document, layer, history, clipboard, open, and save signatures.