@snowcone-app/canvas 0.1.0

package/dist/core/GeometryUtils.d.ts

@@ -0,0 +1,247 @@
+import { BoundingBox, Point, ResizeAnchor } from '../types/index.js';
+/**
+ * Calculate position to keep opposite corner fixed during resize
+ * This is the core algorithm that makes corner dragging feel natural
+ *
+ * @param {Object} startData - Transform start state {x, y, width, height}
+ * @param {Object} newDimensions - New dimensions {width, height}
+ * @param {string} activeAnchor - Which corner is being dragged
+ * @param {number} rotation - Rotation in degrees
+ * @returns {Object} New position {x, y}
+ */
+export declare function calculateFixedCornerPosition(startData: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, newDimensions: {
+    width: number;
+    height: number;
+}, activeAnchor: string, rotation: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate rotation handle position
+ * Positioned below the bottom edge, centered horizontally
+ * Distance scales inversely with zoom to maintain consistent screen space distance
+ *
+ * @param {Object} bbox - Bounding box {x, y, width, height}
+ * @param {number} rotation - Rotation in DEGREES (not radians - function converts internally)
+ * @param {Object} rotationAnchor - Point to rotate around {x, y}
+ * @param {number} zoom - Current zoom level (default 1.0)
+ * @returns {Object} Handle position {x, y}
+ *
+ * IMPORTANT: This function expects rotation in DEGREES and converts to radians internally.
+ * Do NOT pass radians to this function or you'll get incorrect positioning.
+ * Example: Pass 30 for 30°, NOT 0.524 radians
+ */
+export declare function calculateRotationHandlePosition(bbox: BoundingBox, rotation: number, rotationAnchor: Point, zoom?: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate all 8 resize handle positions
+ *
+ * @param {Object} bbox - Bounding box {x, y, width, height}
+ * @param {number} rotation - Rotation in degrees
+ * @param {Object} rotationAnchor - Point to rotate around {x, y}
+ * @returns {Object[]} Array of handles with {type, anchor, x, y, cursor}
+ */
+export declare function calculateResizeHandles(bbox: BoundingBox, rotation: number, rotationAnchor: Point): {
+    cursor: string;
+    x: number;
+    y: number;
+    type: string;
+    anchor: ResizeAnchor;
+}[];
+/**
+ * Test if a point is inside a circle
+ */
+export declare function hitTestCircle(px: number, py: number, cx: number, cy: number, radius: number): boolean;
+/**
+ * Test if a point is inside a rotated rectangle
+ */
+export declare function hitTestRect(px: number, py: number, rect: BoundingBox, rotation: number): boolean;
+/**
+ * Measure text width using canvas API
+ * @deprecated Use TextMetrics.measureTextWidth instead
+ */
+export declare function measureTextWidth(text: string, fontSize: number, fontFamily?: string, bold?: boolean, italic?: boolean): number;
+/**
+ * Calculate bounding box center
+ */
+export declare function getBoundingBoxCenter(bbox: BoundingBox): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate angle between two points
+ */
+export declare function calculateAngle(centerX: number, centerY: number, pointX: number, pointY: number): number;
+/**
+ * Rotate a point around a center
+ */
+export declare function rotatePoint(px: number, py: number, cx: number, cy: number, angle: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate distance between two points
+ */
+export declare function distance(x1: number, y1: number, x2: number, y2: number): number;
+/**
+ * Calculate distance from a point to a horizontal line
+ */
+export declare function distanceToHorizontalLine(_px: number, py: number, lineY: number): number;
+/**
+ * Calculate distance from a point to a vertical line
+ */
+export declare function distanceToVerticalLine(px: number, _py: number, lineX: number): number;
+/**
+ * Calculate distance from a point to a line segment
+ * @param {number} px - Point X
+ * @param {number} py - Point Y
+ * @param {number} x1 - Line start X
+ * @param {number} y1 - Line start Y
+ * @param {number} x2 - Line end X
+ * @param {number} y2 - Line end Y
+ * @returns {number} Distance to line segment
+ */
+export declare function distanceToLineSegment(px: number, py: number, x1: number, y1: number, x2: number, y2: number): number;
+/**
+ * Check if two values are within a threshold
+ * Useful for snapping detection
+ */
+export declare function isNear(value1: number, value2: number, threshold: number): boolean;
+/**
+ * Get the correct resize cursor accounting for rotation
+ * @param {string} anchor - Handle anchor position (e.g., 'top-left', 'top', 'right')
+ * @param {number} rotation - Rotation in degrees
+ * @returns {string} CSS cursor value
+ */
+export declare function getRotatedResizeCursor(anchor: string, rotation: number): string;
+/**
+ * Get cursor for a handle based on its world position relative to a center point
+ * @param {number} handleWorldX - Handle X position in world coordinates
+ * @param {number} handleWorldY - Handle Y position in world coordinates
+ * @param {number} centerWorldX - Center X position in world coordinates
+ * @param {number} centerWorldY - Center Y position in world coordinates
+ * @param {string} handleType - 'corner' or 'edge'
+ * @param {number} rotation - Element rotation in degrees
+ * @param {string} anchor - Handle anchor position (e.g., 'top-left', 'bottom-right')
+ * @returns {string} CSS cursor value
+ */
+export declare function getCursorForWorldPosition(handleWorldX: number, handleWorldY: number, centerWorldX: number, centerWorldY: number, handleType: string, rotation?: number, anchor?: string): string;
+/**
+ * Canvas Zoom Utilities
+ *
+ * CRITICAL: Canvas transforms affect visual properties differently:
+ * - Line widths ARE affected by canvas transforms (scale with zoom)
+ * - Font sizes in ctx.font are NOT affected by canvas transforms
+ * - Dash patterns ARE affected by canvas transforms
+ *
+ * Use these utilities to maintain consistent visual appearance at all zoom levels.
+ */
+/**
+ * Extract the current canvas scale factor from the transform matrix.
+ * This accounts for zoom, DPR (device pixel ratio), and any other scaling.
+ *
+ * @param ctx - Canvas rendering context
+ * @returns Current scale factor (e.g., 0.33 for 33% zoom, 1.0 for 100%)
+ *
+ * @example
+ * const scale = getCanvasScale(ctx); // 0.33 at 33% zoom
+ * ctx.lineWidth = 3 / scale; // Renders as 3px visually at any zoom
+ */
+export declare function getCanvasScale(ctx: CanvasRenderingContext2D): number;
+/**
+ * Set a line width that maintains consistent visual thickness at all zoom levels.
+ *
+ * Canvas transforms affect line widths, so a 3px line at 33% zoom appears as 1px.
+ * This function applies inverse scaling to counteract the zoom effect.
+ *
+ * @param ctx - Canvas rendering context
+ * @param desiredWidth - The visual width you want (in screen pixels)
+ *
+ * @example
+ * // Selection border that's always 3px thick on screen
+ * setZoomInvariantLineWidth(ctx, 3);
+ * ctx.stroke();
+ */
+export declare function setZoomInvariantLineWidth(ctx: CanvasRenderingContext2D, desiredWidth: number): void;
+/**
+ * Set a line dash pattern that maintains consistent visual appearance at all zoom levels.
+ *
+ * Canvas transforms affect dash patterns, so [8, 8] at 33% zoom appears as [2.64, 2.64].
+ * This function applies inverse scaling to counteract the zoom effect.
+ *
+ * @param ctx - Canvas rendering context
+ * @param pattern - The dash pattern you want (in screen pixels), e.g., [8, 8] for "8px dash, 8px gap"
+ *
+ * @example
+ * // Dotted guide line that's always [8, 8] pattern on screen
+ * setZoomInvariantLineWidth(ctx, 3);
+ * setZoomInvariantDash(ctx, [8, 8]);
+ * ctx.stroke();
+ */
+export declare function setZoomInvariantDash(ctx: CanvasRenderingContext2D, pattern: number[]): void;
+/**
+ * Helper to set both line width and dash pattern with zoom-invariant values.
+ * Commonly used for selection visualization and guide lines.
+ *
+ * @param ctx - Canvas rendering context
+ * @param width - Desired line width (in screen pixels)
+ * @param dashPattern - Desired dash pattern (in screen pixels)
+ *
+ * @example
+ * // Dotted guide line for selected arch text
+ * ctx.strokeStyle = getThemeAccentColor();
+ * setZoomInvariantStroke(ctx, 3, [8, 8]);
+ * ctx.beginPath();
+ * // ... draw path ...
+ * ctx.stroke();
+ * ctx.setLineDash([]); // Reset to solid
+ */
+export declare function setZoomInvariantStroke(ctx: CanvasRenderingContext2D, width: number, dashPattern?: number[]): void;
+/**
+ * Set a dash pattern that scales with viewport size (appears longer when zoomed out).
+ *
+ * This creates viewport-adaptive dashes that maintain better visibility when viewing
+ * a larger area of the canvas. The dashes are specified in world-space, so they scale
+ * naturally with the zoom level:
+ * - At 100% zoom: dashes appear at base size
+ * - At 33% zoom (larger viewport): dashes appear smaller on screen but proportional to viewport
+ * - At 300% zoom (zoomed in): dashes appear larger on screen but proportional to viewport
+ *
+ * @param ctx - Canvas rendering context
+ * @param basePattern - Dash pattern in world-space pixels
+ *
+ * @example
+ * // Guide line with world-space dashes (use larger values than screen-space)
+ * setZoomInvariantLineWidth(ctx, 3); // Keep line width consistent
+ * setViewportProportionalDash(ctx, [30, 15]); // Use larger values for visibility
+ * ctx.stroke();
+ */
+export declare function setViewportProportionalDash(ctx: CanvasRenderingContext2D, basePattern: number[]): void;
+/**
+ * Set both line width and dash pattern with hybrid scaling.
+ * Line width stays zoom-invariant (consistent screen thickness).
+ * Dash pattern uses world-space values (scales with viewport).
+ *
+ * This is the recommended approach for guide lines and selection visualization,
+ * providing consistent visual thickness while maintaining proportional dash spacing.
+ *
+ * @param ctx - Canvas rendering context
+ * @param width - Desired line width (in screen pixels, zoom-invariant)
+ * @param basePattern - Dash pattern in world-space pixels (use larger values than screen-space)
+ *
+ * @example
+ * // Circle transform guide: consistent thickness, viewport-proportional dashes
+ * ctx.strokeStyle = getThemeAccentColor();
+ * setViewportProportionalStroke(ctx, 3, [30, 15]); // 30px dashes in world-space
+ * ctx.arc(0, 0, radius, 0, Math.PI * 2);
+ * ctx.stroke();
+ * ctx.setLineDash([]); // Reset
+ */
+export declare function setViewportProportionalStroke(ctx: CanvasRenderingContext2D, width: number, basePattern?: number[]): void;

package/dist/core/GroupElement.d.ts

@@ -0,0 +1,134 @@
+import { BaseElement } from './BaseElement.js';
+import { TextElement } from './TextElement.js';
+import { ImageElement } from './ImageElement.js';
+import { ShapeElement } from './ShapeElement.js';
+import { PathElement } from './PathElement.js';
+import { GroupElementConfig, GroupTransformData, BoundingBox, Point, ResizeAnchor, TransformStartData } from '../types/index.js';
+/** Child element types that can be contained in a group */
+type ChildElement = TextElement | ImageElement | GroupElement | ShapeElement | PathElement;
+export declare class GroupElement extends BaseElement {
+    transformType: 'group';
+    transformData: GroupTransformData;
+    children: ChildElement[];
+    isGroup: boolean;
+    private _baseBBoxWidth;
+    private _baseBBoxHeight;
+    private _rotationCenterX;
+    private _rotationCenterY;
+    constructor(config?: Partial<GroupElementConfig>);
+    /**
+     * Reconstruct a child element from JSON using the transform registry.
+     * Looks up the Component class by transformType and constructs it.
+     * Adding new element types only requires updating the registry, not this file.
+     */
+    private _reconstructChildFromJSON;
+    /**
+     * Calculate group bounds from all children
+     * Returns axis-aligned bounding box containing all children
+     */
+    getBoundingBox(): BoundingBox;
+    /**
+     * Visual bounding box uses the oriented bounding box for groups
+     * This ensures handles and hover effects stay aligned with the dotted border during rotation
+     */
+    getVisualBoundingBox(): BoundingBox;
+    /**
+     * Get rotation anchor - returns the cached rotation center
+     * This ensures consistent rotation behavior even if this.x/this.y change
+     */
+    getRotationAnchor(): Point;
+    /**
+     * Get the four corners of an element's bounding box in world space
+     */
+    private _getRotatedCorners;
+    /**
+     * Update group center and size from children
+     * @param forceRecalcDimensions - Force recalculation of base dimensions (use when children are modified, not during rotation)
+     */
+    updateBoundsFromChildren(forceRecalcDimensions?: boolean): void;
+    /**
+     * Calculate the axis-aligned bounding box dimensions at current state
+     * This should only be called when the group is created or when children change (not during rotation)
+     *
+     * Like multi-selection, we simply cache the current axis-aligned bbox dimensions
+     * and use them for rendering the selection border.
+     */
+    private _calculateInitialDimensions;
+    /**
+     * Render the group with clipping support
+     * Elements with isClipping=true clip all elements below them in the group
+     */
+    render(ctx: CanvasRenderingContext2D, isSelected?: boolean, isHovered?: boolean): void;
+    /**
+     * Render group with clipping masks
+     * Elements with isClipping=true clip all elements below them
+     */
+    private _renderWithClipping;
+    /**
+     * Render dashed outline around group
+     * Uses an oriented bounding box that doesn't change size during rotation
+     */
+    private _renderGroupOutline;
+    /**
+     * Get oriented bounding box (uses cached base dimensions for stability during rotation)
+     *
+     * This follows the same approach as multi-selection:
+     * - Cache the initial axis-aligned bbox dimensions when group is created
+     * - Use those cached dimensions during rotation (never recalculate)
+     * - This keeps the selection border tight and stable during rotation
+     */
+    private getOrientedBoundingBox;
+    /**
+     * Move the group (moves all children)
+     */
+    move(dx: number, dy: number): void;
+    /**
+     * Rotate the group (rotates all children around group center)
+     */
+    setRotation(newRotation: number): void;
+    /**
+     * Resize the group (scales all children proportionally)
+     * Uses the same fixed-corner approach as multi-selection resize
+     */
+    resize(anchor: ResizeAnchor, newWidth: number, newHeight: number, startData: TransformStartData): void;
+    /**
+     * Get transform start data (includes children data)
+     * Use cached base dimensions instead of axis-aligned bbox for consistency with visual border
+     */
+    getTransformStartData(): TransformStartData;
+    /**
+     * Hit test - check if point is inside group's oriented bounding box
+     * This allows clicking anywhere within the selection border to drag the group
+     */
+    hitTest(x: number, y: number): boolean;
+    /**
+     * Only corner handles for groups (uniform scale)
+     */
+    getEnabledAnchors(): ResizeAnchor[];
+    /**
+     * Serialize to JSON
+     */
+    toJSON(): GroupElementConfig;
+    /**
+     * Clone the group (deep copy with children)
+     */
+    clone(): GroupElement;
+    /**
+     * Add a child to the group
+     */
+    addChild(child: ChildElement): void;
+    /**
+     * Remove a child from the group
+     */
+    removeChild(childId: string): boolean;
+    /**
+     * Get all children (for edit mode)
+     */
+    getChildren(): ChildElement[];
+    /**
+     * Find which child (if any) was clicked at the given point
+     * Returns the child element or null if no child was hit
+     */
+    hitTestChild(x: number, y: number): ChildElement | null;
+}
+export {};

package/dist/core/HoverRenderer.d.ts

@@ -0,0 +1,103 @@
+import { BaseElement } from './BaseElement.js';
+import { TextElement } from './TextElement.js';
+interface HoverState {
+    type: 'element' | 'resize-handle' | 'rotation-handle' | null;
+    data?: BaseElement | null;
+    startTime?: number;
+}
+export declare class HoverRenderer {
+    /**
+     * Render hover highlights layer with fade-in animation
+     * Outlines the actual element shape instead of a rectangular border
+     */
+    static renderHoverLayer(ctx: CanvasRenderingContext2D, hoverState: HoverState, selectedId: string | null, _isAltKeyPressed?: boolean, zoom?: number, artboardBackgroundColor?: string): void;
+    /**
+     * Render outline for a specific element type
+     */
+    private static renderElementOutline;
+    /**
+     * Render outline for shape elements (star, rectangle, circle, etc.)
+     * Creates a ring effect with a gap between the element and the stroke
+     */
+    private static renderShapeOutline;
+    /**
+     * Render outline for image elements
+     * Creates a ring effect with a gap between the element and the stroke
+     */
+    private static renderImageOutline;
+    /**
+     * Render outline for group elements
+     * Creates a ring effect with a gap between the element and the stroke
+     */
+    private static renderGroupOutline;
+    /**
+     * Render outline for text elements
+     * Creates a ring effect with a gap between text and stroke (ring behind text fill)
+     * Supports all transform types: custom, circle, wave, arch, etc.
+     */
+    private static renderTextOutline;
+    /**
+     * HOVER RING EFFECT for straight/custom text
+     *
+     * This is the colored ring that appears when hovering over text elements.
+     * Uses offscreen canvas compositing to create a ring with a transparent gap.
+     * Supports per-character fonts via rich text spans.
+     *
+     * NOTE: This is NOT the same as:
+     * - Element stroke (StrokeRenderer.ts - only when stroke.enabled = true)
+     * - Selection box (dashed rectangle in element.render())
+     */
+    private static renderHoverRingEffect;
+    /**
+     * HOVER RING EFFECT for transformed text (circle, wave, arch, lean, ascend, flag)
+     *
+     * This is the colored ring that appears when hovering over curved/transformed text.
+     * Renders text character-by-character along the transform path with ring effect.
+     * Uses offscreen canvas compositing to create a ring with a transparent gap.
+     *
+     * NOTE: This is NOT the same as:
+     * - Element stroke (StrokeRenderer.ts - only when stroke.enabled = true)
+     * - Selection box (dashed outline shown by each transform's render() method)
+     */
+    private static renderTransformHoverRingEffect;
+    /**
+     * Helper to render text along a transform path with hover effect
+     */
+    private static renderTransformWithHoverEffect;
+    /**
+     * Calculate character positions for different transform types
+     *
+     * Also used by EditModeRenderer for cursor positioning on transformed text.
+     */
+    static calculateCharPositions(element: TextElement, chars: string[], charWidths: number[]): Array<{
+        x: number;
+        y: number;
+        angle: number;
+        skewY?: number;
+    }>;
+    /**
+     * Calculate positions for circle transform
+     */
+    private static calculateCirclePositions;
+    /**
+     * Calculate positions for wave transform
+     */
+    private static calculateWavePositions;
+    /**
+     * Calculate positions for arch transform
+     */
+    private static calculateArchPositions;
+    /**
+     * Calculate positions for lean transform
+     */
+    private static calculateLeanPositions;
+    /**
+     * Calculate positions for ascend transform
+     */
+    private static calculateAscendPositions;
+    /**
+     * Calculate positions for flag transform
+     */
+    private static calculateFlagPositions;
+}
+export {};

package/dist/core/HybridHistoryManager.d.ts

@@ -0,0 +1,137 @@
+import { CommandHistory, Command } from './CommandHistory.js';
+import { ArtboardManager } from './ArtboardManager.js';
+type HistoryType = 'global' | 'artboard';
+interface HistoryEntry {
+    type: HistoryType;
+    artboardId?: string;
+    timestamp: number;
+}
+export declare class HybridHistoryManager {
+    private globalHistory;
+    private artboardHistories;
+    private lastOperation;
+    private artboardManager;
+    private maxHistorySize;
+    private commandExecutedCallbacks;
+    constructor(artboardManager: ArtboardManager, maxHistorySize?: number);
+    /**
+     * Register a callback to be called whenever a command is executed
+     * Returns an unsubscribe function
+     */
+    onCommandExecuted(callback: (command: Command, type: HistoryType, artboardId?: string) => void): () => void;
+    /**
+     * Notify all callbacks that a command was executed
+     */
+    private notifyCommandExecuted;
+    /**
+     * Execute a global command (artboard-level operation)
+     */
+    executeGlobal(command: Command): void;
+    /**
+     * Execute a batch of commands as a single global undo entry.
+     * No-op if commands array is empty.
+     */
+    executeBatchGlobal(commands: Command[]): void;
+    /**
+     * Execute a batch of commands as a single undo entry on a specific artboard.
+     * No-op if commands array is empty.
+     */
+    executeBatchOnArtboard(artboardId: string, commands: Command[]): void;
+    /**
+     * Execute a command on a specific artboard
+     */
+    executeOnArtboard(artboardId: string, command: Command): void;
+    /**
+     * Smart undo - determines which history to use
+     */
+    undo(): boolean;
+    /**
+     * Smart redo - determines which history to use
+     */
+    redo(): boolean;
+    /**
+     * Undo global operation
+     */
+    undoGlobal(): boolean;
+    /**
+     * Redo global operation
+     */
+    redoGlobal(): boolean;
+    /**
+     * Undo artboard operation
+     */
+    undoArtboard(artboardId: string): boolean;
+    /**
+     * Redo artboard operation
+     */
+    redoArtboard(artboardId: string): boolean;
+    /**
+     * Check if global undo is available
+     */
+    canUndoGlobal(): boolean;
+    /**
+     * Check if global redo is available
+     */
+    canRedoGlobal(): boolean;
+    /**
+     * Check if artboard undo is available
+     */
+    canUndoArtboard(artboardId: string): boolean;
+    /**
+     * Check if artboard redo is available
+     */
+    canRedoArtboard(artboardId: string): boolean;
+    /**
+     * Check if any undo is available (smart check)
+     */
+    canUndo(): boolean;
+    /**
+     * Check if any redo is available (smart check)
+     */
+    canRedo(): boolean;
+    /**
+     * Clear all histories
+     */
+    clear(): void;
+    /**
+     * Clear history for a specific artboard
+     */
+    clearArtboardHistory(artboardId: string): void;
+    /**
+     * Get history for a specific artboard (create if doesn't exist)
+     */
+    getArtboardHistory(artboardId: string): CommandHistory;
+    /**
+     * Get global history
+     */
+    getGlobalHistory(): CommandHistory;
+    /**
+     * Get state of all histories
+     */
+    getState(): {
+        global: {
+            canUndo: boolean;
+            canRedo: boolean;
+            historySize: number;
+        };
+        artboards: Map<string, {
+            canUndo: boolean;
+            canRedo: boolean;
+            historySize: number;
+        }>;
+        lastOperation: HistoryEntry | null;
+    };
+    /**
+     * Update last operation tracker
+     */
+    private updateLastOperation;
+    /**
+     * Get description of what will be undone
+     */
+    getUndoDescription(): string;
+    /**
+     * Get description of what will be redone
+     */
+    getRedoDescription(): string;
+}
+export default HybridHistoryManager;

package/dist/core/ImageCache.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared image cache for HTMLImageElement instances.
+ * Prevents duplicate loading of the same URL across elements.
+ * Reference-counted -- images are evicted when no elements reference them.
+ *
+ * Usage:
+ *   const cache = ImageCache.getInstance();
+ *   const img = cache.acquire('https://example.com/photo.jpg');
+ *   // ... use img ...
+ *   cache.release('https://example.com/photo.jpg');
+ */
+export declare class ImageCache {
+    private static instance;
+    private cache;
+    private constructor();
+    /**
+     * Get the singleton ImageCache instance.
+     */
+    static getInstance(): ImageCache;
+    /**
+     * Acquire an HTMLImageElement for the given URL.
+     * If the URL is already cached, increments the reference count and returns the existing element.
+     * If not cached, creates a new HTMLImageElement, starts loading, and caches it.
+     *
+     * @param url - The image URL to load
+     * @returns The cached or newly created HTMLImageElement
+     */
+    acquire(url: string): HTMLImageElement;
+    /**
+     * Release a reference to a cached image.
+     * When the reference count reaches zero, the entry is evicted from the cache.
+     *
+     * @param url - The image URL to release
+     */
+    release(url: string): void;
+    /**
+     * Get a cached HTMLImageElement without incrementing the reference count.
+     * Returns undefined if the URL is not in the cache.
+     *
+     * @param url - The image URL to look up
+     */
+    get(url: string): HTMLImageElement | undefined;
+    /**
+     * Check if a URL is in the cache.
+     *
+     * @param url - The image URL to check
+     */
+    has(url: string): boolean;
+    /**
+     * Get cache statistics.
+     *
+     * @returns Object with entry count and total reference count across all entries
+     */
+    getStats(): {
+        entries: number;
+        totalRefs: number;
+    };
+    /**
+     * Clear the entire cache.
+     * Primarily for testing -- removes all entries regardless of reference count.
+     */
+    clear(): void;
+}