@kritzel/engine 0.4.31

package/dist/types/classes/objects/base-object.class.d.ts

@@ -0,0 +1,266 @@
+import { KritzelBoundingBox } from '../../interfaces/bounding-box.interface';
+import { KritzelObject } from '../../interfaces/object.interface';
+import { KritzelPolygon } from '../../interfaces/polygon.interface';
+import { KritzelSerializable } from '../../interfaces/serializable.interface';
+import { KritzelCore } from '../core/core.class';
+import { KritzelClonable } from '../../interfaces/clonable.interface';
+import { ThemeAwareColor } from '../../constants/color-palette.constants';
+/**
+ * Base class for all objects that can be rendered on the Kritzel canvas.
+ * Provides common functionality for positioning, transformation, hit testing,
+ * serialization, and lifecycle management.
+ * @template T - The type of the underlying DOM element (HTMLElement or SVGElement)
+ */
+export declare class KritzelBaseObject<T extends Element = HTMLElement | SVGElement> implements KritzelObject<T>, KritzelSerializable, KritzelClonable<KritzelBaseObject<T>> {
+    __class__: string;
+    _core: KritzelCore;
+    _elementRef: T;
+    id: string;
+    workspaceId: string;
+    x: number;
+    y: number;
+    translateX: number;
+    translateY: number;
+    height: number;
+    width: number;
+    backgroundColor?: ThemeAwareColor;
+    borderColor?: ThemeAwareColor;
+    borderWidth: number;
+    opacity: number;
+    padding: number;
+    scale?: number;
+    resizing: boolean;
+    rotation: number;
+    markedForRemoval: boolean;
+    zIndex: number;
+    userId?: string;
+    isVisible: boolean;
+    isSelected: boolean;
+    isHovered: boolean;
+    isMounted: boolean;
+    isEditable: boolean;
+    isInteractive: boolean;
+    isResizable: boolean;
+    isRotatable: boolean;
+    /**
+     * Gets the total width of the object including padding.
+     * @returns The width plus double the padding value
+     */
+    get totalWidth(): number;
+    /**
+     * Gets the total height of the object including padding.
+     * @returns The height plus double the padding value
+     */
+    get totalHeight(): number;
+    /**
+     * Sets the underlying DOM element reference for this object.
+     * @param element - The DOM element to associate with this object
+     */
+    set elementRef(element: T);
+    /**
+     * Gets the underlying DOM element reference for this object.
+     * @returns The associated DOM element
+     */
+    get elementRef(): T;
+    /**
+     * Gets the axis-aligned bounding box of the object without rotation.
+     * @returns The bounding box with position, scale, and dimensions
+     */
+    get boundingBox(): KritzelBoundingBox;
+    /**
+     * Gets the axis-aligned bounding box that encompasses the rotated object.
+     * Calculates the smallest rectangle that contains all four rotated corners.
+     * @returns The bounding box accounting for rotation
+     */
+    get rotatedBoundingBox(): KritzelBoundingBox;
+    /**
+     * Gets the four corners of the object as a polygon, accounting for rotation.
+     * Uses optimized trigonometric calculations with precomputed cos/sin values.
+     * @returns A polygon with topLeft, topRight, bottomRight, and bottomLeft coordinates
+     */
+    get rotatedPolygon(): KritzelPolygon;
+    /**
+     * Gets the minimum X coordinate among all rotated corners.
+     * @returns The leftmost X coordinate of the rotated object
+     */
+    get minXRotated(): number;
+    /**
+     * Gets the minimum Y coordinate among all rotated corners.
+     * @returns The topmost Y coordinate of the rotated object
+     */
+    get minYRotated(): number;
+    /**
+     * Gets the maximum X coordinate among all rotated corners.
+     * @returns The rightmost X coordinate of the rotated object
+     */
+    get maxXRotated(): number;
+    /**
+     * Gets the maximum Y coordinate among all rotated corners.
+     * @returns The bottommost Y coordinate of the rotated object
+     */
+    get maxYRotated(): number;
+    /**
+     * Gets the CSS transformation matrix string for positioning and scaling.
+     * @returns A CSS matrix() function string combining scale and translation
+     */
+    get transformationMatrix(): string;
+    /**
+     * Gets the rotation angle converted from radians to degrees.
+     * @returns The rotation angle in degrees
+     */
+    get rotationDegrees(): number;
+    /**
+     * Gets the X coordinate of the object's center point.
+     * @returns The center X position in world coordinates
+     */
+    get centerX(): number;
+    /**
+     * Gets the Y coordinate of the object's center point.
+     * @returns The center Y position in world coordinates
+     */
+    get centerY(): number;
+    /**
+     * Creates a new KritzelBaseObject instance with a generated unique ID.
+     */
+    constructor();
+    /**
+     * Factory method to create a new KritzelBaseObject with core context.
+     * Automatically assigns the current z-index and active workspace ID.
+     * @param core - The KritzelCore instance providing context and state
+     * @returns A new KritzelBaseObject instance configured with core context
+     */
+    static create(core: KritzelCore): KritzelBaseObject<Element>;
+    /**
+     * Mounts the object to a DOM element. Only executes once; subsequent calls are ignored.
+     * Sets the element reference and marks the object as mounted.
+     * @param element - The DOM element to mount this object to
+     */
+    mount(element: T): void;
+    /**
+     * Generates a unique identifier for the object.
+     * @returns A UUID string
+     */
+    generateId(): string;
+    /**
+     * Checks whether the object is currently visible within the viewport.
+     * Objects smaller than 0.5 square pixels (when scaled) are considered invisible.
+     * Uses the rotated bounding box for accurate intersection testing.
+     * @returns True if the object intersects with the visible viewport area
+     */
+    isInViewport(): boolean;
+    /**
+     * Moves the object to the center of the current viewport.
+     * Calculates the offset needed to align the object's center with the viewport's center.
+     */
+    centerInViewport(): void;
+    /**
+     * Notifies the store that this object has been updated.
+     * Triggers a re-render of the object in the canvas.
+     */
+    update(): void;
+    /**
+     * Moves the object based on the delta between start and end coordinates.
+     * The movement is scaled according to the current viewport scale.
+     * @param startX - The starting X coordinate in screen space
+     * @param startY - The starting Y coordinate in screen space
+     * @param endX - The ending X coordinate in screen space
+     * @param endY - The ending Y coordinate in screen space
+     */
+    move(startX: number, startY: number, endX: number, endY: number): void;
+    /**
+     * Resizes the object to new dimensions and position.
+     * Ignores resize requests that would make the object smaller than 1x1 pixels.
+     * Also updates any lines anchored to this object after resizing.
+     * @param x - The new X position (translateX)
+     * @param y - The new Y position (translateY)
+     * @param width - The new width (must be > 1)
+     * @param height - The new height (must be > 1)
+     */
+    resize(x: number, y: number, width: number, height: number): void;
+    /**
+     * Sets the rotation angle of the object.
+     * @param value - The rotation angle in radians
+     */
+    rotate(value: number): void;
+    /**
+     * Creates a shallow clone of this object with the same ID.
+     * The clone shares the same prototype and copies all properties.
+     * @returns A new instance with identical properties including the same ID
+     */
+    clone(): KritzelBaseObject<T>;
+    /**
+     * Creates a copy of this object with a new unique ID.
+     * Unlike clone(), this creates an independent object suitable for duplication.
+     * The copied object is not mounted by default.
+     * @returns A new instance with copied properties and a new unique ID
+     */
+    copy(): KritzelBaseObject<T>;
+    /**
+     * Serializes the object to a plain JavaScript object for persistence.
+     * Excludes internal references (_core, _elementRef) and computed properties.
+     * Subclasses should override to handle domain-specific serialization (e.g., HTML elements).
+     * @returns A serializable object containing all persistent properties
+     */
+    serialize(): any;
+    /**
+     * Restores the object's state from a serialized plain object.
+     * Merges all properties from the input object into this instance.
+     * @template T - The expected return type
+     * @param object - The serialized object data to restore from
+     * @returns This instance cast to type T
+     */
+    deserialize<T>(object: any): T;
+    /**
+     * Copies transient (non-persisted) state from a previous local instance
+     * onto this freshly-revived instance. Called when a remote Yjs update
+     * replaces an existing object so that local-only fields (e.g. asset
+     * load state, resolved blob URLs) survive across remote position
+     * updates and don't visually flicker.
+     *
+     * Default implementation is a no-op; subclasses with transient fields
+     * should override.
+     * @param previous - The previous local instance being replaced.
+     */
+    adoptTransientStateFrom(_previous: KritzelBaseObject<any>): void;
+    /**
+     * Type guard to check if this object is of a specific class type.
+     * Compares against the __class__ property.
+     * @template T - The expected class type extending KritzelBaseObject
+     * @param className - The class name to check against
+     * @returns True if this object's __class__ matches the given class name
+     */
+    isClass<T extends KritzelBaseObject>(this: T, className: string): this is T;
+    /**
+     * Handles edit actions on the object. Override in subclasses to implement
+     * custom edit behavior (e.g., entering text edit mode).
+     * @param _event - Optional pointer event that triggered the edit
+     */
+    edit(_event?: PointerEvent): void;
+    /**
+     * Lifecycle hook called after properties are updated via updateObject.
+     * Override in subclasses to perform custom logic when specific properties change.
+     * @param _changedProperties - Array of property names that were changed
+     */
+    onAfterUpdate(_changedProperties: string[]): void;
+    /**
+     * Tests if a point intersects with this object.
+     * Override in subclasses for precise hit detection (e.g., path-based objects).
+     * @param _x - The X coordinate to test in world space
+     * @param _y - The Y coordinate to test in world space
+     * @returns True if the point hits the object (default always returns true)
+     */
+    hitTest(_x: number, _y: number): boolean;
+    /**
+     * Tests if this object's rotated polygon intersects with another polygon.
+     * Useful for lasso selection and collision detection.
+     * @param polygon - The polygon to test intersection against
+     * @returns True if the polygons intersect
+     */
+    hitTestPolygon(polygon: KritzelPolygon): boolean;
+    /**
+     * Updates the object's position and notifies the store.
+     * @param x - The new X position (translateX)
+     * @param y - The new Y position (translateY)
+     */
+    updatePosition(x: number, y: number): void;
+}

package/dist/types/classes/objects/dynamic-object.class.d.ts

@@ -0,0 +1,148 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelBaseObject } from './base-object.class';
+/**
+ * Configuration options for creating a KritzelDynamicObject instance.
+ */
+export interface KritzelDynamicObjectConfig {
+    element?: HTMLElement;
+    rendererKey?: string;
+    rendererData?: unknown;
+    translateX?: number;
+    translateY?: number;
+    rotation?: number;
+    scale?: number;
+    height?: number;
+    width?: number;
+}
+/**
+ * Represents a custom HTML element that can be placed and manipulated on the Kritzel canvas.
+ * Extends KritzelBaseObject to inherit common object functionality like positioning,
+ * scaling, and lifecycle management.
+ */
+export declare class KritzelDynamicObject extends KritzelBaseObject<HTMLElement> {
+    __class__: string;
+    /** The HTML element to be rendered on the canvas. */
+    element: HTMLElement;
+    /**
+     * Optional identifier for a registered renderer (e.g., 'angular-component', 'react-default').
+     * When set, mount() resolves the renderer from a global registry and delegates lifecycle.
+     * If null, falls back to DOM element mounting.
+     */
+    rendererKey: string | null;
+    /**
+     * Custom data payload for the renderer (e.g., Angular component inputs, React props, Vue data).
+     * Only meaningful when rendererKey is set. Captured on unmount and restored on rehydrate.
+     */
+    rendererData?: unknown;
+    /**
+     * Creates a new KritzelDynamicObject instance.
+     * @param config - Optional configuration object for the dynamic object.
+     * @param config.element - The HTML element to wrap.
+     * @param config.translateX - Initial X position offset. Defaults to 0.
+     * @param config.translateY - Initial Y position offset. Defaults to 0.
+     * @param config.scale - Initial scale factor. Defaults to 1.
+     * @param config.height - Initial height in pixels. Defaults to 0.
+     * @param config.width - Initial width in pixels. Defaults to 0.
+     */
+    constructor(config?: KritzelDynamicObjectConfig);
+    /**
+     * Factory method to create a new KritzelDynamicObject with proper core binding.
+     * Generates a unique ID and assigns the element to the active workspace.
+     * @param core - The KritzelCore instance for state management and ID generation.
+     * @param config - Optional configuration object for the dynamic object.
+     * @param config.element - The HTML element to wrap.
+     * @param config.translateX - Initial X position offset.
+     * @param config.translateY - Initial Y position offset.
+     * @param config.scale - Initial scale factor.
+     * @param config.height - Initial height in pixels.
+     * @param config.width - Initial width in pixels.
+     * @returns A new KritzelBaseObject instance bound to the core.
+     */
+    static create(core: KritzelCore, config?: KritzelDynamicObjectConfig): KritzelBaseObject<Element>;
+    /**
+     * Mounts the dynamic object to a container element in the DOM.
+     * If a renderer is registered for this.rendererKey, delegates to the renderer.
+     * Otherwise, uses the standard DOM element mounting fallback.
+     * Skips mounting if already mounted to the same container with content attached.
+     * @param element - The container HTML element to mount this dynamic object into.
+     */
+    mount(element: HTMLElement): void;
+    /**
+     * Updates interactivity state for embedded HTML content.
+     * When disabling interactivity, any focused descendant is blurred so
+     * keyboard input is released immediately.
+     */
+    setIsInteractive(isInteractive: boolean): void;
+    private applyInteractiveState;
+    private blurFocusedDescendant;
+    /**
+     * Returns true when a text-input-like element inside this dynamic object
+     * currently owns focus.
+     */
+    hasFocusedInputElement(): boolean;
+    private getFocusHosts;
+    /**
+     * Returns true when the given host (or, via the flat tree, one of its shadow descendants)
+     * currently contains a focused input-like element.
+     */
+    private hasFocusedInputDescendant;
+    /**
+     * Walks the `:focus` chain from a tree scope, descending into open shadow roots, and returns
+     * the focused element when it is input-like.
+     */
+    private findFocusedInputLikeElement;
+    private matchesFocus;
+    private isInputLikeElement;
+    private isNodeInsideHost;
+    private getDeepActiveElement;
+    /**
+     * Unmounts the dynamic object and performs cleanup.
+     * If a renderer is registered, delegates to renderer.onUnmount and captures returned state.
+     * Otherwise, simply removes from DOM.
+     * Called when object is deleted, viewport culled, or editor is unloading.
+     */
+    unmount(): void;
+    /**
+     * Returns whether the rendered content contains a scrollable element.
+     * Traverses light DOM, open shadow roots, and slotted content so nested
+     * framework components are detected as well.
+     */
+    isElementScrollable(): boolean;
+    /**
+     * Creates a placeholder element when HTML deserialization fails.
+     * Used as fallback to ensure element is always defined.
+     * @returns A div element with placeholder styling
+     */
+    private createPlaceholder;
+    /**
+     * Resizes and repositions the dynamic object on the canvas.
+     * Updates both the internal state and the DOM element's inline styles.
+     * Syncs changes to Yjs for collaborative editing and cross-tab propagation.
+     * @param x - The new X position (translateX) in canvas coordinates.
+     * @param y - The new Y position (translateY) in canvas coordinates.
+     * @param width - The new width in pixels. Must be greater than 1.
+     * @param height - The new height in pixels. Must be greater than 1.
+     */
+    resize(x: number, y: number, width: number, height: number): void;
+    /**
+     * Creates a deep copy of this dynamic object.
+     * The copy receives a new unique ID, is marked as unmounted,
+     * and contains a cloned copy of the underlying HTML element.
+     * @returns A new KritzelDynamicObject instance with copied properties and a cloned DOM element.
+     */
+    copy(): KritzelDynamicObject;
+    /**
+     * Serializes the dynamic object to a plain JavaScript object for persistence.
+     * Stores HTML as a string (safe for JSON/Yjs) and captures dimension metadata.
+     * @returns A serializable object with htmlString and dimension snapshots
+     */
+    serialize(): any;
+    /**
+     * Deserializes the dynamic object from a plain object.
+     * Reconstructs the element from stored HTML string with fallback to placeholder.
+     * @template T - The expected return type
+     * @param object - The serialized object data to restore from
+     * @returns This instance cast to type T
+     */
+    deserialize<T>(object: any): T;
+}

package/dist/types/classes/objects/group.class.d.ts

@@ -0,0 +1,231 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelBaseObject } from './base-object.class';
+import { KritzelPolygon } from '../../interfaces/polygon.interface';
+/**
+ * Configuration options for creating a KritzelGroup instance.
+ */
+export interface KritzelGroupConfig {
+    rotation?: number;
+}
+/**
+ * KritzelGroup represents a permanent grouping of objects that act as a single unit.
+ *
+ * Unlike KritzelSelectionGroup (which is ephemeral and used for temporary multi-selection),
+ * KritzelGroup is persisted and saved with the workspace. Grouped objects move, resize,
+ * rotate, copy, and delete together as one unit.
+ *
+ * Key features:
+ * - Supports nested groups (groups can contain other groups)
+ * - Clicking any child selects the entire group
+ * - Can be ungrouped to restore children to top-level objects
+ */
+export declare class KritzelGroup extends KritzelBaseObject<HTMLElement> {
+    __class__: string;
+    constructor(config?: KritzelGroupConfig);
+    /**
+     * IDs of child objects within this group.
+     * Children can be any KritzelBaseObject, including other KritzelGroups for nesting.
+     */
+    childIds: string[];
+    /**
+     * Holds child objects that have been added via addChild() before the group
+     * is added to the engine. Once the group is added (and _core is set),
+     * these are flushed into the store and this array is cleared.
+     */
+    _pendingChildren: KritzelBaseObject<any>[];
+    /**
+     * Snapshots of child states for transformation operations (resize, rotate).
+     * Similar pattern to KritzelSelectionGroup.
+     */
+    private unchangedChildSnapshots;
+    private snapshotRotation;
+    private snapshotTranslateX;
+    private snapshotTranslateY;
+    private snapshotTotalWidth;
+    private snapshotTotalHeight;
+    private snapshotScale;
+    /**
+     * Retrieves the actual child objects from the store by their IDs.
+     * Filters out any IDs that no longer exist in the store.
+     * @returns An array of KritzelBaseObject instances representing the group's children.
+     */
+    get children(): KritzelBaseObject<any>[];
+    /**
+     * Returns the number of children in this group.
+     * @returns The count of child IDs stored in this group.
+     */
+    get length(): number;
+    /**
+     * Factory method to create a new empty KritzelGroup with core integration.
+     * Initializes the group with default values and links it to the core store.
+     * @param core - The KritzelCore instance providing access to store and state management.
+     * @returns A new KritzelGroup instance configured with the core context.
+     */
+    static create(core: KritzelCore, config?: {
+        rotation?: number;
+    }): KritzelGroup;
+    /**
+     * Creates a KritzelGroup from an array of existing objects.
+     * The objects are added as children and the group's bounding box is calculated
+     * to encompass all children. Child snapshots are captured for transformation operations.
+     * @param core - The KritzelCore instance providing access to store and state management.
+     * @param objects - An array of KritzelBaseObject instances to group together.
+     * @returns A new KritzelGroup containing the specified objects as children.
+     */
+    static createFromObjects(core: KritzelCore, objects: KritzelBaseObject<any>[]): KritzelGroup;
+    /**
+     * Finds the parent KritzelGroup that contains the given object as a direct child.
+     * Searches through all groups in the store to find one containing the specified object ID.
+     * @param core - The KritzelCore instance providing access to the object store.
+     * @param objectId - The unique identifier of the object to find the parent group for.
+     * @returns The parent KritzelGroup if found, or null if the object is not a child of any group.
+     */
+    static findParentGroup(core: KritzelCore, objectId: string): KritzelGroup | null;
+    /**
+     * Recursively collects the IDs of all descendants of the given group (children,
+     * grandchildren, etc.). Useful for detecting when a selection contains both an
+     * ancestor group and one of its descendants — a configuration that would otherwise
+     * cause the descendant to be transformed twice (once via the ancestor, once directly).
+     * @param group - The group whose descendants should be collected.
+     * @param out - A set that will be populated with all descendant object IDs.
+     */
+    static collectDescendantIds(group: KritzelGroup, out?: Set<string>): Set<string>;
+    /**
+     * Adds a child object to this group.
+     * If the object is already a child, no action is taken.
+     * Automatically refreshes the bounding box and captures child snapshots.
+     * @param object - The KritzelBaseObject instance to add as a child.
+     */
+    addChild(object: KritzelBaseObject<any>): void;
+    /**
+     * Removes a child object from this group by its ID.
+     * If the object is not a child, no action is taken.
+     * Automatically refreshes the bounding box and captures child snapshots.
+     * @param objectId - The unique identifier of the child object to remove.
+     */
+    removeChild(objectId: string): void;
+    /**
+     * Ungroups this group, returning all children to top-level objects.
+     * The group itself should be removed from the store after calling this method.
+     * @returns An array of all child objects that were part of this group.
+     */
+    ungroup(): KritzelBaseObject<any>[];
+    /**
+     * Finalizes the group after children have been positioned (e.g., after paste).
+     * Refreshes the bounding box to encompass all children and captures
+     * child snapshots for subsequent transformation operations.
+     *
+     * Recursively finalizes nested child groups first, so that when a transform
+     * (rotate/resize) cascades through nested groups, every group's snapshots are
+     * aligned with the current visual state. Without this, a nested group's
+     * `snapshotRotation` could be stale, causing the inner group to be offset
+     * relative to its parent during rotation.
+     */
+    finalize(): void;
+    /**
+     * Moves the group and all its children to the center of the viewport.
+     * Overrides the base implementation to ensure children move with the group.
+     */
+    centerInViewport(): void;
+    /**
+     * Recalculates the group's bounding box based on its children.
+     * Handles three cases: empty group (zero dimensions), single child (inherit its bounds),
+     * and multiple children (calculate encompassing bounds with rotation support).
+     * Updates translateX, translateY, width, and height properties.
+     */
+    refreshBoundingBox(): void;
+    /**
+     * Captures snapshots of all child states for transformation operations.
+     * Stores position, rotation, dimensions, and scale for each child.
+     * Also captures the group's current state for relative calculations.
+     */
+    private captureChildSnapshots;
+    /**
+     * Moves the group and all its children by the delta between start and end positions.
+     * Updates are wrapped in a transaction for atomic persistence.
+     * Also updates any lines anchored to child objects.
+     * @param startX - The starting x coordinate in screen space.
+     * @param startY - The starting y coordinate in screen space.
+     * @param endX - The ending x coordinate in screen space.
+     * @param endY - The ending y coordinate in screen space.
+     */
+    move(startX: number, startY: number, endX: number, endY: number): void;
+    /**
+     * Resizes the group and proportionally transforms all children.
+     * Children are scaled and repositioned relative to the group's center,
+     * accounting for rotation. Updates are wrapped in a transaction.
+     * @param x - The new x translation coordinate for the group.
+     * @param y - The new y translation coordinate for the group.
+     * @param width - The new width of the group's content area.
+     * @param height - The new height of the group's content area.
+     */
+    resize(x: number, y: number, width: number, height: number): void;
+    /**
+     * Rotates the group and all its children around the group's center.
+     * Children maintain their relative positions and are individually rotated.
+     * Uses captured snapshots to calculate rotation deltas.
+     * @param value - The new absolute rotation angle in radians.
+     */
+    rotate(value: number): void;
+    /**
+     * Calculates the horizontal offset from the group's center to a child's center
+     * using the captured snapshot values.
+     * @param snapshot - The captured state of the child object.
+     * @returns The x-axis offset from the group center to the child center.
+     */
+    private getOffsetXToCenterFromSnapshot;
+    /**
+     * Calculates the vertical offset from the group's center to a child's center
+     * using the captured snapshot values.
+     * @param snapshot - The captured state of the child object.
+     * @returns The y-axis offset from the group center to the child center.
+     */
+    private getOffsetYToCenterFromSnapshot;
+    /**
+     * Tests if a point lies within any of the group's children.
+     * The group is considered hit if any child passes the hit test.
+     * @param x - The x coordinate to test in world space.
+     * @param y - The y coordinate to test in world space.
+     * @returns True if the point is inside any child, false otherwise.
+     */
+    hitTest(x: number, y: number): boolean;
+    /**
+     * Tests if a polygon intersects with any of the group's children.
+     * Used for lasso selection and area-based hit detection.
+     * @param polygon - The polygon to test intersection against.
+     * @returns True if the polygon intersects any child, false otherwise.
+     */
+    hitTestPolygon(polygon: KritzelPolygon): boolean;
+    /**
+     * Creates a deep copy of this group and all its children.
+     * Children are copied but not added to the store; they are stored
+     * in a temporary _pendingChildren property for paste() to handle.
+     * @returns A new KritzelGroup with copied children and properties.
+     */
+    copy(): KritzelGroup;
+    /**
+     * Serializes the group to a plain object for persistence.
+     * Excludes runtime references (_core, _elementRef, element) and
+     * converts the unchangedChildSnapshots Map to a plain object.
+     * @returns A serializable plain object representation of this group.
+     */
+    serialize(): any;
+    /**
+     * Deserializes a plain object back into this KritzelGroup instance.
+     * Restores the unchangedChildSnapshots Map from the serialized object format.
+     * @param object - The serialized plain object containing group data.
+     * @returns This group instance after deserialization, cast to type T.
+     */
+    deserialize<T>(object: any): T;
+    /**
+     * Persists the current state of this group to the store.
+     * Triggers synchronization with y.js for collaborative editing.
+     */
+    update(): void;
+    /**
+     * Updates the workspace ID for this group and all its children recursively.
+     * Handles nested groups by recursively calling this method on child groups.
+     * @param workspaceId - The new workspace ID to assign to this group and its children.
+     */
+    updateWorkspaceId(workspaceId: string): void;
+}