Skip to main content

Engine

The <UpmadeEngine> is the low-level headless canvas primitive. It handles rendering, viewport management, pointer events, undo/redo, and workspace management with no built-in controls.

Object​

Props​

PropertyTypeDescription
objectConfigUpmadeObjectConfigConfigures how objects behave, in one place for all objects: which objects get a titlebar, and which can be rotated or resized. Each option is a boolean or a function of the object. See Configuring Objects.

Events​

EventPayload TypeDescription
objectsAddedObjectsAddedEventEmitted when one or more objects are added to the canvas. source is set when an agent made the change.
objectsChangeUpmadeBaseObject[]Emitted when objects on the canvas are added, removed, or modified.
objectsRemovedObjectsRemovedEventEmitted when one or more objects are removed from the canvas. source is set when an agent made the change.
objectsUpdatedObjectsUpdatedEventEmitted when one or more objects are updated on the canvas. source is set when an agent made the change.

Methods​

addObject​

Adds a new object to the canvas. The object is automatically assigned an ID, core reference, and z-index.

addObject<T extends UpmadeBaseObject>(object: T): Promise<T | null>

addObjects​

Adds multiple objects to the canvas in a single batch operation within one undo step and render cycle.

addObjects<T extends UpmadeBaseObject>(objects: T[]): Promise<T[]>

removeObject​

Removes an object from the canvas.

removeObject<T extends UpmadeBaseObject>(object: T): Promise<T | null>

removeObjects​

Removes multiple objects from the canvas in a single batch operation.

removeObjects<T extends UpmadeBaseObject>(objects: T[]): Promise<T[]>

updateObject​

Updates properties of an existing canvas object.

updateObject<T extends UpmadeBaseObject>(object: T, updatedProperties: Partial<T>): Promise<T | null>

getObjectById​

Retrieves a canvas object by its unique ID.

getObjectById<T extends UpmadeBaseObject>(id: string): Promise<T | null>

getAllObjects​

Returns all objects on the canvas across all layers.

getAllObjects<T extends UpmadeBaseObject>(): Promise<T[]>

findObjects​

Returns all objects matching the given predicate. Excludes internal selection-related objects.

findObjects<T extends UpmadeBaseObject>(predicate: (obj: UpmadeBaseObject) => boolean): Promise<T[]>

getObjectsTotalCount​

Returns the total number of objects on the canvas.

getObjectsTotalCount(): Promise<number>

getObjectsInViewport​

Returns all objects currently visible within the viewport bounds.

getObjectsInViewport(): Promise<UpmadeBaseObject[]>

Selection​

Props​

No selection-specific props.

Events​

EventPayload TypeDescription
objectsSelectionChangevoidEmitted when the set of selected objects changes.

Methods​

getSelectedObjects​

Returns the currently selected objects. Returns an empty array if nothing is selected.

getSelectedObjects(): Promise<UpmadeBaseObject[]>

selectObjects​

Programmatically selects the given objects. Switches to the selection tool automatically.

selectObjects(objects: UpmadeBaseObject[]): Promise<void>

selectAllObjectsInViewport​

Selects all objects currently visible in the viewport. Switches to the selection tool automatically.

selectAllObjectsInViewport(): Promise<void>

clearSelection​

Deselects all currently selected objects.

clearSelection(): Promise<void>

triggerSelectionChange​

Manually triggers the objectsSelectionChange event.

triggerSelectionChange(): Promise<void>

Viewport & Navigation​

Props​

PropertyTypeDescription
isPanningEnabledbooleanEnable or disable viewport panning via regular wheel input.
isZoomingEnabledbooleanEnable or disable viewport zooming via Ctrl+wheel.
scaleMaxnumberMaximum zoom scale allowed.
scaleMinnumberMinimum zoom scale allowed.
viewportBoundaryBottomnumberBottom pan boundary in world coordinates.
viewportBoundaryLeftnumberLeft pan boundary in world coordinates.
viewportBoundaryRightnumberRight pan boundary in world coordinates.
viewportBoundaryTopnumberTop pan boundary in world coordinates.

Events​

EventPayload TypeDescription
viewportChangeUpmadeViewportStateEmitted on viewport pan, zoom, or resize.
objectsInViewportChangeUpmadeBaseObject[]Emitted when the set of objects visible in the current viewport changes.

Methods​

getViewport​

Returns the current viewport state including position, scale, and dimensions.

getViewport(): Promise<UpmadeViewportState>

setViewport​

Sets the viewport to center on the given world coordinates at the specified scale.

setViewport(x: number, y: number, scale: number): Promise<void>

panTo​

Pans the viewport to center on the given world coordinates without changing the scale.

panTo(x: number, y: number): Promise<void>

panToObject​

Pans the viewport to center on the specified object without changing the scale.

panToObject(object: UpmadeBaseObject): Promise<void>

zoomTo​

Zooms the viewport to the given scale. Optionally centers on a world point; if omitted, zooms around the viewport center.

zoomTo(scale: number, worldX?: number, worldY?: number): Promise<void>

zoomIn​

Zooms into the viewport by a specified factor over an optional duration.

zoomIn(factor?: number, duration?: number): Promise<void>

zoomOut​

Zooms out of the viewport by a specified factor over an optional duration.

zoomOut(factor?: number, duration?: number): Promise<void>

centerObjectInViewport​

Moves the given object to the center of the current viewport and returns the updated object. Use panToObject or centerObjects when you want to move the camera instead.

centerObjectInViewport(object: UpmadeBaseObject): Promise<UpmadeBaseObject>

centerObjects​

Pans and zooms the viewport to fit the provided objects.

centerObjects(objects: UpmadeBaseObject[], animate?: boolean): Promise<boolean>

centerAllObjects​

Pans and zooms the viewport to fit all objects on the canvas, including those not currently rendered.

centerAllObjects(animate?: boolean): Promise<boolean>

backToContent​

Pans and zooms the viewport to fit the nearest content, with padding. Useful when the user has panned away from all objects.

backToContent(): Promise<boolean>

screenToWorld​

Converts screen-relative pixel coordinates to world coordinates.

screenToWorld(x: number, y: number): Promise<{ x: number; y: number }>

worldToScreen​

Converts world coordinates to screen-relative pixel coordinates.

worldToScreen(x: number, y: number): Promise<{ x: number; y: number }>

Workspace​

Props​

PropertyTypeDescription
activeWorkspaceIdstringOptional workspace ID to load.
workspacesUpmadeWorkspace[]Optional authoritative workspace catalog for this engine instance.
syncConfigUpmadeSyncConfigConfiguration for synchronization providers.
userIUpmadeUserCurrent user for awareness broadcasting.
isLoadingbooleanExternal loading state merged with internal workspace loading state.

Events​

EventPayload TypeDescription
activeWorkspaceChangeUpmadeWorkspaceEmitted when the active workspace changes.
workspacesChangeUpmadeWorkspace[]Emitted when workspaces are created, updated, or deleted.
awarenessChangeAwarenessStateMapEmitted when awareness state changes.
syncingChangebooleanEmitted when remote workspace synchronization status changes.
loadingChangebooleanEmitted when the combined loading state changes.

Methods​

setActiveWorkspace​

Switches the active workspace shown in the engine by ID.

setActiveWorkspace(id: string): Promise<void>

createWorkspace​

Creates a new workspace and emits a workspacesChange event. Accepts an UpmadeWorkspace instance.

createWorkspace(workspace: UpmadeWorkspace): Promise<UpmadeWorkspace | null>

updateWorkspace​

Applies a workspace as declared and emits a workspacesChange event. Metadata and viewport are always applied. When workspace.objects is set it is treated as the complete desired object set: objects are matched by ID, unknown IDs are added, known IDs are updated, and objects missing from the list are removed. Leave objects undefined to keep the current objects, or pass [] to remove them all. Updating the objects of a workspace that is not currently active requires a configured sync provider.

updateWorkspace(workspace: UpmadeWorkspace): Promise<void>

deleteWorkspace​

Deletes a workspace and emits a workspacesChange event.

deleteWorkspace(workspace: UpmadeWorkspace): Promise<void>

getWorkspaces​

Returns all available workspaces.

getWorkspaces(): Promise<UpmadeWorkspace[]>

getActiveWorkspace​

Returns the currently active workspace.

getActiveWorkspace(): Promise<UpmadeWorkspace>

getIsPublic​

Gets whether the active workspace is publicly accessible.

getIsPublic(): Promise<boolean>

loadSharedWorkspace​

Loads a workspace shared externally using a secure access token.

loadSharedWorkspace(token: string): Promise<void>

reinitSync​

Reinitializes the active synchronization provider connection.

reinitSync(): Promise<void>

Tool Management​

Props​

No tool-specific props.

Events​

EventPayload TypeDescription
activeToolChangeUpmadeBaseToolEmitted when the active drawing tool changes.

Methods​

registerTool​

Registers a new drawing tool with the engine.

registerTool(
toolName: string,
toolClass: any,
toolConfig?: UpmadeBrushToolConfig | UpmadeLineToolConfig | UpmadeTextToolConfig | UpmadeShapeToolConfig
): Promise<UpmadeBaseTool | null>

setActiveTool​

Switches the active drawing tool. Deactivates the current tool and clears any selection.

setActiveTool(toolName: string): Promise<void>

disable​

Disables all user interaction with the engine (pointer, keyboard, etc.).

disable(): Promise<void>

enable​

Re-enables user interaction after a call to disable.

enable(): Promise<void>

Clipboard & Editing​

Props​

No clipboard/editing-specific props.

Events​

No clipboard/editing-specific events.

Methods​

copy​

Copies the currently selected objects to the internal clipboard.

copy(): Promise<void>

cut​

Cuts the currently selected objects to the internal clipboard and removes them from the canvas.

cut(): Promise<void>

paste​

Pastes previously copied objects at the specified world coordinates.

paste(x: number, y: number): Promise<void>

delete​

Deletes the currently selected objects from the canvas.

delete(): Promise<void>

Ordering​

Props​

No ordering-specific props.

Events​

No ordering-specific events.

Methods​

bringForward​

Moves an object one layer forward in the z-order, past the next layer above it. If omitted, applies to the current selection and moves each selected layer. A group is one layer, so all of its children move together; a grouped object moves within its group.

bringForward(object?: UpmadeBaseObject): Promise<void>

sendBackward​

Moves an object one layer backward in the z-order, past the next layer below it. If omitted, applies to the current selection and moves each selected layer. A group is one layer, so all of its children move together; a grouped object moves within its group.

sendBackward(object?: UpmadeBaseObject): Promise<void>

bringToFront​

Moves an object to the very front of the z-order. If omitted, applies to the current selection, keeping the relative order of the selected layers. A group moves together with all of its children; a grouped object moves to the front of its group.

bringToFront(object?: UpmadeBaseObject): Promise<void>

sendToBack​

Moves an object to the very back of the z-order. If omitted, applies to the current selection, keeping the relative order of the selected layers. A group moves together with all of its children; a grouped object moves to the back of its group.

sendToBack(object?: UpmadeBaseObject): Promise<void>

Alignment​

Props​

No alignment-specific props.

Events​

No alignment-specific events.

Methods​

alignObjects​

Aligns the currently selected objects according to the specified alignment.

alignObjects(alignment: UpmadeAlignment): Promise<void>

Alignment values: StartHorizontal, CenterHorizontal, EndHorizontal, StartVertical, CenterVertical, EndVertical.


Grouping​

Props​

No grouping-specific props.

Events​

No grouping-specific events.

Methods​

group​

Creates a group (UpmadeGroup) from the given objects. Requires at least two objects. They become one layer at the position of the topmost object, in a single undoable step. Objects are resolved by id, so stale references work; objects that are not in the active workspace are skipped with a console warning. Objects inside a common group are grouped within it; objects from different groups are grouped at the level that contains all of them. Selected objects that end up in the group are replaced by the group in the selection. Resolves to the created group, or null (with a console warning) when fewer than two objects could be grouped. To group the current selection, pass await getSelectedObjects().

group(objects: UpmadeBaseObject[]): Promise<UpmadeGroup | null>

ungroup​

Ungroups the given groups. Their children become individual objects again and keep their stacking order; the children of a nested group stay in its parent group. All groups are dissolved in a single undoable step. Groups are resolved by id, so stale references work; entries that are not an UpmadeGroup or not in the active workspace are skipped with a console warning. Dissolved groups in the selection are replaced by their children. Resolves to the extracted children. To ungroup the current selection, pass the UpmadeGroup objects from await getSelectedObjects().

ungroup(groups: UpmadeGroup[]): Promise<UpmadeBaseObject[]>

Undo & Redo​

Props​

No undo/redo-specific props.

Events​

EventPayload TypeDescription
undoStateChangeUpmadeUndoStateEmitted when undo/redo availability changes.

Methods​

undo​

Undoes the last action.

undo(): Promise<void>

redo​

Redoes the last undone action.

redo(): Promise<void>

Export & Import​

Props​

No export/import-specific props.

Events​

No export/import-specific events.

Methods​

getScreenshot​

Captures a screenshot of the current viewport as a data URL.

getScreenshot(format?: "png" | "svg"): Promise<string | null>

exportViewportAsPng​

Exports the current viewport as a PNG file and triggers a browser download.

exportViewportAsPng(): Promise<void>

exportViewportAsSvg​

Exports the current viewport as an SVG file and triggers a browser download.

exportViewportAsSvg(): Promise<void>

canExportSelectedObjectAs​

Checks whether the currently selected object supports a specific export format.

canExportSelectedObjectAs(format: UpmadeObjectExportFormat): Promise<boolean>

exportSelectedObject​

Exports the currently selected object in the specified format.

exportSelectedObject(format: UpmadeObjectExportFormat): Promise<void>

getSelectedObjectSupportedExportFormats​

Returns the export formats supported by the currently selected object.

getSelectedObjectSupportedExportFormats(): Promise<UpmadeObjectExportFormat[]>

exportAsJson​

Exports the current workspace and all its objects as a JSON string.

exportAsJson(): Promise<string>

importFromJson​

Imports a workspace from a JSON string into a new workspace.

importFromJson(json: string): Promise<void>

loadObjectsFromJson​

Loads objects from workspace JSON into the current workspace.

loadObjectsFromJson(json: string): Promise<number>

downloadAsJson​

Downloads the current workspace as JSON.

downloadAsJson(filename?: string): Promise<void>

importFromFile​

Opens a file picker and imports the selected JSON file.

importFromFile(): Promise<void>

Localization & Settings​

Props​

PropertyTypeDescription
fallbackLocaleLocaleCodeLocale used to resolve terms missing from the active locale.
localeLocaleCodeCurrent locale code.
localesUpmadeLocale[]Available locale definitions.
themeThemeCodeCurrent theme.
themesUpmadeTheme[]Available themes.

Events​

No localization/settings-specific events.

Methods​

registerLocales​

registerLocales(locales: UpmadeLocale[]): Promise<void>

setLocale​

setLocale(code: LocaleCode): Promise<void>

getLocale​

getLocale(): Promise<LocaleCode>

getAvailableLocales​

getAvailableLocales(): Promise<LocaleCode[]>

getAvailableLocaleOptions​

getAvailableLocaleOptions(): Promise<{ code: LocaleCode; label: string }[]>

t​

t(key: UpmadeTermKey, vars?: UpmadeTermVars): Promise<string>

getResolvedTerms​

getResolvedTerms(): Promise<Partial<Record<UpmadeTermKey, string>>>

saveSettings​

saveSettings(settings: UpmadeSettingsConfig): Promise<void>

loadSettings​

loadSettings(): Promise<Partial<UpmadeSettingsConfig> | null>

Context Menu & Lifecycle​

Props​

PropertyTypeDescription
assetStorageConfigUpmadeAssetStorageConfigBinary asset storage provider configuration.
cursorTargetHTMLElementElement to apply cursor styles to.
debugInfoUpmadeDebugInfoDebug overlay configuration.
editorIdstringIdentifier for namespacing storage keys.
globalContextMenuItemsContextMenuItem[]Canvas background menu items.
isWatermarkVisiblebooleanShow or hide the upmade.io watermark (default true). Keeping it visible helps support the project.
lockDrawingScalebooleanKeeps objects at a fixed visual size across zoom.
objectContextMenuItemsContextMenuItem[]Selected-object menu items.

Events​

EventPayload TypeDescription
contextMenuStateChangeUpmadeContextMenuStateEmitted when context-menu state changes.
isEngineReadyUpmadeEngineStateEmitted when the engine is ready.
longpressPointerEventEmitted on touch or pen long-press.
notificationsChangeUpmadeNotificationEmitted when notifications change.

Methods​

openContextMenu​

openContextMenu(options: { x: number; y: number; objectId?: string }): Promise<void>

hideContextMenu​

Hides the context menu and resets any associated selection state.

hideContextMenu(): Promise<void>

getDisplayableShortcuts​

Returns all registered keyboard shortcuts (without action/condition) for display in a help UI.

getDisplayableShortcuts(): Promise<Omit<UpmadeShortcut, "action" | "condition">[]>

beginSceneBootstrap​

beginSceneBootstrap(): Promise<void>

endSceneBootstrap​

endSceneBootstrap(): Promise<void>

Agents​

Agents are participants on the canvas that are driven by code, for example an AI assistant. Each agent is a UpmadeAgent with its own cursor, actions, and undo history. See Agents for a guide. When the editor shares presence, collaborators see its agents, and it shows theirs; see Collaboration.

Props​

PropertyTypeDescription
chatSessionUpmadeChatSessionA chat session whose tools act on this canvas. Its agent, if any, is added here. A session that is replaced finishes its running prompt first. See Agents.

Events​

EventPayload TypeDescription
agentsChangeUpmadeAgentsChangeEventEmitted when agents are added or removed, or when their name, color, avatar, status, visibility, or activity changes, in this editor or in the editor of a collaborator. Lists the agents of this editor first, then the agents of collaborators (isRemote: true). Never emitted for plain cursor motion.

Methods​

addAgent​

Adds an agent and shows its cursor. Adding the same agent again does nothing. An agent belongs to one editor at a time; an agent of an editor that was removed from the page moves here. Call it after the engine emitted isEngineReady. Rejects for a value that is not an UpmadeAgent, for a second agent with the same ID, and for an agent of another editor.

addAgent(agent: UpmadeAgent): Promise<UpmadeAgent>

removeAgent​

Removes an agent, given the agent or its ID: its running action is rolled back, its queued actions resolve with 'agent-removed', and its cursor and history are dropped. The agent can be added again. Resolves with false if the agent was not added.

removeAgent(agent: UpmadeAgent | string): Promise<boolean>

getAgent​

Returns an agent added to this editor by its ID, or null if there is none. Agents of collaborators are never returned; see getRemoteAgents.

getAgent(id: string): Promise<UpmadeAgent | null>

getAgents​

Returns the agents added to this editor.

getAgents(): Promise<UpmadeAgent[]>

getRemoteAgents​

Returns the agents of collaborators, as they share them through presence. They are descriptions, not UpmadeAgent objects, and cannot be controlled from here. Empty without a sync provider that shares presence. See UpmadeRemoteAgentPresence.

getRemoteAgents(): Promise<UpmadeRemoteAgentPresence[]>

Object Titlebar​

Props​

PropertyTypeDescription
objectTitlebarUpmadeObjectTitlebarConfigContent of the titlebar rendered above every object for which objectConfig.hasTitlebar is true. The same configuration applies to all objects. Leave unset to disable titlebars. See Object Titlebar.

Events​

EventPayload TypeDescription
objectTitlebarActionUpmadeObjectTitlebarActionEventEmitted when a button in an object titlebar is clicked or a menu item of a titlebar menu is selected, in addition to calling the optional action callback of the button or menu item.
objectTitlebarMenuStateChangeUpmadeObjectTitlebarMenuStateEmitted when a titlebar menu opens or closes. Contains the resolved menu items and the menu button as anchor, so that a host can render the menu. <UpmadeEditor> renders titlebar menus itself and does not re-emit this event.

Methods​

closeObjectTitlebarMenu​

Closes the open titlebar menu, if any.

closeObjectTitlebarMenu(): Promise<void>

selectObjectTitlebarMenuItem​

Selects a menu item of the open titlebar menu. Closes the menu, calls the menu item's action, and emits objectTitlebarAction with the id of the menu as elementId and menuItemId. Does nothing if no menu is open or the menu item is hidden or disabled.

selectObjectTitlebarMenuItem(menuItemId: string): Promise<void>

Use updateObject to change the name of an existing object.


Object Elements​

Elements inside the content of objects such as UpmadeIframeObject. See Interacting with iFrame Content.

Props​

No object-element-specific props.

Events​

EventPayload TypeDescription
objectElementHoverUpmadeObjectElementHoverEventEmitted when the mouse or pen pointer moves onto another element inside the content of a selected object, such as an iframe object, and with element: null when it leaves the content or the object is deselected.
objectElementClickUpmadeObjectElementClickEventEmitted when the user clicks an element inside the content of a selected object. The click works as usual.
objectElementPickUpmadeObjectElementPickEventEmitted when the user picks an element inside an object that is picking elements. The click doesn't reach the content. See setObjectElementPicking.

Methods​

setObjectElementPicking​

Turns element picking on or off for an object whose content has elements, such as an iframe object. While picking, the element under the pointer is highlighted, and a press or click emits objectElementPick instead of reaching the content. Picking works while the object is selected and stays on until it is turned off. selector limits picking to the closest matching ancestor of the element under the pointer, color sets the highlight color.

setObjectElementPicking(objectId: string, enabled: boolean, options?: UpmadeObjectElementPickingOptions): Promise<void>

highlightObjectElements​

Highlights elements inside an object's content, replacing the object's previous highlights. Each entry is { selector, color?, label? }, and every element that matches its selector is highlighted, up to 100 per selector. Highlights are local: they are neither saved nor shown to collaborators.

highlightObjectElements(objectId: string, highlights: UpmadeObjectElementHighlight[]): Promise<void>

clearObjectElementHighlights​

Removes the element highlights of an object, or of all objects when objectId is omitted.

clearObjectElementHighlights(objectId?: string): Promise<void>

queryObjectElements​

Describes the elements inside an object's content that match a CSS selector, in document order. Each result has a selector that can be used to highlight the element or point an agent's cursor at it (agent.moveTo({ objectId, selector }), see UpmadeAgenticTarget). limit defaults to 100 and can be at most 500. The object must be mounted, which it is while it is in or near the viewport. Rejects when the content does not answer within 3 seconds, or within 15 seconds while it is still loading.

queryObjectElements(objectId: string, selector: string, limit?: number): Promise<UpmadeObjectElementInfo[]>

All object element methods reject for invalid selectors and for objects that don't exist or have no content elements.

Support us

Upmade is an MIT-licensed open source project. If you like the idea of a framework-agnostic infinite canvas library and want to support our work, leave us a star or consider becoming a sponsor.