Adding usePresence and bumping version

Author: MattStellisoft

README.md

@@ -67,6 +67,7 @@ Vue-reactive modules. Use inside `<script setup>` or `setup()`.
 | Data fetching | usePagination, useInfiniteScroll, useLiveData, useLazyLoad |
 | State | useQueryState |
 | Auth & Chat | useAuth, useChat |
+| Collaboration | usePresence |
 | Routing | useRouter |
 
 ## File Uploads
@@ -256,6 +257,67 @@ router.navigate('/users/123')
 // Reactive: router.currentPath, router.params
 ```
 
+### usePresence
+
+Real-time collaborative presence: who's here, where their cursor is, what they're focused on.
+
+```javascript
+import { usePresence } from 'stellify-framework'
+
+const { users, cursor, focus } = usePresence({
+  channel: 'customers',
+  user: { id: currentUser.id, name: currentUser.name },
+})
+```
+
+Wire `cursor` to a `@mousemove` handler. Wire `focus(key)` to row hover or field focus. Other connected users appear in `users` with their cursor positions, focus state, and metadata.
+
+```vue
+<template>
+  <div @mousemove="cursor" class="relative">
+    <div v-for="row in rows" :key="row.id"
+         @mouseenter="focus(row.id)"
+         @mouseleave="focus(null)">
+      {{ row.name }}
+      <span v-if="users.find(u => u.focus === row.id)">
+        {{ users.find(u => u.focus === row.id).name }} viewing
+      </span>
+    </div>
+    <UserCursor v-for="user in users" :key="user.id" :user="user" />
+  </div>
+</template>
+```
+
+Pairs with Laravel Reverb / Pusher on the backend. Channel name should match a presence channel defined in `routes/channels.php`.
+
+**Options:**
+- `channel` (required) - Laravel broadcast channel name
+- `user` (required) - `{ id, ...metadata }` current user's identity
+- `autoJoin` - Join on mount (default: true)
+- `throttleMs` - Cursor broadcast throttle (default: 50ms)
+
+**Returns:**
+- `users` - `ComputedRef<PresenceUser[]>` other users present (excludes self)
+- `self` - `Ref<PresenceUser | null>` current user's presence record
+- `cursor` - `(event: MouseEvent) => void` call from @mousemove
+- `focus` - `(key: string | null) => void` broadcast focus state
+- `setMeta` - `(meta: Record<string, unknown>) => void` broadcast arbitrary metadata
+- `isConnected` - `Ref<boolean>` WebSocket connection state
+- `error` - `Ref<Error | null>` connection errors
+- `join` / `leave` - Manual channel control
+
+**PresenceUser shape:**
+```typescript
+{
+  id: string | number
+  joinedAt: number
+  cursor: { x: number; y: number } | null
+  focus: string | null
+  meta: Record<string, unknown>
+  // ...additional fields from user config
+}
+```
+
 ## Design Principles
 
 1. **Chainable APIs** - Fluent method chaining for readable code

dist/composables/usePresence/channel.d.ts

@@ -0,0 +1,96 @@
+import type { PresenceUser, PresenceOptions, CursorMessage, FocusMessage, MetaMessage } from './types';
+/**
+ * Channel event handlers interface
+ */
+export interface ChannelHandlers {
+    onSubscribed: (members: Map<string | number, PresenceUser>, self: PresenceUser) => void;
+    onMemberAdded: (user: PresenceUser) => void;
+    onMemberRemoved: (userId: string | number) => void;
+    onCursor: (message: CursorMessage) => void;
+    onFocus: (message: FocusMessage) => void;
+    onMeta: (message: MetaMessage) => void;
+    onConnected: () => void;
+    onDisconnected: () => void;
+    onError: (error: Error) => void;
+}
+/**
+ * Presence channel manager
+ * Handles channel subscription, message routing, and client broadcasts
+ */
+export declare class PresenceChannel {
+    private socket;
+    private channelName;
+    private user;
+    private handlers;
+    private socketUrl;
+    private isSubscribed;
+    constructor(options: PresenceOptions, handlers: ChannelHandlers);
+    /**
+     * Auto-detect Reverb WebSocket URL
+     */
+    private getDefaultSocketUrl;
+    /**
+     * Connect to socket and subscribe to presence channel
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect and cleanup
+     */
+    disconnect(): void;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Broadcast cursor position to channel
+     */
+    whisperCursor(x: number, y: number): void;
+    /**
+     * Broadcast focus state to channel
+     */
+    whisperFocus(focus: string | null): void;
+    /**
+     * Broadcast meta state to channel
+     */
+    whisperMeta(meta: Record<string, unknown>): void;
+    /**
+     * Handle socket connection opened
+     */
+    private handleOpen;
+    /**
+     * Handle socket connection closed
+     */
+    private handleClose;
+    /**
+     * Handle socket error
+     */
+    private handleError;
+    /**
+     * Handle successful channel subscription
+     */
+    private handleSubscribed;
+    /**
+     * Handle member joining channel
+     */
+    private handleMemberAdded;
+    /**
+     * Handle member leaving channel
+     */
+    private handleMemberRemoved;
+    /**
+     * Handle cursor broadcast from another user
+     */
+    private handleCursor;
+    /**
+     * Handle focus broadcast from another user
+     */
+    private handleFocus;
+    /**
+     * Handle meta broadcast from another user
+     */
+    private handleMeta;
+    /**
+     * Create a PresenceUser from user info
+     */
+    private createPresenceUser;
+}