@kritzel/engine 0.4.31

package/dist/types/components.d.ts

@@ -0,0 +1,981 @@
+/* eslint-disable */
+/* tslint:disable */
+/**
+ * This is an autogenerated file created by the Stencil compiler.
+ * It contains typing information for all components that exist in this project.
+ */
+import { HTMLStencilElement, JSXBase } from "./stencil-public-runtime";
+import { KritzelCore } from "./classes/core/core.class";
+import { KritzelWorkspace } from "./classes/core/workspace.class";
+import { KritzelSyncConfig } from "./interfaces/sync-config.interface";
+import { KritzelAssetStorageConfig } from "./interfaces/asset-storage-config.interface";
+import { IKritzelUser } from "./interfaces/user.interface";
+import { ContextMenuItem } from "./interfaces/context-menu-item.interface";
+import { KritzelTheme, ThemeName } from "./interfaces/theme.interface";
+import { KritzelLocale, KritzelTermKey, KritzelTermVars, LocaleCode } from "./interfaces/localization.interface";
+import { KritzelDebugInfo } from "./interfaces/debug-info.interface";
+import { KritzelEngineState } from "./interfaces/engine-state.interface";
+import { KritzelBaseTool } from "./classes/tools/base-tool.class";
+import { KritzelBaseObject } from "./classes/objects/base-object.class";
+import { ObjectsAddedEvent, ObjectsInViewportChangeEvent, ObjectsRemovedEvent, ObjectsUpdatedEvent } from "./interfaces/object-change-event.interface";
+import { KritzelUndoState } from "./interfaces/undo-state.interface";
+import { KritzelViewportState } from "./interfaces/viewport-state.interface";
+import { KritzelNotification } from "./interfaces/notification.interface";
+import { KritzelContextMenuState } from "./interfaces/context-menu-state.interface";
+import { KritzelBrushToolConfig, KritzelLineToolConfig, KritzelShapeToolConfig, KritzelTextToolConfig } from "./interfaces/toolbar-item.interface";
+import { KritzelAlignment } from "./enums/alignment.enum";
+import { Element, Event } from "./stencil-public-runtime";
+import { KritzelImage } from "./classes/objects/image.class";
+import { KritzelText } from "./classes/objects/text.class";
+import { KritzelGroup } from "./classes/objects/group.class";
+import { KritzelLine } from "./classes/objects/line.class";
+import { KritzelShortcut } from "./interfaces/shortcut.interface";
+import { KritzelObjectExportFormat } from "./interfaces/object-export.interface";
+import { KritzelSettingsConfig } from "./interfaces/settings.interface";
+export { KritzelCore } from "./classes/core/core.class";
+export { KritzelWorkspace } from "./classes/core/workspace.class";
+export { KritzelSyncConfig } from "./interfaces/sync-config.interface";
+export { KritzelAssetStorageConfig } from "./interfaces/asset-storage-config.interface";
+export { IKritzelUser } from "./interfaces/user.interface";
+export { ContextMenuItem } from "./interfaces/context-menu-item.interface";
+export { KritzelTheme, ThemeName } from "./interfaces/theme.interface";
+export { KritzelLocale, KritzelTermKey, KritzelTermVars, LocaleCode } from "./interfaces/localization.interface";
+export { KritzelDebugInfo } from "./interfaces/debug-info.interface";
+export { KritzelEngineState } from "./interfaces/engine-state.interface";
+export { KritzelBaseTool } from "./classes/tools/base-tool.class";
+export { KritzelBaseObject } from "./classes/objects/base-object.class";
+export { ObjectsAddedEvent, ObjectsInViewportChangeEvent, ObjectsRemovedEvent, ObjectsUpdatedEvent } from "./interfaces/object-change-event.interface";
+export { KritzelUndoState } from "./interfaces/undo-state.interface";
+export { KritzelViewportState } from "./interfaces/viewport-state.interface";
+export { KritzelNotification } from "./interfaces/notification.interface";
+export { KritzelContextMenuState } from "./interfaces/context-menu-state.interface";
+export { KritzelBrushToolConfig, KritzelLineToolConfig, KritzelShapeToolConfig, KritzelTextToolConfig } from "./interfaces/toolbar-item.interface";
+export { KritzelAlignment } from "./enums/alignment.enum";
+export { Element, Event } from "./stencil-public-runtime";
+export { KritzelImage } from "./classes/objects/image.class";
+export { KritzelText } from "./classes/objects/text.class";
+export { KritzelGroup } from "./classes/objects/group.class";
+export { KritzelLine } from "./classes/objects/line.class";
+export { KritzelShortcut } from "./interfaces/shortcut.interface";
+export { KritzelObjectExportFormat } from "./interfaces/object-export.interface";
+export { KritzelSettingsConfig } from "./interfaces/settings.interface";
+export namespace Components {
+    interface KritzelAwarenessCursors {
+        "core": KritzelCore;
+        /**
+          * @default 8
+         */
+        "edgeIndicatorPadding": number;
+        /**
+          * @default true
+         */
+        "showEdgeIndicators": boolean;
+    }
+    interface KritzelCursorTrail {
+        "core": KritzelCore;
+    }
+    interface KritzelEngine {
+        /**
+          * Optional workspace ID to load. If provided, the engine will look up and load this workspace by ID.
+         */
+        "activeWorkspaceId"?: string;
+        /**
+          * Adds a new object to the canvas. The object will be assigned an ID, core reference, and z-index automatically.
+          * @param object - The object instance to add.
+          * @returns The added object.
+         */
+        "addObject": <T extends KritzelBaseObject>(object: T) => Promise<T | null>;
+        /**
+          * Adds multiple objects to the canvas in a single batch operation. All objects are inserted within one Yjs transaction (single undo step), triggering only one rerender cycle. Intended for programmatic streaming scenarios where per-object overhead would cause stutter.
+          * @param objects - The object instances to add.
+          * @returns The added objects.
+         */
+        "addObjects": <T extends KritzelBaseObject>(objects: T[]) => Promise<T[]>;
+        /**
+          * Aligns the currently selected objects according to the specified alignment.
+          * @param alignment - The alignment direction (e.g., `CenterHorizontal`, `StartVertical`).
+         */
+        "alignObjects": (alignment: KritzelAlignment) => Promise<void>;
+        /**
+          * Configuration for binary asset storage (e.g., images).  The Yjs document only persists asset ids; the actual bytes are stored by the providers listed here. Defaults to IndexedDB-only storage. To support cross-device image sync alongside a networked sync provider (Hocuspocus, WebSocket), configure at least one remote asset provider such as `HttpAssetProvider` or `PresignedAssetProvider`.
+         */
+        "assetStorageConfig"?: KritzelAssetStorageConfig;
+        /**
+          * Pans and zooms the viewport to fit the nearest content, with padding. Useful when the user has panned away from all objects.
+          * @returns `true` if content was found and the viewport was adjusted, `false` otherwise.
+         */
+        "backToContent": () => Promise<boolean>;
+        /**
+          * Starts a scene bootstrap phase by hiding the scene immediately.
+         */
+        "beginSceneBootstrap": () => Promise<void>;
+        /**
+          * Moves an object one layer forward in the z-order.
+          * @param object - The object to move. If omitted, applies to the current selection.
+         */
+        "bringForward": (object?: KritzelBaseObject<any>) => Promise<void>;
+        /**
+          * Moves an object to the very front of the z-order.
+          * @param object - The object to move. If omitted, applies to the current selection.
+         */
+        "bringToFront": (object?: KritzelBaseObject<any>) => Promise<void>;
+        /**
+          * Checks whether the currently selected object supports a specific export format. Returns false when none or multiple objects are selected.
+         */
+        "canExportSelectedObjectAs": (format: KritzelObjectExportFormat) => Promise<boolean>;
+        /**
+          * Cancels an active file picker opened by importFromFile.
+         */
+        "cancelImportFromFile": () => Promise<void>;
+        /**
+          * Pans and zooms the viewport to fit ALL objects on the canvas, including those not currently rendered. Calculates the combined bounding box of all objects and centers the viewport to show them.
+          * @param animate - Whether to animate the viewport transition (default: true).
+          * @returns `true` if objects were found and the viewport was adjusted, `false` otherwise.
+         */
+        "centerAllObjects": (animate?: boolean) => Promise<boolean>;
+        /**
+          * Pans and zooms the viewport to center on the given object.
+          * @param object - The object to center in the viewport.
+          * @returns The centered object.
+         */
+        "centerObjectInViewport": (object: KritzelBaseObject) => Promise<KritzelBaseObject<HTMLElement | SVGElement>>;
+        /**
+          * Pans and zooms the viewport to fit the provided objects. Calculates the combined bounding box of the given objects and centers the viewport to show them.
+          * @param objects - The objects to center and fit in the viewport.
+          * @param animate - Whether to animate the viewport transition (default: true).
+          * @returns `true` if objects were provided and the viewport was adjusted, `false` otherwise.
+         */
+        "centerObjects": (objects: KritzelBaseObject[], animate?: boolean) => Promise<boolean>;
+        /**
+          * Switches the active drawing tool by its registered name.
+          * @param toolName - The name the tool was registered with (e.g., 'brush', 'eraser').
+         */
+        "changeActiveTool": (toolName: string) => Promise<void>;
+        /**
+          * Deselects all currently selected objects.
+         */
+        "clearSelection": () => Promise<void>;
+        /**
+          * Declaratively configures the full locale catalog, replacing the available locale set. Pass `undefined` to restore the built-in locales (en/de/fr).
+          * @param locales - The full locale catalog, or `undefined` for built-ins.
+         */
+        "configureLocales": (locales?: KritzelLocale[]) => Promise<void>;
+        /**
+          * Copies the currently selected objects to the internal clipboard.
+         */
+        "copy": () => Promise<void>;
+        /**
+          * Creates a new workspace and emits a `workspacesChange` event. Emits `activeWorkspaceChange` if the created workspace is activated.
+          * @param workspace - The workspace instance to create.
+          * @returns The created workspace.
+         */
+        "createWorkspace": (workspace: KritzelWorkspace) => Promise<KritzelWorkspace | null>;
+        /**
+          * The HTML element to apply cursor styles to. Defaults to `document.body` if not set.
+         */
+        "cursorTarget"?: HTMLElement;
+        /**
+          * Cuts the currently selected objects to the internal clipboard (deletes them from the canvas).
+         */
+        "cut": () => Promise<void>;
+        /**
+          * Debug info display options controlling which debug overlays are visible
+         */
+        "debugInfo"?: KritzelDebugInfo;
+        /**
+          * Deletes the currently selected objects from the canvas.
+         */
+        "delete": () => Promise<void>;
+        /**
+          * Deletes a workspace and emits a `workspacesChange` event.
+          * @param workspace - The workspace to delete.
+         */
+        "deleteWorkspace": (workspace: KritzelWorkspace) => Promise<void>;
+        /**
+          * Disables all user interaction with the engine (pointer, keyboard, etc.).
+         */
+        "disable": () => Promise<void>;
+        /**
+          * Exports the current workspace as a JSON file and triggers a browser download.
+          * @param filename - Optional custom filename (without extension). Defaults to workspace name with timestamp.
+         */
+        "downloadAsJson": (filename?: string) => Promise<void>;
+        /**
+          * Optional unique identifier for namespacing storage keys across multiple editor instances.
+         */
+        "editorId"?: string;
+        /**
+          * Re-enables user interaction after a call to `disable()`.
+         */
+        "enable": () => Promise<void>;
+        /**
+          * Ends a scene bootstrap phase by fading the scene back in.
+         */
+        "endSceneBootstrap": () => Promise<void>;
+        /**
+          * Exports the current workspace and all its objects as a JSON string. The exported data includes workspace metadata (id, name, viewport) and all canvas objects.
+          * @returns A JSON string representing the complete workspace state.
+         */
+        "exportAsJson": () => Promise<string>;
+        /**
+          * Exports the currently selected object in the requested format and triggers a file download. Only supports single selection.
+         */
+        "exportSelectedObject": (format: KritzelObjectExportFormat) => Promise<void>;
+        /**
+          * Exports the current viewport as a PNG file and triggers a browser download.
+         */
+        "exportViewportAsPng": () => Promise<void>;
+        /**
+          * Exports the current viewport as an SVG file and triggers a browser download.
+         */
+        "exportViewportAsSvg": () => Promise<void>;
+        /**
+          * The locale used to resolve terms missing from the active locale.
+          * @default 'en'
+         */
+        "fallbackLocale": LocaleCode;
+        /**
+          * Returns all objects that match the given predicate function. Excludes internal selection-related objects (selection groups and selection boxes).
+          * @param predicate - A filter function called for each object. Return `true` to include.
+          * @returns An array of matching objects.
+          * @example ```ts // Find all text objects const texts = await engine.findObjects(obj => obj.__class__ === 'KritzelText');  // Find objects at a point const hits = await engine.findObjects(obj => obj.hitTest(100, 200));  // Combine criteria const filtered = await engine.findObjects(obj => obj.__class__ === 'KritzelPath' && obj.opacity < 0.5); ```
+         */
+        "findObjects": <T extends KritzelBaseObject>(predicate: (obj: KritzelBaseObject<Element>) => boolean) => Promise<T[]>;
+        /**
+          * Returns the currently active workspace.
+         */
+        "getActiveWorkspace": () => Promise<KritzelWorkspace>;
+        /**
+          * Returns all objects on the canvas across all layers.
+         */
+        "getAllObjects": <T extends KritzelBaseObject>() => Promise<T[]>;
+        /**
+          * Gets the list of available locales as `{ code, label }` options for a selector.
+         */
+        "getAvailableLocaleOptions": () => Promise<{ code: LocaleCode; label: string; }[]>;
+        /**
+          * Gets the list of available locale codes (built-in and registered).
+         */
+        "getAvailableLocales": () => Promise<LocaleCode[]>;
+        /**
+          * Returns all registered keyboard shortcuts (without action/condition) for display in a help UI.
+         */
+        "getDisplayableShortcuts": () => Promise<Omit<KritzelShortcut, "action" | "condition">[]>;
+        /**
+          * Gets whether the active workspace is publicly accessible.
+          * @returns True if the workspace is public, false otherwise
+         */
+        "getIsPublic": () => Promise<boolean>;
+        /**
+          * Gets the currently active locale code.
+         */
+        "getLocale": () => Promise<LocaleCode>;
+        /**
+          * Retrieves a canvas object by its unique ID.
+          * @param id - The object's unique identifier.
+          * @returns The matching object, or `null` if not found.
+         */
+        "getObjectById": <T extends KritzelBaseObject>(id: string) => Promise<T | null>;
+        /**
+          * Returns all objects currently visible within the viewport bounds.
+         */
+        "getObjectsInViewport": () => Promise<KritzelBaseObject[]>;
+        /**
+          * Returns the total number of objects on the canvas.
+         */
+        "getObjectsTotalCount": () => Promise<number>;
+        /**
+          * Resolves every known term key for the active locale into a flat map. Useful for UI layers that need to localize many strings at once.
+         */
+        "getResolvedTerms": () => Promise<Partial<Record<KritzelTermKey, string>>>;
+        /**
+          * Captures a screenshot of the current viewport as a data URL.
+          * @param format - The image format: `'png'` (default) or `'svg'`.
+          * @returns A data URL string of the captured image.
+         */
+        "getScreenshot": (format?: "png" | "svg") => Promise<string | null>;
+        /**
+          * Returns export formats supported by the currently selected object. Only returns formats when exactly one object is selected.
+         */
+        "getSelectedObjectSupportedExportFormats": () => Promise<KritzelObjectExportFormat[]>;
+        /**
+          * Returns the currently selected objects. Returns an empty array if nothing is selected.
+         */
+        "getSelectedObjects": () => Promise<KritzelBaseObject<any>[]>;
+        /**
+          * Returns the current viewport state including position, scale, and dimensions.
+          * @returns The current viewport state.
+         */
+        "getViewport": () => Promise<KritzelViewportState>;
+        /**
+          * Returns all available workspaces.
+         */
+        "getWorkspaces": () => Promise<KritzelWorkspace[]>;
+        /**
+          * Context menu items shown when right-clicking the canvas background.
+         */
+        "globalContextMenuItems"?: ContextMenuItem[];
+        /**
+          * Groups the currently selected objects into a single selection group.
+         */
+        "group": () => Promise<void>;
+        /**
+          * Hides the context menu and resets any associated selection state.
+         */
+        "hideContextMenu": () => Promise<void>;
+        /**
+          * Opens a file picker dialog and imports the selected JSON file into the workspace. This method creates a hidden file input, triggers the browser's file chooser, reads the selected JSON file, and imports it using importFromJson.
+          * @returns A promise that resolves when the import is complete or rejects on error/cancel.
+         */
+        "importFromFile": () => Promise<void>;
+        /**
+          * Imports a workspace from a JSON string into a new workspace. Creates a new workspace with the imported data and automatically switches to it.
+          * @param json - A JSON string containing workspace data (from exportAsJson).
+          * @throws Error if the JSON is invalid or the format version is incompatible.
+         */
+        "importFromJson": (json: string) => Promise<void>;
+        /**
+          * When false, non-modified wheel events do not pan the viewport.
+          * @default true
+         */
+        "isPanningEnabled": boolean;
+        /**
+          * When false, Ctrl+wheel events do not zoom the viewport.
+          * @default true
+         */
+        "isZoomingEnabled": boolean;
+        /**
+          * License key that, when valid, removes the "Powered by Kritzel" watermark.
+         */
+        "licenseKey"?: string;
+        /**
+          * Loads objects from a workspace JSON string into the current workspace. Unlike importFromJson, this does not create a new workspace - it adds objects to the existing one. Useful for initializing a workspace with pre-existing content after the editor is ready.
+          * @param json - A JSON string containing workspace data (from exportAsJson).
+          * @returns The number of objects loaded.
+          * @throws Error if the JSON is invalid or the format version is incompatible.
+         */
+        "loadObjectsFromJson": (json: string) => Promise<number>;
+        /**
+          * Loads the persisted settings object from localStorage.
+          * @returns The stored settings, or null if nothing is stored or the value is invalid.
+         */
+        "loadSettings": () => Promise<Partial<KritzelSettingsConfig> | null>;
+        /**
+          * Loads a shared workspace by token. If the workspace exists locally, it switches to it. If it doesn't exist, it adds it to the local workspaces list and then switches to it.
+          * @param token - The connection token identifying the shared workspace
+         */
+        "loadSharedWorkspace": (token: string) => Promise<void>;
+        /**
+          * The current locale (language) code to apply to the editor, e.g. 'en', 'de', 'fr'.
+          * @default 'en'
+         */
+        "locale": LocaleCode;
+        /**
+          * An array of available locale definitions (with optional partial term overrides). Replaces the built-in locale set (en/de/fr) when provided, even if empty.
+         */
+        "locales"?: KritzelLocale[];
+        /**
+          * When true, objects are drawn at a fixed visual size regardless of zoom level
+          * @default true
+         */
+        "lockDrawingScale": boolean;
+        /**
+          * Context menu items shown when right-clicking a selected object.
+         */
+        "objectContextMenuItems"?: ContextMenuItem[];
+        /**
+          * Programmatically opens the context menu at a specified world-coordinate position. If `objectId` is provided and found, the object context menu is shown for that object. If no `objectId` is provided but a selection group already exists, the object context menu is shown. Otherwise, the global context menu is shown.
+          * @param options.x - The X position in world (canvas) coordinates.
+          * @param options.y - The Y position in world (canvas) coordinates.
+          * @param options.objectId - Optional ID of an object to select and show the object context menu for.
+         */
+        "openContextMenu": (options: { x: number; y: number; objectId?: string; }) => Promise<void>;
+        /**
+          * Pans the viewport to center on the given world coordinates without changing the scale.
+          * @param x - X position in world coordinates to center on.
+          * @param y - Y position in world coordinates to center on.
+         */
+        "panTo": (x: number, y: number) => Promise<void>;
+        /**
+          * Pans the viewport to center on the given object without changing the zoom level. Unlike `centerObjectInViewport`, this moves the camera — not the object.
+          * @param object - The object whose center the viewport should pan to.
+         */
+        "panToObject": (object: KritzelBaseObject) => Promise<void>;
+        /**
+          * Pastes previously copied objects at the specified world coordinates.
+          * @param x - X position in world coordinates.
+          * @param y - Y position in world coordinates.
+         */
+        "paste": (x: number, y: number) => Promise<void>;
+        /**
+          * Redoes the last undone action.
+         */
+        "redo": () => Promise<void>;
+        /**
+          * Registers additional locale definitions (with optional partial term overrides).
+          * @param locales - The locale definitions to register.
+         */
+        "registerLocales": (locales: KritzelLocale[]) => Promise<void>;
+        /**
+          * Registers a new drawing tool with the engine.
+          * @param toolName - Unique identifier for the tool (e.g., 'brush', 'eraser').
+          * @param toolClass - Constructor class extending `KritzelBaseTool`.
+          * @param toolConfig - Optional initial configuration to apply to the tool instance.
+          * @returns The registered tool instance, or `null` if registration failed.
+         */
+        "registerTool": (toolName: string, toolClass: any, toolConfig?: KritzelTextToolConfig | KritzelBrushToolConfig | KritzelLineToolConfig | KritzelShapeToolConfig) => Promise<KritzelBaseTool | null>;
+        /**
+          * Reinitializes sync by performing a full teardown and re-initialization. Destroys the current Yjs documents and providers, then rebuilds everything from the current syncConfig. Data reloads from IndexedDB nearly instantly. Call this after updating the syncConfig prop (e.g. after authentication state changes).
+         */
+        "reinitSync": () => Promise<void>;
+        /**
+          * Removes an object from the canvas.
+          * @param object - The object to remove.
+          * @returns The removed object.
+         */
+        "removeObject": <T extends KritzelBaseObject>(object: T) => Promise<T | null>;
+        /**
+          * Removes multiple objects from the canvas in a single batch operation. All removals happen within one Yjs transaction (single undo step), triggering only one rerender cycle. Intended for programmatic streaming scenarios where per-object overhead would cause stutter.
+          * @param objects - The objects to remove.
+          * @returns The removed objects.
+         */
+        "removeObjects": <T extends KritzelBaseObject>(objects: T[]) => Promise<T[]>;
+        /**
+          * Persists the given settings object to localStorage using the namespaced storage key.
+          * @param settings - The settings configuration to persist.
+         */
+        "saveSettings": (settings: KritzelSettingsConfig) => Promise<void>;
+        /**
+          * Maximum zoom scale allowed. Clamped to the absolute maximum defined by the engine.
+          * @default 1000
+         */
+        "scaleMax": number;
+        /**
+          * Minimum zoom scale allowed. Clamped to the absolute minimum defined by the engine.
+          * @default 0.0001
+         */
+        "scaleMin": number;
+        /**
+          * Converts screen-relative pixel coordinates to world coordinates.
+          * @param x - X position in screen pixels (relative to the engine element).
+          * @param y - Y position in screen pixels (relative to the engine element).
+          * @returns World coordinates { x, y }.
+         */
+        "screenToWorld": (x: number, y: number) => Promise<{ x: number; y: number; }>;
+        /**
+          * Selects all objects currently visible in the viewport. Switches to the selection tool automatically.
+         */
+        "selectAllObjectsInViewport": () => Promise<void>;
+        /**
+          * Programmatically selects the given objects. Switches to the selection tool automatically.
+          * @param objects - The objects to select.
+         */
+        "selectObjects": (objects: KritzelBaseObject[]) => Promise<void>;
+        /**
+          * Moves an object one layer backward in the z-order.
+          * @param object - The object to move. If omitted, applies to the current selection.
+         */
+        "sendBackward": (object?: KritzelBaseObject<any>) => Promise<void>;
+        /**
+          * Moves an object to the very back of the z-order.
+          * @param object - The object to move. If omitted, applies to the current selection.
+         */
+        "sendToBack": (object?: KritzelBaseObject<any>) => Promise<void>;
+        /**
+          * Switches the active workspace in the engine by ID.
+          * @param id - The unique ID of the workspace to activate
+         */
+        "setActiveWorkspace": (id: string) => Promise<void>;
+        /**
+          * Sets the active locale (language) and re-renders the UI.
+          * @param code - The locale code to activate, e.g. 'de'.
+         */
+        "setLocale": (code: LocaleCode) => Promise<void>;
+        /**
+          * Sets the viewport to center on the given world coordinates at the specified scale.
+          * @param x - X position in world coordinates to center on.
+          * @param y - Y position in world coordinates to center on.
+          * @param scale - Target scale level.
+         */
+        "setViewport": (x: number, y: number, scale: number) => Promise<void>;
+        /**
+          * Configuration for real-time synchronization providers (e.g., IndexedDB, WebSocket).
+         */
+        "syncConfig"?: KritzelSyncConfig;
+        /**
+          * Resolves a term key to its translated string for the active locale.
+          * @param key - The term key to resolve.
+          * @param vars - Optional values for `{placeholder}` interpolation.
+         */
+        "t": (key: KritzelTermKey, vars?: KritzelTermVars) => Promise<string>;
+        /**
+          * The current theme to apply to the editor
+          * @default 'light'
+         */
+        "theme": ThemeName;
+        /**
+          * An array of available themes for the editor.
+         */
+        "themes"?: KritzelTheme[];
+        /**
+          * Manually triggers the `objectsSelectionChange` event.
+         */
+        "triggerSelectionChange": () => Promise<void>;
+        /**
+          * Undoes the last action.
+         */
+        "undo": () => Promise<void>;
+        /**
+          * Ungroups the currently selected group back into individual objects.
+         */
+        "ungroup": () => Promise<void>;
+        /**
+          * Updates properties of an existing canvas object.
+          * @param object - The object to update.
+          * @param updatedProperties - A partial set of properties to apply.
+          * @returns The updated object.
+         */
+        "updateObject": <T extends KritzelBaseObject>(object: T, updatedProperties: Partial<T>) => Promise<T | null>;
+        /**
+          * 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 (`undefined` leaves objects untouched, `[]` removes them all); updating objects of a non-active workspace requires a configured sync provider.
+          * @param workspace - The workspace describing the desired state.
+         */
+        "updateWorkspace": (workspace: KritzelWorkspace) => Promise<void>;
+        /**
+          * The current user for awareness broadcasting (name, id, cursor position).
+         */
+        "user"?: IKritzelUser;
+        /**
+          * Bottom boundary of the viewport in world coordinates. Objects beyond this Y position cannot be panned to.
+          * @default Infinity
+         */
+        "viewportBoundaryBottom": number;
+        /**
+          * Left boundary of the viewport in world coordinates. Objects beyond this X position cannot be panned to.
+          * @default -Infinity
+         */
+        "viewportBoundaryLeft": number;
+        /**
+          * Right boundary of the viewport in world coordinates. Objects beyond this X position cannot be panned to.
+          * @default Infinity
+         */
+        "viewportBoundaryRight": number;
+        /**
+          * Top boundary of the viewport in world coordinates. Objects beyond this Y position cannot be panned to.
+          * @default -Infinity
+         */
+        "viewportBoundaryTop": number;
+        /**
+          * Authoritative workspace catalog for this engine instance. When provided, provider-only workspaces are hidden but not deleted.
+         */
+        "workspaces"?: KritzelWorkspace[];
+        /**
+          * Converts world coordinates to screen-relative pixel coordinates.
+          * @param x - X position in world coordinates.
+          * @param y - Y position in world coordinates.
+          * @returns Screen coordinates { x, y } relative to the engine element.
+         */
+        "worldToScreen": (x: number, y: number) => Promise<{ x: number; y: number; }>;
+        /**
+          * Zooms in by a fixed step, centered on the current viewport center, with a smooth animation.
+          * @param factor - Multiplicative zoom-in step.
+          * @param duration - Animation duration in milliseconds.
+         */
+        "zoomIn": (factor: number, duration: number) => Promise<void>;
+        /**
+          * Zooms out by a fixed step, centered on the current viewport center, with a smooth animation.
+          * @param factor - Multiplicative zoom-out step.
+          * @param duration - Animation duration in milliseconds.
+         */
+        "zoomOut": (factor: number, duration: number) => Promise<void>;
+        /**
+          * Zooms the viewport to the given scale level. Optionally centers on a world point; if omitted, zooms around the viewport center.
+          * @param scale - Target scale level.
+          * @param worldX - Optional X position in world coordinates to center on.
+          * @param worldY - Optional Y position in world coordinates to center on.
+         */
+        "zoomTo": (scale: number, worldX?: number, worldY?: number) => Promise<void>;
+    }
+    interface KritzelIcon {
+        "label"?: string;
+        "name": string;
+        /**
+          * @default 24
+         */
+        "size": number;
+    }
+    /**
+     * "Powered by Kritzel" watermark shown in the bottom-right corner of the engine
+     * when the editor is not licensed.
+     * Rendered inside the engine's Shadow DOM and gated by the license manager on
+     * the engine's reactive render path, so removing the node simply causes it to
+     * reappear on the next render. The badge links to the Kritzel website.
+     */
+    interface KritzelWatermark {
+        /**
+          * The core instance used to resolve localized terms.
+         */
+        "core": KritzelCore;
+        /**
+          * Resolved "Powered by Kritzel" label. Passed in by the engine so the badge re-renders when the active locale changes. Falls back to resolving the term from the core when not provided.
+         */
+        "label"?: string;
+    }
+}
+export interface KritzelEngineCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLKritzelEngineElement;
+}
+declare global {
+    interface HTMLKritzelAwarenessCursorsElement extends Components.KritzelAwarenessCursors, HTMLStencilElement {
+    }
+    var HTMLKritzelAwarenessCursorsElement: {
+        prototype: HTMLKritzelAwarenessCursorsElement;
+        new (): HTMLKritzelAwarenessCursorsElement;
+    };
+    interface HTMLKritzelCursorTrailElement extends Components.KritzelCursorTrail, HTMLStencilElement {
+    }
+    var HTMLKritzelCursorTrailElement: {
+        prototype: HTMLKritzelCursorTrailElement;
+        new (): HTMLKritzelCursorTrailElement;
+    };
+    interface HTMLKritzelEngineElementEventMap {
+        "isEngineReady": KritzelEngineState;
+        "activeToolChange": KritzelBaseTool;
+        "workspacesChange": KritzelWorkspace[];
+        "activeWorkspaceChange": KritzelWorkspace;
+        "longpress": PointerEvent;
+        "objectsChange": KritzelBaseObject[];
+        "objectsAdded": ObjectsAddedEvent;
+        "objectsRemoved": ObjectsRemovedEvent;
+        "objectsUpdated": ObjectsUpdatedEvent;
+        "objectsSelectionChange": KritzelBaseObject[];
+        "undoStateChange": KritzelUndoState;
+        "objectsInViewportChange": ObjectsInViewportChangeEvent;
+        "viewportChange": KritzelViewportState;
+        "awarenessChange": Map<number, Record<string, any>>;
+        "notificationsChange": KritzelNotification;
+        "contextMenuStateChange": KritzelContextMenuState;
+        "isLoadingChange": boolean;
+    }
+    interface HTMLKritzelEngineElement extends Components.KritzelEngine, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLKritzelEngineElementEventMap>(type: K, listener: (this: HTMLKritzelEngineElement, ev: KritzelEngineCustomEvent<HTMLKritzelEngineElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLKritzelEngineElementEventMap>(type: K, listener: (this: HTMLKritzelEngineElement, ev: KritzelEngineCustomEvent<HTMLKritzelEngineElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLKritzelEngineElement: {
+        prototype: HTMLKritzelEngineElement;
+        new (): HTMLKritzelEngineElement;
+    };
+    interface HTMLKritzelIconElement extends Components.KritzelIcon, HTMLStencilElement {
+    }
+    var HTMLKritzelIconElement: {
+        prototype: HTMLKritzelIconElement;
+        new (): HTMLKritzelIconElement;
+    };
+    /**
+     * "Powered by Kritzel" watermark shown in the bottom-right corner of the engine
+     * when the editor is not licensed.
+     * Rendered inside the engine's Shadow DOM and gated by the license manager on
+     * the engine's reactive render path, so removing the node simply causes it to
+     * reappear on the next render. The badge links to the Kritzel website.
+     */
+    interface HTMLKritzelWatermarkElement extends Components.KritzelWatermark, HTMLStencilElement {
+    }
+    var HTMLKritzelWatermarkElement: {
+        prototype: HTMLKritzelWatermarkElement;
+        new (): HTMLKritzelWatermarkElement;
+    };
+    interface HTMLElementTagNameMap {
+        "kritzel-awareness-cursors": HTMLKritzelAwarenessCursorsElement;
+        "kritzel-cursor-trail": HTMLKritzelCursorTrailElement;
+        "kritzel-engine": HTMLKritzelEngineElement;
+        "kritzel-icon": HTMLKritzelIconElement;
+        "kritzel-watermark": HTMLKritzelWatermarkElement;
+    }
+}
+declare namespace LocalJSX {
+    interface KritzelAwarenessCursors {
+        "core": KritzelCore;
+        /**
+          * @default 8
+         */
+        "edgeIndicatorPadding"?: number;
+        /**
+          * @default true
+         */
+        "showEdgeIndicators"?: boolean;
+    }
+    interface KritzelCursorTrail {
+        "core": KritzelCore;
+    }
+    interface KritzelEngine {
+        /**
+          * Optional workspace ID to load. If provided, the engine will look up and load this workspace by ID.
+         */
+        "activeWorkspaceId"?: string;
+        /**
+          * Configuration for binary asset storage (e.g., images).  The Yjs document only persists asset ids; the actual bytes are stored by the providers listed here. Defaults to IndexedDB-only storage. To support cross-device image sync alongside a networked sync provider (Hocuspocus, WebSocket), configure at least one remote asset provider such as `HttpAssetProvider` or `PresignedAssetProvider`.
+         */
+        "assetStorageConfig"?: KritzelAssetStorageConfig;
+        /**
+          * The HTML element to apply cursor styles to. Defaults to `document.body` if not set.
+         */
+        "cursorTarget"?: HTMLElement;
+        /**
+          * Debug info display options controlling which debug overlays are visible
+         */
+        "debugInfo"?: KritzelDebugInfo;
+        /**
+          * Optional unique identifier for namespacing storage keys across multiple editor instances.
+         */
+        "editorId"?: string;
+        /**
+          * The locale used to resolve terms missing from the active locale.
+          * @default 'en'
+         */
+        "fallbackLocale"?: LocaleCode;
+        /**
+          * Context menu items shown when right-clicking the canvas background.
+         */
+        "globalContextMenuItems"?: ContextMenuItem[];
+        /**
+          * When false, non-modified wheel events do not pan the viewport.
+          * @default true
+         */
+        "isPanningEnabled"?: boolean;
+        /**
+          * When false, Ctrl+wheel events do not zoom the viewport.
+          * @default true
+         */
+        "isZoomingEnabled"?: boolean;
+        /**
+          * License key that, when valid, removes the "Powered by Kritzel" watermark.
+         */
+        "licenseKey"?: string;
+        /**
+          * The current locale (language) code to apply to the editor, e.g. 'en', 'de', 'fr'.
+          * @default 'en'
+         */
+        "locale"?: LocaleCode;
+        /**
+          * An array of available locale definitions (with optional partial term overrides). Replaces the built-in locale set (en/de/fr) when provided, even if empty.
+         */
+        "locales"?: KritzelLocale[];
+        /**
+          * When true, objects are drawn at a fixed visual size regardless of zoom level
+          * @default true
+         */
+        "lockDrawingScale"?: boolean;
+        /**
+          * Context menu items shown when right-clicking a selected object.
+         */
+        "objectContextMenuItems"?: ContextMenuItem[];
+        /**
+          * Emitted when the active drawing tool changes.
+         */
+        "onActiveToolChange"?: (event: KritzelEngineCustomEvent<KritzelBaseTool>) => void;
+        /**
+          * Emitted when the active workspace changes (e.g., after import).
+         */
+        "onActiveWorkspaceChange"?: (event: KritzelEngineCustomEvent<KritzelWorkspace>) => void;
+        /**
+          * Emitted when the awareness state changes (remote user cursors, presence).
+         */
+        "onAwarenessChange"?: (event: KritzelEngineCustomEvent<Map<number, Record<string, any>>>) => void;
+        /**
+          * Emitted when context-menu visibility, items, or position changes.
+         */
+        "onContextMenuStateChange"?: (event: KritzelEngineCustomEvent<KritzelContextMenuState>) => void;
+        /**
+          * Emitted when the engine has fully initialized and is ready for interaction.
+         */
+        "onIsEngineReady"?: (event: KritzelEngineCustomEvent<KritzelEngineState>) => void;
+        /**
+          * Emitted while the selected workspace's objects are being initialized and synchronized.
+         */
+        "onIsLoadingChange"?: (event: KritzelEngineCustomEvent<boolean>) => void;
+        /**
+          * Emitted on long-press (touch/pen). Useful for showing custom context menus on mobile.
+         */
+        "onLongpress"?: (event: KritzelEngineCustomEvent<PointerEvent>) => void;
+        /**
+          * Emitted when notifications change.
+         */
+        "onNotificationsChange"?: (event: KritzelEngineCustomEvent<KritzelNotification>) => void;
+        /**
+          * Emitted when one or more objects are added to the canvas.
+         */
+        "onObjectsAdded"?: (event: KritzelEngineCustomEvent<ObjectsAddedEvent>) => void;
+        /**
+          * Emitted when objects on the canvas are added, removed, or modified.
+         */
+        "onObjectsChange"?: (event: KritzelEngineCustomEvent<KritzelBaseObject[]>) => void;
+        /**
+          * Emitted when the set of objects visible in the current viewport changes (e.g., after pan or zoom).
+         */
+        "onObjectsInViewportChange"?: (event: KritzelEngineCustomEvent<ObjectsInViewportChangeEvent>) => void;
+        /**
+          * Emitted when one or more objects are removed from the canvas.
+         */
+        "onObjectsRemoved"?: (event: KritzelEngineCustomEvent<ObjectsRemovedEvent>) => void;
+        /**
+          * Emitted when the set of selected objects changes.
+         */
+        "onObjectsSelectionChange"?: (event: KritzelEngineCustomEvent<KritzelBaseObject[]>) => void;
+        /**
+          * Emitted when one or more objects are updated on the canvas.
+         */
+        "onObjectsUpdated"?: (event: KritzelEngineCustomEvent<ObjectsUpdatedEvent>) => void;
+        /**
+          * Emitted when the undo/redo state changes, providing current undo availability.
+         */
+        "onUndoStateChange"?: (event: KritzelEngineCustomEvent<KritzelUndoState>) => void;
+        /**
+          * Emitted when the viewport position, scale, or dimensions change (e.g., after pan, zoom, or resize).
+         */
+        "onViewportChange"?: (event: KritzelEngineCustomEvent<KritzelViewportState>) => void;
+        /**
+          * Emitted when workspaces are created, updated, or deleted.
+         */
+        "onWorkspacesChange"?: (event: KritzelEngineCustomEvent<KritzelWorkspace[]>) => void;
+        /**
+          * Maximum zoom scale allowed. Clamped to the absolute maximum defined by the engine.
+          * @default 1000
+         */
+        "scaleMax"?: number;
+        /**
+          * Minimum zoom scale allowed. Clamped to the absolute minimum defined by the engine.
+          * @default 0.0001
+         */
+        "scaleMin"?: number;
+        /**
+          * Configuration for real-time synchronization providers (e.g., IndexedDB, WebSocket).
+         */
+        "syncConfig"?: KritzelSyncConfig;
+        /**
+          * The current theme to apply to the editor
+          * @default 'light'
+         */
+        "theme"?: ThemeName;
+        /**
+          * An array of available themes for the editor.
+         */
+        "themes"?: KritzelTheme[];
+        /**
+          * The current user for awareness broadcasting (name, id, cursor position).
+         */
+        "user"?: IKritzelUser;
+        /**
+          * Bottom boundary of the viewport in world coordinates. Objects beyond this Y position cannot be panned to.
+          * @default Infinity
+         */
+        "viewportBoundaryBottom"?: number;
+        /**
+          * Left boundary of the viewport in world coordinates. Objects beyond this X position cannot be panned to.
+          * @default -Infinity
+         */
+        "viewportBoundaryLeft"?: number;
+        /**
+          * Right boundary of the viewport in world coordinates. Objects beyond this X position cannot be panned to.
+          * @default Infinity
+         */
+        "viewportBoundaryRight"?: number;
+        /**
+          * Top boundary of the viewport in world coordinates. Objects beyond this Y position cannot be panned to.
+          * @default -Infinity
+         */
+        "viewportBoundaryTop"?: number;
+        /**
+          * Authoritative workspace catalog for this engine instance. When provided, provider-only workspaces are hidden but not deleted.
+         */
+        "workspaces"?: KritzelWorkspace[];
+    }
+    interface KritzelIcon {
+        "label"?: string;
+        "name"?: string;
+        /**
+          * @default 24
+         */
+        "size"?: number;
+    }
+    /**
+     * "Powered by Kritzel" watermark shown in the bottom-right corner of the engine
+     * when the editor is not licensed.
+     * Rendered inside the engine's Shadow DOM and gated by the license manager on
+     * the engine's reactive render path, so removing the node simply causes it to
+     * reappear on the next render. The badge links to the Kritzel website.
+     */
+    interface KritzelWatermark {
+        /**
+          * The core instance used to resolve localized terms.
+         */
+        "core": KritzelCore;
+        /**
+          * Resolved "Powered by Kritzel" label. Passed in by the engine so the badge re-renders when the active locale changes. Falls back to resolving the term from the core when not provided.
+         */
+        "label"?: string;
+    }
+
+    interface KritzelAwarenessCursorsAttributes {
+        "showEdgeIndicators": boolean;
+        "edgeIndicatorPadding": number;
+    }
+    interface KritzelEngineAttributes {
+        "editorId": string;
+        "activeWorkspaceId": string;
+        "scaleMax": number;
+        "scaleMin": number;
+        "lockDrawingScale": boolean;
+        "theme": ThemeName;
+        "licenseKey": string;
+        "locale": LocaleCode;
+        "fallbackLocale": LocaleCode;
+        "viewportBoundaryLeft": number;
+        "viewportBoundaryRight": number;
+        "viewportBoundaryTop": number;
+        "viewportBoundaryBottom": number;
+        "isPanningEnabled": boolean;
+        "isZoomingEnabled": boolean;
+    }
+    interface KritzelIconAttributes {
+        "name": string;
+        "label": string;
+        "size": number;
+    }
+    interface KritzelWatermarkAttributes {
+        "label": string;
+    }
+
+    interface IntrinsicElements {
+        "kritzel-awareness-cursors": Omit<KritzelAwarenessCursors, keyof KritzelAwarenessCursorsAttributes> & { [K in keyof KritzelAwarenessCursors & keyof KritzelAwarenessCursorsAttributes]?: KritzelAwarenessCursors[K] } & { [K in keyof KritzelAwarenessCursors & keyof KritzelAwarenessCursorsAttributes as `attr:${K}`]?: KritzelAwarenessCursorsAttributes[K] } & { [K in keyof KritzelAwarenessCursors & keyof KritzelAwarenessCursorsAttributes as `prop:${K}`]?: KritzelAwarenessCursors[K] };
+        "kritzel-cursor-trail": KritzelCursorTrail;
+        "kritzel-engine": Omit<KritzelEngine, keyof KritzelEngineAttributes> & { [K in keyof KritzelEngine & keyof KritzelEngineAttributes]?: KritzelEngine[K] } & { [K in keyof KritzelEngine & keyof KritzelEngineAttributes as `attr:${K}`]?: KritzelEngineAttributes[K] } & { [K in keyof KritzelEngine & keyof KritzelEngineAttributes as `prop:${K}`]?: KritzelEngine[K] };
+        "kritzel-icon": Omit<KritzelIcon, keyof KritzelIconAttributes> & { [K in keyof KritzelIcon & keyof KritzelIconAttributes]?: KritzelIcon[K] } & { [K in keyof KritzelIcon & keyof KritzelIconAttributes as `attr:${K}`]?: KritzelIconAttributes[K] } & { [K in keyof KritzelIcon & keyof KritzelIconAttributes as `prop:${K}`]?: KritzelIcon[K] };
+        "kritzel-watermark": Omit<KritzelWatermark, keyof KritzelWatermarkAttributes> & { [K in keyof KritzelWatermark & keyof KritzelWatermarkAttributes]?: KritzelWatermark[K] } & { [K in keyof KritzelWatermark & keyof KritzelWatermarkAttributes as `attr:${K}`]?: KritzelWatermarkAttributes[K] } & { [K in keyof KritzelWatermark & keyof KritzelWatermarkAttributes as `prop:${K}`]?: KritzelWatermark[K] };
+    }
+}
+export { LocalJSX as JSX };
+declare module "@stencil/core" {
+    export namespace JSX {
+        interface IntrinsicElements {
+            "kritzel-awareness-cursors": LocalJSX.IntrinsicElements["kritzel-awareness-cursors"] & JSXBase.HTMLAttributes<HTMLKritzelAwarenessCursorsElement>;
+            "kritzel-cursor-trail": LocalJSX.IntrinsicElements["kritzel-cursor-trail"] & JSXBase.HTMLAttributes<HTMLKritzelCursorTrailElement>;
+            "kritzel-engine": LocalJSX.IntrinsicElements["kritzel-engine"] & JSXBase.HTMLAttributes<HTMLKritzelEngineElement>;
+            "kritzel-icon": LocalJSX.IntrinsicElements["kritzel-icon"] & JSXBase.HTMLAttributes<HTMLKritzelIconElement>;
+            /**
+             * "Powered by Kritzel" watermark shown in the bottom-right corner of the engine
+             * when the editor is not licensed.
+             * Rendered inside the engine's Shadow DOM and gated by the license manager on
+             * the engine's reactive render path, so removing the node simply causes it to
+             * reappear on the next render. The badge links to the Kritzel website.
+             */
+            "kritzel-watermark": LocalJSX.IntrinsicElements["kritzel-watermark"] & JSXBase.HTMLAttributes<HTMLKritzelWatermarkElement>;
+        }
+    }
+}