# Presence cursor

> Other people's pointers and carets over the work, each in their colour with their name. Never between someone and the work.

Source: https://kwark.space/designSystem/components/presence-cursor

## Usage

### When to use
On shared surfaces where people work at the same time: the screenplay page, the outline board, the stripboard. Positions are measured as a fraction of the page, so a cursor lands on the same word for everybody whatever their window size.

### When not to
- Never in private spaces (private research, Dailies).
- Never to show who is "idle". Kwark has no idle curtain (Decision 0012).

### Anatomy in use
- **Pointer**: an arrow in the person's colour, with their name in a tag; it moves with a 90ms ease so movement reads as a hand.
- **Caret**: a 2px line with the name above.
- **Selection**: a 28% wash of their colour.
- **Bar**: avatars with a ring in each person's colour, and *2 others here*.
- Against the right or bottom edge the name flips inside, so no arrow belongs to nobody.

### Writing
Name tags use first names. The bar counts others, not you.

**Do:** *Mira* tag beside her pointer, flipped inside at the page edge.

**Don't:** A pointer that blocks clicks, or "Arjun is idle".

## Style

### Anatomy

Layer fills its positioned parent with `pointer-events: none`, z-index 40. Name tag 11px 600 on the peer colour with `--k-peer-ink`.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-peer` | #79a9e8 |  |
| `--k-peer-ink` | #14161a |  |
| `--k-bg` | #f8fafc | #191919 |
| `--k-cal-recce` | #4d6a7a | #83aac0 |

## Code

### React

In the Kwark app: `import { PresenceCursors } from '@/components/presence/PresenceCursors'`.

```tsx
<div ref={usePointerSurface('script')} style={{ position: 'relative' }}>
  <PresenceCursors surface="script" />
</div>
<PresenceBar people={peers} max={5} />
```

| Prop | Type | Notes |
|---|---|---|
| `surface` | `string` | a fraction of this element lands on the same word for everybody |
| `people` | `Peer[]` | PresenceBar |
| `max` | `number` | avatars before "+n" |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-presence-layer kw-card" style="width:100%;height:120px">
  <p style="margin:0;font-family:var(--k-font-screenplay)">She stops the playhead on a frame<span class="kw-caret-peer" data-name="Arjun" style="--kw-peer:var(--k-cal-recce)"></span> nobody remembers <span class="kw-select-peer">filming</span>.</p>
  <span class="kw-cursor" style="left:62%;top:58px"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M2 1.5 14 8l-5.2 1.3L6.4 14z" fill="currentColor"/></svg><span class="kw-cursor__name">Mira</span></span>
</div>
<div class="kw-presence-bar"><span class="kw-avatar-stack"><span class="kw-avatar">M</span><span class="kw-avatar" style="--kw-peer:var(--k-cal-recce)">A</span></span>2 others here</div>
```

## Accessibility

- Cursors are decorative to assistive tech; the bar announces arrivals politely ("Arjun joined").
- Under reduced motion pointers jump instead of easing.
- Peer colours keep `--k-peer-ink` text at 4.5:1.

## For agents

### Rules

- **Never** let presence layers take pointer events.
- **Must** measure positions against the page, not the window.
- **Never** show presence in private spaces or label anyone idle.

### AI readiness test

**Task:** Show collaborators on the stripboard.

**Give the agent:** Presence cursor, Stripboard strip, Collaboration pattern.

**Constraint:** Two people may drag strips at once.

**A reliable answer:**
- Pointers over the board, no pointer events
- A dragged strip shows who holds it
- Positions relative to the board
- Bar counts others
