@oyerinde/caliper 0.1.4 → 0.2.1

package/dist/preset.d.ts

@@ -0,0 +1,964 @@
+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;
+    /** Name of a global window function to call on state changes (IIFE/CDN-safe, JSON-serializable) */
+    onStateChangeGlobal?: string;
+}
+
+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;
+}
+
+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.
+ */
+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;
+}
+
+export declare type CaliperAgentState = z.infer<typeof CaliperAgentStateSchema>;
+
+export 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>;
+
+/**
+ * @caliper/agent-bridge
+ * Enables AI agents to use Caliper's high-precision measurement engine
+ *
+ * @example
+ * ```typescript
+ * import { createMeasurementSystem, createSelectionSystem } from "@oyerinde/caliper/core";
+ * import { bridge } from "@oyerinde/caliper-bridge";
+ *
+ * const measurementSystem = createMeasurementSystem();
+ * const selectionSystem = createSelectionSystem();
+ *
+ * const cleanup = bridge({
+ *   enabled: true,
+ *   systems: { measurementSystem, selectionSystem }
+ * });
+ * ```
+ */
+
+/**
+ * CaliperBridge Plugin Factory
+ *
+ * Creates a Caliper plugin that enables AI agents to interact with the overlay via
+ * a WebSocket bridge (local MCP relay) or direct global intent dispatching.
+ *
+ * When installed, this plugin:
+ * 1. Starts a local WebSocket server (or connects to one) to receive agent commands.
+ * 2. Exposes `window.dispatchCaliperIntent` for manual/in-page agentic calls.
+ * 3. Syncs the overlay state (camera, selection, measurements) back to the agent.
+ *
+ * @example
+ * ```ts
+ * import { init } from "@oyerinde/caliper/preset";
+ * import { CaliperBridge } from "@oyerinde/caliper/bridge";
+ *
+ * init({ ... }, [
+ *   new CaliperBridge({
+ *     enabled: true,
+ *     wsPort: 3010,
+ *     onStateChange: (state) => console.log("New Agent State:", state)
+ *   })
+ * ]);
+ * ```
+ *
+ * @param config - The bridge configuration settings.
+ * @returns A CaliperPlugin that can be used with `caliper.use()` or in `init()`.
+ */
+export declare function CaliperBridge(config: AgentBridgeConfig): CaliperPlugin;
+
+export declare interface CaliperConfig {
+    /** 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;
+    /** Enable debug logging (default: true). All logs are stripped from production builds. */
+    debug?: boolean;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * An extension can be either a simple function that receives the Caliper instance,
+ * or a full Plugin object with an `install` method.
+ */
+export declare type Extension = ((instance: OverlayInstance) => void) | CaliperPlugin;
+
+/**
+ * High-level initialization for Caliper with support for extensions and plugins.
+ *
+ * This "preset" initializer streamlines setting up Caliper in development or
+ * agentic environments by handling both core configuration and plugin injection
+ * in a single call.
+ *
+ * It accepts two types of extensions:
+ * 1. Simple callback functions: `(instance: OverlayInstance) => void`
+ * 2. Formal Caliper plugins: Objects with an `install(instance: OverlayInstance)` method.
+ *
+ * @example
+ * ```ts
+ * import { init, CaliperBridge } from "@oyerinde/caliper/preset";
+ *
+ * const caliper = init({
+ *   theme: { primary: "#18a0fb" }
+ * }, [
+ *   (instance) => console.log("Caliper ready!", instance),
+ *   CaliperBridge({ wsPort: 3010 })
+ * ]);
+ * ```
+ *
+ * @param configuration - Caliper core configuration (theme, commands, settings).
+ * @param extensions - An array of functions or plugin objects to install immediately.
+ * @returns The initialized Caliper OverlayInstance.
+ */
+export declare function init(configuration?: CaliperConfig, extensions?: Array<Extension>): OverlayInstance;
+
+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
+ */
+declare type MeasurementState = "IDLE" | "ARMED" | "MEASURING" | "FROZEN";
+
+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;
+}
+
+declare type MeasurementSystemListener = () => void;
+
+/**
+ * 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.
+ */
+declare interface ProjectionShortcuts {
+    top?: string;
+    left?: string;
+    bottom?: string;
+    right?: string;
+}
+
+declare interface ProjectionState {
+    direction: ProjectionDirection | null;
+    value: string;
+    element: HTMLElement | null;
+}
+
+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[];
+}
+
+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
+ */
+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>;
+
+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;
+}
+
+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;
+}
+
+export { }