@kritzel/engine 0.4.31

package/dist/types/components/kritzel-engine/kritzel-engine.d.ts

@@ -0,0 +1,695 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import { KritzelViewport } from '../../classes/core/viewport.class';
+import { KritzelKeyHandler } from '../../classes/handlers/key.handler';
+import { KritzelBaseTool } from '../../classes/tools/base-tool.class';
+import { ContextMenuItem } from '../../interfaces/context-menu-item.interface';
+import { KritzelBrushToolConfig, KritzelLineToolConfig, KritzelShapeToolConfig, KritzelTextToolConfig } from '../../interfaces/toolbar-item.interface';
+import { KritzelContextMenuHandler } from '../../classes/handlers/context-menu.handler';
+import { KritzelBaseObject } from '../../classes/objects/base-object.class';
+import { KritzelWorkspace } from '../../classes/core/workspace.class';
+import { KritzelEngineState } from '../../interfaces/engine-state.interface';
+import { KritzelDebugInfo } from '../../interfaces/debug-info.interface';
+import { KritzelSettingsConfig } from '../../interfaces/settings.interface';
+import { KritzelCore } from '../../classes/core/core.class';
+import { KritzelSyncConfig } from '../../interfaces/sync-config.interface';
+import { KritzelAssetStorageConfig } from '../../interfaces/asset-storage-config.interface';
+import { KritzelUndoState } from '../../interfaces/undo-state.interface';
+import { KritzelTheme, ThemeName } from '../../interfaces/theme.interface';
+import { KritzelLocale, KritzelTermKey, KritzelTermVars, LocaleCode } from '../../interfaces/localization.interface';
+import { KritzelShortcut } from '../../interfaces/shortcut.interface';
+import { KritzelAlignment } from '../../enums/alignment.enum';
+import { KritzelViewportState } from '../../interfaces/viewport-state.interface';
+import { ObjectsAddedEvent, ObjectsRemovedEvent, ObjectsUpdatedEvent, ObjectsInViewportChangeEvent } from '../../interfaces/object-change-event.interface';
+import { IKritzelUser } from '../../interfaces/user.interface';
+import { KritzelNotification } from '../../interfaces/notification.interface';
+import { KritzelContextMenuState } from '../../interfaces/context-menu-state.interface';
+import { KritzelObjectExportFormat } from '../../interfaces/object-export.interface';
+export declare class KritzelEngine {
+    host: HTMLElement;
+    private activeImportFileInput?;
+    private cancelActiveImport?;
+    /** Authoritative workspace catalog for this engine instance. When provided, provider-only workspaces are hidden but not deleted. */
+    workspaces?: KritzelWorkspace[];
+    onWorkspacesPropChange(): Promise<void>;
+    /** Optional unique identifier for namespacing storage keys across multiple editor instances. */
+    editorId?: string;
+    /** Optional workspace ID to load. If provided, the engine will look up and load this workspace by ID. */
+    activeWorkspaceId?: string;
+    onActiveWorkspaceIdChange(newWorkspaceId?: string): Promise<void>;
+    /** Configuration for real-time synchronization providers (e.g., IndexedDB, WebSocket). */
+    syncConfig?: KritzelSyncConfig;
+    onSyncConfigChange(newValue: KritzelSyncConfig | undefined): 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;
+    onAssetStorageConfigChange(newValue: KritzelAssetStorageConfig | undefined): Promise<void>;
+    /** The current user for awareness broadcasting (name, id, cursor position). */
+    user?: IKritzelUser;
+    onUserChange(newValue: IKritzelUser | undefined): void;
+    /** Context menu items shown when right-clicking the canvas background. */
+    globalContextMenuItems?: ContextMenuItem[];
+    onGlobalContextMenuItemsChange(newValue: ContextMenuItem[] | undefined): void;
+    /** Context menu items shown when right-clicking a selected object. */
+    objectContextMenuItems?: ContextMenuItem[];
+    onObjectContextMenuItemsChange(newValue: ContextMenuItem[] | undefined): void;
+    /** Maximum zoom scale allowed. Clamped to the absolute maximum defined by the engine. */
+    scaleMax: number;
+    validateScaleMax(newValue: number): void;
+    /** Minimum zoom scale allowed. Clamped to the absolute minimum defined by the engine. */
+    scaleMin: number;
+    validateScaleMin(newValue: number): void;
+    /** The HTML element to apply cursor styles to. Defaults to `document.body` if not set. */
+    cursorTarget?: HTMLElement;
+    onCursorTargetChange(newValue: HTMLElement | undefined): void;
+    /** When true, objects are drawn at a fixed visual size regardless of zoom level */
+    lockDrawingScale: boolean;
+    onLockDrawingScaleChange(newValue: boolean): void;
+    /** The current theme to apply to the editor */
+    theme: ThemeName;
+    onThemeChange(newValue: ThemeName): void;
+    /** License key that, when valid, removes the "Powered by Kritzel" watermark. */
+    licenseKey?: string;
+    onLicenseKeyChange(newValue?: string): void;
+    /** An array of available themes for the editor. */
+    themes?: KritzelTheme[];
+    onThemesChange(newValue?: KritzelTheme[]): void;
+    /** The current locale (language) code to apply to the editor, e.g. 'en', 'de', 'fr'. */
+    locale: LocaleCode;
+    onLocaleChange(newValue: LocaleCode): void;
+    /** 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[];
+    onLocalesChange(newValue?: KritzelLocale[]): void;
+    /** The locale used to resolve terms missing from the active locale. */
+    fallbackLocale: LocaleCode;
+    onFallbackLocaleChange(newValue: LocaleCode): void;
+    /** Left boundary of the viewport in world coordinates. Objects beyond this X position cannot be panned to. */
+    viewportBoundaryLeft: number;
+    onViewportBoundaryLeftChange(newValue: number): void;
+    /** Right boundary of the viewport in world coordinates. Objects beyond this X position cannot be panned to. */
+    viewportBoundaryRight: number;
+    onViewportBoundaryRightChange(newValue: number): void;
+    /** Top boundary of the viewport in world coordinates. Objects beyond this Y position cannot be panned to. */
+    viewportBoundaryTop: number;
+    onViewportBoundaryTopChange(newValue: number): void;
+    /** Bottom boundary of the viewport in world coordinates. Objects beyond this Y position cannot be panned to. */
+    viewportBoundaryBottom: number;
+    onViewportBoundaryBottomChange(newValue: number): void;
+    /** Debug info display options controlling which debug overlays are visible */
+    debugInfo?: KritzelDebugInfo;
+    onDebugInfoChange(newValue: KritzelDebugInfo): void;
+    /** When false, non-modified wheel events do not pan the viewport. */
+    isPanningEnabled: boolean;
+    /** When false, Ctrl+wheel events do not zoom the viewport. */
+    isZoomingEnabled: boolean;
+    /** Emitted when the engine has fully initialized and is ready for interaction. */
+    isEngineReady: EventEmitter<KritzelEngineState>;
+    /** Emitted when the active drawing tool changes. */
+    activeToolChange: EventEmitter<KritzelBaseTool>;
+    /** Emitted when workspaces are created, updated, or deleted. */
+    workspacesChange: EventEmitter<KritzelWorkspace[]>;
+    /** Emitted when the active workspace changes (e.g., after import). */
+    activeWorkspaceChange: EventEmitter<KritzelWorkspace>;
+    /** Emitted on long-press (touch/pen). Useful for showing custom context menus on mobile. */
+    longpress: EventEmitter<PointerEvent>;
+    /** Emitted when objects on the canvas are added, removed, or modified. */
+    objectsChange: EventEmitter<KritzelBaseObject[]>;
+    /** Emitted when one or more objects are added to the canvas. */
+    objectsAdded: EventEmitter<ObjectsAddedEvent>;
+    /** Emitted when one or more objects are removed from the canvas. */
+    objectsRemoved: EventEmitter<ObjectsRemovedEvent>;
+    /** Emitted when one or more objects are updated on the canvas. */
+    objectsUpdated: EventEmitter<ObjectsUpdatedEvent>;
+    /** Emitted when the set of selected objects changes. */
+    objectsSelectionChange: EventEmitter<KritzelBaseObject[]>;
+    /** Emitted when the undo/redo state changes, providing current undo availability. */
+    undoStateChange: EventEmitter<KritzelUndoState>;
+    /** Emitted when the set of objects visible in the current viewport changes (e.g., after pan or zoom). */
+    objectsInViewportChange: EventEmitter<ObjectsInViewportChangeEvent>;
+    /** Emitted when the viewport position, scale, or dimensions change (e.g., after pan, zoom, or resize). */
+    viewportChange: EventEmitter<KritzelViewportState>;
+    /** Emitted when the awareness state changes (remote user cursors, presence). */
+    awarenessChange: EventEmitter<Map<number, Record<string, any>>>;
+    /** Emitted when notifications change. */
+    notificationsChange: EventEmitter<KritzelNotification>;
+    /** Emitted when context-menu visibility, items, or position changes. */
+    contextMenuStateChange: EventEmitter<KritzelContextMenuState>;
+    /** Emitted while the selected workspace's objects are being initialized and synchronized. */
+    isLoadingChange: EventEmitter<boolean>;
+    forceUpdate: number;
+    /** Manually triggers the `objectsSelectionChange` event. */
+    triggerSelectionChange(): Promise<void>;
+    /** Starts a scene bootstrap phase by hiding the scene immediately. */
+    beginSceneBootstrap(): Promise<void>;
+    /** Ends a scene bootstrap phase by fading the scene back in. */
+    endSceneBootstrap(): Promise<void>;
+    handleWheel(ev: WheelEvent): void;
+    handlePointerDown(ev: PointerEvent): void;
+    private throttledPointerMoveMulti;
+    handlePointerMove(ev: PointerEvent): void;
+    handlePointerUp(ev: PointerEvent): void;
+    handlePointerCancel(ev: PointerEvent): void;
+    private isEmbeddedDynamicObjectInteraction;
+    private isNativeInteractiveEmbeddedTarget;
+    handlePointerLeave(): void;
+    handleLongPress(ev: CustomEvent<PointerEvent>): void;
+    handleContextMenu(ev: PointerEvent): void;
+    handleResize(): void;
+    handleKeyDown(ev: KeyboardEvent): void;
+    handleKeyUp(ev: KeyboardEvent): void;
+    handleCopy(ev: ClipboardEvent): void;
+    handleCut(ev: ClipboardEvent): void;
+    handlePaste(ev: ClipboardEvent): void;
+    /**
+     * Determines if the engine should handle a keyboard/clipboard shortcut event.
+     * Returns true only if:
+     * - The event originates from within the engine component, OR
+     * - The event target is not an interactive element that needs keyboard input
+     *
+     * This prevents conflicts with inputs, textareas, dialogs, or other
+     * interactive elements that need their own keyboard handling.
+     */
+    private shouldHandleGlobalShortcutEvent;
+    preventDoubleTapZoomOnTouchDevices(ev: MouseEvent): 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>;
+    private activateTool;
+    /**
+     * 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>;
+    /** Disables all user interaction with the engine (pointer, keyboard, etc.). */
+    disable(): Promise<void>;
+    /** Re-enables user interaction after a call to `disable()`. */
+    enable(): Promise<void>;
+    /** Deletes the currently selected objects from the canvas. */
+    delete(): Promise<void>;
+    /** Copies the currently selected objects to the internal clipboard. */
+    copy(): Promise<void>;
+    /** Cuts the currently selected objects to the internal clipboard (deletes them from the canvas). */
+    cut(): 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>;
+    /**
+     * 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 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 front of the z-order.
+     * @param object - The object to move. If omitted, applies to the current selection.
+     */
+    bringToFront(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>;
+    /**
+     * Aligns the currently selected objects according to the specified alignment.
+     * @param alignment - The alignment direction (e.g., `CenterHorizontal`, `StartVertical`).
+     */
+    alignObjects(alignment: KritzelAlignment): Promise<void>;
+    /** Groups the currently selected objects into a single selection group. */
+    group(): Promise<void>;
+    /** Ungroups the currently selected group back into individual objects. */
+    ungroup(): Promise<void>;
+    /** Undoes the last action. */
+    undo(): Promise<void>;
+    /** Redoes the last undone action. */
+    redo(): Promise<void>;
+    /** Hides the context menu and resets any associated selection state. */
+    hideContextMenu(): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * 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 on the canvas across all layers. */
+    getAllObjects<T extends KritzelBaseObject>(): Promise<T[]>;
+    /**
+     * 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 total number of objects on the canvas. */
+    getObjectsTotalCount(): Promise<number>;
+    /**
+     * 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[]>;
+    /**
+     * 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>;
+    /**
+     * 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[]>;
+    /** Returns the currently selected objects. Returns an empty array if nothing is selected. */
+    getSelectedObjects(): Promise<KritzelBaseObject<any>[]>;
+    /** Returns all registered keyboard shortcuts (without action/condition) for display in a help UI. */
+    getDisplayableShortcuts(): Promise<Omit<KritzelShortcut, 'action' | 'condition'>[]>;
+    /**
+     * Programmatically selects the given objects. Switches to the selection tool automatically.
+     * @param objects - The objects to select.
+     */
+    selectObjects(objects: KritzelBaseObject[]): Promise<void>;
+    /** Selects all objects currently visible in the viewport. Switches to the selection tool automatically. */
+    selectAllObjectsInViewport(): Promise<void>;
+    /** Deselects all currently selected objects. */
+    clearSelection(): Promise<void>;
+    /**
+     * 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 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>;
+    /**
+     * 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>;
+    /**
+     * 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 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Returns the current viewport state including position, scale, and dimensions.
+     * @returns The current viewport state.
+     */
+    getViewport(): Promise<KritzelViewportState>;
+    /**
+     * 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;
+    }>;
+    /**
+     * 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;
+    }>;
+    /** Returns all objects currently visible within the viewport bounds. */
+    getObjectsInViewport(): Promise<KritzelBaseObject[]>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Returns export formats supported by the currently selected object.
+     * Only returns formats when exactly one object is selected.
+     */
+    getSelectedObjectSupportedExportFormats(): Promise<KritzelObjectExportFormat[]>;
+    /**
+     * 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>;
+    /**
+     * 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 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    private getWorkspaceExportMode;
+    private collectPortableAssets;
+    private restorePortableAssets;
+    private blobToDataUrl;
+    private dataUrlToBlob;
+    private triggerDataUrlDownload;
+    private getSingleSelectedExportableObject;
+    private getObjectExportContext;
+    private getObjectAsSvgMarkup;
+    private svgMarkupToDataUrl;
+    private svgMarkupToPngDataUrl;
+    private getImportedWorkspaceName;
+    private getImportedWorkspaceViewport;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /** Cancels an active file picker opened by importFromFile. */
+    cancelImportFromFile(): 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Deletes a workspace and emits a `workspacesChange` event.
+     * @param workspace - The workspace to delete.
+     */
+    deleteWorkspace(workspace: KritzelWorkspace): Promise<void>;
+    /** Returns all available workspaces. */
+    getWorkspaces(): Promise<KritzelWorkspace[]>;
+    /** Returns the currently active workspace. */
+    getActiveWorkspace(): Promise<KritzelWorkspace>;
+    /**
+     * Gets whether the active workspace is publicly accessible.
+     * @returns True if the workspace is public, false otherwise
+     */
+    getIsPublic(): Promise<boolean>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Persists the given settings object to localStorage using the namespaced storage key.
+     * @param settings - The settings configuration to persist.
+     */
+    saveSettings(settings: KritzelSettingsConfig): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * Registers additional locale definitions (with optional partial term overrides).
+     * @param locales - The locale definitions to register.
+     */
+    registerLocales(locales: KritzelLocale[]): 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>;
+    /**
+     * 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>;
+    /**
+     * Gets the currently active locale code.
+     */
+    getLocale(): Promise<LocaleCode>;
+    /**
+     * Gets the list of available locale codes (built-in and registered).
+     */
+    getAvailableLocales(): Promise<LocaleCode[]>;
+    /**
+     * Gets the list of available locales as `{ code, label }` options for a selector.
+     */
+    getAvailableLocaleOptions(): Promise<{
+        code: LocaleCode;
+        label: string;
+    }[]>;
+    /**
+     * 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>;
+    /**
+     * 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>>>;
+    core: KritzelCore;
+    viewport: KritzelViewport;
+    contextMenuHandler: KritzelContextMenuHandler;
+    keyHandler: KritzelKeyHandler;
+    private _lastHadSelectionGroup;
+    private _isViewportReady;
+    private _isYjsInitialized;
+    private _isAssetStorageInitialized;
+    private _isResolvingActiveWorkspaceId;
+    private _stateChangeListenersRegistered;
+    private _workspaceInitializationPromise;
+    private _workspaceInitializationTargetKey;
+    private _syncInitPromise;
+    private _syncConfigRevision;
+    private _assetStorageConfigRevision;
+    private _hasLoggedUnlicensedWelcomeBanner;
+    private _previousVisibleDynamicObjects;
+    private _revealedImageKeys;
+    private _sceneBootstrapOpacity;
+    private _sceneBootstrapTransitionEnabled;
+    private _sceneBootstrapTransitionTimer;
+    private readonly _defaultUndoState;
+    private setLoadingState;
+    private isNetworkAvailable;
+    private emitContextMenuStateChange;
+    private applyToolConfig;
+    private normalizeToolConfig;
+    private isTextToolConfig;
+    /** Built-in tool classes of this bundle keyed by their tool type. */
+    private static readonly BUILT_IN_TOOL_CLASSES;
+    /**
+     * Resolves a tool class to the internal built-in class when a foreign copy is passed.
+     * Classes from another compiled copy of the library (dual-package hazard, e.g. built-ins
+     * re-exported by a framework wrapper) would otherwise break `instanceof` checks.
+     */
+    private resolveToolClass;
+    get isSelecting(): boolean;
+    get isSelectionActive(): boolean;
+    constructor();
+    disconnectedCallback(): void;
+    componentWillLoad(): void;
+    componentDidLoad(): Promise<void>;
+    private initializeSyncAndWorkspace;
+    /**
+     * Initializes the asset storage layer with the latest config. Mirrors
+     * the in-flight replay logic of {@link doInitializeSyncAndWorkspace} for
+     * `assetStorageConfig` prop updates that arrive while init is running.
+     */
+    private initializeAssetStorage;
+    private logUnlicensedWelcomeBanner;
+    private doInitializeSyncAndWorkspace;
+    private initializeStartupWorkspace;
+    /**
+       * On a cold start the remote workspace list may still be in flight; creating a
+       * fallback workspace before it arrives would pollute the synced app state.
+       */
+    private waitForRemoteAppStateIfEmpty;
+    private resolveStartupWorkspace;
+    private ensureActiveWorkspaceIsVisible;
+    private reconcileProvidedWorkspaces;
+    private isWorkspaceCatalogControlled;
+    private getProvidedWorkspaces;
+    private getVisibleWorkspaces;
+    private findVisibleWorkspace;
+    private syncVisibleWorkspacesToState;
+    private hasWorkspaceMetadataChanged;
+    private cloneWorkspaceMetadata;
+    private tryResolveActiveWorkspaceFromId;
+    private switchToWorkspaceById;
+    private initializeWorkspaceIfNeeded;
+    emitObjectsChange(): void;
+    emitObjectsAdded(objects: KritzelBaseObject<any>[]): void;
+    emitObjectsRemoved(objects: KritzelBaseObject<any>[]): void;
+    emitObjectsUpdated(objects: {
+        object: KritzelBaseObject<any>;
+        changedProperties: string[];
+    }[]): void;
+    emitAwarenessChange(states: Map<number, Record<string, any>>): void;
+    emitObjectsInViewportChange(): void;
+    private _registerStateChangeListeners;
+    private _handleActiveToolChange;
+    private getObjectEffectiveOpacity;
+    private getSelectionHandleCapabilities;
+    private getImageRevealKey;
+    private shouldAnimateImageFirstReveal;
+    render(): any;
+}