Cursor and Stable Positions

Quick Reference

Cursors maintain stable positions across concurrent edits by anchoring to operation IDs instead of indices. Essential for collaborative editing features like collaborative cursors and persistent annotations.

How It Works

Cursors anchor to operation IDs and ContainerIDs, not indices:

Text:    H e l l o   W o r l d
Op IDs:  1 2 3 4 5 6 7 8 9 A B
Cursor:  References ID 5 (after 'o')

After concurrent insert at start:
Text:    N e w   H e l l o   W o r l d  
Op IDs:  C D E F 1 2 3 4 5 6 7 8 9 A B
Cursor:  Still references ID 5 - position automatically adjusted

Side Parameter

Side.Before (-1): Stay before the target
Side.Middle (0): On the target (default)
Side.After (1): Stay after the target

const  = new ();
const  = .("text");
.(0, "ABC");
 
const  = .(1, -1); // Before 'B'
.(1, "X"); // Insert at cursor
// Result: "AXBC", cursor still before 'B'
const  = .(!);
.(); // { offset: 2, side: Side.Before }

Common Use Cases

Text Selections

const  = new ();
const  = .("text");
.(0, "Hello World");
 
// Selection range
const  = .(0, -1);  // Anchor
const  = .(5, 1);     // Head

List Positions

const  = new ();
const  = .("items");
.(0, ["a", "b", "c"]);
 
const  = .(0, 1); // After "a"
.(0, "new"); // Cursor adjusts automatically

Text Container - Text editing with cursors
Cursor Tutorial - Building collaborative features
Events - Cursor change events

Version Vector Import Status and Pending Operations