PR #327's ProseMirror widget keys omit cursor colour and name, so recycled cursor DOM goes stale #331

Finding

Open draft PR #327 (⚡ Bolt: Optimize ProseMirror decoration recycling, head 59decd10f6) removes the decorationGeneration counter in pkgs/id/web/src/cursors.ts and gives the collaborative-cursor widgets stable, state-derived keys — but two of the new keys omit properties that are rendered into the widget DOM, so ProseMirror will keep showing the old DOM after those properties change.

ProseMirror compares a widget decoration's key instead of its DOM node to decide whether it needs to be redrawn (ProseMirror reference: widget spec key — "When comparing decorations of this type (in order to decide whether it needs to be redrawn), ProseMirror will by default compare the widget DOM node by identity. If you pass a key, that key will be compared instead"). A property that changes without changing the key therefore never reaches the screen.

Evidence (PR #327 head, cross-checked via gh api contents?ref=59decd10f6)

• Standalone remote cursor, cursors.ts:738 on the PR head:
  key: cursor-${cursor.clientID}-o${cursor.opacity}-c${connectionState}
  — includes opacity and connection state, but not cursor.color and not cursor.name. The widget it keys is built by createStandaloneCursor / createCursorLine (same file): caret borderColor = cursor.color, label backgroundColor = cursor.color, label text colour derived from cursor.color, and label textContent = cursor.name.
• Cluster/merged cursor lines, cursors.ts:715 on the PR head:
  key: cursor-cluster-${group.position}-${clusterKey}-c${group.mostRecentColor}
  — the merged bar appended to the leftmost line renders one segment per cursor with that cursor's color (background), name (text), opacity and connection-state-driven strobe state (createMergedBar), and non-leftmost group lines render their first cursor's opacity/strobe state (createCursorLine); none of those per-cursor values are in the key (clusterKey encodes only clientID@head per cursor, and mostRecentColor is only the owning group's first cursor's colour).
• Contrast inside the same diff: the own-cursor key (cursors.ts:651) correctly includes its only rendered variable property, ownCursor.color. Contrast across the sibling drafts tracked by Triage 11 overlapping Jules Bolt and Palette draft PRs #310: PR ⚡ Bolt: optimize ProseMirror cursor DOM recycling #217's standalone key includes -color-${cursor.color}, its cluster key includes connection state plus an opacity hash, and its selection key includes colour — ⚡ Bolt: Optimize ProseMirror decoration recycling #327 drops colour from the standalone and selection keys.
• Colour/name are not session constants in this code: the plugin's apply() "update" case replaces color on every cursor update and takes name from the update when present (name = cursorUpdate.name ?? existing?.name), and createCursorDecorations falls back to getColorForClient(clientID) only when an update carries no colour — so a peer's colour source/value and display name can both change mid-session. While a peer is active their opacity stays at 1.0 (see getOpacityForAge in cursor-utils.ts: 1.0 for the first 30s after each update, and every update refreshes lastUpdate), so no other key component forces a redraw either.

Why it matters

If #327 (or a variant with the same keys) merges as-is, a collaborator who changes colour or display name — or whose first updates arrive colourless and later carry an explicit colour — keeps rendering with the stale caret colour and stale name label for everyone else, indefinitely while they stay active. That is a correctness regression introduced specifically by removing the generation counter, in the one file the PR touches. The PR's own added learning note (.jules/bolt.md) states the rule it breaks: properties that dynamically dictate the widget's appearance (it names opacity, connectionState and colour) must be included in the key.

Acceptance criteria

• Whichever ProseMirror-recycling PR survives the Triage 11 overlapping Jules Bolt and Palette draft PRs #310 triage, every widget key in cursors.ts covers all properties rendered into that widget's DOM: standalone cursor keys include colour and name; cluster keys include the per-cursor segment values (colour, name, opacity) and connection state, not just the group's most-recent colour.
• The selection decoration's colour handling is checked the same way (PR ⚡ Bolt: Optimize ProseMirror decoration recycling #327's selection-…-o${opacity} key omits cursor.color, which is half of its rendered background-color: ${cursor.color}${selectionOpacity} style).
• A test or equivalent check pins the key construction: changing only a cursor's colour (or only its name) produces a different standalone key. There is currently no cursors.test.ts (only cursor-utils.test.ts), so the key derivation may need extracting to a pure helper to be testable.

Found by the pr-diff-review job reviewing PR #327 (open) in developing-today/code. Cross-repo check: createCursorDecorations / collab-cursor exist only in developing-today/code (GitHub code search), so this is a single-repo issue. Related triage: #310.