Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

32.3 KB
Raw Blame
/**
 * Annotation Surface (shared component)
 *
 * Word-review-style inline comments over a container of IMMUTABLE
 * rendered text (research reports, library-document extracted text —
 * immutability is what makes quote anchors safe). Provides:
 *   - a selection toolbar (Comment + host-supplied extra actions),
 *   - the comment-entry popover (each comment is saved as a NOTE by the
 *     host's endpoint; this component only ships quote/prefix/suffix +
 *     comment),
 *   - the anchor engine: whitespace-normalized quote matching with
 *     virtual spaces at <br>/block boundaries, per-text-node <mark>
 *     wrapping, prefix/suffix disambiguation for repeated phrases,
 *   - highlight popovers with Open note / Delete.
 *
 * Hosts (components/research_notes.js, components/document_notes.js)
 * call LDRAnnotationSurface.init(config) with their endpoints. The ONE
 * deliberate global is the namespaced window.LDRAnnotationSurface —
 * unique enough not to collide with the deferred shared scripts.
 *
 * URL security: all URLs used here come from the host config and are
 * same-origin relative paths; no external URLs are handled. External URL
 * validation is available via URLValidator.isSafeUrl if that changes.
 */
(function() {
    'use strict';

    // ------------------------------------------------------------------
    // Anchor engine (pure — exposed on the test hook below)
    // ------------------------------------------------------------------

    // Elements whose boundary reads as a break in the rendered text even
    // though they contribute NO character to textContent: <br> most of
    // all (markdown renderers turn intra-paragraph newlines into <br>, so
    // textContent says "butshared" where the user sees — and selects —
    // "but\nshared"), plus block-level containers.
    const BLOCK_BOUNDARY_RE = /^(?:P|DIV|LI|UL|OL|H[1-6]|BLOCKQUOTE|PRE|TABLE|THEAD|TBODY|TR|TD|TH|SECTION|ARTICLE|BR|HR)$/;

    /**
     * Build a whitespace-normalized string over the container's rendered
     * text plus a per-character map back to (node, offset). Whitespace
     * runs collapse to one space, and <br>/block boundaries emit a
     * VIRTUAL space (map entry null — no DOM position), so a quote
     * captured from selection.toString() (which inserts newlines at those
     * boundaries) matches the same passage in the haystack.
     */
    function buildNormalizedText(root) {
        const map = [];
        let text = '';
        let lastWasSpace = true; // drop leading whitespace

        const pushVirtualSpace = () => {
            if (!lastWasSpace) {
                text += ' ';
                map.push(null);
                lastWasSpace = true;
            }
        };

        // Recursive DFS (document order, same as a TreeWalker) so a block/<br>
        // boundary can emit a virtual space on BOTH sides. Emitting only on
        // ENTER left bare text that immediately follows a closed block (e.g. a
        // caption right after </blockquote>) glued to the block's text
        // ("insightas noted"), so a quote spanning that boundary — where a
        // selection inserts a newline — never anchored.
        const walk = (parent) => {
            for (let node = parent.firstChild; node; node = node.nextSibling) {
                if (node.nodeType === Node.ELEMENT_NODE) {
                    const isBoundary = BLOCK_BOUNDARY_RE.test(node.tagName);
                    if (isBoundary) pushVirtualSpace();
                    walk(node);
                    if (isBoundary) pushVirtualSpace();
                } else if (node.nodeType === Node.TEXT_NODE) {
                    const s = node.textContent;
                    for (let i = 0; i < s.length; i++) {
                        if (/\s/.test(s[i])) {
                            if (!lastWasSpace) {
                                text += ' ';
                                map.push({ node, offset: i });
                                lastWasSpace = true;
                            }
                        } else {
                            text += s[i];
                            map.push({ node, offset: i });
                            lastWasSpace = false;
                        }
                    }
                }
            }
        };
        walk(root);

        // Drop trailing boundary/whitespace: the outermost element's exit adds
        // a trailing virtual space, but a quote is always trimmed, so the
        // haystack should end at its last real character (keeps the text stable
        // and matchable).
        while (text.endsWith(' ')) {
            text = text.slice(0, -1);
            map.pop();
        }
        return { text, map };
    }

    function normalizeWhitespace(s) {
        return String(s || '').replace(/\s+/g, ' ').trim();
    }

    /**
     * Locate `quote` in the normalized haystack; when the phrase repeats,
     * prefer the occurrence whose surroundings best match prefix/suffix.
     */
    function findQuoteIndex(haystack, quote, prefix, suffix) {
        // Empty quote: indexOf('', n) never returns -1, so the hit-collection
        // loop below would spin forever. Callers already guard, but this is
        // the exposed pure engine — fail closed.
        if (!quote) return -1;
        const hits = [];
        let i = haystack.indexOf(quote);
        while (i !== -1) {
            hits.push(i);
            i = haystack.indexOf(quote, i + 1);
        }
        if (!hits.length) return -1;
        if (hits.length === 1 || (!prefix && !suffix)) return hits[0];

        const sharedEndLen = (a, b) => {
            let n = 0;
            while (n < a.length && n < b.length && a[a.length - 1 - n] === b[b.length - 1 - n]) n++;
            return n;
        };
        const sharedStartLen = (a, b) => {
            let n = 0;
            while (n < a.length && n < b.length && a[n] === b[n]) n++;
            return n;
        };

        let best = hits[0];
        let bestScore = -1;
        for (const h of hits) {
            let score = 0;
            if (prefix) score += sharedEndLen(haystack.slice(Math.max(0, h - prefix.length), h), prefix);
            if (suffix) score += sharedStartLen(haystack.slice(h + quote.length, h + quote.length + suffix.length), suffix);
            if (score > bestScore) {
                bestScore = score;
                best = h;
            }
        }
        return best;
    }

    /**
     * Wrap the normalized-index range [start, end) in <mark> elements —
     * one per text-node segment (a Range spanning element boundaries
     * can't be surrounded in one piece). Null map entries are virtual
     * boundary spaces with no DOM position.
     */
    function wrapNormalizedRange(map, start, end, noteId) {
        const segments = [];
        let current = null;
        for (let i = start; i < end; i++) {
            const m = map[i];
            if (!m) {
                if (current) {
                    segments.push(current);
                    current = null;
                }
                continue;
            }
            if (current && current.node === m.node && m.offset === current.endOffset) {
                current.endOffset = m.offset + 1;
            } else {
                if (current) segments.push(current);
                current = { node: m.node, startOffset: m.offset, endOffset: m.offset + 1 };
            }
        }
        if (current) segments.push(current);

        // Wrap segments HIGHEST-offset-first. A quote spanning a collapsed
        // whitespace run (e.g. a double space) maps to two non-contiguous
        // segments on the SAME text node; wrapping the earlier one first calls
        // surroundContents, which splits that node and shortens it, so the
        // later segment's offsets become out of bounds -> IndexSizeError.
        // Going back-to-front keeps every not-yet-wrapped segment's offsets
        // valid. The whole range op is guarded so one bad segment (e.g. an
        // overlap with a prior mark) is skipped, not fatal to the other marks.
        for (const seg of segments.slice().reverse()) {
            const mark = document.createElement('mark');
            mark.className = 'ldr-research-annotation';
            mark.dataset.noteId = noteId;
            try {
                const range = document.createRange();
                range.setStart(seg.node, seg.startOffset);
                range.setEnd(seg.node, seg.endOffset);
                range.surroundContents(mark);
            } catch (e) {
                SafeLogger.error('Annotation wrap failed:', e);
            }
        }
    }

    /** Apply one annotation's highlight; returns whether it anchored. */
    function applyAnnotation(container, annotation) {
        const quote = normalizeWhitespace(annotation.quote);
        if (!quote) return false;
        // Rebuilt per annotation: wrapping mutates/splits text nodes, so
        // earlier maps go stale. Targets are a few hundred KB at most and
        // annotations number in the dozens — fine.
        const { text, map } = buildNormalizedText(container);
        const idx = findQuoteIndex(
            text,
            quote,
            normalizeWhitespace(annotation.prefix),
            normalizeWhitespace(annotation.suffix)
        );
        if (idx === -1) return false;
        wrapNormalizedRange(map, idx, idx + quote.length, annotation.note_id);
        return true;
    }

    // ------------------------------------------------------------------
    // Surface factory
    // ------------------------------------------------------------------

    // Component-local wrappers over the shared trio (window.NotesShared) —
    // local names kept for shadowing-safety; the bodies live in one place.
    const csrfToken = () => window.NotesShared.csrfToken();
    const toast = (message, type) => window.NotesShared.toast(message, type);

    /**
     * Wire an annotation surface over a container.
     *
     * @param {Object} config
     * @param {string} config.containerId  Element holding the immutable
     *     rendered text.
     * @param {Object} config.endpoints  { list, create, deleteFor(noteId) }
     *     — list GETs {annotations}, create POSTs {quote, prefix, suffix,
     *     comment}, deleteFor(noteId) returns the DELETE url. All
     *     same-origin relative paths.
     * @param {Array}  [config.extraActions]  Additional selection-toolbar
     *     actions: {icon, label, onActivate(selectionHit)} where
     *     selectionHit = {text, range}.
     * @param {Function} [config.onChanged]  Called after a comment is
     *     created or deleted (hosts refresh their notes panels).
     * @returns {{reload: Function}}
     */
    function init(config) {
        const containerId = config.containerId;
        const endpoints = config.endpoints;
        const onChanged = config.onChanged || (() => {});
        let toolbar = null;
        let popover = null;
        let clickBound = false;
        let annotationsByNoteId = {};
        // Re-apply-across-render machinery (see applyWhenReady).
        let readyObserver = null;
        let applyingHighlights = false;
        // Monotonic token so an out-of-order reload() response can't
        // overwrite a newer annotation list (see reload).
        let reloadToken = 0;

        const container = () => document.getElementById(containerId);

        const postJson = (url, body) => window.NotesShared.postJson(url, body);

        // ---- selection toolbar ----

        function makeToolbarButton(iconClass, label, onActivate) {
            const btn = document.createElement('button');
            btn.type = 'button';
            btn.className = 'btn btn-primary btn-sm';
            const icon = document.createElement('i');
            icon.className = iconClass;
            icon.setAttribute('aria-hidden', 'true');
            btn.append(icon, document.createTextNode(` ${label}`));
            // mousedown, not click: a click first collapses the selection
            // (mousedown clears it), hiding the toolbar before its click
            // handler ever ran.
            btn.addEventListener('mousedown', (e) => {
                e.preventDefault();
                onActivate(selectionWithinContainer());
            });
            return btn;
        }

        function setupToolbar() {
            toolbar = document.createElement('div');
            toolbar.className = 'ldr-selection-toolbar';
            toolbar.style.display = 'none';
            toolbar.appendChild(
                makeToolbarButton('fas fa-comment', 'Comment', openCommentPopover)
            );
            for (const action of config.extraActions || []) {
                toolbar.appendChild(
                    makeToolbarButton(action.icon, action.label, (hit) => {
                        hideToolbar();
                        action.onActivate(hit);
                    })
                );
            }
            document.body.appendChild(toolbar);

            document.addEventListener('mouseup', () => {
                // Defer: the selection object updates after mouseup.
                setTimeout(maybeShowToolbar, 0);
            });
            document.addEventListener('scroll', hideToolbar, { passive: true });
        }

        function selectionWithinContainer() {
            const root = container();
            const sel = window.getSelection();
            if (!root || !sel || sel.isCollapsed || sel.rangeCount === 0) return null;
            const range = sel.getRangeAt(0);
            if (!root.contains(range.commonAncestorContainer)) return null;
            const text = sel.toString().trim();
            return text.length >= 10 ? { text, range } : null;
        }

        function maybeShowToolbar() {
            const hit = selectionWithinContainer();
            if (!hit) {
                hideToolbar();
                return;
            }
            const rect = hit.range.getBoundingClientRect();
            toolbar.style.position = 'fixed';
            toolbar.style.top = `${Math.max(8, rect.top - 36)}px`;
            toolbar.style.left = `${Math.min(window.innerWidth - 220, Math.max(8, rect.left + rect.width / 2 - 80))}px`;
            toolbar.style.zIndex = '10001';
            toolbar.style.display = 'inline-flex';
        }

        function hideToolbar() {
            if (toolbar) toolbar.style.display = 'none';
        }

        // ---- popovers ----

        // The current popover's outside-click listener, so EVERY close path
        // (Cancel, save, delete, Escape, opening the next popover) can remove
        // it. Previously it was only removed from inside its own handler on a
        // genuine outside click, so closing any other way orphaned the
        // document-level 'mousedown' listener permanently — unbounded
        // accumulation over a session of opening/closing comments.
        let popoverOutsideClick = null;

        function closePopover() {
            if (popoverOutsideClick) {
                document.removeEventListener('mousedown', popoverOutsideClick);
                popoverOutsideClick = null;
            }
            if (popover) {
                popover.remove();
                popover = null;
            }
        }

        function positionPopover(pop, anchorRect) {
            pop.style.position = 'fixed';
            pop.style.top = `${Math.min(window.innerHeight - 60, anchorRect.bottom + 6)}px`;
            pop.style.left = `${Math.min(window.innerWidth - 340, Math.max(8, anchorRect.left))}px`;
            pop.style.zIndex = '10002';
        }

        function basePopover() {
            closePopover();
            const pop = document.createElement('div');
            pop.className = 'ldr-annotation-popover';
            popover = pop;
            document.body.appendChild(pop);
            setTimeout(() => {
                if (popover !== pop) return; // already closed before we armed
                popoverOutsideClick = (e) => {
                    if (popover === pop && !pop.contains(e.target)) {
                        closePopover();
                    }
                };
                document.addEventListener('mousedown', popoverOutsideClick);
            }, 0);
            pop.addEventListener('keydown', (e) => {
                if (e.key === 'Escape') closePopover();
            });
            return pop;
        }

        /**
         * Capture short normalized prefix/suffix context around the
         * selection to disambiguate repeated phrases. Range.comparePoint
         * against the normalized index map finds the exact occurrence the
         * user selected rather than guessing among duplicates.
         */
        function captureContext(range, quote) {
            const root = container();
            const empty = { prefix: '', suffix: '' };
            if (!root) return empty;
            try {
                const { text, map } = buildNormalizedText(root);
                let start = -1;
                for (let i = 0; i < map.length; i++) {
                    if (!map[i]) continue; // virtual boundary space
                    if (range.comparePoint(map[i].node, map[i].offset) >= 0) {
                        start = i;
                        break;
                    }
                }
                if (start === -1) return empty;
                const end = Math.min(start + quote.length, text.length);
                return {
                    prefix: text.slice(Math.max(0, start - 30), start),
                    suffix: text.slice(end, end + 30)
                };
            } catch (e) {
                SafeLogger.error('Annotation context capture failed:', e);
                return empty;
            }
        }

        /** Selection → comment entry popover. */
        function openCommentPopover(hit) {
            hideToolbar();
            if (!hit) return;

            let quote = normalizeWhitespace(hit.text);
            if (quote.length > 1000) quote = quote.slice(0, 1000);
            const context = captureContext(hit.range, quote);

            const rect = hit.range.getBoundingClientRect();
            const pop = basePopover();

            const label = document.createElement('div');
            label.className = 'ldr-annotation-popover-quote';
            label.textContent = quote.length > 120 ? `${quote.slice(0, 120)}…` : quote;

            const textarea = document.createElement('textarea');
            textarea.className = 'ldr-annotation-popover-input';
            textarea.rows = 3;
            textarea.placeholder = 'Your comment… (saved as a note linked to this page)';

            const actions = document.createElement('div');
            actions.className = 'ldr-annotation-popover-actions';
            const save = document.createElement('button');
            save.type = 'button';
            save.className = 'btn btn-primary btn-sm';
            save.textContent = 'Comment';
            const cancel = document.createElement('button');
            cancel.type = 'button';
            cancel.className = 'btn ldr-btn-outline btn-sm';
            cancel.textContent = 'Cancel';
            actions.append(save, cancel);
            pop.append(label, textarea, actions);
            positionPopover(pop, rect);
            textarea.focus();

            cancel.addEventListener('click', closePopover);
            save.addEventListener('click', async () => {
                const comment = textarea.value.trim();
                if (!comment) {
                    textarea.focus();
                    return;
                }
                save.disabled = true;
                try {
                    await postJson(endpoints.create, {
                        quote,
                        prefix: context.prefix,
                        suffix: context.suffix,
                        comment
                    });
                    closePopover();
                    toast('Comment saved as a note', 'success');
                    onChanged();
                    reload();
                } catch (error) {
                    SafeLogger.error('Error saving annotation:', error);
                    toast(error.message || 'Failed to save comment', 'error');
                    save.disabled = false;
                }
            });
        }

        /** Existing-highlight popover: comment preview + open/delete. */
        function showAnnotationPopover(mark, annotation) {
            const pop = basePopover();

            const body = document.createElement('div');
            body.className = 'ldr-annotation-popover-comment';
            // Note content is comment-first, then the quoted passage as a
            // "> " blockquote; the reader is already looking at the
            // passage, so show only the comment part.
            const preview = annotation.comment_preview || annotation.note_title || '';
            body.textContent = preview.split(/\n\s*>/)[0].trim();

            const actions = document.createElement('div');
            actions.className = 'ldr-annotation-popover-actions';
            const open = document.createElement('a');
            open.className = 'btn btn-primary btn-sm';
            open.href = `/notes/${encodeURIComponent(annotation.note_id)}`;
            open.textContent = 'Open note';
            const del = document.createElement('button');
            del.type = 'button';
            del.className = 'btn ldr-btn-outline btn-sm';
            del.textContent = 'Delete note';
            actions.append(open, del);
            pop.append(body, actions);
            positionPopover(pop, mark.getBoundingClientRect());

            del.addEventListener('click', async () => {
                // The comment IS a note that the user may have opened and
                // expanded with unrelated content — deleting the annotation
                // deletes that whole note. Confirm so it's never silent.
                if (!window.confirm(
                    'Delete this comment? The linked note (and anything you '
                    + 'added to it) will be permanently removed.'
                )) {
                    return;
                }
                del.disabled = true;
                try {
                    const response = await safeFetchWithAuth(endpoints.deleteFor(annotation.note_id), {
                        method: 'DELETE',
                        headers: { 'X-CSRFToken': csrfToken() },
                        credentials: 'same-origin'
                    });
                    const data = await response.json().catch(() => ({}));
                    if (!response.ok || !data.success) {
                        throw new Error(
                            data.error || data.detail ||
                            `Server returned ${response.status}`
                        );
                    }
                    closePopover();
                    toast('Comment deleted', 'success');
                    onChanged();
                    // Unwrap ALL segments of this annotation, not just the
                    // clicked one: a quote spanning a <br>/whitespace run
                    // renders as several <mark data-note-id=X> siblings (see
                    // wrapNormalizedRange / anchoredCount), so unwrapping only
                    // the clicked mark leaves the others as clickable ghosts
                    // bound to a now-deleted note. Also drop the map entry
                    // synchronously so a ghost click before the fire-and-forget
                    // reload() completes (or if reload() fails) can't reopen a
                    // popover for the deleted note. reload() re-applies the rest.
                    const root = container();
                    if (root) {
                        root.querySelectorAll('mark.ldr-research-annotation').forEach((m) => {
                            if (m.dataset.noteId === String(annotation.note_id)) {
                                // audited 2026-07-22: replaceWith() spreads the mark's own child Nodes (never a string) — no HTML parsing
                                // bearer:disable javascript_lang_dangerous_insert_html
                                m.replaceWith(...m.childNodes);
                            }
                        });
                    } else {
                        // audited 2026-07-22: same Node-spread unwrap as above — no HTML parsing
                        // bearer:disable javascript_lang_dangerous_insert_html
                        mark.replaceWith(...mark.childNodes);
                    }
                    delete annotationsByNoteId[annotation.note_id];
                    reload();
                } catch (error) {
                    SafeLogger.error('Error deleting annotation:', error);
                    toast(error.message || 'Failed to delete comment', 'error');
                    del.disabled = false;
                }
            });
        }

        // ---- highlight application ----

        function applyAllAnnotations(annotations) {
            const root = container();
            if (!root) return;
            for (const mark of [...root.querySelectorAll('mark.ldr-research-annotation')]) {
                // audited 2026-07-22: unwrap pass spreads each mark's existing child Nodes (never a string) — no HTML parsing
                // bearer:disable javascript_lang_dangerous_insert_html
                mark.replaceWith(...mark.childNodes);
            }
            root.normalize();
            let missed = 0;
            for (const a of annotations) {
                if (!applyAnnotation(root, a)) missed++;
            }
            if (missed) {
                SafeLogger.error(`${missed} annotation(s) could not be anchored to the rendered text`);
            }
            annotationsByNoteId = {};
            for (const a of annotations) annotationsByNoteId[a.note_id] = a;
            if (!clickBound) {
                clickBound = true;
                root.addEventListener('click', (e) => {
                    const mark = e.target.closest('mark.ldr-research-annotation');
                    if (!mark) return;
                    const annotation = annotationsByNoteId[mark.dataset.noteId];
                    if (annotation) showAnnotationPopover(mark, annotation);
                });
            }
        }

        // A loading placeholder is present. Must be robust to more than the
        // original page markup: the results page (results.js) first replaces
        // results.html's `.ldr-loading-spinner` with its OWN placeholder
        // (`<i class="fas fa-spinner fa-pulse"> Loading research results…`)
        // and only THEN, after the report fetch, swaps in the real content —
        // so a heuristic that only knew `.ldr-loading-spinner` would treat
        // the placeholder as ready, anchor nothing, and never re-run.
        function looksLikeLoading(root) {
            if (root.querySelector('.ldr-loading-spinner, .ldr-spinner, .fa-spinner, .fa-pulse, .spinner-border')) {
                return true;
            }
            const text = root.textContent.trim();
            if (!text) return true;
            // Only a SHORT body that opens with a loading word is a
            // placeholder ("Loading research results…"). A real report that
            // merely begins with the word "Loading"/"Searching" is long, and
            // treating it as a placeholder would suppress every highlight on
            // that page permanently.
            return text.length < 120 && /^(?:loading|searching)\b/i.test(text);
        }

        /**
         * The host's text often renders asynchronously (the research report
         * is fetched + rendered by results.js, possibly through more than
         * one placeholder). Apply once real content is present, and RE-APPLY
         * whenever the container's content is replaced — results.js swaps the
         * whole report in via innerHTML, which would blow away marks applied
         * to an earlier placeholder. Stop once every annotation has anchored
         * (or after a timeout / on the surface being reloaded).
         */
        function applyWhenReady(annotations) {
            const root = container();
            if (!root) return;
            if (readyObserver) {
                readyObserver.disconnect();
                readyObserver = null;
            }
            const total = annotations.length;

            // Count DISTINCT anchored annotations, not <mark> elements: a
            // multi-segment quote yields several marks for ONE annotation,
            // so an element count would over-report and stop the observer
            // while other annotations are still unanchored.
            const anchoredCount = () => {
                const ids = new Set();
                root.querySelectorAll('mark.ldr-research-annotation').forEach((m) => {
                    if (m.dataset.noteId) ids.add(m.dataset.noteId);
                });
                return ids.size;
            };

            const tryApply = () => {
                if (looksLikeLoading(root)) return false;
                // applyAllAnnotations mutates the DOM (wraps marks). Those
                // mutations fire the observer on a LATER microtask — after a
                // synchronous `applyingHighlights=false` reset would already
                // have cleared — so a partially-anchored set would re-trigger
                // this callback forever (a browser-hanging microtask loop).
                // Disconnect around the mutation and discard our own records
                // before reconnecting, so only genuine host changes re-run us.
                applyingHighlights = true;
                if (readyObserver) readyObserver.disconnect();
                try {
                    applyAllAnnotations(annotations);
                } finally {
                    if (readyObserver) {
                        readyObserver.takeRecords();
                        readyObserver.observe(root, { childList: true, subtree: true });
                    }
                    applyingHighlights = false;
                }
                return anchoredCount() >= total;
            };

            if (tryApply()) return;

            const thisObserver = new MutationObserver(() => {
                if (applyingHighlights) return;
                if (tryApply() && readyObserver === thisObserver) {
                    readyObserver.disconnect();
                    readyObserver = null;
                }
            });
            readyObserver = thisObserver;
            readyObserver.observe(root, { childList: true, subtree: true });
            // Content that never fully anchors (a quote genuinely not present
            // in the final render) must not observe forever. Guard on identity:
            // a newer applyWhenReady() may have replaced readyObserver with its
            // own observer (and its own fresh 60s window); this stale timeout
            // must only tear down ITS OWN observer, never the newer one.
            setTimeout(() => {
                if (readyObserver === thisObserver) {
                    readyObserver.disconnect();
                    readyObserver = null;
                }
            }, 60000);
        }

        async function reload() {
            // Sequence concurrent reloads: create-comment and delete both
            // fire their own reload(), so responses can arrive out of order.
            // Only the newest reload is allowed to apply — otherwise a stale
            // earlier list can overwrite a newer one (a just-added highlight
            // vanishing, or a just-deleted mark reappearing).
            const myToken = ++reloadToken;
            try {
                const response = await safeFetchWithAuth(endpoints.list, {
                    credentials: 'same-origin'
                });
                const data = await response.json();
                if (!data.success) throw new Error(data.error || 'load failed');
                if (myToken !== reloadToken) return; // superseded
                const annotations = data.annotations || [];
                if (!annotations.length && !Object.keys(annotationsByNoteId).length) return;
                applyWhenReady(annotations);
            } catch (error) {
                SafeLogger.error('Error loading annotations:', error);
            }
        }

        setupToolbar();
        reload();
        return { reload };
    }

    window.LDRAnnotationSurface = { init };

    // Test hook (production-inert): the pure anchor engine.
    if (window.__VITEST_TEST__) {
        window.__annotationSurfaceTest = {
            buildNormalizedText,
            normalizeWhitespace,
            findQuoteIndex,
            applyAnnotation
        };
    }
})();