@oyerinde/caliper 0.1.4 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.1] - 2026-02-16
+
+### Refactored
+
+- **Configuration Engine**: Renamed `OverlayConfig` to `CaliperConfig` to reflect its expanded scope.
+- **Bridge Decoupling**: Moved `bridge` configuration out of the core config type. It is now exclusively a plugin concern, with specialized `IIFEConfig` handling for CDN/script-tag users.
+
+### Added
+
+- **Agent Bridge Serialization**: Introduced `onStateChangeGlobal` to allow string-based callback names in `data-config` for IIFE/CDN environments.
+
+### Fixed
+
+- **Boundary Box Snapping**: Fixed a bug where boxes would snap to `(0,0)` when elements animated out or were removed from the DOM. The overlay now retains the last known good position.
+
+## [0.2.0] - 2026-02-12
+
+### Added
+
+- **Agent Bridge**: Support for AI agents and programmatic audits via `@oyerinde/caliper/bridge`.
+- **MCP Server**: Integrated MCP server for AI auditing (activate via `npx @oyerinde/caliper`).
+  - **MCP tools**: `caliper_list_tabs`, `caliper_get_context`, `caliper_switch_tab`, `caliper_inspect`, `caliper_measure`, `caliper_clear`, `caliper_walk_dom`, and `caliper_walk_and_measure`.
+  - **Accessibility Tools**: `caliper_check_contrast` and `caliper_delta_e`.
+  - **MCP prompts**: `caliper-selector-audit` and `caliper-selectors-compare`.
+  - **MCP resources**: `caliper://tabs` and `caliper://state`.
+- **Context Menu**: Right-click selected elements to copy metadata.
+- **Expanded Distribution**: Multi-entry support for `@oyerinde/caliper/preset` and `@oyerinde/caliper/bridge`, alongside dedicated `index.js`, `index.min.js`, and `index.global.js` bundles.
+
+### Fixed
+
+- **Geometry Engine**: Improved coordinate tracking for `fixed` and `sticky` elements and nested scroll containers.
+  - Fix: Precision tracking for sticky elements across complex DOM hierarchies.
+  - Fix: Deep scroll resolution for nested overflow containers.
+  - Fix: Real-time clipping path calculation for partially visible elements.
+
 ## [0.1.4] - 2026-01-16
 
 ### Fixed

package/README.md

@@ -7,6 +7,16 @@
 
 Caliper is a high-precision, framework-agnostic measurement tool that lives in your browser during development. It helps you catch "pixel-drift" and alignment issues before they reach production.
 
+### AI Agents & MCP 🤖
+
+Caliper is "AI-Native". It can be connected to AI agents (like Cursor, Claude Code, or Antigravity) via the **Model Context Protocol (MCP)**, allowing agents to perform pixel-perfect audits of your UI.
+
+1. **Install Bridge**: Available as `@oyerinde/caliper/bridge` for custom integrations.
+2. **Run Server**: `npx @oyerinde/caliper`
+3. **Connect**: Add the MCP server to your editor on the default port **9876**.
+
+The AI agent gains "layout eyes" and can perform high-precision audits, measurements, and alignment checks directly in your browser.
+
 ---
 
 ## Features 🚀
@@ -17,6 +27,8 @@ Caliper is a high-precision, framework-agnostic measurement tool that lives in y
 - **Edge Projections**: Check alignment across the entire viewport using relative projections (W/A/S/D).
 - **Viewport Rulers**: Draggable guidelines with magnetic snapping and chained distance measurements (Shift + R).
 - **Integrated Calculator**: Precise spatial math for complex component spacing (T/R/B/L/G).
+- **Agent Bridge**: Built-in support for AI-driven audits and programmatic UI inspection.
+- **Agent State Sync**: Real-time "passive observation" synchronization with AI agents, providing stable JSON fingerprints for seamless tool-based hand-off.
 - **Full Customization**: Fully configurable shortcuts and theme colors.
 
 ---
@@ -26,6 +38,7 @@ Caliper is a high-precision, framework-agnostic measurement tool that lives in y
 Caliper is designed to be side-effect-free in production and easy to integrate into any modern stack.
 
 ### 1. Next.js (App Router)
+
 ```tsx
 // app/layout.tsx
 import Script from "next/script";
@@ -37,7 +50,7 @@ export default function RootLayout({ children }) {
         {process.env.NODE_ENV === "development" && (
           <Script
             src="https://unpkg.com/@oyerinde/caliper/dist/index.global.js"
-            data-config={JSON.stringify({ theme: { primary: '#AC2323' } })}
+            data-config={JSON.stringify({ theme: { primary: "#AC2323" } })}
             strategy="afterInteractive"
           />
         )}
@@ -49,19 +62,21 @@ export default function RootLayout({ children }) {
 ```
 
 ### 2. Vite
+
 ```html
 <!-- index.html -->
 <script type="module">
-if (import.meta.env.DEV) {
-  // Run npm i @oyerinde/caliper then
-  import("@oyerinde/caliper").then(({ init }) => {
-    init({ theme: { primary: '#AC2323' } });
-  });
-}
+  if (import.meta.env.DEV) {
+    // Run npm i @oyerinde/caliper then
+    import("@oyerinde/caliper").then(({ init }) => {
+      init({ theme: { primary: "#AC2323" } });
+    });
+  }
 </script>
 ```
 
 ### 3. HTML (Plain)
+
 ```html
 <!-- index.html -->
 <script type="module">
@@ -76,12 +91,13 @@ if (import.meta.env.DEV) {
 ```
 
 ### 4. Astro
+
 ```html
 <!-- src/components/Caliper.astro -->
 <script type="module" is:inline>
   if (import.meta.env.DEV) {
     // Run npm i @oyerinde/caliper then
-    import('@oyerinde/caliper').then(({ init }) => {
+    import("@oyerinde/caliper").then(({ init }) => {
       init();
     });
   }
@@ -89,6 +105,7 @@ if (import.meta.env.DEV) {
 ```
 
 ### 5. Nuxt
+
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
@@ -96,43 +113,45 @@ export default defineNuxtConfig({
     head: {
       script: [
         {
-          src: 'https://unpkg.com/@oyerinde/caliper/dist/index.global.js',
-          'data-config': JSON.stringify({ theme: { primary: '#AC2323' } }),
-          defer: true
-        }
-      ]
-    }
-  }
+          src: "https://unpkg.com/@oyerinde/caliper/dist/index.global.js",
+          "data-config": JSON.stringify({ theme: { primary: "#AC2323" } }),
+          defer: true,
+        },
+      ],
+    },
+  },
 });
 ```
 
 ### 6. Vue
+
 ```html
 <!-- index.html -->
 <script type="module">
   if (import.meta.env.DEV) {
     // Run npm i @oyerinde/caliper then
     import("@oyerinde/caliper").then(({ init }) => {
-      init({ theme: { primary: '#AC2323' } });
+      init({ theme: { primary: "#AC2323" } });
     });
   }
 </script>
 ```
 
 ### 7. TanStack Start
+
 ```tsx
 // root.tsx
-import { Meta, Scripts } from '@tanstack/react-router';
+import { Meta, Scripts } from "@tanstack/react-router";
 
 export function Root() {
   return (
     <html lang="en">
       <head>
         <Meta />
-        {process.env.NODE_ENV === 'development' && (
+        {process.env.NODE_ENV === "development" && (
           <script
             src="https://unpkg.com/@oyerinde/caliper/dist/index.global.js"
-            data-config={JSON.stringify({ theme: { primary: '#AC2323' } })}
+            data-config={JSON.stringify({ theme: { primary: "#AC2323" } })}
             async
           />
         )}
@@ -147,6 +166,59 @@ export function Root() {
 
 ---
 
+## Agent Bridge Installation 🤖
+
+The Agent Bridge enables AI agents (like Claude or Cursor) to communicate with Caliper. It is available as a sub-export of the main package.
+
+### 1. Vite & Module Bundlers
+
+If you've installed `@oyerinde/caliper` via npm, you can initialize the bridge using the plugin pattern:
+
+```typescript
+import { init } from "@oyerinde/caliper";
+import { CaliperBridge } from "@oyerinde/caliper/bridge";
+
+const caliper = init();
+
+caliper.use(
+  CaliperBridge({
+    enabled: true,
+    wsPort: 9876,
+  })
+);
+```
+
+### 2. Standalone (CDN/IIFE)
+
+If you are using the global script tag, the bridge is automatically included in the default bundle. Use the **minified lite** version if you don't need bridge support:
+
+```html
+<!-- Full version (Includes Agent Bridge) -->
+<script
+  src="https://unpkg.com/@oyerinde/caliper/dist/index.global.js"
+  data-config='{"bridge": {"enabled": true}}'
+></script>
+
+<!-- Lite Version (Core only, No Bridge) -->
+<script src="https://unpkg.com/@oyerinde/caliper/dist/index.global.min.js"></script>
+```
+
+### 3. Next.js (App Router)
+
+Enable the bridge directly in your configuration block:
+
+```tsx
+<Script
+  src="https://unpkg.com/@oyerinde/caliper/dist/index.global.js"
+  data-config={JSON.stringify({
+    bridge: { enabled: true },
+  })}
+  strategy="afterInteractive"
+/>
+```
+
+---
+
 ## Configuration 🛠️
 
 Caliper can be customized to fit your specific design system and workflow. `init()` automatically mounts the overlay in the browser.
@@ -157,17 +229,39 @@ import { init } from "@oyerinde/caliper";
 init({
   theme: {
     primary: "#18A0FB", // Main brand color
-    ruler: "#AC2323", // Guideline color
-    calcBg: "rgba(0,0,0,0.9)",
+    secondary: "#F24E1E", // Accent color (for highlights)
+    calcBg: "rgba(30,30,30,0.95)",
+    calcShadow: "rgba(0,0,0,0.5)",
+    calcOpHighlight: "#18A0FB", // Operator pulse color
+    calcText: "#FFFFFF",
+    text: "#FFFFFF",
+    projection: "#9B51E4", // Edge projection lines
+    ruler: "#18A0FB", // Ruler/guideline color
   },
   commands: {
-    activate: "Alt", // Key to show overlay
+    activate: "Alt", // Reveal overlay
     freeze: " ", // Key to lock lines
-    ruler: "r", // Key for guideline (Shift+r)
-    selectionHoldDuration: 250, // Hold duration to select
+    select: "Control", // Key to select (held)
+    clear: "Escape", // Clear measurements
+    ruler: "r", // Ruler (Shift+r)
+    selectionHoldDuration: 250, // Select hold-time (ms)
+    calculator: {
+      top: "t",
+      right: "r",
+      bottom: "b",
+      left: "l",
+      distance: "g",
+    },
+    projection: {
+      top: "w",
+      left: "a",
+      bottom: "s",
+      right: "d",
+    },
   },
   animation: {
-    lerpFactor: 0.2, // Smoothness (0-1)
+    enabled: true, // Smooth hover box
+    lerpFactor: 0.25, // Fluidity (low = slower)
   },
 });
 ```
@@ -182,6 +276,16 @@ To prevent Caliper from measuring specific elements (like sidebars, floating but
 </div>
 ```
 
+### Stable Markers
+
+For AI agents to reliably rediscover elements across re-renders (like HMR), we recommend adding stable markers to critical UI components. Use the `caliperProps` helper to add these attributes only in non-production environments.
+
+**Usage:**
+
+```tsx
+<div {...caliperProps("main-sidebar")}>...</div>
+```
+
 ---
 
 ## Interaction Guide ⌨️
@@ -189,6 +293,7 @@ To prevent Caliper from measuring specific elements (like sidebars, floating but
 ### Measurements
 
 - **Cmd/Ctrl + Click + Hold** (250ms) — Select an element.
+- **Right-Click** — Copy element metadata (selector, ID, text) when selected.
 - **Hover** — View relative distances to target.
 - **Option/Alt** — Hold to reveal the overlay.
 - **Space** — Freeze the current state.

package/dist/bridge.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+var chunkPYAVLOZM_cjs = require('./chunk-PYAVLOZM.cjs');
+
+
+
+Object.defineProperty(exports, "CALIPER_METHODS", {
+  enumerable: true,
+  get: function () { return chunkPYAVLOZM_cjs.CALIPER_METHODS; }
+});
+Object.defineProperty(exports, "CaliperActionResultSchema", {
+  enumerable: true,
+  get: function () { return chunkPYAVLOZM_cjs.CaliperActionResultSchema; }
+});
+Object.defineProperty(exports, "CaliperAgentStateSchema", {
+  enumerable: true,
+  get: function () { return chunkPYAVLOZM_cjs.CaliperAgentStateSchema; }
+});
+Object.defineProperty(exports, "CaliperBridge", {
+  enumerable: true,
+  get: function () { return chunkPYAVLOZM_cjs.CaliperBridge; }
+});
+Object.defineProperty(exports, "CaliperGetContextPayloadSchema", {
+  enumerable: true,
+  get: function () { return chunkPYAVLOZM_cjs.CaliperGetContextPayloadSchema; }
+});
+Object.defineProperty(exports, "CaliperInspectPayloadSchema", {
+  enumerable: true,
+  get: function () { return chunkPYAVLOZM_cjs.CaliperInspectPayloadSchema; }
+});
+Object.defineProperty(exports, "CaliperMeasurePayloadSchema", {
+  enumerable: true,
+  get: function () { return chunkPYAVLOZM_cjs.CaliperMeasurePayloadSchema; }
+});
+Object.defineProperty(exports, "CaliperSelectPayloadSchema", {
+  enumerable: true,
+  get: function () { return chunkPYAVLOZM_cjs.CaliperSelectPayloadSchema; }
+});
+Object.defineProperty(exports, "CaliperWalkAndMeasurePayloadSchema", {
+  enumerable: true,
+  get: function () { return chunkPYAVLOZM_cjs.CaliperWalkAndMeasurePayloadSchema; }
+});
+Object.defineProperty(exports, "CaliperWalkDomPayloadSchema", {
+  enumerable: true,
+  get: function () { return chunkPYAVLOZM_cjs.CaliperWalkDomPayloadSchema; }
+});
+Object.defineProperty(exports, "dispatchCaliperIntent", {
+  enumerable: true,
+  get: function () { return chunkPYAVLOZM_cjs.dispatchCaliperIntent; }
+});