@oyerinde/caliper 0.1.4 → 0.2.0

package/dist/index.d.cts

@@ -1,18 +1,975 @@
-export { OverlayInstance, createOverlay as init } from '@caliper/overlay';
-export { OverlayConfig, getConfig, setConfig } from '@caliper/core';
-
-/**
- * @oyerinde/caliper
- *
- * Browser-based measurement tool overlay.
- * This package bundles all dependencies for easy consumption.
- *
- * Usage:
- * 1. Script tag (Auto-mount): <script src="@oyerinde/caliper/dist/index.global.js"></script>
- * 2. ESM import (Manual): import { init } from "@oyerinde/caliper"
- * 3. Initialize: const caliper = init(); caliper.mount();
- */
-
-declare const VERSION: string;
-
-export { VERSION };
+import { z } from 'zod';
+
+export declare interface AgentBridgeConfig {
+    /** Enable the agentic bridge for AI integration (default: false) */
+    enabled?: boolean;
+    /** WebSocket port for the MCP relay (default: 9876) */
+    wsPort?: number;
+    /** Callback for agent state changes */
+    onStateChange?: (state: CaliperAgentState) => void;
+}
+
+export declare interface AnimationConfig {
+    /** Enable smooth lerp animation for boundary box hover (default: true) */
+    enabled?: boolean;
+    /** Lerp factor for animation smoothness (0-1, lower = smoother, default: 0.25) */
+    lerpFactor?: number;
+}
+
+export declare interface CalculatorIntegration {
+    getState: () => CalculatorState;
+    open: (baseValue: number) => void;
+    handleInput: (key: string) => void;
+    handleBackspace: () => void;
+    handleDelete: () => void;
+    handleEnter: () => void;
+    close: () => void;
+    syncValue: (value: number) => void;
+    getResult: () => number | null;
+}
+
+/**
+ * Calculator state machine
+ */
+declare type CalculatorOperation = "+" | "-" | "*" | "/";
+
+/**
+ * Keyboard shortcuts for measurement sides.
+ */
+export declare interface CalculatorShortcuts {
+    top?: string;
+    bottom?: string;
+    left?: string;
+    right?: string;
+    distance?: string;
+}
+
+declare interface CalculatorState {
+    baseValue: number;
+    operation: CalculatorOperation | null;
+    inputValue: string;
+    result: number | null;
+    isActive: boolean;
+}
+
+declare type CaliperAgentState = z.infer<typeof CaliperAgentStateSchema>;
+
+declare const CaliperAgentStateSchema: z.ZodObject<{
+    viewport: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        scrollX: z.ZodNumber;
+        scrollY: z.ZodNumber;
+    }, z.core.$strip>;
+    activeSelection: z.ZodNullable<z.ZodObject<{
+        rect: z.ZodNullable<z.ZodObject<{
+            top: z.ZodNumber;
+            right: z.ZodNumber;
+            bottom: z.ZodNumber;
+            left: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        scrollHierarchy: z.ZodArray<z.ZodObject<{
+            initialScrollTop: z.ZodNumber;
+            initialScrollLeft: z.ZodNumber;
+            containerRect: z.ZodNullable<z.ZodObject<{
+                top: z.ZodNumber;
+                right: z.ZodNumber;
+                bottom: z.ZodNumber;
+                left: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+            absoluteDepth: z.ZodNumber;
+            hasStickyAncestor: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        position: z.ZodEnum<{
+            static: "static";
+            relative: "relative";
+            absolute: "absolute";
+            fixed: "fixed";
+            sticky: "sticky";
+        }>;
+        stickyConfig: z.ZodOptional<z.ZodObject<{
+            top: z.ZodNullable<z.ZodNumber>;
+            bottom: z.ZodNullable<z.ZodNumber>;
+            left: z.ZodNullable<z.ZodNumber>;
+            right: z.ZodNullable<z.ZodNumber>;
+            naturalTop: z.ZodNumber;
+            naturalLeft: z.ZodNumber;
+            containerWidth: z.ZodNumber;
+            containerHeight: z.ZodNumber;
+            elementWidth: z.ZodNumber;
+            elementHeight: z.ZodNumber;
+            anchorAbsoluteDepth: z.ZodNumber;
+        }, z.core.$strip>>;
+        initialWindowX: z.ZodNumber;
+        initialWindowY: z.ZodNumber;
+        depth: z.ZodNumber;
+        hasContainingBlock: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    selectionFingerprint: z.ZodNullable<z.ZodObject<{
+        selector: z.ZodString;
+        tag: z.ZodString;
+        timestamp: z.ZodNumber;
+        id: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tabId: z.ZodOptional<z.ZodString>;
+        nthChild: z.ZodOptional<z.ZodNumber>;
+        x: z.ZodOptional<z.ZodNumber>;
+        y: z.ZodOptional<z.ZodNumber>;
+        depth: z.ZodOptional<z.ZodNumber>;
+        marker: z.ZodOptional<z.ZodString>;
+        scrollHierarchy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            initialScrollTop: z.ZodNumber;
+            initialScrollLeft: z.ZodNumber;
+            containerRect: z.ZodNullable<z.ZodObject<{
+                top: z.ZodNumber;
+                right: z.ZodNumber;
+                bottom: z.ZodNumber;
+                left: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+            absoluteDepth: z.ZodNumber;
+            hasStickyAncestor: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        position: z.ZodOptional<z.ZodEnum<{
+            static: "static";
+            relative: "relative";
+            absolute: "absolute";
+            fixed: "fixed";
+            sticky: "sticky";
+        }>>;
+        stickyConfig: z.ZodOptional<z.ZodObject<{
+            top: z.ZodNullable<z.ZodNumber>;
+            bottom: z.ZodNullable<z.ZodNumber>;
+            left: z.ZodNullable<z.ZodNumber>;
+            right: z.ZodNullable<z.ZodNumber>;
+            naturalTop: z.ZodNumber;
+            naturalLeft: z.ZodNumber;
+            containerWidth: z.ZodNumber;
+            containerHeight: z.ZodNumber;
+            elementWidth: z.ZodNumber;
+            elementHeight: z.ZodNumber;
+            anchorAbsoluteDepth: z.ZodNumber;
+        }, z.core.$strip>>;
+        initialWindowX: z.ZodOptional<z.ZodNumber>;
+        initialWindowY: z.ZodOptional<z.ZodNumber>;
+        hasContainingBlock: z.ZodOptional<z.ZodBoolean>;
+        rect: z.ZodOptional<z.ZodObject<{
+            top: z.ZodNumber;
+            right: z.ZodNumber;
+            bottom: z.ZodNumber;
+            left: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    lastMeasurement: z.ZodNullable<z.ZodObject<{
+        context: z.ZodNullable<z.ZodEnum<{
+            parent: "parent";
+            child: "child";
+            sibling: "sibling";
+        }>>;
+        lines: z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                top: "top";
+                right: "right";
+                bottom: "bottom";
+                left: "left";
+                distance: "distance";
+            }>;
+            value: z.ZodNumber;
+            start: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>;
+            end: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>;
+            startSync: z.ZodOptional<z.ZodEnum<{
+                primary: "primary";
+                secondary: "secondary";
+            }>>;
+            endSync: z.ZodOptional<z.ZodEnum<{
+                primary: "primary";
+                secondary: "secondary";
+            }>>;
+        }, z.core.$strip>>;
+        primary: z.ZodObject<{
+            top: z.ZodNumber;
+            right: z.ZodNumber;
+            bottom: z.ZodNumber;
+            left: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        secondary: z.ZodNullable<z.ZodObject<{
+            top: z.ZodNumber;
+            right: z.ZodNumber;
+            bottom: z.ZodNumber;
+            left: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        timestamp: z.ZodNumber;
+        primaryHierarchy: z.ZodArray<z.ZodObject<{
+            initialScrollTop: z.ZodNumber;
+            initialScrollLeft: z.ZodNumber;
+            containerRect: z.ZodNullable<z.ZodObject<{
+                top: z.ZodNumber;
+                right: z.ZodNumber;
+                bottom: z.ZodNumber;
+                left: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+            absoluteDepth: z.ZodNumber;
+            hasStickyAncestor: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        secondaryHierarchy: z.ZodArray<z.ZodObject<{
+            initialScrollTop: z.ZodNumber;
+            initialScrollLeft: z.ZodNumber;
+            containerRect: z.ZodNullable<z.ZodObject<{
+                top: z.ZodNumber;
+                right: z.ZodNumber;
+                bottom: z.ZodNumber;
+                left: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+            absoluteDepth: z.ZodNumber;
+            hasStickyAncestor: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        primaryPosition: z.ZodEnum<{
+            static: "static";
+            relative: "relative";
+            absolute: "absolute";
+            fixed: "fixed";
+            sticky: "sticky";
+        }>;
+        secondaryPosition: z.ZodEnum<{
+            static: "static";
+            relative: "relative";
+            absolute: "absolute";
+            fixed: "fixed";
+            sticky: "sticky";
+        }>;
+        primaryWinX: z.ZodNumber;
+        primaryWinY: z.ZodNumber;
+        secondaryWinX: z.ZodNumber;
+        secondaryWinY: z.ZodNumber;
+        primarySticky: z.ZodOptional<z.ZodObject<{
+            top: z.ZodNullable<z.ZodNumber>;
+            bottom: z.ZodNullable<z.ZodNumber>;
+            left: z.ZodNullable<z.ZodNumber>;
+            right: z.ZodNullable<z.ZodNumber>;
+            naturalTop: z.ZodNumber;
+            naturalLeft: z.ZodNumber;
+            containerWidth: z.ZodNumber;
+            containerHeight: z.ZodNumber;
+            elementWidth: z.ZodNumber;
+            elementHeight: z.ZodNumber;
+            anchorAbsoluteDepth: z.ZodNumber;
+        }, z.core.$strip>>;
+        secondarySticky: z.ZodOptional<z.ZodObject<{
+            top: z.ZodNullable<z.ZodNumber>;
+            bottom: z.ZodNullable<z.ZodNumber>;
+            left: z.ZodNullable<z.ZodNumber>;
+            right: z.ZodNullable<z.ZodNumber>;
+            naturalTop: z.ZodNumber;
+            naturalLeft: z.ZodNumber;
+            containerWidth: z.ZodNumber;
+            containerHeight: z.ZodNumber;
+            elementWidth: z.ZodNumber;
+            elementHeight: z.ZodNumber;
+            anchorAbsoluteDepth: z.ZodNumber;
+        }, z.core.$strip>>;
+        primaryHasContainingBlock: z.ZodOptional<z.ZodBoolean>;
+        secondaryHasContainingBlock: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    measurementFingerprint: z.ZodNullable<z.ZodObject<{
+        primary: z.ZodObject<{
+            selector: z.ZodString;
+            tag: z.ZodString;
+            timestamp: z.ZodNumber;
+            id: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+            classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            tabId: z.ZodOptional<z.ZodString>;
+            nthChild: z.ZodOptional<z.ZodNumber>;
+            x: z.ZodOptional<z.ZodNumber>;
+            y: z.ZodOptional<z.ZodNumber>;
+            depth: z.ZodOptional<z.ZodNumber>;
+            marker: z.ZodOptional<z.ZodString>;
+            scrollHierarchy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                initialScrollTop: z.ZodNumber;
+                initialScrollLeft: z.ZodNumber;
+                containerRect: z.ZodNullable<z.ZodObject<{
+                    top: z.ZodNumber;
+                    right: z.ZodNumber;
+                    bottom: z.ZodNumber;
+                    left: z.ZodNumber;
+                    width: z.ZodNumber;
+                    height: z.ZodNumber;
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                }, z.core.$strip>>;
+                absoluteDepth: z.ZodNumber;
+                hasStickyAncestor: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>;
+            position: z.ZodOptional<z.ZodEnum<{
+                static: "static";
+                relative: "relative";
+                absolute: "absolute";
+                fixed: "fixed";
+                sticky: "sticky";
+            }>>;
+            stickyConfig: z.ZodOptional<z.ZodObject<{
+                top: z.ZodNullable<z.ZodNumber>;
+                bottom: z.ZodNullable<z.ZodNumber>;
+                left: z.ZodNullable<z.ZodNumber>;
+                right: z.ZodNullable<z.ZodNumber>;
+                naturalTop: z.ZodNumber;
+                naturalLeft: z.ZodNumber;
+                containerWidth: z.ZodNumber;
+                containerHeight: z.ZodNumber;
+                elementWidth: z.ZodNumber;
+                elementHeight: z.ZodNumber;
+                anchorAbsoluteDepth: z.ZodNumber;
+            }, z.core.$strip>>;
+            initialWindowX: z.ZodOptional<z.ZodNumber>;
+            initialWindowY: z.ZodOptional<z.ZodNumber>;
+            hasContainingBlock: z.ZodOptional<z.ZodBoolean>;
+            rect: z.ZodOptional<z.ZodObject<{
+                top: z.ZodNumber;
+                right: z.ZodNumber;
+                bottom: z.ZodNumber;
+                left: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        secondary: z.ZodObject<{
+            selector: z.ZodString;
+            tag: z.ZodString;
+            timestamp: z.ZodNumber;
+            id: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+            classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            tabId: z.ZodOptional<z.ZodString>;
+            nthChild: z.ZodOptional<z.ZodNumber>;
+            x: z.ZodOptional<z.ZodNumber>;
+            y: z.ZodOptional<z.ZodNumber>;
+            depth: z.ZodOptional<z.ZodNumber>;
+            marker: z.ZodOptional<z.ZodString>;
+            scrollHierarchy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                initialScrollTop: z.ZodNumber;
+                initialScrollLeft: z.ZodNumber;
+                containerRect: z.ZodNullable<z.ZodObject<{
+                    top: z.ZodNumber;
+                    right: z.ZodNumber;
+                    bottom: z.ZodNumber;
+                    left: z.ZodNumber;
+                    width: z.ZodNumber;
+                    height: z.ZodNumber;
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                }, z.core.$strip>>;
+                absoluteDepth: z.ZodNumber;
+                hasStickyAncestor: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>;
+            position: z.ZodOptional<z.ZodEnum<{
+                static: "static";
+                relative: "relative";
+                absolute: "absolute";
+                fixed: "fixed";
+                sticky: "sticky";
+            }>>;
+            stickyConfig: z.ZodOptional<z.ZodObject<{
+                top: z.ZodNullable<z.ZodNumber>;
+                bottom: z.ZodNullable<z.ZodNumber>;
+                left: z.ZodNullable<z.ZodNumber>;
+                right: z.ZodNullable<z.ZodNumber>;
+                naturalTop: z.ZodNumber;
+                naturalLeft: z.ZodNumber;
+                containerWidth: z.ZodNumber;
+                containerHeight: z.ZodNumber;
+                elementWidth: z.ZodNumber;
+                elementHeight: z.ZodNumber;
+                anchorAbsoluteDepth: z.ZodNumber;
+            }, z.core.$strip>>;
+            initialWindowX: z.ZodOptional<z.ZodNumber>;
+            initialWindowY: z.ZodOptional<z.ZodNumber>;
+            hasContainingBlock: z.ZodOptional<z.ZodBoolean>;
+            rect: z.ZodOptional<z.ZodObject<{
+                top: z.ZodNumber;
+                right: z.ZodNumber;
+                bottom: z.ZodNumber;
+                left: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    lastUpdated: z.ZodNumber;
+}, z.core.$strip>;
+
+/**
+ * A plugin allows extending Caliper's functionality by accessing the
+ * OverlayInstance and internal systems.
+ */
+export declare interface CaliperPlugin {
+    /** Unique identifier for the plugin. Used for deduplication. */
+    name: string;
+    /** Called when the plugin is installed on an overlay instance. */
+    install: (instance: OverlayInstance) => void;
+    /** Optional cleanup logic called when the overlay is disposed. */
+    dispose?: () => void;
+}
+
+/**
+ * A helper function for developers to add stable markers to their components.
+ * Returns an object with the data-caliper-marker attribute.
+ *
+ * @example
+ * <div {...caliperProps("main-logo")}>...</div>
+ */
+export declare function caliperProps(marker: string): {
+    "data-caliper-marker"?: undefined;
+} | {
+    "data-caliper-marker": string;
+};
+
+export declare interface CommandsConfig {
+    /** Key to activate measuring mode (default: Alt) */
+    activate?: string;
+    /** Key to freeze current measurement (default: Space) */
+    freeze?: string;
+    /** Key to select an element - must be held + click (default: Control) */
+    select?: string;
+    /** Key to clear current selection (default: Escape) */
+    clear?: string;
+    /** Custom keys to trigger calculator for specific sides (default: t, r, b, l) */
+    calculator?: CalculatorShortcuts;
+    /** Custom keys to trigger projection for specific directions (default: w, a, s, d) */
+    projection?: ProjectionShortcuts;
+    /** Key to trigger ruler lines - must be Shift + this key (default: r) */
+    ruler?: string;
+    /** Duration in ms to hold the select key to trigger selection (default: 250) */
+    selectionHoldDuration?: number;
+}
+
+/**
+ * Retrieves the current Caliper configuration from the environment.
+ *
+ * It resolves configuration in the following priority:
+ * 1. Global window object (`window.__CALIPER_CONFIG__`)
+ * 2. `data-config` attribute on the script tag (useful for UMD/CDN usage)
+ *
+ * @returns The resolved OverlayConfig object.
+ */
+export declare function getConfig(): OverlayConfig;
+
+/**
+ * Core factory function to create and mount the Caliper overlay.
+ *
+ * It manages the lifecycle of the overlay instance, including:
+ * - Bootstrapping the Shadow DOM container.
+ * - Injecting CSS styles.
+ * - Initializing Solid.js rendering for the UI.
+ * - Coordinating measurement and selection systems.
+ * - Managing plugin lifecycle via the `.use()` method.
+ *
+ * This function is idempotent and will return the existing active instance if
+ * one is already mounted in the window.
+ *
+ * @example
+ * ```ts
+ * import { createOverlay } from "@caliper/overlay";
+ *
+ * const caliper = createOverlay({
+ *   theme: { primary: "#18a0fb" }
+ * });
+ *
+ * // Plugins can be added using .use()
+ * caliper.use(myPlugin);
+ * ```
+ *
+ * @param config - The initial configuration object to merge with global defaults.
+ * @returns An OverlayInstance with mount, dispose, and plugin management capabilities.
+ */
+export declare function init(config?: OverlayConfig): OverlayInstance;
+
+export declare type MeasurementLine = MeasurementLine_2;
+
+declare type MeasurementLine_2 = Prettify_2<z.infer<typeof MeasurementLineSchema>>;
+
+declare const MeasurementLineSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        top: "top";
+        right: "right";
+        bottom: "bottom";
+        left: "left";
+        distance: "distance";
+    }>;
+    value: z.ZodNumber;
+    start: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    end: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    startSync: z.ZodOptional<z.ZodEnum<{
+        primary: "primary";
+        secondary: "secondary";
+    }>>;
+    endSync: z.ZodOptional<z.ZodEnum<{
+        primary: "primary";
+        secondary: "secondary";
+    }>>;
+}, z.core.$strip>;
+
+export declare type MeasurementResult = Remap<MeasurementResult_2, {
+    primary: DOMRect;
+    secondary: DOMRect | null;
+    primaryHierarchy: ScrollState[];
+    secondaryHierarchy: ScrollState[];
+    secondaryElement: Element | null;
+}>;
+
+declare type MeasurementResult_2 = Prettify_2<z.infer<typeof MeasurementResultSchema>>;
+
+declare const MeasurementResultSchema: z.ZodObject<{
+    context: z.ZodNullable<z.ZodEnum<{
+        parent: "parent";
+        child: "child";
+        sibling: "sibling";
+    }>>;
+    lines: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            top: "top";
+            right: "right";
+            bottom: "bottom";
+            left: "left";
+            distance: "distance";
+        }>;
+        value: z.ZodNumber;
+        start: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        end: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        startSync: z.ZodOptional<z.ZodEnum<{
+            primary: "primary";
+            secondary: "secondary";
+        }>>;
+        endSync: z.ZodOptional<z.ZodEnum<{
+            primary: "primary";
+            secondary: "secondary";
+        }>>;
+    }, z.core.$strip>>;
+    primary: z.ZodObject<{
+        top: z.ZodNumber;
+        right: z.ZodNumber;
+        bottom: z.ZodNumber;
+        left: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    secondary: z.ZodNullable<z.ZodObject<{
+        top: z.ZodNumber;
+        right: z.ZodNumber;
+        bottom: z.ZodNumber;
+        left: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    timestamp: z.ZodNumber;
+    primaryHierarchy: z.ZodArray<z.ZodObject<{
+        initialScrollTop: z.ZodNumber;
+        initialScrollLeft: z.ZodNumber;
+        containerRect: z.ZodNullable<z.ZodObject<{
+            top: z.ZodNumber;
+            right: z.ZodNumber;
+            bottom: z.ZodNumber;
+            left: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        absoluteDepth: z.ZodNumber;
+        hasStickyAncestor: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    secondaryHierarchy: z.ZodArray<z.ZodObject<{
+        initialScrollTop: z.ZodNumber;
+        initialScrollLeft: z.ZodNumber;
+        containerRect: z.ZodNullable<z.ZodObject<{
+            top: z.ZodNumber;
+            right: z.ZodNumber;
+            bottom: z.ZodNumber;
+            left: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        absoluteDepth: z.ZodNumber;
+        hasStickyAncestor: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    primaryPosition: z.ZodEnum<{
+        static: "static";
+        relative: "relative";
+        absolute: "absolute";
+        fixed: "fixed";
+        sticky: "sticky";
+    }>;
+    secondaryPosition: z.ZodEnum<{
+        static: "static";
+        relative: "relative";
+        absolute: "absolute";
+        fixed: "fixed";
+        sticky: "sticky";
+    }>;
+    primaryWinX: z.ZodNumber;
+    primaryWinY: z.ZodNumber;
+    secondaryWinX: z.ZodNumber;
+    secondaryWinY: z.ZodNumber;
+    primarySticky: z.ZodOptional<z.ZodObject<{
+        top: z.ZodNullable<z.ZodNumber>;
+        bottom: z.ZodNullable<z.ZodNumber>;
+        left: z.ZodNullable<z.ZodNumber>;
+        right: z.ZodNullable<z.ZodNumber>;
+        naturalTop: z.ZodNumber;
+        naturalLeft: z.ZodNumber;
+        containerWidth: z.ZodNumber;
+        containerHeight: z.ZodNumber;
+        elementWidth: z.ZodNumber;
+        elementHeight: z.ZodNumber;
+        anchorAbsoluteDepth: z.ZodNumber;
+    }, z.core.$strip>>;
+    secondarySticky: z.ZodOptional<z.ZodObject<{
+        top: z.ZodNullable<z.ZodNumber>;
+        bottom: z.ZodNullable<z.ZodNumber>;
+        left: z.ZodNullable<z.ZodNumber>;
+        right: z.ZodNullable<z.ZodNumber>;
+        naturalTop: z.ZodNumber;
+        naturalLeft: z.ZodNumber;
+        containerWidth: z.ZodNumber;
+        containerHeight: z.ZodNumber;
+        elementWidth: z.ZodNumber;
+        elementHeight: z.ZodNumber;
+        anchorAbsoluteDepth: z.ZodNumber;
+    }, z.core.$strip>>;
+    primaryHasContainingBlock: z.ZodOptional<z.ZodBoolean>;
+    secondaryHasContainingBlock: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+
+/**
+ * Measurement state machine
+ * IDLE → ARMED → MEASURING → FROZEN → IDLE
+ */
+export declare type MeasurementState = "IDLE" | "ARMED" | "MEASURING" | "FROZEN";
+
+export declare interface MeasurementSystem {
+    measure: (selectedElement: Element, cursor: {
+        x: number;
+        y: number;
+    }) => void;
+    abort: () => void;
+    stop: () => void;
+    freeze: () => void;
+    unfreeze: (isAltDown: boolean) => void;
+    cleanup: () => void;
+    getState: () => MeasurementState;
+    getCurrentResult: () => MeasurementResult | null;
+    getSecondaryElement: () => Element | null;
+    getCalculator: () => CalculatorIntegration;
+    getProjection: () => ProjectionSystem;
+    getRuler: () => RulerSystem;
+    onStateChange: (listener: MeasurementSystemListener) => () => void;
+    updatePrimaryRect: (rect: DOMRect) => void;
+    updateSecondaryRect: (rect: DOMRect) => void;
+    applyResult: (result: MeasurementResult) => void;
+}
+
+export declare type MeasurementSystemListener = () => void;
+
+export declare interface OverlayConfig {
+    /** Customize the visual appearance of the overlay (colors, shadows). */
+    theme?: ThemeConfig;
+    /** Customize keyboard shortcuts for all interactions. */
+    commands?: CommandsConfig;
+    /** Control the boundary box lerp animation behavior. */
+    animation?: AnimationConfig;
+    /** Configure the Agent Bridge for AI/MCP integration. */
+    bridge?: AgentBridgeConfig;
+    /** Enable debug logging (default: true). All logs are stripped from production builds. */
+    debug?: boolean;
+}
+
+/**
+ * Handle to a running Caliper overlay.
+ */
+export declare interface OverlayInstance {
+    /**
+     * Mounts the overlay into the DOM.
+     * By default, it mounts into document.documentElement (safe for Shadow DOM).
+     */
+    mount: (container?: HTMLElement) => void;
+    /**
+     * Removes the overlay from the DOM and cleans up all event listeners and systems.
+     */
+    dispose: () => void;
+    /**
+     * Synchronously returns the internal systems if they are initialized.
+     */
+    getSystems: () => Systems | null;
+    /**
+     * Asynchronous helper that resolves when the internal systems are ready.
+     * Useful for plugins that need to interact with the DOM or state immediately.
+     */
+    waitForSystems: () => Promise<Systems>;
+    /**
+     * Registers a plugin with this instance.
+     */
+    use: (plugin: CaliperPlugin) => OverlayInstance;
+    /** Whether the overlay is currently mounted in the document. */
+    mounted: boolean;
+}
+
+declare type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+declare type Prettify_2<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+declare type ProjectionDirection = "top" | "right" | "bottom" | "left";
+
+declare type ProjectionListener = (state: ProjectionState) => void;
+
+/**
+ * Keyboard shortcuts for projection directions.
+ */
+export declare interface ProjectionShortcuts {
+    top?: string;
+    left?: string;
+    bottom?: string;
+    right?: string;
+}
+
+declare interface ProjectionState {
+    direction: ProjectionDirection | null;
+    value: string;
+    element: HTMLElement | null;
+}
+
+export declare interface ProjectionSystem {
+    getState: () => ProjectionState;
+    setDirection: (direction: ProjectionDirection | null) => void;
+    setElement: (element: HTMLElement | null) => void;
+    appendValue: (char: string, max?: number) => void;
+    capValue: (max: number) => void;
+    backspace: () => void;
+    clear: () => void;
+    onUpdate: (listener: ProjectionListener) => () => void;
+}
+
+declare type Remap<T, U> = Prettify<Omit<T, keyof U> & U>;
+
+declare interface RulerLine {
+    id: string;
+    type: "horizontal" | "vertical";
+    position: number;
+}
+
+declare type RulerListener = (state: RulerState) => void;
+
+declare interface RulerState {
+    lines: RulerLine[];
+}
+
+export declare interface RulerSystem {
+    getState: () => RulerState;
+    addPair: (x: number, y: number) => string | null;
+    updateLine: (id: string, position: number) => void;
+    removeLine: (id: string) => void;
+    clear: () => void;
+    onUpdate: (listener: RulerListener) => () => void;
+}
+
+declare interface ScrollState extends ScrollState_2 {
+    element?: HTMLElement;
+    containerRect: DOMRect | null;
+}
+
+declare type ScrollState_2 = Prettify_2<z.infer<typeof ScrollStateSchema>>;
+
+declare const ScrollStateSchema: z.ZodObject<{
+    initialScrollTop: z.ZodNumber;
+    initialScrollLeft: z.ZodNumber;
+    containerRect: z.ZodNullable<z.ZodObject<{
+        top: z.ZodNumber;
+        right: z.ZodNumber;
+        bottom: z.ZodNumber;
+        left: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    absoluteDepth: z.ZodNumber;
+    hasStickyAncestor: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+
+/**
+ * Selection system for tracking selected elements
+ */
+export declare type SelectionMetadata = Remap<SelectionMetadata_2, {
+    element: Element | null;
+    rect: DOMRect | null;
+    scrollHierarchy: ScrollState[];
+}>;
+
+declare type SelectionMetadata_2 = Prettify_2<z.infer<typeof SelectionMetadataSchema>>;
+
+declare const SelectionMetadataSchema: z.ZodObject<{
+    rect: z.ZodNullable<z.ZodObject<{
+        top: z.ZodNumber;
+        right: z.ZodNumber;
+        bottom: z.ZodNumber;
+        left: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    scrollHierarchy: z.ZodArray<z.ZodObject<{
+        initialScrollTop: z.ZodNumber;
+        initialScrollLeft: z.ZodNumber;
+        containerRect: z.ZodNullable<z.ZodObject<{
+            top: z.ZodNumber;
+            right: z.ZodNumber;
+            bottom: z.ZodNumber;
+            left: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        absoluteDepth: z.ZodNumber;
+        hasStickyAncestor: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    position: z.ZodEnum<{
+        static: "static";
+        relative: "relative";
+        absolute: "absolute";
+        fixed: "fixed";
+        sticky: "sticky";
+    }>;
+    stickyConfig: z.ZodOptional<z.ZodObject<{
+        top: z.ZodNullable<z.ZodNumber>;
+        bottom: z.ZodNullable<z.ZodNumber>;
+        left: z.ZodNullable<z.ZodNumber>;
+        right: z.ZodNullable<z.ZodNumber>;
+        naturalTop: z.ZodNumber;
+        naturalLeft: z.ZodNumber;
+        containerWidth: z.ZodNumber;
+        containerHeight: z.ZodNumber;
+        elementWidth: z.ZodNumber;
+        elementHeight: z.ZodNumber;
+        anchorAbsoluteDepth: z.ZodNumber;
+    }, z.core.$strip>>;
+    initialWindowX: z.ZodNumber;
+    initialWindowY: z.ZodNumber;
+    depth: z.ZodNumber;
+    hasContainingBlock: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+
+export declare interface SelectionSystem {
+    select: (element: Element | null) => void;
+    getSelected: () => Element | null;
+    getSelectedRect: () => DOMRect | null;
+    getMetadata: () => SelectionMetadata;
+    clear: () => void;
+    onUpdate: (callback: (metadata: SelectionMetadata) => void) => () => void;
+    updateRect: (rect: DOMRect) => void;
+}
+
+/**
+ * Sets the global Caliper configuration.
+ * This is a typed wrapper around window.__CALIPER_CONFIG__.
+ *
+ * @param config - The configuration object to set
+ *
+ * @example
+ * ```ts
+ * import { setConfig } from "@caliper/core";
+ *
+ * setConfig({
+ *   theme: { primary: "#ff0000" },
+ *   commands: { activate: "Alt" }
+ * });
+ * ```
+ */
+export declare function setConfig(config: OverlayConfig): void;
+
+export declare interface Systems {
+    measurementSystem: MeasurementSystem;
+    selectionSystem: SelectionSystem;
+}
+
+export declare interface ThemeConfig {
+    primary?: string;
+    secondary?: string;
+    calcBg?: string;
+    calcShadow?: string;
+    calcOpHighlight?: string;
+    calcText?: string;
+    text?: string;
+    projection?: string;
+    ruler?: string;
+}
+
+/**
+ * The current version of the Caliper package.
+ */
+export declare const VERSION: string;
+
+export { }