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 controls.

Object

Props

Property	Type	Description
objectConfig	KritzelObjectConfig	Configures 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

Event	Payload Type	Description
objectsAdded	ObjectsAddedEvent	Emitted when one or more objects are added to the canvas.
objectsChange	KritzelBaseObject[]	Emitted when objects on the canvas are added, removed, or modified.
objectsRemoved	ObjectsRemovedEvent	Emitted when one or more objects are removed from the canvas.
objectsUpdated	ObjectsUpdatedEvent	Emitted when one or more objects are updated on the canvas.

Methods

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>

addObjects

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

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

removeObject

Removes an object from the canvas.

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

removeObjects

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

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

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<Element>) => 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[]>

---

Selection

Props

No selection-specific props.

Events

Event	Payload Type	Description
objectsSelectionChange	void	Emitted when the set of selected objects changes.

Methods

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

Props

Property	Type	Description
isPanningEnabled	boolean	Enable or disable viewport panning via regular wheel input.
isZoomingEnabled	boolean	Enable or disable viewport zooming via Ctrl+wheel.
scaleMax	number	Maximum zoom scale allowed.
scaleMin	number	Minimum zoom scale allowed.
viewportBoundaryBottom	number	Bottom pan boundary in world coordinates.
viewportBoundaryLeft	number	Left pan boundary in world coordinates.
viewportBoundaryRight	number	Right pan boundary in world coordinates.
viewportBoundaryTop	number	Top pan boundary in world coordinates.

Events

Event	Payload Type	Description
viewportChange	KritzelViewportState	Emitted on viewport pan, zoom, or resize.
objectsInViewportChange	KritzelBaseObject[]	Emitted when the set of objects visible in the current viewport changes (for example after pan/zoom).

Methods

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>

panToObject

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

panToObject(object: KritzelBaseObject): 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: KritzelBaseObject): Promise<KritzelBaseObject>

centerObjects

Pans and zooms the viewport to fit the provided objects.

centerObjects(objects: KritzelBaseObject[], 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

Property	Type	Description
activeWorkspaceId	string	Optional workspace ID to load. If provided, the engine automatically loads this workspace by ID.
workspaces	KritzelWorkspace[]	Optional authoritative workspace catalog for this engine instance. Provider-only workspaces are hidden but not deleted.
syncConfig	KritzelSyncConfig	Configuration for real-time synchronization providers (for example IndexedDB/WebSocket).
user	IKritzelUser	Current user for awareness broadcasting (name, id, cursor position).
isLoading	boolean	External loading state merged with internal workspace loading state.

Events

Event	Payload Type	Description
activeWorkspaceChange	KritzelWorkspace	Emitted when the active workspace changes (for example after import or switching workspaces).
workspacesChange	KritzelWorkspace[]	Emitted when workspaces are created, updated, or deleted.
awarenessChange	AwarenessStateMap	Emitted when awareness state changes (remote user cursors/presence).
syncingChange	boolean	Emitted when remote workspace synchronization status changes.
loadingChange	boolean	Emitted when the combined loading state changes (external isLoading or internal workspace loading).

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 a KritzelWorkspace instance.

createWorkspace(workspace: KritzelWorkspace): Promise<KritzelWorkspace | 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: 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>

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

Event	Payload Type	Description
activeToolChange	KritzelBaseTool	Emitted when the active drawing tool changes.

Methods

registerTool

Registers a new drawing tool with the engine.

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

setActiveTool

Switches the active drawing tool by its registered name.

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 (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

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?: KritzelBaseObject): 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?: KritzelBaseObject): 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?: KritzelBaseObject): 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?: KritzelBaseObject): 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: KritzelAlignment): 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 (KritzelGroup) 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: KritzelBaseObject[]): Promise<KritzelGroup | 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 a KritzelGroup 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 KritzelGroup objects from await getSelectedObjects().

ungroup(groups: KritzelGroup[]): Promise<KritzelBaseObject[]>

---

Undo & Redo

Props

No undo/redo-specific props.

Events

Event	Payload Type	Description
undoStateChange	KritzelUndoState	Emitted 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 ("png" | "svg").

canExportSelectedObjectAs(format: KritzelObjectExportFormat): Promise<boolean>

exportSelectedObject

Exports the currently selected object in the specified format ("png" | "svg").

exportSelectedObject(format: KritzelObjectExportFormat): Promise<void>

getSelectedObjectSupportedExportFormats

Retrieves the array of export formats supported by the currently selected object.

getSelectedObjectSupportedExportFormats(): Promise<KritzelObjectExportFormat[]>

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>

downloadAsJson

Exports the current workspace as a JSON file and triggers a browser download.

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

importFromFile

Opens a file picker dialog and imports the selected JSON file into the workspace.

importFromFile(): Promise<void>

---

Localization & Settings

Props

Property	Type	Description
fallbackLocale	LocaleCode	Locale used to resolve terms missing from the active locale.
locale	LocaleCode	Current locale (language) code applied to the editor, for example en, de, fr.
locales	KritzelLocale[]	Available locale definitions with optional partial term overrides.
theme	ThemeCode	Current theme applied to the editor.
themes	KritzelTheme[]	Available themes for the editor.

Events

No localization/settings-specific events.

Methods

registerLocales

Registers additional locale definitions (with optional partial term overrides).

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

setLocale

Sets the active locale (language) and re-renders the UI.

setLocale(code: LocaleCode): Promise<void>

getLocale

Gets the currently active locale code.

getLocale(): Promise<LocaleCode>

getAvailableLocales

Gets the list of available locale codes (built-in and registered).

getAvailableLocales(): Promise<LocaleCode[]>

getAvailableLocaleOptions

Gets the list of available locales as { code, label } options.

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

t

Resolves a term key to its translated string for the active locale.

t(key: KritzelTermKey, vars?: KritzelTermVars): Promise<string>

getResolvedTerms

Resolves every known term key for the active locale into a flat map.

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

saveSettings

Persists the given settings object to localStorage.

saveSettings(settings: KritzelSettingsConfig): Promise<void>

loadSettings

Loads the persisted settings object from localStorage.

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

---

Context Menu & Lifecycle

Props

Property	Type	Description
assetStorageConfig	KritzelAssetStorageConfig	Configuration for binary asset storage providers (for example image bytes and remote asset sync).
cursorTarget	HTMLElement	HTML element to apply cursor styles to. Defaults to document.body if not set.
debugInfo	KritzelDebugInfo	Controls which debug overlays are visible.
editorId	string	Optional unique identifier for namespacing storage keys across multiple engine instances.
globalContextMenuItems	ContextMenuItem[]	Context menu items shown when right-clicking the canvas background.
isWatermarkVisible	boolean	Show or hide the "Powered by Kritzel" watermark (default true). Keeping it visible helps support the project.
lockDrawingScale	boolean	Keep drawn objects at a fixed visual size regardless of zoom.
objectContextMenuItems	ContextMenuItem[]	Context menu items shown when right-clicking selected objects.

Events

Event	Payload Type	Description
contextMenuStateChange	KritzelContextMenuState	Emitted when context-menu visibility, items, or position changes.
isEngineReady	KritzelEngineState	Emitted when the engine has fully initialized and is ready for interaction.
longpress	PointerEvent	Emitted on long-press (touch/pen), useful for showing custom context menus on mobile.
notificationsChange	KritzelNotification	Emitted when notifications change.

Methods

openContextMenu

Programmatically opens the context menu at a specified world-coordinate position.

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

beginSceneBootstrap

Starts a scene bootstrap phase by hiding the scene immediately.

beginSceneBootstrap(): Promise<void>

endSceneBootstrap

Ends the scene bootstrap phase.

endSceneBootstrap(): Promise<void>

Agentic Cursors

Props

No agentic-cursor-specific props.

Events

Event	Payload Type	Description
agenticCursorDetached	KritzelAgenticCursorDetachedEvent	Emitted when an agentic cursor is detached from an object, either manually or because the object was removed.

Methods

addAgenticCursor

Adds a programmatically controlled cursor. Agentic cursors are rendered locally only.

addAgenticCursor(options?: KritzelAgenticCursorOptions): Promise<KritzelAgenticCursor>

updateAgenticCursor

Updates the name, color, status or visibility of an agentic cursor. Pass status: null to clear the status.

updateAgenticCursor(id: string, patch: KritzelAgenticCursorPatch): Promise<KritzelAgenticCursor>

moveAgenticCursor

Smoothly moves an agentic cursor to world coordinates or to an anchor on an object. Object targets attach the cursor by default. Resolves when the animation ends; completed is false if the move was interrupted.

moveAgenticCursor(id: string, target: KritzelAgenticCursorTarget, options?: KritzelAgenticCursorMoveOptions): Promise<KritzelAgenticCursorMoveResult>

detachAgenticCursor

Detaches an agentic cursor from its object. The cursor stays at its current position.

detachAgenticCursor(id: string): Promise<void>

removeAgenticCursor

Removes an agentic cursor. A running move resolves with completed: false.

removeAgenticCursor(id: string): Promise<boolean>

clearAgenticCursors

Removes all agentic cursors.

clearAgenticCursors(): Promise<void>

getAgenticCursor

Returns a snapshot of an agentic cursor, or null if it doesn't exist.

getAgenticCursor(id: string): Promise<KritzelAgenticCursor | null>

getAgenticCursors

Returns snapshots of all agentic cursors.

getAgenticCursors(): Promise<KritzelAgenticCursor[]>

---

Object Titlebar

Props

Property	Type	Description
objectTitlebar	KritzelObjectTitlebarConfig	Content 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

Event	Payload Type	Description
objectTitlebarAction	KritzelObjectTitlebarActionEvent	Emitted 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.
objectTitlebarMenuStateChange	KritzelObjectTitlebarMenuState	Emitted 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. <kritzel-editor> 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.