presence-cursor.ts

presence-cursor.tsapps/web/src/lib/presence-cursor.tsraw ← lib5,416 B← Back to the app
1/**
2 * presence-cursor (TASK-0093, spec R4) — the PURE geometry resolution for
3 * remote cursors: which peers get a caret, where, and which selection
4 * highlights to draw.
5 *
6 * The web editor is per-block Tiptap (no shared ProseMirror document), so a
7 * remote cursor's `{blockId, offset}` is resolved against THAT block's own
8 * view. The browser glue (the editor-view registry + `coordsAtPos`) is the
9 * injectable `lookup` — this module is DOM-free and unit-testable
10 * (AGENTS rules 23 + 25).
11 *
12 * Rules (spec R4 + the stale-cursor contract):
13 *  - a peer with `cursor: null` gets nothing (cleared, or the 50-peer
14 *    avatars-only cap — the avatar bar still shows them);
15 *  - a peer with `viewing: false` gets NO CARET (a background tab's cursor
16 *    is noise — the avatar stays);
17 *  - a cursor whose `blockId` is not in the doc (deleted/moved by a
18 *    concurrent edit) is DROPPED SILENTLY (`dropped` counts it) — the peer's
19 *    next caret move re-places it; no crash, no orphan node;
20 *  - the name label is MANDATORY (the a11y rule: color is never the sole
21 *    identifier) — the component renders it, here we only carry the peer.
22 *
23 * Selections (spec R4): a peer's `selection` decomposes into per-block
24 * ranges (single block → 1 range; multi-block → head partial + full middle
25 * blocks + tail partial). Each range is requested from `lookup` at its two
26 * endpoints; the renderer takes their bounding box (a wrapped multi-line
27 * selection is approximated by the endpoint bbox — recorded). A range
28 * endpoint in a missing block drops just that range (the caret, if valid,
29 * stays).
30 */
31import type { Presence } from "./types";
32 
33export interface CursorPoint {
34  x: number;
35  y: number;
36}
37 
38/** A bounding box (min/max corners), for a selection highlight. */
39export interface SelectionRect {
40  x1: number;
41  y1: number;
42  x2: number;
43  y2: number;
44}
45 
46/** An endpoint inside one block: a text offset, or "end" of the block doc. */
47export type BlockOffset = number | "end";
48 
49/**
50 * Resolve a point for one block at an offset. Returns null when the block
51 * is gone, hidden, or the offset is out of range (stale — the cursor/hide
52 * is dropped silently). The browser glue maps `offset`/`"end"` through the
53 * block's Tiptap view (`coordsAtPos`), relative to the page root.
54 */
55export type CursorLookup = (blockId: string, offset: BlockOffset) => CursorPoint | null;
56 
57export interface ResolvedCursor {
58  peer: Presence;
59  caret: CursorPoint;
60  /** The peer's selection as bounding boxes (empty when no/invalid selection). */
61  rects: SelectionRect[];
62}
63 
64export interface CursorResolution {
65  /** One entry per peer with a resolvable caret (viewing + block present). */
66  cursors: ResolvedCursor[];
67  /** Peers whose cursor was dropped as stale (block not found / offset OOB). */
68  dropped: number;
69}
70 
71/** Decompose a selection into per-block ranges (pure). */
72export function selectionRanges(
73  blockOrder: readonly string[],
74  sel: { fromBlockId: string; fromOffset: number; toBlockId: string; toOffset: number },
75): { blockId: string; from: BlockOffset; to: BlockOffset }[] {
76  const fi = blockOrder.indexOf(sel.fromBlockId);
77  const ti = blockOrder.indexOf(sel.toBlockId);
78  if (fi === -1 || ti === -1) return []; // stale — a selected block is gone
79  if (fi === ti) {
80    return [
81      {
82        blockId: sel.fromBlockId,
83        from: Math.min(sel.fromOffset, sel.toOffset),
84        to: Math.max(sel.fromOffset, sel.toOffset),
85      },
86    ];
87  }
88  const [lo, hi] = fi < ti ? [fi, ti] : [ti, fi];
89  const out: { blockId: string; from: BlockOffset; to: BlockOffset }[] = [];
90  for (let i = lo; i <= hi; i += 1) {
91    const blockId = blockOrder[i]!; // lo..hi is in-range (fi/ti are indexOf hits)
92    if (i === lo)
93      out.push({
94        blockId,
95        from: fi < ti ? sel.fromOffset : sel.toOffset,
96        to: i === hi ? (fi < ti ? sel.toOffset : sel.fromOffset) : "end",
97      });
98    else if (i === hi) out.push({ blockId, from: 0, to: fi < ti ? sel.toOffset : sel.fromOffset });
99    else out.push({ blockId, from: 0, to: "end" });
100  }
101  return out;
102}
103 
104function bbox(a: CursorPoint, b: CursorPoint): SelectionRect {
105  return {
106    x1: Math.min(a.x, b.x),
107    y1: Math.min(a.y, b.y),
108    x2: Math.max(a.x, b.x),
109    y2: Math.max(a.y, b.y),
110  };
111}
112 
113export function resolvePresenceCursors(
114  peers: readonly Presence[],
115  blockOrder: readonly string[],
116  lookup: CursorLookup,
117): CursorResolution {
118  const cursors: ResolvedCursor[] = [];
119  let dropped = 0;
120 
121  for (const peer of peers) {
122    const cursor = peer.cursor;
123    if (cursor === null || cursor === undefined) continue; // cleared / avatars-only cap
124    if (peer.viewing === false) continue; // background tab — avatar stays, caret hides
125 
126    const caret = lookup(cursor.blockId, cursor.offset);
127    if (caret === null) {
128      dropped += 1; // stale block — silent drop, re-placed on the next move
129      continue;
130    }
131 
132    const rects: SelectionRect[] = [];
133    if (cursor.selection) {
134      for (const range of selectionRanges(blockOrder, cursor.selection)) {
135        const p1 = lookup(range.blockId, range.from);
136        const p2 = lookup(range.blockId, range.to);
137        if (p1 !== null && p2 !== null) rects.push(bbox(p1, p2));
138        // A missing endpoint drops just that range (the caret stays).
139      }
140    }
141 
142    cursors.push({ peer, caret, rects });
143  }
144 
145  return { cursors, dropped };
146}
147