Engine

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

Props

Property	Type	Description
activeWorkspaceId	string	Programmatically force an active workspace
assetStorageConfig	KritzelAssetStorageConfig	Asset storage configuration for images
cursorTarget	HTMLElement	Element to apply cursor styles to
debugInfo	KritzelDebugInfo	Toggle debug overlay information
editorId	string	Unique identifier for namespacing storage keys
globalContextMenuItems	ContextMenuItem[]	Context menu items for canvas background
isLoading	boolean	External loading state
lockDrawingScale	boolean	Fixed visual size for drawn objects regardless of zoom
objectContextMenuItems	ContextMenuItem[]	Context menu items for selected objects
scaleMax	number	Maximum zoom scale
scaleMin	number	Minimum zoom scale
syncConfig	KritzelSyncConfig	Sync provider configuration
theme	'light' | 'dark'	Active theme
themes	KritzelTheme[]	Array of available themes
user	IKritzelUser	The current user for awareness broadcasting
viewportBoundaryBottom	number	Bottom pan boundary
viewportBoundaryLeft	number	Left pan boundary
viewportBoundaryRight	number	Right pan boundary
viewportBoundaryTop	number	Top pan boundary
wheelEnabled	boolean	Enable or disable mouse wheel zoom/pan
workspace	KritzelWorkspace	The active workspace

Events

Event	Payload Type	Description
activeToolChange	KritzelBaseTool	Emitted when the active tool changes
activeWorkspaceChange	KritzelWorkspace	Emitted when the active workspace changes
awarenessChange	Map<number, Record<string, any>>	Emitted when the awareness state changes
isEngineReady	KritzelEngineState	Emitted when the engine is fully initialized
longpress	PointerEvent	Emitted on long-press (useful for mobile context menus)
objectsAdded	ObjectsAddedEvent	Emitted when objects are added
objectsChange	KritzelBaseObject[]	Emitted when objects are added, removed, or modified
objectsInViewportChange	KritzelBaseObject[]	Emitted when visible objects change (after pan/zoom)
objectsRemoved	ObjectsRemovedEvent	Emitted when objects are removed
objectsSelectionChange	void	Emitted when selected objects change
objectsUpdated	ObjectsUpdatedEvent	Emitted when objects are updated
undoStateChange	KritzelUndoState	Emitted when undo/redo availability changes
viewportChange	KritzelViewportState	Emitted on pan, zoom, or resize
workspacesChange	KritzelWorkspace[]	Emitted when workspaces are created, updated, or deleted

---

Methods

All methods are async and return Promises.

Object

addObject

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

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

removeObject

Removes an object from the canvas.

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

updateObject

Updates properties of an existing canvas object.

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

getObjectById

Retrieves a canvas object by its unique ID.

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

getAllObjects

Returns all objects on the canvas across all layers.

getAllObjects<T extends KritzelBaseObject>: Promise<T[]>

findObjects

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

findObjects<T extends KritzelBaseObject>(predicate: (obj: KritzelBaseObject) => 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<KritzelBaseObject[]>

getCopiedObjects

Returns objects currently in the internal clipboard from a prior copy call.

getCopiedObjects: Promise<KritzelBaseObject[]>

---

Selection

getSelectedObjects

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

getSelectedObjects: Promise<KritzelBaseObject[]>

selectObjects

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

selectObjects(objects: KritzelBaseObject[]): 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

getViewport

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

getViewport: Promise<KritzelViewportState>

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>

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>

centerObjectInViewport

Pans and zooms the viewport to center on the given object.

centerObjectInViewport(object: KritzelBaseObject): Promise<KritzelBaseObject>

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>

Returns true if content was found and the viewport was adjusted, false otherwise.

centerAllObjects

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

centerAllObjects(animate?: boolean): 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

createWorkspace

Creates a new workspace and emits a workspacesChange event.

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

updateWorkspace

Updates an existing workspace's metadata and emits a workspacesChange event.

updateWorkspace(workspace: KritzelWorkspace): Promise<void>

deleteWorkspace

Deletes a workspace and emits a workspacesChange event.

deleteWorkspace(workspace: KritzelWorkspace): Promise<void>

getWorkspaces

Returns all available workspaces.

getWorkspaces: Promise<KritzelWorkspace[]>

getActiveWorkspace

Returns the currently active workspace.

getActiveWorkspace: Promise<KritzelWorkspace>

---

Tool Management

registerTool

Registers a new drawing tool with the engine.

registerTool(
  toolName: string,
  toolClass: any,
  toolConfig?: KritzelBrushToolConfig | KritzelLineToolConfig | KritzelTextToolConfig | KritzelShapeToolConfig
): Promise<KritzelBaseTool>

changeActiveToolByName

Switches the active drawing tool by its registered name.

changeActiveToolByName(toolName: string): Promise<void>

changeActiveTool

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

changeActiveTool(tool: KritzelBaseTool): 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

copy

Copies the currently selected objects to the internal clipboard.

copy(): Promise<void>

cut

Cuts the currently selected objects to the internal clipboard (deletes 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

bringForward

Moves an object one layer forward in the z-order. If omitted, applies to the current selection.

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

sendBackward

Moves an object one layer backward in the z-order. If omitted, applies to the current selection.

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

bringToFront

Moves an object to the very front of the z-order. If omitted, applies to the current selection.

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

sendToBack

Moves an object to the very back of the z-order. If omitted, applies to the current selection.

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

---

Alignment

alignObjects

Aligns the currently selected objects according to the specified alignment.

alignObjects(alignment: KritzelAlignment): Promise<void>

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

---

Grouping

group

Groups the currently selected objects into a single group.

group: Promise<void>

ungroup

Ungroups the currently selected group back into individual objects.

ungroup: Promise<void>

---

Undo & Redo

undo

Undoes the last action.

undo: Promise<void>

redo

Redoes the last undone action.

redo: Promise<void>

---

Export

getScreenshot

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

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

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>

getSelectedObjectsAsSvgString

Generates an SVG string from the currently selected objects.

getSelectedObjectsAsSvgString(options?: { theme?: 'light' | 'dark'; padding?: number }): Promise<string | null>

exportSelectedObjectsAsSvg

Exports the currently selected objects as an SVG file and triggers a browser download.

exportSelectedObjectsAsSvg(options?: { theme?: 'light' | 'dark'; padding?: number }): Promise<void>

getSelectedObjectsAsPngDataUrl

Generates a PNG data URL from the currently selected objects.

getSelectedObjectsAsPngDataUrl(options?: { theme?: 'light' | 'dark'; padding?: number; scale?: number }): Promise<string | null>

exportSelectedObjectsAsPng

Exports the currently selected objects as a PNG file and triggers a browser download.

exportSelectedObjectsAsPng(options?: { theme?: 'light' | 'dark'; padding?: number; scale?: number }): Promise<void>

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 a workspace JSON string into the current workspace.

loadObjectsFromJson(json: string): Promise<number>

---

Other

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<KritzelShortcut, 'action' | 'condition'>[]>