@meistrari/tela-build 1.68.0 → 1.69.0

package/components/tela/presence/presence-avatars.mdx

@@ -0,0 +1,123 @@
+# TelaPresenceAvatars
+
+Shows who else is currently viewing the same page. Two variants:
+
+- **`pill`** (default): a "N Viewing" count followed by up to `max` overlapping round avatars on a `bg-muted` pill (8px radius, 4px vertical / 10px left / 8px right padding). Hovering the count lists viewer names (up to `tooltipMax`, then a "x more" line).
+- **`avatars`**: just the overlapping avatar stack — no count label, no pill surface — at a larger default size (`xs`, 24px). Meant for page headers (canvas, workflow, agent) where the count pill is too heavy. When more than `max` viewers are present, the last visible avatar gets an 80% `neutral-950` mask with a white "+N" count on top (no extra bubble); hovering it shows the same tooltip as the pill count (up to `tooltipMax` names, then the "x more" line).
+
+Hovering an avatar shows the viewer's name and live status on separate lines: `Viewing now`, or for away viewers a relative time like "3 min ago" when `awaySinceLabel` is provided (falling back to the plain `awayLabel`). All tooltips share one `TelaTooltipGroup`, so moving between triggers skips the open delay instead of re-animating each tooltip. Viewers with `active: false` (page open, tab hidden) render dimmed instead of disappearing. Renders nothing when the viewers list is empty, so mount points need no guards.
+
+Overlapping avatars are separated with a `mask-image` radial-gradient (the tags-select dot technique): each avatar except the last carves a transparent 2px crescent where the next avatar overlaps, so the gap shows whatever is behind the stack instead of a hardcoded ring color. Overlap scales with avatar size (16px→4px, 24px→6px, 32px→8px, 40px→10px).
+
+Pair it with the `usePresence` composable, which joins a Yjs awareness room over websockets (channel switching, hard stop on repeated connection failures) and exposes the other viewers as `PresenceViewer[]` — deduped per user across tabs, sorted with active viewers first, then by join time, so people who tab away drop to the back of the stack and active viewers hold the visible slots. The connection stays open while the tab is hidden; the composable publishes `active: false` so peers dim and demote the avatar rather than dropping it. The consuming app provides the websocket `url`, the auth `getToken`, and the local `self` identity.
+
+The component is i18n-free: pass pre-translated `countLabel`, `viewingLabel`, `awayLabel`, and `moreLabel` strings, and the `awaySinceLabel` formatter, from the app layer.
+
+## Examples
+
+### Basic Usage
+
+```vue
+<TelaPresenceAvatars
+  :viewers="[
+    { name: 'Ada Lovelace', email: 'ada@example.com', image: 'https://example.com/ada.jpg' },
+    { name: 'Grace Hopper', email: 'grace@example.com' },
+  ]"
+  count-label="2 Viewing"
+/>
+```
+
+### Avatars-only variant
+
+No count label, no pill chrome, larger avatars (defaults to `xs` / 24px). Used inside canvas, workflow, and agent headers. Overflow beyond `max` darkens the last visible avatar with an 80% mask and a "+N" count, with the name-list tooltip on hover.
+
+```vue
+<TelaPresenceAvatars
+  variant="avatars"
+  :viewers="others"
+  label="Viewing this canvas"
+/>
+```
+
+### Away viewers
+
+A viewer with `active: false` renders at reduced opacity, moves behind the active viewers (`usePresence` sorts active-first), and their tooltip status switches to `awaySinceLabel(viewer.awaySince)` (e.g. "3 min ago") or the `awayLabel` when no timestamp/formatter is available. `usePresence` publishes `awaySince` when the tab goes hidden and clears it on return; pass a formatter that reads a reactive clock (e.g. `useNow`) so the label stays fresh while the tooltip is open.
+
+```vue
+<TelaPresenceAvatars
+  :viewers="[
+    { name: 'Ada Lovelace', email: 'ada@example.com' },
+    { name: 'Grace Hopper', email: 'grace@example.com', active: false },
+  ]"
+  count-label="2 Viewing"
+  viewing-label="Viewing now"
+  away-label="Away"
+/>
+```
+
+### Overflow
+
+Only the first `max` viewers render as avatars (priority to active viewers, then the earliest joiners — the input order). The count tooltip lists up to `tooltipMax` emails, then a final "x more" line built with `moreLabel`.
+
+```vue
+<TelaPresenceAvatars
+  :viewers="manyViewers"
+  :max="3"
+  :tooltip-max="7"
+  count-label="9 Viewing"
+  :more-label="count => `${count} more`"
+/>
+```
+
+### With usePresence
+
+The composable joins the live-collaboration room for the channel; `others` is already sorted (active first, then join time) and feeds straight into the component.
+
+```ts
+const { others } = usePresence({
+  channel: computed(() => `prompt:${route.params.promptId}`),
+  url: 'wss://collab.example.com',
+  self: computed(() => ({ id: user.id, email: user.email, name: user.name, image: user.image })),
+  getToken: async () => await auth.getToken(),
+})
+```
+
+```vue
+<TelaPresenceAvatars
+  :viewers="others"
+  :count-label="`${others.length} Viewing`"
+  label="Viewing this canvas"
+/>
+```
+
+## Props
+
+| Prop           | Type                                                                                        | Default               | Description                                                              |
+| -------------- | ------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------ |
+| `viewers`      | `{ name?: string, email?: string, image?: string, active?: boolean, joinedAt?: number \| null }[]` | required      | The other people in the room, pre-sorted (`usePresence` output)          |
+| `max`          | `number`                                                                                    | `3`                   | Visible avatar slots                                                     |
+| `tooltipMax`   | `number`                                                                                    | `7`                   | Names listed in the count tooltip before the "x more" line               |
+| `variant`      | `'pill' \| 'avatars'`                                                                       | `'pill'`              | `pill` shows the count on a muted surface; `avatars` is just the stack   |
+| `size`         | `'2xs' \| 'xs' \| 'sm' \| 'md'`                                                             | `'2xs'` pill / `'xs'` avatars | Avatar size                                                      |
+| `label`        | `string`                                                                                    | `'Viewing this page'` | aria-label suffix; pass a translated string                              |
+| `countLabel`   | `string`                                                                                    | viewer count          | Pre-translated count text, e.g. "3 Viewing" (pill variant only)          |
+| `viewingLabel` | `string`                                                                                    | `'Viewing now'`       | Status word in the avatar tooltip for active viewers                     |
+| `awayLabel`    | `string`                                                                                    | `'Away'`              | Status word in the avatar tooltip for hidden-tab viewers                 |
+| `awaySinceLabel` | `(awaySince: number) => string`                                                           | —                     | Formats the away timestamp (e.g. "3 min ago"); falls back to `awayLabel` |
+| `moreLabel`    | `(count: number) => string`                                                                 | `` count => `${count} more` `` | Builds the overflow line in the count tooltip                    |
+
+## Features
+
+- Pill variant surface: `bg-muted`, 8px radius, 4px vertical / 10px left / 8px right padding, `body-12-medium` count text
+- Overlapping avatars separated by a mask-carved 2px transparent crescent (no hardcoded ring color), overlap proportional to avatar size
+- Falls back to initials when a viewer has no image (via `TelaAvatar`)
+- Count tooltip lists viewer names (capped at `tooltipMax` + "x more"); avatar tooltip stacks the name and Viewing/Away status on separate lines
+- Shared `TelaTooltipGroup`: hovering across triggers skips the tooltip delay/animation
+- Away viewers (`active: false`) dim the avatar to 50% with a 160ms transition and reorder to the back of the stack instead of leaving
+- Subtle 160ms enter/leave/move transitions when viewers join, drop off, or reorder
+- Empty viewers list renders nothing
+
+## Accessibility
+
+- Container exposes `role="group"` with an `aria-label` of `"{count} {label}"`
+- Each avatar's accessible name comes from its `alt` (viewer name or email)

package/components/tela/presence/presence-avatars.vue

@@ -0,0 +1,192 @@
+<script setup lang="ts">
+export type PresenceAvatarSize = '2xs' | 'xs' | 'sm' | 'md'
+export type PresenceAvatarsVariant = 'pill' | 'avatars'
+
+export interface PresenceAvatarViewer {
+    name?: string
+    email?: string
+    image?: string
+    active?: boolean
+    joinedAt?: number | null
+    awaySince?: number | null
+}
+
+const props = withDefaults(defineProps<{
+    viewers: PresenceAvatarViewer[]
+    max?: number
+    tooltipMax?: number
+    size?: PresenceAvatarSize
+    variant?: PresenceAvatarsVariant
+    label?: string
+    countLabel?: string
+    viewingLabel?: string
+    awayLabel?: string
+    awaySinceLabel?: (awaySince: number) => string
+    moreLabel?: (count: number) => string
+}>(), {
+    max: 3,
+    tooltipMax: 7,
+    variant: 'pill',
+    label: 'Viewing this page',
+    viewingLabel: 'Viewing now',
+    awayLabel: 'Away',
+    moreLabel: (count: number) => `${count} more`,
+})
+
+const STACK_METRICS: Record<PresenceAvatarSize, { size: number, overlap: number, fontSize: number }> = {
+    '2xs': { size: 16, overlap: 4, fontSize: 8 },
+    'xs': { size: 24, overlap: 6, fontSize: 10 },
+    'sm': { size: 32, overlap: 8, fontSize: 12 },
+    'md': { size: 40, overlap: 10, fontSize: 14 },
+}
+
+const resolvedSize = computed<PresenceAvatarSize>(() => props.size ?? (props.variant === 'avatars' ? 'xs' : '2xs'))
+
+// Overlapped avatars get a crescent carved out with a mask (same technique as
+// tags-select dots): the mask circle is centered on the next avatar's center,
+// with a 2px ring of transparency around it.
+const stackStyle = computed(() => {
+    const { size, overlap } = STACK_METRICS[resolvedSize.value]
+    return {
+        '--presence-overlap': `${overlap}px`,
+        '--presence-mask-radius': `${size / 2 + 2}px`,
+        '--presence-mask-x': `calc(100% + ${size / 2 - overlap}px)`,
+    }
+})
+
+const visibleViewers = computed(() => props.viewers.slice(0, props.max))
+const tooltipViewers = computed(() => props.viewers.slice(0, props.tooltipMax))
+const hiddenTooltipCount = computed(() => Math.max(props.viewers.length - props.tooltipMax, 0))
+const resolvedCountLabel = computed(() => props.countLabel ?? `${props.viewers.length}`)
+
+const overflowCount = computed(() => props.variant === 'avatars' ? Math.max(props.viewers.length - props.max, 0) : 0)
+
+const overflowTextStyle = computed(() => ({ fontSize: `${STACK_METRICS[resolvedSize.value].fontSize}px` }))
+
+function isOverflowSlot(index: number) {
+    return overflowCount.value > 0 && index === visibleViewers.value.length - 1
+}
+
+function isActive(viewer: PresenceAvatarViewer) {
+    return viewer.active !== false
+}
+
+function displayName(viewer: PresenceAvatarViewer) {
+    return viewer.name || viewer.email || 'Unknown'
+}
+
+function viewerKey(viewer: PresenceAvatarViewer, index: number) {
+    return viewer.email || viewer.name || `viewer-${index}`
+}
+
+function statusLabel(viewer: PresenceAvatarViewer) {
+    if (isActive(viewer))
+        return props.viewingLabel
+    if (viewer.awaySince != null && props.awaySinceLabel)
+        return props.awaySinceLabel(viewer.awaySince)
+    return props.awayLabel
+}
+</script>
+
+<template>
+    <TelaTooltipGroup v-if="viewers.length > 0">
+        <div
+            role="group"
+            :aria-label="`${viewers.length} ${label}`"
+            flex items-center
+            :class="variant === 'pill' ? 'gap-6px rounded-8px bg-muted py-4px pl-10px pr-8px' : ''"
+        >
+            <TelaTooltipGroupTrigger v-if="variant === 'pill'" side="bottom" trigger-class="flex">
+                <span body-12-medium text-primary leading-16px>{{ resolvedCountLabel }}</span>
+                <template #content>
+                    <div flex="~ col" gap-4px text-left>
+                        <p
+                            v-for="(viewer, index) in tooltipViewers"
+                            :key="viewerKey(viewer, index)"
+                            body-12-regular text-white leading-16px
+                        >
+                            {{ displayName(viewer) }}
+                        </p>
+                        <p v-if="hiddenTooltipCount > 0" body-12-regular text-white leading-16px>
+                            {{ moreLabel(hiddenTooltipCount) }}
+                        </p>
+                    </div>
+                </template>
+            </TelaTooltipGroupTrigger>
+
+            <TransitionGroup name="tela-presence" tag="div" flex items-center :style="stackStyle">
+                <div
+                    v-for="(viewer, index) in visibleViewers"
+                    :key="viewerKey(viewer, index)"
+                    class="tela-presence-avatar"
+                    flex
+                >
+                    <TelaTooltipGroupTrigger side="bottom" trigger-class="flex">
+                        <div relative flex>
+                            <TelaAvatar
+                                :image="viewer.image"
+                                :alt="displayName(viewer)"
+                                :size="resolvedSize"
+                                rounded-full transition-opacity duration-160 ease-out
+                                :class="isActive(viewer) || isOverflowSlot(index) ? '' : 'op-50'"
+                            />
+                            <div
+                                v-if="isOverflowSlot(index)"
+                                absolute inset-0 rounded-full
+                                class="bg-neutral-950/80"
+                                flex items-center justify-center
+                                text-white font-500 leading-none select-none
+                                :style="overflowTextStyle"
+                            >
+                                +{{ overflowCount }}
+                            </div>
+                        </div>
+                        <template #content>
+                            <div v-if="isOverflowSlot(index)" flex="~ col" gap-4px text-left>
+                                <p
+                                    v-for="(tooltipViewer, tooltipIndex) in tooltipViewers"
+                                    :key="viewerKey(tooltipViewer, tooltipIndex)"
+                                    body-12-regular text-white leading-16px
+                                >
+                                    {{ displayName(tooltipViewer) }}
+                                </p>
+                                <p v-if="hiddenTooltipCount > 0" body-12-regular text-white leading-16px>
+                                    {{ moreLabel(hiddenTooltipCount) }}
+                                </p>
+                            </div>
+                            <div v-else flex="~ col" gap-2px text-left>
+                                <span body-12-medium text-white>{{ displayName(viewer) }}</span>
+                                <span body-12-regular text-neutral-200>{{ statusLabel(viewer) }}</span>
+                            </div>
+                        </template>
+                    </TelaTooltipGroupTrigger>
+                </div>
+            </TransitionGroup>
+        </div>
+    </TelaTooltipGroup>
+</template>
+
+<style scoped>
+.tela-presence-avatar:not(:first-child) {
+    margin-left: calc(var(--presence-overlap) * -1);
+}
+
+.tela-presence-avatar:not(:last-child) {
+    mask-image: radial-gradient(circle var(--presence-mask-radius) at var(--presence-mask-x) center, transparent var(--presence-mask-radius), #fff var(--presence-mask-radius));
+}
+
+.tela-presence-enter-active,
+.tela-presence-leave-active {
+    transition: opacity 160ms cubic-bezier(0.215, 0.61, 0.355, 1), transform 160ms cubic-bezier(0.215, 0.61, 0.355, 1);
+}
+
+.tela-presence-enter-from,
+.tela-presence-leave-to {
+    opacity: 0;
+    transform: scale(0.8);
+}
+
+.tela-presence-move {
+    transition: transform 160ms cubic-bezier(0.215, 0.61, 0.355, 1);
+}
+</style>

package/components/tela/tooltip-group/tooltip-group-trigger.vue

@@ -19,6 +19,7 @@ export type TooltipProps = {
     title?: string
     description?: string
     disableClosingTrigger?: boolean
+    triggerClass?: string
 }
 
 const props = withDefaults(defineProps<TooltipProps>(), {
@@ -54,7 +55,7 @@ const variantClasses = computed(() => {
 
 <template>
     <TelaTooltipRoot v-bind="tooltipRootProps">
-        <TelaTooltipTrigger>
+        <TelaTooltipTrigger :class="triggerClass">
             <slot />
         </TelaTooltipTrigger>
         <TelaTooltipContent

package/composables/__tests__/presence.test.ts

@@ -0,0 +1,632 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import type { Ref } from 'vue'
+import { effectScope, nextTick, ref } from 'vue'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { applyAwarenessUpdate, Awareness, encodeAwarenessUpdate, removeAwarenessStates } from 'y-protocols/awareness'
+import * as Y from 'yjs'
+import type { PresenceConnectionContext, PresenceConnectionHooks, PresenceUser } from '../presence'
+import { usePresence } from '../presence'
+
+const SELF: PresenceUser = { id: 'user-self', email: 'self@tela.com', name: 'Self' }
+const USER_A: PresenceUser = { id: 'user-a', email: 'a@tela.com', name: 'Ada' }
+const USER_B: PresenceUser = { id: 'user-b', email: 'b@tela.com', name: 'Grace' }
+const USER_C: PresenceUser = { id: 'user-c', email: 'c@tela.com', name: 'Lin' }
+
+function setVisibility(state: 'visible' | 'hidden') {
+    Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => state })
+    document.dispatchEvent(new Event('visibilitychange'))
+}
+
+async function flush() {
+    await Promise.resolve()
+    await Promise.resolve()
+    await nextTick()
+}
+
+function createFakeConnection(hooks: PresenceConnectionHooks) {
+    const doc = new Y.Doc()
+    const awareness = new Awareness(doc)
+
+    const connection = {
+        awareness,
+        hooks,
+        connectCalls: 0,
+        disconnectCalls: 0,
+        destroyed: false,
+        tokens: [] as (string | null)[],
+        connect() {
+            connection.connectCalls++
+        },
+        disconnect() {
+            connection.disconnectCalls++
+        },
+        setToken(token: string | null) {
+            connection.tokens.push(token)
+        },
+        destroy() {
+            connection.destroyed = true
+            awareness.destroy()
+            doc.destroy()
+        },
+        addPeer(user: PresenceUser, extra?: { active?: boolean, joinedAt?: number, awaySince?: number }) {
+            const peerDoc = new Y.Doc()
+            const peer = new Awareness(peerDoc)
+            peer.setLocalStateField('user', user)
+            if (extra?.active !== undefined)
+                peer.setLocalStateField('active', extra.active)
+            if (extra?.joinedAt !== undefined)
+                peer.setLocalStateField('joinedAt', extra.joinedAt)
+            if (extra?.awaySince !== undefined)
+                peer.setLocalStateField('awaySince', extra.awaySince)
+            applyAwarenessUpdate(awareness, encodeAwarenessUpdate(peer, [peer.clientID]), 'test')
+
+            return {
+                clientId: peer.clientID,
+                setField: (field: string, value: unknown) => {
+                    peer.setLocalStateField(field, value)
+                    applyAwarenessUpdate(awareness, encodeAwarenessUpdate(peer, [peer.clientID]), 'test')
+                },
+                remove: () => {
+                    removeAwarenessStates(awareness, [peer.clientID], 'test')
+                    peer.destroy()
+                    peerDoc.destroy()
+                },
+            }
+        },
+    }
+
+    return connection
+}
+
+type FakeConnection = ReturnType<typeof createFakeConnection>
+
+describe('usePresence', () => {
+    afterEach(() => {
+        setVisibility('visible')
+    })
+
+    function createPresence(input?: {
+        channel?: Ref<string | null | undefined>
+        url?: Ref<string | null | undefined>
+        self?: Ref<PresenceUser | null | undefined>
+        enabled?: Ref<boolean>
+        getToken?: () => Promise<string | null>
+        maxConsecutiveFailures?: number
+    }) {
+        const channel = input?.channel ?? ref<string | null | undefined>('prompt:p1')
+        const url = input?.url ?? ref<string | null | undefined>('ws://localhost:4005')
+        const self = input?.self ?? ref<PresenceUser | null | undefined>(SELF)
+        const enabled = input?.enabled ?? ref(true)
+
+        const connections: FakeConnection[] = []
+        const contexts: PresenceConnectionContext[] = []
+        const createConnection = vi.fn((context: PresenceConnectionContext, hooks: PresenceConnectionHooks) => {
+            contexts.push(context)
+            const connection = createFakeConnection(hooks)
+            connections.push(connection)
+            return connection
+        })
+
+        const scope = effectScope()
+        const presence = scope.run(() => usePresence({
+            channel,
+            url,
+            self,
+            enabled,
+            getToken: input?.getToken,
+            createConnection,
+            ...(input?.maxConsecutiveFailures ? { maxConsecutiveFailures: input.maxConsecutiveFailures } : {}),
+        }))!
+
+        return {
+            channel,
+            url,
+            self,
+            enabled,
+            presence,
+            scope,
+            createConnection,
+            connections,
+            contexts,
+            current: () => connections[connections.length - 1]!,
+        }
+    }
+
+    it('connects with the resolved token and sets the local awareness user', async () => {
+        const { presence, createConnection, contexts, current } = createPresence({
+            getToken: async () => 'jwt-token',
+        })
+
+        await flush()
+
+        expect(createConnection).toHaveBeenCalledTimes(1)
+        expect(contexts[0]).toEqual({ url: 'ws://localhost:4005', channel: 'prompt:p1', token: 'jwt-token' })
+        expect(current().awareness.getLocalState()?.user).toEqual(SELF)
+        expect(current().awareness.getLocalState()?.active).toBe(true)
+        expect(current().awareness.getLocalState()?.joinedAt).toEqual(expect.any(Number))
+        expect(presence.others.value).toEqual([])
+        expect(presence.isAlone.value).toBe(true)
+
+        presence.stop()
+    })
+
+    it('lists other viewers from awareness states', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        const peerA = current().addPeer(USER_A)
+        current().addPeer(USER_B)
+        await flush()
+
+        expect(presence.others.value.map(user => user.id).sort()).toEqual(['user-a', 'user-b'])
+        // Peers that never published the new fields surface with defaults.
+        expect(presence.others.value.every(viewer => viewer.active === true && viewer.joinedAt === null)).toBe(true)
+        expect(presence.isAlone.value).toBe(false)
+
+        peerA.remove()
+        await flush()
+
+        expect(presence.others.value.map(user => user.id)).toEqual(['user-b'])
+
+        presence.stop()
+    })
+
+    it('dedupes users across tabs and never shows yourself', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        current().addPeer(SELF)
+        current().addPeer(USER_A)
+        current().addPeer(USER_A)
+        await flush()
+
+        expect(presence.others.value.map(user => user.id)).toEqual(['user-a'])
+
+        presence.stop()
+    })
+
+    it('does not connect while disabled or without a channel or url', async () => {
+        const channel = ref<string | null | undefined>(null)
+        const enabled = ref(false)
+        const { createConnection, presence } = createPresence({ channel, enabled })
+
+        await flush()
+        expect(createConnection).not.toHaveBeenCalled()
+
+        channel.value = 'prompt:p1'
+        await flush()
+        expect(createConnection).not.toHaveBeenCalled()
+
+        enabled.value = true
+        await flush()
+        expect(createConnection).toHaveBeenCalledTimes(1)
+
+        presence.stop()
+    })
+
+    it('recreates the connection when the channel changes', async () => {
+        const channel = ref<string | null | undefined>('prompt:p1')
+        const { presence, connections, contexts, current } = createPresence({ channel })
+
+        await flush()
+        current().addPeer(USER_A)
+        await flush()
+        expect(presence.others.value).toHaveLength(1)
+
+        channel.value = 'agent:a1'
+        await flush()
+
+        expect(connections).toHaveLength(2)
+        expect(connections[0]!.destroyed).toBe(true)
+        expect(contexts[1]!.channel).toBe('agent:a1')
+        expect(presence.others.value).toEqual([])
+
+        presence.stop()
+    })
+
+    it('destroys the connection when the channel becomes null', async () => {
+        const channel = ref<string | null | undefined>('prompt:p1')
+        const { presence, current, connections } = createPresence({ channel })
+
+        await flush()
+
+        channel.value = null
+        await flush()
+
+        expect(connections).toHaveLength(1)
+        expect(current().destroyed).toBe(true)
+        expect(presence.isConnected.value).toBe(false)
+
+        presence.stop()
+    })
+
+    it('stays connected while the tab is hidden and publishes the away state', async () => {
+        const { presence, current, connections } = createPresence()
+
+        await flush()
+        expect(current().awareness.getLocalState()?.active).toBe(true)
+
+        setVisibility('hidden')
+        await flush()
+        expect(current().disconnectCalls).toBe(0)
+        expect(current().destroyed).toBe(false)
+        expect(current().awareness.getLocalState()?.active).toBe(false)
+
+        setVisibility('visible')
+        await flush()
+        expect(current().awareness.getLocalState()?.active).toBe(true)
+        expect(connections).toHaveLength(1)
+
+        presence.stop()
+    })
+
+    it('keeps listing peers while the local tab is hidden', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        setVisibility('hidden')
+        await flush()
+        current().addPeer(USER_A)
+        await flush()
+
+        expect(presence.others.value.map(viewer => viewer.id)).toEqual(['user-a'])
+
+        presence.stop()
+    })
+
+    it('orders viewers by join time with unknown join times last', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        current().addPeer(USER_A, { joinedAt: 300 })
+        current().addPeer(USER_B, { joinedAt: 100 })
+        current().addPeer(USER_C)
+        await flush()
+
+        expect(presence.others.value.map(viewer => viewer.id)).toEqual(['user-b', 'user-a', 'user-c'])
+        expect(presence.others.value[2]!.joinedAt).toBeNull()
+
+        presence.stop()
+    })
+
+    it('orders peers without join time by client id', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        const peerA = current().addPeer(USER_A)
+        const peerB = current().addPeer(USER_B)
+        await flush()
+
+        const expected = [
+            { id: USER_A.id, clientId: peerA.clientId },
+            { id: USER_B.id, clientId: peerB.clientId },
+        ].sort((a, b) => a.clientId - b.clientId).map(entry => entry.id)
+
+        expect(presence.others.value.map(viewer => viewer.id)).toEqual(expected)
+
+        presence.stop()
+    })
+
+    it('pushes away viewers behind active ones and restores join order on return', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        const peerA = current().addPeer(USER_A, { joinedAt: 100 })
+        current().addPeer(USER_B, { joinedAt: 200 })
+        await flush()
+        expect(presence.others.value.map(viewer => viewer.id)).toEqual(['user-a', 'user-b'])
+
+        peerA.setField('active', false)
+        await flush()
+        expect(presence.others.value.map(viewer => viewer.id)).toEqual(['user-b', 'user-a'])
+        expect(presence.others.value[1]!.active).toBe(false)
+
+        peerA.setField('active', true)
+        await flush()
+        expect(presence.others.value.map(viewer => viewer.id)).toEqual(['user-a', 'user-b'])
+        expect(presence.others.value[0]!.active).toBe(true)
+
+        presence.stop()
+    })
+
+    it('publishes awaySince while hidden and clears it when visible again', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        expect(current().awareness.getLocalState()?.awaySince).toBeNull()
+
+        setVisibility('hidden')
+        await flush()
+        expect(current().awareness.getLocalState()?.awaySince).toEqual(expect.any(Number))
+
+        setVisibility('visible')
+        await flush()
+        expect(current().awareness.getLocalState()?.awaySince).toBeNull()
+
+        presence.stop()
+    })
+
+    it('surfaces each away viewer\'s awaySince and null for active or legacy peers', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        current().addPeer(USER_A, { active: false, awaySince: 1234, joinedAt: 100 })
+        current().addPeer(USER_B, { active: true, joinedAt: 200 })
+        current().addPeer(USER_C, { active: false, joinedAt: 300 })
+        await flush()
+
+        const byId = new Map(presence.others.value.map(viewer => [viewer.id, viewer]))
+        expect(byId.get('user-a')!.awaySince).toBe(1234)
+        expect(byId.get('user-b')!.awaySince).toBeNull()
+        expect(byId.get('user-c')!.awaySince).toBeNull()
+
+        presence.stop()
+    })
+
+    it('merges multi-tab awaySince to the most recent, dropping it if any tab is active', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        current().addPeer(USER_A, { active: false, awaySince: 100 })
+        const tabTwo = current().addPeer(USER_A, { active: false, awaySince: 500 })
+        await flush()
+
+        expect(presence.others.value).toHaveLength(1)
+        expect(presence.others.value[0]!.awaySince).toBe(500)
+
+        tabTwo.setField('active', true)
+        await flush()
+
+        expect(presence.others.value[0]!.active).toBe(true)
+        expect(presence.others.value[0]!.awaySince).toBeNull()
+
+        presence.stop()
+    })
+
+    it('keeps join order within the active and away groups', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        current().addPeer(USER_A, { joinedAt: 100, active: false })
+        current().addPeer(USER_B, { joinedAt: 200, active: true })
+        current().addPeer(USER_C, { joinedAt: 300, active: false })
+        await flush()
+
+        expect(presence.others.value.map(viewer => viewer.id)).toEqual(['user-b', 'user-a', 'user-c'])
+
+        presence.stop()
+    })
+
+    it('merges multiple tabs of the same user with active OR and earliest join', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        current().addPeer(USER_A, { active: false, joinedAt: 200 })
+        const tabTwo = current().addPeer(USER_A, { active: true, joinedAt: 500 })
+        await flush()
+
+        expect(presence.others.value).toHaveLength(1)
+        expect(presence.others.value[0]).toMatchObject({ id: 'user-a', active: true, joinedAt: 200 })
+
+        tabTwo.setField('active', false)
+        await flush()
+
+        expect(presence.others.value[0]!.active).toBe(false)
+
+        presence.stop()
+    })
+
+    it('publishes a fresh join time on each new connection', async () => {
+        const channel = ref<string | null | undefined>('prompt:p1')
+        const { presence, current, connections } = createPresence({ channel })
+
+        await flush()
+        expect(current().awareness.getLocalState()?.joinedAt).toEqual(expect.any(Number))
+
+        channel.value = 'agent:a1'
+        await flush()
+
+        expect(connections).toHaveLength(2)
+        expect(current().awareness.getLocalState()?.joinedAt).toEqual(expect.any(Number))
+
+        presence.stop()
+    })
+
+    it('updates the local awareness state when self changes', async () => {
+        const self = ref<PresenceUser | null | undefined>(SELF)
+        const { presence, current } = createPresence({ self })
+
+        await flush()
+
+        self.value = { ...SELF, name: 'Renamed' }
+        await flush()
+
+        expect(current().awareness.getLocalState()?.user?.name).toBe('Renamed')
+
+        presence.stop()
+    })
+
+    it('tracks connection status', async () => {
+        const { presence, current } = createPresence()
+
+        await flush()
+        expect(presence.isConnected.value).toBe(false)
+
+        current().hooks.onStatusChange(true)
+        await flush()
+        expect(presence.isConnected.value).toBe(true)
+
+        current().hooks.onStatusChange(false)
+        await flush()
+        expect(presence.isConnected.value).toBe(false)
+
+        presence.stop()
+    })
+
+    it('hard-stops after repeated connection failures without ever connecting', async () => {
+        const { presence, current } = createPresence({ maxConsecutiveFailures: 3 })
+
+        await flush()
+        current().hooks.onConnectionError()
+        current().hooks.onConnectionError()
+        current().hooks.onConnectionError()
+        await flush()
+
+        expect(presence.hasError.value).toBe(true)
+        expect(current().disconnectCalls).toBeGreaterThan(0)
+
+        presence.stop()
+    })
+
+    it('resets the failure counter once connected', async () => {
+        const { presence, current } = createPresence({ maxConsecutiveFailures: 3 })
+
+        await flush()
+        current().hooks.onConnectionError()
+        current().hooks.onConnectionError()
+        current().hooks.onStatusChange(true)
+        current().hooks.onConnectionError()
+        current().hooks.onConnectionError()
+        await flush()
+
+        expect(presence.hasError.value).toBe(false)
+
+        presence.stop()
+    })
+
+    it('recovers from a hard stop when the channel changes', async () => {
+        const channel = ref<string | null | undefined>('prompt:p1')
+        const { presence, connections, current } = createPresence({ channel, maxConsecutiveFailures: 2 })
+
+        await flush()
+        current().hooks.onConnectionError()
+        current().hooks.onConnectionError()
+        await flush()
+        expect(presence.hasError.value).toBe(true)
+
+        channel.value = 'prompt:p2'
+        await flush()
+
+        expect(presence.hasError.value).toBe(false)
+        expect(connections).toHaveLength(2)
+
+        presence.stop()
+    })
+
+    it('ignores events from a stale connection after a channel switch', async () => {
+        const channel = ref<string | null | undefined>('prompt:p1')
+        const { presence, connections } = createPresence({ channel })
+
+        await flush()
+        const stale = connections[0]!
+
+        channel.value = 'prompt:p2'
+        await flush()
+
+        stale.hooks.onStatusChange(true)
+        await flush()
+
+        expect(presence.isConnected.value).toBe(false)
+
+        presence.stop()
+    })
+
+    it('destroys the connection on scope dispose', async () => {
+        const { current, scope } = createPresence()
+
+        await flush()
+
+        scope.stop()
+        await flush()
+
+        expect(current().destroyed).toBe(true)
+    })
+})
+
+describe('usePresence token lifecycle', () => {
+    function createPresence(getToken: () => Promise<string | null>) {
+        const connections: FakeConnection[] = []
+        const contexts: PresenceConnectionContext[] = []
+
+        const scope = effectScope()
+        const presence = scope.run(() => usePresence({
+            channel: ref('prompt:p1'),
+            url: ref('ws://localhost:4005'),
+            self: ref(SELF),
+            getToken,
+            maxConsecutiveFailures: 10,
+            createConnection: (context, hooks) => {
+                contexts.push(context)
+                const connection = createFakeConnection(hooks)
+                connections.push(connection)
+                return connection
+            },
+        }))!
+
+        return { presence, scope, connections, contexts, current: () => connections[connections.length - 1]! }
+    }
+
+    it('pushes a fresh token into the provider after a failed connection', async () => {
+        let issued = 0
+        const { scope, current } = createPresence(async () => `jwt-${++issued}`)
+        await flush()
+
+        expect(current().tokens).toEqual([])
+
+        current().hooks.onConnectionError()
+        await flush()
+        current().hooks.onConnectionError()
+        await flush()
+
+        expect(current().tokens).toEqual(['jwt-2', 'jwt-3'])
+        scope.stop()
+    })
+
+    it('stops refreshing once the failure budget is spent', async () => {
+        let issued = 0
+        const { presence, scope, current } = createPresence(async () => `jwt-${++issued}`)
+        await flush()
+
+        for (let attempt = 0; attempt < 10; attempt++) {
+            current().hooks.onConnectionError()
+            await flush()
+        }
+
+        expect(presence.hasError.value).toBe(true)
+        // Nine refreshes, then the tenth failure gives up instead of asking again.
+        expect(current().tokens).toHaveLength(9)
+        scope.stop()
+    })
+
+    it('survives a token refresh that rejects', async () => {
+        let issued = 0
+        const { presence, scope, current } = createPresence(async () => {
+            issued++
+            if (issued > 1)
+                throw new Error('auth down')
+            return 'jwt-1'
+        })
+        await flush()
+
+        current().hooks.onConnectionError()
+        await flush()
+
+        expect(presence.hasError.value).toBe(false)
+        expect(current().tokens).toEqual([])
+        scope.stop()
+    })
+
+    it('surfaces a rejected initial token as an error rather than an unhandled rejection', async () => {
+        const { presence, scope, connections } = createPresence(async () => {
+            throw new Error('auth down')
+        })
+        await flush()
+
+        expect(connections).toHaveLength(0)
+        expect(presence.hasError.value).toBe(true)
+        expect(presence.isConnected.value).toBe(false)
+        scope.stop()
+    })
+})

package/composables/presence.ts

@@ -0,0 +1,336 @@
+import type { ComputedRef, MaybeRef, Ref } from 'vue'
+import { tryOnScopeDispose } from '@vueuse/core'
+import { computed, readonly, ref, unref, watch } from 'vue'
+import type { Awareness } from 'y-protocols/awareness'
+import { WebsocketProvider } from 'y-websocket'
+import * as Y from 'yjs'
+
+const PRESENCE_MAX_CONSECUTIVE_FAILURES = 10
+
+export interface PresenceUser {
+    id: string
+    email: string
+    name?: string
+    image?: string
+}
+
+export interface PresenceViewer extends PresenceUser {
+    active: boolean
+    joinedAt: number | null
+    awaySince: number | null
+}
+
+export interface PresenceConnectionContext {
+    url: string
+    channel: string
+    token: string | null
+}
+
+export interface PresenceConnectionHooks {
+    onStatusChange: (connected: boolean) => void
+    onConnectionError: () => void
+}
+
+export interface PresenceConnection {
+    awareness: Awareness
+    connect: () => void
+    disconnect: () => void
+    setToken: (token: string | null) => void
+    destroy: () => void
+}
+
+export type PresenceConnectionFactory = (
+    context: PresenceConnectionContext,
+    hooks: PresenceConnectionHooks,
+) => PresenceConnection
+
+export interface UsePresenceOptions {
+    channel: MaybeRef<string | null | undefined>
+    url: MaybeRef<string | null | undefined>
+    self: MaybeRef<PresenceUser | null | undefined>
+    getToken?: () => Promise<string | null | undefined>
+    enabled?: MaybeRef<boolean>
+    maxConsecutiveFailures?: number
+    createConnection?: PresenceConnectionFactory
+}
+
+export interface UsePresenceReturn {
+    others: ComputedRef<PresenceViewer[]>
+    isAlone: ComputedRef<boolean>
+    isConnected: Readonly<Ref<boolean>>
+    hasError: Readonly<Ref<boolean>>
+    stop: () => void
+}
+
+const createWebsocketConnection: PresenceConnectionFactory = (context, hooks) => {
+    const doc = new Y.Doc()
+    const provider = new WebsocketProvider(context.url, context.channel, doc, {
+        params: context.token ? { token: context.token } : {},
+        disableBc: true,
+    })
+
+    provider.on('status', event => hooks.onStatusChange(event.status === 'connected'))
+    provider.on('connection-error', () => hooks.onConnectionError())
+
+    return {
+        awareness: provider.awareness,
+        connect: () => provider.connect(),
+        disconnect: () => provider.disconnect(),
+        // y-websocket rebuilds its url from `params` on every reconnect attempt, so
+        // replacing the entry is enough to make the next attempt use a fresh token.
+        setToken: (token) => {
+            provider.params = token ? { token } : {}
+        },
+        destroy: () => {
+            provider.destroy()
+            doc.destroy()
+        },
+    }
+}
+
+export function usePresence(options: UsePresenceOptions): UsePresenceReturn {
+    const others = ref<PresenceViewer[]>([])
+    const isConnected = ref(false)
+    const hasError = ref(false)
+    const isStopped = ref(false)
+    const isDocumentVisible = ref(typeof document === 'undefined' || document.visibilityState === 'visible')
+
+    const channel = computed(() => unref(options.channel) ?? null)
+    const url = computed(() => unref(options.url) ?? null)
+    const self = computed(() => unref(options.self) ?? null)
+    const maxConsecutiveFailures = options.maxConsecutiveFailures ?? PRESENCE_MAX_CONSECUTIVE_FAILURES
+    const createConnection = options.createConnection ?? createWebsocketConnection
+
+    const isEnabled = computed(() =>
+        Boolean(unref(options.enabled) ?? true)
+        && Boolean(channel.value)
+        && Boolean(url.value),
+    )
+
+    let current: { connection: PresenceConnection, key: string, cleanup: () => void } | null = null
+    let establishSeq = 0
+    let consecutiveFailures = 0
+
+    function recomputeOthers() {
+        if (!current) {
+            others.value = []
+            return
+        }
+
+        const { awareness } = current.connection
+        const selfId = self.value?.id
+        const byId = new Map<string, { user: PresenceUser, active: boolean, joinedAt: number | null, awaySince: number | null, minClientId: number }>()
+
+        for (const [clientId, state] of awareness.getStates()) {
+            if (clientId === awareness.clientID)
+                continue
+
+            const presenceState = state as { user?: PresenceUser, active?: boolean, joinedAt?: number, awaySince?: number } | null
+            const user = presenceState?.user
+            if (!user?.id || user.id === selfId)
+                continue
+
+            // Peers on older clients never publish these fields: assume active, unknown join time.
+            const active = presenceState?.active !== false
+            const joinedAt = typeof presenceState?.joinedAt === 'number' ? presenceState.joinedAt : null
+            const awaySince = typeof presenceState?.awaySince === 'number' ? presenceState.awaySince : null
+
+            const existing = byId.get(user.id)
+            if (!existing) {
+                byId.set(user.id, { user, active, joinedAt, awaySince, minClientId: clientId })
+                continue
+            }
+
+            // Same user in multiple tabs: active if any tab is, joined when the first tab did,
+            // away since the most recent tab activity.
+            existing.active = existing.active || active
+            if (joinedAt !== null)
+                existing.joinedAt = existing.joinedAt === null ? joinedAt : Math.min(existing.joinedAt, joinedAt)
+            if (awaySince !== null)
+                existing.awaySince = existing.awaySince === null ? awaySince : Math.max(existing.awaySince, awaySince)
+            existing.minClientId = Math.min(existing.minClientId, clientId)
+        }
+
+        others.value = Array.from(byId.values())
+            .sort((a, b) => {
+                if (a.active !== b.active)
+                    return a.active ? -1 : 1
+                if (a.joinedAt !== null && b.joinedAt !== null && a.joinedAt !== b.joinedAt)
+                    return a.joinedAt - b.joinedAt
+                if ((a.joinedAt === null) !== (b.joinedAt === null))
+                    return a.joinedAt === null ? 1 : -1
+                return a.minClientId - b.minClientId
+            })
+            .map(({ user, active, joinedAt, awaySince }) => ({ ...user, active, joinedAt, awaySince: active ? null : awaySince }))
+    }
+
+    function teardown() {
+        establishSeq++
+
+        if (current) {
+            current.cleanup()
+            current.connection.destroy()
+            current = null
+        }
+
+        others.value = []
+        isConnected.value = false
+    }
+
+    async function establish(targetChannel: string, targetUrl: string) {
+        const seq = ++establishSeq
+
+        hasError.value = false
+        consecutiveFailures = 0
+
+        let token: string | null = null
+        if (options.getToken) {
+            token = (await options.getToken()) ?? null
+
+            if (seq !== establishSeq || isStopped.value || !isEnabled.value)
+                return
+        }
+
+        let establishedConnection: PresenceConnection | null = null
+        const isStale = () => !current || current.connection !== establishedConnection
+
+        async function refreshToken() {
+            if (!options.getToken)
+                return
+
+            try {
+                const fresh = (await options.getToken()) ?? null
+                if (!isStale())
+                    establishedConnection?.setToken(fresh)
+            }
+            catch {
+                // Nothing to do: the next failure retries this alongside the reconnect.
+            }
+        }
+
+        const hooks: PresenceConnectionHooks = {
+            onStatusChange: (connected) => {
+                if (isStale())
+                    return
+
+                isConnected.value = connected
+
+                if (connected)
+                    consecutiveFailures = 0
+            },
+            onConnectionError: () => {
+                if (isStale())
+                    return
+
+                consecutiveFailures++
+
+                if (consecutiveFailures >= maxConsecutiveFailures) {
+                    hasError.value = true
+                    isConnected.value = false
+                    establishedConnection?.disconnect()
+                    return
+                }
+
+                // The token that opened this connection expires long before a canvas tab
+                // does; without refreshing it every reconnect would 401 until the failure
+                // budget runs out and presence stops for good.
+                void refreshToken()
+            },
+        }
+
+        const connection = createConnection({ url: targetUrl, channel: targetChannel, token }, hooks)
+        establishedConnection = connection
+
+        const handleAwarenessChange = () => recomputeOthers()
+        connection.awareness.on('change', handleAwarenessChange)
+
+        current = {
+            connection,
+            key: `${targetChannel}|${targetUrl}`,
+            cleanup: () => {
+                connection.awareness.off('change', handleAwarenessChange)
+            },
+        }
+
+        connection.awareness.setLocalStateField('user', self.value)
+        connection.awareness.setLocalStateField('joinedAt', Date.now())
+        connection.awareness.setLocalStateField('active', isDocumentVisible.value)
+        connection.awareness.setLocalStateField('awaySince', isDocumentVisible.value ? null : Date.now())
+        recomputeOthers()
+    }
+
+    watch([channel, url, isEnabled], () => {
+        if (isStopped.value)
+            return
+
+        if (!isEnabled.value) {
+            // Missing channel/url means the page context is gone — drop the room.
+            // An explicit disabled flag keeps the connection for a cheap resume.
+            if (!channel.value || !url.value)
+                teardown()
+            else if (current)
+                current.connection.disconnect()
+
+            isConnected.value = false
+            return
+        }
+
+        const key = `${channel.value}|${url.value}`
+
+        if (current && current.key === key && !hasError.value) {
+            current.connection.connect()
+            return
+        }
+
+        teardown()
+        establish(channel.value!, url.value!).catch(() => {
+            hasError.value = true
+            isConnected.value = false
+        })
+    }, { immediate: true })
+
+    watch(self, () => {
+        if (!current)
+            return
+
+        current.connection.awareness.setLocalStateField('user', self.value)
+        recomputeOthers()
+    }, { deep: true })
+
+    watch(isDocumentVisible, (visible) => {
+        current?.connection.awareness.setLocalStateField('active', visible)
+        current?.connection.awareness.setLocalStateField('awaySince', visible ? null : Date.now())
+    })
+
+    function handleVisibilityChange() {
+        isDocumentVisible.value = document.visibilityState === 'visible'
+    }
+
+    if (typeof document !== 'undefined') {
+        document.addEventListener('visibilitychange', handleVisibilityChange)
+    }
+
+    function stop() {
+        if (isStopped.value)
+            return
+
+        isStopped.value = true
+        teardown()
+
+        if (typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', handleVisibilityChange)
+        }
+    }
+
+    tryOnScopeDispose(() => {
+        stop()
+    })
+
+    return {
+        others: computed(() => others.value),
+        isAlone: computed(() => others.value.length === 0),
+        isConnected: readonly(isConnected),
+        hasError: readonly(hasError),
+        stop,
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@meistrari/tela-build",
-    "version": "1.68.0",
+    "version": "1.69.0",
     "type": "module",
     "files": [
         "app.config.ts",
@@ -76,7 +76,10 @@
         "vue-component-meta": "3.0.8",
         "vue-docgen-api": "4.78.0",
         "vue-input-otp": "0.3.2",
-        "vue-router": "4.5.0"
+        "vue-router": "4.5.0",
+        "y-protocols": "^1.0.6",
+        "y-websocket": "^2.0.4",
+        "yjs": "13.6.24"
     },
     "peerDependencies": {
         "nuxt": "^3.17.0 || ^4.0.0",