@wrium/evasive-button 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Khalife
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+# @wrium/evasive-button
+
+A fun, highly practical plugin for [Wrium](https://github.com/wrium/wrium) that makes buttons (or any interactive element) playfully and smoothly dodge the user's cursor when approached, hovered, or clicked.
+
+Ideal for gamified forms, smart validation ("complete fields to unlock button"), interactive confirmations, or playful login screens!
+
+---
+
+## Highlights
+
+- 🏃 **Smooth Tangential Gliding**: Physics-based wall-sliding that avoids erratic jumps, teleportation, or sticking against boundaries.
+- 📐 **Boundary & Arena Control**: Confine movement to `'parent'`, `'viewport'`, or any custom CSS selector (`bounds: '#arena'`).
+- 🎯 **Movement Limits**:
+  - `maxRadius`: Restrict evasion distance from the button's home anchor so it stays in its neighborhood.
+  - `duration`: Auto-timeout (in milliseconds) after which the button gives up and settles.
+  - `maxAttempts`: Auto-settle after a maximum number of dodge attempts.
+- 🔄 **Form Validation / Reactive Toggles**: Bind directly to expressions like `v-evade="{ active: !isFormValid }"`. When valid, the button smoothly glides home to `(0, 0)`!
+- 🎨 **State Classes & Attributes**: Automatically manages `.is-settled`, `.is-evading`, and `data-state="settled|evading|gaveup"` for styling.
+- 🔔 **Rich Lifecycle Events**: `@evade`, `@settle`, and `@giveup` DOM events.
+- ♿ **Accessible by Design**: Respects `prefers-reduced-motion` and preserves keyboard navigation (`Tab` + `Enter`/`Space`).
+- ⚡ **Minimalist**: Zero dependencies, GPU-accelerated transforms, ~1.5 KB.
+
+---
+
+## Installation
+
+```bash
+npm install @wrium/evasive-button
+# or
+bun add @wrium/evasive-button
+```
+
+`@wrium/wrium` is a peer dependency — install it too if you haven't already.
+
+---
+
+## Quick Start
+
+### Basic Usage
+
+```html
+<div id="app">
+    <button v-evade>Try to Click Me!</button>
+</div>
+
+<script type="module">
+    import { createApp } from '@wrium/wrium';
+    import { EvasiveButtonPlugin } from '@wrium/evasive-button';
+
+    createApp(() => ({}))
+        .use(EvasiveButtonPlugin)
+        .mount('#app');
+</script>
+```
+
+---
+
+## Practical Form Validation Scenario
+
+The button evades the cursor while required fields are incomplete; as soon as the form is valid, it stops evading and smoothly returns to its default position, ready to be clicked!
+
+```html
+<div id="app" class="login-card">
+    <h2>Secure Login</h2>
+
+    <input type="text" v-model="username" placeholder="Username (3+ chars)" />
+    <input type="password" v-model="password" placeholder="Password (6+ chars)" />
+
+    <!-- Evasion container arena -->
+    <div id="button-arena" class="arena">
+        <button
+            type="submit"
+            class="login-btn"
+            v-evade="{
+                active: !isFormValid,
+                bounds: '#button-arena',
+                maxRadius: 150,
+                threshold: 75,
+                duration: 10000
+            }"
+            @settle="onButtonSettled"
+            @evade="onButtonEvaded"
+        >
+            {{ isFormValid ? 'Log In' : 'Fill fields first!' }}
+        </button>
+    </div>
+</div>
+
+<script type="module">
+    import { createApp, ref, computed } from '@wrium/wrium';
+    import { EvasiveButtonPlugin } from '@wrium/evasive-button';
+
+    createApp(() => {
+        const username = ref('');
+        const password = ref('');
+
+        const isFormValid = computed(() => {
+            return username.value.trim().length >= 3 && password.value.length >= 6;
+        });
+
+        function onButtonSettled(e) {
+            console.log('Button has returned home and settled!', e.detail);
+        }
+
+        function onButtonEvaded(e) {
+            console.log('Button evaded, total attempts:', e.detail.attempts);
+        }
+
+        return { username, password, isFormValid, onButtonSettled, onButtonEvaded };
+    })
+        .use(EvasiveButtonPlugin)
+        .mount('#app');
+</script>
+```
+
+---
+
+## Directive Options Reference
+
+Options can be passed directly as an object to `v-evade="{ ... }"` or globally when installing via `app.use(EvasiveButtonPlugin, { ... })`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `active` | `boolean` | `true` | When `false`, evasion stops and the button smoothly returns to `(0, 0)` |
+| `bounds` | `string` | `'parent'` | Bounding container: `'parent'`, `'viewport'`, or a CSS selector (e.g. `'#arena'`) |
+| `maxRadius` | `number` | `Infinity` | Maximum radius (in pixels) the button is allowed to stray from its natural anchor |
+| `duration` | `number` | `Infinity` | Maximum time (in ms) to evade before giving up and settling |
+| `maxAttempts` | `number` | `Infinity` | Maximum number of dodges before giving up and settling |
+| `threshold` | `number` | `75` | Proximity trigger distance (in pixels) from the cursor |
+| `distance` | `number` | `100` | Base leap distance (in pixels) away from the cursor |
+| `random` | `boolean` | `false` | Adds angular jitter to evasion trajectories |
+| `teleport` | `boolean` | `false` | Jump instantly without smooth CSS transition animation |
+| `allowKeyboard` | `boolean` | `true` | Allows keyboard users (`Tab` + `Enter`/`Space`) to submit without triggering evasion |
+| `respectReducedMotion` | `boolean` | `true` | Automatically disables evasion if OS `prefers-reduced-motion` is active |
+
+---
+
+## State Classes & Attributes
+
+The directive automatically maintains CSS classes and data attributes on the element, making visual styling effortless:
+
+- **`.is-settled`** / **`data-state="settled"`**: Present when the button is at rest at its natural origin.
+- **`.is-evading`** / **`data-state="evading"`**: Present while the button is actively evading or displaced.
+- **`data-state="gaveup"`**: Present when evasion stopped due to `duration` timeout or `maxAttempts`.
+
+### Styling Example:
+```css
+/* Normal state */
+.login-btn.is-settled {
+    background: #0284c7;
+}
+
+/* While dodging the cursor */
+.login-btn.is-evading {
+    background: #e11d48;
+    box-shadow: 0 4px 14px rgba(225, 29, 72, 0.4);
+}
+```
+
+---
+
+## Lifecycle Events
+
+Elements dispatch custom DOM events that can be listened to via `@event` in Wrium templates:
+
+### `@evade`
+Fires on each evasion:
+```ts
+e.detail: {
+    attempts: number, // Total number of evasions triggered
+    x: number,        // Current translation X in px
+    y: number,        // Current translation Y in px
+    dx: number,       // Delta X moved this step
+    dy: number,       // Delta Y moved this step
+    source: string    // 'proximity' | 'enter' | 'click_attempt'
+}
+```
+
+### `@settle`
+Fires when evasion stops and the button has smoothly landed back at `(0, 0)`:
+```ts
+e.detail: {
+    attempts: number,
+    reason: string    // 'disabled' | 'duration' | 'maxAttempts'
+}
+```
+
+### `@giveup`
+Fires when evasion automatically stops because `duration` or `maxAttempts` was reached:
+```ts
+e.detail: {
+    attempts: number,
+    reason: string    // 'duration' | 'maxAttempts'
+}
+```
+
+---
+
+## Standalone Helper Functions
+
+Pure mathematical functions exported for standalone use outside of DOM bindings:
+
+```js
+import { calculateEvasionOffset, isNearTarget, isReducedMotionPreferred } from '@wrium/evasive-button';
+
+// Check proximity
+const { isNear, distance } = isNearTarget(cursor, targetRect, 80);
+
+// Calculate next offset respecting boundaries and maxRadius
+const nextOffset = calculateEvasionOffset(
+    cursor,
+    elSize,
+    naturalPos,
+    containerBounds,
+    currentOffset,
+    { distance: 100, threshold: 80, maxRadius: 150 }
+);
+```
+
+---
+
+## Testing
+
+Run unit tests (Vitest):
+```bash
+bun run test
+# or: npm test
+```
+
+Run End-to-End tests (Playwright):
+```bash
+bun run test:e2e
+# or: npm run test:e2e
+```
+
+Interactive UI Test Mode:
+```bash
+bun run test:e2e:ui
+```
+
+---
+
+## License
+
+MIT License.

package/dist/types/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Evasive Button Plugin for Wrium.
+ *
+ * Causes buttons (or any interactive element) to playfully and smoothly dodge the cursor
+ * when hovered, approached, or clicked. Ideal for playful login screens,
+ * gamified forms, prank pages, or interactive validation feedback.
+ *
+ * Phase 2 Capabilities:
+ * - Fluid tangential gliding and perimeter wall-sliding (no erratic corner teleporting).
+ * - Anti-stuck corner escape mechanics (never gets trapped in corners or pinned against walls).
+ * - Bounded environment control: 'parent', 'viewport', or custom selector (e.g. bounds: '#arena').
+ * - Movement limits:
+ *   - maxRadius: limits evasion distance from the button's home anchor.
+ *   - duration: timeout in milliseconds after which evasion gives up and settles.
+ *   - maxAttempts: count limit after which evasion gives up and settles.
+ * - Guaranteed smooth return to default position (0, 0) when disabled or form becomes valid.
+ * - Lifecycle state classes (.is-evading, .is-settled) and events (@evade, @settle, @giveup).
+ * - Accessibility: prefers-reduced-motion auto-detection and Tab+Enter keyboard support.
+ *
+ * @example
+ * import { createApp, ref, computed } from '@wrium/wrium';
+ * import { EvasiveButtonPlugin } from '@wrium/evasive-button';
+ *
+ * createApp(() => {
+ *     const username = ref('');
+ *     const password = ref('');
+ *     const isFormValid = computed(() => username.value.length >= 3 && password.value.length >= 6);
+ *     return { username, password, isFormValid };
+ * })
+ *     .use(EvasiveButtonPlugin)
+ *     .mount('#app');
+ *
+ * <!-- Evasive until fields are filled, then smoothly glides home and settles -->
+ * <button v-evade="{ active: !isFormValid, bounds: '#arena', maxRadius: 150 }" @settle="onSettled">
+ *     Log In
+ * </button>
+ */
+/**
+ * Check if user's OS has prefers-reduced-motion enabled.
+ *
+ * @returns {boolean}
+ */
+export declare function isReducedMotionPreferred(): boolean;
+/**
+ * Check if the cursor is within the proximity threshold of a target bounding rect.
+ *
+ * @param {{ x: number, y: number }} cursor
+ * @param {{ left: number, top: number, width: number, height: number, right?: number, bottom?: number }} targetRect
+ * @param {number} threshold
+ * @returns {{ isNear: boolean, distance: number, center: { x: number, y: number } }}
+ */
+export declare function isNearTarget(cursor: {
+    x: number;
+    y: number;
+}, targetRect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    right?: number;
+    bottom?: number;
+}, threshold?: number): {
+    isNear: boolean;
+    distance: number;
+    center: {
+        x: number;
+        y: number;
+    };
+};
+/**
+ * Calculates a new translation offset { x, y } that evades the cursor
+ * while staying strictly within the container bounds and respecting maxRadius.
+ *
+ * Pure function - completely decoupled from DOM mutations for clean testability.
+ *
+ * @param {{ x: number, y: number }} cursor - Cursor coordinates in viewport space
+ * @param {{ width: number, height: number }} elSize - Element dimensions
+ * @param {{ left: number, top: number }} naturalPos - Natural element origin (translate = 0)
+ * @param {{ left: number, top: number, right: number, bottom: number }} bounds - Allowed boundary box
+ * @param {{ x: number, y: number }} currentOffset - Current translation { x, y }
+ * @param {Object} [options]
+ * @param {number} [options.distance=100] - Base leap distance in pixels
+ * @param {number} [options.threshold=80] - Proximity trigger distance in pixels
+ * @param {number} [options.maxRadius] - Maximum allowable distance from home origin (0, 0)
+ * @param {boolean} [options.random=false] - Apply random angle jitter
+ * @returns {{ x: number, y: number, escaped: boolean }}
+ */
+export declare function calculateEvasionOffset(cursor: {
+    x: number;
+    y: number;
+}, elSize: {
+    width: number;
+    height: number;
+}, naturalPos: {
+    left: number;
+    top: number;
+}, bounds: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}, currentOffset?: {
+    x: number;
+    y: number;
+}, options?: {
+    distance?: number;
+    threshold?: number;
+    maxRadius?: number;
+    random?: boolean;
+}): {
+    x: number;
+    y: number;
+    escaped: boolean;
+};
+/**
+ * Resolve the bounding box to constrain element movement within.
+ *
+ * @param {HTMLElement} el
+ * @param {'parent'|'viewport'|string} [boundsType='parent']
+ * @returns {{ left: number, top: number, right: number, bottom: number, width: number, height: number }}
+ */
+export declare function getBoundingContainer(el: HTMLElement, boundsType?: 'parent' | 'viewport' | string): {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+};
+/**
+ * EvasiveButtonPlugin definition for Wrium.
+ */
+export declare const EvasiveButtonPlugin: {
+    install(api: any, options?: {}): void;
+};
+/**
+ * Convenient aliases
+ */
+export declare const EvadePlugin: {
+    install(api: any, options?: {}): void;
+};
+export declare const EvasivePlugin: {
+    install(api: any, options?: {}): void;
+};
+export default EvasiveButtonPlugin;

package/index.js

@@ -0,0 +1,813 @@
+/**
+ * Evasive Button Plugin for Wrium.
+ *
+ * Causes buttons (or any interactive element) to playfully and smoothly dodge the cursor
+ * when hovered, approached, or clicked. Ideal for playful login screens,
+ * gamified forms, prank pages, or interactive validation feedback.
+ *
+ * Phase 2 Capabilities:
+ * - Fluid tangential gliding and perimeter wall-sliding (no erratic corner teleporting).
+ * - Anti-stuck corner escape mechanics (never gets trapped in corners or pinned against walls).
+ * - Bounded environment control: 'parent', 'viewport', or custom selector (e.g. bounds: '#arena').
+ * - Movement limits:
+ *   - maxRadius: limits evasion distance from the button's home anchor.
+ *   - duration: timeout in milliseconds after which evasion gives up and settles.
+ *   - maxAttempts: count limit after which evasion gives up and settles.
+ * - Guaranteed smooth return to default position (0, 0) when disabled or form becomes valid.
+ * - Lifecycle state classes (.is-evading, .is-settled) and events (@evade, @settle, @giveup).
+ * - Accessibility: prefers-reduced-motion auto-detection and Tab+Enter keyboard support.
+ *
+ * @example
+ * import { createApp, ref, computed } from '@wrium/wrium';
+ * import { EvasiveButtonPlugin } from '@wrium/evasive-button';
+ *
+ * createApp(() => {
+ *     const username = ref('');
+ *     const password = ref('');
+ *     const isFormValid = computed(() => username.value.length >= 3 && password.value.length >= 6);
+ *     return { username, password, isFormValid };
+ * })
+ *     .use(EvasiveButtonPlugin)
+ *     .mount('#app');
+ *
+ * <!-- Evasive until fields are filled, then smoothly glides home and settles -->
+ * <button v-evade="{ active: !isFormValid, bounds: '#arena', maxRadius: 150 }" @settle="onSettled">
+ *     Log In
+ * </button>
+ */
+
+/**
+ * Check if user's OS has prefers-reduced-motion enabled.
+ *
+ * @returns {boolean}
+ */
+export function isReducedMotionPreferred() {
+    if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+        return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    }
+    return false;
+}
+
+/**
+ * Check if the cursor is within the proximity threshold of a target bounding rect.
+ *
+ * @param {{ x: number, y: number }} cursor
+ * @param {{ left: number, top: number, width: number, height: number, right?: number, bottom?: number }} targetRect
+ * @param {number} threshold
+ * @returns {{ isNear: boolean, distance: number, center: { x: number, y: number } }}
+ */
+export function isNearTarget(cursor, targetRect, threshold = 80) {
+    const center = {
+        x: targetRect.left + targetRect.width / 2,
+        y: targetRect.top + targetRect.height / 2
+    };
+
+    // Calculate shortest distance from cursor point to element rectangle
+    const nearestX = Math.max(targetRect.left, Math.min(cursor.x, targetRect.left + targetRect.width));
+    const nearestY = Math.max(targetRect.top, Math.min(cursor.y, targetRect.top + targetRect.height));
+    const edgeDist = Math.hypot(cursor.x - nearestX, cursor.y - nearestY);
+
+    return {
+        isNear: edgeDist < threshold,
+        distance: edgeDist,
+        center
+    };
+}
+
+/**
+ * Calculates a new translation offset { x, y } that evades the cursor
+ * while staying strictly within the container bounds and respecting maxRadius.
+ *
+ * Pure function - completely decoupled from DOM mutations for clean testability.
+ *
+ * @param {{ x: number, y: number }} cursor - Cursor coordinates in viewport space
+ * @param {{ width: number, height: number }} elSize - Element dimensions
+ * @param {{ left: number, top: number }} naturalPos - Natural element origin (translate = 0)
+ * @param {{ left: number, top: number, right: number, bottom: number }} bounds - Allowed boundary box
+ * @param {{ x: number, y: number }} currentOffset - Current translation { x, y }
+ * @param {Object} [options]
+ * @param {number} [options.distance=100] - Base leap distance in pixels
+ * @param {number} [options.threshold=80] - Proximity trigger distance in pixels
+ * @param {number} [options.maxRadius] - Maximum allowable distance from home origin (0, 0)
+ * @param {boolean} [options.random=false] - Apply random angle jitter
+ * @returns {{ x: number, y: number, escaped: boolean }}
+ */
+export function calculateEvasionOffset(
+    cursor,
+    elSize,
+    naturalPos,
+    bounds,
+    currentOffset = { x: 0, y: 0 },
+    options = {}
+) {
+    const rawDistance = options.distance ?? 100;
+    const threshold = options.threshold ?? 80;
+    const maxRadius = (typeof options.maxRadius === 'number' && options.maxRadius > 0)
+        ? options.maxRadius
+        : Infinity;
+    const randomJitter = options.random ?? false;
+
+    // Translation limits relative to natural position
+    const minX = bounds.left - naturalPos.left;
+    const maxX = bounds.right - naturalPos.left - elSize.width;
+    const minY = bounds.top - naturalPos.top;
+    const maxY = bounds.bottom - naturalPos.top - elSize.height;
+
+    // Safe clamped ranges (handles tight/reversed bounds)
+    const safeMinX = Math.min(minX, maxX);
+    const safeMaxX = Math.max(minX, maxX);
+    const safeMinY = Math.min(minY, maxY);
+    const safeMaxY = Math.max(minY, maxY);
+
+    const spanX = safeMaxX - safeMinX;
+    const spanY = safeMaxY - safeMinY;
+
+    // Adapt step distance to container dimensions and maxRadius
+    const minSpan = Math.min(spanX, spanY);
+    const maxSpan = Math.max(spanX, spanY);
+    let adaptiveDistance = maxSpan > 0
+        ? Math.min(rawDistance, Math.max(30, Math.min(rawDistance, minSpan > 40 ? minSpan * 0.75 : maxSpan * 0.6)))
+        : 0;
+
+    if (maxRadius !== Infinity) {
+        adaptiveDistance = Math.min(adaptiveDistance, maxRadius * 0.8);
+    }
+
+    // Current visual center
+    const currentCenter = {
+        x: naturalPos.left + currentOffset.x + elSize.width / 2,
+        y: naturalPos.top + currentOffset.y + elSize.height / 2
+    };
+
+    // Vector pointing away from cursor towards element center
+    let vx = currentCenter.x - cursor.x;
+    let vy = currentCenter.y - cursor.y;
+    let d = Math.hypot(vx, vy);
+
+    if (d === 0) {
+        vx = (Math.random() - 0.5) || 1;
+        vy = (Math.random() - 0.5) || 1;
+        d = Math.hypot(vx, vy);
+    }
+
+    let ux = vx / d;
+    let uy = vy / d;
+
+    if (randomJitter) {
+        const jitterAngle = (Math.random() - 0.5) * (Math.PI / 4);
+        const cosJ = Math.cos(jitterAngle);
+        const sinJ = Math.sin(jitterAngle);
+        const nux = ux * cosJ - uy * sinJ;
+        const nuy = ux * sinJ + uy * cosJ;
+        ux = nux;
+        uy = nuy;
+    }
+
+    // Step 1: Direct Flee with Tangential Deflection (Wall Sliding)
+    const stepX = ux * adaptiveDistance;
+    const stepY = uy * adaptiveDistance;
+
+    let targetX = currentOffset.x + stepX;
+    let targetY = currentOffset.y + stepY;
+
+    // Boundary collision handling: deflect overflow into sliding along the open wall
+    if (targetX > safeMaxX) {
+        const overflow = targetX - safeMaxX;
+        targetX = safeMaxX;
+        const dirY = uy !== 0 ? Math.sign(uy) : (currentCenter.y >= cursor.y ? 1 : -1);
+        targetY += dirY * overflow * 0.85;
+    } else if (targetX < safeMinX) {
+        const overflow = safeMinX - targetX;
+        targetX = safeMinX;
+        const dirY = uy !== 0 ? Math.sign(uy) : (currentCenter.y >= cursor.y ? 1 : -1);
+        targetY += dirY * overflow * 0.85;
+    }
+
+    if (targetY > safeMaxY) {
+        const overflow = targetY - safeMaxY;
+        targetY = safeMaxY;
+        const dirX = ux !== 0 ? Math.sign(ux) : (currentCenter.x >= cursor.x ? 1 : -1);
+        targetX += dirX * overflow * 0.85;
+    } else if (targetY < safeMinY) {
+        const overflow = safeMinY - targetY;
+        targetY = safeMinY;
+        const dirX = ux !== 0 ? Math.sign(ux) : (currentCenter.x >= cursor.x ? 1 : -1);
+        targetX += dirX * overflow * 0.85;
+    }
+
+    // Apply maxRadius constraint from natural origin (0, 0)
+    if (maxRadius !== Infinity) {
+        const distFromOrigin = Math.hypot(targetX, targetY);
+        if (distFromOrigin > maxRadius) {
+            const scale = maxRadius / distFromOrigin;
+            targetX *= scale;
+            targetY *= scale;
+        }
+    }
+
+    // Ensure within boundary limits
+    targetX = Math.max(safeMinX, Math.min(safeMaxX, targetX));
+    targetY = Math.max(safeMinY, Math.min(safeMaxY, targetY));
+
+    // Step 2: Anti-Stuck Corner Escape
+    // If trapped in a corner or pinned against a wall (effective displacement < 15px),
+    // evaluate smooth sliding paths along open perimeter walls rather than freezing or teleporting.
+    const moveDist = Math.hypot(targetX - currentOffset.x, targetY - currentOffset.y);
+
+    if (moveDist < 15 && (spanX > 0 || spanY > 0)) {
+        const escapeCandidates = [];
+
+        // Slide horizontally along wall
+        if (spanX > 0) {
+            escapeCandidates.push({
+                x: Math.max(safeMinX, Math.min(safeMaxX, currentOffset.x + adaptiveDistance)),
+                y: currentOffset.y
+            });
+            escapeCandidates.push({
+                x: Math.max(safeMinX, Math.min(safeMaxX, currentOffset.x - adaptiveDistance)),
+                y: currentOffset.y
+            });
+        }
+
+        // Slide vertically along wall
+        if (spanY > 0) {
+            escapeCandidates.push({
+                x: currentOffset.x,
+                y: Math.max(safeMinY, Math.min(safeMaxY, currentOffset.y + adaptiveDistance))
+            });
+            escapeCandidates.push({
+                x: currentOffset.x,
+                y: Math.max(safeMinY, Math.min(safeMaxY, currentOffset.y - adaptiveDistance))
+            });
+        }
+
+        // Diagonal perimeter glides away from corner
+        if (spanX > 0 && spanY > 0) {
+            escapeCandidates.push({
+                x: Math.max(safeMinX, Math.min(safeMaxX, currentOffset.x + adaptiveDistance * 0.7)),
+                y: Math.max(safeMinY, Math.min(safeMaxY, currentOffset.y + adaptiveDistance * 0.7))
+            });
+            escapeCandidates.push({
+                x: Math.max(safeMinX, Math.min(safeMaxX, currentOffset.x - adaptiveDistance * 0.7)),
+                y: Math.max(safeMinY, Math.min(safeMaxY, currentOffset.y - adaptiveDistance * 0.7))
+            });
+            escapeCandidates.push({
+                x: Math.max(safeMinX, Math.min(safeMaxX, currentOffset.x + adaptiveDistance * 0.7)),
+                y: Math.max(safeMinY, Math.min(safeMaxY, currentOffset.y - adaptiveDistance * 0.7))
+            });
+            escapeCandidates.push({
+                x: Math.max(safeMinX, Math.min(safeMaxX, currentOffset.x - adaptiveDistance * 0.7)),
+                y: Math.max(safeMinY, Math.min(safeMaxY, currentOffset.y + adaptiveDistance * 0.7))
+            });
+        }
+
+        let bestCandidate = null;
+        let maxCandidateDist = -Infinity;
+
+        for (const cand of escapeCandidates) {
+            // Apply maxRadius constraint to candidate
+            if (maxRadius !== Infinity) {
+                const candR = Math.hypot(cand.x, cand.y);
+                if (candR > maxRadius) {
+                    cand.x *= maxRadius / candR;
+                    cand.y *= maxRadius / candR;
+                }
+            }
+
+            cand.x = Math.max(safeMinX, Math.min(safeMaxX, cand.x));
+            cand.y = Math.max(safeMinY, Math.min(safeMaxY, cand.y));
+
+            const candMoveDist = Math.hypot(cand.x - currentOffset.x, cand.y - currentOffset.y);
+            if (candMoveDist >= 15) {
+                const candCenter = {
+                    x: naturalPos.left + cand.x + elSize.width / 2,
+                    y: naturalPos.top + cand.y + elSize.height / 2
+                };
+                const distFromCursor = Math.hypot(candCenter.x - cursor.x, candCenter.y - cursor.y);
+                if (distFromCursor > maxCandidateDist) {
+                    maxCandidateDist = distFromCursor;
+                    bestCandidate = cand;
+                }
+            }
+        }
+
+        if (bestCandidate) {
+            targetX = bestCandidate.x;
+            targetY = bestCandidate.y;
+        }
+    }
+
+    const finalCenter = {
+        x: naturalPos.left + targetX + elSize.width / 2,
+        y: naturalPos.top + targetY + elSize.height / 2
+    };
+    const finalDistFromCursor = Math.hypot(finalCenter.x - cursor.x, finalCenter.y - cursor.y);
+
+    return {
+        x: Math.round(targetX),
+        y: Math.round(targetY),
+        escaped: finalDistFromCursor >= threshold
+    };
+}
+
+/**
+ * Resolve the bounding box to constrain element movement within.
+ *
+ * @param {HTMLElement} el
+ * @param {'parent'|'viewport'|string} [boundsType='parent']
+ * @returns {{ left: number, top: number, right: number, bottom: number, width: number, height: number }}
+ */
+export function getBoundingContainer(el, boundsType = 'parent') {
+    const defaultW = typeof window !== 'undefined' && window.innerWidth ? window.innerWidth : 1024;
+    const defaultH = typeof window !== 'undefined' && window.innerHeight ? window.innerHeight : 768;
+
+    if (boundsType === 'viewport' || typeof window === 'undefined') {
+        const padding = 12;
+        return {
+            left: padding,
+            top: padding,
+            right: defaultW - padding,
+            bottom: defaultH - padding,
+            width: defaultW - 2 * padding,
+            height: defaultH - 2 * padding
+        };
+    }
+
+    let container = null;
+    if (typeof boundsType === 'string' && boundsType !== 'parent') {
+        container = document.querySelector(boundsType);
+    }
+    if (!container) {
+        container = el.offsetParent || el.parentElement || document.body;
+    }
+
+    const r = container ? container.getBoundingClientRect() : { left: 0, top: 0, right: defaultW, bottom: defaultH };
+    const w = (container ? container.clientWidth : 0) || r.width || defaultW;
+    const h = (container ? container.clientHeight : 0) || r.height || defaultH;
+
+    // Safety margin inside container so the button never clips borders
+    const pad = 6;
+    return {
+        left: (r.left || 0) + pad,
+        top: (r.top || 0) + pad,
+        right: (r.right || (r.left + w)) - pad,
+        bottom: (r.bottom || (r.top + h)) - pad,
+        width: Math.max(0, w - 2 * pad),
+        height: Math.max(0, h - 2 * pad)
+    };
+}
+
+/**
+ * Creates the directive handler for `v-evade` / `v-evasive`.
+ */
+function createEvadeDirective(pluginOptions = {}) {
+    return (el, exp, { scope, cs, evalExp, watchEffect, arg, modifiers }) => {
+        let attempts = 0;
+        let currentTranslate = { x: 0, y: 0 };
+        let naturalRect = null;
+        let lastEvadeTime = 0;
+        let evasionStartTime = null;
+        let hasGivenUp = false;
+        let settleTimer = null;
+        const COOLDOWN_MS = 130; // Minimum time between proximity triggers for smooth fluid motion
+
+        const isTeleport = modifiers.teleport || pluginOptions.teleport;
+        // Fluid, natural easing curve
+        const transitionDuration = isTeleport ? 0 : 280;
+        const transitionStyle = isTeleport
+            ? 'none'
+            : `transform ${transitionDuration / 1000}s cubic-bezier(0.25, 1, 0.5, 1)`;
+
+        el.style.willChange = 'transform';
+        el.style.transition = transitionStyle;
+
+        // Initial state
+        function setButtonState(state) {
+            el.dataset.state = state;
+            el.dataset.evading = state === 'evading' ? 'true' : 'false';
+            if (state === 'evading') {
+                el.classList.add('is-evading');
+                el.classList.remove('is-settled');
+            } else if (state === 'settled') {
+                el.classList.remove('is-evading');
+                el.classList.add('is-settled');
+            } else if (state === 'gaveup') {
+                el.classList.remove('is-evading');
+                el.classList.add('is-settled');
+            }
+        }
+
+        setButtonState('settled');
+
+        function resolveContainerElement() {
+            if (config.bounds === 'viewport') return null;
+            if (typeof config.bounds === 'string' && config.bounds !== 'parent') {
+                const found = document.querySelector(config.bounds);
+                if (found) return found;
+            }
+            return el.offsetParent || el.parentElement || document.body;
+        }
+
+        // Measure natural position dynamically without layout shift or scroll drift
+        function getNaturalPosition() {
+            const currentW = el.offsetWidth || (naturalRect ? naturalRect.width : 100);
+            const currentH = el.offsetHeight || (naturalRect ? naturalRect.height : 36);
+            const containerEl = resolveContainerElement();
+
+            if (containerEl && containerEl !== document.body) {
+                const cRect = containerEl.getBoundingClientRect();
+                let ox = 0;
+                let oy = 0;
+                let curr = el;
+                while (curr && curr !== containerEl && curr !== document.body) {
+                    ox += curr.offsetLeft || 0;
+                    oy += curr.offsetTop || 0;
+                    curr = curr.offsetParent;
+                }
+                naturalRect = {
+                    left: cRect.left + ox,
+                    top: cRect.top + oy,
+                    width: currentW,
+                    height: currentH
+                };
+                return naturalRect;
+            }
+
+            // Fallback for viewport or document.body
+            const r = el.getBoundingClientRect();
+            naturalRect = {
+                left: r.left - currentTranslate.x,
+                top: r.top - currentTranslate.y,
+                width: currentW,
+                height: currentH
+            };
+            return naturalRect;
+        }
+
+        // Configuration resolution (reactively updated if expression is used)
+        let active = true;
+        let config = {
+            threshold: pluginOptions.threshold ?? 75,
+            distance: pluginOptions.distance ?? 100,
+            maxRadius: pluginOptions.maxRadius ?? Infinity,
+            duration: pluginOptions.duration ?? Infinity,
+            bounds: arg || pluginOptions.bounds || (modifiers.viewport ? 'viewport' : 'parent'),
+            random: modifiers.random || pluginOptions.random || false,
+            maxAttempts: pluginOptions.maxAttempts ?? Infinity,
+            allowKeyboard: pluginOptions.allowKeyboard ?? true,
+            respectReducedMotion: pluginOptions.respectReducedMotion ?? true,
+            onEvade: null,
+            onSettle: null,
+            onGiveup: null
+        };
+
+        // Smooth return to default (0, 0) position with .is-settled state
+        function resetPosition(reason = 'disabled') {
+            currentTranslate = { x: 0, y: 0 };
+            el.style.transition = transitionStyle;
+            el.style.transform = 'translate(0px, 0px)';
+
+            if (settleTimer) clearTimeout(settleTimer);
+            settleTimer = setTimeout(() => {
+                if (hasGivenUp) {
+                    setButtonState('gaveup');
+                } else {
+                    setButtonState('settled');
+                }
+
+                if (typeof config.onSettle === 'function') {
+                    config.onSettle({ attempts, reason });
+                }
+
+                el.dispatchEvent(
+                    new CustomEvent('settle', {
+                        bubbles: true,
+                        cancelable: true,
+                        detail: { attempts, reason }
+                    })
+                );
+            }, transitionDuration);
+        }
+
+        let durationTimer = null;
+
+        function startDurationTimer() {
+            clearDurationTimer();
+            if (config.duration === Infinity || !active || hasGivenUp) return;
+
+            const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+            if (evasionStartTime === null) {
+                evasionStartTime = now;
+            }
+            const elapsed = now - evasionStartTime;
+            const remaining = Math.max(0, config.duration - elapsed);
+
+            durationTimer = setTimeout(() => {
+                durationTimer = null;
+                if (active && !hasGivenUp) {
+                    triggerGiveup('duration');
+                }
+            }, remaining);
+        }
+
+        function clearDurationTimer() {
+            if (durationTimer) {
+                clearTimeout(durationTimer);
+                durationTimer = null;
+            }
+        }
+
+        function triggerGiveup(reason) {
+            clearDurationTimer();
+            hasGivenUp = true;
+            setButtonState('gaveup');
+
+            if (typeof config.onGiveup === 'function') {
+                config.onGiveup({ reason, attempts });
+            }
+
+            el.dispatchEvent(
+                new CustomEvent('giveup', {
+                    bubbles: true,
+                    cancelable: true,
+                    detail: { reason, attempts }
+                })
+            );
+
+            resetPosition(reason);
+        }
+
+        let previousDuration = config.duration;
+        let lastResetKey = undefined;
+
+        // Handle expression binding (boolean flag, config object, or ref)
+        if (exp && exp.trim()) {
+            cs.addEffect(watchEffect(() => {
+                const val = evalExp(exp, scope);
+
+                if (typeof val === 'boolean') {
+                    active = val;
+                } else if (typeof val === 'number') {
+                    active = true;
+                } else if (val && typeof val === 'object') {
+                    if ('active' in val) active = Boolean(val.active);
+                    if ('threshold' in val) config.threshold = val.threshold;
+                    if ('distance' in val) config.distance = val.distance;
+                    if ('maxRadius' in val) config.maxRadius = val.maxRadius;
+                    if ('duration' in val) config.duration = val.duration;
+                    if ('bounds' in val) config.bounds = val.bounds;
+                    if ('random' in val) config.random = Boolean(val.random);
+                    if ('maxAttempts' in val) config.maxAttempts = val.maxAttempts;
+                    if ('allowKeyboard' in val) config.allowKeyboard = Boolean(val.allowKeyboard);
+                    if ('respectReducedMotion' in val) config.respectReducedMotion = Boolean(val.respectReducedMotion);
+                    if ('onEvade' in val) config.onEvade = val.onEvade;
+                    if ('onSettle' in val) config.onSettle = val.onSettle;
+                    if ('onGiveup' in val) config.onGiveup = val.onGiveup;
+
+                    // Manual reset trigger via resetKey
+                    if ('resetKey' in val && val.resetKey !== lastResetKey) {
+                        lastResetKey = val.resetKey;
+                        clearDurationTimer();
+                        evasionStartTime = null;
+                        hasGivenUp = false;
+                        attempts = 0;
+                        setButtonState('settled');
+                    }
+                } else {
+                    active = Boolean(val);
+                }
+
+                // If duration configuration changed, reset timer state
+                if (config.duration !== previousDuration) {
+                    previousDuration = config.duration;
+                    clearDurationTimer();
+                    evasionStartTime = null;
+                    hasGivenUp = false;
+                    attempts = 0;
+                    setButtonState('settled');
+                }
+
+                // If active toggled from false back to true, reset given-up state
+                if (active) {
+                    if (hasGivenUp) {
+                        hasGivenUp = false;
+                        evasionStartTime = null;
+                        attempts = 0;
+                    }
+                } else {
+                    clearDurationTimer();
+                    resetPosition('disabled');
+                }
+            }));
+        }
+
+        function triggerEvade(cursor, source = 'proximity') {
+            if (!active || hasGivenUp) return false;
+
+            // Accessibility: Respect prefers-reduced-motion
+            if (config.respectReducedMotion && isReducedMotionPreferred()) {
+                return false;
+            }
+
+            const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+
+            // Track duration limit with active timer
+            if (config.duration !== Infinity) {
+                if (evasionStartTime === null) {
+                    evasionStartTime = now;
+                    startDurationTimer();
+                } else if (now - evasionStartTime >= config.duration) {
+                    triggerGiveup('duration');
+                    return false;
+                }
+            }
+
+            // Track maxAttempts limit
+            if (attempts >= config.maxAttempts) {
+                triggerGiveup('maxAttempts');
+                return false;
+            }
+
+            // Proximity triggers respect cooldown to allow transitions to complete smoothly
+            if (source === 'proximity' && (now - lastEvadeTime < COOLDOWN_MS)) {
+                return false;
+            }
+
+            const nat = getNaturalPosition();
+            const container = getBoundingContainer(el, config.bounds);
+
+            const safeCursor = {
+                x: (cursor && typeof cursor.x === 'number' && !isNaN(cursor.x))
+                    ? cursor.x
+                    : (nat.left + currentTranslate.x + nat.width / 2),
+                y: (cursor && typeof cursor.y === 'number' && !isNaN(cursor.y))
+                    ? cursor.y
+                    : (nat.top + currentTranslate.y + nat.height / 2)
+            };
+
+            const nextOffset = calculateEvasionOffset(
+                safeCursor,
+                { width: nat.width, height: nat.height },
+                { left: nat.left, top: nat.top },
+                container,
+                currentTranslate,
+                {
+                    distance: config.distance,
+                    threshold: config.threshold,
+                    maxRadius: config.maxRadius,
+                    random: config.random
+                }
+            );
+
+            // Calculate actual displacement. If button cannot move further away (blocked/at limit), do nothing
+            const moveDelta = Math.hypot(nextOffset.x - currentTranslate.x, nextOffset.y - currentTranslate.y);
+            if (moveDelta < 4) {
+                return false;
+            }
+
+            lastEvadeTime = now;
+            const dx = nextOffset.x - currentTranslate.x;
+            const dy = nextOffset.y - currentTranslate.y;
+            currentTranslate = { x: nextOffset.x, y: nextOffset.y };
+            attempts++;
+
+            // Update state
+            setButtonState('evading');
+
+            el.style.transition = transitionStyle;
+            el.style.transform = `translate(${nextOffset.x}px, ${nextOffset.y}px)`;
+
+            // Update write-back ref if expression points directly to a ref holding attempts
+            const targetRef = scope[exp];
+            if (targetRef && targetRef._isRef && typeof targetRef.value === 'number') {
+                targetRef.value = attempts;
+            }
+
+            const eventDetail = {
+                attempts,
+                x: nextOffset.x,
+                y: nextOffset.y,
+                dx,
+                dy,
+                source
+            };
+
+            if (typeof config.onEvade === 'function') {
+                config.onEvade(eventDetail);
+            }
+
+            // Dispatch custom evade event
+            el.dispatchEvent(
+                new CustomEvent('evade', {
+                    bubbles: true,
+                    cancelable: true,
+                    detail: eventDetail
+                })
+            );
+
+            return true;
+        }
+
+        // Pointer proximity detection with zero layout thrashing
+        const onPointerMove = e => {
+            if (!active || hasGivenUp) return;
+
+            const cx = typeof e.clientX === 'number' ? e.clientX : 0;
+            const cy = typeof e.clientY === 'number' ? e.clientY : 0;
+
+            const nat = getNaturalPosition();
+            const currentRect = {
+                left: nat.left + currentTranslate.x,
+                top: nat.top + currentTranslate.y,
+                width: nat.width,
+                height: nat.height,
+                right: nat.left + currentTranslate.x + nat.width,
+                bottom: nat.top + currentTranslate.y + nat.height
+            };
+
+            const { isNear } = isNearTarget(
+                { x: cx, y: cy },
+                currentRect,
+                config.threshold
+            );
+
+            if (isNear) {
+                triggerEvade({ x: cx, y: cy }, 'proximity');
+            }
+        };
+
+        // Pointer enter (cursor flicked fast into element)
+        const onPointerEnter = e => {
+            if (!active || hasGivenUp) return;
+            const cx = typeof e.clientX === 'number' ? e.clientX : undefined;
+            const cy = typeof e.clientY === 'number' ? e.clientY : undefined;
+            triggerEvade({ x: cx, y: cy }, 'enter');
+        };
+
+        // Intercept mouse click / pointerdown attempts
+        const onPointerDown = e => {
+            if (!active || hasGivenUp) return;
+
+            if (e.pointerType === 'mouse' || e.pointerType === 'touch' || e.pointerType === 'pen' || e.clientX !== 0 || e.clientY !== 0) {
+                e.preventDefault();
+                e.stopPropagation();
+                const cx = typeof e.clientX === 'number' ? e.clientX : undefined;
+                const cy = typeof e.clientY === 'number' ? e.clientY : undefined;
+                triggerEvade({ x: cx, y: cy }, 'click_attempt');
+            }
+        };
+
+        const onClick = e => {
+            if (!active || hasGivenUp) return;
+
+            // Synthetic click triggered with mouse cursor
+            if (e.clientX !== 0 || e.clientY !== 0 || e.detail > 0) {
+                if (e.pointerType !== '') {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    triggerEvade({ x: e.clientX, y: e.clientY }, 'click_attempt');
+                }
+            } else if (!config.allowKeyboard) {
+                e.preventDefault();
+                e.stopPropagation();
+                const rect = el.getBoundingClientRect();
+                triggerEvade({ x: rect.left, y: rect.top }, 'keyboard_attempt');
+            }
+        };
+
+        const onResize = () => {
+            naturalRect = null;
+        };
+
+        // Attach listeners with automatic scope cleanup
+        window.addEventListener('pointermove', onPointerMove, { passive: true });
+        el.addEventListener('pointerenter', onPointerEnter);
+        el.addEventListener('pointerdown', onPointerDown);
+        el.addEventListener('click', onClick);
+        window.addEventListener('resize', onResize);
+
+        cs.addListener(window, 'pointermove', onPointerMove);
+        cs.addListener(el, 'pointerenter', onPointerEnter);
+        cs.addListener(el, 'pointerdown', onPointerDown);
+        cs.addListener(el, 'click', onClick);
+        cs.addListener(window, 'resize', onResize);
+    };
+}
+
+/**
+ * EvasiveButtonPlugin definition for Wrium.
+ */
+export const EvasiveButtonPlugin = {
+    install(api, options = {}) {
+        const handler = createEvadeDirective(options);
+        api.directive('evade', handler);
+        api.directive('evasive', handler);
+    }
+};
+
+/**
+ * Convenient aliases
+ */
+export const EvadePlugin = EvasiveButtonPlugin;
+export const EvasivePlugin = EvasiveButtonPlugin;
+export default EvasiveButtonPlugin;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@wrium/evasive-button",
+  "version": "1.0.0",
+  "description": "A fun evasive button plugin for Wrium - causes buttons to playfully dodge the cursor when clicked or hovered.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "dist/types"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wrium/wrium-evasive-button.git"
+  },
+  "homepage": "https://github.com/wrium/wrium-evasive-button#readme",
+  "bugs": {
+    "url": "https://github.com/wrium/wrium-evasive-button/issues"
+  },
+  "peerDependencies": {
+    "@wrium/wrium": "^1.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "@wrium/wrium": "^1.0.0",
+    "jsdom": "^27.3.0",
+    "typescript": "^7.0.2",
+    "vite": "^7.2.4",
+    "vitest": "^4.0.15"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -p tsconfig.json",
+    "build:types": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "prepublishOnly": "npm run test && npm run test:e2e && npm run build:types"
+  },
+  "keywords": [
+    "wrium",
+    "wrium-plugin",
+    "evasive-button",
+    "runaway-button",
+    "fun-ui"
+  ],
+  "author": "Benjamin Khalife",
+  "license": "MIT"
+}