braid-text 0.2.116 → 0.3.1

package/README.md

@@ -104,7 +104,7 @@ Here's a basic running example to start:
 
 <!-- 2. Include the libraries -->
 <script src="https://unpkg.com/braid-http@~1.3/braid-http-client.js"></script>
-<script src="https://unpkg.com/braid-text/simpleton-client.js"></script>
+<script src="https://unpkg.com/braid-text@~0.3/client/simpleton-sync.js"></script>
 
 <!-- 3. Wire it up -->
 <script>
@@ -173,7 +173,35 @@ var simpleton = simpleton_client(url, {
 })
 ```
 
-See [editor.html](https://github.com/braid-org/braid-text/blob/master/editor.html) for a complete example.
+See [editor.html](https://github.com/braid-org/braid-text/blob/master/client/editor.html) for a complete example.
+
+### Adding Multiplayer Cursor + Selections
+
+This will render each peer's cursor and selection with colored highlights.  Just add three lines to your simpleton client:
+
+```html
+<!-- 1. Include these additional script tags -->
+<script src="https://unpkg.com/braid-text@~0.3/client/cursor-highlights.js"></script>
+<script src="https://unpkg.com/braid-text@~0.3/client/cursor-sync.js"></script>
+
+<!-- 2. Add two lines to your simpleton_client() call -->
+<script>
+  var cursors = cursor_highlights(my_textarea, location.pathname)
+
+  var simpleton = simpleton_client(location.pathname, {
+    on_patches: (patches) => {
+      apply_patches_and_update_selection(my_textarea, patches)
+      cursors.on_patches(patches)        // <-- update remote cursors
+    },
+    get_state: () => my_textarea.value
+  })
+
+  my_textarea.oninput = () => {
+    cursors.on_edit(simpleton.changed())  // <-- send local cursor
+  }
+</script>
+```
+
 
 ## Client API
 
@@ -229,7 +257,7 @@ Creates a new Simpleton client that synchronizes with a Braid-Text server.
 
 ### Methods
 
-- `simpleton.changed()`: Notify the client that local changes have occurred. Call this in your editor's change event handler. The client will call `get_patches` and `get_state` when it's ready to send updates.
+- `simpleton.changed()`: Notify the client that local changes have occurred. Call this in your editor's change event handler. The client will call `get_patches` and `get_state` when it's ready to send updates. Returns the array of JS-index patches (or `undefined` if there was no change), which can be passed to `cursors.on_edit()`.
 
 ### Deprecated Options
 
@@ -238,6 +266,17 @@ The following options are deprecated and should be replaced with the new API:
 - ~~`apply_remote_update`~~ → Use `on_patches` or `on_state` instead
 - ~~`generate_local_diff_update`~~ → Use `get_patches` and `get_state` instead
 
+### Multiplayer Cursor API
+
+`cursor_highlights(textarea, url)` returns an object with:
+- `cursors.on_patches(patches)` — call after applying remote patches to transform and re-render remote cursors
+- `cursors.on_edit(patches)` — call after local edits; pass the patches from `simpleton.changed()` to update cursor positions and broadcast your selection
+- `cursors.destroy()` — tear down listeners and DOM elements
+
+Colors are auto-assigned per peer ID. See `?editor` and `?markdown-editor` in the demo server for working examples.
+
+
+
 ## Testing
 
 ### to run unit tests:

package/client/cursor-highlights.js

@@ -0,0 +1,302 @@
+// cursor-highlights.js — Render colored cursors and selections behind a <textarea>
+//
+// No dependencies. Pure DOM/CSS.
+//
+// Usage:
+//   var hl = textarea_highlights(textarea)
+//   hl.set('peer-1', [{ from: 5, to: 10, color: 'rgba(97,175,239,0.25)' }])
+//   hl.render()
+//   hl.remove('peer-1')
+//   hl.destroy()
+//
+function textarea_highlights(textarea) {
+    // Inject CSS once per page
+    if (!document.getElementById('textarea-highlights-css')) {
+        var style = document.createElement('style')
+        style.id = 'textarea-highlights-css'
+        style.textContent = `
+            .textarea-hl-backdrop {
+                position: absolute;
+                top: 0; left: 0; right: 0; bottom: 0;
+                white-space: pre-wrap;
+                word-wrap: break-word;
+                overflow-y: auto;
+                pointer-events: none;
+                color: transparent;
+                z-index: 1;
+                scrollbar-width: none;
+                -ms-overflow-style: none;
+            }
+            .textarea-hl-backdrop::-webkit-scrollbar { display: none; }
+            .textarea-hl-backdrop span { color: transparent; border-radius: 2px; }
+            .textarea-hl-backdrop span.sel {
+                padding: var(--sel-pad, 3px) 0;
+                -webkit-box-decoration-break: clone;
+                box-decoration-break: clone;
+            }
+            .textarea-hl-backdrop .cursor {
+                position: relative;
+                display: inline-block;
+                width: 0;
+                height: 1em;
+                z-index: 10;
+            }
+            .textarea-hl-backdrop .cursor::before {
+                content: '';
+                position: absolute;
+                left: -1px;
+                top: 0;
+                bottom: 0;
+                width: 2px;
+                background-color: var(--cursor-color, #ff5722);
+                z-index: 10;
+            }
+        `
+        document.head.appendChild(style)
+    }
+
+    // Ensure textarea is wrapped in a position:relative container
+    var wrap = textarea.parentElement
+    if (getComputedStyle(wrap).position === 'static')
+        wrap.style.position = 'relative'
+
+    // Move textarea's background to the wrapper so backdrops show through
+    var bg = getComputedStyle(textarea).backgroundColor
+    if (!wrap.style.backgroundColor)
+        wrap.style.backgroundColor = (!bg || bg === 'rgba(0, 0, 0, 0)') ? 'white' : bg
+    textarea.style.backgroundColor = 'transparent'
+    textarea.style.position = 'relative'
+    textarea.style.zIndex = '2'
+
+    // Measure font metrics for gap-free selection highlights
+    var cs = getComputedStyle(textarea)
+    var test_div = document.createElement('div')
+    test_div.style.cssText =
+        'font-family:' + cs.fontFamily + ';' +
+        'font-size:' + cs.fontSize + ';' +
+        'line-height:' + cs.lineHeight + ';' +
+        'position:absolute;top:-9999px;'
+    var test_span = document.createElement('span')
+    test_span.style.backgroundColor = 'red'
+    test_span.textContent = 'Xg'
+    test_div.appendChild(test_span)
+    document.body.appendChild(test_div)
+    var line_height = parseFloat(getComputedStyle(test_div).lineHeight)
+    var bg_height = test_span.getBoundingClientRect().height
+    document.body.removeChild(test_div)
+    var sel_pad = (line_height - bg_height) / 2
+    wrap.style.setProperty('--sel-pad', sel_pad + 'px')
+
+    // State
+    var layer_data = {}     // layer_id -> [{ from, to, color }]
+    var layer_divs = {}     // layer_id -> DOM div
+
+    // Scroll sync
+    function sync_scroll() {
+        for (var div of Object.values(layer_divs)) {
+            div.scrollTop = textarea.scrollTop
+            div.scrollLeft = textarea.scrollLeft
+        }
+    }
+    textarea.addEventListener('scroll', sync_scroll)
+
+    // Build a backdrop style string matching the textarea's font/padding/border
+    function backdrop_style() {
+        var cs = getComputedStyle(textarea)
+        return 'font-family:' + cs.fontFamily + ';' +
+            'font-size:' + cs.fontSize + ';' +
+            'line-height:' + cs.lineHeight + ';' +
+            'padding:' + cs.paddingTop + ' ' + cs.paddingRight + ' ' +
+                cs.paddingBottom + ' ' + cs.paddingLeft + ';' +
+            'border:' + cs.borderTopWidth + ' solid transparent;' +
+            'border-radius:' + cs.borderRadius + ';'
+    }
+
+    function escape_html(text) {
+        var div = document.createElement('div')
+        div.textContent = text
+        return div.innerHTML
+    }
+
+    function build_html(text, highlights) {
+        var cursors = highlights.filter(h => h.from === h.to)
+        var sels = highlights.filter(h => h.from !== h.to)
+
+        var items = []
+        for (var s of sels)
+            items.push({ type: 'selection', start: s.from, end: s.to, color: s.color })
+        for (var c of cursors)
+            items.push({ type: 'cursor', pos: c.from, color: c.color })
+
+        items.sort((a, b) => {
+            var pa = a.type === 'cursor' ? a.pos : a.start
+            var pb = b.type === 'cursor' ? b.pos : b.start
+            return pa - pb
+        })
+
+        var result = ''
+        var last = 0
+
+        for (var item of items) {
+            if (item.type === 'selection') {
+                if (item.start < last) continue
+                result += escape_html(text.substring(last, item.start))
+                var sel_text = text.substring(item.start, item.end)
+                var sel_html = escape_html(sel_text).replace(/\n/g, ' \n')
+                result += '<span class="sel" style="background-color:' + item.color + ';">' + sel_html + '</span>'
+                last = item.end
+            } else {
+                if (item.pos < last) continue
+                result += escape_html(text.substring(last, item.pos))
+                result += '<span class="cursor" style="--cursor-color:' + item.color + ';"></span>'
+                last = item.pos
+            }
+        }
+
+        result += escape_html(text.substring(last))
+        if (text.endsWith('\n')) result += '\u200B\n'
+        return result
+    }
+
+    return {
+        set: function(layer_id, highlights) {
+            layer_data[layer_id] = highlights
+        },
+
+        remove: function(layer_id) {
+            delete layer_data[layer_id]
+            if (layer_divs[layer_id]) {
+                layer_divs[layer_id].remove()
+                delete layer_divs[layer_id]
+            }
+        },
+
+        render: function() {
+            var text = textarea.value
+            var len = text.length
+            var style_str = backdrop_style()
+
+            // Remove divs for layers that no longer exist
+            for (var id of Object.keys(layer_divs)) {
+                if (!layer_data[id]) {
+                    layer_divs[id].remove()
+                    delete layer_divs[id]
+                }
+            }
+
+            // Render each layer
+            for (var id of Object.keys(layer_data)) {
+                var highlights = layer_data[id].map(h => ({
+                    from: Math.min(h.from, len),
+                    to: Math.min(h.to, len),
+                    color: h.color
+                }))
+
+                if (!layer_divs[id]) {
+                    var div = document.createElement('div')
+                    div.className = 'textarea-hl-backdrop'
+                    wrap.insertBefore(div, textarea)
+                    layer_divs[id] = div
+                }
+
+                // Font/padding/border are set inline to match textarea;
+                // positioning/pointer-events/etc come from the CSS class.
+                layer_divs[id].style.cssText = style_str
+
+                layer_divs[id].innerHTML = build_html(text, highlights)
+                layer_divs[id].scrollTop = textarea.scrollTop
+                layer_divs[id].scrollLeft = textarea.scrollLeft
+            }
+        },
+
+        layers: function() {
+            return Object.keys(layer_data)
+        },
+
+        destroy: function() {
+            textarea.removeEventListener('scroll', sync_scroll)
+            for (var div of Object.values(layer_divs)) div.remove()
+            layer_data = {}
+            layer_divs = {}
+        }
+    }
+}
+
+// --- Color helpers ---
+
+var _cursor_colors = ["#e06c75", "#61afef", "#98c379", "#c678dd", "#e5c07b", "#56b6c2"]
+
+function peer_color(peer_id) {
+    var hash = 0
+    for (var i = 0; i < peer_id.length; i++)
+        hash = ((hash << 5) - hash + peer_id.charCodeAt(i)) | 0
+    return _cursor_colors[Math.abs(hash) % _cursor_colors.length]
+}
+
+function peer_bg_color(peer_id) {
+    var c = peer_color(peer_id)
+    var r = parseInt(c.slice(1, 3), 16)
+    var g = parseInt(c.slice(3, 5), 16)
+    var b = parseInt(c.slice(5, 7), 16)
+    return `rgba(${r}, ${g}, ${b}, 0.25)`
+}
+
+// --- High-level wrapper ---
+//
+// Usage:
+//   var cursors = cursor_highlights(textarea, url)
+//   cursors.on_patches(patches)   // call after applying remote patches
+//   cursors.on_edit(patches)      // call after local edit; patches optional
+//   cursors.destroy()
+//
+function cursor_highlights(textarea, url) {
+    var peer = Math.random().toString(36).slice(2)
+    var hl = textarea_highlights(textarea)
+    var applying_remote = false
+    var client = null
+
+    cursor_client(url, {
+        peer,
+        get_text: () => textarea.value,
+        on_change: (sels) => {
+            for (var [id, ranges] of Object.entries(sels)) {
+                if (!ranges.length) { hl.remove(id); continue }
+                hl.set(id, ranges.map(r => ({
+                    from: r.from, to: r.to,
+                    color: r.from === r.to ? peer_color(id) : peer_bg_color(id)
+                })))
+            }
+            hl.render()
+        }
+    }).then(function(c) { client = c })
+
+    document.addEventListener('selectionchange', function() {
+        if (applying_remote) return
+        if (document.activeElement !== textarea) return
+        if (client) client.set(textarea.selectionStart, textarea.selectionEnd)
+    })
+
+    return {
+        online: function() { if (client) client.online() },
+        offline: function() { if (client) client.offline() },
+
+        on_patches: function(patches) {
+            applying_remote = true
+            if (client) client.changed(patches)
+            hl.render()
+            setTimeout(() => { applying_remote = false }, 0)
+        },
+
+        on_edit: function(patches) {
+            if (client) {
+                if (patches) client.changed(patches)
+                client.set(textarea.selectionStart, textarea.selectionEnd)
+            }
+        },
+
+        destroy: function() {
+            if (client) client.destroy()
+            hl.destroy()
+        }
+    }
+}

package/client/cursor-sync.js

@@ -0,0 +1,278 @@
+// cursor-sync.js — Sync cursor/selection positions via braid-http
+//
+// Requires braid-http-client.js (for braid_fetch)
+//
+// Usage:
+//   var cursors = await cursor_client(url, {
+//       peer: 'my-id',
+//       get_text: () => textarea.value,
+//       on_change: (selections) => { ... },
+//   })
+//   if (!cursors) return  // server doesn't support cursors
+//   cursors.online()      // call when text subscription is online
+//   cursors.offline()     // call when text subscription goes offline
+//   cursors.set(selectionStart, selectionEnd)
+//   cursors.changed(patches)
+//   cursors.destroy()
+//
+async function cursor_client(url, { peer, get_text, on_change }) {
+    // --- feature detection: HEAD probe ---
+    try {
+        var head_res = await fetch(url, {
+            method: 'HEAD',
+            headers: { 'Accept': 'application/text-cursors+json' }
+        })
+        var ct = head_res.headers.get('content-type') || ''
+        if (!ct.includes('application/text-cursors+json')) return null
+    } catch (e) { return null }
+
+    var selections = {}     // peer_id -> [{ from, to }]  in JS string indices
+    var online = false      // true after online(), false after offline()
+    var pending = null      // buffered cursor snapshot while offline
+    var last_sent = null
+    var last_ranges = null  // last cursor ranges (JS indices) for re-PUT on reconnect
+    var send_timer = null
+    var ac = new AbortController()
+    var put_ac = null       // AbortController for in-flight PUT retry
+
+    // --- code-point <-> JS index helpers ---
+
+    function code_point_to_index_map(s) {
+        var m = []
+        var c = 0
+        for (var i = 0; i < s.length; i++) {
+            m[c] = i
+            var code = s.charCodeAt(i)
+            if (code >= 0xd800 && code <= 0xdbff) i++
+            c++
+        }
+        m[c] = i
+        return m
+    }
+
+    function js_index_to_code_point(s, idx) {
+        var c = 0
+        for (var i = 0; i < idx; i++) {
+            var code = s.charCodeAt(i)
+            if (code >= 0xd800 && code <= 0xdbff) i++
+            c++
+        }
+        return c
+    }
+
+    // --- position transform through edits ---
+
+    function transform_pos(pos, del_start, del_len, ins_len) {
+        if (del_len === 0) {
+            if (pos < del_start) return pos
+            return pos + ins_len
+        }
+        if (pos <= del_start) return pos
+        if (pos <= del_start + del_len) return del_start + ins_len
+        return pos - del_len + ins_len
+    }
+
+    // --- process cursor data (code-points → JS indices) ---
+
+    function process_data(data, is_snapshot) {
+        var text = get_text()
+        var m = code_point_to_index_map(text)
+        var changed = {}
+
+        // Full snapshot: remove peers no longer present
+        if (is_snapshot) {
+            for (var id of Object.keys(selections)) {
+                if (!(id in data)) {
+                    delete selections[id]
+                    changed[id] = []
+                }
+            }
+        }
+
+        for (var id of Object.keys(data)) {
+            if (id === peer) continue
+            var ranges = data[id]
+            if (!ranges) {
+                delete selections[id]
+                changed[id] = []
+            } else {
+                selections[id] = ranges.map(function(r) {
+                    return {
+                        from: m[r.from] !== undefined ? m[r.from] : text.length,
+                        to: m[r.to] !== undefined ? m[r.to] : text.length,
+                    }
+                })
+                changed[id] = selections[id]
+            }
+        }
+
+        if (on_change) on_change(changed)
+    }
+
+    // --- PUT helper ---
+
+    function do_put(ranges) {
+        if (put_ac) put_ac.abort()
+        put_ac = new AbortController()
+        var text = get_text()
+        var cp_ranges = ranges.map(function(r) {
+            return {
+                from: js_index_to_code_point(text, r.from),
+                to: js_index_to_code_point(text, r.to),
+            }
+        })
+        braid_fetch(url, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/text-cursors+json',
+                Peer: peer,
+                'Content-Range': 'json [' + JSON.stringify(peer) + ']',
+            },
+            body: JSON.stringify(cp_ranges),
+            retry: function(res) { return res.status === 425 },
+            signal: put_ac.signal,
+        }).catch(function() {})
+    }
+
+    // --- subscribe for remote cursors ---
+    // The subscription stays alive always. Data is only processed when online.
+
+    var connected_before = false
+    braid_fetch(url, {
+        subscribe: true,
+        retry: { onRes: function() {
+            if (connected_before && online) {
+                // Reconnecting — go offline to clear stale cursors.
+                // The application will call online() again when text is ready.
+                var changed = {}
+                for (var id of Object.keys(selections)) changed[id] = []
+                selections = {}
+                online = false
+                pending = null
+                if (on_change && Object.keys(changed).length) on_change(changed)
+            }
+            connected_before = true
+        }},
+        peer,
+        headers: {
+            Accept: 'application/text-cursors+json',
+            Heartbeats: '10',
+        },
+        signal: ac.signal,
+    }).then(function(r) {
+        r.subscribe(function(update) {
+            var data
+            var is_snapshot = false
+            if (update.body_text != null) {
+                data = JSON.parse(update.body_text)
+                is_snapshot = true
+            } else if (update.patches && update.patches.length) {
+                var p = update.patches[0]
+                var ct = p.content_text
+                data = { [JSON.parse(p.range)[0]]: ct ? JSON.parse(ct) : null }
+            } else return
+
+            if (!online) {
+                // Buffer snapshot data; apply patches to buffered data
+                if (is_snapshot || !pending) pending = {}
+                if (is_snapshot) pending = data
+                else for (var id of Object.keys(data)) pending[id] = data[id]
+                return
+            }
+
+            process_data(data, is_snapshot)
+        })
+    })
+
+    return {
+        // Call when text subscription comes online.
+        // Processes any buffered cursor data and re-PUTs local cursor.
+        online: function() {
+            online = true
+            if (pending) {
+                process_data(pending, true)
+                pending = null
+            }
+            if (last_ranges) do_put(last_ranges)
+        },
+
+        // Call when text subscription goes offline.
+        // Clears all remote cursors.
+        offline: function() {
+            online = false
+            pending = null
+            if (put_ac) put_ac.abort()
+            if (send_timer) { clearTimeout(send_timer); send_timer = null }
+            var changed = {}
+            for (var id of Object.keys(selections)) {
+                changed[id] = []
+            }
+            selections = {}
+            if (on_change && Object.keys(changed).length) on_change(changed)
+        },
+
+        // Send local cursor/selection position (JS string indices).
+        // Supports multiple selections: set(from, to) or set([{from, to}, ...])
+        set: function(from_or_ranges, to) {
+            var ranges
+            if (Array.isArray(from_or_ranges)) {
+                ranges = from_or_ranges
+            } else {
+                ranges = [{ from: from_or_ranges, to: to }]
+            }
+
+            // Skip if same as last sent
+            var key = JSON.stringify(ranges)
+            if (key === last_sent) return
+            last_sent = key
+            last_ranges = ranges
+
+            if (!online) return
+
+            // Debounce 50ms
+            if (send_timer) clearTimeout(send_timer)
+            send_timer = setTimeout(function() { do_put(ranges) }, 50)
+        },
+
+        // Transform all stored remote cursor positions through text edits.
+        // patches: [{ range: [start, end], content: string }] in JS string indices.
+        changed: function(patches) {
+            var any_changed = false
+            for (var id of Object.keys(selections)) {
+                selections[id] = selections[id].map(function(sel) {
+                    var from = sel.from
+                    var to = sel.to
+                    for (var p of patches) {
+                        var del_len = p.range[1] - p.range[0]
+                        var ins_len = p.content.length
+                        from = transform_pos(from, p.range[0], del_len, ins_len)
+                        to = transform_pos(to, p.range[0], del_len, ins_len)
+                    }
+                    return { from, to }
+                })
+                any_changed = true
+            }
+            if (any_changed && on_change) {
+                // Report all current selections
+                var all = {}
+                for (var id of Object.keys(selections))
+                    all[id] = selections[id]
+                on_change(all)
+            }
+        },
+
+        // Get current selections (for reading state)
+        get_selections: function() {
+            var copy = {}
+            for (var id of Object.keys(selections))
+                copy[id] = selections[id]
+            return copy
+        },
+
+        destroy: function() {
+            ac.abort()
+            if (put_ac) put_ac.abort()
+            if (send_timer) clearTimeout(send_timer)
+        },
+    }
+}

package/{editor.html → client/editor.html}

@@ -4,20 +4,27 @@
 <script src="https://braid.org/code/myers-diff1.js"></script>
 <script src="https://unpkg.com/braid-http@~1.3/braid-http-client.js"></script>
 <script src="/web-utils.js"></script>
-<script src="/simpleton-client.js"></script>
+<script src="/simpleton-sync.js"></script>
+<script src="/cursor-highlights.js"></script>
+<script src="/cursor-sync.js"></script>
 <script>
 
-  let simpleton = simpleton_client(location.pathname, {
-    on_patches: (patches) => apply_patches_and_update_selection(the_editor, patches),
+  var cursors = cursor_highlights(the_editor, location.pathname)
+
+  var simpleton = simpleton_client(location.pathname, {
+    on_patches: (patches) => {
+      apply_patches_and_update_selection(the_editor, patches)
+      cursors.on_patches(patches)
+    },
     get_patches: (prev_state) => diff(prev_state, the_editor.value),
     get_state: () => the_editor.value,
     on_error: (e) => set_error_state(the_editor),
     on_ack: () => set_acked_state(the_editor)
-  });
+  })
 
   the_editor.oninput = (e) => {
     set_acked_state(the_editor, false)
-    simpleton.changed()
+    cursors.on_edit(simpleton.changed())
   }
 
 </script>

package/{markdown-editor.html → client/markdown-editor.html}

@@ -3,22 +3,29 @@
 <script src="https://braid.org/code/myers-diff1.js"></script>
 <script src="https://unpkg.com/braid-http@~1.3/braid-http-client.js"></script>
 <script src="/web-utils.js"></script>
-<script src="/simpleton-client.js"></script>
+<script src="/simpleton-sync.js"></script>
+<script src="/cursor-highlights.js"></script>
+<script src="/cursor-sync.js"></script>
 <body>
   <div id="markdown_container" style="max-width: 750px; padding: 10px 60px"></div>
   <div id="bottom_spacer" style="height: 50vh; display: none;"></div>
-  <textarea 
-    id="the_editor"
-    style="
+  <div id="editor_wrap" style="
       position: fixed;
       bottom: 0;
       right: 0;
       width: 45vw;
       height: 100%;
-      font-size: 15px;
-      font-family: helvetica, arial, avenir, lucida grande;
-      hyphens: none;
-    "></textarea>
+    ">
+    <textarea
+      id="the_editor"
+      style="
+        width: 100%;
+        height: 100%;
+        font-size: 15px;
+        font-family: helvetica, arial, avenir, lucida grande;
+        hyphens: none;
+      "></textarea>
+  </div>
   <div 
     id="edit-button"
     style="
@@ -38,9 +45,12 @@ var first_time = true
 var render_timer = null
 var render_delay = 100
 
+var cursors = cursor_highlights(the_editor, location.pathname)
+
 var simpleton = simpleton_client(location.pathname, {
   on_patches: (patches) => {
     apply_patches_and_update_selection(the_editor, patches)
+    cursors.on_patches(patches)
     update_markdown_later()
   },
   get_patches: (prev_state) => diff(prev_state, the_editor.value),
@@ -51,7 +61,7 @@ var simpleton = simpleton_client(location.pathname, {
 
 the_editor.oninput = (e) => {
   set_acked_state(the_editor, false)
-  simpleton.changed()
+  cursors.on_edit(simpleton.changed())
   update_markdown_later()
 }
 
@@ -70,9 +80,9 @@ function update_layout() {
   var vert = window.innerWidth < 1200
   markdown_container.style.width = editing && !vert ? '55vw' : ''
   bottom_spacer.style.display = !editing || !vert ? 'none' : ''
-  the_editor.style.width = vert ? '100%' : '45vw'
-  the_editor.style.height = vert ? '50vh' : '100%'
-  the_editor.style.display = !editing ? 'none' : ''
+  editor_wrap.style.width = vert ? '100%' : '45vw'
+  editor_wrap.style.height = vert ? '50vh' : '100%'
+  editor_wrap.style.display = !editing ? 'none' : ''
 }
 
 function toggle_editor() {

package/{simpleton-client.js → client/simpleton-sync.js}

@@ -47,6 +47,7 @@ function simpleton_client(url, {
 
     on_error,
     on_res,
+    on_online,
     on_ack,
     send_digests
 }) {
@@ -67,6 +68,7 @@ function simpleton_client(url, {
             ...(content_type ? {Accept: content_type} : {}) },
         subscribe: true,
         retry: () => true,
+        onSubscriptionStatus: (status) => { if (on_online) on_online(status) },
         parents: () => current_version.length ? current_version : null,
         peer,
         signal: ac.signal
@@ -138,71 +140,91 @@ function simpleton_client(url, {
       stop: async () => {
         ac.abort()
       },
-      changed: async () => {
+      changed: () => {
         if (outstanding_changes >= max_outstanding_changes) return
-        while (true) {
-            if (generate_local_diff_update) {
-                // DEPRECATED
-                var update = generate_local_diff_update(prev_state)
-                if (!update) return   // Stop if there wasn't a change!
-                var {patches, new_state} = update
-            } else {
-                var new_state = get_state()
-                if (new_state === prev_state) return // Stop if there wasn't a change!
-                var patches = get_patches ? get_patches(prev_state) :
-                    [simple_diff(prev_state, new_state)]
-            }
 
-            // convert from js-indicies to code-points
-            let c = 0
-            let i = 0
-            for (let p of patches) {
-                while (i < p.range[0]) {
-                    i += get_char_size(prev_state, i)
-                    c++
-                }
-                p.range[0] = c
+        if (generate_local_diff_update) {
+            // DEPRECATED
+            var update = generate_local_diff_update(prev_state)
+            if (!update) return   // Stop if there wasn't a change!
+            var {patches, new_state} = update
+        } else {
+            var new_state = get_state()
+            if (new_state === prev_state) return // Stop if there wasn't a change!
+            var patches = get_patches ? get_patches(prev_state) :
+                [simple_diff(prev_state, new_state)]
+        }
+
+        // Save JS-index patches before code-point conversion mutates them
+        var js_patches = patches.map(p => ({range: [...p.range], content: p.content}))
+
+        ;(async () => {
+            while (true) {
+                // convert from js-indicies to code-points
+                let c = 0
+                let i = 0
+                for (let p of patches) {
+                    while (i < p.range[0]) {
+                        i += get_char_size(prev_state, i)
+                        c++
+                    }
+                    p.range[0] = c
+
+                    while (i < p.range[1]) {
+                        i += get_char_size(prev_state, i)
+                        c++
+                    }
+                    p.range[1] = c
 
-                while (i < p.range[1]) {
-                    i += get_char_size(prev_state, i)
-                    c++
+                    char_counter += p.range[1] - p.range[0]
+                    char_counter += count_code_points(p.content)
+
+                    p.unit = "text"
+                    p.range = `[${p.range[0]}:${p.range[1]}]`
                 }
-                p.range[1] = c
 
-                char_counter += p.range[1] - p.range[0]
-                char_counter += count_code_points(p.content)
+                var version = [peer + "-" + char_counter]
 
-                p.unit = "text"
-                p.range = `[${p.range[0]}:${p.range[1]}]`
-            }
+                var parents = current_version
+                current_version = version
+                prev_state = new_state
+
+                outstanding_changes++
+                try {
+                    var r = await braid_fetch(url, {
+                        headers: {
+                            "Merge-Type": "simpleton",
+                            ...send_digests && {"Repr-Digest": await get_digest(prev_state)},
+                            ...content_type && {"Content-Type": content_type}
+                        },
+                        method: "PUT",
+                        retry: (res) => res.status !== 550,
+                        version, parents, patches,
+                        peer
+                    })
+                    if (!r.ok) throw new Error(`bad http status: ${r.status}${(r.status === 401 || r.status === 403) ? ` (access denied)` : ''}`)
+                } catch (e) {
+                    on_error(e)
+                    throw e
+                }
+                outstanding_changes--
+                if (on_ack && !outstanding_changes) on_ack()
 
-            var version = [peer + "-" + char_counter]
-
-            var parents = current_version
-            current_version = version
-            prev_state = new_state
-
-            outstanding_changes++
-            try {
-                var r = await braid_fetch(url, {
-                    headers: {
-                        "Merge-Type": "simpleton",
-                        ...send_digests && {"Repr-Digest": await get_digest(prev_state)},
-                        ...content_type && {"Content-Type": content_type}
-                    },
-                    method: "PUT",
-                    retry: (res) => res.status !== 550,
-                    version, parents, patches,
-                    peer
-                })
-                if (!r.ok) throw new Error(`bad http status: ${r.status}${(r.status === 401 || r.status === 403) ? ` (access denied)` : ''}`)
-            } catch (e) {
-                on_error(e)
-                throw e
+                // Check for more changes that accumulated while we were sending
+                if (generate_local_diff_update) {
+                    update = generate_local_diff_update(prev_state)
+                    if (!update) return
+                    ;({patches, new_state} = update)
+                } else {
+                    new_state = get_state()
+                    if (new_state === prev_state) return
+                    patches = get_patches ? get_patches(prev_state) :
+                        [simple_diff(prev_state, new_state)]
+                }
             }
-            outstanding_changes--
-            if (on_ack && !outstanding_changes) on_ack()
-        }
+        })()
+
+        return js_patches
       }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-text",
-  "version": "0.2.116",
+  "version": "0.3.1",
   "description": "Library for collaborative text over http using braid.",
   "author": "Braid Working Group",
   "repository": "braid-org/braid-text",
@@ -8,18 +8,21 @@
   "scripts": {
     "test": "node test/test.js"
   },
+  "main": "server.js",
   "files": [
-    "index.js",
+    "server.js",
     "simpleton-client.js",
-    "web-utils.js",
+    "client/simpleton-sync.js",
+    "client/cursor-sync.js",
+    "client/cursor-highlights.js",
+    "client/web-utils.js",
     "README.md",
-    "AI-README.md",
-    "editor.html",
-    "markdown-editor.html",
+    "client/editor.html",
+    "client/markdown-editor.html",
     "server-demo.js"
   ],
   "dependencies": {
     "@braid.org/diamond-types-node": "^2.0.1",
-    "braid-http": "~1.3.89"
+    "braid-http": "^1.3.95"
   }
 }

package/server-demo.js

@@ -1,5 +1,5 @@
 var port = process.argv[2] || 8888
-var braid_text = require("./index.js")
+var braid_text = require("./server.js")
 
 // TODO: set a custom database folder
 // (the default is ./braid-text-db)
@@ -16,13 +16,14 @@ var server = require("http").createServer(async (req, res) => {
     var q = req.url.split('?').slice(-1)[0]
     if (q === 'editor' || q === 'markdown-editor') {
         res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-cache" })
-        require("fs").createReadStream(`./${q}.html`).pipe(res)
+        require("fs").createReadStream(`./client/${q}.html`).pipe(res)
         return
     }
 
-    if (req.url === '/simpleton-client.js' || req.url === '/web-utils.js') {
+    if (req.url === '/simpleton-sync.js' || req.url === '/web-utils.js'
+        || req.url === '/cursor-highlights.js' || req.url === '/cursor-sync.js') {
         res.writeHead(200, { "Content-Type": "text/javascript", "Cache-Control": "no-cache" })
-        require("fs").createReadStream("." + req.url).pipe(res)
+        require("fs").createReadStream("./client" + req.url).pipe(res)
         return
     }
 

package/{index.js → server.js}

@@ -3,6 +3,7 @@ let { Doc, OpLog, Branch } = require("@braid.org/diamond-types-node")
 let {http_server: braidify, fetch: braid_fetch} = require("braid-http")
 let fs = require("fs")
 
+
 function create_braid_text() {
     let braid_text = {
         verbose: false,
@@ -371,51 +372,9 @@ function create_braid_text() {
 
         let peer = req.headers["peer"]
 
-        // selection sharing prototype
-        if (req.headers['selection-sharing-prototype']) {
-            res.setHeader('Content-Type', 'application/json')
-
-            if (!resource.selections) resource.selections = {}
-            if (!resource.selection_clients) resource.selection_clients = new Set()
-
-            if (req.method === "GET" || req.method === "HEAD") {
-                if (!req.subscribe) {
-                    return my_end(200, JSON.stringify(resource.selections))
-                } else {
-                    var client = {peer, res}
-                    resource.selection_clients.add(client)
-                    res.startSubscription({
-                        onClose: () => resource.selection_clients.delete(client)
-                    })
-                    res.sendUpdate({ body: JSON.stringify(resource.selections) })
-                    return
-                }
-            } else if (req.method == "PUT" || req.method == "POST" || req.method == "PATCH") {
-                var body = (await req.patches())[0].content_text
-                var json = JSON.parse(body)
-
-                // only keep new selections if they are newer
-                for (var [user, selection] of Object.entries(json)) {
-                    if (resource.selections[user] && resource.selections[user].time > selection.time) delete json[user]
-                    else resource.selections[user] = selection
-                }
-
-                // remove old selections that are too old
-                var long_ago = Date.now() - 1000 * 60 * 5
-                for (var [user, selection] of Object.entries(resource.selections))
-                    if (selection.time < long_ago) {
-                        delete resource.selections[user]
-                        delete json[user]
-                    }
-
-                body = JSON.stringify(json)
-                if (body.length > 2)
-                    for (let client of resource.selection_clients)
-                        if (client.peer !== peer) client.res.sendUpdate({ body })
-                
-                return my_end(200)
-            }
-        }
+        // Implement Multiplayer Text Cursors
+        if (await handle_cursors(resource, req, res))
+            return
 
         let merge_type = req.headers["merge-type"]
         if (!merge_type) merge_type = 'simpleton'
@@ -1023,6 +982,9 @@ function create_braid_text() {
             resource.val = resource.doc.get()
             resource.version = resource.doc.getRemoteVersion().map(x => x.join("-")).sort()
 
+            // Transform stored cursor positions through the applied patches
+            if (resource.cursor_state) resource.cursor_state.transform(patches)
+
             var post_commit_updates = []
 
             if (options.merge_type != "dt") {
@@ -1144,7 +1106,7 @@ function create_braid_text() {
             if (braid_text.db_folder) {
                 await db_folder_init()
                 var pages = new Set()
-                for (let x of await require('fs').promises.readdir(braid_text.db_folder)) pages.add(decode_filename(x.replace(/\.\w+$/, '')))
+                for (let x of await require('fs').promises.readdir(braid_text.db_folder)) if (/\.\d+$/.test(x)) pages.add(decode_filename(x.replace(/\.\d+$/, '')))
                 return [...pages.keys()]
             } else return Object.keys(braid_text.cache)
         } catch (e) { return [] }
@@ -3011,4 +2973,174 @@ function create_braid_text() {
     return braid_text
 }
 
+
+// Cursor lifecycle state for a single resource.
+//
+// Each peer's cursor is stored as:
+//   cursors[peer_id] = { data: [{from, to}, ...], last_connected: timestamp }
+//
+// A cursor is "online" if the peer has an active subscription, OR if
+// last_connected is within expiry_ms.  Expired entries are lazily
+// cleaned on each snapshot.
+//
+// This is factored out so that the same logic could conceptually run
+// on a client as well (e.g. for client-side filtering of stale cursors).
+// Transform a single position through a delete+insert operation.
+// Positions before the edit are unchanged; positions inside the deleted
+// range collapse to the edit point; positions after shift by the net change.
+// Pure inserts (del_len=0) push positions at the insert point forward.
+function transform_pos(pos, del_start, del_len, ins_len) {
+    if (del_len === 0) {
+        // Pure insert: push positions at or after the insert point
+        if (pos < del_start) return pos
+        return pos + ins_len
+    }
+    if (pos <= del_start) return pos
+    if (pos <= del_start + del_len) return del_start + ins_len
+    return pos - del_len + ins_len
+}
+
+class cursor_state {
+    constructor() {
+        this.cursors = {}
+        this.subscribers = new Set()
+    }
+
+    subscribed_peers() {
+        var peers = new Set()
+        for (var sub of this.subscribers)
+            if (sub.peer) peers.add(sub.peer)
+        return peers
+    }
+
+    broadcast(peer_id, data, exclude_peer) {
+        var content = data != null ? JSON.stringify(data) : ''
+        for (var sub of this.subscribers)
+            if (sub.peer !== exclude_peer)
+                try { sub.res.sendUpdate({
+                    patches: [{
+                        unit: 'json',
+                        range: '[' + JSON.stringify(peer_id) + ']',
+                        content: content
+                    }]
+                }) } catch (e) {}
+    }
+
+    snapshot() {
+        var result = {}
+        for (var [peer_id, cursor] of Object.entries(this.cursors))
+            result[peer_id] = cursor.data
+        return result
+    }
+
+    subscribe(subscriber) {
+        this.subscribers.add(subscriber)
+    }
+
+    unsubscribe(subscriber) {
+        this.subscribers.delete(subscriber)
+        var peer_id = subscriber.peer
+        if (peer_id && !this.subscribed_peers().has(peer_id)) {
+            delete this.cursors[peer_id]
+            this.broadcast(peer_id, null)
+        }
+    }
+
+    // Transform all stored cursor positions through text patches.
+    // Each patch has { range: [start, end], content_codepoints: [...] }.
+    // Patches must be sorted by range[0] ascending (original coordinates).
+    transform(patches) {
+        if (!patches || !patches.length) return
+
+        for (var cursor of Object.values(this.cursors)) {
+            cursor.data = cursor.data.map(sel => {
+                var from = sel.from
+                var to = sel.to
+
+                // Apply each patch's effect on positions, accumulating offset
+                var offset = 0
+                for (var p of patches) {
+                    var del_start = p.range[0] + offset
+                    var del_end = p.range[1] + offset
+                    var del_len = del_end - del_start
+                    var ins_len = p.content_codepoints.length
+
+                    from = transform_pos(from, del_start, del_len, ins_len)
+                    to = transform_pos(to, del_start, del_len, ins_len)
+
+                    offset += ins_len - del_len
+                }
+
+                return {from, to}
+            })
+        }
+    }
+
+    put(peer_id, cursor_data) {
+        if (!peer_id || !cursor_data) return false
+        if (!this.subscribed_peers().has(peer_id)) return false
+        this.cursors[peer_id] = { data: cursor_data }
+        this.broadcast(peer_id, cursor_data, peer_id)
+        return true
+    }
+}
+
+// Handle cursor requests routed by content negotiation.
+// Returns true if the request was handled, false to fall through.
+async function handle_cursors(resource, req, res) {
+    var accept = req.headers['accept'] || ''
+    var content_type = req.headers['content-type'] || ''
+
+    if (!accept.includes('application/text-cursors+json')
+        && !content_type.includes('application/text-cursors+json'))
+        return false
+
+    res.setHeader('Content-Type', 'application/text-cursors+json')
+
+    if (!resource.cursor_state) resource.cursor_state = new cursor_state()
+    var cursors = resource.cursor_state
+    var peer = req.headers['peer']
+
+    if (req.method === 'GET' || req.method === 'HEAD') {
+        if (!req.subscribe) {
+            res.writeHead(200)
+            if (req.method === 'HEAD')
+                res.end()
+            else
+                res.end(JSON.stringify(cursors.snapshot()))
+        } else {
+            var subscriber = {peer, res}
+            cursors.subscribe(subscriber)
+            res.startSubscription({
+                onClose: () => cursors.unsubscribe(subscriber)
+            })
+            res.sendUpdate({ body: JSON.stringify(cursors.snapshot()) })
+        }
+    } else if (req.method === 'PUT' || req.method === 'POST' || req.method === 'PATCH') {
+        var raw_body = await new Promise((resolve, reject) => {
+            var chunks = []
+            req.on('data', chunk => chunks.push(chunk))
+            req.on('end', () => resolve(Buffer.concat(chunks).toString()))
+            req.on('error', reject)
+        })
+        var range = req.headers['content-range']
+        if (!range || !range.startsWith('json ')) {
+            res.writeHead(400)
+            res.end('Missing Content-Range: json [<peer-id>] header')
+            return true
+        }
+        var cursor_peer = JSON.parse(range.slice(5))[0]
+        var accepted = cursors.put(cursor_peer, JSON.parse(raw_body))
+        if (accepted) {
+            res.writeHead(200)
+            res.end()
+        } else {
+            res.writeHead(425)
+            res.end('Peer not subscribed')
+        }
+    }
+
+    return true
+}
+
 module.exports = create_braid_text()

package/AI-README.md

@@ -1,82 +0,0 @@
-# AI-README for braid-text
-
-This document provides AI assistants with key information about the braid-text project, including development procedures and architecture notes.
-
-## Release Procedure
-
-Follow these steps to create a new release:
-
-1. **Version Bump**
-   - Update the version in `package.json` (use smallest version bump: patch level)
-   - Current version format: `0.2.x`
-
-2. **Run Tests**
-   - Run `node test/test.js` - should show all 74 tests passing
-   - Run `node test/fuzz-test.js` - runs 10,000 iterations (takes ~5-10 minutes), should complete with `best_n = Infinity @ NaN` indicating success
-   - Both tests must pass before proceeding
-
-3. **Commit Changes**
-   - Use commit message format: `VERSION - description`
-   - Example: `0.2.73 - adds automatic test cleanup`
-   - Keep description concise and descriptive
-
-4. **Push to Remote**
-   - Run `git push` to push to the remote repository
-
-5. **Publish to npm**
-   - Run `npm publish` to publish the new version
-
-## Test Suite
-
-### test/test.js
-- Main test suite with 74 tests
-- Tests Braid protocol, version control, syncing, and collaboration features
-- Automatically cleans up `test_db_folder` after completion
-- Run with: `node test/test.js`
-- Filter tests with: `node test/test.js --filter="sync"`
-
-### test/fuzz-test.js
-- Fuzz testing suite that generates random edits and verifies correctness
-- Tests diamond-types integration and merge operations
-- Runs 10,000 iterations by default (takes approximately 5-10 minutes)
-- Success indicated by `best_n = Infinity @ NaN` at completion (no failures found)
-- Run with: `node test/fuzz-test.js`
-- Let it run to completion - do not interrupt
-
-## Project Structure
-
-- **index.js** - Main library file implementing Braid protocol for collaborative text
-- **package.json** - Package configuration and dependencies
-- **test/** - Test suite directory
-  - **test.js** - Main test runner (supports both console and browser modes)
-  - **tests.js** - Test definitions (shared between console and browser)
-  - **fuzz-test.js** - Fuzz testing suite
-  - **test.html** - Browser test interface
-
-## Key Dependencies
-
-- **@braid.org/diamond-types-node** - CRDT implementation for conflict-free text editing
-- **braid-http** - Braid protocol HTTP implementation
-- **url-file-db** - File-based database for persistent storage
-
-## Architecture Notes
-
-- Implements the Braid protocol for synchronizing collaborative text over HTTP
-- Uses diamond-types CRDT for conflict-free merging
-- Supports both simpleton and dt (diamond-types) merge strategies
-- Provides version control with parents tracking and version history
-- File-based persistence with case-insensitive filesystem support
-
-## Common Operations
-
-### Running Tests Locally
-```bash
-node test/test.js              # Run all tests
-node test/test.js --filter="sync"  # Run tests matching "sync"
-node test/fuzz-test.js         # Run fuzz tests
-```
-
-### Test Cleanup
-The test suite automatically cleans up temporary files and databases. If manual cleanup is needed:
-- Test database is created at `test/test_db_folder` during tests
-- Automatically removed after test completion