@kritzel/engine 0.4.31

package/dist/types/classes/managers/anchor.manager.d.ts

@@ -0,0 +1,513 @@
+import { AnchorIndexEntry, AnchorLinesRenderData, AnchorVisualization, LineAnchor, SnapCandidate, SnapIndicatorRenderData, SnapPreviewCandidate, SnapTarget } from '../../interfaces/anchor.interface';
+import { KritzelCore } from '../core/core.class';
+import { KritzelLine } from '../objects/line.class';
+import { KritzelBaseObject } from '../objects/base-object.class';
+type AnchorClipInfo = {
+    localX: number;
+    localY: number;
+    worldX: number;
+    worldY: number;
+    t?: number;
+};
+/**
+ * Manages anchor connections between line endpoints and other objects.
+ * Maintains a runtime index for efficient reverse lookups and handles
+ * snap detection during line endpoint dragging.
+ */
+export declare class KritzelAnchorManager {
+    private readonly _core;
+    /**
+     * Runtime index mapping objectId to the lines anchored to it.
+     * This is derived from the anchor properties on lines and rebuilt as needed.
+     */
+    private readonly _anchorIndex;
+    /**
+     * Creates a new KritzelAnchorManager instance.
+     * @param core - The KritzelCore instance that provides access to the store and other managers.
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Sets an anchor from a line endpoint to a target object's center.
+     * Updates both the line's anchor property and the internal index.
+     * Prevents anchoring both endpoints of the same line to the same object.
+     *
+     * @param lineId - The unique identifier of the line to anchor.
+     * @param endpoint - Which endpoint of the line to anchor ('start' or 'end').
+     * @param targetObjectId - The unique identifier of the object to anchor to.
+     */
+    setAnchor(lineId: string, endpoint: 'start' | 'end', targetObjectId: string): void;
+    /**
+     * Removes an anchor from a line endpoint.
+     * Updates both the line's anchor property and the internal index.
+     *
+     * @param lineId - The unique identifier of the line.
+     * @param endpoint - Which endpoint's anchor to remove ('start' or 'end').
+     */
+    removeAnchor(lineId: string, endpoint: 'start' | 'end'): void;
+    /**
+     * Gets the anchor for a specific line endpoint.
+     *
+     * @param lineId - The unique identifier of the line.
+     * @param endpoint - Which endpoint to get the anchor for ('start' or 'end').
+     * @returns The LineAnchor object if an anchor exists, null otherwise.
+     */
+    getAnchor(lineId: string, endpoint: 'start' | 'end'): LineAnchor | null;
+    /**
+     * Gets all lines that have an endpoint anchored to the specified object.
+     * Uses the internal anchor index for efficient reverse lookup.
+     *
+     * @param objectId - The unique identifier of the object to query.
+     * @returns An array of AnchorIndexEntry objects containing lineId and endpoint information.
+     */
+    getLinesAnchoredTo(objectId: string): AnchorIndexEntry[];
+    /**
+     * Updates all line endpoints that are anchored to the specified object.
+     * Should be called when an object moves to keep anchored lines in sync.
+     *
+     * @param objectId - The unique identifier of the object that has moved.
+     */
+    updateAnchorsForObject(objectId: string): void;
+    /**
+     * Snaps a line endpoint to an object's center position.
+     * Converts world coordinates to the line's local coordinate system before updating.
+     *
+     * @param line - The KritzelLine object to update.
+     * @param endpoint - Which endpoint to snap ('start' or 'end').
+     * @param targetObjectId - The unique identifier of the target object to snap to.
+     */
+    private snapEndpointToObject;
+    /**
+     * Converts world coordinates to a line's local coordinate system.
+     * Applies inverse rotation and scale transformations to translate
+     * from global canvas coordinates to the line's internal SVG coordinates.
+     *
+     * @param line - The KritzelLine object providing the transformation context.
+     * @param worldX - The X coordinate in world/canvas space.
+     * @param worldY - The Y coordinate in world/canvas space.
+     * @returns An object containing the local x and y coordinates.
+     */
+    private worldToLineLocal;
+    /**
+     * Finds an object that can be snapped to when the cursor is sufficiently close to its center.
+     * Snap is only triggered when the cursor is inside the object's bounds AND within 1/5 of the
+     * shorter side from the center, so snapping activates only as the user approaches the center
+     * and releases quickly as they move away.
+     * Returns null if no suitable snap target is found.
+     *
+     * @param worldX - X coordinate in world space
+     * @param worldY - Y coordinate in world space
+     * @param excludeLineId - ID of the line being edited (to exclude from snap targets)
+     * @param otherEndpointAnchorId - ID of object anchored to the other endpoint (to prevent same-object anchoring)
+     * @param pointerType - The pointer type driving the drag interaction.
+     */
+    findSnapTarget(worldX: number, worldY: number, excludeLineId: string, otherEndpointAnchorId?: string, pointerType?: string): SnapTarget | null;
+    /**
+     * Finds the topmost anchorable object currently containing the dragged endpoint.
+     * Used to drive preview UI before an actual snap engages.
+     */
+    findSnapPreviewTarget(worldX: number, worldY: number, excludeLineId: string, otherEndpointAnchorId?: string): SnapTarget | null;
+    private findBestSnapTarget;
+    private getSnapRadius;
+    /**
+     * Sets the current snap candidate for visual feedback during line endpoint dragging.
+     * Updates the store state and triggers a rerender to show the snap indicator.
+     *
+     * @param candidate - The SnapCandidate object containing snap target info, or null to clear.
+     */
+    setSnapCandidate(candidate: SnapCandidate | null): void;
+    /**
+     * Sets the current snap preview candidate for early visual feedback during line dragging.
+     * Preview state must remain separate from active snap state so line clipping and anchor
+     * commit semantics only react to actual snaps.
+     *
+     * @param candidate - The preview candidate object, or null to clear.
+     */
+    setSnapPreviewCandidate(candidate: SnapPreviewCandidate | null): void;
+    /**
+     * Gets the current snap candidate from the store state.
+     *
+     * @returns The current SnapCandidate object if one exists, null otherwise.
+     */
+    getSnapCandidate(): SnapCandidate | null;
+    /**
+     * Gets the current snap preview candidate from the store state.
+     *
+     * @returns The current preview candidate if one exists, null otherwise.
+     */
+    getSnapPreviewCandidate(): SnapPreviewCandidate | null;
+    /**
+     * Clears the snap candidate from the store state and triggers a rerender.
+     * Should be called when snapping is cancelled or completed.
+     */
+    clearSnapCandidate(): void;
+    /**
+     * Clears the snap preview candidate from the store state and triggers a rerender.
+     */
+    clearSnapPreviewCandidate(): void;
+    /**
+     * Gets render data for anchor lines visualization.
+     * Computes stroke widths, dash patterns, and indicator sizes scaled to the current viewport.
+     *
+     * @returns AnchorLinesRenderData object containing visualization parameters and anchor
+     *          visualization data for both endpoints, or null if there's no selected line
+     *          with anchors.
+     */
+    getAnchorLinesRenderData(): AnchorLinesRenderData | null;
+    /**
+     * Gets render data for snap indicator visualization.
+     * Computes all visual parameters needed to render the snap preview including
+     * indicator radius, stroke widths, dash patterns, and arrow geometry.
+     *
+     * @returns SnapIndicatorRenderData object containing all visualization parameters,
+     *          or null if there's no active snap candidate.
+     */
+    getSnapIndicatorRenderData(): SnapIndicatorRenderData | null;
+    /**
+     * Gets render data for snap preview visualization.
+     *
+     * @returns SnapIndicatorRenderData for the active preview candidate, or null if none exists.
+     */
+    getSnapPreviewRenderData(): SnapIndicatorRenderData | null;
+    private getIndicatorRenderDataForCandidate;
+    /**
+     * Handles cleanup when an object is deleted from the canvas.
+     * Detaches all lines that were anchored to the deleted object and
+     * removes the object from the internal anchor index.
+     *
+     * @param objectId - The unique identifier of the deleted object.
+     */
+    handleObjectDeleted(objectId: string): void;
+    /**
+     * Handles cleanup when a line is deleted from the canvas.
+     * Removes all anchor index entries for the deleted line.
+     *
+     * @param lineId - The unique identifier of the deleted line.
+     */
+    handleLineDeleted(lineId: string): void;
+    /**
+     * Rebuilds the anchor index from all lines in the object map.
+     * Iterates through all KritzelLine objects and indexes their anchor connections.
+     * Should be called after loading/deserializing objects or when the index may be stale.
+     */
+    rebuildIndex(): void;
+    /**
+     * Adds an entry to the anchor index.
+     * Creates a new Set for the object if it doesn't exist in the index.
+     * Prevents duplicate entries by checking for existing matches.
+     *
+     * @param objectId - The unique identifier of the anchored-to object.
+     * @param lineId - The unique identifier of the line with the anchor.
+     * @param endpoint - Which endpoint of the line is anchored ('start' or 'end').
+     */
+    private addToIndex;
+    /**
+     * Removes an entry from the anchor index.
+     * Cleans up empty Sets from the index to prevent memory leaks.
+     *
+     * @param objectId - The unique identifier of the anchored-to object.
+     * @param lineId - The unique identifier of the line with the anchor.
+     * @param endpoint - Which endpoint of the line is anchored ('start' or 'end').
+     */
+    private removeFromIndex;
+    /**
+     * Gets a KritzelLine object by its unique identifier.
+     *
+     * @param lineId - The unique identifier of the line to retrieve.
+     * @returns The KritzelLine object if found and is a line, null otherwise.
+     */
+    private getLineById;
+    /**
+     * Gets any KritzelBaseObject by its unique identifier.
+     *
+     * @param objectId - The unique identifier of the object to retrieve.
+     * @returns The KritzelBaseObject if found, null otherwise.
+     */
+    private getObjectById;
+    /**
+     * Finds the target object that a line endpoint is anchored to.
+     * Searches among all non-selection objects in the store.
+     *
+     * @param line - The KritzelLine object to check.
+     * @param endpoint - Which endpoint to check ('start' or 'end').
+     * @returns The target KritzelBaseObject if the anchor exists and target is found, null otherwise.
+     */
+    findAnchorTarget(line: KritzelLine, endpoint: 'start' | 'end'): KritzelBaseObject<Element> | null;
+    /**
+     * Computes anchor visualization data for a specific endpoint of a line with anchors.
+     * Calculates edge intersection points for rendering dashed lines from edge to center.
+     *
+     * @param line - The KritzelLine object to compute visualization for.
+     * @param endpoint - Which endpoint to compute visualization for ('start' or 'end').
+     * @returns AnchorVisualization object containing edge and center coordinates plus
+     *          optional path data for curved lines, or null if no anchor exists.
+     */
+    computeAnchorVisualization(line: KritzelLine, endpoint: 'start' | 'end'): AnchorVisualization | null;
+    /**
+     * Computes a clipped line path that stops at anchor edges instead of going to anchor centers.
+     * When arrows are present on anchored ends, the line is shortened so the arrow tip appears at the edge.
+     * Handles both straight lines and curved (quadratic Bezier) lines.
+     *
+     * @param line - The KritzelLine object to compute the clipped path for.
+     * @param offsetByViewBox - If true, subtracts line.x and line.y from coordinates (for selection UI).
+     * @returns The SVG path 'd' attribute string, or the original path if no clipping is needed.
+     */
+    computeClippedLinePath(line: KritzelLine, offsetByViewBox?: boolean): string;
+    /**
+     * Computes anchor clipping information for a line endpoint connected to a target object.
+     * Dispatches to either curved or straight line computation based on line type.
+     *
+     * @param line - The KritzelLine object.
+     * @param endpoint - Which endpoint to compute clip info for ('start' or 'end').
+     * @param targetObject - The object the line is anchored to.
+     * @returns AnchorClipInfo containing local and world coordinates of the clip point,
+     *          plus parameter t for curved lines, or null if computation fails.
+     */
+    computeAnchorClipInfo(line: KritzelLine, endpoint: 'start' | 'end', targetObject: KritzelBaseObject<Element>): AnchorClipInfo | null;
+    /**
+     * Computes clip information for a straight line anchored to a target object.
+     * Uses ray-casting from the opposite endpoint through the target's edge.
+     *
+     * @param line - The KritzelLine object (must be a straight line, no control point).
+     * @param endpoint - Which endpoint is anchored ('start' or 'end').
+     * @param targetObject - The object the line is anchored to.
+     * @returns AnchorClipInfo with intersection coordinates and parameter t, or null if no intersection.
+     */
+    private computeStraightClipInfo;
+    /**
+     * Computes clip information for a curved (quadratic Bezier) line anchored to a target object.
+     * Samples along the curve to find where it exits the target object's bounds.
+     *
+     * @param line - The KritzelLine object (must have controlX and controlY defined).
+     * @param endpoint - Which endpoint is anchored ('start' or 'end').
+     * @param targetObject - The object the line is anchored to.
+     * @returns AnchorClipInfo with intersection coordinates and parameter t, or null if no intersection.
+     */
+    private computeCurvedClipInfo;
+    /**
+     * Finds the point where a curved line exits a polygon boundary.
+     * Samples along the curve from the anchored endpoint outward, detecting
+     * the transition from inside to outside the polygon, then refines the result.
+     *
+     * @param line - The KritzelLine object (curved line with control point).
+     * @param endpoint - Which endpoint is anchored inside the polygon ('start' or 'end').
+     * @param polygonPoints - Array of points defining the polygon boundary.
+     * @returns AnchorClipInfo with the exit point coordinates and parameter t, or null if no exit found.
+     */
+    private findCurveExitPoint;
+    /**
+     * Finds the exit point for a curved line going to a Path object.
+     * Uses distance-to-stroke sampling instead of polygon containment
+     * to detect when the line exits the path's stroke width boundary.
+     *
+     * @param line - The KritzelLine object (curved line with control point).
+     * @param endpoint - Which endpoint is anchored to the path ('start' or 'end').
+     * @param path - The KritzelPath object the line is anchored to.
+     * @returns AnchorClipInfo with the exit point coordinates and parameter t, or null if no exit found.
+     */
+    private findCurveExitPointForPath;
+    /**
+     * Refines the curve exit parameter for a Path object using binary search.
+     * Narrows down the exact parameter t where the curve exits the path's stroke.
+     *
+     * @param line - The KritzelLine object being evaluated.
+     * @param pathPoints - Array of adjusted path points [[x, y], ...].
+     * @param halfStroke - Half of the path's stroke width for distance checks.
+     * @param insideT - Parameter t known to be inside the stroke.
+     * @param outsideT - Parameter t known to be outside the stroke.
+     * @returns The refined parameter t at the stroke boundary.
+     */
+    private refineCurveExitParameterForPath;
+    /**
+     * Gets the adjusted world-space points for a Path object.
+     * Wrapper that delegates to computePathAdjustedPoints.
+     *
+     * @param path - The KritzelPath object to get points for.
+     * @returns Array of [x, y] coordinate pairs in world space.
+     */
+    private getPathAdjustedPoints;
+    /**
+     * Computes world-space adjusted points for a Path object.
+     * Applies rotation and scale transformations to convert the path's
+     * internal points to world coordinates.
+     *
+     * @param path - The KritzelPath object to compute points for.
+     * @returns Array of [x, y] coordinate pairs in world space, or empty array if path has no points.
+     */
+    private computePathAdjustedPoints;
+    /**
+     * Checks if a point is within the stroke width of a Path.
+     * Tests distance from the point to each segment of the path.
+     *
+     * @param x - X coordinate in world space.
+     * @param y - Y coordinate in world space.
+     * @param pathPoints - Array of [x, y] coordinate pairs defining the path.
+     * @param halfStroke - Half of the stroke width (the distance threshold).
+     * @returns True if the point is within halfStroke distance of any path segment.
+     */
+    private isPointInPathStroke;
+    /**
+     * Calculates the shortest distance from a point to a line segment.
+     * Uses projection to find the nearest point on the segment, clamped to segment bounds.
+     *
+     * @param px - X coordinate of the point.
+     * @param py - Y coordinate of the point.
+     * @param x1 - X coordinate of segment start.
+     * @param y1 - Y coordinate of segment start.
+     * @param x2 - X coordinate of segment end.
+     * @param y2 - Y coordinate of segment end.
+     * @returns The distance from the point to the nearest point on the segment.
+     */
+    private pointToSegmentDistance;
+    /**
+     * Refines the curve exit parameter using binary search.
+     * Narrows down the exact parameter t where the curve exits a polygon.
+     *
+     * @param line - The KritzelLine object being evaluated.
+     * @param polygonPoints - Array of points defining the polygon boundary.
+     * @param insideT - Parameter t known to be inside the polygon.
+     * @param outsideT - Parameter t known to be outside the polygon.
+     * @returns The refined parameter t at the polygon boundary.
+     */
+    private refineCurveExitParameter;
+    /**
+     * Approximates the curve parameter t for a given world point by sampling.
+     * Finds the t value that produces a point closest to the target.
+     *
+     * @param line - The KritzelLine object to evaluate.
+     * @param target - The target point with x and y coordinates in world space.
+     * @returns The parameter t (0 to 1) that produces the closest point on the line.
+     */
+    private approximateParameterForWorldPoint;
+    /**
+     * Evaluates a line at parameter t to get both local and world coordinates.
+     * For curved lines, uses quadratic Bezier interpolation.
+     * For straight lines, uses linear interpolation.
+     *
+     * @param line - The KritzelLine object to evaluate.
+     * @param t - The parameter value (0 = start, 1 = end).
+     * @returns Object containing clamped t, local coordinates, and world coordinates.
+     */
+    private evaluateLineAtT;
+    /**
+     * Calculates the derivative speed (magnitude of tangent vector) at parameter t.
+     * For quadratic Bezier: |B'(t)| = |2(1-t)(P1-P0) + 2t(P2-P1)|
+     * For straight lines: constant length of the line segment.
+     *
+     * @param line - The KritzelLine object to evaluate.
+     * @param t - The parameter value (0 to 1).
+     * @returns The magnitude of the derivative (units per parameter unit).
+     */
+    private evaluateDerivativeSpeedAtT;
+    /**
+     * Extracts a sub-segment from a quadratic Bezier curve.
+     * Uses de Casteljau's algorithm to split the curve at the specified t values.
+     *
+     * @param start - The start point of the original curve.
+     * @param control - The control point of the original curve.
+     * @param end - The end point of the original curve.
+     * @param tStart - The parameter value for the new start (0 to 1).
+     * @param tEnd - The parameter value for the new end (0 to 1).
+     * @returns A new QuadraticSegment representing the sub-curve from tStart to tEnd.
+     */
+    private extractQuadraticSegment;
+    /**
+     * Splits a quadratic Bezier segment at parameter t using de Casteljau's algorithm.
+     *
+     * @param segment - The original QuadraticSegment to split.
+     * @param t - The parameter value to split at (0 to 1).
+     * @returns An object containing left and right QuadraticSegments.
+     */
+    private splitQuadraticSegment;
+    /**
+     * Linearly interpolates between two points.
+     *
+     * @param a - The start point.
+     * @param b - The end point.
+     * @param t - The interpolation factor (0 = a, 1 = b).
+     * @returns A new QuadraticPoint at the interpolated position.
+     */
+    private lerpPoint;
+    /**
+     * Builds an SVG path for the anchor visualization from clip point to target center.
+     * For straight lines, returns a simple line path. For curved lines, extracts and
+     * transforms the appropriate Bezier segment.
+     *
+     * @param line - The KritzelLine object.
+     * @param endpoint - Which endpoint is anchored ('start' or 'end').
+     * @param clipInfo - The computed clip information including coordinates and parameter t.
+     * @param targetObject - The target object the line is anchored to.
+     * @returns SVG path 'd' attribute string, or null if path cannot be built.
+     */
+    private buildAnchorPath;
+    /**
+     * Builds an SVG quadratic Bezier path in world coordinates from a segment.
+     * Applies line transformations to convert local segment coordinates to world space.
+     *
+     * @param line - The KritzelLine providing transformation context.
+     * @param segment - The QuadraticSegment to convert to a path.
+     * @param reverse - If true, draws the path from end to start.
+     * @returns SVG path 'd' attribute string with M and Q commands.
+     */
+    private buildWorldQuadraticPath;
+    /**
+     * Converts a KritzelPolygon to an array of corner points.
+     *
+     * @param polygon - The KritzelPolygon with topLeft, topRight, bottomRight, bottomLeft corners.
+     * @returns Array of KritzelPoint in clockwise order starting from topLeft.
+     */
+    private getPolygonPoints;
+    /**
+     * Gets the custom clip polygon for an object if it has one.
+     * Used for non-rectangular shapes like ellipses and triangles that need
+     * special edge detection instead of using the default bounding box.
+     *
+     * @param object - The object to check for a custom clip polygon.
+     * @returns Array of KritzelPoint defining the clip boundary, or null for default behavior.
+     */
+    private getClipPolygonForObject;
+    /**
+     * Gets the clip point for a Path object by finding the stroke edge intersection.
+     * Path objects don't use polygon-based clipping; they use distance-to-stroke calculations.
+     *
+     * @param object - The object to check (only processes KritzelPath objects).
+     * @param outsidePoint - A reference point outside the path to cast a ray from.
+     * @returns The intersection point on the path's stroke edge, or null if not a path or no intersection.
+     */
+    private getPathClipPoint;
+    /**
+     * Converts local line coordinates to world coordinates.
+     * Applies the line's rotation, scale, and translation transformations
+     * to convert from internal SVG coordinates to canvas world space.
+     *
+     * @param line - The KritzelLine providing transformation context.
+     * @param localX - X coordinate in the line's local SVG space.
+     * @param localY - Y coordinate in the line's local SVG space.
+     * @returns Object with x and y coordinates in world space.
+     */
+    private lineLocalToWorld;
+    /**
+     * Converts world coordinates to line's local SVG coordinates.
+     * Applies inverse transformations (scale, rotation, translation) to convert
+     * from canvas world space to the line's internal SVG coordinate system.
+     *
+     * @param line - The KritzelLine providing transformation context.
+     * @param worldX - X coordinate in world/canvas space.
+     * @param worldY - Y coordinate in world/canvas space.
+     * @returns Object with x and y coordinates in the line's local SVG space.
+     */
+    private lineWorldToLocal;
+    private getSafeScale;
+    private areFiniteNumbers;
+    private isFiniteAnchorVisualization;
+    private isFinitePathData;
+    /**
+     * Checks if an object can be used as an anchor target.
+     * Excludes selection-related objects (SelectionBox, SelectionGroup) and
+     * line objects (lines cannot anchor to other lines).
+     *
+     * @param object - The object to check for anchorability.
+     * @returns True if the object can be anchored to, false otherwise.
+     */
+    private isAnchorable;
+}
+export {};

package/dist/types/classes/managers/browser-permission.manager.d.ts

@@ -0,0 +1,41 @@
+import { KritzelCore } from '../core/core.class';
+type BrowserPermissionHandler = () => Promise<PermissionState> | PermissionState;
+/**
+ * Manages browser permission checks and prompts for a core instance.
+ *
+ * Permission-specific prompt logic is routed through a handler registry so new
+ * permissions can be added without changing the core control flow.
+ */
+export declare class KritzelBrowserPermissionManager {
+    private readonly _isFirefox;
+    private readonly _isSafari;
+    private readonly _requestHandlers;
+    /**
+     * Creates a new KritzelBrowserPermissionManager instance.
+     * @param core - The KritzelCore instance this manager belongs to
+     */
+    constructor(_core: KritzelCore);
+    /**
+     * Registers a custom request handler for a browser permission name.
+     * Existing handlers are replaced, which makes the registry easy to extend.
+     *
+     * @param permissionName - The browser permission name to handle
+     * @param handler - The request implementation for that permission
+     */
+    registerRequestPermissionHandler(permissionName: string, handler: BrowserPermissionHandler): void;
+    /**
+     * Checks the current state for a browser permission via the Permissions API.
+     *
+     * @param permissionName - The browser permission name to inspect
+     */
+    checkPermission(permissionName: string): Promise<PermissionState>;
+    /**
+     * Requests a browser permission using the registered handler for the given
+     * permission name, then falls back to a permission check when no handler is
+     * registered.
+     *
+     * @param permissionName - The browser permission name to request
+     */
+    requestPermission(permissionName: string): Promise<PermissionState>;
+}
+export {};

package/dist/types/classes/managers/clipboard.manager.d.ts

@@ -0,0 +1,71 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelClipboardPayload } from './clipboard.types';
+export type { PasteIntent } from './clipboard.types';
+/**
+ * Manages clipboard operations (copy/cut/paste) for a core instance.
+ *
+ * The system clipboard is the preferred source of truth: copy serializes the current
+ * selection into a Kritzel payload, paste reads + revives it.
+ *
+ * A copy also mirrors the payload into an in-memory session buffer. On platforms where
+ * eventless programmatic clipboard access is unavailable (notably iOS Safari, where the
+ * context menu triggers copy/paste without a native ClipboardEvent), the session buffer
+ * is used as the fallback source so internal object copy/paste keeps working.
+ */
+export declare class KritzelClipboardManager {
+    private readonly _core;
+    private readonly _pasteIntentRegistry;
+    /**
+     * In-memory mirror of the most recent copy payload. Acts as the fallback clipboard
+     * source when the system clipboard cannot be read programmatically (e.g. iOS Safari
+     * context-menu paste). Reset is not required; a new copy overwrites it.
+     */
+    private _sessionClipboardPayload;
+    /**
+     * In-memory cascade offset (world units) applied to successive pastes of the same
+     * clipboard content so they don't stack exactly on top of each other. Reset on copy/cut.
+     */
+    private _pasteOffset;
+    constructor(core: KritzelCore);
+    /**
+     * The most recent copy payload mirrored in memory, used as a fallback clipboard
+     * source when the system clipboard cannot be read programmatically.
+     */
+    get sessionClipboardPayload(): KritzelClipboardPayload | null;
+    /**
+     * Serializes an object for the clipboard payload. Groups additionally embed their
+     * (recursively serialized) children under `__children__` so the payload is self-contained.
+     */
+    private serializeForClipboard;
+    private serializeClipboardPayload;
+    private writeBrowserClipboardPayload;
+    /**
+     * Revives a single serialized clipboard object (and its embedded group children).
+     * IDs are NOT regenerated here; see regenerateIdsAndRemapAnchors.
+     */
+    private reviveClipboardObject;
+    /**
+     * Assigns fresh unique IDs to every revived object (including nested group children),
+     * keeping group.childIds in sync and remapping line anchors that reference copied
+     * siblings to their new IDs. Anchors pointing at objects outside the pasted set are
+     * left untouched so they stay connected to the existing object.
+     */
+    private regenerateIdsAndRemapAnchors;
+    /**
+     * Copies currently selected objects into internal clipboard state.
+     */
+    copy(event?: ClipboardEvent): void;
+    /**
+     * Cuts currently selected objects (copy then delete).
+     */
+    cut(event?: ClipboardEvent): void;
+    private materializeKritzelObjects;
+    private materializeImageFiles;
+    private prepareImageFile;
+    private materializePlainText;
+    /**
+     * Pastes objects from clipboard with optional explicit world coordinates.
+     */
+    paste(x?: number, y?: number, event?: ClipboardEvent): Promise<void>;
+    private insertMaterializedObjects;
+}

package/dist/types/classes/managers/clipboard.types.d.ts

@@ -0,0 +1,23 @@
+export declare const CLIPBOARD_PAYLOAD_PREFIX = "kritzel-clipboard/v1:";
+export interface SerializedClipboardObject {
+    [key: string]: any;
+    __class__?: string;
+    __children__?: SerializedClipboardObject[];
+}
+export interface KritzelClipboardPayload {
+    version: 1;
+    sourceWorkspaceId?: string;
+    objects: SerializedClipboardObject[];
+}
+export type PasteIntent = {
+    type: 'kritzel_objects';
+    payload: KritzelClipboardPayload;
+} | {
+    type: 'image_files';
+    files: File[];
+} | {
+    type: 'plain_text';
+    text: string;
+} | {
+    type: 'unknown';
+};